Repository navigation
fix(close): stop an Apple simulator only on its open's own boot proof - #4864
Conversation
Plain `close` stopped an Apple simulator whenever the pre-open inventory snapshot said the device was stopped, which is an inference about a moment before the boot, not a fact about the boot (#4791). Anything else could have booted the simulator in that window — a concurrent `xcrun simctl boot`, another workspace, a person at the machine — and closing the session then shut down a boot the session never caused. The stop now requires positive proof from the step that could have performed it: the readiness call the open makes reports whether its own `simctl boot` started the boot, and only that answer gives the session a boot to stop. `open`'s preparation accepts an optional boot report and the Apple lifecycle forwards readiness's answer into it, so the port's other implementers are unchanged. Readiness answers on every exit: performed when it issued the boot, `already-booted` when the memo hit or the listing found the Simulator up or CoreSimulator refused the boot, and `no-boot-attempt` for macOS and physical devices. An owner that boots the device through a step outside its preparation, which is the daemon's Android emulator launch, answers nothing, so Android keeps its existing launched-process ownership. `resolveSessionBootOwnership` in contracts turns the pair of answers into the ownership the session records, and `SessionStore.updateOpenDevice` writes it beside `bootedByOpen` in the same store-owned write. A disproved re-open cannot take back a boot an earlier open of the same device proved, so the reason is recorded only alongside the ownership it refused. When the inference is refused, plain `close` keeps the simulator running and names `boot-owner-unverified` in `warnings`, so a kept-running device is never silent. `close --shutdown` still commands the stop without asking the ownership question, and an open that proved its boot still stops the device as before.
…eement The resolver required the pre-open snapshot to have inferred a boot before it would accept the boot step's own proof (#4791 review). The device can go down between the snapshot and readiness, which makes the reported boot real while the inference answers nothing, so the session would have owned no stop for a boot it performed. A boot the boot step reports performing is now proof on its own, and the contracts suite pins each answer pair at the owner of the decision.
Live evidenceDedicated simulator (a) cold open, then plain close — close stops the simulator it bootedThe proof here is the open's own boot step: readiness issued (b) prebooted open, then plain close — close keeps it runningNo (c) foreign boot between the snapshot and the boot step — head keeps it, base stops itThe open was started, and after 2s a separate loop issued Head Base (d)
|
Size Report
Startup median (7 runs, lower is better):
|
Apex Sentinel · ✅ Approve · review of
|
| 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.
|
This PR is ready at bece9b3. CI is green: 15 checks, none failing. There are no conflicts. Nothing else is needed before merge. Not verified here: tests and a device run, and the author's live transcript was not re-run. Not blocking, and fine to take or leave: (1) |
Review follow-up at
|
| Finding | Fix |
|---|---|
A proved boot granted nothing without the snapshot's agreement |
bece9b32a4 — performed: true owns the stop on its own. Confirmed load-bearing, not cosmetic: an existing-session re-open always answers bootOccurred: false (device-selection-resolver.ts), so before that commit a re-open that really cold-booted a device that died mid-session owned nothing. |
A failed re-open stripped bootOwnerUnverified, silencing a later close |
updateOpenDevice keeps the recorded disproval on a 'none' write — it establishes no ownership of its own, and the same foreign boot is still running whether this re-open then succeeds or fails. Routed case: disproved open → re-open failing at beforeDispatch → close still warns. |
CloseBootOwnership admitted "owns the stop" and "report one withheld" at once, and the publisher re-implemented the store's math |
The type is now the exclusive union `'proved' |
| The resolver was a pure algorithm in contracts (ADR 0038: vocabulary, not algorithms) | resolveSessionBootOwnership moved to session-boot-ownership.ts in the daemon session lifecycle; its decision table moved with it. Contracts keeps DeviceBootPerformance, CloseBootOwnership and the reason table. |
| Nothing pinned the lifecycle forwarding line — deleting it kept both lanes green | Two cases in lifecycle-readied-device.test.ts (cold → performed: true; simctl refusal → already-booted). Mutation-checked: deleting onSimulatorBoot: input.onBootPerformance fails them. |
| The third refusal phrase widened unrelated boot paths with no evidence simctl emits it | Dropped. simctlBootRefusedAlreadyBooted matches only CoreSimulator's own wording, and core/__tests__/simulator.test.ts now pins that ensureBootedSimulator absorbs that exact refusal — both readers of the shared detector. |
close --shutdown on a disproved session untested |
Routed case: after a disproved open, close --shutdown calls the runtime stop once, no warnings. Live case (d) covers the proved-boot side. |
bootedByOpen's doc named one of its two producers; cli-help-workflows.ts still described the old rule; the ios-simulator skill card omitted the new warning |
All three updated, and CLOSE_BOOT_OWNER_UNVERIFIED_REASONS now registers cli-help-workflows.ts as a guarded surface, so the next reason there cannot land undocumented. |
The no-boot-attempt comment described the simulator case incorrectly |
Rewritten: it is the answer for a target this call readies without a simulator boot — macOS, a physical device, another kind. |
The routed test's command.bootPerformance! could misclassify a future case |
run is a discriminated union now: an open must state its boot report, a close cannot. |
Left as-is deliberately: the warning states "The device is still running" from close's own evidence rather than a fresh observation, matching the sibling #4585 warnings beside it and the wording commands.md / sessions.md promise. The 5-second bootedSimulators memo stays out of scope and is listed under "Not in this PR".
Gates at this head: build, typecheck, check:layering, format, oxlint, fallow audit --base origin/0.22, check:mcp-metadata, check:command-docs, check:doc-prose, check:daemon-wire-compat (protocol hash unchanged), the published-reason docs guard, and 875 focused unit tests across the sessions, core, contracts and platform-apple lanes. The live evidence above was recorded at bece9b32a4; this commit changes only re-open/after-failure retention and doc surfaces.
|
Correction on the commit in my review-follow-up comment: this PR was squash-merged as The merged code is |
|
Correction on the commit named in my review-follow-up comment: this PR was squash-merged as Everything the table describes as already fixed in |
Addresses review on #4864: - a re-open that proves nothing keeps the recorded disproved boot, so a failed re-open cannot silence the warning for the same foreign boot (session-store.ts); routed and store cases pin both directions - CloseBootOwnership is a four-member union, so owning a stop and reporting one withheld cannot both be represented; the publisher no longer duplicates the store's ownership math - resolveSessionBootOwnership moves to the daemon session lifecycle per ADR 0038/R18 (contracts keeps vocabulary, not algorithms) - the boot refusal read drops the unverified third phrase, keeping only CoreSimulator's own wording, pinned at both readers - lifecycle forwarding of the boot report is pinned where it happens - docs and help name the new warning: session-state field contract, cli-help-workflows (now a guarded surface), ios-simulator skill (cherry picked from commit 96e0417)
…#4864) * fix(close): stop an Apple simulator only on its open's own boot proof Plain `close` stopped an Apple simulator whenever the pre-open inventory snapshot said the device was stopped, which is an inference about a moment before the boot, not a fact about the boot (#4791). Anything else could have booted the simulator in that window — a concurrent `xcrun simctl boot`, another workspace, a person at the machine — and closing the session then shut down a boot the session never caused. The stop now requires positive proof from the step that could have performed it: the readiness call the open makes reports whether its own `simctl boot` started the boot, and only that answer gives the session a boot to stop. `open`'s preparation accepts an optional boot report and the Apple lifecycle forwards readiness's answer into it, so the port's other implementers are unchanged. Readiness answers on every exit: performed when it issued the boot, `already-booted` when the memo hit or the listing found the Simulator up or CoreSimulator refused the boot, and `no-boot-attempt` for macOS and physical devices. An owner that boots the device through a step outside its preparation, which is the daemon's Android emulator launch, answers nothing, so Android keeps its existing launched-process ownership. `resolveSessionBootOwnership` in contracts turns the pair of answers into the ownership the session records, and `SessionStore.updateOpenDevice` writes it beside `bootedByOpen` in the same store-owned write. A disproved re-open cannot take back a boot an earlier open of the same device proved, so the reason is recorded only alongside the ownership it refused. When the inference is refused, plain `close` keeps the simulator running and names `boot-owner-unverified` in `warnings`, so a kept-running device is never silent. `close --shutdown` still commands the stop without asking the ownership question, and an open that proved its boot still stops the device as before. * fix(close): let a proved boot own the stop without the snapshot's agreement The resolver required the pre-open snapshot to have inferred a boot before it would accept the boot step's own proof (#4791 review). The device can go down between the snapshot and readiness, which makes the reported boot real while the inference answers nothing, so the session would have owned no stop for a boot it performed. A boot the boot step reports performing is now proof on its own, and the contracts suite pins each answer pair at the owner of the decision.
Addresses review on #4864: - a re-open that proves nothing keeps the recorded disproved boot, so a failed re-open cannot silence the warning for the same foreign boot (session-store.ts); routed and store cases pin both directions - CloseBootOwnership is a four-member union, so owning a stop and reporting one withheld cannot both be represented; the publisher no longer duplicates the store's ownership math - resolveSessionBootOwnership moves to the daemon session lifecycle per ADR 0038/R18 (contracts keeps vocabulary, not algorithms) - the boot refusal read drops the unverified third phrase, keeping only CoreSimulator's own wording, pinned at both readers - lifecycle forwarding of the boot report is pinned where it happens - docs and help name the new warning: session-state field contract, cli-help-workflows (now a guarded surface), ios-simulator skill (cherry picked from commit 96e0417)
…on (#4869) * fix(close): keep a disproved boot on record and decide it in the daemon Addresses review on #4864: - a re-open that proves nothing keeps the recorded disproved boot, so a failed re-open cannot silence the warning for the same foreign boot (session-store.ts); routed and store cases pin both directions - CloseBootOwnership is a four-member union, so owning a stop and reporting one withheld cannot both be represented; the publisher no longer duplicates the store's ownership math - resolveSessionBootOwnership moves to the daemon session lifecycle per ADR 0038/R18 (contracts keeps vocabulary, not algorithms) - the boot refusal read drops the unverified third phrase, keeping only CoreSimulator's own wording, pinned at both readers - lifecycle forwarding of the boot report is pinned where it happens - docs and help name the new warning: session-state field contract, cli-help-workflows (now a guarded surface), ios-simulator skill (cherry picked from commit 96e0417) * docs(skill): keep the pinned close guidance contiguous in the iOS card The simulator skill contract reads the card's close paragraph as one contiguous string. Inserting the boot-owner-unverified sentence mid- paragraph broke that read, so the card now states the pinned guidance in full and names the new warning after it. * refactor(daemon): declare boot ownership where its consumers read it Addresses non-blocking review on #4869: - CloseBootOwnership leaves contracts. Its only consumers are in the daemon, so contracts had vocabulary no zone above it shared. R81 rejects a core -> sessions type read, and core/session-store.ts consumes the answer, so it lands in core/session-state.ts beside the flags it decides, which both consumers read downward - the iOS skill card now scopes the boot-owner-unverified warning to a simulator the open FOUND stopped, which is the case that can be disproved; the pinned contiguous paragraph is intact - session-open-execution comment names one union answer, not a pair * docs(help): scope the boot-owner-unverified close note to a simulator open found stopped * docs(help): limit the no-warning close note to a device running at the session's first open * docs(help): keep the first-open close note to a device the session has not since booted * docs(skill): limit the iOS boot-owner warning note to the session's first open * docs(help): keep the reopen warning note to the same device * docs(help): clear the boot-owner warning only on a recorded later boot * docs(help): scope the boot-owner warning sentence to the session's first open
…#4864) * fix(close): stop an Apple simulator only on its open's own boot proof Plain `close` stopped an Apple simulator whenever the pre-open inventory snapshot said the device was stopped, which is an inference about a moment before the boot, not a fact about the boot (#4791). Anything else could have booted the simulator in that window — a concurrent `xcrun simctl boot`, another workspace, a person at the machine — and closing the session then shut down a boot the session never caused. The stop now requires positive proof from the step that could have performed it: the readiness call the open makes reports whether its own `simctl boot` started the boot, and only that answer gives the session a boot to stop. `open`'s preparation accepts an optional boot report and the Apple lifecycle forwards readiness's answer into it, so the port's other implementers are unchanged. Readiness answers on every exit: performed when it issued the boot, `already-booted` when the memo hit or the listing found the Simulator up or CoreSimulator refused the boot, and `no-boot-attempt` for macOS and physical devices. An owner that boots the device through a step outside its preparation, which is the daemon's Android emulator launch, answers nothing, so Android keeps its existing launched-process ownership. `resolveSessionBootOwnership` in contracts turns the pair of answers into the ownership the session records, and `SessionStore.updateOpenDevice` writes it beside `bootedByOpen` in the same store-owned write. A disproved re-open cannot take back a boot an earlier open of the same device proved, so the reason is recorded only alongside the ownership it refused. When the inference is refused, plain `close` keeps the simulator running and names `boot-owner-unverified` in `warnings`, so a kept-running device is never silent. `close --shutdown` still commands the stop without asking the ownership question, and an open that proved its boot still stops the device as before. * fix(close): let a proved boot own the stop without the snapshot's agreement The resolver required the pre-open snapshot to have inferred a boot before it would accept the boot step's own proof (#4791 review). The device can go down between the snapshot and readiness, which makes the reported boot real while the inference answers nothing, so the session would have owned no stop for a boot it performed. A boot the boot step reports performing is now proof on its own, and the contracts suite pins each answer pair at the owner of the decision.
…on (#4869) * fix(close): keep a disproved boot on record and decide it in the daemon Addresses review on #4864: - a re-open that proves nothing keeps the recorded disproved boot, so a failed re-open cannot silence the warning for the same foreign boot (session-store.ts); routed and store cases pin both directions - CloseBootOwnership is a four-member union, so owning a stop and reporting one withheld cannot both be represented; the publisher no longer duplicates the store's ownership math - resolveSessionBootOwnership moves to the daemon session lifecycle per ADR 0038/R18 (contracts keeps vocabulary, not algorithms) - the boot refusal read drops the unverified third phrase, keeping only CoreSimulator's own wording, pinned at both readers - lifecycle forwarding of the boot report is pinned where it happens - docs and help name the new warning: session-state field contract, cli-help-workflows (now a guarded surface), ios-simulator skill (cherry picked from commit 96e0417) * docs(skill): keep the pinned close guidance contiguous in the iOS card The simulator skill contract reads the card's close paragraph as one contiguous string. Inserting the boot-owner-unverified sentence mid- paragraph broke that read, so the card now states the pinned guidance in full and names the new warning after it. * refactor(daemon): declare boot ownership where its consumers read it Addresses non-blocking review on #4869: - CloseBootOwnership leaves contracts. Its only consumers are in the daemon, so contracts had vocabulary no zone above it shared. R81 rejects a core -> sessions type read, and core/session-store.ts consumes the answer, so it lands in core/session-state.ts beside the flags it decides, which both consumers read downward - the iOS skill card now scopes the boot-owner-unverified warning to a simulator the open FOUND stopped, which is the case that can be disproved; the pinned contiguous paragraph is intact - session-open-execution comment names one union answer, not a pair * docs(help): scope the boot-owner-unverified close note to a simulator open found stopped * docs(help): limit the no-warning close note to a device running at the session's first open * docs(help): keep the first-open close note to a device the session has not since booted * docs(skill): limit the iOS boot-owner warning note to the session's first open * docs(help): keep the reopen warning note to the same device * docs(help): clear the boot-owner warning only on a recorded later boot * docs(help): scope the boot-owner warning sentence to the session's first open
Closes #4791. Design context: #4539 (comment)
What changed
Plain
closenow stops an Apple simulator only when the session's ownopenproved it performed the boot. The pre-open inventory snapshot ("device was stopped") is an inference the platform's answer can confirm or refute, never proof on its own.OpenApplicationPreparationInput.onBootPerformance?: (report) => void(@agent-device/contracts/device-boot:DeviceBootPerformance). Optional so external runtime implementers stay source-compatible.{ performed: true },{ performed: false, reason: 'already-booted' }(fresh Booted listing, recent boot observation, orsimctlrefusing the boot), orno-boot-attemptfor a target this call readies without a simulator boot. macOS and physical devices report the no-attempt answer; nothing else writesalready-booted.simctlBootRefusedAlreadyBootedinpackages/platform-apple/src/core/simctl.ts, now shared withensureBootedSimulator. CoreSimulator refusessimctl bootwith prose and exit 149 and no distinguishable code, so this stays a string read — platform-owned, documented, pinned at both readers against CoreSimulator's exact output.CloseBootOwnership = 'proved' | 'inferred' | 'disproved' | 'none'in contracts; the deciding functionresolveSessionBootOwnershiplives in the daemon session lifecycle (ADR 0038: contracts keeps vocabulary, not algorithms). A proved boot owns the stop on its own;inferredkeeps Android's snapshot answer in charge (Android boots outside the preparation and answers nothing);disprovedrefuses the stop and says why.bootOwnerUnverified?: trueis written only throughSessionStore.updateOpenDevice, which also classifies it in the layering table. A'none'write — a re-open that proves nothing, including one that then fails before dispatch — keeps the recorded disproval: the same foreign boot is still running, so a later plainclosestill warns.warnings: "This session's open found this device stopped, but reported boot-owner-unverified: its own boot step never booted the device, so close did not request a stop. The device is still running." The token is read fromCLOSE_BOOT_OWNER_UNVERIFIED_REASONS.commands.md,sessions.md, theclosecommand metadata, bothcli-help-workflows.tssurfaces (now enforced by the published-reason guard), and the ios-simulator skill card.What is unchanged
close --shutdownpassesexplicitShutdown: trueand still commands the stop regardless of ownership, including on a disproved session (routed case + live).onBootPerformanceis answered anywhere in platform-android;inferAndroidEmulatorBootOwnershipis untouched;session-open-launch-cleanup.tsreadsbootedByOpenonly with a matchingandroidLaunchIdentity, so An open that boots an emulator and then fails leaves it running without a session #4764 cleanup is unaffected.Evidence
Automated (
pnpm exec vitest run --project unit-core <path>):session-close-foreign-boot.test.ts: a disproved open keeps the device and warns; a proved open stops it;close --shutdownon a disproved session commands the stop; a failed re-open cannot silence the recorded disproval. Mutation-checked: dropping the'none'retention in the store fails it.e937e57176fails at base (bootedByOpen: true, stop asked for) and passes at head.session-boot-ownership.test.tspins every ownership answer pair at the decision owner.session-open-state.test.tsand the store cases:'disproved'records it; a disproved re-open cannot take back a proved boot; a'none're-open keeps the disproval.readiness/runtime.test.tsandlifecycle-readied-device.test.ts: the report shape on every exit, and the lifecycle forwarding of the report (mutation-checked: deletingonSimulatorBoot: input.onBootPerformancefails).core/__tests__/simulator.test.ts:ensureBootedSimulatorabsorbs CoreSimulator's exact refusal, so the shared detector is pinned at both readers.Live — dedicated simulator
agent-device-4791-liveonly (created and deleted afterwards; no other simulator touched), branch CLI over an isolated--state-dir, JSON transcripts, plus a base-CLI comparison of the same transcript. Posted as a comment on this PR: cold stop (data.shutdown.success: true), prebooted retention, the foreign-boot race (head keeps Booted with the warning; base stops it — the bug), andclose --shutdown.Known limitations
simctlreporting its own call, not from a boot claim; booting a Simulator takes no claim (#4749), and this PR does not add one. Mis-detection keeps the device running — the conservative direction.bootedSimulatorsmemo expired mid-open can make readiness re-boot an already-Booted device and answerperformed: true. Retaining boot-time provenance would need the ownership store this issue rules out, so the memo stays as-is; the residual window is the memo's staleness bound, and it can only ever stop a device the session itself found stopped.simctl listusually sees the foreign boot and infers nothing at all. The live case therefore holds the session open at the readiness boundary with the foreign boot landing during it — the same window the routed test models — with the base-vs-head contrast as the behavioral proof.bece9b32a4. The follow-up commit changes only re-open/after-failure retention and doc surfaces, which the routed tests cover.check:daemon-wire-compatpasses with the protocol hash unchanged.Not in this PR
session-open-launch-cleanup.tsreadsbootedByOpen === trueas launch-miss cleanup permission for non-Android devices too. The proof gate narrows that, but it is not boot ownership's contract.bootedSimulatorsmemo as a source of "already up" answers predates feat(close): stop a simulator or emulator the session's own open booted #4539.