Skip to content

fix(close): stop an Apple simulator only on its open's own boot proof - #4864

Merged
thymikee merged 2 commits into
0.22from
fix/0.22-apple-simulator-boot-proof
Nov 20, 2026
Merged

thymikee merged 2 commits into
0.22from
fix/0.22-apple-simulator-boot-proof

Conversation

@thymikee

@thymikee thymikee commented Nov 20, 2026 •

Copy link
Copy Markdown
Member

Closes #4791. Design context: #4539 (comment)

What changed

Plain close now stops an Apple simulator only when the session's own open proved 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.

  1. Optional port on the open preparation — OpenApplicationPreparationInput.onBootPerformance?: (report) => void (@agent-device/contracts/device-boot: DeviceBootPerformance). Optional so external runtime implementers stay source-compatible.
  2. Apple readiness answers for its own boot step on every exit: { performed: true }, { performed: false, reason: 'already-booted' } (fresh Booted listing, recent boot observation, or simctl refusing the boot), or no-boot-attempt for a target this call readies without a simulator boot. macOS and physical devices report the no-attempt answer; nothing else writes already-booted.
  3. The one read of the refusal text is simctlBootRefusedAlreadyBooted in packages/platform-apple/src/core/simctl.ts, now shared with ensureBootedSimulator. CoreSimulator refuses simctl boot with 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.
  4. One decision, exclusive by type — CloseBootOwnership = 'proved' | 'inferred' | 'disproved' | 'none' in contracts; the deciding function resolveSessionBootOwnership lives in the daemon session lifecycle (ADR 0038: contracts keeps vocabulary, not algorithms). A proved boot owns the stop on its own; inferred keeps Android's snapshot answer in charge (Android boots outside the preparation and answers nothing); disproved refuses the stop and says why.
  5. Session state — bootOwnerUnverified?: true is written only through SessionStore.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 plain close still warns.
  6. Close's outcome — keeps the simulator Running and appends to 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 from CLOSE_BOOT_OWNER_UNVERIFIED_REASONS.
  7. Docs/help — commands.md, sessions.md, the close command metadata, both cli-help-workflows.ts surfaces (now enforced by the published-reason guard), and the ios-simulator skill card.

What is unchanged

  • close --shutdown passes explicitShutdown: true and still commands the stop regardless of ownership, including on a disproved session (routed case + live).
  • Android: no onBootPerformance is answered anywhere in platform-android; inferAndroidEmulatorBootOwnership is untouched; session-open-launch-cleanup.ts reads bootedByOpen only with a matching androidLaunchIdentity, so An open that boots an emulator and then fails leaves it running without a session #4764 cleanup is unaffected.
  • A device found already running keeps running.

Evidence

Automated (pnpm exec vitest run --project unit-core <path>):

  • Routed session-close-foreign-boot.test.ts: a disproved open keeps the device and warns; a proved open stops it; close --shutdown on 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.
  • Base-vs-head probe: the routed scenario run at base commit e937e57176 fails at base (bootedByOpen: true, stop asked for) and passes at head.
  • session-boot-ownership.test.ts pins every ownership answer pair at the decision owner.
  • session-open-state.test.ts and 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.ts and lifecycle-readied-device.test.ts: the report shape on every exit, and the lifecycle forwarding of the report (mutation-checked: deleting onSimulatorBoot: input.onBootPerformance fails).
  • core/__tests__/simulator.test.ts: ensureBootedSimulator absorbs CoreSimulator's exact refusal, so the shared detector is pinned at both readers.

Live — dedicated simulator agent-device-4791-live only (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), and close --shutdown.

Known limitations

  • The proof comes from simctl reporting 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.
  • A Simulator whose 5-second bootedSimulators memo expired mid-open can make readiness re-boot an already-Booted device and answer performed: 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.
  • Reproducing the foreign-boot race by real timing is flaky, because readiness's fresh simctl list usually 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.
  • The live evidence was recorded at bece9b32a4. The follow-up commit changes only re-open/after-failure retention and doc surfaces, which the routed tests cover.
  • No new wire types: check:daemon-wire-compat passes with the protocol hash unchanged.

Not in this PR

  • #4749 — a Simulator boot takes no device claim, so two actors can race a boot by design.
  • session-open-launch-cleanup.ts reads bootedByOpen === true as launch-miss cleanup permission for non-Android devices too. The proof gate narrows that, but it is not boot ownership's contract.
  • The 5-second bootedSimulators memo as a source of "already up" answers predates feat(close): stop a simulator or emulator the session's own open booted #4539.

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.
@thymikee

Copy link
Copy Markdown
Member Author

Live evidence

Dedicated simulator agent-device-4791-live (iPhone 17 Pro, iOS 26.2, UDID 31B096EB-7FEA-408D-94E4-564C862FD910), created for these runs and deleted after them; no other simulator was touched. Driven with the branch CLI (node bin/agent-device.mjs --json) and an isolated --state-dir per case. Head bece9b32a4; the base run uses e937e57176 from a separate worktree.

(a) cold open, then plain close — close stops the simulator it booted

$ xcrun simctl list devices | grep agent-device-4791-live
    agent-device-4791-live (31B096EB-…) (Shutdown)
$ agent-device open https://example.com --platform ios --device agent-device-4791-live --state-dir .tmp/case-a --timeout 300000 --json
# … "selection": { "reason": "explicit-selector", "bootOccurred": true }, "message": "Opened: https://example.com"
$ xcrun simctl list devices | grep agent-device-4791-live
    agent-device-4791-live (31B096EB-…) (Booted)
$ agent-device close --platform ios --device agent-device-4791-live --state-dir .tmp/case-a --json
{ "success": true, "data": { "session": "default", "shutdown": { "success": true, "exitCode": 0 }, "message": "Closed: default" } }
$ xcrun simctl list devices | grep agent-device-4791-live
    agent-device-4791-live (31B096EB-…) (Shutdown)

The proof here is the open's own boot step: readiness issued simctl boot, so data.shutdown.success: true.

(b) prebooted open, then plain close — close keeps it running

$ xcrun simctl boot 31B096EB-…
$ agent-device open https://example.com --platform ios --device agent-device-4791-live --state-dir .tmp/case-b --json
# ok | selection.bootOccurred: false | Opened: https://example.com
$ xcrun simctl list devices | grep agent-device-4791-live
    agent-device-4791-live (31B096EB-…) (Booted)
$ agent-device close --platform ios --device agent-device-4791-live --state-dir .tmp/case-b --json
{ "success": true, "data": { "session": "default", "message": "Closed: default" } }
$ xcrun simctl list devices | grep agent-device-4791-live
    agent-device-4791-live (31B096EB-…) (Booted)

No data.shutdown, no warning: the device was running when the open looked at it, so nothing was owed.

(c) foreign boot between the snapshot and the boot step — head keeps it, base stops it

The open was started, and after 2s a separate loop issued xcrun simctl boot on the same UDID and won. Selection still saw a shut-down simulator, so it still reported bootOccurred: true; the open's own simctl boot was refused.

Head bece9b32a4:

start state:     agent-device-4791-live (31B096EB-…) (Shutdown)
foreign boot won the race after 2s (attempt 1)
open ok: True | selection.bootOccurred: True
after open:      agent-device-4791-live (31B096EB-…) (Booted)
$ agent-device close --platform ios --device agent-device-4791-live --state-dir .tmp/case-c --json
{
  "success": true,
  "data": {
    "session": "default",
    "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."
    ],
    "message": "Closed: default"
  }
}
$ xcrun simctl list devices | grep agent-device-4791-live
    agent-device-4791-live (31B096EB-…) (Booted)

Base e937e57176, same race:

foreign boot won the race (attempt 1)
open ok: True | selection.bootOccurred: True
after open:      agent-device-4791-live (31B096EB-…) (Booted)
$ agent-device close --platform ios --device agent-device-4791-live --state-dir .tmp/base-case-c --json
{ "success": true, "data": { "session": "default", "shutdown": { "success": true }, "message": "Closed: default" } }
$ xcrun simctl list devices | grep agent-device-4791-live
    agent-device-4791-live (31B096EB-…) (Shutdown)   # the bug: somebody else's boot, stopped

