fix(apple-runner): a canceled request is not a runner that stopped answering

The marker says the preflight gave up, and one of the things a preflight gives up on is a caller that
stopped waiting. `createRequestCanceledError` answers `COMMAND_FAILED` too, so the rule written last
round matched a cancellation exactly as well as a wedged runner: on a session that was ready and
still working, the cancel invalidated the session and replayed the canceled command against a fresh
boot nobody was going to wait for. The main branch rethrew cancellations before any restart branch
could see them; the marker rule made the marker the only question, and the marker does not distinguish
the two shapes it is applied to.

The exception belongs on the rule, where the verdict is, rather than on the call site that happens to
notice: a marked error restarts the session unless the typed reason on it says the request was
canceled. `isRequestCanceledDetails` is exported from the owning type so the rule reads that reason
instead of restating the literal, and `isRequestCanceledError` now asks it. Deleting the conjunct turns
both the classification test and the lifecycle test red — the lifecycle one pins the exact shape from
the report: ready session, marked cancellation, error rethrown, no invalidate called, no second boot.

Author: thymikee

CHANGELOG.md

@@ -22,7 +22,9 @@
   `pressButton`, `activateApp`).
 - Changed (iOS runner): what recovers a stuck runner is decided by the recorded error, not by its
   wording. A readiness preflight marks the error it gives up with, and that marker is now the whole
-  test for restarting the session and replaying the command. Two message checks decided it before,
+  test for restarting the session and replaying the command — except for a request that was canceled,
+  which that same catch also marks: a command nobody is going to send again has no restart to spend,
+  and the session it would tear down may be one that still works. Two message checks decided it before,
   and a preflight reaches the caller in whatever shape its connect loop ended with — "Runner did not
   accept connection", "Runner endpoint probe failed", a killed `simctl` fallback, a post that ran out
   of its budget — so only some of those restarted and the rest failed the command. The other half is

packages/kernel/src/errors.ts

@@ -262,10 +262,19 @@ export function createRequestCanceledError(details?: AppErrorDetails, cause?: un
   );
 }
 
+/**
+ * The typed reason of a canceled request, for a caller holding the details rather than the error:
+ * a rule table that matches on details needs the same fact {@link isRequestCanceledError} reads, and
+ * must not restate the literal.
+ */
+export function isRequestCanceledDetails(details: AppErrorDetails | undefined): boolean {
+  return details?.reason === REQUEST_CANCELED_REASON;
+}
+
 export function isRequestCanceledError(error: unknown): boolean {
   if (!(error instanceof AppError)) return false;
   if (error.code !== 'COMMAND_FAILED') return false;
-  if (error.details?.reason === REQUEST_CANCELED_REASON) return true;
+  if (isRequestCanceledDetails(error.details)) return true;
   // Owned debt: canceled errors that crossed a wire without their details keep
   // the message; do not add new message sniffs beside it.
   return error.message === REQUEST_CANCELED_MESSAGE;

packages/platform-apple/src/runner/__tests__/runner-error-classification.test.ts

@@ -1,6 +1,6 @@
 import assert from 'node:assert/strict';
 import { test } from 'vitest';
-import { AppError } from '@agent-device/kernel/errors';
+import { AppError, createRequestCanceledError } from '@agent-device/kernel/errors';
 import {
   RUNNER_ERROR_RULES,
   isRetryableRunnerError,
@@ -108,6 +108,14 @@ test('the preflight marker alone decides the restart', () => {
     shouldRestartRunnerAfterReadinessPreflight(commandFailed('Runner readiness refused')),
     false,
   );
+  // The same catch marks a caller that stopped waiting. That mark is not a runner that stopped
+  // answering: the command was canceled, so no restart has a request left to serve.
+  assert.equal(
+    shouldRestartRunnerAfterReadinessPreflight(
+      createRequestCanceledError({ runnerReadinessPreflightFailed: true }),
+    ),
+    false,
+  );
 });
 
 test('a deadline on its own earns no recovery verdict', () => {

packages/platform-apple/src/runner/__tests__/runner-lifecycle-readiness-preflight.test.ts

@@ -1,6 +1,10 @@
 import assert from 'node:assert/strict';
 import { beforeEach, test, vi } from 'vitest';
-import { AppError } from '@agent-device/kernel/errors';
+import {
+  AppError,
+  createRequestCanceledError,
+  isRequestCanceledError,
+} from '@agent-device/kernel/errors';
 import { appleRunnerTestHost } from '../test-host.ts';
 import type { RunnerXctestrunArtifact } from '../runner-xctestrun.ts';
 import { IOS_SIMULATOR } from './device-fixtures.ts';
@@ -178,6 +182,31 @@ test('a failed readiness probe without the marker does not restart the session',
   assert.equal(mockEnsureRunnerSession.mock.calls.length, 1);
 });
 
+test('a cancellation during the readiness preflight does not restart the session it canceled', async () => {
+  const session = makeRunnerSession({ port: 8100, ready: true });
+
+  // The preflight's catch marks whatever it was waiting on when it gave up, and one of the things
+  // it waits on is a caller that stopped waiting. That mark describes a walkaway, not a wedged
+  // runner, and a session that is ready is the one the caller just left: restarting it would boot a
+  // runner for a command nobody is going to send again, and take down a session that still works.
+  mockEnsureRunnerSession.mockResolvedValueOnce(session);
+  mockExecuteRunnerCommandWithSession.mockRejectedValueOnce(
+    createRequestCanceledError({ runnerReadinessPreflightFailed: true, command: 'tap' }),
+  );
+
+  await assert.rejects(
+    () => runAppleRunnerCommand(IOS_SIMULATOR, { command: 'tap', x: 120, y: 240 }),
+    (error: unknown) => {
+      assert.ok(error instanceof AppError);
+      assert.ok(isRequestCanceledError(error));
+      return true;
+    },
+  );
+  assert.equal(mockInvalidateRunnerSession.mock.calls.length, 0);
+  assert.equal(mockEnsureRunnerSession.mock.calls.length, 1);
+  assert.equal(mockExecuteRunnerCommandWithSession.mock.calls.length, 1);
+});
+
 test('a boot that exited early does not wipe a restored runner artifact', async () => {
   const restoredSession = makeRunnerSession({
     port: 8100,

packages/platform-apple/src/runner/runner-contract.ts

@@ -1,6 +1,7 @@
 import {
   AppError,
   createRequestCanceledError,
+  isRequestCanceledDetails,
   toAppErrorCode,
   type AppErrorCode,
   type AppErrorDetails,
@@ -168,8 +169,14 @@ type RunnerErrorMatch = {
 const hasRetriableFlag: RunnerErrorDetailsMatch = (details) => details.retriable === true;
 const hasUsbmuxDeviceUnattached: RunnerErrorDetailsMatch = (details) =>
   details.usbmuxDeviceAttached === false;
+/**
+ * The preflight marks whatever it was waiting on when it stopped, and one of the things it waits on
+ * is a caller that stopped waiting. A canceled request is not a wedged runner: the restart this
+ * marker authorises would boot a runner for a command nobody is going to send again. Every abort in
+ * the connect loop normalizes to the typed canceled reason before it reaches here.
+ */
 const hasReadinessPreflightFailure: RunnerErrorDetailsMatch = (details) =>
-  details.runnerReadinessPreflightFailed === true;
+  details.runnerReadinessPreflightFailed === true && !isRequestCanceledDetails(details);
 
 type RunnerErrorVerdicts = {
   /** isRetryableRunnerError: transport error worth a same-session resend. */