fix(ios): give an unverifiable simulator state its own typed reason and cause text (#3321)

runner_unreachable meant both 'the runner stopped answering' and 'our own state
probe could not be read'. The probe verdict is now runner_destination_unverified,
and the open warning's cause text is a total map over the reasons.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

Author: thymikee

packages/platform-apple/src/runner/__tests__/runner-destination-watch.test.ts

@@ -172,7 +172,10 @@ test('an unreadable device state stops the runner without claiming a shutdown',
   (await listener.nextConnection()).destroy();
   await vi.waitFor(() => assert.equal(onStop.mock.calls.length, 1));
 
-  assert.equal((await takeRunnerWarmLossNotice(DEVICE.id))?.reason, 'runner_unreachable');
+  assert.equal(
+    (await takeRunnerWarmLossNotice(DEVICE.id))?.reason,
+    'runner_destination_unverified',
+  );
 });
 
 test('a boot unobservable on both reads while the destination process lives is a loss', async () => {

packages/platform-apple/src/runner/runner-destination-watch.ts

@@ -11,7 +11,10 @@ import {
  * Why a runner retained after `close` was stopped before the session asked for it again.
  * Keyed behavior: consumers branch on these values, never on prose.
  */
-export type RunnerWarmLossReason = 'runner_destination_lost' | 'runner_unreachable';
+export type RunnerWarmLossReason =
+  | 'runner_destination_lost'
+  | 'runner_unreachable'
+  | 'runner_destination_unverified';
 
 /**
  * What a retained runner's owner records when the watcher stops it: the typed reason, the session
@@ -80,7 +83,10 @@ const DESTINATION_LOST: LossVerdict = { action: 'stop', noticeReason: 'runner_de
  * The listing timed out or was unreadable, so nothing proves the device changed. Stopping is still
  * the safe side, but the notice must not claim a shutdown nobody observed.
  */
-const STATE_UNVERIFIABLE: LossVerdict = { action: 'stop', noticeReason: 'runner_unreachable' };
+const STATE_UNVERIFIABLE: LossVerdict = {
+  action: 'stop',
+  noticeReason: 'runner_destination_unverified',
+};
 
 type DestinationWatch = {
   device: DeviceInfo;
@@ -342,7 +348,7 @@ async function handleRefusedAttach(
  * boot the window began with, and anything else is destination loss: a shut-down device keeps its
  * old `launchd_sim` listed for ~6s, so the boot witness alone would read the old boot and call it
  * a crash. A listing that timed out or was unreadable is no evidence of a healthy device, so it
- * stops the runner too, but as `runner_unreachable`: it cannot support a claim about the device. A boot newer than the
+ * stops the runner too, but as `runner_destination_unverified`: it cannot support a claim about the device. A boot newer than the
  * window is Xcode's reboot; a boot unobservable twice is a device that is down with a reboot
  * promise that may already be in flight. Stopping pre-empts that promise in every loss case.
  */

src/commands/schema/cli-help.ts

@@ -530,7 +530,7 @@ Android physical-device prerequisites:
 Runner and daemon lifecycle (applies to simulators too):
   open without --relaunch is idempotent-foreground for an already-running app (it brings the process forward; it does not restart it). open --relaunch restarts the app; on iOS simulators this collapses to one simctl launch --terminate-running-process call instead of a separate terminate-then-launch.
   No runner read launches a session app that is not running: snapshot, wait, is, get, a reading find, and an interaction's leading reads (a gesture's viewport read, the capture that resolves a selector click/fill) answer the retriable APP_NOT_RUNNING instead of bare-launching over a launch SpringBoard still holds behind its deep-link confirmation. Only open, activate, and a command that mutates without a leading read bring a stopped app up.
-  close keeps a healthy iOS simulator XCTest runner warm by default so the next open on that simulator (same udid in the same simulator set) skips the runner build, unless --shutdown was requested, the session was recording, or the session held a device lease. A retained runner auto-stops after an idle window (default 5 minutes); set AGENT_DEVICE_IOS_RUNNER_IDLE_STOP_MS to override, or 0 to disable idle stop and retain until daemon exit. A simulator shut down externally while its runner is retained is detected and the retained runner is stopped, because the retained Xcode destination would otherwise reboot the simulator and leave it powered on; the next open reports reason=runner_destination_lost (or reason=runner_unreachable when the runner stopped answering) in its warnings.
+  close keeps a healthy iOS simulator XCTest runner warm by default so the next open on that simulator (same udid in the same simulator set) skips the runner build, unless --shutdown was requested, the session was recording, or the session held a device lease. A retained runner auto-stops after an idle window (default 5 minutes); set AGENT_DEVICE_IOS_RUNNER_IDLE_STOP_MS to override, or 0 to disable idle stop and retain until daemon exit. A simulator shut down externally while its runner is retained is detected and the retained runner is stopped, because the retained Xcode destination would otherwise reboot the simulator and leave it powered on; the next open reports reason=runner_destination_lost in its warnings, or reason=runner_unreachable when the runner stopped answering, or reason=runner_destination_unverified when the runner's connection closed and the simulator's state could not be read.
   Each AGENT_DEVICE_STATE_DIR runs its own daemon. It self-exits after an idle window (default 5 minutes, matching the runner idle-stop default) once it has no open sessions, no in-flight requests, and no active recording; set AGENT_DEVICE_DAEMON_IDLE_TIMEOUT_MS to override, or 0 to disable idle reap.
   On a machine shared by several agents, set AGENT_DEVICE_SESSION_IDLE_TIMEOUT_MS to also expire an individual session that has taken a host-global device claim and then received no commands for that long; the claim is released and the next command on that session answers SESSION_NOT_FOUND with details.reason SESSION_IDLE_EXPIRED naming the window and the device. Off by default, because on a shared host "idle" and "thinking" are indistinguishable: only set it where an abandoned claim blocking every other agent is the worse failure. Sessions holding a remote lease or any active capture (recording, logs, audio, performance, or trace) are never expired this way.
   A stale iOS runner lease — its owner process dead, or its AGENT_DEVICE_STATE_DIR deleted — is reclaimed automatically instead of failing with "is already owned by another agent-device daemon". A live owner's runner is also reclaimed when the requesting daemon holds the host-global device claim for that device: claims are exclusive, so holding one proves the runner's owner released the device and merely kept the runner warm. The error remains only for owners outside claim arbitration (a pre-claims build, or daemons pointed at different claim stores).

src/daemon/__tests__/request-router-open-claim.test.ts

@@ -213,6 +213,49 @@ test('open warns with the typed reason when a warm runner was stopped for a lost
   }
 });
 
+test('open warns with its own typed reason when a warm runner was stopped on an unverifiable state', async () => {
+  const sessionStore = makeSessionStore('agent-device-router-open-warm-unverified-');
+  const device = makeIosDevice('SIM-WARM-UNVERIFIED');
+  mockResolveTargetDevice.mockResolvedValue(device);
+  mockTakeRunnerWarmLossNotice.mockResolvedValueOnce({
+    reason: 'runner_destination_unverified',
+    deviceId: device.id,
+    sessionId: 'warm-unverified',
+    atMs: Date.now(),
+  });
+  const claimsDir = mkdtempForTestSync('agent-device-router-open-warm-unverified-claims-');
+  const previousClaimsDir = process.env.AGENT_DEVICE_CLAIMS_DIR;
+  process.env.AGENT_DEVICE_CLAIMS_DIR = claimsDir;
+
+  try {
+    const opened = await createOpenHandler(sessionStore)(
+      openRequest('warm-unverified', { platform: 'ios' }, 'req-open-warm-unverified', {}, [
+        'FixtureApp',
+      ]),
+    );
+
+    expect(opened.ok).toBe(true);
+    if (!opened.ok) return;
+    expect(mockTakeRunnerWarmLossNotice).toHaveBeenCalledWith(device.id);
+    expect(opened.data?.warnings).toEqual([
+      expect.stringContaining('reason=runner_destination_unverified'),
+    ]);
+    expect(String(opened.data?.warnings)).not.toContain('stopped answering');
+
+    const reopened = await createOpenHandler(sessionStore)(
+      openRequest('warm-unverified', { platform: 'ios' }, 'req-open-warm-unverified-again', {}, [
+        'FixtureApp',
+      ]),
+    );
+    expect(reopened.ok).toBe(true);
+    if (reopened.ok) expect(reopened.data?.warnings).toBeUndefined();
+  } finally {
+    if (previousClaimsDir === undefined) delete process.env.AGENT_DEVICE_CLAIMS_DIR;
+    else process.env.AGENT_DEVICE_CLAIMS_DIR = previousClaimsDir;
+    fs.rmSync(claimsDir, { recursive: true, force: true });
+  }
+});
+
 // The production reopen path never re-acquires the claim, so renewal has to ride the successful
 // existing-session open itself: without it, an owner that came back after a reboot still carries a
 // pre-reboot stamp and loses the device to the next caller that asks.

src/daemon/session-lifecycle/internal/session-open-execution.ts

@@ -141,14 +141,18 @@ async function readWarmRunnerLossNotice(
  * be stopped because the Simulator was shut down externally while it was retained (#3321). Names
  * the typed reason so automation can key on it without parsing prose.
  */
+const WARM_RUNNER_LOSS_CAUSE: Record<RunnerWarmLossNotice['reason'], string> = {
+  runner_destination_lost:
+    'the simulator was shut down externally while it was retained, so the runner was stopped before it could boot the simulator again',
+  runner_unreachable: 'it stopped answering while it was retained',
+  runner_destination_unverified:
+    "its connection closed while it was retained and the simulator's state could not be read, so the runner was stopped as a precaution",
+};
+
 function warmRunnerLossWarning(notice: RunnerWarmLossNotice): string {
-  const cause =
-    notice.reason === 'runner_destination_lost'
-      ? 'the simulator was shut down externally while it was retained, so the runner was stopped before it could boot the simulator again'
-      : 'it stopped answering while it was retained';
   return (
-    `The warm iOS runner left by a previous close was stopped at ${new Date(notice.atMs).toISOString()}: ${cause}. ` +
-    `reason=${notice.reason}`
+    `The warm iOS runner left by a previous close was stopped at ${new Date(notice.atMs).toISOString()}: ` +
+    `${WARM_RUNNER_LOSS_CAUSE[notice.reason]}. reason=${notice.reason}`
   );
 }
 

website/docs/docs/sessions.md

@@ -117,7 +117,7 @@ agent-device close --shutdown
 Without `--shutdown`, `close` keeps the iOS runner warm for the next `open`. If you shut that simulator
 down yourself (`xcrun simctl shutdown`) while the runner is waiting, agent-device stops the runner so it
 doesn't boot the simulator again, and the next `open` returns a warning that ends in
-`reason=runner_destination_lost`, or `reason=runner_unreachable` when the runner stopped answering.
+`reason=runner_destination_lost`. It ends in `reason=runner_unreachable` when the runner stopped answering, or `reason=runner_destination_unverified` when its connection closed and the simulator's state could not be read.
 
 ## Wait for a slow or busy device