Skip to content

fix(android): stop the emulator a failed cold boot left unowned - #4863

Merged
thymikee merged 3 commits into
0.22from
fix/0.22-stop-emulator-on-failed-boot
Nov 21, 2026
Merged

thymikee merged 3 commits into
0.22from
fix/0.22-stop-emulator-on-failed-boot

Conversation

@thymikee

@thymikee thymikee commented Nov 20, 2026 •

Copy link
Copy Markdown
Member

Summary

An open that boots a stopped Android emulator stops that launch when the open fails (#4764). A failure inside the boot was outside that rule: readiness terminated its launch only on cancellation, so a boot failing for another reason left an emulator running with no session to own it, and no later close ever learned to stop it. Fixes #4847.

Readiness keeps booting only for the boot wait itself running out its startup budget — a step failing after the boot is not "still booting" — and stops its launch for every other failure after launch returned a pid, rethrowing its own error unchanged.

That stop tears down a launched emulator, so the launching host now asks assertShutdownAllowed first: a daemon denying device-shutdown leaves its launch running and the open keeps its boot error. The same call closes the existing cancellation bypass, where a canceled boot signaled its launch past the policy. An already-running emulator is never stopped.

Before / after

Same injected adb transport fault, AVD agent-device-4539-live.

base decae77d37 head c58a582203
BOOT_COMMAND_FAILED, emulator left running unowned same error, emulator stopped
denied policy: same error, emulator SIGTERM'd same error, emulator kept, refusal recorded

Validation

At c58a582203: build, typecheck, lint, format, check:layering, test:unit (21845 passed), fallow audit, check:mcp-metadata, doc prose and links, command-docs. Ten new unit tests: six boot-failure stops, one post-boot phase case, three policy-gate cases; nine fail at origin/0.22. Live: policy-denied and control runs in the comment replying to the review.

Not in this PR

The readiness stop checks no other session or claim for the emulator; tracked as a follow-up issue. The daemon's post-boot stop path (#4842) and its cleanup reporting are unchanged.

@thymikee

Copy link
Copy Markdown
Member Author

Live device evidence

Runs on this branch's CLI (node bin/agent-device.mjs, head 22781873c6, plus a base-build comparison below), on a dedicated AVD agent-device-4539-live only, each run with an isolated --state-dir under .tmp/. No other device was touched: emulator-5556, which another session owns, stayed running and was never addressed. All state dirs ended with daemon stop, and the AVD ended not running.

(a) Control — cold open, plain close

open com.android.settings --platform android --device agent-device-4539-live --state-dir .tmp/ad-4847
  exit 0 | success true | selection.bootOccurred true
  pgrep -f "avd agent-device-4539-live" -> 96152 (running)
close --platform android --device agent-device-4539-live --state-dir .tmp/ad-4847
  exit 0 | success true | shutdown stdout "OK: killing emulator, bye bye"
  pgrep -> AVD NOT RUNNING

Re-ran both at the final head: open success with bootOccurred true, plain close stopped it.

(b) Deadline expiry keeps the emulator booting (unchanged)

open com.android.settings --platform android --device agent-device-4539-live --state-dir .tmp/ad-4847 --timeout 3000
  exit 1 | COMMAND_FAILED | "Android emulator did not appear in time" | details.reason boot_timeout
  no failedOpenEmulatorCleanup
  pgrep -> 97768 still running 6s after the failure
  60s later: adb -s emulator-5554 shell getprop sys.boot_completed -> 1  (booted on its own)

Stopped afterwards with shutdown --device agent-device-4539-live. A second short-timeout run (.tmp/ad-4847-timeout2) booted inside the 3s budget and returned success, so it offered nothing to observe.

(c) Non-deadline failure stops the launched emulator

Injected at the host boundary, scoped to one run: ANDROID_SDK_ROOT/ANDROID_HOME pointed at a symlink farm of the real SDK whose only substituted file is platform-tools/adb — a shim that passes every call through to the real adb unchanged, except the sys.boot_completed probe for a serial other than emulator-5556, which after the first probe fails the way a dropped transport does: exit 1 with error: closed. No kills, no signals, no privileged commands.

branch build   (.tmp/ad-4847-fault3)
  exit 1 | COMMAND_FAILED | "Android boot probe failed: closed" | details.reason BOOT_COMMAND_FAILED
    details.exitCode 1 | details.stderr "error: closed"
  pgrep -> AVD NOT RUNNING        # this open's launch was stopped with it

base build (HEAD runtime.ts, same injection, .tmp/ad-4847-base)
  exit 1 | COMMAND_FAILED | "Android boot probe failed: closed" | details.reason BOOT_COMMAND_FAILED
  pgrep -> 62255 qemu-system-aarch64 -avd agent-device-4539-live   # left running, unowned

That base/branch pair is the reported bug and its fix: the same failure now takes the emulator this open launched with it, and still reports its own error. Two earlier injection attempts were discarded as invalid — the fake SDK root then had no SDK payload, so the launch never reached the probe and the client hit its own 90s request timeout.

@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Size Report

Metric Base Current Diff
Installed (including dependencies) 6.19 MB 6.19 MB +826 B
Package (unpacked) 6.19 MB 6.19 MB +826 B
Package (download) 1.89 MB 1.89 MB +241 B

Startup median (7 runs, lower is better):

Scenario Base Current Diff
CLI --version 29.6 ms 34.2 ms +4.6 ms
CLI --help 51.5 ms 60.1 ms +8.6 ms

@apex-sentinel-staging

This comment has been minimized.

@apex-sentinel-staging apex-sentinel-staging Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Apex Sentinel: 4 new findings on 2278187. The verdict and the full list are in the summary comment.

@thymikee

Copy link
Copy Markdown
Member Author

Review of 2278187: the new readiness stop bypasses the daemon's device-shutdown policy, so this needs one fix before merge.

The stop calls host.deviceReadiness.androidEmulator.terminate (runtime.ts:83), and that terminate has no policy gate. assertShutdownAllowed is wired only into deviceShutdown (src/platform-runtime-operation-host.ts:125-129). Take a daemon that denies device-shutdown and an open of a stopped AVD whose boot fails in the new stop set. At base the emulator stayed running, which obeys the policy. At head the daemon SIGTERMs or kills it. The throw also happens inside bootStoppedLocalAndroidDevice, before withFailedOpenLaunchCleanup, so the daemon's kept_running / daemon-policy-denied report is never reached. ADR 0029 rule 3 says a denied failed open keeps its launch running. The rule the code must satisfy is that every teardown of a launched emulator passes the device-shutdown gate. The owner of that teardown is createAndroidEmulatorHost, built in deviceReadiness.androidEmulator: pass it assertShutdownAllowed and call it first in terminate. terminateLaunch already records a diagnostic when terminate throws, so a denied daemon leaves the emulator running and still reports the open's own boot error. The same gate also closes the existing cancellation bypass. Please add a host-level test that a denied terminate does not signal the recorded pid, and amend the Android sentence in ADR 0029.

Required before merge: repeat the live failure case on a daemon started with AGENT_DEVICE_DAEMON_POLICY denying device-shutdown. The run must exit 1 with details.reason BOOT_COMMAND_FAILED, and pgrep for -avd <name> must still show the launched emulator. The same run without the policy is the control and must end with the AVD not running. The existing live run (comment 7051556847) covers the unrestricted route and is taken as the author's report. Not verified here: unit tests, any device run, or the CLI were not run for this review.

Could the fix stay this small? Keep the readiness stop where the issue puts it, and give its only dependency the existing gate, which is about three lines. That makes readiness stops obey ADR 0029 with no new seam.

Not blocking, and fine to take or leave: (1) the readiness stop has no check that another session or claim holds the emulator, so a second open that binds to the booting emulator-NNNN could lose it, which is worth a follow-up issue unless the author prefers to close it here; (2) in keepsBootAfterFailure (runtime.ts:110) the clock clause can keep a fully booted emulator when a post-boot step fails after the deadline, so deciding by phase (keep only for a failure from the boot wait itself) would also remove the clock dependency and one redundant clause; (3) commands.md:125 describes the rule only for open, while boot, app deployment and the other ensureAndroidReady callers follow it too, and 'through the same launch the readiness step started' reads better as 'because it launched it'; (4) the comments on keepsBootAfterFailure and terminateLaunch can shrink to the rule once (2) is settled, and the PR body says seven new tests while the diff adds six.

Of the open inline threads, the policy gate thread still applies and is the blocking item above, and the ownership check thread still applies as the non-blocking note. One lower-priority thread still applies. The boot-timeout thread does not apply: with the clock below the deadline and reason ANDROID_BOOT_TIMEOUT, keepsBootAfterFailure returns false, so the emulator is stopped, which is what the issue asks for.

No conflicts. The only check that is not passing is the other automated review check, which reports the same policy bypass in code this PR changes, so it is likely related; the other 14 checks pass. After the policy gate and the policy-denied live run, nothing else stands between this PR and merge.

An open that boots a stopped Android emulator stops that launch when the open
fails (#4764). A failure inside the boot was outside that rule: readiness
terminated the process it launched only when the request was canceled, so a
boot that failed for another reason left an emulator running with no session to
own it, and no later close ever learned to stop it (#4847).

Readiness now decides per failure reason at the owner that holds the launched
pid. A refusal that spent the startup budget keeps booting, which is what the
--timeout contract and the existing tests promise, and a canceled request keeps
terminating its launch. Every other failure after the launch returned a pid
stops that process and rethrows its own error: the host could not record the
launch, a boot probe failed inside the budget, or discovery went wrong. A
terminate that itself throws records a diagnostic naming the boot failure it
answers rather than replacing that failure. An emulator that was already
running is still never stopped, and the daemon's open orchestration gains no
second stop path.

commands.md and the open help said a boot that failed before the emulator was
ready left it as it is; both now state the final rule.
…icy (#4847)

`terminate` is the one teardown a launched emulator's own host can perform, and
it was the one shutdown no policy was asked about: `assertShutdownAllowed`
guarded only `deviceShutdown`. A daemon that denies `device-shutdown` therefore
SIGTERM'd the emulator a failed boot had launched, and a canceled boot had
signaled it the same way before this.

Pass that assertion to the host that owns the launch and ask it before anything
else. A denied daemon now leaves its launch running and the caller keeps the
failure that asked: readiness already records a diagnostic when `terminate`
throws, and the open reports its own boot error.

The keep-decision now reads the boot's phase rather than the clock, so a step
after a finished boot cannot read as a spent budget: only a boot-wait poller
that ran out that budget keeps its launch. The rule belongs to booting, not to
`open`, so `commands.md` says so.
@thymikee
thymikee force-pushed the fix/0.22-stop-emulator-on-failed-boot branch from 2278187 to c58a582 Compare November 20, 2026 23:19
@thymikee

Copy link
Copy Markdown
Member Author

Re-review at c58a582203, rebased onto decae77d37 so the branch now carries #4864's simulator wording too.

The gate. createAndroidEmulatorHost takes assertShutdownAllowed and calls it first in terminate, before the process table is read, so the one teardown a launched emulator's own host can perform obeys ADR 0029 whichever request asks: the failed-boot stop, the cancellation stop, and anything added later. Composition hands it the same assertion deviceShutdown uses (src/platform-runtime-operation-host.ts:123) — no new seam. terminateLaunch already kept the boot failure and recorded a refusal, so the open still reports its own error. ADR 0029's capability gate now says the launching host applies this gate to its own terminate.

Taken from the non-blocking list: (2) the keep-decision reads the boot's phase — a launch is kept only when a boot-wait poller ran out its startup budget, so a step that fails after the boot is done stops it; that removed the clock clause and the redundant reason clause. (3) commands.md now says the boot-time rule belongs to booting, so boot and app deployment follow it, and reads "because it launched it". (4) Both comments are the rule, and the body's test count is corrected: ten new unit tests, not seven. (1) ownership is left as the follow-up issue the coordinator is filing.

Live, at c58a582203. AVD agent-device-4539-live, injected terminal sys.boot_completed probe failure through a substituted platform-tools/adb, isolated --state-dir per run.

Denied policy — {"version":1,"capabilities":{"deny":["device-shutdown"]}} through AGENT_DEVICE_DAEMON_POLICY:

$ agent-device open "Settings" --platform android --device agent-device-4539-live --timeout 30000 --json
exit=1
  "message": "Android boot probe failed: closed",
  "details": { "serial": "emulator-5554", "stderr": "error: closed", "reason": "BOOT_COMMAND_FAILED" }

$ pgrep -f "avd agent-device-4539-live"
20018 /Users/thymikee/Library/Android/sdk/emulator/qemu/darwin-aarch64/qemu-system-aarch64 -avd agent-device-4539-live ...

# that request's log
{"phase":"android_emulator_launch_terminate_failed","data":{"pid":20018,
 "error":"This daemon's policy denies device-shutdown.","bootFailure":"Android boot probe failed"}}

Control — same fault, same command, no policy named:

$ agent-device open "Settings" --platform android --device agent-device-4539-live --timeout 30000 --json
exit=1
  "message": "Android boot probe failed: closed",
  "details": { "serial": "emulator-5554", "stderr": "error: closed", "reason": "BOOT_COMMAND_FAILED" }

$ pgrep -f "avd agent-device-4539-live"      # nothing: the launch was stopped

The kept emulator was stopped afterwards under a daemon with no policy (shutdown --platform android --device agent-device-4539-live → OK: killing emulator). The AVD is left off and all six test daemons are stopped. Evidence comment 7051556847 belongs to 22781873c6.

Checks at this head: build, typecheck, lint, format, check:layering, test:unit, fallow audit, check:mcp-metadata, doc prose and links, command-docs.

@apex-sentinel-staging

This comment has been minimized.

@apex-sentinel-staging

Copy link
Copy Markdown

Apex Sentinel · ✅ Approve · review of 8bf0b9a

Since the review of c58a582: 0 new · 0 still open · 1 no longer raised (1 marked fixed)

No open findings.

1 finding below minor hidden (user_settings.min_severity).

Reviewed with this repository's own Sentinel configuration (18c6c42cde99).

💬 Talking to Sentinel

In a finding's thread, reply with:

Command What it does
@apex-sentinel-staging note <context> Adds context; Sentinel re-checks the cited code
@apex-sentinel-staging pivot <why> Says the finding is wrong; Sentinel re-checks the cited code
@apex-sentinel-staging like Marks the finding as useful
@apex-sentinel-staging dislike <why> Marks it as not useful, so it is not raised again

On this conversation, comment @apex-sentinel-staging review to run a full review once again.

@thymikee

Copy link
Copy Markdown
Member Author

This PR is ready at 8bf0b9a. The earlier findings from #4863 (comment) are fixed: the keep-boot decision now reads the boot phase and typed evidence, the policy gate reaches the emulator host, and the open --help text describes the denied-shutdown case.

Not blocking, and these can be taken or left: the bootBudgetSpent: true marker in packages/platform-android/src/readiness/runtime.ts:273 becomes a public error.details field that no doc describes, so deriving the keep from !bootWaitDone && clock.now() >= deadlineAtMs would drop it; the ADR 0029 amendment in docs/adr/0029-daemon-policy.md:8 says the gate covers every host that can tear down a launched emulator, while the daemon's launched-process stop relies on the request-level deviceShutdownDenied flag; and one composition test through createPlatformRuntimeHost with a throwing assertShutdownAllowed would catch a dropped argument at src/platform-runtime-operation-host.ts:123.

All 14 checks are green. The live denied-policy and control runs in #4863 (comment) were taken as reported. Their shape matches what was asked for, and they ran at c58a582, with 8bf0b9a changing only a help string. Not verified here: the unit tests were not run, and the new host test was judged from the diff and the pre-change code. No conflicts are known, and nothing else must happen before merge.

The open inline threads still need resolving. These are fixed at this commit: #4863 (comment) (help text now has the denial sentence), #4863 (comment) (policy gate and help gap covered at the emulator host and in help), #4863 (comment) (keep decision no longer compares the clock or reason strings), and #4863 (comment) (the two-constant split is gone). #4863 (comment) does not apply here: the ownership check before the readiness stop was ruled out as follow-up #4867.

@thymikee thymikee added the ready-for-human Valid work that needs human implementation, judgment, or maintainer merge label Nov 20, 2026
@thymikee
thymikee merged commit c50f522 into 0.22 Nov 21, 2026
14 checks passed
@thymikee
thymikee deleted the fix/0.22-stop-emulator-on-failed-boot branch November 21, 2026 00:00
thymikee added a commit that referenced this pull request Nov 21, 2026
* fix(android): stop the emulator a failed cold boot left unowned

An open that boots a stopped Android emulator stops that launch when the open
fails (#4764). A failure inside the boot was outside that rule: readiness
terminated the process it launched only when the request was canceled, so a
boot that failed for another reason left an emulator running with no session to
own it, and no later close ever learned to stop it (#4847).

Readiness now decides per failure reason at the owner that holds the launched
pid. A refusal that spent the startup budget keeps booting, which is what the
--timeout contract and the existing tests promise, and a canceled request keeps
terminating its launch. Every other failure after the launch returned a pid
stops that process and rethrows its own error: the host could not record the
launch, a boot probe failed inside the budget, or discovery went wrong. A
terminate that itself throws records a diagnostic naming the boot failure it
answers rather than replacing that failure. An emulator that was already
running is still never stopped, and the daemon's open orchestration gains no
second stop path.

commands.md and the open help said a boot that failed before the emulator was
ready left it as it is; both now state the final rule.

* fix(android): gate the launched emulator's stop with the shutdown policy (#4847)

`terminate` is the one teardown a launched emulator's own host can perform, and
it was the one shutdown no policy was asked about: `assertShutdownAllowed`
guarded only `deviceShutdown`. A daemon that denies `device-shutdown` therefore
SIGTERM'd the emulator a failed boot had launched, and a canceled boot had
signaled it the same way before this.

Pass that assertion to the host that owns the launch and ask it before anything
else. A denied daemon now leaves its launch running and the caller keeps the
failure that asked: readiness already records a diagnostic when `terminate`
throws, and the open reports its own boot error.

The keep-decision now reads the boot's phase rather than the clock, so a step
after a finished boot cannot read as a spent budget: only a boot-wait poller
that ran out that budget keeps its launch. The rule belongs to booting, not to
`open`, so `commands.md` says so.

* docs(open): say a denied device-shutdown policy keeps a failed boot's emulator running
thymikee added a commit that referenced this pull request Nov 21, 2026
* fix(android): stop the emulator a failed cold boot left unowned

An open that boots a stopped Android emulator stops that launch when the open
fails (#4764). A failure inside the boot was outside that rule: readiness
terminated the process it launched only when the request was canceled, so a
boot that failed for another reason left an emulator running with no session to
own it, and no later close ever learned to stop it (#4847).

Readiness now decides per failure reason at the owner that holds the launched
pid. A refusal that spent the startup budget keeps booting, which is what the
--timeout contract and the existing tests promise, and a canceled request keeps
terminating its launch. Every other failure after the launch returned a pid
stops that process and rethrows its own error: the host could not record the
launch, a boot probe failed inside the budget, or discovery went wrong. A
terminate that itself throws records a diagnostic naming the boot failure it
answers rather than replacing that failure. An emulator that was already
running is still never stopped, and the daemon's open orchestration gains no
second stop path.

commands.md and the open help said a boot that failed before the emulator was
ready left it as it is; both now state the final rule.

* fix(android): gate the launched emulator's stop with the shutdown policy (#4847)

`terminate` is the one teardown a launched emulator's own host can perform, and
it was the one shutdown no policy was asked about: `assertShutdownAllowed`
guarded only `deviceShutdown`. A daemon that denies `device-shutdown` therefore
SIGTERM'd the emulator a failed boot had launched, and a canceled boot had
signaled it the same way before this.

Pass that assertion to the host that owns the launch and ask it before anything
else. A denied daemon now leaves its launch running and the caller keeps the
failure that asked: readiness already records a diagnostic when `terminate`
throws, and the open reports its own boot error.

The keep-decision now reads the boot's phase rather than the clock, so a step
after a finished boot cannot read as a spent budget: only a boot-wait poller
that ran out that budget keeps its launch. The rule belongs to booting, not to
`open`, so `commands.md` says so.

* docs(open): say a denied device-shutdown policy keeps a failed boot's emulator running
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ready-for-human Valid work that needs human implementation, judgment, or maintainer merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant