Inc 2: the two destructive lifecycle paths stop guessing (L4, L5, L9), and the README stops deferring (P8)

[fluxxion82]

Inc 2 of the v0.7.0 plan: L4, L5, L9, P8 — plus Codex round 1 (R1–R6, R8).

Rebased onto 701ed7d (#14). Counts: 1613 passed / 0 xfailed on origin/main, 1652 passed / 0 xfailed here. Measured by cp-snapshotting the changed files, git checkout 701ed7d -- them, running, and restoring from the snapshots. No xfail(strict=True) marker covered any of these findings, and #14 removed the last markers on this tree, so none was deleted.

---

Codex round 2

All six addressed. 1613 passed on 701ed7d → 1652 passed here. KNOWN_VIOLATIONS 6 → 5 (F4 paid one off).

F2 (P1) — the listing failing is the third gap

EmulatorProbe already covered two gaps: an emulator not in state device, and one whose console will not answer. adb devices itself failing is a third, and all three scripts handled it differently and all three were wrong:

script	what it did with a failed listing
emulator_selector	except RuntimeError: return [] — ranked every AVD as idle, silently
emulator_boot	let it escape as a bare RuntimeError → traceback
emulator_shutdown	same

The escape is worth spelling out: get_connected_devices re-wraps a failed listing as a plain RuntimeError, which is not an AdbError, so main()'s handler never saw it — a stack trace, from the one module family whose whole purpose is turning adb failures into remedies.

common/emu_console.py now has EmulatorSurvey and survey_emulators. The listing is a value, phrased once as running state unavailable: <reason>, and the listing callable is passed in so each script keeps the seam its own tests already stub. Callers differ where they should:

• selector ranks what it can — the AVDs on disk are real and a suggestion is not destructive — and discloses the gap: warnings in the JSON document, an indented ! line in the text listing, stderr in both.
• boot refuses: if what is running cannot be listed, a boot may start a second instance of an AVD that is already up.
• shutdown refuses, --name and --all alike.

One correctness note beyond the brief: describe_gap() appends UNKNOWN_EMULATOR_REMEDY only to the unidentified case. An adb_exec error already names its own remedy, and bolting "restart the emulator, or reset the adb connection" onto "adb is not on PATH" is advice that does not work.

Mutations (cp snapshot → edit → pytest → cp restore):

mutation	tests red
survey_emulators swallows the failure (unavailable=None)	12, across boot, shutdown and selector
boot's if survey.unavailable: disabled	test_boot_refuses_when_the_emulators_cannot_be_listed, test_cli_reports_an_adb_error_without_a_traceback
shutdown's UNKNOWN branch disabled	test_shutdown_by_name_refuses_when_an_emulator_could_not_be_queried, ..._when_the_emulators_cannot_be_listed, test_cli_reports_an_adb_error_without_a_traceback[by-name]

New tests read adb_device_not_found via recorded_anywhere, as instructed.

F1 (P1) — --all --json exited 1 with an empty stdout

emulator_shutdown.main()'s adb handler sat outside the arg parsing — R1's defect, still live. Parsing happens first now and the handler answers in the mode it was asked in. emulator_boot had the identical shape and got the identical fix.

The test is inverted as instructed: test_cli_reports_an_adb_error_without_a_traceback now requires {"error": ...} on stdout and an empty stderr for the --json parametrisation, prose on stderr for the text ones. Its docstring says why it stayed green — it asserted prose for the JSON case too.

Mutation: _fail back to prose-only → [all-json] and test_shutdown_by_name_when_the_emulators_cannot_be_listed go red.

F3 (P1) — the remedy needed the console that was not answering

Leads with the shared UNKNOWN_EMULATOR_REMEDY, then says explicitly to terminate the stale emulator process (pkill -f 'qemu-system.*<avd>', or Device Manager) — emulator_shutdown cannot reach a console that is not answering.

Mutation: revert to "Shut that emulator down with emulator_shutdown.py" → test_boot_refuses_while_an_emulator_cannot_be_identified red.

F4 (P1) — invented tool output, and a debt that was already paid

emulator -list-avds now comes from recorded.text("emulator_list_avds") in both selector tests. The framed console reply comes from recorded.text("emu_avd_name") with only the AVD name substituted, through a _framed_reply helper whose docstring says why: the OK framing is the part nobody would write by hand and the part that defeated the already-booted check for a whole release (S5).

That paid off KNOWN_VIOLATIONS' test_emulator_shutdown.py::_FakeResult — and the ratchet caught it itself: test_the_debt_list_does_not_rot failed with "listed as known violations but no longer violate anything". Entry deleted, the payoff recorded in the PAID OFF SINCE block. 6 → 5.

config.ini: no profile records one and none can be captured here, so per your instruction the read-from-disk test reuses this file's single existing literal — hoisted to a module constant so it stays visible to the detector under the existing parse_config_ini freeze rather than becoming a second invention. Recording an AVD config.ini is the next recording candidate.

F5 (P2) — one failure shape, and the promise made true

Ordinary failures in emulator_erase, emulator_shutdown and emulator_boot go through one _fail helper — the (error, *, json_mode) spelling emulator_boot and emulator_selector have had since #15. My round-1 _fail(args, message) was a second helper that shadowed boot's existing one; that is gone.

Batches keep their per-AVD summary and carry error alongside it when any AVD failed, in emulator_delete too so the two destructive scripts do not disagree. Three "Error: " prefixes embedded in returned messages are removed — the helper adds exactly one.

Mutation: delete erase's if not success: _fail(...) → three tests red, including the new test_an_ordinary_failure_answers_with_the_documented_error_key.

F6 (P2)

Docstring corrected, with a note that KNOWN_CONSOLE_CALLS is the count that matters because a number in prose goes stale silently — which that one did. No behavioural test, so no mutation: the enumeration is its own check.

A fourth existing-test assertion changed

test_emulator_shutdown.py::test_cli_exits_non_zero_when_refusing_a_physical_device asserted the L1 refusal appears on stdout. Under F5 a refusal is a failure and goes to stderr. Its invariants — exit 1, the serial named, no adb command issued — are unchanged and still asserted, plus a new assert not captured.out so a refusal cannot be printed as a result again.

Honest note on the F6 mutation run

The batched mutation run hit the 2-minute tool timeout mid-f6-stale-count, after the edit and before the restore, and because the runner snapshots before asserting, the snapshot was the mutated file. I repaired the docstring by hand and verified with git diff. The runner's snapshot-then-assert order is the wrong way round for a mutation that does not apply; the other twelve restored correctly.

---

Codex round 1

R3 (P1) — "unknown means not running" in three more scripts

This is L4 again, and the fix is one function rather than four. Four places asked the same question — which AVD is this serial running? — each with its own console call, its own timeout, and its own idea of what a failure means:

script	function	caught	answered
emulator_boot	_get_avd_name_for_serial	AdbError	None
emulator_erase	is_avd_running	AdbCommandError / EmuConsoleError	False
emulator_selector	_avd_name_for_serial	EmuConsoleError only	None
emulator_shutdown	get_avd_name_for_serial	bare Exception	None

Four answers to one question, and every one collapsed "I could not ask" into "it is not that AVD". Each collapse authorised something: a wipe (L4); a second instance of a live AVD (boot's already-booted check filtered out every emulator not in state device, so one mid-boot was invisible); a ranking that silently dropped what it could not read; and --name X reporting "No running emulator found" over a device nobody had managed to query.

common/emu_console.py now holds:

• identify_emulator(serial, state) — the only run_emu("avd", "name") call in the skill. Never raises for a console or command failure: that outcome is the answer, carried as reason alongside the serial and adb's state column. A non-device state short-circuits without asking, because a console that is not up cannot answer.
• probe_emulators(devices=None) — one probe per attached emulator. The optional devices argument lets a caller pass a listing it already has, which keeps the listing on that caller's own seam (where its tests stub it) and avoids querying adb twice.
• avd_running(name) → RunningAnswer with a RunningVerdict of RUNNING / NOT_RUNNING / UNKNOWN. UNKNOWN beats NOT_RUNNING and loses to RUNNING — that ordering is the safety property.

The four callers now differ where they should, in what they do about UNKNOWN:

• erase refuses, naming the serial and its state; --force still erases.
• boot refuses and warns on stderr. Codex's instruction allowed proceeding "if the requested AVD is not the unknown one's name when it can be read" — for an unidentified emulator the name cannot be read by definition, so that clause resolves to "refuse", which is what this does. emulator_boot has no --force, and I did not add one; flag me if you want the escape hatch.
• selector ranks without it but lists it: unidentified_emulators in the --json document, an indented ! line in the text listing, and a stderr warning in every mode, so a --json caller still gets a clean stdout.
• shutdown --name exits non-zero saying which serial could not be queried and why, via a new resolve_target_by_avd_name returning (serial, reason). resolve_serial_by_avd_name is kept as its lossy wrapper.

Console-call enumeration delta

tests/test_shape_guards.KNOWN_CONSOLE_CALLS, 9 → 6:

	before	after
common/emu_console.py::identify_emulator	—	added
common/emu_console.py::console_available	✓	✓
emulator_boot.py::_get_avd_name_for_serial	✓	removed
emulator_erase.py::is_avd_running	✓	removed
emulator_selector.py::_avd_name_for_serial	✓	removed
emulator_shutdown.py::get_avd_name_for_serial	✓	removed
emulator_shutdown.py::shutdown	✓	✓
location.py::_run_geo_fix	✓	✓
sms.py::send	✓	✓
snapshot.py::_console	✓	✓

The four removed are recorded in a comment above the list with what each of them used to catch, so the enumeration keeps the history the guard exists to protect. The guard failed on the first run of the rewrite and named exactly those four — the delta is its output, not my summary of it.

Three existing tests changed, all in the same direction

Called out individually because none is an xfail spec and each pinned the behaviour R3 says is wrong:

1. test_emulator_erase.py::test_a_device_error_is_not_answered_as_not_running — asserted pytest.raises(DeviceNotFoundError) out of erase(). A device error on one emulator's console is now an UNKNOWN verdict instead. Strictly more information reaches the agent: the refusal names which serial went unanswered and quotes adb's own message and remedy, where the exception said only that something had. The safety assertion (userdata still on disk) is unchanged and the test now also asserts the serial and the remedy appear.
2. test_emulator_selector.py::test_a_device_error_is_not_ranked_as_not_running — asserted the same raise out of running_avd_names(), which made a suggestion fatal over a condition it cannot fix. Its invariant ("an unanswered check must not read as idle") is unchanged and still asserted — no name is invented, and the emulator is reported unidentified. The thing it was really protecting (a second copy of a live AVD being booted) is now refused by emulator_boot, which is the only place that can actually prevent it.
3. test_emulator_selector.py::test_cli_reports_an_adb_error_without_a_traceback → test_the_cli_names_an_emulator_it_could_not_identify. --suggest no longer exits 1 over one unauthorized emulator; it ranks what it can and warns. The remedy and no-traceback assertions are kept verbatim, and selector's CLI failure boundary is still covered by test_the_cli_exits_non_zero_when_avd_discovery_fails and test_a_json_caller_gets_the_failure_in_the_json.

Also: test_emulator_erase.py::test_running_check_uses_adb_command_mapping now expects adb devices -l, because the listing goes through device_utils.get_connected_devices rather than this script's own row parser.

R1 (P1) — --json promised {"error": ...} and printed nothing

main() caught AdbError outside the arg parsing, so it could not know --json had been asked for: --name Pixel_9 --json under a RunningCheckError gave exit 1, prose on stderr, and an empty stdout — nothing at all on the stream an agent parses. Parsing now happens first and _fail(args, message) answers in the mode it was asked in. The --name is required usage error had the same shape (argparse help, no JSON) and is fixed with it.

New test test_every_failing_json_mode_prints_an_error_document, parametrised over --name … --json, --all --json and a bare --json.

R2 (P1) — the clone fallback installed something that is not a skill

git clone <url> ~/.claude/skills/android-emulator-skill puts the repository root there, but the skill is android-emulator-skill/skills/android-emulator-skill/ — two levels down. Claude Code loads nothing. Both README.md and SKILL.md now clone to a workspace path and symlink (or cp -R) the inner directory into ~/.claude/skills/ or .claude/skills/.

The guard resolves it rather than matching a string: _clone_installations parses the fenced block for a git clone <url> <dest> and each later ln -s / cp -R whose source starts with that destination, strips the destination prefix to get a path relative to the repository, and asserts REPO_ROOT / relative / "SKILL.md" is a file.

R4 (P1) — read_avd_config hard-coded ~/.android/avd

Now resolve_avd_home(). On a host that relocates the AVD tree every config read returned {}, so every AVD lost its API level, device profile and ABI from the ranking — a ranking computed from no inputs and printed as a recommendation. Tested with ANDROID_AVD_HOME set.

R5 (P2) — the refusal recommended a remedy that cannot work

An offline emulator cannot be console-killed, so emulator_shutdown.py --all was not merely second-best, it was the thing that will not work. UNKNOWN_EMULATOR_REMEDY ("restart the emulator, or reset the adb connection with adb kill-server && adb start-server") comes first now, carried by RunningAnswer.describe_unknown() so all four scripts quote the same fix.

R6 (P2) — Pillow is optional in the packaged README too

R8 (P2) — the guard claim was wrong on all three counts

Codex is right and my PR body was wrong. There are five guard functions, not six (I counted parametrisations). Two read prose, not fenced blocks. And two placeholder parametrisations were green on main — my earlier "all six red" transcript mutated the root README into a state main never had, which is evidence of nothing.

What changed:

• Every guard now declares which stream it reads. _code_block_lines is the commands a reader copies — a <placeholder> there is a defect. A new _prose_lines is the claims the document makes — a deferral sentence is a defect there, a placeholder is not. Neither reads the whole file.
• The deferral guard is no longer parametrised over the packaged README, which never carried the sentence: a guard that was green before the change it claims to enforce is not evidence. The placeholder guard keeps its clean parametrisations, but they are labelled in the docstring as the false-positive control rather than as evidence.
• The deferral guard matched line-at-a-time and so was blind to wrapped prose. Its own mutation caught this: inserting the sentence with a newline inside it left the guard green. It now joins the prose stream before matching. That is the one place in this PR where writing the transcript found a real defect in the thing being written.

Per-guard mutation transcript

Runner: cp snapshot → edit → pytest -x → cp restore, asserting the anchor text occurs exactly once so a stale mutation fails loudly instead of silently testing nothing. Never git checkout --.

cp <target> /tmp/mutate-snapshot.py       # snapshot
# ...apply the single-anchor replacement below...
uvx --python 3.12 --with pytest --with pillow --with pyyaml pytest <tests> -q --no-header -x
cp /tmp/mutate-snapshot.py <target>       # restore

#	mutation (what main had)	test that went red	failing assertion
1	SKILL.md: real URL → git clone <repository-url>	test_no_documented_command_still_carries_a_placeholder[skill]	SKILL.md documents commands nobody can run: ['git clone <repository-url> ~/src/android-emulator-skill']
2	README.md: deferral sentence restored, wrapped across two lines	test_the_repo_readme_does_not_defer_its_install_instructions	README defers its own instructions: 'Plugin install instructions will be finalized once feature parity work lands:'
3	README.md: claude plugin marketplace update line deleted	test_the_readme_documents_both_halves_of_an_update	README does not show 'claude plugin marketplace update'
4	README.md: clone URL → a different owner	test_the_clone_url_points_at_this_repositorys_owner	assert False … any(<genexpr>)
5	README.md: link the clone root into .claude/skills (main's own instruction)	test_the_clone_fallback_installs_a_directory_that_is_actually_a_skill[repo]	where False = (PosixPath('<repo>') / 'SKILL.md').is_file
6	README.md: the $ANDROID_HOME/emulator warning generalised away	test_the_readme_names_the_emulator_path_trap	re.search('not\s+?$ANDROID_HOME?[,.\s]', prose) → None

Only #1 and #5 correspond to text main actually had; #2–#4 and #6 are anti-vacuity checks on guards protecting text this PR adds. Stated rather than blurred, which is the correction R8 asked for.

Code mutation transcript (R1, R3, R4, R5)

#	mutation (what main had)	test that went red	failing assertion
7	_fail always writes prose to stderr (handler outside arg parsing)	test_every_failing_json_mode_prints_an_error_document[name]	json.decoder.JSONDecodeError: Expecting value: line 1 column 1
8	probe_emulators filters to state == "device" (what all four callers did)	test_boot_refuses_while_an_emulator_cannot_be_identified	'emulator-5554' in 'Boot error: a second emulator was launched over an unidentified one'
9	emulator_boot: unidentified = []	test_boot_refuses_while_an_emulator_cannot_be_identified	same — the test's Popen stub raises, so the launch is proved, not inferred
10	emulator_shutdown: the UNKNOWN branch deleted	test_shutdown_by_name_refuses_when_an_emulator_could_not_be_queried	'emulator-5554' in "Error: No running emulator found for AVD name 'Pixel_9'"
11	emulator_selector: self.unidentified = ()	test_suggest_lists_an_emulator_it_could_not_identify	[p.serial for p in selector.unidentified] == [serials[0]]
12	read_avd_config back to Path.home() / ".android" / "avd"	test_read_avd_config_honours_the_resolved_avd_home	config read from the real home instead of $ANDROID_AVD_HOME
13	erase refusal recommends emulator_shutdown --all first	test_a_device_error_is_not_answered_as_not_running	'emulator-5554' in 'Refusing to erase Pixel_9: … Shut the emulators down (emulator_shutdown.py --all).'

#8 and #9 both land on the same test from different directions — the shared filter and the caller's use of it — which is what makes the pair worth keeping.

Every R3 test is driven from recorded.text("adb_devices_multiple") (two emulators) and recorded.text("emu_avd_name"). The offline state is the recorded row with its state column rewritten, and each such test says so in its docstring: no profile has recorded a device in that state (see test_fixture_policy.KNOWN_VIOLATIONS' parse_adb_devices entry), and provoking one means killing an emulator mid-boot on the recording host. KNOWN_VIOLATIONS is unchanged.

R7

Noted as going to the v0.8.0 list, not actioned here.

---

The original findings

L4 — is_avd_running said "not running" four ways it had not established

scripts/emulator_erase.py. Every one leads into the unlink loop.

• (a) One failing console query ended the whole scan: the try wrapped the loop, so an AdbCommandError from the first emulator returned False with later emulators never examined.
• (b) Only the literal state device counted, so an emulator still booting (offline) was invisible. The row filter also stopped being "emulator" in line and "device" in line — against adb devices -l every row carries a device:emu64a16k descriptor, so that predicate is true of a row in any state.
• (c) The name test was a substring, so --name Pixel was refused while an unrelated Pixel_9 ran. Now equality on the unframed payload. This hole leans the opposite way: name in payload is a strict superset of name == payload, so it over-refuses and can never cause a wipe equality would prevent. Its test asserts the erase of a differently-named AVD now proceeds, with a companion asserting the true match still refuses. The brief's "never reach unlink in any of them" holds for (a) and (b) but is inverted for (c).
• (d) A failed adb devices returned False — the check never ran at all. Now RunningCheckError, naming adb kill-server and --force.

The three holes' mutation transcripts (equality → substring; state column → main's line filter, whose failure message is the defect verbatim, AVD erased: Pixel_9 (deleted 2 files); per-emulator failure → main's scan abort) are in the commit history of this branch and reproduce unchanged; the L4 logic now lives in avd_running and its mutations are #8 above.

L5 — --old N deleted the AVDs it could not find

_mtime returned 0.0 on OSError, so in a newest-first sort every AVD the script could not locate went to the end — which is the end --old deletes. --old 3 on a host whose AVD home is elsewhere proposed deleting the lot, and the only symptom was that it appeared to work. Now AvdHomeError (subclasses SdkToolError, so every mode reports it the one way the L8 fix established) naming the directory searched and the two variables that relocate it.

AVD home is resolved as avdmanager resolves it: ANDROID_AVD_HOME, else ANDROID_SDK_HOME/.android/avd, else ~/.android/avd. Note the asymmetry — the first is the directory of .avd directories, the second is the parent of .android. grep found the same two-branch resolver in emulator_erase.get_avd_home and (via R4) emulator_selector.read_avd_config; all three call one common.sdk_tools.resolve_avd_home().

Also, from the same finding's evidence: --old 0 keeps nothing, so it silently meant --all. Now a usage error (exit 2) pointing at --all --yes.

Mutations: _mtime → return 0.0 reddens both L5 tests; dropping the ANDROID_SDK_HOME branch reddens [sdk_home]; removing the --old 0 guard reddens both parametrisations.

L9 — snapshots kept, and now said so

A snapshot is a whole guest machine, not user data, so deleting one during an erase would throw away state somebody recorded deliberately — but a later snapshot.py --load can undo the "factory state" this script promises. One line, in the module docstring, on every successful erase (text and --json, single and --all), and in the SKILL.md entry. <name> is inserted into the brief's wording because snapshot.py --delete takes a NAME metavar; test_the_snapshot_note_names_a_flag_snapshot_py_actually_has parses snapshot.py's argparse with ast to confirm the flag exists.

P8 — install instructions somebody can run

Deferral sentence deleted; both install commands kept; the @fluxxion82 suffix explained as marketplace.json's name field; the two-command update with its silent-failure note; a clone fallback that installs the right directory (R2); and a Prerequisites list — platform-tools; cmdline-tools with the reason the legacy tools/bin/avdmanager cannot substitute (NoClassDefFoundError: javax/xml/bind/annotation/XmlSchema on Java 11+); Java 21; Python 3.12+; Pillow optional; and the $ANDROID_HOME vs $ANDROID_HOME/emulator trap. No script table. The Status paragraph, two lines above the deleted sentence, still claimed parity was pending and was corrected with it.

---

Other enumerations

Enumeration	before	after
KNOWN_CONSOLE_CALLS	9	6 (table above)
KNOWN_EMU_BYPASSES	()	unchanged
KNOWN_VIOLATIONS (fixture policy)	6	5 (F4 paid one off)
KNOWN_BOUNDS_SITES	() (emptied by #14)	unchanged

SKILL.md ↔ argparse parity is green. --name was added to emulator_shutdown's documented options — it exists and was simply missing from the list.

Lane failure on the first round-1 push, and what it was

The mocked check went red on test_a_successful_erase_says_snapshots_were_kept while the same test passed here. It stubbed is_avd_running, but after the R3 rewiring erase() consults running_check — so the real probe ran, found adb on my PATH and nothing on the runner's.

The exit status was the symptom; the defect is a unit test reaching the adb boundary at all. Fixed at the right seam, and subprocess.run is now stubbed to raise in that test, so anything under it that tries to talk to a device fails loudly rather than depending on whose machine it is.

Verification

uvx --python 3.12 --with pytest --with pillow --with pyyaml pytest tests/ -q
1652 passed, 1 skipped, 25 deselected

uvx --python 3.12 --with black==26.5.1 black --check …   117 files would be left unchanged
uvx --python 3.12 --with ruff==0.15.14 ruff check …      All checks passed!

Run on the tree rebased onto origin/main@701ed7d immediately before pushing. No adb, emulator, skill script or pytest -m emulator was run at any point — a physical phone is attached to this host.