(d) close --shutdown still commands the stop

$ agent-device open https://example.com --platform ios --device agent-device-4791-live --state-dir .tmp/case-d --json   # cold boot
$ agent-device close --shutdown --platform ios --device agent-device-4791-live --state-dir .tmp/case-d --json
{ "success": true, "data": { "session": "default", "shutdown": { "success": true }, "message": "Closed: default" } }
$ xcrun simctl list devices | grep agent-device-4791-live
    agent-device-4791-live (31B096EB-…) (Shutdown)

Cleanup

Every session opened above was closed with the same session, platform, device and state directory.

$ xcrun simctl delete agent-device-4791-live
$ xcrun simctl list devices | grep -c agent-device-4791-live
0

@github-actions

Copy link
Copy Markdown
Contributor

Size Report

Metric Base Current Diff
Installed (including dependencies) 6.19 MB 6.19 MB +1.7 kB
Package (unpacked) 6.19 MB 6.19 MB +1.7 kB
Package (download) 1.89 MB 1.89 MB +427 B

Startup median (7 runs, lower is better):

Scenario Base Current Diff
CLI --version 39.7 ms 24.2 ms -15.5 ms
CLI --help 71.4 ms 55.6 ms -15.8 ms

@apex-sentinel-staging

Copy link
Copy Markdown

Apex Sentinel · ✅ Approve · review of bece9b3

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 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) readRecentBootObservation in packages/platform-apple/src/readiness/runtime.ts trusts the 5 s booted memo, which no shutdown clears, so a close followed by an open within 5 s can report already-booted when the device was just shut down (reasoned from the code, not reproduced); clearing the memo where this process stops a simulator would fix it. (2) The open response in session-open-execution.ts still publishes bootOccurred: true from the snapshot inference when the boot step was refused; deriving it from bootOwnership.ownsBoot would match the new ownership proof. (3) bootedByOpen and bootOwnerUnverified encode one tri-state, and the report travels through a callback into a mutable local; one bootOwnership field returned from prepareApplicationOpen would be simpler.

@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 decae77 into 0.22 Nov 20, 2026
15 checks passed
@thymikee
thymikee deleted the fix/0.22-apple-simulator-boot-proof branch November 20, 2026 23:03
@thymikee

Copy link
Copy Markdown
Member Author

Review follow-up at 96e04179c4

Three review passes came back. What I accepted and how:

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.

@thymikee

Copy link
Copy Markdown
Member Author

Correction on the commit in my review-follow-up comment: this PR was squash-merged as decae77d37 at 23:03 UTC, before that commit reached the branch, so it is not in this PR's history. The review fixes now ship in #4869, rebased onto merged 0.22 as b2a61c2621 (content identical to 96e04179c4 apart from the rebase).

The merged code is bece9b32a4: the invariant, the routed test, the platform tests and the live evidence above are all in it. #4869 only adds what the reviews asked for on top — the 'none'-write retention for a disproved boot, the exclusive union for CloseBootOwnership, the resolver's move out of contracts per ADR 0038, dropping the unverified third refusal phrase, and the doc/help surfaces #4864 left stale.

@thymikee

Copy link
Copy Markdown
Member Author

Correction on the commit named in my review-follow-up comment: this PR was squash-merged as decae77d37 at 23:03 UTC, before that commit reached the branch, so 96e04179c4 is not in this PR's history. The review fixes ship in #4869, rebased onto merged 0.22 as b2a61c2621 (content identical apart from the rebase).

Everything the table describes as already fixed in bece9b32a4 — the proved-boot rule — is in this merge. The rest of that table is the follow-up's diff, listed there file by file.

thymikee added a commit that referenced this pull request Nov 21, 2026
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)
thymikee added a commit that referenced this pull request Nov 21, 2026
…#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.
thymikee added a commit that referenced this pull request Nov 21, 2026
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)
thymikee added a commit that referenced this pull request Nov 21, 2026
…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
thymikee added a commit that referenced this pull request Nov 21, 2026
…#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.
thymikee added a commit that referenced this pull request Nov 21, 2026
…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
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