From 05b150eac388dbd29b0498aa201e48773aa43bf0 Mon Sep 17 00:00:00 2001
From: Rohit <40559587+Rohit3523@users.noreply.github.com>
Date: Tue, 22 Sep 2026 03:17:20 +0530
Subject: [PATCH 001/132] feat(maestro): support killApp via close mode

Maestro killApp triggers system-initiated process death (adb shell am
kill on Android) instead of stopApp's force-stop. On other platforms it
aliases stopApp through the shared close dispatcher.

- contracts: optional Interactor.kill, CloseApplicationInput.mode, with
  fallback to close in invokeApplicationClose
- android: killAndroidApp (am kill) wired onto the interactor
- maestro: killApp IR kind, parser, runtime port, daemon projection to
  an app-only close carrying killApp dispatch, conformance canonical
- daemon: replay dispatch folds killApp; session close passes
  mode kill into closeApplication
- upstream/116_kill_app now classifies identical; divergence removed
---
 .../application-lifecycle-interaction.test.ts | 47 +++++++++++++++++
 .../src/application-lifecycle-interaction.ts  |  8 ++-
 .../src/application-lifecycle-runtime.ts      |  6 +++
 packages/contracts/src/interactor-types.ts    |  6 +++
 packages/contracts/src/replay.ts              |  5 ++
 .../__tests__/daemon-runtime-port.test.ts     | 41 +++++++++++++++
 .../daemon-runtime-public-operation.test.ts   | 16 ++++++
 .../src/daemon-port/daemon-runtime-port.ts    |  4 ++
 .../daemon-runtime-public-operation.ts        | 22 +++++++-
 .../__tests__/program-ir-parser.test.ts       | 21 ++++++++
 .../__tests__/runtime-port-fixtures.ts        |  1 +
 .../internal/__tests__/runtime-port.test.ts   | 19 +++++++
 .../src/internal/conformance-normalize.ts     |  7 ++-
 .../src/internal/program-ir-command-parser.ts | 12 +++++
 packages/maestro/src/internal/program-ir.ts   |  7 +++
 .../src/internal/runtime-port-commands.ts     | 11 +++-
 .../src/internal/runtime-port-types.ts        |  1 +
 .../maestro/src/internal/support-matrix.ts    |  2 +-
 .../test/conformance/expected-divergence.ts   |  5 --
 .../src/__tests__/app-lifecycle-open.test.ts  | 43 +++++++++++++++-
 .../platform-android/src/app-lifecycle.ts     | 20 ++++++++
 packages/platform-android/src/lifecycle.ts    |  1 +
 packages/platform-android/src/mechanics.ts    |  1 +
 .../fuzz/validation-arbitraries-maestro.ts    |  2 +
 src/core/interactors/android.ts               |  2 +
 .../session-replay-maestro-request.test.ts    | 13 +++++
 .../session-replay-maestro-request.ts         |  1 +
 .../session-close-lifecycle-runtime.test.ts   | 50 +++++++++++++++++++
 .../internal/session-close.ts                 |  1 +
 website/docs/docs/replay-e2e.md               |  2 +-
 30 files changed, 364 insertions(+), 13 deletions(-)

diff --git a/packages/contracts/src/application-lifecycle-interaction.test.ts b/packages/contracts/src/application-lifecycle-interaction.test.ts
index 2e42310f7c..662aca9474 100644
--- a/packages/contracts/src/application-lifecycle-interaction.test.ts
+++ b/packages/contracts/src/application-lifecycle-interaction.test.ts
@@ -5,6 +5,7 @@ import type { OpenApplicationInput } from './application-lifecycle-runtime.ts';
 import {
   bindDirectApplicationLifecycle,
   bindLocalApplicationLifecycleInteractor,
+  invokeApplicationClose,
   invokeApplicationOpen,
 } from './application-lifecycle-interaction.ts';
 
@@ -91,6 +92,52 @@ test('direct lifecycle owners preserve the daemon runtime launch URL follow-up',
   expect(calls[1]?.options).toHaveProperty('launchArgs', undefined);
 });
 
+test('kill mode dispatches Interactor.kill when the owner implements it', async () => {
+  const calls: string[] = [];
+  const interactor: Interactor = {
+    ...interactorWithOpen(),
+    close: async (app) => {
+      calls.push(`close:${app}`);
+    },
+    kill: async (app) => {
+      calls.push(`kill:${app}`);
+    },
+  };
+
+  await invokeApplicationClose({
+    device: LINUX_DEVICE,
+    interactor,
+    positionals: ['com.example.app'],
+    mode: 'kill',
+  });
+
+  expect(calls).toEqual(['kill:com.example.app']);
+});
+
+test('kill mode falls back to close when the owner has no kill', async () => {
+  const calls: string[] = [];
+  const interactor: Interactor = {
+    ...interactorWithOpen(),
+    close: async (app) => {
+      calls.push(`close:${app}`);
+    },
+  };
+
+  await invokeApplicationClose({
+    device: LINUX_DEVICE,
+    interactor,
+    positionals: ['com.example.app'],
+    mode: 'kill',
+  });
+  await invokeApplicationClose({
+    device: LINUX_DEVICE,
+    interactor,
+    positionals: ['com.example.app'],
+  });
+
+  expect(calls).toEqual(['close:com.example.app', 'close:com.example.app']);
+});
+
 test.each([
   {
     name: 'more than two positionals',
diff --git a/packages/contracts/src/application-lifecycle-interaction.ts b/packages/contracts/src/application-lifecycle-interaction.ts
index 0db4ce162f..c82d7ce814 100644
--- a/packages/contracts/src/application-lifecycle-interaction.ts
+++ b/packages/contracts/src/application-lifecycle-interaction.ts
@@ -370,13 +370,19 @@ export async function invokeApplicationClose(
     device: DeviceInfo;
     interactor: Interactor;
     positionals: readonly string[];
+    /** `kill` dispatches `Interactor.kill` with fallback to `close`; absent means `stop`. */
+    mode?: 'stop' | 'kill';
   }>,
 ): Promise<void> {
-  const { device, interactor, positionals } = params;
+  const { device, interactor, positionals, mode } = params;
   const app = positionals[0];
   if (!app) {
     if (device.platform === 'web') await interactor.close('');
     return;
   }
+  if (mode === 'kill' && interactor.kill) {
+    await interactor.kill(app);
+    return;
+  }
   await interactor.close(app);
 }
diff --git a/packages/contracts/src/application-lifecycle-runtime.ts b/packages/contracts/src/application-lifecycle-runtime.ts
index 58304a5235..73d1b5c78e 100644
--- a/packages/contracts/src/application-lifecycle-runtime.ts
+++ b/packages/contracts/src/application-lifecycle-runtime.ts
@@ -148,6 +148,12 @@ export type CloseApplicationInput = Readonly<{
   surface: SessionSurface;
   /** A selector-only close establishes readiness inside its admitted lifecycle binding. */
   ensureReady?: boolean;
+  /**
+   * `kill` is Maestro `killApp` (system-initiated process death: `am kill` on
+   * Android); absent means `stop`. Owners without an `Interactor.kill` alias
+   * it to `close` in the shared dispatcher.
+   */
+  mode?: 'stop' | 'kill';
   execution: ApplicationLifecycleExecution;
 }>;
 
diff --git a/packages/contracts/src/interactor-types.ts b/packages/contracts/src/interactor-types.ts
index 77f3982c58..d63cee6025 100644
--- a/packages/contracts/src/interactor-types.ts
+++ b/packages/contracts/src/interactor-types.ts
@@ -298,6 +298,12 @@ export type Interactor = {
   ): Promise<void>;
   openDevice(): Promise<void>;
   close(app: string): Promise<void>;
+  /**
+   * System-initiated process death (Maestro `killApp`): on Android `am kill`
+   * rather than `am force-stop`. Owners without a lighter-weight kill leave
+   * it undefined and the shared close dispatcher falls back to `close(app)`.
+   */
+  kill?(app: string): Promise<void>;
   tap(x: number, y: number): Promise<Record<string, unknown> | void>;
   /** Complete point-press semantics for owners with fused series, alternate buttons, or surfaces. */
   pressPoint?(point: Point, options: PressPointOptions): Promise<Record<string, unknown> | void>;
diff --git a/packages/contracts/src/replay.ts b/packages/contracts/src/replay.ts
index fab9e8d8c8..8ddd81e9c2 100644
--- a/packages/contracts/src/replay.ts
+++ b/packages/contracts/src/replay.ts
@@ -277,6 +277,11 @@ export type ReplayDispatchOptions = Readonly<{
   openLifecycle?: ReplayOpenLifecycle;
   /** Terminate the targeted app without ending the owning daemon session. */
   closeAppOnly?: boolean;
+  /**
+   * With `closeAppOnly`: Maestro `killApp` system-initiated process death
+   * (`am kill` on Android, `stopApp` alias elsewhere) instead of `stop`.
+   */
+  killApp?: boolean;
   /**
    * Daemon-composed hierarchy capture used as operational evidence only. It must not issue or
    * replace client ref authority.
diff --git a/packages/maestro/src/daemon-port/__tests__/daemon-runtime-port.test.ts b/packages/maestro/src/daemon-port/__tests__/daemon-runtime-port.test.ts
index dccc465176..c505138a71 100644
--- a/packages/maestro/src/daemon-port/__tests__/daemon-runtime-port.test.ts
+++ b/packages/maestro/src/daemon-port/__tests__/daemon-runtime-port.test.ts
@@ -173,6 +173,47 @@ test('projects standalone clearState to settings without opening the app', async
   ]);
 });
 
+test('projects standalone killApp to an app-only close carrying the kill mode', async () => {
+  const requests: MaestroDaemonOperationRequest[] = [];
+  const invoke: MaestroDaemonOperationInvoke = async (request) => {
+    requests.push(request);
+    return { ok: true, data: {} };
+  };
+  const port = createDaemonMaestroRuntimePort({
+    ...makeRuntimeEnvelope({ flags: { platform: 'android', replayBackend: 'maestro' } }),
+    invoke,
+    dependencies: makeDependencies(),
+    platform: 'android',
+  });
+
+  await port.execute({
+    command: { kind: 'killApp', source: { line: 2 }, appId: 'com.example.app' },
+    generation: 0,
+    env: {},
+    invalidateObservation() {},
+  });
+  await port.execute({
+    command: { kind: 'killApp', source: { line: 3 } },
+    generation: 1,
+    env: {},
+    appId: 'com.example.session',
+    invalidateObservation() {},
+  });
+
+  expect(requests).toEqual([
+    expect.objectContaining({
+      command: 'close',
+      positionals: ['com.example.app'],
+      dispatch: { closeAppOnly: true, killApp: true },
+    }),
+    expect.objectContaining({
+      command: 'close',
+      positionals: ['com.example.session'],
+      dispatch: { closeAppOnly: true, killApp: true },
+    }),
+  ]);
+});
+
 test('uses the direct viewport without snapshot and pairs it with the nested gesture request', async () => {
   const requests: MaestroDaemonOperationRequest[] = [];
   const viewport = { x: 10, y: 20, width: 400, height: 800 };
diff --git a/packages/maestro/src/daemon-port/__tests__/daemon-runtime-public-operation.test.ts b/packages/maestro/src/daemon-port/__tests__/daemon-runtime-public-operation.test.ts
index ad9409bf02..1f45660a6a 100644
--- a/packages/maestro/src/daemon-port/__tests__/daemon-runtime-public-operation.test.ts
+++ b/packages/maestro/src/daemon-port/__tests__/daemon-runtime-public-operation.test.ts
@@ -49,6 +49,22 @@ describe('Maestro public operation projection', () => {
       operation: { kind: 'stopApp' },
       expected: { command: 'close', positionals: [], dispatch: { closeAppOnly: true } },
     },
+    {
+      operation: { kind: 'killApp', appId: 'com.example' },
+      expected: {
+        command: 'close',
+        positionals: ['com.example'],
+        dispatch: { closeAppOnly: true, killApp: true },
+      },
+    },
+    {
+      operation: { kind: 'killApp' },
+      expected: {
+        command: 'close',
+        positionals: [],
+        dispatch: { closeAppOnly: true, killApp: true },
+      },
+    },
     {
       operation: { kind: 'clearState', appId: 'com.example' },
       expected: { command: 'settings', positionals: ['clear-app-state', 'com.example'] },
diff --git a/packages/maestro/src/daemon-port/daemon-runtime-port.ts b/packages/maestro/src/daemon-port/daemon-runtime-port.ts
index d2f8917c6a..65788203ff 100644
--- a/packages/maestro/src/daemon-port/daemon-runtime-port.ts
+++ b/packages/maestro/src/daemon-port/daemon-runtime-port.ts
@@ -189,6 +189,10 @@ function createDaemonMaestroRuntimeParts(options: CreateDaemonMaestroRuntimeOper
       const appId = input.appId ?? context.appId;
       await invokeMutation({ kind: 'stopApp', ...(appId ? { appId } : {}) }, context);
     },
+    killApp: async (input, context) => {
+      const appId = input.appId ?? context.appId;
+      await invokeMutation({ kind: 'killApp', ...(appId ? { appId } : {}) }, context);
+    },
     setPermissions: async (input, context) => {
       await applyPermissionMutations(
         input.appId ?? context.appId,
diff --git a/packages/maestro/src/daemon-port/daemon-runtime-public-operation.ts b/packages/maestro/src/daemon-port/daemon-runtime-public-operation.ts
index 9016723661..d30915bf52 100644
--- a/packages/maestro/src/daemon-port/daemon-runtime-public-operation.ts
+++ b/packages/maestro/src/daemon-port/daemon-runtime-public-operation.ts
@@ -21,6 +21,7 @@ export type MaestroPublicOperation =
       launchArgs: string[];
     }
   | { kind: 'stopApp'; appId?: string }
+  | { kind: 'killApp'; appId?: string }
   | { kind: 'clearState'; appId?: string }
   | {
       kind: 'settingsPermission';
@@ -53,6 +54,8 @@ export type MaestroPublicOperation =
 export type MaestroDaemonDispatchOptions = Readonly<{
   /** Terminate the targeted app without ending the owning daemon session. */
   closeAppOnly?: true;
+  /** With `closeAppOnly`: Maestro `killApp` process death (`am kill` on Android) instead of `stop`. */
+  killApp?: true;
   /** A hierarchy capture used as operational evidence only; it issues no client ref authority. */
   observationOnly?: true;
   /** Provider-owned viewport already resolved for a nested gesture command. */
@@ -88,12 +91,15 @@ export function projectMaestroPublicOperation(
 
 type MaestroAppOperation = Extract<
   MaestroPublicOperation,
-  { kind: 'launchApp' | 'stopApp' | 'openLink' }
+  { kind: 'launchApp' | 'stopApp' | 'killApp' | 'openLink' }
 >;
 
 function isAppOperation(operation: MaestroPublicOperation): operation is MaestroAppOperation {
   return (
-    operation.kind === 'launchApp' || operation.kind === 'stopApp' || operation.kind === 'openLink'
+    operation.kind === 'launchApp' ||
+    operation.kind === 'stopApp' ||
+    operation.kind === 'killApp' ||
+    operation.kind === 'openLink'
   );
 }
 
@@ -103,6 +109,8 @@ function projectAppOperation(operation: MaestroAppOperation): MaestroDaemonOpera
       return projectLaunchApp(operation);
     case 'stopApp':
       return projectStopApp(operation);
+    case 'killApp':
+      return projectKillApp(operation);
     case 'openLink':
       return projectOpenLink(operation);
   }
@@ -132,6 +140,16 @@ function projectStopApp(
   };
 }
 
+function projectKillApp(
+  operation: Extract<MaestroAppOperation, { kind: 'killApp' }>,
+): MaestroDaemonOperationRequest {
+  return {
+    command: 'close',
+    positionals: operation.appId ? [operation.appId] : [],
+    dispatch: { closeAppOnly: true, killApp: true },
+  };
+}
+
 function projectClearState(
   operation: Extract<MaestroPublicOperation, { kind: 'clearState' }>,
 ): MaestroDaemonOperationRequest {
diff --git a/packages/maestro/src/internal/__tests__/program-ir-parser.test.ts b/packages/maestro/src/internal/__tests__/program-ir-parser.test.ts
index 52dd72b9bb..090c3815c2 100644
--- a/packages/maestro/src/internal/__tests__/program-ir-parser.test.ts
+++ b/packages/maestro/src/internal/__tests__/program-ir-parser.test.ts
@@ -613,6 +613,27 @@ describe('parseMaestroProgram', () => {
     });
   });
 
+  test('parses standalone killApp with an explicit or config app id', () => {
+    const program = parseMaestroProgram(
+      `appId: example.app
+---
+- killApp: example.app
+- killApp
+`,
+      { sourcePath: '/flows/kill.yaml' },
+    );
+
+    assert.deepEqual(program.commands[0], {
+      kind: 'killApp',
+      source: { path: '/flows/kill.yaml', line: 3 },
+      appId: 'example.app',
+    });
+    assert.deepEqual(program.commands[1], {
+      kind: 'killApp',
+      source: { path: '/flows/kill.yaml', line: 4 },
+    });
+  });
+
   test('preserves source paths for unsupported and malformed flows', () => {
     const sourcePath = '/flows/includes/child.yaml';
     assert.throws(
diff --git a/packages/maestro/src/internal/__tests__/runtime-port-fixtures.ts b/packages/maestro/src/internal/__tests__/runtime-port-fixtures.ts
index 765892c9b2..b69da541af 100644
--- a/packages/maestro/src/internal/__tests__/runtime-port-fixtures.ts
+++ b/packages/maestro/src/internal/__tests__/runtime-port-fixtures.ts
@@ -59,6 +59,7 @@ export function makeOperations(
     resolveGestureViewport: async () => ({ x: 0, y: 0, width: 402, height: 874 }),
     launchApp: noOp,
     stopApp: noOp,
+    killApp: noOp,
     setPermissions: noOp,
     clearState: noOp,
     openLink: noOp,
diff --git a/packages/maestro/src/internal/__tests__/runtime-port.test.ts b/packages/maestro/src/internal/__tests__/runtime-port.test.ts
index 9da89973c2..24a684acdd 100644
--- a/packages/maestro/src/internal/__tests__/runtime-port.test.ts
+++ b/packages/maestro/src/internal/__tests__/runtime-port.test.ts
@@ -178,6 +178,25 @@ describe('MaestroRuntimePort', () => {
     expect(calls[1]).toMatchObject({ input: { appId: 'com.example.checkout' } });
   });
 
+  test('dispatches standalone killApp with an explicit or config app id', async () => {
+    const calls: RecordedCall[] = [];
+    const operations = makeOperations({
+      killApp: vi.fn(async (input, context) => record(calls, 'killApp', input, context)),
+    });
+    const program = parseMaestroProgram(
+      ['appId: com.example.checkout', '---', '- killApp: com.example.checkout', '- killApp'].join(
+        '\n',
+      ),
+    );
+
+    const result = await executeMaestroProgram(program, createMaestroRuntimePort(operations));
+
+    expect(result).toMatchObject({ executed: 2, skipped: 0 });
+    expect(calls.map(({ kind }) => kind)).toEqual(['killApp', 'killApp']);
+    expect(calls[0]).toMatchObject({ input: { appId: 'com.example.checkout' } });
+    expect(calls[1]).toMatchObject({ input: { appId: 'com.example.checkout' } });
+  });
+
   test('preserves observation validity after visual waits and scripts', async () => {
     const waitInvalidation = vi.fn();
     const scriptInvalidation = vi.fn();
diff --git a/packages/maestro/src/internal/conformance-normalize.ts b/packages/maestro/src/internal/conformance-normalize.ts
index 6d61c13be4..1d4993eacf 100644
--- a/packages/maestro/src/internal/conformance-normalize.ts
+++ b/packages/maestro/src/internal/conformance-normalize.ts
@@ -83,6 +83,7 @@ export type CanonicalCommand =
   | { kind: 'takeScreenshot' }
   | { kind: 'waitForAnimationToEnd'; timeout?: number | string }
   | { kind: 'stopApp' }
+  | { kind: 'killApp' }
   | { kind: 'setPermissions'; appId?: string; permissions?: Record<string, string> }
   | { kind: 'clearState'; appId?: string }
   | { kind: 'repeat'; times: string | number }
@@ -116,6 +117,8 @@ function canonicalizeUpstreamLifecycleCommand(
       });
     case 'StopAppCommand':
       return { kind: 'stopApp' };
+    case 'KillAppCommand':
+      return { kind: 'killApp' };
     case 'ClearStateCommand':
       return dropUndefined({ kind: 'clearState' as const, appId: str(f.appId) });
     default:
@@ -367,7 +370,7 @@ type AgentLifecycleCommand = Extract<
   { kind: (typeof AGENT_LIFECYCLE_KINDS)[number] }
 >;
 
-const AGENT_LIFECYCLE_KINDS = ['launchApp', 'stopApp', 'clearState'] as const;
+const AGENT_LIFECYCLE_KINDS = ['launchApp', 'stopApp', 'killApp', 'clearState'] as const;
 
 function isAgentLifecycleCommand(command: MaestroCommand): command is AgentLifecycleCommand {
   return (AGENT_LIFECYCLE_KINDS as readonly string[]).includes(command.kind);
@@ -388,6 +391,8 @@ function canonicalizeAgentLifecycleCommand(
       });
     case 'stopApp':
       return { kind: 'stopApp' };
+    case 'killApp':
+      return { kind: 'killApp' };
     case 'clearState':
       return dropUndefined({ kind: 'clearState', appId: command.appId ?? config.appId });
   }
diff --git a/packages/maestro/src/internal/program-ir-command-parser.ts b/packages/maestro/src/internal/program-ir-command-parser.ts
index f1d797c950..a2b6a3dc4d 100644
--- a/packages/maestro/src/internal/program-ir-command-parser.ts
+++ b/packages/maestro/src/internal/program-ir-command-parser.ts
@@ -10,6 +10,7 @@ import type {
   MaestroExtendedWaitUntilCommand,
   MaestroHideKeyboardCommand,
   MaestroInputTextCommand,
+  MaestroKillAppCommand,
   MaestroLaunchAppCommand,
   MaestroLaunchArguments,
   MaestroOpenLinkCommand,
@@ -127,6 +128,7 @@ const COMMAND_VALUE_PARSERS: Readonly<Record<string, CommandValueParser>> = {
   back: parseBack,
   waitForAnimationToEnd: parseWaitForAnimationToEnd,
   stopApp: parseStopApp,
+  killApp: parseKillApp,
   setPermissions: parseSetPermissions,
   clearState: parseClearState,
   runScript: parseMaestroRunScriptCommand,
@@ -459,6 +461,16 @@ function parseStopApp(
   return { kind: 'stopApp', source, appId: readRequiredString(value, 'stopApp', context) };
 }
 
+function parseKillApp(
+  value: Node | null,
+  commandNode: Node,
+  context: MaestroProgramParseContext,
+): MaestroKillAppCommand {
+  const source = sourceAt(commandNode, context);
+  if (isNullNode(value)) return { kind: 'killApp', source };
+  return { kind: 'killApp', source, appId: readRequiredString(value, 'killApp', context) };
+}
+
 function parseSetPermissions(
   value: Node | null,
   commandNode: Node,
diff --git a/packages/maestro/src/internal/program-ir.ts b/packages/maestro/src/internal/program-ir.ts
index d8020097ee..0798618c5d 100644
--- a/packages/maestro/src/internal/program-ir.ts
+++ b/packages/maestro/src/internal/program-ir.ts
@@ -208,6 +208,12 @@ export type MaestroStopAppCommand = {
   appId?: string;
 };
 
+export type MaestroKillAppCommand = {
+  kind: 'killApp';
+  source: MaestroSourceLocation;
+  appId?: string;
+};
+
 export type MaestroSetPermissionsCommand = MaestroOptionalCommand & {
   kind: 'setPermissions';
   source: MaestroSourceLocation;
@@ -286,6 +292,7 @@ export type MaestroCommand =
   | MaestroBackCommand
   | MaestroWaitForAnimationToEndCommand
   | MaestroStopAppCommand
+  | MaestroKillAppCommand
   | MaestroSetPermissionsCommand
   | MaestroClearStateCommand
   | MaestroRunScriptCommand
diff --git a/packages/maestro/src/internal/runtime-port-commands.ts b/packages/maestro/src/internal/runtime-port-commands.ts
index cb4fafb422..e398600ee1 100644
--- a/packages/maestro/src/internal/runtime-port-commands.ts
+++ b/packages/maestro/src/internal/runtime-port-commands.ts
@@ -30,7 +30,7 @@ type MaestroCommandOf<K extends MaestroRuntimeCommand['kind']> = Extract<
 >;
 
 type MaestroLifecycleCommand = MaestroCommandOf<
-  'launchApp' | 'stopApp' | 'setPermissions' | 'clearState' | 'openLink'
+  'launchApp' | 'stopApp' | 'killApp' | 'setPermissions' | 'clearState' | 'openLink'
 >;
 type MaestroTargetCommand = MaestroCommandOf<'tapOn' | 'doubleTapOn' | 'longPressOn'>;
 type MaestroTextCommand = MaestroCommandOf<'inputText' | 'eraseText'>;
@@ -55,6 +55,7 @@ type MaestroRuntimeCommandHandlers = {
 const MAESTRO_RUNTIME_COMMAND_HANDLERS = {
   launchApp: executeLifecycleCommand,
   stopApp: executeLifecycleCommand,
+  killApp: executeLifecycleCommand,
   setPermissions: executeLifecycleCommand,
   clearState: executeLifecycleCommand,
   openLink: executeLifecycleCommand,
@@ -82,6 +83,7 @@ const MAESTRO_RUNTIME_COMMAND_HANDLERS = {
 const MAESTRO_COMMAND_REQUIRES_SETTLED_PREDECESSOR = {
   launchApp: true,
   stopApp: true,
+  killApp: true,
   setPermissions: true,
   clearState: true,
   openLink: true,
@@ -150,6 +152,13 @@ async function executeLifecycleCommand(
         context,
         'invalidate',
       );
+    case 'killApp':
+      return await invokeOperation(
+        operations.killApp,
+        { appId: command.appId ?? request.appId },
+        context,
+        'invalidate',
+      );
     case 'setPermissions':
       return await invokeOperation(
         operations.setPermissions,
diff --git a/packages/maestro/src/internal/runtime-port-types.ts b/packages/maestro/src/internal/runtime-port-types.ts
index 4c82492049..924468a460 100644
--- a/packages/maestro/src/internal/runtime-port-types.ts
+++ b/packages/maestro/src/internal/runtime-port-types.ts
@@ -124,6 +124,7 @@ export type MaestroRuntimeOperations = {
     readonly launchArguments?: MaestroLaunchArguments;
   }>;
   readonly stopApp: MaestroRuntimeOperation<{ readonly appId?: string }>;
+  readonly killApp: MaestroRuntimeOperation<{ readonly appId?: string }>;
   readonly setPermissions: MaestroRuntimeOperation<{
     readonly appId?: string;
     readonly permissions: Readonly<Record<string, string>>;
diff --git a/packages/maestro/src/internal/support-matrix.ts b/packages/maestro/src/internal/support-matrix.ts
index a58f2bcff7..dd265a7eaf 100644
--- a/packages/maestro/src/internal/support-matrix.ts
+++ b/packages/maestro/src/internal/support-matrix.ts
@@ -1,7 +1,7 @@
 export const MAESTRO_COMPAT_SUPPORTED_CAPABILITIES = [
   'Flows: launchApp (with clearState, permissions, and Apple-only launch arguments; permissions apply after state clearing but before launch, and a launchApp without permissions touches nothing — there is no silent all: allow default); setPermissions (mid-flow permission grants, denials, and resets; all resolves in the backend — one simctl call on iOS, the declared permissions on Android — with specific entries overriding after it); runFlow file/inline with platform, visibility, and limited boolean conditions; onFlowStart/onFlowComplete; repeat.times and retry.',
   'Interactions: tapOn, doubleTapOn, longPressOn, inputText on the focused element, eraseText, openLink, hideKeyboard, basic pressKey, and back; selector targets poll until available and support recursive index, childOf, above, below, leftOf, rightOf, containsChild, containsDescendants, points, and optional; outer command labels are metadata, not target selectors.',
-  'Assertions and navigation: assertVisible, assertNotVisible, assertTrue (literal values and ${VAR} lookups only; "", "false", "0", "null", and "undefined" are falsy, everything else is truthy), extendedWaitUntil, scroll, scrollUntilVisible, absolute/percentage/target swipe, takeScreenshot, waitForAnimationToEnd, clearState, and stopApp.',
+  'Assertions and navigation: assertVisible, assertNotVisible, assertTrue (literal values and ${VAR} lookups only; "", "false", "0", "null", and "undefined" are falsy, everything else is truthy), extendedWaitUntil, scroll, scrollUntilVisible, absolute/percentage/target swipe, takeScreenshot, waitForAnimationToEnd, clearState, stopApp, and killApp (system-initiated process death: am kill on Android, stopApp alias elsewhere).',
   'Scripts: ordered runScript file/env scripts with http.post, json, and output variables; evalScript inline expressions run flow-scoped JavaScript and write output.* leaves for later steps.',
 ] as const;
 
diff --git a/packages/maestro/test/conformance/expected-divergence.ts b/packages/maestro/test/conformance/expected-divergence.ts
index 52f96e4fc1..6d7a2e3997 100644
--- a/packages/maestro/test/conformance/expected-divergence.ts
+++ b/packages/maestro/test/conformance/expected-divergence.ts
@@ -48,11 +48,6 @@ export const FLOW_DIVERGENCES: Record<string, FlowDivergence> = {
     reason: 'travel is outside the supported subset.',
     unsupported: ['travel'],
   },
-  'upstream/116_kill_app': {
-    classification: 'we-reject',
-    reason: 'Standalone killApp is outside the supported subset.',
-    unsupported: ['killApp'],
-  },
   // --- Deliberately stricter than upstream ---
   'invalid/duplicate-keys': {
     classification: 'we-reject',
diff --git a/packages/platform-android/src/__tests__/app-lifecycle-open.test.ts b/packages/platform-android/src/__tests__/app-lifecycle-open.test.ts
index 1abced327e..78b92e563a 100644
--- a/packages/platform-android/src/__tests__/app-lifecycle-open.test.ts
+++ b/packages/platform-android/src/__tests__/app-lifecycle-open.test.ts
@@ -1,6 +1,6 @@
 import { test } from 'vitest';
 import assert from 'node:assert/strict';
-import { closeAndroidApp, openAndroidApp } from '../app-lifecycle.ts';
+import { closeAndroidApp, killAndroidApp, openAndroidApp } from '../app-lifecycle.ts';
 import { withAndroidAdbProvider } from '../adb-executor.ts';
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import { AppError } from '@agent-device/kernel/errors';
@@ -162,6 +162,47 @@ test('closeAndroidApp waits until package process exits after force-stop', async
   ]);
 });
 
+test('killAndroidApp dispatches am kill rather than am force-stop', async () => {
+  const device: DeviceInfo = {
+    platform: 'android',
+    id: 'emulator-5554',
+    name: 'Pixel',
+    kind: 'emulator',
+    booted: true,
+  };
+  const calls: (readonly string[])[] = [];
+
+  await withAndroidAdbProvider(
+    {
+      exec: async (args) => {
+        calls.push(args);
+        if (args.join(' ') === 'shell dumpsys window windows') {
+          return {
+            stdout: 'mCurrentFocus=Window{43 u0 com.android.launcher/.Launcher}\n',
+            stderr: '',
+            exitCode: 0,
+          };
+        }
+        return { stdout: '', stderr: '', exitCode: 0 };
+      },
+      reverse: {
+        ensure: async () => {},
+        remove: async () => {},
+        removeAllOwned: async () => {},
+      },
+    },
+    { serial: 'emulator-5554' },
+    async () => await killAndroidApp(device, 'com.example.app'),
+  );
+
+  assert.deepEqual(calls, [
+    ['shell', 'am', 'kill', 'com.example.app'],
+    ['shell', 'dumpsys', 'window', 'windows'],
+    ['shell', 'pidof', 'com.example.app'],
+    ['shell', 'pidof', 'com.example.app'],
+  ]);
+});
+
 test('openAndroidApp ensures Android reverse before localhost deep link launch', async () => {
   const device: DeviceInfo = {
     platform: 'android',
diff --git a/packages/platform-android/src/app-lifecycle.ts b/packages/platform-android/src/app-lifecycle.ts
index c5880ce5fb..c02cb89c0d 100644
--- a/packages/platform-android/src/app-lifecycle.ts
+++ b/packages/platform-android/src/app-lifecycle.ts
@@ -488,6 +488,26 @@ export async function closeAndroidApp(device: DeviceInfo, app: string): Promise<
   await waitForAndroidPackageStopped(device, resolved.value);
 }
 
+/**
+ * Maestro `killApp` on Android: system-initiated process death (`am kill`),
+ * which only reaps a backgrounded/cached process — unlike `closeAndroidApp`'s
+ * `am force-stop`. Callers background the app first (e.g. `pressKey: Home`).
+ */
+export async function killAndroidApp(device: DeviceInfo, app: string): Promise<void> {
+  const trimmed = app.trim();
+  if (trimmed.toLowerCase() === 'settings') {
+    await runAndroidShell(device, ['am', 'kill', 'com.android.settings']);
+    await waitForAndroidPackageStopped(device, 'com.android.settings');
+    return;
+  }
+  const resolved = await resolveAndroidApp(device, app);
+  if (resolved.type === 'intent') {
+    throw new AppError('INVALID_ARGS', 'Kill requires a package name, not an intent');
+  }
+  await runAndroidShell(device, ['am', 'kill', resolved.value]);
+  await waitForAndroidPackageStopped(device, resolved.value);
+}
+
 async function waitForAndroidPackageStopped(
   device: DeviceInfo,
   packageName: string,
diff --git a/packages/platform-android/src/lifecycle.ts b/packages/platform-android/src/lifecycle.ts
index cab32f52f6..912c0dc606 100644
--- a/packages/platform-android/src/lifecycle.ts
+++ b/packages/platform-android/src/lifecycle.ts
@@ -67,6 +67,7 @@ export function bindAndroidApplicationLifecycle(
         device,
         interactor: await binding.resolveInteractor(input.execution, input.appBundleId),
         positionals: input.positionals,
+        mode: input.mode,
       });
     },
     finalizeApplicationClose: async (input) => {
diff --git a/packages/platform-android/src/mechanics.ts b/packages/platform-android/src/mechanics.ts
index 96efabf755..43b5dfa3f9 100644
--- a/packages/platform-android/src/mechanics.ts
+++ b/packages/platform-android/src/mechanics.ts
@@ -83,6 +83,7 @@ export async function listAndroidAppsWithAdb(
 export {
   closeAndroidApp,
   isAmStartError,
+  killAndroidApp,
   openAndroidApp,
   openAndroidDevice,
   parseAndroidLaunchComponent,
diff --git a/scripts/fuzz/validation-arbitraries-maestro.ts b/scripts/fuzz/validation-arbitraries-maestro.ts
index 1507debbcc..6b47745bb7 100644
--- a/scripts/fuzz/validation-arbitraries-maestro.ts
+++ b/scripts/fuzz/validation-arbitraries-maestro.ts
@@ -22,6 +22,8 @@ function validMaestroCommand(pick: number, salt: number): string[] {
     () => ['- back'],
     () => ['- hideKeyboard'],
     () => ['- stopApp'],
+    () => ['- killApp'],
+    () => [`- killApp: ${text}`],
     () => ['- clearState'],
     () => [`- clearState: ${text}`],
     () => ['- scroll'],
diff --git a/src/core/interactors/android.ts b/src/core/interactors/android.ts
index fff5d3f126..b52c1917d5 100644
--- a/src/core/interactors/android.ts
+++ b/src/core/interactors/android.ts
@@ -11,6 +11,7 @@ import {
   getAndroidKeyboardState,
   handleAndroidAlert,
   homeAndroid,
+  killAndroidApp,
   longPressAndroid,
   openAndroidApp,
   openAndroidDevice,
@@ -69,6 +70,7 @@ export function createAndroidInteractor(
       }),
     openDevice: () => openAndroidDevice(device),
     close: (app) => closeAndroidApp(device, app),
+    kill: (app) => killAndroidApp(device, app),
     tap: (x, y) => pressAndroid(device, x, y),
     doubleTap: async (x, y) => {
       await pressAndroid(device, x, y);
diff --git a/src/daemon/replay/internal/__tests__/session-replay-maestro-request.test.ts b/src/daemon/replay/internal/__tests__/session-replay-maestro-request.test.ts
index 8102fab292..df2948d92a 100644
--- a/src/daemon/replay/internal/__tests__/session-replay-maestro-request.test.ts
+++ b/src/daemon/replay/internal/__tests__/session-replay-maestro-request.test.ts
@@ -102,6 +102,19 @@ test('folds Maestro settings app targeting into dispatch', () => {
   expect(request.dispatch).toEqual({ settingsAppBundleId: 'com.example.app' });
 });
 
+test('folds Maestro killApp targeting into dispatch', () => {
+  const request = maestroOperationDispatchRequest(
+    { token: 'token', session: 'session', command: 'replay', positionals: [] },
+    {
+      command: 'close',
+      positionals: ['com.example.app'],
+      dispatch: { closeAppOnly: true, killApp: true },
+    },
+  );
+
+  expect(request.dispatch).toEqual({ closeAppOnly: true, killApp: true });
+});
+
 test('leaves dispatch options the operation does not set untouched', () => {
   const viewport = { x: 0, y: 0, width: 402, height: 874 };
   const request = maestroOperationDispatchRequest(
diff --git a/src/daemon/replay/internal/session-replay-maestro-request.ts b/src/daemon/replay/internal/session-replay-maestro-request.ts
index a95e077f2d..5aefbf320a 100644
--- a/src/daemon/replay/internal/session-replay-maestro-request.ts
+++ b/src/daemon/replay/internal/session-replay-maestro-request.ts
@@ -39,6 +39,7 @@ function maestroDispatchOptions(
 ): Pick<ReplayDispatchOptions, keyof MaestroDaemonDispatchOptions> {
   return stripUndefined({
     closeAppOnly: dispatch?.closeAppOnly,
+    killApp: dispatch?.killApp,
     observationOnly: dispatch?.observationOnly,
     gestureViewport: dispatch?.gestureViewport,
     gestureExecutionProfile: dispatch?.gestureExecutionProfile,
diff --git a/src/daemon/session-lifecycle/internal/__tests__/session-close-lifecycle-runtime.test.ts b/src/daemon/session-lifecycle/internal/__tests__/session-close-lifecycle-runtime.test.ts
index 7ca47b926c..dcfc5631a6 100644
--- a/src/daemon/session-lifecycle/internal/__tests__/session-close-lifecycle-runtime.test.ts
+++ b/src/daemon/session-lifecycle/internal/__tests__/session-close-lifecycle-runtime.test.ts
@@ -319,6 +319,56 @@ test('a supported Android close clears admitted runtime hints exactly once', asy
   );
 });
 
+test('an app-only kill close carries mode kill while a stop close carries none', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'android-app-only-kill-carries-mode';
+  const device = {
+    platform: 'android' as const,
+    id: 'emulator-5554',
+    name: 'Pixel',
+    kind: 'emulator' as const,
+    target: 'mobile' as const,
+    booted: true,
+  };
+  const session = makeSession(sessionName, device);
+  session.appBundleId = 'com.example.app';
+  sessionStore.set(sessionName, session);
+  const seenModes: Array<unknown> = [];
+  const baseBind = mockBindDeviceRuntime.getMockImplementation();
+  mockBindDeviceRuntime.mockImplementation(async (boundDevice, use) => {
+    const binding = await baseBind!(boundDevice, use);
+    const innerClose = binding.operations.closeApplication;
+    if (!innerClose) return binding;
+    return {
+      ...binding,
+      operations: {
+        ...binding.operations,
+        closeApplication: async (input: Parameters<typeof innerClose>[0]) => {
+          seenModes.push(input.mode);
+          return await innerClose(input);
+        },
+      },
+    };
+  });
+
+  const killed = await close({
+    sessionName,
+    sessionStore,
+    positionals: ['com.example.app'],
+    internal: { closeAppOnly: true, killApp: true },
+  });
+  const stopped = await close({
+    sessionName,
+    sessionStore,
+    positionals: ['com.example.app'],
+    internal: { closeAppOnly: true },
+  });
+
+  expect(killed?.ok).toBe(true);
+  expect(stopped?.ok).toBe(true);
+  expect(seenModes).toEqual(['kill', undefined]);
+});
+
 test('close expires the ref frame immediately before its admitted platform mutation', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'close-ref-frame-seam';
diff --git a/src/daemon/session-lifecycle/internal/session-close.ts b/src/daemon/session-lifecycle/internal/session-close.ts
index da1bd016e5..924a04a64a 100644
--- a/src/daemon/session-lifecycle/internal/session-close.ts
+++ b/src/daemon/session-lifecycle/internal/session-close.ts
@@ -149,6 +149,7 @@ async function dispatchTargetedPlatformClose(params: {
       outPath: req.flags?.out,
       appBundleId: session.appBundleId,
       surface: session.surface ?? 'app',
+      ...(req.internal?.killApp === true ? { mode: 'kill' as const } : {}),
       execution: applicationLifecycleExecutionFromRequest(req, logPath, session.trace?.outPath),
     });
     return undefined;
diff --git a/website/docs/docs/replay-e2e.md b/website/docs/docs/replay-e2e.md
index 304ec141da..e86b3f66db 100644
--- a/website/docs/docs/replay-e2e.md
+++ b/website/docs/docs/replay-e2e.md
@@ -72,7 +72,7 @@ Supported subset:
 
 - Flows: `launchApp` (with `clearState`, `permissions`, and Apple-only launch arguments; `permissions` apply after state clearing but before launch, and a `launchApp` without `permissions` touches nothing — there is no silent `all: allow` default); `setPermissions` (mid-flow permission grants, denials, and resets; `all` resolves in the backend — one simctl call on iOS, the declared permissions on Android — with specific entries overriding after it); `runFlow` file/inline with platform, visibility, and limited boolean conditions; `onFlowStart`/`onFlowComplete`; `repeat.times` and retry.
 - Interactions: `tapOn`, `doubleTapOn`, `longPressOn`, `inputText` on the focused element, `eraseText`, `openLink`, `hideKeyboard`, basic `pressKey`, and `back`; selector targets poll until available and support recursive `index`, `childOf`, `above`, `below`, `leftOf`, `rightOf`, `containsChild`, `containsDescendants`, points, and `optional`; outer command labels are metadata, not target selectors.
-- Assertions and navigation: `assertVisible`, `assertNotVisible`, `assertTrue` (literal values and `${VAR}` lookups only; `""`, `"false"`, `"0"`, `"null"`, and `"undefined"` are falsy, everything else is truthy), `extendedWaitUntil`, `scroll`, `scrollUntilVisible`, absolute/percentage/target `swipe`, `takeScreenshot`, `waitForAnimationToEnd`, `clearState`, and `stopApp`.
+- Assertions and navigation: `assertVisible`, `assertNotVisible`, `assertTrue` (literal values and `${VAR}` lookups only; `""`, `"false"`, `"0"`, `"null"`, and `"undefined"` are falsy, everything else is truthy), `extendedWaitUntil`, `scroll`, `scrollUntilVisible`, absolute/percentage/target `swipe`, `takeScreenshot`, `waitForAnimationToEnd`, `clearState`, `stopApp`, and `killApp` (system-initiated process death: `am kill` on Android, `stopApp` alias elsewhere).
 - Scripts: ordered `runScript` file/env scripts with `http.post`, `json`, and `output` variables; `evalScript` inline expressions run flow-scoped JavaScript and write `output.*` leaves for later steps.
 
 Boundaries:

From 369a51b35a8846983d4055658a73f4a075ec2cef Mon Sep 17 00:00:00 2001
From: Rohit <40559587+Rohit3523@users.noreply.github.com>
Date: Tue, 22 Sep 2026 03:34:43 +0530
Subject: [PATCH 002/132] refactor(maestro): table-drive app-target lifecycle
 dispatch

executeLifecycleCommand grew a sixth case for killApp and tripped the
complexity gate. The stopApp/killApp/clearState legs share one shape,
so dispatch them through a lookup instead of three switch cases.
---
 .../src/internal/runtime-port-commands.ts     | 39 +++++++++----------
 1 file changed, 19 insertions(+), 20 deletions(-)

diff --git a/packages/maestro/src/internal/runtime-port-commands.ts b/packages/maestro/src/internal/runtime-port-commands.ts
index e398600ee1..7c71f57124 100644
--- a/packages/maestro/src/internal/runtime-port-commands.ts
+++ b/packages/maestro/src/internal/runtime-port-commands.ts
@@ -131,6 +131,19 @@ function dispatchMaestroRuntimeCommand<K extends MaestroCommandKind>(
   return handler(command, request, operations, context);
 }
 
+type MaestroAppTargetLifecycleCommand = MaestroCommandOf<'stopApp' | 'killApp' | 'clearState'>;
+
+/** Lifecycle commands carrying only an app target share one dispatch shape. */
+const MAESTRO_APP_TARGET_OPERATIONS: {
+  [K in MaestroAppTargetLifecycleCommand['kind']]: (
+    operations: MaestroRuntimeOperations,
+  ) => MaestroRuntimeOperations[K];
+} = {
+  stopApp: (operations) => operations.stopApp,
+  killApp: (operations) => operations.killApp,
+  clearState: (operations) => operations.clearState,
+};
+
 async function executeLifecycleCommand(
   command: MaestroLifecycleCommand,
   request: MaestroRuntimeRequest,
@@ -145,20 +158,6 @@ async function executeLifecycleCommand(
         context,
         'invalidate',
       );
-    case 'stopApp':
-      return await invokeOperation(
-        operations.stopApp,
-        { appId: command.appId ?? request.appId },
-        context,
-        'invalidate',
-      );
-    case 'killApp':
-      return await invokeOperation(
-        operations.killApp,
-        { appId: command.appId ?? request.appId },
-        context,
-        'invalidate',
-      );
     case 'setPermissions':
       return await invokeOperation(
         operations.setPermissions,
@@ -169,17 +168,17 @@ async function executeLifecycleCommand(
         context,
         'invalidate',
       );
-    case 'clearState':
+    case 'openLink':
       return await invokeOperation(
-        operations.clearState,
-        { appId: command.appId ?? request.appId },
+        operations.openLink,
+        { link: command.link },
         context,
         'invalidate',
       );
-    case 'openLink':
+    default:
       return await invokeOperation(
-        operations.openLink,
-        { link: command.link },
+        MAESTRO_APP_TARGET_OPERATIONS[command.kind](operations),
+        { appId: command.appId ?? request.appId },
         context,
         'invalidate',
       );

From 78727e3f1dac3be6c25c45faabcc2eec510dcf95 Mon Sep 17 00:00:00 2001
From: Rohit <40559587+Rohit3523@users.noreply.github.com>
Date: Tue, 22 Sep 2026 03:43:30 +0530
Subject: [PATCH 003/132] fix(maestro): fail killApp loud when the target
 survives

am kill only reaps background processes, so a foreground killApp used
to succeed without killing anything. Refuse a foreground target naming
the background-first precondition, and verify the process is gone after
the kill instead of reporting an unproven success.
---
 .../src/__tests__/app-lifecycle-open.test.ts  | 95 +++++++++++++++++++
 .../platform-android/src/app-lifecycle.ts     | 26 ++++-
 2 files changed, 117 insertions(+), 4 deletions(-)

diff --git a/packages/platform-android/src/__tests__/app-lifecycle-open.test.ts b/packages/platform-android/src/__tests__/app-lifecycle-open.test.ts
index 78b92e563a..ac270f8fe5 100644
--- a/packages/platform-android/src/__tests__/app-lifecycle-open.test.ts
+++ b/packages/platform-android/src/__tests__/app-lifecycle-open.test.ts
@@ -196,13 +196,108 @@ test('killAndroidApp dispatches am kill rather than am force-stop', async () =>
   );
 
   assert.deepEqual(calls, [
+    ['shell', 'dumpsys', 'window', 'windows'],
     ['shell', 'am', 'kill', 'com.example.app'],
     ['shell', 'dumpsys', 'window', 'windows'],
     ['shell', 'pidof', 'com.example.app'],
     ['shell', 'pidof', 'com.example.app'],
+    ['shell', 'pidof', 'com.example.app'],
   ]);
 });
 
+test('killAndroidApp refuses a foreground target before killing', async () => {
+  const device: DeviceInfo = {
+    platform: 'android',
+    id: 'emulator-5554',
+    name: 'Pixel',
+    kind: 'emulator',
+    booted: true,
+  };
+  const calls: (readonly string[])[] = [];
+
+  await withAndroidAdbProvider(
+    {
+      exec: async (args) => {
+        calls.push(args);
+        if (args.join(' ') === 'shell dumpsys window windows') {
+          return {
+            stdout: 'mCurrentFocus=Window{42 u0 com.example.app/.MainActivity}\n',
+            stderr: '',
+            exitCode: 0,
+          };
+        }
+        return { stdout: '', stderr: '', exitCode: 0 };
+      },
+      reverse: {
+        ensure: async () => {},
+        remove: async () => {},
+        removeAllOwned: async () => {},
+      },
+    },
+    { serial: 'emulator-5554' },
+    async () => {
+      await assertRejectsAppError(() => killAndroidApp(device, 'com.example.app'), {
+        code: 'COMMAND_FAILED',
+        hint: /Background the app before killApp/,
+      });
+      try {
+        await killAndroidApp(device, 'com.example.app');
+        assert.fail('expected killAndroidApp to reject for a foreground app');
+      } catch (error) {
+        assert.equal(
+          (error as InstanceType<typeof AppError>).details?.reason,
+          'android-kill-requires-background-app',
+        );
+      }
+    },
+  );
+
+  assert.deepEqual(calls, [
+    ['shell', 'dumpsys', 'window', 'windows'],
+    ['shell', 'dumpsys', 'window', 'windows'],
+  ]);
+});
+
+test('killAndroidApp fails when the process survives the kill', async () => {
+  const device: DeviceInfo = {
+    platform: 'android',
+    id: 'emulator-5554',
+    name: 'Pixel',
+    kind: 'emulator',
+    booted: true,
+  };
+
+  await withAndroidAdbProvider(
+    {
+      exec: async (args) => {
+        if (args.join(' ') === 'shell dumpsys window windows') {
+          return {
+            stdout: 'mCurrentFocus=Window{43 u0 com.android.launcher/.Launcher}\n',
+            stderr: '',
+            exitCode: 0,
+          };
+        }
+        if (args.join(' ') === 'shell pidof com.example.app') {
+          return { stdout: '12345\n', stderr: '', exitCode: 0 };
+        }
+        return { stdout: '', stderr: '', exitCode: 0 };
+      },
+      reverse: {
+        ensure: async () => {},
+        remove: async () => {},
+        removeAllOwned: async () => {},
+      },
+    },
+    { serial: 'emulator-5554' },
+    async () => {
+      await assertRejectsAppError(() => killAndroidApp(device, 'com.example.app'), {
+        code: 'COMMAND_FAILED',
+        hint: /Background the app before killApp/,
+      });
+    },
+  );
+});
+
 test('openAndroidApp ensures Android reverse before localhost deep link launch', async () => {
   const device: DeviceInfo = {
     platform: 'android',
diff --git a/packages/platform-android/src/app-lifecycle.ts b/packages/platform-android/src/app-lifecycle.ts
index c02cb89c0d..6b3072fb05 100644
--- a/packages/platform-android/src/app-lifecycle.ts
+++ b/packages/platform-android/src/app-lifecycle.ts
@@ -492,20 +492,38 @@ export async function closeAndroidApp(device: DeviceInfo, app: string): Promise<
  * Maestro `killApp` on Android: system-initiated process death (`am kill`),
  * which only reaps a backgrounded/cached process — unlike `closeAndroidApp`'s
  * `am force-stop`. Callers background the app first (e.g. `pressKey: Home`).
+ * A foreground target fails loud naming the precondition, and a process that
+ * survives the kill fails rather than reading as success.
  */
 export async function killAndroidApp(device: DeviceInfo, app: string): Promise<void> {
   const trimmed = app.trim();
   if (trimmed.toLowerCase() === 'settings') {
-    await runAndroidShell(device, ['am', 'kill', 'com.android.settings']);
-    await waitForAndroidPackageStopped(device, 'com.android.settings');
+    await killAndroidPackage(device, 'com.android.settings');
     return;
   }
   const resolved = await resolveAndroidApp(device, app);
   if (resolved.type === 'intent') {
     throw new AppError('INVALID_ARGS', 'Kill requires a package name, not an intent');
   }
-  await runAndroidShell(device, ['am', 'kill', resolved.value]);
-  await waitForAndroidPackageStopped(device, resolved.value);
+  await killAndroidPackage(device, resolved.value);
+}
+
+async function killAndroidPackage(device: DeviceInfo, packageName: string): Promise<void> {
+  const foreground = await readAndroidForegroundApp(device);
+  if (foreground?.package === packageName) {
+    throw new AppError('COMMAND_FAILED', `Cannot kill foreground app ${packageName}`, {
+      reason: 'android-kill-requires-background-app',
+      hint: 'Background the app before killApp (for example pressKey: Home): am kill only reaps background processes.',
+    });
+  }
+  await runAndroidShell(device, ['am', 'kill', packageName]);
+  await waitForAndroidPackageStopped(device, packageName);
+  if (await isAndroidPackageProcessRunning(device, packageName)) {
+    throw new AppError('COMMAND_FAILED', `am kill did not stop ${packageName}`, {
+      reason: 'android-kill-requires-background-app',
+      hint: 'Background the app before killApp (for example pressKey: Home): am kill only reaps background processes.',
+    });
+  }
 }
 
 async function waitForAndroidPackageStopped(

From 690313034532600aab6696a8d234423b6f7fc308 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Tue, 22 Sep 2026 07:45:08 +0200
Subject: [PATCH 004/132] fix(ios): serve a simulator recording whose recorder
 died with its daemon (#2736)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(ios): serve a simulator recording whose recorder died with its daemon

A simctl reattach answered `missing` as soon as the recorder process was gone,
which is the ordinary state after daemon loss, so a retried `record stop` threw
`resource-missing` forever even with the recorder's video on disk. The simctl
descriptor now carries the caller-facing export coordinates, so a proven-gone
recorder whose file still passes the container sniff reattaches as a handle that
runs the same stop-and-export sequence the live recording would have run, and
discloses the touch overlay whose events did not survive the daemon.

A manifest written without those coordinates is answered exactly as it was
before, because it cannot name an export it never recorded.

* fix(ios): resume a recovered simulator export from what the first stop journaled

A recorder that died with its daemon proved nothing about the export its file can
still become, and neither did a manifest whose stop had already collected a copy or
journaled a finalization. Reattach decided from the recorder's own path alone, so a
retry after those steps found no file there and reported a loss the manifest
contradicted. It now asks what a resumed stop would still have to read, which the
shared stop sequence answers from the checkpoints the first attempt wrote.

The coordinates a recovered export needs are the caller-facing keys of the live
snapshot, so the facet is a Pick of it, encoded and restored by spread, and validated
by the recording-facts validator Android's descriptor already needed — moved to
capture-kit so both backends answer with the same strictness. A recovered handle
refuses an overlay whose gesture events died with the daemon instead of running the
overlay pass with nothing to burn in and then reporting it unavailable.

* chore(gates): declare the capture-kit recording-facts subpath in the boundary enumeration
---
 packages/capture-kit/package.json             |   4 +
 .../src/recording/recording-facts.test.ts     |  47 +++
 .../src/recording/recording-facts.ts          |  56 ++++
 .../src/recording/stop-sequence.ts            |   7 +
 .../src/recording/manifest-validation.ts      |  46 +--
 .../src/recording/completion.ts               |  14 +-
 .../src/recording/recovery.test.ts            | 233 ++++++++++++++
 .../platform-apple/src/recording/recovery.ts  | 292 +++++++++++++++---
 .../src/recording/runtime.fixtures.ts         |  21 +-
 .../platform-apple/src/recording/runtime.ts   |  97 +++++-
 scripts/layering/package-boundaries.test.ts   |   1 +
 11 files changed, 724 insertions(+), 94 deletions(-)
 create mode 100644 packages/capture-kit/src/recording/recording-facts.test.ts
 create mode 100644 packages/capture-kit/src/recording/recording-facts.ts

diff --git a/packages/capture-kit/package.json b/packages/capture-kit/package.json
index 05346e4968..139662c3d2 100644
--- a/packages/capture-kit/package.json
+++ b/packages/capture-kit/package.json
@@ -166,6 +166,10 @@
       "types": "./src/recording/artifact.fixtures.ts",
       "default": "./src/recording/artifact.fixtures.ts"
     },
+    "./recording-facts": {
+      "types": "./src/recording/recording-facts.ts",
+      "default": "./src/recording/recording-facts.ts"
+    },
     "./recording-mp4-fixtures": {
       "types": "./src/recording/mp4.fixtures.ts",
       "default": "./src/recording/mp4.fixtures.ts"
diff --git a/packages/capture-kit/src/recording/recording-facts.test.ts b/packages/capture-kit/src/recording/recording-facts.test.ts
new file mode 100644
index 0000000000..51c679b483
--- /dev/null
+++ b/packages/capture-kit/src/recording/recording-facts.test.ts
@@ -0,0 +1,47 @@
+import assert from 'node:assert/strict';
+import { test } from 'vitest';
+import { RECORDING_FACTS_KEYS, recordingFactsAreValid } from './recording-facts.ts';
+
+const FACTS = Object.freeze({
+  scope: 'device',
+  showTouches: true,
+  recordOnlySession: false,
+});
+
+function facet(overrides: Record<string, unknown> = {}): Record<string, unknown> {
+  return { ...FACTS, ...overrides };
+}
+
+test('accepts the facts a caller asked for, with or without the optional ones', () => {
+  assert.equal(recordingFactsAreValid(facet()), true);
+  assert.equal(
+    recordingFactsAreValid(
+      facet({ activeSessionApp: { bundleId: 'com.example.app', name: 'Example' } }),
+    ),
+    true,
+  );
+  assert.equal(recordingFactsAreValid(facet({ exportQuality: 'high' })), true);
+});
+
+test('refuses a facet whose recording facts no start could have produced', () => {
+  assert.equal(recordingFactsAreValid(facet({ scope: 'window' })), false);
+  assert.equal(recordingFactsAreValid(facet({ showTouches: 'yes' })), false);
+  assert.equal(recordingFactsAreValid(facet({ recordOnlySession: 1 })), false);
+  assert.equal(recordingFactsAreValid({ ...FACTS, showTouches: undefined }), false);
+});
+
+test('refuses an optional fact that is present but unreadable rather than dropping it', () => {
+  assert.equal(recordingFactsAreValid(facet({ exportQuality: 'ultra' })), false);
+  assert.equal(recordingFactsAreValid(facet({ activeSessionApp: { bundleId: '' } })), false);
+  assert.equal(recordingFactsAreValid(facet({ activeSessionApp: { name: 'Example' } })), false);
+  assert.equal(recordingFactsAreValid(facet({ activeSessionApp: 'com.example.app' })), false);
+  assert.equal(
+    recordingFactsAreValid(facet({ activeSessionApp: { bundleId: 'a', name: '' } })),
+    false,
+  );
+});
+
+test('names every key of the facet it validates', () => {
+  const declared = Object.keys({ ...FACTS, activeSessionApp: undefined, exportQuality: undefined });
+  assert.deepEqual([...RECORDING_FACTS_KEYS].sort(), declared.sort());
+});
diff --git a/packages/capture-kit/src/recording/recording-facts.ts b/packages/capture-kit/src/recording/recording-facts.ts
new file mode 100644
index 0000000000..57cb388331
--- /dev/null
+++ b/packages/capture-kit/src/recording/recording-facts.ts
@@ -0,0 +1,56 @@
+import {
+  isRecordingExportQuality,
+  isRecordingScope,
+  type RecordingAppIdentity,
+  type RecordingExportQuality,
+  type RecordingScope,
+} from '@agent-device/contracts/recording';
+import { isRecord } from '@agent-device/kernel/record';
+
+/**
+ * What a durable recording keeps about what its caller asked for, apart from where its files live
+ * (ADR 0024 2.3). Every backend's descriptor carries these facts because the export it owes the
+ * caller is described by them, so one validator decides whether a manifest's copy can be trusted
+ * rather than each backend inventing its own strictness.
+ */
+export type RecordingFacts = Readonly<{
+  scope: RecordingScope;
+  showTouches: boolean;
+  recordOnlySession: boolean;
+  activeSessionApp?: RecordingAppIdentity;
+  exportQuality?: RecordingExportQuality;
+}>;
+
+/** The keys of {@link RecordingFacts}, so a backend carries the facet without naming it twice. */
+export const RECORDING_FACTS_KEYS = [
+  'scope',
+  'showTouches',
+  'recordOnlySession',
+  'activeSessionApp',
+  'exportQuality',
+] as const satisfies readonly (keyof RecordingFacts)[];
+
+/**
+ * Whether a durable value carries whole recording facts. One unreadable field refuses the whole
+ * facet: a resumed stop that trusted half an overlay request would serve a video the caller never
+ * asked for, which is the failure an unreadable descriptor is supposed to prevent.
+ */
+export function recordingFactsAreValid(value: Record<string, unknown>): value is RecordingFacts {
+  return (
+    isRecordingScope(value.scope) &&
+    typeof value.showTouches === 'boolean' &&
+    typeof value.recordOnlySession === 'boolean' &&
+    (value.exportQuality === undefined || isRecordingExportQuality(value.exportQuality)) &&
+    isOptionalAppIdentity(value.activeSessionApp)
+  );
+}
+
+function isOptionalAppIdentity(value: unknown): value is RecordingAppIdentity | undefined {
+  if (value === undefined) return true;
+  if (!isRecord(value) || !isNonemptyText(value.bundleId)) return false;
+  return value.name === undefined || isNonemptyText(value.name);
+}
+
+function isNonemptyText(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0;
+}
diff --git a/packages/capture-kit/src/recording/stop-sequence.ts b/packages/capture-kit/src/recording/stop-sequence.ts
index 2c2970d3c3..a7a5787222 100644
--- a/packages/capture-kit/src/recording/stop-sequence.ts
+++ b/packages/capture-kit/src/recording/stop-sequence.ts
@@ -15,6 +15,13 @@ import { readStopCheckpoints, writeStopCheckpoint } from './stop-checkpoints.ts'
 /** Where a recorder writes when its file must stay separate from the export (ADR 0024 2.3). */
 export { collectedRecordingPath, nativeRecordingPath } from './artifact-paths.ts';
 
+/**
+ * What an earlier attempt of this stop journaled. A backend deciding whether a lost recording is still
+ * recoverable reads the same checkpoints this sequence resumes from, so the two cannot disagree about
+ * what a retry would still have to do.
+ */
+export { readStopCheckpoints } from './stop-checkpoints.ts';
+
 /** What a backend learned while asking its recorder to stop (ADR 0024 2.2). */
 export type RecorderStop = Readonly<{
   observation: StopObservation;
diff --git a/packages/platform-android/src/recording/manifest-validation.ts b/packages/platform-android/src/recording/manifest-validation.ts
index 8d0960fa65..c8ad5fc90b 100644
--- a/packages/platform-android/src/recording/manifest-validation.ts
+++ b/packages/platform-android/src/recording/manifest-validation.ts
@@ -1,4 +1,5 @@
 import { isNativePathDisposition } from '@agent-device/contracts/recording-native-path';
+import { recordingFactsAreValid } from '@agent-device/capture-kit/recording-facts';
 import { isStopObservation } from '@agent-device/contracts/recording-stop-observation';
 import type {
   ScreenRecordingChunk,
@@ -53,20 +54,11 @@ function descriptorIdentityIsValid(value: Record<string, unknown>): boolean {
 }
 
 function descriptorRecordingIsValid(value: Record<string, unknown>): boolean {
-  return (
-    (value.clientOutputPath === undefined || typeof value.clientOutputPath === 'string') &&
-    isScope(value.scope) &&
-    typeof value.showTouches === 'boolean' &&
-    typeof value.recordOnlySession === 'boolean'
-  );
+  return isOptionalText(value.clientOutputPath) && recordingFactsAreValid(value);
 }
 
 function descriptorOptionsAreValid(value: Record<string, unknown>): boolean {
-  return (
-    isTransportMode(value.transportMode) &&
-    isOptionalQuality(value.exportQuality) &&
-    isOptionalApp(value.activeSessionApp)
-  );
+  return isTransportMode(value.transportMode);
 }
 
 function manifestIdentityIsValid(candidate: Partial<NativeManifest>): boolean {
@@ -84,17 +76,13 @@ function manifestIdentityIsValid(candidate: Partial<NativeManifest>): boolean {
 function manifestRecordingIsValid(candidate: Partial<NativeManifest>): boolean {
   return (
     typeof candidate.outputPath === 'string' &&
-    (candidate.clientOutputPath === undefined || typeof candidate.clientOutputPath === 'string') &&
-    isScope(candidate.scope) &&
-    typeof candidate.showTouches === 'boolean' &&
-    typeof candidate.recordOnlySession === 'boolean'
+    isOptionalText(candidate.clientOutputPath) &&
+    recordingFactsAreValid(candidate)
   );
 }
 
 function manifestOptionsAreValid(candidate: Partial<NativeManifest>): boolean {
   return (
-    isOptionalApp(candidate.activeSessionApp) &&
-    isOptionalQuality(candidate.exportQuality) &&
     isTransportMode(candidate.transportMode) &&
     (candidate.pendingRemotePath === undefined ||
       isNativeRecordingPath(candidate.pendingRemotePath))
@@ -153,12 +141,7 @@ function completionIdentityIsValid(candidate: Partial<ScreenRecordingCompletion>
 }
 
 function completionRecordingIsValid(candidate: Partial<ScreenRecordingCompletion>): boolean {
-  return (
-    isScope(candidate.scope) &&
-    typeof candidate.showTouches === 'boolean' &&
-    typeof candidate.recordOnlySession === 'boolean' &&
-    isOptionalApp(candidate.activeSessionApp)
-  );
+  return recordingFactsAreValid(candidate);
 }
 
 function isValidCompletionChunk(chunk: ScreenRecordingChunk, index: number): boolean {
@@ -229,25 +212,12 @@ function isObject(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null;
 }
 
-function isScope(value: unknown): value is 'app' | 'device' | 'system' {
-  return value === 'app' || value === 'device' || value === 'system';
-}
-
 function isTransportMode(value: unknown): value is AndroidRecordingDescriptor['transportMode'] {
   return value === 'local' || value === 'transport-composed';
 }
 
-function isOptionalQuality(value: unknown): boolean {
-  return value === undefined || value === 'medium' || value === 'high';
-}
-
-function isOptionalApp(value: unknown): boolean {
-  return (
-    value === undefined ||
-    (isObject(value) &&
-      typeof value.bundleId === 'string' &&
-      (value.name === undefined || typeof value.name === 'string'))
-  );
+function isOptionalText(value: unknown): value is string | undefined {
+  return value === undefined || typeof value === 'string';
 }
 
 function isNativeRecordingPath(value: unknown): value is string {
diff --git a/packages/platform-apple/src/recording/completion.ts b/packages/platform-apple/src/recording/completion.ts
index b3c89fce87..6fc7b50120 100644
--- a/packages/platform-apple/src/recording/completion.ts
+++ b/packages/platform-apple/src/recording/completion.ts
@@ -63,6 +63,10 @@ export async function completeAppleRecording(params: {
  * Turns the copy a stop collected into the export, and answers what became of the recorder's own
  * file (ADR 0024 2.3). The recorder's file is never finalized in place: the overlay and the telemetry
  * land on the export, and the recorder's file is retired only once that export exists.
+ *
+ * `overlayUnavailable` names a reason the caller was promised an overlay this export cannot carry,
+ * which is refused on the way in and disclosed on the way out rather than attempted with nothing to
+ * burn in and then apologised for.
  */
 export async function finalizeAppleRecordingFromCollected(
   params: Readonly<{
@@ -72,6 +76,7 @@ export async function finalizeAppleRecordingFromCollected(
     collectedPath: string;
     exportPath: string;
     nativePath: string;
+    overlayUnavailable?: string;
   }>,
 ): Promise<ScreenRecordingFinalization> {
   const { host, snapshot, targetLabel, collectedPath, exportPath, nativePath } = params;
@@ -80,13 +85,14 @@ export async function finalizeAppleRecordingFromCollected(
   if (snapshot.invalidatedReason && !snapshot.showTouches) {
     throw new Error(`recording invalidated: ${snapshot.invalidatedReason}`);
   }
+  const overlayUnavailability = params.overlayUnavailable ?? snapshot.invalidatedReason;
   let finalization: Awaited<ReturnType<typeof host.screenRecording.finalize.complete>>;
   try {
     await host.screenRecording.outputs.copy({ from: collectedPath, to: exportPath });
     finalization = await asAppErrorAsync(() =>
       host.screenRecording.finalize.complete({
         outputPath: exportPath,
-        showTouches: snapshot.invalidatedReason ? false : snapshot.showTouches,
+        showTouches: overlayUnavailability === undefined && snapshot.showTouches,
         gestureEvents: snapshot.gestureEvents,
         exportQuality: snapshot.exportQuality ?? 'medium',
         targetLabel,
@@ -99,9 +105,9 @@ export async function finalizeAppleRecordingFromCollected(
   }
   return {
     ...finalization,
-    ...(snapshot.invalidatedReason
-      ? { overlayWarning: `overlay unavailable: ${snapshot.invalidatedReason}` }
-      : {}),
+    ...(overlayUnavailability === undefined
+      ? {}
+      : { overlayWarning: `overlay unavailable: ${overlayUnavailability}` }),
     nativePathDisposition:
       (await host.screenRecording.outputs.remove(nativePath)) === 'removed'
         ? 'retired'
diff --git a/packages/platform-apple/src/recording/recovery.test.ts b/packages/platform-apple/src/recording/recovery.test.ts
index 3c64cf26c8..70d880eef4 100644
--- a/packages/platform-apple/src/recording/recovery.test.ts
+++ b/packages/platform-apple/src/recording/recovery.test.ts
@@ -1,12 +1,21 @@
 import { expect, test, vi } from 'vitest';
+import type { DurableCaptureProgress } from '@agent-device/contracts/durable-resource';
 import { localRuntimeOwner } from '@agent-device/contracts/platform-runtime';
+import { recordingFileStore } from '@agent-device/capture-kit/recording-artifact-fixtures';
+import {
+  collectedRecordingPath,
+  nativeRecordingPath,
+} from '@agent-device/capture-kit/recording-stop-sequence';
+import type { JsonObject } from '@agent-device/contracts/client';
 import { createAppleScreenRecordingOperations } from './runtime.ts';
 import {
   appleRecordingHost,
   coreDevice,
   processIdentity,
   recordingInput,
+  recordingOutputPath,
   simulator,
+  simulatorRecorderStart,
 } from './runtime.fixtures.ts';
 
 test('daemon-loss cleanup distinguishes live, dead, replaced, and corrupt simulator identity', async () => {
@@ -68,6 +77,230 @@ test('daemon-loss cleanup distinguishes live, dead, replaced, and corrupt simula
   expect(inspectProcess).not.toHaveBeenCalled();
 });
 
+type SimulatorHostOptions = Parameters<typeof appleRecordingHost>[0];
+
+function simulatorHost(
+  files: ReturnType<typeof recordingFileStore>,
+  extra: SimulatorHostOptions = {},
+) {
+  return appleRecordingHost({
+    ...extra,
+    files,
+    apple: {
+      ...simulatorRecorderStart(),
+      inspectProcess: async () => 'missing' as const,
+      ...extra.apple,
+    },
+  });
+}
+
+function recoveryOperations(host: ReturnType<typeof appleRecordingHost>) {
+  return createAppleScreenRecordingOperations({
+    host,
+    device: simulator,
+    owner: localRuntimeOwner('apple'),
+    signal: new AbortController().signal,
+  });
+}
+
+async function startSimulatorRecording(
+  files: ReturnType<typeof recordingFileStore>,
+  overrides: Parameters<typeof recordingInput>[0] = {},
+) {
+  return await recoveryOperations(simulatorHost(files)).screenRecordingStart(
+    recordingInput(overrides),
+  );
+}
+
+test('a simulator recording whose recorder died with its daemon exports through the retried stop', async () => {
+  const files = recordingFileStore();
+  const started = await startSimulatorRecording(files);
+  const nativePath = nativeRecordingPath(recordingOutputPath());
+
+  const reattached = await recoveryOperations(simulatorHost(files)).screenRecordingReattach({
+    envelope: started.envelope,
+  });
+  expect(reattached).toMatchObject({ status: 'active' });
+  if (reattached.status !== 'active') throw new Error('expected an exportable recording');
+
+  await expect(reattached.handle.finish()).resolves.toMatchObject({
+    status: 'completed',
+    result: {
+      backend: 'simctl recordVideo',
+      outPath: recordingOutputPath(),
+      scope: 'device',
+      stopObservation: { recorder: 'confirmed' },
+      nativePathDisposition: 'retired',
+    },
+  });
+  expect(files.exists(recordingOutputPath())).toBe(true);
+  expect(files.exists(nativePath)).toBe(false);
+});
+
+test('a finalized export whose daemon died before the record closed still completes', async () => {
+  // What the first attempt left behind: the export it wrote, the recorder's file it retired, and the
+  // copy it discarded once the finalization below was journaled.
+  const files = recordingFileStore({ [recordingOutputPath()]: 'fake-video' });
+  const started = await startSimulatorRecording(files);
+  await files.outputs.remove(nativeRecordingPath(recordingOutputPath()));
+  const complete = vi.fn(async () => ({}));
+  const envelope = stopJournalOn(started.envelope, {
+    stopObservation: { recorder: 'confirmed' },
+    stoppedAtMs: 1_790_000_000_000,
+    collectedPath: collectedRecordingPath(recordingOutputPath()),
+    exportPath: recordingOutputPath(),
+    stopFinalization: {
+      telemetryPath: '/tmp/capture.gesture-telemetry.json',
+      nativePathDisposition: 'retired',
+    },
+  });
+
+  const reattached = await recoveryOperations(
+    simulatorHost(files, { complete }),
+  ).screenRecordingReattach({ envelope });
+  if (reattached.status !== 'active') throw new Error('expected a finalized export to replay');
+
+  await expect(reattached.handle.finish(stopProgressFor(envelope))).resolves.toMatchObject({
+    status: 'completed',
+    result: {
+      outPath: recordingOutputPath(),
+      telemetryPath: '/tmp/capture.gesture-telemetry.json',
+      stopObservation: { recorder: 'confirmed' },
+      nativePathDisposition: 'retired',
+    },
+  });
+  // The export was written by the stop that journaled it, so nothing here re-runs the finalizer.
+  expect(complete).not.toHaveBeenCalled();
+});
+
+test('a collected copy is finalized again when the recorder no longer has its own file', async () => {
+  const files = recordingFileStore();
+  const started = await startSimulatorRecording(files);
+  const collectedPath = collectedRecordingPath(recordingOutputPath());
+  await files.outputs.copy({ from: nativeRecordingPath(recordingOutputPath()), to: collectedPath });
+  await files.outputs.remove(nativeRecordingPath(recordingOutputPath()));
+  const copy = vi.fn(async ({ from, to }: Readonly<{ from: string; to: string }>) => {
+    const bytes = files.files.get(from);
+    if (bytes === undefined) throw new Error(`ENOENT: ${from}`);
+    files.files.set(to, bytes);
+  });
+  const complete = vi.fn(async () => ({
+    telemetryPath: '/tmp/capture.gesture-telemetry.json',
+  }));
+  const envelope = stopJournalOn(started.envelope, {
+    stopObservation: { recorder: 'confirmed' },
+    stoppedAtMs: 1_790_000_000_000,
+    collectedPath,
+  });
+
+  const reattached = await recoveryOperations(
+    simulatorHost(files, { complete, outputs: { copy } }),
+  ).screenRecordingReattach({ envelope });
+  if (reattached.status !== 'active') throw new Error('expected a collectable copy to finish');
+
+  await expect(reattached.handle.finish(stopProgressFor(envelope))).resolves.toMatchObject({
+    status: 'completed',
+    result: {
+      outPath: recordingOutputPath(),
+      telemetryPath: '/tmp/capture.gesture-telemetry.json',
+      stopObservation: { recorder: 'confirmed' },
+    },
+  });
+  expect(files.exists(recordingOutputPath())).toBe(true);
+  // The recorder's own file is gone. A stop that collected again would fail on its way to an export the
+  // manifest already describes.
+  expect(copy.mock.calls.map(([attempt]) => attempt.from)).toEqual([collectedPath]);
+});
+
+test('a journaled copy that cannot be read is answered as a loss instead of a fresh collect', async () => {
+  const started = await startSimulatorRecording(recordingFileStore());
+
+  await expect(
+    recoveryOperations(simulatorHost(recordingFileStore())).screenRecordingReattach({
+      envelope: stopJournalOn(started.envelope, {
+        stopObservation: { recorder: 'confirmed' },
+        collectedPath: collectedRecordingPath(recordingOutputPath()),
+      }),
+    }),
+  ).resolves.toEqual({ status: 'missing' });
+});
+
+/**
+ * The checkpoints a first attempt journaled, under the keys the shared stop sequence writes them with,
+ * so `readStopCheckpoints` hands them back to the resumed stop.
+ */
+function stopJournalOn(
+  envelope: Awaited<ReturnType<typeof startSimulatorRecording>>['envelope'],
+  journal: JsonObject,
+) {
+  return { ...envelope, metadata: { ...(envelope.metadata ?? {}), ...journal } };
+}
+
+/** How the durable record hands a stop what its earlier attempt journaled. */
+function stopProgressFor(envelope: ReturnType<typeof stopJournalOn>): DurableCaptureProgress {
+  const learned = { ...(envelope.metadata ?? {}) };
+  return Object.freeze({ learned, record: (fact: JsonObject) => Object.assign(learned, fact) });
+}
+
+test('a recovered export discloses the touch overlay whose events died with the daemon', async () => {
+  const files = recordingFileStore();
+  const started = await startSimulatorRecording(files, { showTouches: true });
+
+  const reattached = await recoveryOperations(simulatorHost(files)).screenRecordingReattach({
+    envelope: started.envelope,
+  });
+  if (reattached.status !== 'active') throw new Error('expected an exportable recording');
+  const finished = await reattached.handle.finish();
+  if (finished.status !== 'completed') throw new Error('expected a completed export');
+  expect(finished.result.overlayWarning).toContain('overlay unavailable');
+});
+
+test('a simulator recording left by a manifest without export coordinates is still a loss', async () => {
+  const files = recordingFileStore();
+  const started = await startSimulatorRecording(files);
+  const { recording: _dropped, ...bodyWithoutCoordinates } = started.envelope.descriptor.body;
+
+  await expect(
+    recoveryOperations(simulatorHost(files)).screenRecordingReattach({
+      envelope: {
+        ...started.envelope,
+        descriptor: { ...started.envelope.descriptor, body: bodyWithoutCoordinates },
+      },
+    }),
+  ).resolves.toEqual({ status: 'missing' });
+});
+
+test('a gone recorder with no readable video left behind is answered as a loss', async () => {
+  const started = await startSimulatorRecording(recordingFileStore());
+
+  await expect(
+    recoveryOperations(simulatorHost(recordingFileStore())).screenRecordingReattach({
+      envelope: started.envelope,
+    }),
+  ).resolves.toEqual({ status: 'missing' });
+});
+
+test('unreadable export coordinates refuse reattach before the recorder is probed', async () => {
+  const files = recordingFileStore();
+  const started = await startSimulatorRecording(files);
+  const inspectProcess = vi.fn(async () => 'missing' as const);
+
+  await expect(
+    recoveryOperations(simulatorHost(files, { apple: { inspectProcess } })).screenRecordingReattach(
+      {
+        envelope: {
+          ...started.envelope,
+          descriptor: {
+            ...started.envelope.descriptor,
+            body: { ...started.envelope.descriptor.body, recording: { outPath: 42 } },
+          },
+        },
+      },
+    ),
+  ).resolves.toMatchObject({ status: 'unreattachable', reason: 'descriptor-invalid' });
+  expect(inspectProcess).not.toHaveBeenCalled();
+});
+
 test('runner recovery never stops a replacement session owner', async () => {
   const operations = createAppleScreenRecordingOperations({
     host: appleRecordingHost(),
diff --git a/packages/platform-apple/src/recording/recovery.ts b/packages/platform-apple/src/recording/recovery.ts
index 7b1ae4cfcc..b0b4a91a94 100644
--- a/packages/platform-apple/src/recording/recovery.ts
+++ b/packages/platform-apple/src/recording/recovery.ts
@@ -1,17 +1,34 @@
 import { deviceIdentity, isIosFamily, type DeviceInfo } from '@agent-device/kernel/device';
-import type { CleanupOutcome } from '@agent-device/contracts/durable-resource';
-import type { DurableDescriptorCodec } from '@agent-device/contracts/durable-resource-envelope';
+import type {
+  CleanupOutcome,
+  ReattachOutcome,
+  ResourceUnreattachableReason,
+} from '@agent-device/contracts/durable-resource';
+import type {
+  DurableDescriptorCodec,
+  DurableResourceEnvelope,
+} from '@agent-device/contracts/durable-resource-envelope';
 import type {
   ManagedProcessIdentity,
   OwnedProcessRecordScope,
 } from '@agent-device/contracts/platform-runtime-host';
 import type { RuntimeOwnerRef } from '@agent-device/contracts/platform-runtime';
 import type { ScreenRecordingRuntimeHost } from '@agent-device/contracts/screen-recording-runtime-host';
+import { isRecord } from '@agent-device/kernel/record';
 import {
-  type ScreenRecordingStartInput,
   SCREEN_RECORDING_RESOURCE_KIND,
+  type ScreenRecordingCompletion,
+  type ScreenRecordingLiveHandle,
+  type ScreenRecordingLiveSnapshot,
+  type ScreenRecordingStartInput,
 } from '@agent-device/contracts/screen-recording-runtime';
 import { createDurableResourceEnvelope, encodeDurableDescriptor } from '@agent-device/capture-kit';
+import {
+  RECORDING_FACTS_KEYS,
+  recordingFactsAreValid,
+} from '@agent-device/capture-kit/recording-facts';
+import type { RecordingStopProgress } from '@agent-device/contracts/recording-stop-progress';
+import { readStopCheckpoints } from '@agent-device/capture-kit/recording-stop-sequence';
 
 export type AppleScreenRecordingOperationHost = Readonly<{
   screenRecording: Pick<
@@ -20,11 +37,34 @@ export type AppleScreenRecordingOperationHost = Readonly<{
   >;
 }>;
 
+/**
+ * The export a simulator recording owes its caller, durable so a `record stop` that lost its daemon
+ * mid-export can still produce it. These are the caller-facing facts of the live snapshot, never the
+ * recorder's: `outPath` is the path the caller asked for, which is not the descriptor's `outputPath`
+ * (that one is where `simctl` writes), and `startedAt` is the launch the duration is measured from.
+ *
+ * A manifest written before these coordinates existed cannot name an export it never recorded, so
+ * the field stays optional and its absence is answered exactly as such a manifest was answered then.
+ */
+/** The live-snapshot keys a recovered export is described by, which is the caller's own request. */
+const SIMULATOR_EXPORT_KEYS = [
+  'outPath',
+  'startedAt',
+  'clientOutPath',
+  ...RECORDING_FACTS_KEYS,
+] as const;
+
+export type AppleSimulatorExportCoordinates = Pick<
+  ScreenRecordingLiveSnapshot,
+  (typeof SIMULATOR_EXPORT_KEYS)[number]
+>;
+
 export type AppleRecordingDescriptor =
   | Readonly<{
       backend: 'simctl';
       outputPath: string;
       processes: readonly ManagedProcessIdentity[];
+      recording?: AppleSimulatorExportCoordinates;
     }>
   | Readonly<{
       backend: 'runner';
@@ -46,6 +86,7 @@ const encodeAppleRecordingDescriptor: AppleRecordingDescriptorCodec['encode'] =
       backend: descriptor.backend,
       outputPath: descriptor.outputPath,
       processes: descriptor.processes.map((process) => ({ ...process })),
+      ...(descriptor.recording === undefined ? {} : { recording: { ...descriptor.recording } }),
     };
     return encoded;
   }
@@ -85,6 +126,21 @@ export function createAppleRecordingEnvelope(params: {
   });
 }
 
+/**
+ * The part of a live snapshot that outlives its daemon. What the recorder's own process held — gesture
+ * events, the touch reference frame, a runner's clock — is deliberately absent: recovery cannot invent
+ * it, and a recovered export states what it could not honour instead of pretending otherwise.
+ */
+export function simulatorExportCoordinates(
+  snapshot: ScreenRecordingLiveSnapshot,
+): AppleSimulatorExportCoordinates {
+  const coordinates: Partial<AppleSimulatorExportCoordinates> = {};
+  for (const key of SIMULATOR_EXPORT_KEYS) {
+    if (snapshot[key] !== undefined) Object.assign(coordinates, { [key]: snapshot[key] });
+  }
+  return coordinates as AppleSimulatorExportCoordinates;
+}
+
 export async function cleanupAppleRecording(
   host: AppleScreenRecordingOperationHost,
   device: DeviceInfo,
@@ -171,48 +227,159 @@ async function cleanupRunner(
   }
 }
 
+/** What a recovered simulator export needs besides the coordinates its manifest kept. */
+export type AppleSimulatorExportRestore = Readonly<{
+  recording: AppleSimulatorExportCoordinates;
+  /** The file `simctl` wrote, or the copy a first attempt already collected. */
+  nativePath: string;
+  cleanup(): Promise<CleanupOutcome>;
+}>;
+
+/**
+ * What an envelope allows next. `restore-export` is the answer when the recorder is gone and the export
+ * is still reachable: recovery holds the facts and runs no stop, so the runtime that owns the stop
+ * sequence builds the handle from them.
+ */
+export type AppleRecordingReattachment =
+  | ReattachOutcome<ScreenRecordingLiveHandle, ScreenRecordingCompletion>
+  | (AppleSimulatorExportRestore & Readonly<{ status: 'restore-export' }>);
+
 export async function reattachAppleRecording(
-  host: AppleScreenRecordingOperationHost,
-  device: DeviceInfo,
-  body: Parameters<AppleRecordingDescriptorCodec['decode']>[0],
-) {
-  const decoded = descriptorCodec.decode(body);
+  params: Readonly<{
+    host: AppleScreenRecordingOperationHost;
+    device: DeviceInfo;
+    envelope: DurableResourceEnvelope<typeof SCREEN_RECORDING_RESOURCE_KIND>;
+  }>,
+): Promise<AppleRecordingReattachment> {
+  const { host, device, envelope } = params;
+  const decoded = descriptorCodec.decode(envelope.descriptor.body);
   if (decoded.status !== 'decoded') {
-    return {
-      status: 'unreattachable' as const,
-      reason: 'descriptor-invalid' as const,
-      message: decoded.message,
-    };
+    return unreattachableAppleRecording('descriptor-invalid', decoded.message);
   }
   if (!descriptorMatchesAppleDevice(device, decoded.descriptor)) {
-    return {
-      status: 'unreattachable' as const,
-      reason: 'descriptor-invalid' as const,
-      message: 'Apple screen-recording descriptor does not match the bound device.',
-    };
+    return unreattachableAppleRecording(
+      'descriptor-invalid',
+      'Apple screen-recording descriptor does not match the bound device.',
+    );
+  }
+  return decoded.descriptor.backend === 'simctl'
+    ? await reattachSimulatorRecording(params, decoded.descriptor)
+    : await reattachRunnerRecording(host, device, decoded.descriptor);
+}
+
+/**
+ * A `simctl` recorder that is proven gone is the ordinary state of a recording whose daemon died,
+ * and it says nothing about the file that recorder already wrote (ADR 0024 2.2). The manifest's
+ * coordinates plus that file are what a retried `record stop` still owes the caller, so this answers
+ * with a handle that finishes the export instead of with a loss nobody observed.
+ */
+/**
+ * A `simctl` recorder that is proven gone is the ordinary state of a recording whose daemon died, and it
+ * says nothing about what the export can still become (ADR 0024 2.2). So the answer comes from what a
+ * resumed stop would still have to read: nothing when the first attempt journaled a finalization, that
+ * copy when it journaled one, and otherwise the recorder's own file. Nothing reachable is reported as a
+ * loss.
+ */
+async function reattachSimulatorRecording(
+  params: Readonly<{
+    host: AppleScreenRecordingOperationHost;
+    envelope: DurableResourceEnvelope<typeof SCREEN_RECORDING_RESOURCE_KIND>;
+  }>,
+  descriptor: Extract<AppleRecordingDescriptor, { backend: 'simctl' }>,
+): Promise<AppleRecordingReattachment> {
+  const ownership = await Promise.all(
+    descriptor.processes.map(
+      async (marker) => await params.host.screenRecording.apple.inspectProcess(marker),
+    ),
+  );
+  if (!ownership.every((value) => value === 'missing')) {
+    return unreattachableAppleRecording(
+      'transport-not-reattachable',
+      ownership.includes('ownership-lost')
+        ? 'Apple recording ownership no longer matches the durable descriptor.'
+        : 'Apple screen recordings require exact cleanup after daemon restart.',
+    );
+  }
+  const { recording } = descriptor;
+  const source = resumedExportSource(
+    readStopCheckpoints(params.envelope.metadata),
+    descriptor.outputPath,
+  );
+  if (
+    recording === undefined ||
+    (source !== undefined && !(await recordingRemains(params.host, source)))
+  ) {
+    return { status: 'missing' };
   }
-  const ownership =
-    decoded.descriptor.backend === 'simctl'
-      ? await Promise.all(
-          decoded.descriptor.processes.map(
-            async (marker) => await host.screenRecording.apple.inspectProcess(marker),
-          ),
-        )
-      : [
-          await host.screenRecording.apple.inspectRunner(
-            device,
-            decoded.descriptor.runnerSessionId,
-            decoded.descriptor.runnerAuthority,
-          ),
-        ];
-  if (ownership.every((value) => value === 'missing')) return { status: 'missing' as const };
   return {
-    status: 'unreattachable' as const,
-    reason: 'transport-not-reattachable' as const,
-    message: ownership.includes('ownership-lost')
+    status: 'restore-export',
+    recording,
+    nativePath: descriptor.outputPath,
+    cleanup: async () =>
+      await cleanupSimulator(params.host, descriptor.processes, params.envelope.sessionId),
+  };
+}
+
+/**
+ * The file a resumed stop will still read, or `undefined` when it will read none. A journaled
+ * finalization is replayed as it stands and its copy is then discarded, a step that tolerates the copy
+ * already being gone; a journaled copy is what `finalize` runs from; and a stop that journaled neither
+ * collects from the recorder's own path again.
+ */
+function resumedExportSource(
+  learned: RecordingStopProgress,
+  nativePath: string,
+): string | undefined {
+  if (learned.finalization !== undefined) return undefined;
+  return learned.collectedPath ?? nativePath;
+}
+
+async function reattachRunnerRecording(
+  host: AppleScreenRecordingOperationHost,
+  device: DeviceInfo,
+  descriptor: Extract<AppleRecordingDescriptor, { backend: 'runner' }>,
+): Promise<AppleRecordingReattachment> {
+  const ownership = await host.screenRecording.apple.inspectRunner(
+    device,
+    descriptor.runnerSessionId,
+    descriptor.runnerAuthority,
+  );
+  if (ownership === 'missing') return { status: 'missing' };
+  return unreattachableAppleRecording(
+    'transport-not-reattachable',
+    ownership === 'ownership-lost'
       ? 'Apple recording ownership no longer matches the durable descriptor.'
       : 'Apple screen recordings require exact cleanup after daemon restart.',
-  };
+  );
+}
+
+/**
+ * Whether the recorder's own file can still become an export. The container sniff is the read-only
+ * probe the stop itself runs on its collected copy, and it is the most this step can promise: a file
+ * that fails it is exactly the recording a retry would refuse, so nothing is offered for it.
+ */
+/**
+ * Whether a file the resumed stop would read can still become an export. The container sniff is the
+ * read-only probe the stop itself runs on that file, and it is the most this step can promise: a file
+ * that fails it is exactly the recording a retry would refuse.
+ */
+async function recordingRemains(
+  host: AppleScreenRecordingOperationHost,
+  outputPath: string,
+): Promise<boolean> {
+  try {
+    await host.screenRecording.finalize.sniff({ outputPath });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function unreattachableAppleRecording(
+  reason: ResourceUnreattachableReason,
+  message: string,
+): AppleRecordingReattachment {
+  return { status: 'unreattachable', reason, message };
 }
 
 function decodeAppleRecordingDescriptor(
@@ -227,12 +394,43 @@ function decodeAppleRecordingDescriptor(
 
 function decodeSimulatorDescriptor(body: Record<string, unknown>, outputPath: string) {
   const processes = decodeProcessIdentities(body.processes);
-  return processes
-    ? ({
-        status: 'decoded',
-        descriptor: Object.freeze({ backend: 'simctl', outputPath, processes }),
-      } as const)
-    : invalidDescriptor();
+  const recording = readSimulatorExportCoordinates(body.recording);
+  if (!processes || recording === 'invalid') return invalidDescriptor();
+  return {
+    status: 'decoded' as const,
+    descriptor: Object.freeze({
+      backend: 'simctl' as const,
+      outputPath,
+      processes,
+      ...(recording === undefined ? {} : { recording }),
+    }),
+  } as const;
+}
+
+/**
+ * What the durable coordinates have to say for themselves. `invalid` is a manifest whose recording
+ * facet cannot be trusted, which is answered exactly like any other unreadable descriptor: no
+ * reattach, no cleanup, the record stays for a human.
+ */
+function readSimulatorExportCoordinates(
+  value: unknown,
+): AppleSimulatorExportCoordinates | undefined | 'invalid' {
+  if (value === undefined) return undefined;
+  return isRecord(value) && isWholeExportCoordinates(value)
+    ? Object.freeze(value as unknown as AppleSimulatorExportCoordinates)
+    : 'invalid';
+}
+
+/** The facts a recovered export computes on rather than repeats, whole or absent. */
+function isWholeExportCoordinates(
+  value: Record<string, unknown>,
+): value is AppleSimulatorExportCoordinates {
+  return (
+    isNonemptyString(value.outPath) &&
+    isFiniteNumber(value.startedAt) &&
+    isOptionalText(value.clientOutPath) &&
+    recordingFactsAreValid(value)
+  );
 }
 
 function decodeRunnerDescriptor(body: Record<string, unknown>, outputPath: string) {
@@ -257,6 +455,14 @@ function isNonemptyString(value: unknown): value is string {
   return typeof value === 'string' && value.length > 0;
 }
 
+function isOptionalText(value: unknown): value is string | undefined {
+  return value === undefined || isNonemptyString(value);
+}
+
+function isFiniteNumber(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value);
+}
+
 function isRunnerAuthority(value: unknown): value is 'local-lease' | 'scoped-provider' {
   return value === 'local-lease' || value === 'scoped-provider';
 }
diff --git a/packages/platform-apple/src/recording/runtime.fixtures.ts b/packages/platform-apple/src/recording/runtime.fixtures.ts
index 190970e65c..90381e10e4 100644
--- a/packages/platform-apple/src/recording/runtime.fixtures.ts
+++ b/packages/platform-apple/src/recording/runtime.fixtures.ts
@@ -65,6 +65,19 @@ export function recordingInput(
   };
 }
 
+export function simulatorRecorderStart(): Pick<
+  ScreenRecordingRuntimeHost['apple'],
+  'startSimulator'
+> {
+  return {
+    startSimulator: async () => ({
+      markers: [processIdentity],
+      wait: new Promise<never>(() => {}),
+      terminate: async () => {},
+    }),
+  };
+}
+
 export function appleRecordingHost(
   options: {
     apple?: Partial<ScreenRecordingRuntimeHost['apple']>;
@@ -114,7 +127,13 @@ export function appleRecordingHost(
       apple,
       outputs: Object.assign({}, store.outputs, options.outputs),
       finalize: {
-        sniff: options.sniff ?? (async () => {}),
+        // The real sniff reads the file and refuses one that is not there or not a video, which is
+        // what lets a recovery ask whether a recorder's file can still become an export.
+        sniff:
+          options.sniff ??
+          (async ({ outputPath }: Readonly<{ outputPath: string }>) => {
+            if (!store.exists(outputPath)) throw new Error(`no recording file at ${outputPath}`);
+          }),
         complete: options.complete ?? (async () => ({})),
       },
       ownedProcesses: options.ownedProcesses ?? { replace: () => {}, clear: () => {} },
diff --git a/packages/platform-apple/src/recording/runtime.ts b/packages/platform-apple/src/recording/runtime.ts
index 927ad959a9..e3e5deff41 100644
--- a/packages/platform-apple/src/recording/runtime.ts
+++ b/packages/platform-apple/src/recording/runtime.ts
@@ -28,12 +28,15 @@ import {
   cleanupAppleRecording,
   createAppleRecordingEnvelope,
   reattachAppleRecording,
+  simulatorExportCoordinates,
   type AppleRecordingDescriptor,
   type AppleScreenRecordingOperationHost,
+  type AppleSimulatorExportRestore,
 } from './recovery.ts';
 import { validateAppleSimulatorRecording } from './validation.ts';
 
 const SIMULATOR_TARGET_LABEL = 'iOS recording';
+const SIMULATOR_BACKEND_LABEL = 'simctl recordVideo';
 
 export function appleScreenRecordingFacts(device: DeviceInfo) {
   if (device.appleOs === 'watchos')
@@ -61,8 +64,12 @@ export function createAppleScreenRecordingOperations(params: {
   return Object.freeze({
     screenRecordingStart: async (input) =>
       await startAppleRecording({ host, device, owner, input, signal }),
-    screenRecordingReattach: async (input) =>
-      await reattachAppleRecording(host, device, input.envelope.descriptor.body),
+    screenRecordingReattach: async (input) => {
+      const reattached = await reattachAppleRecording({ host, device, envelope: input.envelope });
+      return reattached.status === 'restore-export'
+        ? { status: 'active', handle: simulatorExportHandle({ host, restored: reattached }) }
+        : reattached;
+    },
     screenRecordingCleanup: async (input) =>
       await cleanupAppleRecording(
         host,
@@ -147,24 +154,27 @@ async function startAppleSimulatorRecording(params: AppleRecordingStartParams) {
           }),
     };
   };
+  const startedSnapshot = snapshot(input, SIMULATOR_BACKEND_LABEL, {}, clockAnchor);
   return startResult({
     device,
     owner,
     input,
-    descriptor: { backend: 'simctl', outputPath: nativePath, processes },
-    snapshot: snapshot(input, 'simctl recordVideo', {}, clockAnchor),
+    descriptor: {
+      backend: 'simctl',
+      outputPath: nativePath,
+      processes,
+      recording: simulatorExportCoordinates(startedSnapshot),
+    },
+    snapshot: startedSnapshot,
     finish: (current, progress) =>
       stopAndExportScreenRecording({
         snapshot: current,
         progress,
         steps: {
           stop: stopSimulatorRecorder,
-          // The copy gets the container sniff before it is checkpointed; the full playability verdict
-          // runs once, on the export `finalize` writes from it.
           collect: async (collectedPath) => {
             try {
-              await host.screenRecording.outputs.copy({ from: nativePath, to: collectedPath });
-              await host.screenRecording.finalize.sniff({ outputPath: collectedPath });
+              await collectSimulatorRecording(host, nativePath, collectedPath);
             } catch (collectError) {
               throw recorderExitEndedTheRecording(collectError, recorderExit, recorderResult);
             }
@@ -201,6 +211,77 @@ async function startAppleSimulatorRecording(params: AppleRecordingStartParams) {
   });
 }
 
+/**
+ * The stop a `simctl` recording gets when its recorder died with its daemon. There is no recorder left
+ * to signal and no gesture event left to burn in, and every other step is the one the first stop would
+ * have run — including which of them are still owed, which the shared sequence decides from the
+ * checkpoints the first attempt journaled.
+ */
+function simulatorExportHandle(
+  params: Readonly<{
+    host: AppleScreenRecordingOperationHost;
+    restored: AppleSimulatorExportRestore;
+  }>,
+): ScreenRecordingLiveHandle {
+  const {
+    host,
+    restored: { recording, nativePath, cleanup },
+  } = params;
+  const snapshot: ScreenRecordingLiveSnapshot = Object.freeze({
+    ...recording,
+    backend: SIMULATOR_BACKEND_LABEL,
+    gestureEvents: [],
+  });
+  return createScreenRecordingLiveHandle(snapshot, {
+    finish: (current, progress) =>
+      stopAndExportScreenRecording({
+        snapshot: current,
+        progress,
+        steps: {
+          stop: async () => ({
+            observation: { recorder: 'confirmed' as const },
+            warning:
+              'simctl recordVideo had already ended when record stop reattached to it; ' +
+              'the video covers only what the recorder wrote before it stopped.',
+          }),
+          collect: async (collectedPath) => {
+            await collectSimulatorRecording(host, nativePath, collectedPath);
+          },
+          finalize: async ({ collectedPath, exportPath }) =>
+            await finalizeAppleRecordingFromCollected({
+              host,
+              snapshot: current,
+              targetLabel: SIMULATOR_TARGET_LABEL,
+              collectedPath,
+              exportPath,
+              nativePath,
+              ...(recording.showTouches
+                ? {
+                    overlayUnavailable:
+                      'the daemon that held the touch events ended before record stop',
+                  }
+                : {}),
+            }),
+          discard: async (collectedPath) => {
+            await host.screenRecording.outputs.remove(collectedPath);
+          },
+        },
+      }),
+    forceCleanup: async () => await cleanup(),
+  });
+}
+
+async function collectSimulatorRecording(
+  host: AppleScreenRecordingOperationHost,
+  nativePath: string,
+  collectedPath: string,
+): Promise<void> {
+  // The copy gets the container sniff before it is checkpointed; the full playability verdict
+  // runs once, on the export `finalize` writes from it.
+  await host.screenRecording.outputs.copy({ from: nativePath, to: collectedPath });
+  await host.screenRecording.finalize.sniff({ outputPath: collectedPath });
+}
+
 async function startAppleRunnerRecording(params: AppleRecordingStartParams) {
   const { host, device, owner, input, signal } = params;
   const appBundleId = input.activeSessionApp?.bundleId;
diff --git a/scripts/layering/package-boundaries.test.ts b/scripts/layering/package-boundaries.test.ts
index f2f423170b..dd3402c096 100644
--- a/scripts/layering/package-boundaries.test.ts
+++ b/scripts/layering/package-boundaries.test.ts
@@ -423,6 +423,7 @@ test('the real tree parses, declares, and passes R11', () => {
     '@agent-device/capture-kit/quality-warnings',
     '@agent-device/capture-kit/react-native-overlay',
     '@agent-device/capture-kit/recording-artifact-fixtures',
+    '@agent-device/capture-kit/recording-facts',
     '@agent-device/capture-kit/recording-mp4-duration',
     '@agent-device/capture-kit/recording-mp4-fixtures',
     '@agent-device/capture-kit/recording-output-path',

From ddc0d50b9e2e7ce0256d5f3142c672cb45870e9f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Tue, 22 Sep 2026 08:56:09 +0200
Subject: [PATCH 005/132] test(ios): close the snapshot convergence evidence
 sweep at a final head (#2188) (#2750)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(ios-benchmark): wait out unmounted fixture screens during setup admission

The proxy leg stopped on `fixture-anchor` for every deep-linked screen it
reached: the persistent client reads the anchor right after `apps.open`, and
that read lands before the app mounts its first tree. Measured on the fixture
app, the snapshot taken immediately after an `open --relaunch --launch-url`
returns the single Application node, while a read 1.5s later returns 31 nodes
with the anchor. The fresh-process CLI leg hides the same gap behind its
per-read process spawn.

Setup reads are untimed, so the shared admission now re-observes until the
expected anchor is exposed, bounded by FIXTURE_ANCHOR_ADMISSION_BUDGET_MS, and
still stops the run on the same typed reason when a fixture never exposes it.
An unsuccessful observation keeps failing immediately rather than polling.

Also repairs the test module's stale `FixturePreparationResult` import: the
scripts directory is erased rather than typechecked, so the rename to
`FixtureOperationResult` went unnoticed.

* docs(evidence): record the iOS snapshot convergence final head

The sweep that gated #2188 on #2199 completed at `7c434b5758`: cold/cold-cold,
first-interaction, warm/relaunch with the package-size leg, and the 0/20/80 ms
proxy matrix, every leg clean and free of failed samples. The four Markdown
summaries ride along; the record states what the numbers prove and the
deviations that bound them — target and runtime, host load, the fixture app's
changed trees, and the 196-commit span behind the package-size delta.

Two findings that should not travel quietly: the warm snapshot daemon cost is
about double the baseline under a controlled side-by-side diagnostic, and the
#2198 slice corpora come from unmerged branch heads, so they are not parity
baselines for anything.

* chore(gates): pin the iOS snapshot convergence final corpus

`PUBLISHED_EVIDENCE` becomes `PUBLISHED_CORPORA`: the pinned evidence is now two
corpora measured at two revisions on two runtimes, each carrying its own tag and
evidence commit, and `PUBLISHED_EVIDENCE` derives from them. A missing file is
now fetched with a hint naming the corpus that actually holds it, instead of a
single tag that is wrong for one of them. Disjointness, naming, and the tag and
commit each corpus is cited by are tests rather than comments.

Also stops exporting the setup admission's internals, which the dead-code audit
rightly flags.
---
 ...s-snapshot-convergence-final-2026-09-21.md | 190 ++++++++++++++++++
 .../ios-snapshot-benchmark/evidence.test.ts   |  44 +++-
 scripts/ios-snapshot-benchmark/evidence.ts    | 103 ++++++++--
 .../ios-snapshot-benchmark/evidence/README.md |  43 +++-
 .../ios-snapshot-cold-local-7c434b575.md      |  34 ++++
 ...pshot-first-interaction-local-7c434b575.md |  28 +++
 .../evidence/ios-snapshot-proxy-7c434b575.md  |  58 ++++++
 ...-snapshot-warm-relaunch-local-7c434b575.md |  37 ++++
 .../fixture-admission.test.ts                 |  79 +++++++-
 .../fixture-admission.ts                      |  79 ++++++--
 .../proxy-client-support.test.ts              |  12 ++
 .../proxy-client-support.ts                   |  56 +++---
 12 files changed, 681 insertions(+), 82 deletions(-)
 create mode 100644 docs/evidence/ios-snapshot-convergence-final-2026-09-21.md
 create mode 100644 scripts/ios-snapshot-benchmark/evidence/ios-snapshot-cold-local-7c434b575.md
 create mode 100644 scripts/ios-snapshot-benchmark/evidence/ios-snapshot-first-interaction-local-7c434b575.md
 create mode 100644 scripts/ios-snapshot-benchmark/evidence/ios-snapshot-proxy-7c434b575.md
 create mode 100644 scripts/ios-snapshot-benchmark/evidence/ios-snapshot-warm-relaunch-local-7c434b575.md

diff --git a/docs/evidence/ios-snapshot-convergence-final-2026-09-21.md b/docs/evidence/ios-snapshot-convergence-final-2026-09-21.md
new file mode 100644
index 0000000000..37be6760cf
--- /dev/null
+++ b/docs/evidence/ios-snapshot-convergence-final-2026-09-21.md
@@ -0,0 +1,190 @@
+# iOS snapshot convergence final-head evidence
+
+- Issues: #2188 (gate), #2199 (measurement), #2189 (baseline corpus), #1571/#1626 (corpus lineage)
+- Observed: 2026-09-21, 19:03–22:52 CEST (legs sequential, one subprocess-backed gate per host)
+- Revision: `7c434b5758` (`docs/ios-snapshot-final-evidence`, clean tree at every leg; `revision.dirty: false`)
+- Target: `bench-2188-final` iPhone 17 Pro Simulator, iOS 26.2, UDID `5FEADD02-98E4-4F01-861C-07003C1A3291`
+- Host: MacBook Pro `Mac16,8`, Apple M4 Pro, 12 cores, Xcode 26.2 (17C52), Node v26.8.1
+- App: `Agent Device Tester` (`com.callstack.agentdevicelab`) from the CI artifact
+  `fingerprint.d6b4c1f5e022e54074df584e332d1e0f100c7a0f.ios` (run `35530285864`), repacked with the
+  measured head's own JavaScript bundle
+- Corpora: tag `evidence/ios-snapshot/7c434b575`, evidence commit `96d4951c19`, four files listed
+  with their SHA-256 digests in [`scripts/ios-snapshot-benchmark/evidence/README.md`](../../scripts/ios-snapshot-benchmark/evidence/README.md)
+- Baseline: tag `evidence/ios-snapshot/71fb2483f`, evidence commit `2d4baf461aa`, measured at
+  `71fb2483f3` on `bench-golden-v2` (iOS 27.0)
+
+## What this closes
+
+#2188 was gated on #2199's final exact-head evidence sweep: the package-size delta against #2189, the
+conformance/fuzz/property corpus, provider contracts, the Simulator and proxy legs, the no-regrowth
+enforcement, and a release record at a named head. All of it now exists at `7c434b5758`.
+
+The proxy leg was the last blocker, and it was blocked by the harness, not by the product. The
+anchor admission the harness gained at `71fb2483f3` reads the tree exactly once after `apps.open`.
+On this target the first tree lands later than that read: the snapshot taken immediately after an
+`open --relaunch --launch-url` returns the single `Application` node, while a read 1.5 s later
+returns 31 nodes with the `Catalog` anchor. Every deep-linked screen the leg reached stopped with
+`fixture-anchor`. `45e4c594a1..7c434b5758` puts a bounded wait into that untimed setup admission
+(`FIXTURE_ANCHOR_ADMISSION_BUDGET_MS`, 30 s, 500 ms polling) and keeps the same typed stop when a
+fixture never exposes its anchor. No `src/`, `packages/`, app, or CLI runtime file differs between
+those two commits; the measured binary is the measured head's own `pnpm build` output.
+
+## Deviations from the baseline corpus
+
+Stated in full, because they bound what these numbers can prove.
+
+| Deviation | This corpus | Baseline corpus |
+| --- | --- | --- |
+| Simulator and runtime | `bench-2188-final`, iOS 26.2 | `bench-golden-v2`, iOS 27.0 |
+| Why | `bench-golden-v2`'s iOS 27.0 runtime was not installed on this host at measurement time | — |
+| Host load (1-min average, sampled per leg) | warm/relaunch 4.2–31.2, proxy 6.4–30.3, cold 5.3–96.7 | quiet |
+| Fixture app trees | catalog 31 nodes, nested-scroll 23, checkout 25, alert 26, Settings 18, inert 4 | catalog 35, nested-scroll 25, checkout 29, alert 28, Settings 18, inert 6 |
+| Package-size span | `71fb2483f3..7c434b5758`: 196 commits of unrelated product work | — |
+
+Because the fixture trees differ, response sizes are not comparable cell for cell, and any timing
+delta on a screen whose tree changed is only partly attributable to the tooling. Timings are bounded
+observations under uncontrolled host load, not a general performance guarantee.
+
+## Result — cold and cold-cold (10 samples per cell, fresh CLI process)
+
+| State | Screen | Wall median | Wall median (base) | Daemon median | Daemon median (base) |
+| --- | --- | ---: | ---: | ---: | ---: |
+| cold-cold | quiet | 7,159 | 17,544 | 5,709 | 15,161 |
+| cold-cold | list | 7,580 | 19,170 | 5,881 | 17,191 |
+| cold-cold | nested-scroll | 8,091 | 19,407 | 6,374 | 17,773 |
+| cold-cold | alert | 7,461 | 19,448 | 5,689 | 17,436 |
+| cold-cold | system-surface | 6,553 | 20,235 | 4,961 | 17,974 |
+| cold-cold | xctest-stress | 7,273 | 20,811 | 5,761 | 18,506 |
+| cold | quiet | 5,743 | 6,643 | 4,409 | 5,886 |
+| cold | list | 5,847 | 6,851 | 4,420 | 5,897 |
+| cold | nested-scroll | 6,058 | 6,713 | 4,619 | 5,884 |
+| cold | alert | 5,706 | 6,674 | 4,310 | 5,868 |
+| cold | system-surface | 5,028 | 6,819 | 3,662 | 5,957 |
+| cold | xctest-stress | 5,679 | 6,714 | 4,323 | 5,874 |
+
+Milliseconds. `cold-cold` shuts the Simulator down, clears benchmark-owned derived data, and boots it
+again before every sample; `cold` stops the daemon and terminates the app. Cold-cold wall medians
+fall by 57–68% and daemon medians by 62–72% against the baseline, measured while this host carried
+substantially more load than the baseline's. Cold (booted Simulator, cold runner) improves by 9–26%.
+
+## Result — warm, relaunch, and first interaction
+
+Warm and relaunch carry 20 samples per cell; first interaction carries 10 and has no baseline-corpus
+counterpart, so it is reported on its own.
+
+| Screen | Warm wall | Warm wall (base) | Warm daemon | Warm daemon (base) | Relaunch wall | Relaunch wall (base) | First interaction wall |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
+| quiet | 169 | 154 | 89 | 50 | 3,876 | 3,645 | 928 |
+| list | 291 | 312 | 202 | 209 | 3,888 | 4,378 | 1,436 |
+| nested-scroll | 250 | 187 | 167 | 83 | 3,872 | 4,313 | 741 |
+| alert | 224 | 207 | 139 | 104 | 3,896 | 4,370 | 1,005 |
+| system-surface | 208 | 210 | 130 | 105 | 3,576 | 4,917 | 1,119 |
+| xctest-stress | 213 | 208 | 128 | 105 | 3,868 | 4,260 | 1,302 |
+
+Milliseconds. Relaunch is at or better than the baseline on five of six screens. Warm wall is within
+±10% of the baseline on five of six screens; warm daemon duration is uniformly higher, which is the
+finding below.
+
+## Result — proxy transport (20 samples per screen at each added RTT)
+
+The headline of the convergence work: a warm snapshot crossed the tunnel with far fewer round trips
+than at the baseline, so added latency costs far less.
+
+| Screen | Transport | 0 ms | 20 ms | 80 ms | 0 ms (base) | 20 ms (base) | 80 ms (base) |
+| --- | --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| quiet | fresh CLI | 184 | 293 | 556 | 233 | 1,057 | 1,801 |
+| quiet | persistent client | 103 | 158 | 282 | 273 | 562 | 806 |
+| list | fresh CLI | 304 | 415 | 691 | 431 | 1,221 | 1,328 |
+| list | persistent client | 214 | 280 | 408 | 254 | 719 | 729 |
+| nested-scroll | fresh CLI | 260 | 377 | 643 | 188 | 1,116 | 1,108 |
+| nested-scroll | persistent client | 179 | 240 | 381 | 138 | 590 | 616 |
+| alert | fresh CLI | 241 | 343 | 615 | 210 | 1,113 | 1,362 |
+| alert | persistent client | 148 | 203 | 351 | 108 | 622 | 637 |
+| system-surface | fresh CLI | 217 | 319 | 595 | 209 | 1,119 | 1,145 |
+| system-surface | persistent client | 128 | 183 | 330 | 105 | 537 | 638 |
+| xctest-stress | fresh CLI | 229 | 340 | 562 | 225 | 1,136 | 1,395 |
+| xctest-stress | persistent client | 136 | 197 | 314 | 127 | 612 | 619 |
+
+Milliseconds, wall-clock medians. Going from 0 to 80 ms of added RTT costs 178–387 ms per snapshot
+here, against 475–1,568 ms at the baseline. On the quiet fixture over the fresh CLI transport that
+difference is about twenty RTT-bound exchanges per snapshot at the baseline against about five here;
+over the persistent client it is about seven against about two. Every cell completed with zero failed
+samples at every RTT, so the retry/timeout path is not what improved.
+
+## Result — package size against #2189
+
+| Measurement | `7c434b5758` | `71fb2483f3` | Delta |
+| --- | ---: | ---: | ---: |
+| Packed tarball | 1,409,306 B | 982,960 B | +43.4% |
+| Clean-installed package | 4,723,895 B / 543 files | 3,347,347 B / 436 files | +41.1% / +107 |
+| Bundled JavaScript | 3,775,024 B raw, 1,258,950 B gzip, 410 files | 2,480,947 B raw, 835,279 B gzip, 330 files | +52.2% raw, +50.7% gzip |
+
+The span covers 196 commits of unrelated product work, so this delta cannot be attributed to the
+snapshot convergence alone; it is recorded as the size at the measured head, and the leg reproduces
+to the byte across independent runs (the same `1,409,306` tarball twice).
+
+## Result — deterministic corpus and no-regrowth enforcement
+
+| Gate | Command | Result |
+| --- | --- | --- |
+| Swift/TypeScript presentation differential | `pnpm test:ios-snapshot-differential` | pass (`swift test --package-path apple/snapshot-presentation`, plus 3 differential tests) |
+| Engine conformance, properties, transitions, tree | `vitest run packages/capture-kit/src/ios-snapshot-engine` | pass (10 files, 67 tests) |
+| Fuzz corpus replay | `vitest run scripts/fuzz/corpus-replay.test.ts` | pass (11 cases) |
+| Fuzz worker lane | `pnpm test:fuzz-worker` | pass (11 cases) |
+| Provider contracts | `pnpm test:integration:provider` | pass (66 files, 212 tests) |
+| No-regrowth rules R72/R73/R74 | `pnpm check:layering` | pass (`ios-snapshot-engine-ownership`, `provider-snapshot-presentation-ownership`, `snapshot-assembly-presentation-neutrality`, wired in `scripts/layering/check.ts`) |
+| Benchmark harness unit suite | `vitest run scripts/ios-snapshot-benchmark` | pass (17 files, 50 tests) |
+| Deep-button controls | inside every corpus (`deepButtonEvidence`) | the shallow-rule control exits 1 with "changed descendant was omitted by shallow observation"; the safe control exits 0 |
+| Affected gate | `pnpm check:affected --run` | see the PR; GitHub stays authoritative for provider integration, coverage, native builds, and device lanes |
+
+## Finding — warm snapshot daemon cost is about double the baseline
+
+Recorded here rather than hidden, and not explained by target, runtime, app, or load.
+
+An off-corpus controlled diagnostic: same Simulator, same installed app, same ambient load
+(1-minute average ~21), back-to-back runs of ten warm `interactiveOnly` snapshots of the smallest
+fixture (4 nodes, ~3.4 KB), reading the daemon's own per-step duration.
+
+| CLI under test | Durations (ms) | Median |
+| --- | --- | ---: |
+| `71fb2483f3` (baseline corpus head) | 68, 47, 46, 44, 43, 43, 43, 45, 47, 46 | 45.5 |
+| `7c434b5758` (this head), round 1 | 97, 86, 84, 90, 84, 86, 86, 92, 83, 82 | 86 |
+| `7c434b5758` (this head), round 2 | 98, 133, 96, 96, 88, 90, 87, 94, 107, 103 | 96 |
+
+The published warm cells agree with the diagnostic (89–202 ms against the baseline's 50–209 ms), and
+a repeat at a 1-minute load average of 3.8 still measured 86 ms, so contention is not the cause. The
+shape is a roughly fixed ~40 ms per snapshot rather than work proportional to tree size. Candidates
+in `71fb2483f3..7c434b5758` that add work to every capture: #2644 (reading the `NotEnabled` trait per
+node), #2670 (publishing the captured keyboard band as a fact), #2693 (disclosing target
+re-activation on every capture-consuming command), and #2661 (the single geometry-normalization
+pass). This does not weaken the claims the corpora were measured for — one converged snapshot path,
+no presentation branching in the assembly, the RTT and cold-cold improvements above — but it is a
+real cost this head carries and it needs its own follow-up.
+
+## Correction — the #2198 slice corpora are not parity baselines
+
+The slice corpora published under `2198-slice-a-7616ba222d/`,
+`2198-slice-a-first-interaction-fixed-e729321dcc/`, and `2198-slice-b-rtt-318d510769/` were measured
+on branch heads (`7616ba222d`, `9189275dcb`, `e729321dcc`) that are **not ancestors** of `main`, and
+two of their first-interaction cells carry ten failed samples each (the ambiguous-anchor harness bug
+those slices themselves fixed). They are cited here as branch-lineage observations only. The pinned
+`71fb2483f3` corpus is the comparison this record rests on.
+
+## Reproduction
+
+```sh
+# one dedicated simulator, app installed, nothing else running a device
+pnpm bench:ios-snapshot -- --udid <UDID> --screen quiet,list,nested-scroll,alert,system-surface,xctest-stress \
+  --mode local --state cold-cold,cold --samples 10 --skip-package-size --out .tmp/cold.json
+pnpm bench:ios-snapshot -- --udid <UDID> --screen quiet,list,nested-scroll,alert,system-surface,xctest-stress \
+  --mode local --state first-interaction --samples 10 --skip-package-size --out .tmp/first.json
+pnpm bench:ios-snapshot -- --udid <UDID> --screen quiet,list,nested-scroll,alert,system-surface,xctest-stress \
+  --mode local --state warm,relaunch --samples 20 --out .tmp/warm-relaunch.json
+pnpm bench:ios-snapshot -- --udid <UDID> --screen quiet,list,nested-scroll,alert,system-surface,xctest-stress \
+  --mode proxy --rtt 0,20,80 --samples 20 --bandwidth-kbps unlimited --packet-loss 0 --skip-package-size \
+  --out .tmp/proxy.json
+pnpm bench:ios-snapshot:evidence   # schema and hash check against PUBLISHED_CORPORA
+```
+
+Legs must not overlap: one subprocess-backed gate per host, otherwise the samples contend and the
+cell admission stops the run rather than reporting mixed timings.
diff --git a/scripts/ios-snapshot-benchmark/evidence.test.ts b/scripts/ios-snapshot-benchmark/evidence.test.ts
index dc69e244f1..b34a16868e 100644
--- a/scripts/ios-snapshot-benchmark/evidence.test.ts
+++ b/scripts/ios-snapshot-benchmark/evidence.test.ts
@@ -6,6 +6,7 @@ import { afterEach, test } from 'vitest';
 import {
   DEFAULT_EVIDENCE_DIR,
   EVIDENCE_FIXTURE_PATH,
+  PUBLISHED_CORPORA,
   PUBLISHED_EVIDENCE,
   checkEvidenceCorpus,
   fetchEvidenceCommand,
@@ -80,13 +81,32 @@ test('the evidence README cites every published hash and the fetch recipe', () =
   assert.ok(readme.includes(fetchEvidenceCommand()));
 });
 
-function oneOfThreePublishedFiles(): EvidenceFile {
-  const [file, sha256] = Object.entries(PUBLISHED_EVIDENCE)[0]!;
+test('each published corpus is disjoint, named for its revision, and cited by tag and commit', () => {
+  const readme = fs.readFileSync(path.join(DEFAULT_EVIDENCE_DIR, 'README.md'), 'utf8');
+  const seen = new Set<string>();
+  for (const corpus of PUBLISHED_CORPORA) {
+    assert.match(corpus.tag, /^refs\/tags\/evidence\/ios-snapshot\/[0-9a-f]{9,}$/);
+    assert.match(corpus.commit, /^[0-9a-f]{40}$/);
+    assert.ok(readme.includes(corpus.tag), `README does not cite ${corpus.tag}`);
+    assert.ok(readme.includes(corpus.commit), `README does not cite ${corpus.commit}`);
+    for (const file of Object.keys(corpus.files)) {
+      assert.ok(!seen.has(file), `${file} is published by two corpora`);
+      seen.add(file);
+      assert.ok(
+        file.endsWith(`-${corpus.tag.split('/').pop()}.json`),
+        `${file} is not named for ${corpus.tag}`,
+      );
+    }
+  }
+});
+
+function onePublishedFile(): EvidenceFile {
+  const [file, sha256] = Object.entries(PUBLISHED_CORPORA[0]!.files)[0]!;
   return {
     file,
     sha256,
     published: 'match',
-    revision: '71fb2483f30d90e615e949601c836aeebbf450c5',
+    revision: PUBLISHED_CORPORA[0]!.revision,
     status: 'completed',
     cells: 2,
     errors: [],
@@ -95,15 +115,23 @@ function oneOfThreePublishedFiles(): EvidenceFile {
 
 test('the default evidence directory must hold the complete published corpus, named files and all', () => {
   const dir = temporaryEvidenceDir({});
-  assert.throws(
-    () => checkEvidenceCorpus(dir, [oneOfThreePublishedFiles()], true),
-    /is missing published evidence file\(s\): ios-snapshot-warm-relaunch-local-71fb2483f\.json, ios-snapshot-proxy-71fb2483f\.json/,
-  );
+  const present = onePublishedFile();
+  let message = '';
+  try {
+    checkEvidenceCorpus(dir, [present], true);
+  } catch (error) {
+    message = error instanceof Error ? error.message : String(error);
+  }
+  assert.match(message, /is missing published evidence file\(s\)/);
+  for (const file of Object.keys(PUBLISHED_EVIDENCE)) {
+    if (file === present.file) continue;
+    assert.ok(message.includes(file), `the error omits ${file}`);
+  }
 });
 
 test('an explicit --evidence-dir stays permissive: a partial corpus does not fail completeness', () => {
   const dir = temporaryEvidenceDir({});
-  assert.doesNotThrow(() => checkEvidenceCorpus(dir, [oneOfThreePublishedFiles()], false));
+  assert.doesNotThrow(() => checkEvidenceCorpus(dir, [onePublishedFile()], false));
 });
 
 test('fetched evidence under the in-tree directory matches the published corpus', (context) => {
diff --git a/scripts/ios-snapshot-benchmark/evidence.ts b/scripts/ios-snapshot-benchmark/evidence.ts
index eb52b04cd6..778b4203fe 100644
--- a/scripts/ios-snapshot-benchmark/evidence.ts
+++ b/scripts/ios-snapshot-benchmark/evidence.ts
@@ -6,25 +6,63 @@ import { validateRawResult } from './schema.ts';
 import type { BenchmarkResult } from './types.ts';
 
 /**
- * The evidence/ios-snapshot branch tip is mutable; this annotated tag and the full commit SHA
- * below are the durable, immutable ref the corpus is pinned to. Re-tag (a new suffix, a new
- * commit) if the corpus is ever re-measured — never move this tag.
+ * Each corpus is pinned by an annotated tag on the mutable `evidence/ios-snapshot` branch tip plus
+ * the full evidence commit below. Re-tag (a new suffix, a new commit) if a corpus is ever
+ * re-measured — never move these tags.
  */
-const EVIDENCE_TAG = 'refs/tags/evidence/ios-snapshot/71fb2483f';
-const EVIDENCE_COMMIT = '2d4baf461aa8897d49c6d4683cd16d8f43588ae8';
-export const DEFAULT_EVIDENCE_DIR = path.join(import.meta.dirname, 'evidence');
-export const EVIDENCE_FIXTURE_PATH = path.join(import.meta.dirname, 'evidence-fixture.v1.json');
+export type PublishedCorpus = {
+  /** Revision the leg measured, as a full SHA. */
+  revision: string;
+  /** Durable ref the corpus is fetched from. */
+  tag: string;
+  /** Evidence-branch commit holding the files. */
+  commit: string;
+  /** Corpus file name -> sha256. */
+  files: Readonly<Record<string, string>>;
+};
+
+const BASELINE_CORPUS: PublishedCorpus = {
+  revision: '71fb2483f30d90e615e949601c836aeebbf450c5',
+  tag: 'refs/tags/evidence/ios-snapshot/71fb2483f',
+  commit: '2d4baf461aa8897d49c6d4683cd16d8f43588ae8',
+  files: {
+    'ios-snapshot-cold-local-71fb2483f.json':
+      '532a83247bfbf8ee47039f80ac429f067c84679e92c781768c1044da1ae6e9bf',
+    'ios-snapshot-warm-relaunch-local-71fb2483f.json':
+      '6d299e8baec69662dca2c1ad8f1348e4361d5afaa781080e9a6b9b3dac362cbf',
+    'ios-snapshot-proxy-71fb2483f.json':
+      'b11b7a07be9e4dcf003f3af66943682a6733c6f21f5f43d3d9e88b3fb37b51a7',
+  },
+};
 
-/** Raw results published on the evidence branch, keyed by file name; measured at 71fb2483f. */
-export const PUBLISHED_EVIDENCE: Readonly<Record<string, string>> = {
-  'ios-snapshot-cold-local-71fb2483f.json':
-    '532a83247bfbf8ee47039f80ac429f067c84679e92c781768c1044da1ae6e9bf',
-  'ios-snapshot-warm-relaunch-local-71fb2483f.json':
-    '6d299e8baec69662dca2c1ad8f1348e4361d5afaa781080e9a6b9b3dac362cbf',
-  'ios-snapshot-proxy-71fb2483f.json':
-    'b11b7a07be9e4dcf003f3af66943682a6733c6f21f5f43d3d9e88b3fb37b51a7',
+const CONVERGENCE_FINAL_CORPUS: PublishedCorpus = {
+  revision: '7c434b575837e3291c51315bf9bb8b54c8ce7568',
+  tag: 'refs/tags/evidence/ios-snapshot/7c434b575',
+  commit: '96d4951c19fbe009ba19d192a9774668edcc3f56',
+  files: {
+    'ios-snapshot-cold-local-7c434b575.json':
+      '4663897ee5104569ad54e2ac803c216b284280c1c70fd82a8b2cf7b675d8a8bd',
+    'ios-snapshot-first-interaction-local-7c434b575.json':
+      '87c686336f5581e3f18111e160cf7b733cd726b41e79ed6d8e5b53e2ab40c3fb',
+    'ios-snapshot-warm-relaunch-local-7c434b575.json':
+      'd49df3c3c943178f016a2b958449b257c6d46a44c8ffdf8fab75c1634ae1ebce',
+    'ios-snapshot-proxy-7c434b575.json':
+      '5b5353831851f3a0f60e19d6bfd0cf50db47c3c4db52a283024c10bb17e71573',
+  },
 };
 
+export const PUBLISHED_CORPORA: readonly PublishedCorpus[] = [
+  BASELINE_CORPUS,
+  CONVERGENCE_FINAL_CORPUS,
+];
+
+/** Raw results published on the evidence branch, keyed by file name across every corpus. */
+export const PUBLISHED_EVIDENCE: Readonly<Record<string, string>> = Object.fromEntries(
+  PUBLISHED_CORPORA.flatMap((corpus) => Object.entries(corpus.files)),
+);
+export const DEFAULT_EVIDENCE_DIR = path.join(import.meta.dirname, 'evidence');
+export const EVIDENCE_FIXTURE_PATH = path.join(import.meta.dirname, 'evidence-fixture.v1.json');
+
 export type EvidenceFile = {
   file: string;
   sha256: string;
@@ -35,9 +73,31 @@ export type EvidenceFile = {
   errors: string[];
 };
 
-export function fetchEvidenceCommand(file = '<file>'): string {
+function corpusFetchCommand(corpus: PublishedCorpus, file: string): string {
   const destination = path.posix.join('scripts/ios-snapshot-benchmark/evidence', file);
-  return `git fetch origin ${EVIDENCE_TAG} && git show ${EVIDENCE_COMMIT}:${file} > ${destination}`;
+  return `git show ${corpus.commit}:${file} > ${destination}`;
+}
+
+/**
+ * The fetch recipe for one corpus file. An unknown name falls back to the newest corpus, which is
+ * what a generic hint should recommend.
+ */
+export function fetchEvidenceCommand(file = '<file>'): string {
+  const corpus =
+    PUBLISHED_CORPORA.find((candidate) => file in candidate.files) ?? PUBLISHED_CORPORA.at(-1)!;
+  return `git fetch origin ${corpus.tag} && ${corpusFetchCommand(corpus, file)}`;
+}
+
+/** One shell line per corpus that holds any of `files`, so a hint never names the wrong commit. */
+function fetchEvidenceCommands(files: readonly string[]): string {
+  const lines: string[] = [];
+  for (const corpus of PUBLISHED_CORPORA) {
+    const missing = files.filter((file) => file in corpus.files);
+    if (missing.length === 0) continue;
+    const fetches = missing.map((file) => corpusFetchCommand(corpus, file));
+    lines.push(`git fetch origin ${corpus.tag} && ${fetches.join(' && ')}`);
+  }
+  return lines.join('\n');
 }
 
 export function listEvidenceFiles(dir: string): string[] {
@@ -133,8 +193,8 @@ export function checkEvidenceCorpus(dir: string, files: EvidenceFile[], isDefaul
     const missing = missingPublishedEvidence(files);
     if (missing.length > 0) {
       throw new Error(
-        `${dir} is missing published evidence file(s): ${missing.join(', ')}. Fetch them with: ` +
-          `${fetchEvidenceCommand()}`,
+        `${dir} is missing published evidence file(s): ${missing.join(', ')}.\n` +
+          `Fetch them with:\n${fetchEvidenceCommands(missing)}`,
       );
     }
   }
@@ -144,7 +204,10 @@ function runEvidenceReport(argv: string[]): void {
   const { dir, isDefault } = readEvidenceDirOption(argv);
   const files = readEvidenceDir(dir);
   if (files.length === 0) {
-    throw new Error(`${dir} holds no evidence; fetch it with: ${fetchEvidenceCommand()}`);
+    throw new Error(
+      `${dir} holds no evidence; fetch it with:\n` +
+        `${fetchEvidenceCommands(Object.keys(PUBLISHED_EVIDENCE))}`,
+    );
   }
   process.stdout.write(renderEvidenceReport(dir, files));
   checkEvidenceCorpus(dir, files, isDefault);
diff --git a/scripts/ios-snapshot-benchmark/evidence/README.md b/scripts/ios-snapshot-benchmark/evidence/README.md
index b91bfaae2e..2945b81618 100644
--- a/scripts/ios-snapshot-benchmark/evidence/README.md
+++ b/scripts/ios-snapshot-benchmark/evidence/README.md
@@ -1,12 +1,16 @@
 # iOS snapshot benchmark evidence
 
-The raw `pnpm bench:ios-snapshot` results measured at commit
-`71fb2483f30d90e615e949601c836aeebbf450c5` on `bench-golden-v2` (iPhone 17 Pro, iOS 27.0) live on
-the orphan branch `evidence/ios-snapshot`, not in this tree. The branch tip is mutable; the durable
-ref is the annotated tag `evidence/ios-snapshot/71fb2483f`, pinned to commit
-`2d4baf461aa8897d49c6d4683cd16d8f43588ae8` — fetch and read from the tag and that full SHA, never
-from the branch tip. Only Markdown summaries are kept here. The published hashes are declared in
-[`../evidence.ts`](../evidence.ts) as `PUBLISHED_EVIDENCE`:
+The raw `pnpm bench:ios-snapshot` results live on the orphan branch `evidence/ios-snapshot`, not in
+this tree. The branch tip is mutable; the durable refs are the annotated tags and full commits
+below — fetch from those, never from the branch tip. Only Markdown summaries are kept here. The
+published hashes are declared in [`../evidence.ts`](../evidence.ts) as `PUBLISHED_CORPORA`, and
+[`../evidence.ts`](../evidence.ts) derives `PUBLISHED_EVIDENCE` from them.
+
+## Baseline corpus — `71fb2483f`
+
+Measured at commit `71fb2483f30d90e615e949601c836aeebbf450c5` on `bench-golden-v2` (iPhone 17 Pro,
+iOS 27.0). Tag `refs/tags/evidence/ios-snapshot/71fb2483f`, commit
+`2d4baf461aa8897d49c6d4683cd16d8f43588ae8`.
 
 | File | sha256 |
 | --- | --- |
@@ -14,12 +18,28 @@ from the branch tip. Only Markdown summaries are kept here. The published hashes
 | `ios-snapshot-warm-relaunch-local-71fb2483f.json` | `6d299e8baec69662dca2c1ad8f1348e4361d5afaa781080e9a6b9b3dac362cbf` |
 | `ios-snapshot-proxy-71fb2483f.json` | `b11b7a07be9e4dcf003f3af66943682a6733c6f21f5f43d3d9e88b3fb37b51a7` |
 
+## Convergence final corpus — `7c434b575`
+
+Measured at commit `7c434b575837e3291c51315bf9bb8b54c8ce7568` on `bench-2188-final` (iPhone 17 Pro,
+iOS 26.2). Tag `refs/tags/evidence/ios-snapshot/7c434b575`, commit
+`96d4951c19fbe009ba19d192a9774668edcc3f56`. This is the corpus that closed the evidence sweep
+gating #2188 on #2199; [`../../../docs/evidence/ios-snapshot-convergence-final-2026-09-21.md`](../../../docs/evidence/ios-snapshot-convergence-final-2026-09-21.md)
+reads it against the baseline, including the target, runtime, host-load, app, and harness
+deviations between the two corpora.
+
+| File | sha256 |
+| --- | --- |
+| `ios-snapshot-cold-local-7c434b575.json` | `4663897ee5104569ad54e2ac803c216b284280c1c70fd82a8b2cf7b675d8a8bd` |
+| `ios-snapshot-first-interaction-local-7c434b575.json` | `87c686336f5581e3f18111e160cf7b733cd726b41e79ed6d8e5b53e2ab40c3fb` |
+| `ios-snapshot-warm-relaunch-local-7c434b575.json` | `d49df3c3c943178f016a2b958449b257c6d46a44c8ffdf8fab75c1634ae1ebce` |
+| `ios-snapshot-proxy-7c434b575.json` | `5b5353831851f3a0f60e19d6bfd0cf50db47c3c4db52a283024c10bb17e71573` |
+
 ## Fetch
 
 One file, from the repository root:
 
 ```sh
-git fetch origin refs/tags/evidence/ios-snapshot/71fb2483f && git show 2d4baf461aa8897d49c6d4683cd16d8f43588ae8:<file> > scripts/ios-snapshot-benchmark/evidence/<file>
+git fetch origin refs/tags/evidence/ios-snapshot/7c434b575 && git show 96d4951c19fbe009ba19d192a9774668edcc3f56:<file> > scripts/ios-snapshot-benchmark/evidence/<file>
 ```
 
 The whole corpus, then a schema and hash check:
@@ -31,6 +51,13 @@ for f in ios-snapshot-cold-local-71fb2483f.json \
          ios-snapshot-proxy-71fb2483f.json; do
   git show 2d4baf461aa8897d49c6d4683cd16d8f43588ae8:$f > scripts/ios-snapshot-benchmark/evidence/$f
 done
+git fetch origin refs/tags/evidence/ios-snapshot/7c434b575
+for f in ios-snapshot-cold-local-7c434b575.json \
+         ios-snapshot-first-interaction-local-7c434b575.json \
+         ios-snapshot-warm-relaunch-local-7c434b575.json \
+         ios-snapshot-proxy-7c434b575.json; do
+  git show 96d4951c19fbe009ba19d192a9774668edcc3f56:$f > scripts/ios-snapshot-benchmark/evidence/$f
+done
 pnpm bench:ios-snapshot:evidence
 ```
 
diff --git a/scripts/ios-snapshot-benchmark/evidence/ios-snapshot-cold-local-7c434b575.md b/scripts/ios-snapshot-benchmark/evidence/ios-snapshot-cold-local-7c434b575.md
new file mode 100644
index 0000000000..76fc7a93cf
--- /dev/null
+++ b/scripts/ios-snapshot-benchmark/evidence/ios-snapshot-cold-local-7c434b575.md
@@ -0,0 +1,34 @@
+# iOS snapshot convergence benchmark
+
+- Status: **completed**
+- Revision: 7c434b575837e3291c51315bf9bb8b54c8ce7568
+- Host: MacBook Pro (Mac16,8; Apple M4 Pro, 12 cores)
+- Target: bench-2188-final (5FEADD02-98E4-4F01-861C-07003C1A3291, com.apple.CoreSimulator.SimRuntime.iOS-26-2)
+- Generated: 2026-09-21T20:51:31.618Z
+
+| State | Screen | Transport | Execution | N | Wall median | Wall p95 | Daemon median | Response median | Failures |
+|---|---|---|---|---:|---:|---:|---:|---:|---:|
+| cold-cold | quiet | local | fresh-process-cli | 10 | 7159.1 | 9060.7 | 5709.0 | 4365.0 | 0 |
+| cold-cold | list | local | fresh-process-cli | 10 | 7580.2 | 9145.6 | 5881.0 | 18206.0 | 0 |
+| cold-cold | nested-scroll | local | fresh-process-cli | 10 | 8091.3 | 9339.9 | 6374.0 | 13423.0 | 0 |
+| cold-cold | alert | local | fresh-process-cli | 10 | 7460.8 | 10034.7 | 5689.0 | 16035.0 | 0 |
+| cold-cold | system-surface | local | fresh-process-cli | 10 | 6553.0 | 9585.4 | 4961.0 | 11342.0 | 0 |
+| cold-cold | xctest-stress | local | fresh-process-cli | 10 | 7273.4 | 9747.5 | 5761.0 | 16106.0 | 0 |
+| cold | quiet | local | fresh-process-cli | 10 | 5743.0 | 6533.9 | 4409.0 | 4337.0 | 0 |
+| cold | list | local | fresh-process-cli | 10 | 5847.5 | 6055.3 | 4420.0 | 17277.0 | 0 |
+| cold | nested-scroll | local | fresh-process-cli | 10 | 6057.6 | 6525.3 | 4619.0 | 12214.0 | 0 |
+| cold | alert | local | fresh-process-cli | 10 | 5706.1 | 5874.5 | 4310.0 | 15105.0 | 0 |
+| cold | system-surface | local | fresh-process-cli | 10 | 5028.5 | 5436.4 | 3662.0 | 12586.0 | 0 |
+| cold | xctest-stress | local | fresh-process-cli | 10 | 5679.0 | 5870.3 | 4323.0 | 14364.0 | 0 |
+
+## Package size
+
+Not measured.
+
+## Deep-button control
+
+- Fixture artifact: deep-button-fixture.v1.json (depth 72)
+- Red control: pnpm bench:ios-snapshot:deep-button -- --rule invalid-shallow (exit 1)
+  - AssertionError: changed descendant was omitted by shallow observation; no-effect claim is invalid.
+- Safe control: pnpm bench:ios-snapshot:deep-button -- --rule safe-full (exit 0)
+  - full observation changed and includes the changed descendant.
diff --git a/scripts/ios-snapshot-benchmark/evidence/ios-snapshot-first-interaction-local-7c434b575.md b/scripts/ios-snapshot-benchmark/evidence/ios-snapshot-first-interaction-local-7c434b575.md
new file mode 100644
index 0000000000..3bf86628d2
--- /dev/null
+++ b/scripts/ios-snapshot-benchmark/evidence/ios-snapshot-first-interaction-local-7c434b575.md
@@ -0,0 +1,28 @@
+# iOS snapshot convergence benchmark
+
+- Status: **completed**
+- Revision: 7c434b575837e3291c51315bf9bb8b54c8ce7568
+- Host: MacBook Pro (Mac16,8; Apple M4 Pro, 12 cores)
+- Target: bench-2188-final (5FEADD02-98E4-4F01-861C-07003C1A3291, com.apple.CoreSimulator.SimRuntime.iOS-26-2)
+- Generated: 2026-09-21T19:20:51.180Z
+
+| State | Screen | Transport | Execution | N | Wall median | Wall p95 | Daemon median | Response median | Failures |
+|---|---|---|---|---:|---:|---:|---:|---:|---:|
+| first-interaction | quiet | local | fresh-process-cli | 10 | 928.2 | 1189.3 | – | 567.0 | 0 |
+| first-interaction | list | local | fresh-process-cli | 10 | 1435.7 | 1707.0 | – | 615.0 | 0 |
+| first-interaction | nested-scroll | local | fresh-process-cli | 10 | 741.1 | 1241.7 | – | 579.0 | 0 |
+| first-interaction | alert | local | fresh-process-cli | 10 | 1005.4 | 1018.1 | – | 546.0 | 0 |
+| first-interaction | system-surface | local | fresh-process-cli | 10 | 1119.4 | 2051.8 | – | 548.0 | 0 |
+| first-interaction | xctest-stress | local | fresh-process-cli | 10 | 1302.4 | 1341.0 | – | 539.0 | 0 |
+
+## Package size
+
+Not measured.
+
+## Deep-button control
+
+- Fixture artifact: deep-button-fixture.v1.json (depth 72)
+- Red control: pnpm bench:ios-snapshot:deep-button -- --rule invalid-shallow (exit 1)
+  - AssertionError: changed descendant was omitted by shallow observation; no-effect claim is invalid.
+- Safe control: pnpm bench:ios-snapshot:deep-button -- --rule safe-full (exit 0)
+  - full observation changed and includes the changed descendant.
diff --git a/scripts/ios-snapshot-benchmark/evidence/ios-snapshot-proxy-7c434b575.md b/scripts/ios-snapshot-benchmark/evidence/ios-snapshot-proxy-7c434b575.md
new file mode 100644
index 0000000000..3a827fb98b
--- /dev/null
+++ b/scripts/ios-snapshot-benchmark/evidence/ios-snapshot-proxy-7c434b575.md
@@ -0,0 +1,58 @@
+# iOS snapshot convergence benchmark
+
+- Status: **completed**
+- Revision: 7c434b575837e3291c51315bf9bb8b54c8ce7568
+- Host: MacBook Pro (Mac16,8; Apple M4 Pro, 12 cores)
+- Target: bench-2188-final (5FEADD02-98E4-4F01-861C-07003C1A3291, com.apple.CoreSimulator.SimRuntime.iOS-26-2)
+- Generated: 2026-09-21T20:02:38.671Z
+
+| State | Screen | Transport | Execution | N | Wall median | Wall p95 | Daemon median | Response median | Failures |
+|---|---|---|---|---:|---:|---:|---:|---:|---:|
+| warm | quiet | proxy | persistent-client | 20 | 102.9 | 109.9 | 94.0 | 1843.0 | 0 |
+| warm | quiet | proxy | fresh-process-cli | 20 | 183.8 | 196.2 | 93.0 | 1841.0 | 0 |
+| warm | list | proxy | persistent-client | 20 | 214.4 | 230.7 | 205.0 | 8869.0 | 0 |
+| warm | list | proxy | fresh-process-cli | 20 | 304.5 | 315.8 | 208.0 | 8869.0 | 0 |
+| warm | nested-scroll | proxy | persistent-client | 20 | 179.4 | 283.4 | 171.0 | 5784.0 | 0 |
+| warm | nested-scroll | proxy | fresh-process-cli | 20 | 260.2 | 299.2 | 168.0 | 5787.0 | 0 |
+| warm | alert | proxy | persistent-client | 20 | 148.4 | 154.1 | 140.0 | 7961.0 | 0 |
+| warm | alert | proxy | fresh-process-cli | 20 | 240.7 | 251.6 | 147.0 | 7961.0 | 0 |
+| warm | system-surface | proxy | persistent-client | 20 | 127.9 | 159.7 | 119.0 | 5758.0 | 0 |
+| warm | system-surface | proxy | fresh-process-cli | 20 | 217.3 | 246.0 | 125.0 | 5758.0 | 0 |
+| warm | xctest-stress | proxy | persistent-client | 20 | 135.8 | 149.7 | 128.0 | 7252.0 | 0 |
+| warm | xctest-stress | proxy | fresh-process-cli | 20 | 228.6 | 235.2 | 139.0 | 7252.0 | 0 |
+| warm | quiet | proxy | persistent-client | 20 | 157.6 | 164.2 | 101.0 | 1842.0 | 0 |
+| warm | quiet | proxy | fresh-process-cli | 20 | 293.1 | 300.6 | 105.0 | 1844.0 | 0 |
+| warm | list | proxy | persistent-client | 20 | 280.4 | 292.0 | 222.0 | 8869.0 | 0 |
+| warm | list | proxy | fresh-process-cli | 20 | 415.5 | 429.1 | 221.0 | 8869.0 | 0 |
+| warm | nested-scroll | proxy | persistent-client | 20 | 239.9 | 250.6 | 183.0 | 5785.0 | 0 |
+| warm | nested-scroll | proxy | fresh-process-cli | 20 | 376.8 | 392.2 | 182.0 | 5785.0 | 0 |
+| warm | alert | proxy | persistent-client | 20 | 203.2 | 221.5 | 148.0 | 7961.0 | 0 |
+| warm | alert | proxy | fresh-process-cli | 20 | 343.4 | 356.7 | 150.0 | 7961.0 | 0 |
+| warm | system-surface | proxy | persistent-client | 20 | 183.3 | 200.8 | 127.0 | 5758.0 | 0 |
+| warm | system-surface | proxy | fresh-process-cli | 20 | 319.3 | 336.4 | 133.0 | 5758.0 | 0 |
+| warm | xctest-stress | proxy | persistent-client | 20 | 197.3 | 208.7 | 140.0 | 7252.0 | 0 |
+| warm | xctest-stress | proxy | fresh-process-cli | 20 | 339.6 | 353.2 | 148.0 | 7252.0 | 0 |
+| warm | quiet | proxy | persistent-client | 20 | 281.9 | 303.0 | 104.0 | 1842.0 | 0 |
+| warm | quiet | proxy | fresh-process-cli | 20 | 555.6 | 569.7 | 116.0 | 1840.0 | 0 |
+| warm | list | proxy | persistent-client | 20 | 407.8 | 437.1 | 227.0 | 8838.0 | 0 |
+| warm | list | proxy | fresh-process-cli | 20 | 691.4 | 708.9 | 236.0 | 8838.0 | 0 |
+| warm | nested-scroll | proxy | persistent-client | 20 | 380.8 | 432.7 | 199.0 | 5785.0 | 0 |
+| warm | nested-scroll | proxy | fresh-process-cli | 20 | 642.7 | 667.0 | 195.0 | 5784.0 | 0 |
+| warm | alert | proxy | persistent-client | 20 | 350.9 | 361.8 | 169.0 | 7961.0 | 0 |
+| warm | alert | proxy | fresh-process-cli | 20 | 615.3 | 626.3 | 170.0 | 7961.0 | 0 |
+| warm | system-surface | proxy | persistent-client | 20 | 329.8 | 346.5 | 150.0 | 5758.0 | 0 |
+| warm | system-surface | proxy | fresh-process-cli | 20 | 595.2 | 611.2 | 152.0 | 5758.0 | 0 |
+| warm | xctest-stress | proxy | persistent-client | 20 | 314.0 | 344.5 | 134.0 | 7252.0 | 0 |
+| warm | xctest-stress | proxy | fresh-process-cli | 20 | 562.4 | 586.0 | 128.0 | 7252.0 | 0 |
+
+## Package size
+
+Not measured.
+
+## Deep-button control
+
+- Fixture artifact: deep-button-fixture.v1.json (depth 72)
+- Red control: pnpm bench:ios-snapshot:deep-button -- --rule invalid-shallow (exit 1)
+  - AssertionError: changed descendant was omitted by shallow observation; no-effect claim is invalid.
+- Safe control: pnpm bench:ios-snapshot:deep-button -- --rule safe-full (exit 0)
+  - full observation changed and includes the changed descendant.
diff --git a/scripts/ios-snapshot-benchmark/evidence/ios-snapshot-warm-relaunch-local-7c434b575.md b/scripts/ios-snapshot-benchmark/evidence/ios-snapshot-warm-relaunch-local-7c434b575.md
new file mode 100644
index 0000000000..29ef025a6f
--- /dev/null
+++ b/scripts/ios-snapshot-benchmark/evidence/ios-snapshot-warm-relaunch-local-7c434b575.md
@@ -0,0 +1,37 @@
+# iOS snapshot convergence benchmark
+
+- Status: **completed**
+- Revision: 7c434b575837e3291c51315bf9bb8b54c8ce7568
+- Host: MacBook Pro (Mac16,8; Apple M4 Pro, 12 cores)
+- Target: bench-2188-final (5FEADD02-98E4-4F01-861C-07003C1A3291, com.apple.CoreSimulator.SimRuntime.iOS-26-2)
+- Generated: 2026-09-21T19:53:30.433Z
+
+| State | Screen | Transport | Execution | N | Wall median | Wall p95 | Daemon median | Response median | Failures |
+|---|---|---|---|---:|---:|---:|---:|---:|---:|
+| warm | quiet | local | fresh-process-cli | 20 | 169.4 | 183.3 | 89.0 | 3448.0 | 0 |
+| warm | list | local | fresh-process-cli | 20 | 291.2 | 309.3 | 202.0 | 18354.0 | 0 |
+| warm | nested-scroll | local | fresh-process-cli | 20 | 249.8 | 268.2 | 167.0 | 12593.0 | 0 |
+| warm | alert | local | fresh-process-cli | 20 | 224.0 | 238.6 | 139.0 | 16256.0 | 0 |
+| warm | system-surface | local | fresh-process-cli | 20 | 207.7 | 225.2 | 130.0 | 11566.0 | 0 |
+| warm | xctest-stress | local | fresh-process-cli | 20 | 213.1 | 233.1 | 128.0 | 14955.0 | 0 |
+| relaunch | quiet | local | fresh-process-cli | 20 | 3876.5 | 3981.8 | 2851.0 | 2757.0 | 0 |
+| relaunch | list | local | fresh-process-cli | 20 | 3888.4 | 3970.5 | 2871.0 | 2754.0 | 0 |
+| relaunch | nested-scroll | local | fresh-process-cli | 20 | 3871.9 | 3958.4 | 2844.0 | 2800.0 | 0 |
+| relaunch | alert | local | fresh-process-cli | 20 | 3896.4 | 4058.7 | 2881.0 | 2763.0 | 0 |
+| relaunch | system-surface | local | fresh-process-cli | 20 | 3576.4 | 3640.7 | 2536.0 | 11302.0 | 0 |
+| relaunch | xctest-stress | local | fresh-process-cli | 20 | 3867.8 | 4071.6 | 2855.0 | 2796.0 | 0 |
+
+## Package size
+
+- Packed tarball: 1409306 bytes
+- Packed unpacked tree: 4723895 bytes
+- Clean-installed package tree: 4723895 bytes (543 files)
+- Bundled JavaScript: 3775024 raw / 1258950 gzip bytes
+
+## Deep-button control
+
+- Fixture artifact: deep-button-fixture.v1.json (depth 72)
+- Red control: pnpm bench:ios-snapshot:deep-button -- --rule invalid-shallow (exit 1)
+  - AssertionError: changed descendant was omitted by shallow observation; no-effect claim is invalid.
+- Safe control: pnpm bench:ios-snapshot:deep-button -- --rule safe-full (exit 0)
+  - full observation changed and includes the changed descendant.
diff --git a/scripts/ios-snapshot-benchmark/fixture-admission.test.ts b/scripts/ios-snapshot-benchmark/fixture-admission.test.ts
index cc328e75ff..f107a812ee 100644
--- a/scripts/ios-snapshot-benchmark/fixture-admission.test.ts
+++ b/scripts/ios-snapshot-benchmark/fixture-admission.test.ts
@@ -4,8 +4,8 @@ import { BenchmarkCellAdmissionError } from './lifecycle.ts';
 import {
   prepareFixture,
   requireFixtureAnchor,
+  type FixtureOperationResult,
   type FixturePreparationDriver,
-  type FixturePreparationResult,
 } from './fixture-admission.ts';
 import type { ScreenFixture } from './types.ts';
 
@@ -18,7 +18,9 @@ const alertFixture: ScreenFixture = {
   setupAction: 'open-alert',
 };
 
-function observed(anchor: string): FixturePreparationResult {
+const shortAnchorOptions = { anchorBudgetMs: 40, anchorPollMs: 5 };
+
+function observed(anchor: string): FixtureOperationResult {
   return {
     ok: true,
     payload: {
@@ -61,10 +63,79 @@ test('shares opening, setup, and post-setup admission across fixture drivers', a
 
 test('turns a wrong post-setup screen into a typed fixture-anchor stop', async () => {
   await assert.rejects(
-    () => prepareFixture(alertFixture, successfulDriver(['Automation lab', 'Settings'])),
+    () =>
+      prepareFixture(
+        alertFixture,
+        successfulDriver(['Automation lab', 'Settings']),
+        shortAnchorOptions,
+      ),
     (error: unknown) =>
-      error instanceof BenchmarkCellAdmissionError && error.reason === 'fixture-anchor',
+      error instanceof BenchmarkCellAdmissionError &&
+      error.reason === 'fixture-anchor' &&
+      error.message.includes('within 40ms'),
+  );
+});
+
+test('waits an unmounted opening screen out, then continues setup', async () => {
+  const calls: string[] = [];
+  const anchors = ['Settings', 'Settings', 'Automation lab', 'Automation confirmation'];
+  const driver: FixturePreparationDriver = {
+    observe: () => {
+      calls.push('observe');
+      return observed(anchors.shift() ?? 'Unexpected extra observation');
+    },
+    scrollToBottom: () => {
+      calls.push('scroll');
+      return { ok: true, payload: {} };
+    },
+    openAlert: () => {
+      calls.push('open-alert');
+      return { ok: true, payload: {} };
+    },
+  };
+
+  await prepareFixture(alertFixture, driver, shortAnchorOptions);
+
+  assert.deepEqual(calls, ['observe', 'observe', 'observe', 'scroll', 'open-alert', 'observe']);
+  assert.deepEqual(anchors, []);
+});
+
+test('stops at the opening anchor once the admission budget elapses', async () => {
+  const unmounted: FixturePreparationDriver = {
+    observe: () => observed('Settings'),
+    scrollToBottom: () => ({ ok: true, payload: {} }),
+    openAlert: () => ({ ok: true, payload: {} }),
+  };
+  const started = Date.now();
+  await assert.rejects(
+    () => prepareFixture(alertFixture, unmounted, shortAnchorOptions),
+    (error: unknown) =>
+      error instanceof BenchmarkCellAdmissionError &&
+      error.reason === 'fixture-anchor' &&
+      error.message.includes('within 40ms'),
+  );
+  assert.ok(Date.now() - started < 5_000, 'the anchor budget was not honored');
+});
+
+test('fails an unsuccessful observation immediately instead of polling', async () => {
+  let observations = 0;
+  const driver: FixturePreparationDriver = {
+    observe: () => {
+      observations += 1;
+      return { ok: false, payload: {} };
+    },
+    scrollToBottom: () => ({ ok: true, payload: {} }),
+    openAlert: () => ({ ok: true, payload: {} }),
+  };
+
+  await assert.rejects(
+    () => prepareFixture(alertFixture, driver, { anchorBudgetMs: 5_000, anchorPollMs: 1 }),
+    (error: unknown) =>
+      error instanceof BenchmarkCellAdmissionError &&
+      error.reason === 'fixture-anchor' &&
+      error.message.includes('failed'),
   );
+  assert.equal(observations, 1);
 });
 
 test('checks the expected post-setup anchor for direct client batch results', () => {
diff --git a/scripts/ios-snapshot-benchmark/fixture-admission.ts b/scripts/ios-snapshot-benchmark/fixture-admission.ts
index 673a37ab3f..c9df0549f3 100644
--- a/scripts/ios-snapshot-benchmark/fixture-admission.ts
+++ b/scripts/ios-snapshot-benchmark/fixture-admission.ts
@@ -5,6 +5,14 @@ import type { Failure, ScreenFixture } from './types.ts';
 
 export type FixtureAnchorPhase = 'opened' | 'prepared' | 'sample';
 
+/**
+ * Setup reads are untimed, so an anchor read that lands before the app has mounted its first tree
+ * is waited out instead of stopping the run. The budget must stay far below the operation timeout
+ * it precedes; a fixture that never exposes its anchor still stops the run.
+ */
+const FIXTURE_ANCHOR_ADMISSION_BUDGET_MS = 30_000;
+const FIXTURE_ANCHOR_POLL_INTERVAL_MS = 500;
+
 export type FixtureOperationResult = {
   ok: boolean;
   payload: unknown;
@@ -19,30 +27,62 @@ export type FixturePreparationDriver = {
   openAlert: () => FixtureOperationResult | Promise<FixtureOperationResult>;
 };
 
+export type FixturePreparationOptions = {
+  anchorBudgetMs?: number;
+  anchorPollMs?: number;
+};
+
 export async function prepareFixture(
   fixture: ScreenFixture,
   driver: FixturePreparationDriver,
+  options: FixturePreparationOptions = {},
 ): Promise<void> {
-  const opened = await driver.observe();
-  requireFixtureOperationSuccess(
-    opened,
-    `${fixture.id} semantic anchor observation`,
-    'fixture-anchor',
-  );
-  requireFixtureAnchor(opened.payload, fixture, 'opened', opened.command);
+  await observeFixtureAnchor(fixture, driver, 'opened', options);
   if (fixture.setupAction !== 'open-alert') return;
 
   const scrolled = await driver.scrollToBottom();
   requireFixtureOperationSuccess(scrolled, `${fixture.id} setup scroll`, 'cell-state');
   const alert = await driver.openAlert();
   requireFixtureOperationSuccess(alert, `${fixture.id} setup action`, 'cell-state');
-  const prepared = await driver.observe();
-  requireFixtureOperationSuccess(
-    prepared,
-    `${fixture.id} post-setup semantic anchor observation`,
-    'fixture-anchor',
-  );
-  requireFixtureAnchor(prepared.payload, fixture, 'prepared', prepared.command);
+  await observeFixtureAnchor(fixture, driver, 'prepared', options);
+}
+
+async function observeFixtureAnchor(
+  fixture: ScreenFixture,
+  driver: FixturePreparationDriver,
+  phase: Exclude<FixtureAnchorPhase, 'sample'>,
+  options: FixturePreparationOptions,
+): Promise<FixtureOperationResult> {
+  const budgetMs = options.anchorBudgetMs ?? FIXTURE_ANCHOR_ADMISSION_BUDGET_MS;
+  const pollMs = options.anchorPollMs ?? FIXTURE_ANCHOR_POLL_INTERVAL_MS;
+  const operation =
+    phase === 'opened'
+      ? `${fixture.id} semantic anchor observation`
+      : `${fixture.id} post-setup semantic anchor observation`;
+  const deadline = Date.now() + budgetMs;
+  for (;;) {
+    const result = await driver.observe();
+    requireFixtureOperationSuccess(result, operation, 'fixture-anchor');
+    if (hasFixtureAnchor(result.payload, fixture, phase)) return result;
+    const remainingMs = deadline - Date.now();
+    if (remainingMs <= 0) {
+      throw new BenchmarkCellAdmissionError(
+        'fixture-anchor',
+        `Fixture ${fixture.id} ${phase} did not expose the exact anchor ` +
+          `${JSON.stringify(expectedAnchor(fixture, phase))} within ${budgetMs}ms.`,
+        result.command,
+      );
+    }
+    await sleep(Math.min(pollMs, remainingMs));
+  }
+}
+
+function hasFixtureAnchor(
+  payload: unknown,
+  fixture: ScreenFixture,
+  phase: FixtureAnchorPhase,
+): boolean {
+  return snapshotHasAnchor(payload, expectedAnchor(fixture, phase));
 }
 
 export function requireFixtureAnchor(
@@ -51,15 +91,20 @@ export function requireFixtureAnchor(
   phase: FixtureAnchorPhase,
   command = 'agent-device snapshot',
 ): void {
-  const anchor = expectedAnchor(fixture, phase);
-  if (snapshotHasAnchor(payload, anchor)) return;
+  if (hasFixtureAnchor(payload, fixture, phase)) return;
   throw new BenchmarkCellAdmissionError(
     'fixture-anchor',
-    `Fixture ${fixture.id} ${phase} did not expose the exact anchor ${JSON.stringify(anchor)}.`,
+    `Fixture ${fixture.id} ${phase} did not expose the exact anchor ${JSON.stringify(
+      expectedAnchor(fixture, phase),
+    )}.`,
     command,
   );
 }
 
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
 export function fixtureOperationFromCli(
   result: CliResult,
   command: string,
diff --git a/scripts/ios-snapshot-benchmark/proxy-client-support.test.ts b/scripts/ios-snapshot-benchmark/proxy-client-support.test.ts
index 825b81a2f3..b84c87fa6e 100644
--- a/scripts/ios-snapshot-benchmark/proxy-client-support.test.ts
+++ b/scripts/ios-snapshot-benchmark/proxy-client-support.test.ts
@@ -75,8 +75,20 @@ test('persistent-client setup rejects a wrong prepared screen as fixture-anchor'
         clientWithSnapshots(['Automation lab', 'Settings'], []),
         alertFixture,
         'simulator',
+        { anchorBudgetMs: 40, anchorPollMs: 5 },
       ),
     (error: unknown) =>
       error instanceof BenchmarkCellAdmissionError && error.reason === 'fixture-anchor',
   );
 });
+
+test('persistent-client setup waits an unmounted opening screen out', async () => {
+  const calls: string[] = [];
+  await openClientFixture(
+    clientWithSnapshots(['Settings', 'Automation lab', 'Automation confirmation'], calls),
+    alertFixture,
+    'simulator',
+    { anchorBudgetMs: 2_000, anchorPollMs: 1 },
+  );
+  assert.deepEqual(calls, ['open', 'snapshot', 'snapshot', 'scroll', 'click', 'snapshot']);
+});
diff --git a/scripts/ios-snapshot-benchmark/proxy-client-support.ts b/scripts/ios-snapshot-benchmark/proxy-client-support.ts
index 6d8c1b9de2..4c26ea85b2 100644
--- a/scripts/ios-snapshot-benchmark/proxy-client-support.ts
+++ b/scripts/ios-snapshot-benchmark/proxy-client-support.ts
@@ -19,6 +19,7 @@ import {
   fixtureOperationFromClient,
   prepareFixture,
   requireFixtureAnchor,
+  type FixturePreparationOptions,
 } from './fixture-admission.ts';
 import { type NetworkConditioner, type ProxyRpcRecord } from './proxy-conditioner.ts';
 import type { ProxyStartup } from './proxy-process.ts';
@@ -108,6 +109,7 @@ export async function openClientFixture(
   client: AgentClient,
   fixture: ScreenFixture,
   udid: string,
+  preparation: FixturePreparationOptions = {},
 ): Promise<void> {
   await client.apps.open({
     app: fixture.app,
@@ -117,31 +119,35 @@ export async function openClientFixture(
     relaunch: true,
     foreground: true,
   });
-  await prepareFixture(fixture, {
-    observe: async () =>
-      fixtureOperationFromClient(
-        await client.batch.run(snapshotBatchOptions()),
-        'agent-device client batch --steps snapshot',
-      ),
-    scrollToBottom: async () =>
-      fixtureOperationFromClient(
-        await client.interactions.scroll({
-          direction: 'bottom',
-          platform: 'ios',
-          udid,
-        }),
-        'agent-device client scroll bottom',
-      ),
-    openAlert: async () =>
-      fixtureOperationFromClient(
-        await client.interactions.click({
-          target: { kind: 'selector', selector: 'id="automation-open-alert"' },
-          platform: 'ios',
-          udid,
-        }),
-        'agent-device client click id="automation-open-alert"',
-      ),
-  });
+  await prepareFixture(
+    fixture,
+    {
+      observe: async () =>
+        fixtureOperationFromClient(
+          await client.batch.run(snapshotBatchOptions()),
+          'agent-device client batch --steps snapshot',
+        ),
+      scrollToBottom: async () =>
+        fixtureOperationFromClient(
+          await client.interactions.scroll({
+            direction: 'bottom',
+            platform: 'ios',
+            udid,
+          }),
+          'agent-device client scroll bottom',
+        ),
+      openAlert: async () =>
+        fixtureOperationFromClient(
+          await client.interactions.click({
+            target: { kind: 'selector', selector: 'id="automation-open-alert"' },
+            platform: 'ios',
+            udid,
+          }),
+          'agent-device client click id="automation-open-alert"',
+        ),
+    },
+    preparation,
+  );
 }
 
 export async function captureClientSample(

From 9208b90491498a2156165e5133518015ce8bfaab Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Tue, 22 Sep 2026 08:57:59 +0200
Subject: [PATCH 006/132] fix(fold): report screen dimensions in their
 native-panel coordinate space (#2737)

The fold response's `screen.widthPt`/`heightPt` are the lit panel's native
points (pixels divided by its point scale, never rotated), not the next
snapshot's viewport. Add the required `screen.coordinateSpace: "native-panel"`
discriminator at the construction site, export it from the owning contract so
the Apple owner and the MCP schema share one value, and correct every doc and
message that implied these numbers could place a tap.

A fresh snapshot stays the only source of app-viewport coordinates: on an open
Duo the 669x951 inner panel hosts a 951x669 app window.

Closes #2729
---
 CHANGELOG.md                                  |  9 ++-
 packages/contracts/src/fold-runtime.ts        | 13 +++-
 packages/contracts/src/navigation.ts          |  5 +-
 .../platform-apple/src/foldable/pose.test.ts  | 59 ++++++++++++++++++-
 packages/platform-apple/src/foldable/pose.ts  |  8 ++-
 src/commands/schema/cli-help.ts               |  4 +-
 src/daemon/__tests__/fold-runtime.test.ts     | 11 +++-
 src/daemon/fold-runtime.ts                    |  2 +-
 .../__tests__/command-tools-parity.test.ts    | 34 +++++++++++
 src/mcp/command-output-schemas.ts             | 12 +++-
 website/docs/docs/commands.md                 |  2 +-
 11 files changed, 141 insertions(+), 18 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4d8783a9c6..5870d0eeee 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -41,13 +41,18 @@
   the pose control in the Xcode Device Hub window through macOS accessibility, and it is confirmed
   the way ADR 0025 asked for, by reading the hinge angle back from CoreDevice
   (`devicectl device motion hinge-angle`) until it agrees with the request. The response reports
-  the verified pose, the hinge angle, and the panel the device now lights with its point size, so an
-  agent can see that its refs and coordinates are stale without another capture. The macOS helper
+  the verified pose, the hinge angle, and the panel the device now lights with its native panel point
+  size, so an agent can see the lit panel changed without another capture. The macOS helper
   gained a `device-hub pose` subcommand that finds Device Hub in the process table (LaunchServices
   registers the trampolined app with no pid), reopens its window when it shows none, and selects the
   simulator through the sidebar row keyed by its UDID so two simulators sharing a name cannot be
   confused. Simulator-only; a single-panel simulator refuses with `UNSUPPORTED_OPERATION`, and every
   other platform states its own refusal cell.
+- Fixed (ios): the `fold` response's `screen` dimensions now match their coordinate-space contract. They
+  are the lit panel's own native points (pixels divided by its point scale, never rotated), so the
+  response carries the `coordinateSpace: "native-panel"` discriminator and the docs no longer claim
+  they are the next snapshot's coordinates. They cannot place a tap; take a fresh snapshot for the app
+  viewport.
 - Added (diff): `diff screenshot` accepts a JPEG baseline or current image. Both inputs had to be PNG,
   so a capture exported by another tool had to be converted first and a HarmonyOS capture — which the
   platform serves as JPEG under whatever name the command was given — could never be compared. Each
diff --git a/packages/contracts/src/fold-runtime.ts b/packages/contracts/src/fold-runtime.ts
index 2aeab8c1ea..c20b3480e8 100644
--- a/packages/contracts/src/fold-runtime.ts
+++ b/packages/contracts/src/fold-runtime.ts
@@ -8,13 +8,22 @@ import type { RuntimeOperationFact } from './platform-runtime.ts';
  */
 export type SetFoldPoseInput = Readonly<{ pose: FoldPose }>;
 
+/** Single source of truth for the discriminator the Apple owner sets and the MCP schema advertises. */
+export const FOLD_SCREEN_COORDINATE_SPACE = 'native-panel' as const;
+
 /**
- * The lit panel after the pose settled, in the points the next snapshot will use. Reported so an
- * agent can see that the coordinate space changed without a second capture.
+ * The panel the device lights after the pose settled, in that panel's own native points: its pixel
+ * size divided by its point scale, never rotated. `coordinateSpace` is always
+ * {@link FOLD_SCREEN_COORDINATE_SPACE}, and these numbers are NOT snapshot coordinates — the active
+ * app window can differ from the panel (iPhone Duo: a 669x951 inner panel hosts a 951x669 app
+ * window), so they cannot place a tap. A caller that needs the app viewport must take a fresh
+ * snapshot.
  */
 export type FoldScreenReport = Readonly<{
   /** The CoreDevice display name of the panel the device now lights. */
   display: string;
+  /** Marks these dimensions as the panel's native points, never a snapshot's app viewport. */
+  coordinateSpace: typeof FOLD_SCREEN_COORDINATE_SPACE;
   widthPt: number;
   heightPt: number;
 }>;
diff --git a/packages/contracts/src/navigation.ts b/packages/contracts/src/navigation.ts
index 861efb3cce..3d5c6c1d62 100644
--- a/packages/contracts/src/navigation.ts
+++ b/packages/contracts/src/navigation.ts
@@ -53,8 +53,9 @@ export type OrientationCommandResult = {
  *
  * Unlike `orientation`, there is no unconfirmed variant: the Apple owner reads the hinge angle
  * back from CoreDevice after pressing the Device Hub pose control, and reports a pose only when
- * that reading agrees with the request. `screen` names the panel the device lights afterwards, in
- * points, because a pose change moves the app to a different coordinate space (ADR 0025).
+ * that reading agrees with the request. `screen` names the panel the device lights afterwards and
+ * that panel's native point size (ADR 0025); it is the panel's geometry, not the app viewport, so a
+ * caller must take a fresh snapshot before placing a tap.
  */
 export type FoldCommandResult = {
   action: 'fold';
diff --git a/packages/platform-apple/src/foldable/pose.test.ts b/packages/platform-apple/src/foldable/pose.test.ts
index d0121eb759..5a7b83413e 100644
--- a/packages/platform-apple/src/foldable/pose.test.ts
+++ b/packages/platform-apple/src/foldable/pose.test.ts
@@ -99,7 +99,7 @@ test('presses the Device Hub control for the pose and reports the pose CoreDevic
   await expect(setAppleFoldPose(duo, 'open')).resolves.toEqual({
     pose: 'open',
     hingeAngleDegrees: 180,
-    screen: { display: 'LCD-1', widthPt: 669, heightPt: 951 },
+    screen: { display: 'LCD-1', coordinateSpace: 'native-panel', widthPt: 669, heightPt: 951 },
   });
 
   expect(mockPress).toHaveBeenCalledWith({
@@ -111,6 +111,62 @@ test('presses the Device Hub control for the pose and reports the pose CoreDevic
   expect(mockHinge).toHaveBeenCalledTimes(2);
 });
 
+test('reports the closed outer panel in native points, not rotated to a snapshot viewport', async () => {
+  // The outer panel is 1398x2034 px at scale 3, i.e. 466x678 native points; the pose must not
+  // rotate that into the app window's shape, because a caller cannot place a tap from it.
+  mockInventory
+    .mockResolvedValueOnce(duoInventory('outer'))
+    .mockResolvedValueOnce(duoInventory('outer'));
+  mockHinge.mockResolvedValue(0);
+
+  await expect(setAppleFoldPose(duo, 'closed')).resolves.toEqual({
+    pose: 'closed',
+    hingeAngleDegrees: 0,
+    screen: { display: 'LCD', coordinateSpace: 'native-panel', widthPt: 466, heightPt: 678 },
+  });
+});
+
+test("reports native panel points regardless of the display's own currentOrientation", async () => {
+  // The same inner panel (2007x2853 px at scale 3) with a portrait orientation tag still measures
+  // 669x951: the report divides by point scale only and never swaps on `currentOrientation`.
+  const rot0Inner = buildInventory([
+    panel({ power: 'dark' }),
+    panel({
+      name: 'LCD-1',
+      displayId: 3,
+      primary: false,
+      power: 'lit',
+      widthPx: 2007,
+      heightPx: 2853,
+      currentOrientation: 'rot0',
+    }),
+  ]);
+  mockInventory.mockResolvedValueOnce(duoInventory('inner')).mockResolvedValueOnce(rot0Inner);
+  mockHinge.mockResolvedValue(180);
+
+  const result = await setAppleFoldPose(duo, 'open');
+  expect(result.screen).toEqual({
+    display: 'LCD-1',
+    coordinateSpace: 'native-panel',
+    widthPt: 669,
+    heightPt: 951,
+  });
+});
+
+test('omits the screen report when panel selection is ambiguous, never inventing a viewport', async () => {
+  // Two lit panels make the inventory ambiguous, so `readLitPanel` refuses to name one; the pose is
+  // still verified but carries no `screen` rather than guessing the app viewport.
+  const bothLit = buildInventory([panel({}), panel({ name: 'LCD-1', displayId: 3 })]);
+  expect(bothLit.ambiguous).toBe(true);
+  mockInventory.mockResolvedValueOnce(bothLit).mockResolvedValueOnce(bothLit);
+  mockHinge.mockResolvedValue(180);
+
+  await expect(setAppleFoldPose(duo, 'open')).resolves.toEqual({
+    pose: 'open',
+    hingeAngleDegrees: 180,
+  });
+});
+
 test('maps half-open onto the Book preset and reports it only once the hinge has stopped', async () => {
   mockInventory
     .mockResolvedValueOnce(duoInventory('inner'))
@@ -122,6 +178,7 @@ test('maps half-open onto the Book preset and reports it only once the hinge has
   await expect(setAppleFoldPose(duo, 'half-open')).resolves.toMatchObject({
     pose: 'half-open',
     hingeAngleDegrees: 130,
+    screen: { display: 'LCD-1', coordinateSpace: 'native-panel', widthPt: 669, heightPt: 951 },
   });
   expect(mockPress).toHaveBeenCalledWith(expect.objectContaining({ pose: 'book' }));
   expect(mockHinge).toHaveBeenCalledTimes(3);
diff --git a/packages/platform-apple/src/foldable/pose.ts b/packages/platform-apple/src/foldable/pose.ts
index 2da21bb9c5..9cab525785 100644
--- a/packages/platform-apple/src/foldable/pose.ts
+++ b/packages/platform-apple/src/foldable/pose.ts
@@ -1,5 +1,9 @@
 import { foldPoseForHingeAngle, type FoldPose } from '@agent-device/contracts/device';
-import type { FoldScreenReport, SetFoldPoseResult } from '@agent-device/contracts/fold-runtime';
+import {
+  FOLD_SCREEN_COORDINATE_SPACE,
+  type FoldScreenReport,
+  type SetFoldPoseResult,
+} from '@agent-device/contracts/fold-runtime';
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import { AppError } from '@agent-device/kernel/errors';
 import { emitDiagnostic } from '@agent-device/host-kit/diagnostics';
@@ -196,9 +200,11 @@ async function readLitPanel(
   return inventory.activeDisplay;
 }
 
+/** The panel's native points: pixels divided by its own point scale, never rotated by orientation. */
 function screenReport(display: AppleDeviceDisplay): FoldScreenReport {
   return {
     display: display.name,
+    coordinateSpace: FOLD_SCREEN_COORDINATE_SPACE,
     widthPt: Math.round(display.widthPx / display.pointScale),
     heightPt: Math.round(display.heightPx / display.pointScale),
   };
diff --git a/src/commands/schema/cli-help.ts b/src/commands/schema/cli-help.ts
index f54c968afe..f49706c7ee 100644
--- a/src/commands/schema/cli-help.ts
+++ b/src/commands/schema/cli-help.ts
@@ -742,12 +742,12 @@ A foldable Apple device (iPhone Duo) carries two integrated panels, which Apple
 
 Screens are handled for you:
   Each iOS simulator capture resolves the CoreDevice display table, captures the lit panel explicitly, and normalizes density with that panel's own point scale. Do not add a screen flag to the normal loop; there is none, because the lit panel is always the only capturable one: the dark panel yields an all-black PNG.
-  The two panels are different sizes and different coordinate spaces (iPhone Duo: 466x678 points closed on the outer panel, 669x951 open on the inner). A pose change therefore invalidates every ref and coordinate. Re-snapshot after any pose change and never carry coordinates or refs across one.
+  The two panels are different sizes (iPhone Duo: 466x678 points closed on the outer panel, 669x951 open on the inner). A pose change therefore invalidates every ref and coordinate. Re-snapshot after any pose change and never carry coordinates or refs across one.
   Check which panel is lit before trusting a geometry claim: agent-device screenshot reports its point size, and 466x678 versus 669x951 says which panel you captured.
 
 Changing the pose:
   agent-device fold closed | half-open | open
-  fold presses the pose control in the Xcode Device Hub window for this simulator (Closed, Book, Open) and then reads the hinge angle back from CoreDevice until it agrees: closed is 0 degrees, open is 180, and half-open is any angle between them (Device Hub's Book preset, 130 degrees on iOS 27.1). An angle in that interval only proves the category, so half-open is reported once two consecutive readings both fall inside it and agree within 0.5 degrees. The response reports the verified pose, the hinge angle, and the panel the device now lights with its point size. A hinge whose last reading is some other pose fails with COMMAND_FAILED and reason fold-pose-unverified, naming the angle CoreDevice still reports; a hinge seen half-open but never at rest fails with reason fold-pose-unsettled, naming the observed and previous angles. A single-panel simulator fails with UNSUPPORTED_OPERATION.
+  fold presses the pose control in the Xcode Device Hub window for this simulator (Closed, Book, Open) and then reads the hinge angle back from CoreDevice until it agrees: closed is 0 degrees, open is 180, and half-open is any angle between them (Device Hub's Book preset, 130 degrees on iOS 27.1). An angle in that interval only proves the category, so half-open is reported once two consecutive readings both fall inside it and agree within 0.5 degrees. The response reports the verified pose, the hinge angle, and the panel the device now lights with its native panel point size, marked coordinateSpace "native-panel". That point size is the panel's own geometry, not the next snapshot's viewport, so it cannot place a tap: the active app window can differ (a 669x951 inner panel hosts a 951x669 window). A hinge whose last reading is some other pose fails with COMMAND_FAILED and reason fold-pose-unverified, naming the angle CoreDevice still reports; a hinge seen half-open but never at rest fails with reason fold-pose-unsettled, naming the observed and previous angles. A single-panel simulator fails with UNSUPPORTED_OPERATION.
   Expect a fold to take 10-16 seconds: each hinge read is a five-second devicectl stream, and half-open waits for the hinge to stop moving. Re-snapshot after every fold; refs and coordinates from before it are stale, and the command's message says so.
   Requirements: an iOS simulator session on a foldable device, Xcode 27.1 or newer with Device Hub, and Accessibility permission for the host (agent-device settings permission grant accessibility --platform macos). The command launches Device Hub if needed, reopens its window when it shows none, and selects the simulator through its sidebar by UDID, so no operator step is needed. No official host API sets the pose; the app under test still reads it as UIHinge.status.
   If a task asserts behavior for more than one pose, fold to each pose and re-snapshot, and report which poses the run covered.`,
diff --git a/src/daemon/__tests__/fold-runtime.test.ts b/src/daemon/__tests__/fold-runtime.test.ts
index a6ca846e63..3cbc78f7ed 100644
--- a/src/daemon/__tests__/fold-runtime.test.ts
+++ b/src/daemon/__tests__/fold-runtime.test.ts
@@ -88,7 +88,12 @@ test('resolves one admitted binding and reports the pose the owner read back', a
   const setFoldPose = vi.fn(async () => ({
     pose: 'open' as const,
     hingeAngleDegrees: 180,
-    screen: { display: 'LCD-1', widthPt: 669, heightPt: 951 },
+    screen: {
+      display: 'LCD-1',
+      coordinateSpace: 'native-panel' as const,
+      widthPt: 669,
+      heightPt: 951,
+    },
   }));
   const harness = runtimeHarness(
     foldRuntimeOperationFacts({ fold: available }).setFoldPose,
@@ -109,9 +114,9 @@ test('resolves one admitted binding and reports the pose the owner read back', a
     action: 'fold',
     pose: 'open',
     hingeAngleDegrees: 180,
-    screen: { display: 'LCD-1', widthPt: 669, heightPt: 951 },
+    screen: { display: 'LCD-1', coordinateSpace: 'native-panel', widthPt: 669, heightPt: 951 },
     message:
-      'Folded to open (hinge 180°, LCD-1 lit at 669x951pt); refs from before the pose change are stale',
+      'Folded to open (hinge 180°, LCD-1 native panel 669x951pt, not snapshot coordinates); refs from before the pose change are stale',
   });
   expect(setFoldPose).toHaveBeenCalledWith({ pose: 'open' });
 });
diff --git a/src/daemon/fold-runtime.ts b/src/daemon/fold-runtime.ts
index 8a214a4a66..179ea15a73 100644
--- a/src/daemon/fold-runtime.ts
+++ b/src/daemon/fold-runtime.ts
@@ -55,7 +55,7 @@ async function executeSetFoldPose(
     ...(screen ? { screen } : {}),
     ...successText(
       screen
-        ? `Folded to ${result.pose} (hinge ${result.hingeAngleDegrees}°, ${screen.display} lit at ${screen.widthPt}x${screen.heightPt}pt); refs from before the pose change are stale`
+        ? `Folded to ${result.pose} (hinge ${result.hingeAngleDegrees}°, ${screen.display} native panel ${screen.widthPt}x${screen.heightPt}pt, not snapshot coordinates); refs from before the pose change are stale`
         : `Folded to ${result.pose} (hinge ${result.hingeAngleDegrees}°); refs from before the pose change are stale`,
     ),
   };
diff --git a/src/mcp/__tests__/command-tools-parity.test.ts b/src/mcp/__tests__/command-tools-parity.test.ts
index b0c4a6f7f6..113ffcc363 100644
--- a/src/mcp/__tests__/command-tools-parity.test.ts
+++ b/src/mcp/__tests__/command-tools-parity.test.ts
@@ -166,6 +166,40 @@ test('MCP fill projects target-bound unconfirmed verification through its advert
   assert.notDeepEqual(validateAgainstSchema(missingTarget, fillTool.outputSchema), []);
 });
 
+test('MCP fold advertises the native-panel discriminator and rejects a screen missing it', async () => {
+  const foldResult = {
+    action: 'fold',
+    pose: 'open',
+    hingeAngleDegrees: 180,
+    screen: { display: 'LCD-1', coordinateSpace: 'native-panel', widthPt: 669, heightPt: 951 },
+    message:
+      'Folded to open (hinge 180°, LCD-1 native panel 669x951pt, not snapshot coordinates); refs from before the pose change are stale',
+  } satisfies CommandExecutionResult<'fold'>;
+  const executor = createCommandToolExecutor({
+    createClient: () => ({}) as AgentDeviceClient,
+    runCommand: async () => foldResult,
+  });
+
+  const foldTool = listCommandTools().find((tool) => tool.name === 'fold');
+  assert.ok(foldTool?.outputSchema);
+  assert.equal(foldTool.outputSchema, COMMAND_OUTPUT_SCHEMAS.fold);
+
+  const result = await executor.execute('fold', { pose: 'open' });
+  assert.deepEqual(result.structuredContent, foldResult);
+  assert.deepEqual(validateAgainstSchema(result.structuredContent, foldTool.outputSchema), []);
+
+  // A panel report that drops the discriminator no longer validates: the coordinate-space contract
+  // is required, not inferable from the numbers alone.
+  const { coordinateSpace: _coordinateSpace, ...screenWithoutDiscriminator } = foldResult.screen;
+  assert.notDeepEqual(
+    validateAgainstSchema(
+      { ...foldResult, screen: screenWithoutDiscriminator },
+      foldTool.outputSchema,
+    ),
+    [],
+  );
+});
+
 test('MCP applies config-backed command defaults; explicit operator input is refused', async () => {
   const home = mkdtempForTestSync('agent-device-mcp-config-');
   temporaryDirectory = home;
diff --git a/src/mcp/command-output-schemas.ts b/src/mcp/command-output-schemas.ts
index 094232fb2f..1f64e203ed 100644
--- a/src/mcp/command-output-schemas.ts
+++ b/src/mcp/command-output-schemas.ts
@@ -6,6 +6,7 @@ import { BACK_MODES } from '@agent-device/contracts/back-mode';
 import { NATIVE_PATH_DISPOSITION_VALUES } from '@agent-device/contracts/recording-native-path';
 import { RECORDER_OBSERVATION_VALUES } from '@agent-device/contracts/recording-stop-observation';
 import { DEVICE_ROTATIONS, FOLD_POSES } from '@agent-device/contracts/device';
+import { FOLD_SCREEN_COORDINATE_SPACE } from '@agent-device/contracts/fold-runtime';
 import { SESSION_SURFACES } from '@agent-device/contracts/session';
 import { TV_REMOTE_BUTTONS } from '@agent-device/contracts/tv-remote';
 import { DEVICE_TARGETS, PUBLIC_PLATFORMS } from '@agent-device/kernel/device';
@@ -525,10 +526,15 @@ const BASE_COMMAND_OUTPUT_SCHEMAS = {
       screen: objectSchema(
         {
           display: stringSchema('CoreDevice name of the panel the device now lights.'),
-          widthPt: numberSchema(),
-          heightPt: numberSchema(),
+          coordinateSpace: constSchema(FOLD_SCREEN_COORDINATE_SPACE),
+          widthPt: numberSchema(
+            'Panel width in native panel points (pixels divided by point scale), NOT snapshot coordinates; take a fresh snapshot to place a tap.',
+          ),
+          heightPt: numberSchema(
+            'Panel height in native panel points (pixels divided by point scale), NOT snapshot coordinates; take a fresh snapshot to place a tap.',
+          ),
         },
-        ['display', 'widthPt', 'heightPt'],
+        ['display', 'coordinateSpace', 'widthPt', 'heightPt'],
       ),
       message: stringSchema(),
     },
diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md
index f3a0629246..44c99a6af7 100644
--- a/website/docs/docs/commands.md
+++ b/website/docs/docs/commands.md
@@ -91,7 +91,7 @@ agent-device fold open
 - `action-button` asks the device whether it has the button before pressing it. A target whose model has none — an iPhone SE beside an iPhone 15, or most iPad simulators — fails with `UNSUPPORTED_OPERATION` rather than reporting a press that never happened.
 - `action-button` does not activate or relaunch the session's app, and it takes no `--settle`: pressing a hardware button is not a navigation, so the app stays where it was.
 - `action-button` reports that the press was dispatched, not what the system did with it. Simulators run no Shortcuts and no App Intents, so what a press triggers can only be verified on a physical iPhone; on a Simulator the command proves the press was accepted and that the session app was not brought forward.
-- `fold <closed|half-open|open>` puts a foldable iPhone simulator (iPhone Duo) into a hinge pose. No official host API sets a pose (ADR 0025), so the command presses the pose control in the Xcode Device Hub window through macOS accessibility, then reads the hinge angle back with `devicectl device motion hinge-angle` and reports the pose only when that reading agrees: `closed` is 0°, `open` is 180°, and `half-open` is any angle between them (Device Hub's Book preset, 130° on iOS 27.1). An angle inside that interval only proves the category, so `half-open` is reported once two consecutive readings both fall inside it and agree within 0.5°. The response names the panel the device now lights and its point size, because a pose change moves the app to a different coordinate space: re-snapshot afterwards, and never carry refs or coordinates across a `fold`.
+- `fold <closed|half-open|open>` puts a foldable iPhone simulator (iPhone Duo) into a hinge pose. No official host API sets a pose (ADR 0025), so the command presses the pose control in the Xcode Device Hub window through macOS accessibility, then reads the hinge angle back with `devicectl device motion hinge-angle` and reports the pose only when that reading agrees: `closed` is 0°, `open` is 180°, and `half-open` is any angle between them (Device Hub's Book preset, 130° on iOS 27.1). An angle inside that interval only proves the category, so `half-open` is reported once two consecutive readings both fall inside it and agree within 0.5°. The response names the panel the device now lights and its native panel point size, marked `coordinateSpace: "native-panel"`; that size is the panel's own geometry, not the next snapshot's viewport (a 669x951 inner panel can host a 951x669 app window), so it cannot place a tap. Re-snapshot afterwards, and never carry refs or coordinates across a `fold`.
 - `fold` is simulator-only and needs Xcode 27.1 or newer with Device Hub. The host needs Accessibility permission (`settings permission grant accessibility --platform macos`), and Device Hub must list the simulator; the command reopens Device Hub's window when it shows none, selects the device through the sidebar row keyed by its UDID, and restores the sidebar afterwards. A single-panel simulator such as an iPhone 17 fails with `UNSUPPORTED_OPERATION`; Android, web, Linux, HarmonyOS, Vega, physical devices, and the tvOS, macOS, and visionOS leaves refuse it.
 - `fold` costs one bounded hinge stream per read, and devicectl's smallest stream is five seconds: `closed` and `open` take about ten seconds, `half-open` about sixteen, because the hinge animates and the command waits for it to stop. A hinge whose last reading is some other pose fails with `COMMAND_FAILED` and `reason: fold-pose-unverified`, naming the angle CoreDevice still reports. A hinge seen `half-open` but never at rest fails with `reason: fold-pose-unsettled`, naming the observed and previous angles: the requested category was observed, and what is missing is a pose the hinge holds (#2730).
 - `action-button` is not a cheap command to loop. On an iPhone 17 Pro Simulator the press itself spent about five seconds inside XCUITest, while `home` and `app-switcher` on the same session took under two seconds each.

From 68a5e64cc8eb3885616755bec2c981e1bfc794e1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Tue, 22 Sep 2026 10:33:11 +0200
Subject: [PATCH 007/132] fix(apple): harden Device Hub discovery and sidebar
 recovery (#2733)

---
 .../DeviceHubWindowInventory.swift            |  65 ++++++
 .../DeviceHubPose.swift                       | 185 +++++-------------
 .../DeviceHubSidebar.swift                    |  57 ++++++
 .../DeviceHubWindowDiscovery.swift            | 108 ++++++++++
 .../DeviceHubWindowInventoryTests.swift       |  65 ++++++
 docs/adr/0025-foldable-apple-panels.md        |  43 ++--
 .../src/os/macos/helper.test.ts               |  48 ++++-
 website/docs/docs/commands.md                 |   3 +-
 8 files changed, 414 insertions(+), 160 deletions(-)
 create mode 100644 apple/macos-helper/Sources/AgentDeviceMacOSDeviceHub/DeviceHubWindowInventory.swift
 create mode 100644 apple/macos-helper/Sources/AgentDeviceMacOSHelper/DeviceHubSidebar.swift
 create mode 100644 apple/macos-helper/Sources/AgentDeviceMacOSHelper/DeviceHubWindowDiscovery.swift
 create mode 100644 apple/macos-helper/Tests/AgentDeviceMacOSDeviceHubTests/DeviceHubWindowInventoryTests.swift

diff --git a/apple/macos-helper/Sources/AgentDeviceMacOSDeviceHub/DeviceHubWindowInventory.swift b/apple/macos-helper/Sources/AgentDeviceMacOSDeviceHub/DeviceHubWindowInventory.swift
new file mode 100644
index 0000000000..066c86f340
--- /dev/null
+++ b/apple/macos-helper/Sources/AgentDeviceMacOSDeviceHub/DeviceHubWindowInventory.swift
@@ -0,0 +1,65 @@
+import ApplicationServices
+
+package enum DeviceHubWindowRead {
+  case available([AXUIElement])
+  case failed(Int32)
+}
+
+package struct DeviceHubWindowCandidate {
+  package let processID: Int32
+  package let window: AXUIElement
+}
+
+package enum DeviceHubRowLookup {
+  case identified(AXUIElement, restoreSidebar: Bool)
+  case sidebarUnavailable
+  case unconfirmed
+  case timedOut
+
+  package var diagnostic: String {
+    switch self {
+    case .identified: return "identified"
+    case .sidebarUnavailable: return "sidebar-unavailable"
+    case .unconfirmed: return "row-unconfirmed"
+    case .timedOut: return "timed-out"
+    }
+  }
+}
+
+package struct DeviceHubWindowInventory {
+  package private(set) var candidates: [DeviceHubWindowCandidate] = []
+  package private(set) var emptyProcessIDs: [Int32] = []
+  package private(set) var failures: [Int32: Int32] = [:]
+  package private(set) var candidateOutcomes: [String] = []
+  package private(set) var budgetExpired = false
+
+  package init() {}
+
+  package mutating func record(processID: Int32, read: DeviceHubWindowRead) {
+    switch read {
+    case .available(let windows):
+      if windows.isEmpty { emptyProcessIDs.append(processID) }
+      candidates.append(contentsOf: windows.map { DeviceHubWindowCandidate(processID: processID, window: $0) })
+    case .failed(let status):
+      failures[processID] = status
+    }
+  }
+
+  package mutating func record(candidate: Int, outcome: DeviceHubRowLookup) {
+    candidateOutcomes.append("\(candidates[candidate].processID):\(candidate):\(outcome.diagnostic)")
+  }
+
+  package mutating func expireBudget() { budgetExpired = true }
+
+  package func processesToReopen(attempted: Set<Int32>) -> [Int32] {
+    budgetExpired ? [] : emptyProcessIDs.filter { !attempted.contains($0) }
+  }
+
+  package func failureReason(reopenFailures: [Int32: String] = [:]) -> String {
+    if !failures.isEmpty { return "device-hub-window-read-failed" }
+    if budgetExpired { return "device-hub-discovery-timeout" }
+    if !candidates.isEmpty { return "device-hub-identity-unconfirmed" }
+    if let reason = reopenFailures.sorted(by: { $0.key < $1.key }).first?.value { return reason }
+    return "device-hub-window-missing"
+  }
+}
diff --git a/apple/macos-helper/Sources/AgentDeviceMacOSHelper/DeviceHubPose.swift b/apple/macos-helper/Sources/AgentDeviceMacOSHelper/DeviceHubPose.swift
index c33f4a69a4..05a6cce6e7 100644
--- a/apple/macos-helper/Sources/AgentDeviceMacOSHelper/DeviceHubPose.swift
+++ b/apple/macos-helper/Sources/AgentDeviceMacOSHelper/DeviceHubPose.swift
@@ -4,12 +4,7 @@ import ApplicationServices
 import Darwin
 import Foundation
 
-/// The Xcode Device Hub application. Its device windows carry an action bar whose pose controls
-/// are the only public seam onto the private channel that folds a simulator.
-private let deviceHubBundleId = "com.apple.dt.Devices"
-
-/// How long a reopen gets to restore a window, and a sidebar selection to switch the window's
-/// device, before the press is refused.
+/// How long sidebar selection and pose-control discovery may each wait before refusing a press.
 private let deviceHubSettleDeadline: TimeInterval = 8
 private let deviceHubPoll: TimeInterval = 0.25
 
@@ -51,16 +46,15 @@ func handleDeviceHub(arguments: [String]) throws -> any Encodable {
       details: ["reason": "accessibility-permission", "permission": "accessibility"]
     )
   }
-  guard let pid = deviceHubProcessIdentifier() else {
-    throw HelperError.commandFailed(
-      "Xcode Device Hub is not running",
-      details: ["reason": "device-hub-not-running", "bundleId": deviceHubBundleId]
-    )
+  let discovery = try discoverDeviceHubWindow(udid: udid, deviceName: deviceName)
+  let window = discovery.window
+  defer {
+    if discovery.revealedSidebar {
+      _ = setDeviceHubSidebar(visible: false, window: window,
+        deadline: ProcessInfo.processInfo.systemUptime + 0.5)
+    }
   }
-
-  let appElement = AXUIElementCreateApplication(pid)
-  let (window, reopened) = try deviceHubWindow(in: appElement, pid: pid, deviceName: deviceName)
-  let selected = try selectDevice(udid: udid, deviceName: deviceName, in: window, appElement: appElement)
+  let selected = try selectDevice(row: discovery.row, deviceName: deviceName, in: window)
   let windowTitle = stringAttribute(window, attribute: kAXTitleAttribute as String) ?? ""
   guard let button = awaitPoseButton(in: window, description: control) else {
     throw HelperError.commandFailed(
@@ -84,64 +78,12 @@ func handleDeviceHub(arguments: [String]) throws -> any Encodable {
       pose: pose.rawValue,
       control: control,
       windowTitle: windowTitle,
-      reopened: reopened,
+      reopened: discovery.reopened,
       selected: selected
     )
   )
 }
 
-/// Device Hub is launched through a trampoline, so LaunchServices registers it with no process
-/// identifier (`NSRunningApplication.processIdentifier` is -1) and an accessibility element built
-/// from that identifier is invalid. The process table is the only place its real pid appears.
-private func deviceHubProcessIdentifier() -> pid_t? {
-  let executableSuffix = deviceHubExecutableSuffix
-  let byteCount = proc_listpids(UInt32(PROC_ALL_PIDS), 0, nil, 0)
-  guard byteCount > 0 else { return nil }
-  var pids = [pid_t](repeating: 0, count: Int(byteCount) / MemoryLayout<pid_t>.size + 64)
-  let filled = proc_listpids(
-    UInt32(PROC_ALL_PIDS), 0, &pids, Int32(pids.count * MemoryLayout<pid_t>.size)
-  )
-  guard filled > 0 else { return nil }
-  var path = [CChar](repeating: 0, count: 4096)
-  for pid in pids.prefix(Int(filled) / MemoryLayout<pid_t>.size) where pid > 0 {
-    guard proc_pidpath(pid, &path, UInt32(path.count)) > 0 else { continue }
-    if String(cString: path).hasSuffix(executableSuffix) {
-      return pid
-    }
-  }
-  return nil
-}
-
-/// A device window to drive: the one already showing this device when there is one, otherwise
-/// any device window, since its sidebar can switch it to the device. A Device Hub with no window
-/// at all — a simulator booted headlessly leaves it that way — is asked to reopen one.
-private func deviceHubWindow(
-  in appElement: AXUIElement,
-  pid: pid_t,
-  deviceName: String
-) throws -> (window: AXUIElement, reopened: Bool) {
-  if let window = preferredWindow(in: appElement, deviceName: deviceName) {
-    return (window, false)
-  }
-  try sendReopenEvent(to: pid)
-  let deadline = Date().addingTimeInterval(deviceHubSettleDeadline)
-  while Date() < deadline {
-    Thread.sleep(forTimeInterval: deviceHubPoll)
-    if let window = preferredWindow(in: appElement, deviceName: deviceName) {
-      return (window, true)
-    }
-  }
-  throw HelperError.commandFailed(
-    "Device Hub shows no device window to drive",
-    details: ["reason": "device-hub-window-missing", "deviceName": deviceName]
-  )
-}
-
-private func preferredWindow(in appElement: AXUIElement, deviceName: String) -> AXUIElement? {
-  let candidates = windows(of: appElement)
-  return candidates.first { windowShows(deviceName: deviceName, $0) } ?? candidates.first
-}
-
 private func windowShows(deviceName: String, _ window: AXUIElement) -> Bool {
   return deviceHubWindowShows(
     deviceName: deviceName,
@@ -152,7 +94,7 @@ private func windowShows(deviceName: String, _ window: AXUIElement) -> Bool {
 /// `kAEReopenApplication` is what the Dock sends when an app with no open windows is clicked, and
 /// it is the one event Device Hub answers by restoring the device window. Sent to the process
 /// directly, because LaunchServices cannot address a trampolined app by bundle identifier.
-private func sendReopenEvent(to pid: pid_t) throws {
+func sendDeviceHubReopenEvent(to pid: pid_t, timeout: TimeInterval) throws {
   let target = NSAppleEventDescriptor(processIdentifier: pid)
   let event = NSAppleEventDescriptor(
     eventClass: AEEventClass(kCoreEventClass),
@@ -162,7 +104,7 @@ private func sendReopenEvent(to pid: pid_t) throws {
     transactionID: AETransactionID(kAnyTransactionID)
   )
   do {
-    _ = try event.sendEvent(options: [.noReply], timeout: 5)
+    _ = try event.sendEvent(options: [.noReply], timeout: min(5, max(0.001, timeout)))
   } catch {
     let code = (error as NSError).code
     throw HelperError.commandFailed(
@@ -178,66 +120,43 @@ private func sendReopenEvent(to pid: pid_t) throws {
 /// Switches the window to the device through its sidebar row, whose accessibility identifier is
 /// `TableRow.Device.<udid>` — the one place Device Hub exposes a device identity that two
 /// simulators sharing a name cannot confuse. A window already titled with the device still gets
-/// the selection when the row is visible, because the title alone cannot tell such twins apart.
+/// the selection, because the title alone cannot tell such twins apart.
 private func selectDevice(
-  udid: String,
+  row: AXUIElement,
   deviceName: String,
-  in window: AXUIElement,
-  appElement: AXUIElement
+  in window: AXUIElement
 ) throws -> Bool {
-  var shownSidebar = false
-  var row = deviceRow(udid: udid, in: window)
-  if row == nil, showSidebar(appElement: appElement) {
-    shownSidebar = true
-    let deadline = Date().addingTimeInterval(deviceHubSettleDeadline)
-    while row == nil, Date() < deadline {
-      Thread.sleep(forTimeInterval: deviceHubPoll)
-      row = deviceRow(udid: udid, in: window)
-    }
-  }
-  defer {
-    if shownSidebar { _ = pressMenuItem(appElement: appElement, menu: "View", item: "Hide Sidebar") }
-  }
-  guard let row else {
-    if windowShows(deviceName: deviceName, window) {
-      return false
-    }
-    throw HelperError.commandFailed(
-      "Device Hub lists no device \(udid) in its sidebar",
-      details: ["reason": "device-hub-device-missing", "udid": udid, "deviceName": deviceName]
-    )
-  }
+  let deadline = ProcessInfo.processInfo.systemUptime + deviceHubSettleDeadline
+  AXUIElementSetMessagingTimeout(row, 0.25)
+  AXUIElementSetMessagingTimeout(window, 0.25)
   let status = AXUIElementSetAttributeValue(row, kAXSelectedAttribute as CFString, kCFBooleanTrue)
-  guard status == .success else {
+  guard status == .success || status == .cannotComplete else {
     throw HelperError.commandFailed(
       "Device Hub refused to select \(deviceName) in its sidebar",
       details: ["reason": "device-hub-select-failed", "status": "\(status.rawValue)"]
     )
   }
-  let deadline = Date().addingTimeInterval(deviceHubSettleDeadline)
-  while !windowShows(deviceName: deviceName, window), Date() < deadline {
+  while ProcessInfo.processInfo.systemUptime < deadline {
+    var selected: CFTypeRef?
+    if AXUIElementCopyAttributeValue(row, kAXSelectedAttribute as CFString, &selected) == .success,
+      (selected as? Bool) == true, windowShows(deviceName: deviceName, window) { return true }
     Thread.sleep(forTimeInterval: deviceHubPoll)
   }
-  guard windowShows(deviceName: deviceName, window) else {
-    throw HelperError.commandFailed(
-      "Device Hub did not switch its window to \(deviceName)",
-      details: [
-        "reason": "device-hub-select-unconfirmed",
-        "windowTitle": stringAttribute(window, attribute: kAXTitleAttribute as String) ?? "",
-      ]
-    )
-  }
-  return true
+  throw HelperError.commandFailed(
+    "Device Hub did not confirm selection of \(deviceName)",
+    details: ["reason": "device-hub-select-unconfirmed", "status": "\(status.rawValue)"]
+  )
 }
 
-private func deviceRow(udid: String, in window: AXUIElement) -> AXUIElement? {
-  guard let label = findElement(root: window, depth: 0, where: {
+func deviceHubDeviceRow(udid: String, in window: AXUIElement, deadline: TimeInterval) -> AXUIElement? {
+  guard let label = findDeviceHubElement(root: window, depth: 0, deadline: deadline, where: {
     stringAttribute($0, attribute: "AXIdentifier") == deviceHubDeviceRowIdentifier(udid: udid)
   }) else {
     return nil
   }
   var current: AXUIElement? = label
-  while let element = current {
+  while let element = current, ProcessInfo.processInfo.systemUptime < deadline {
+    AXUIElementSetMessagingTimeout(element, Float(max(0.001, min(0.25, deadline - ProcessInfo.processInfo.systemUptime))))
     if stringAttribute(element, attribute: kAXRoleAttribute as String) == "AXRow" {
       return element
     }
@@ -246,36 +165,16 @@ private func deviceRow(udid: String, in window: AXUIElement) -> AXUIElement? {
   return nil
 }
 
-private func showSidebar(appElement: AXUIElement) -> Bool {
-  return pressMenuItem(appElement: appElement, menu: "View", item: "Show Sidebar")
-}
-
-private func pressMenuItem(appElement: AXUIElement, menu: String, item: String) -> Bool {
-  guard let menuBar = elementAttribute(appElement, attribute: kAXMenuBarAttribute as String) else {
-    return false
-  }
-  for menuBarItem in children(of: menuBar)
-  where stringAttribute(menuBarItem, attribute: kAXTitleAttribute as String) == menu {
-    for submenu in children(of: menuBarItem) {
-      for menuItem in children(of: submenu)
-      where stringAttribute(menuItem, attribute: kAXTitleAttribute as String) == item {
-        return AXUIElementPerformAction(menuItem, kAXPressAction as CFString) == .success
-      }
-    }
-  }
-  return false
-}
-
 /// The action bar is rebuilt for the device the window shows, so right after a sidebar selection
 /// the window already carries the new title while the pose controls are still being laid out.
 /// The controls are therefore awaited, not looked up once.
 private func awaitPoseButton(in window: AXUIElement, description: String) -> AXUIElement? {
-  let deadline = Date().addingTimeInterval(deviceHubSettleDeadline)
+  let deadline = ProcessInfo.processInfo.systemUptime + deviceHubSettleDeadline
   while true {
-    if let button = poseButton(in: window, description: description) {
+    if let button = poseButton(in: window, description: description, deadline: deadline) {
       return button
     }
-    guard Date() < deadline else { return nil }
+    guard ProcessInfo.processInfo.systemUptime < deadline else { return nil }
     Thread.sleep(forTimeInterval: deviceHubPoll)
   }
 }
@@ -283,29 +182,35 @@ private func awaitPoseButton(in window: AXUIElement, description: String) -> AXU
 /// The pose controls sit in the window's action bar as `AXButton`s described by their preset
 /// name; the simulated screen inside the same window is an iOS content group whose own buttons
 /// carry app labels, never these three.
-private func poseButton(in window: AXUIElement, description: String) -> AXUIElement? {
-  return findElement(root: window, depth: 0) {
+private func poseButton(in window: AXUIElement, description: String, deadline: TimeInterval) -> AXUIElement? {
+  return findDeviceHubElement(root: window, depth: 0, deadline: deadline) {
     stringAttribute($0, attribute: kAXRoleAttribute as String) == "AXButton"
       && stringAttribute($0, attribute: kAXDescriptionAttribute as String) == description
   }
 }
 
-private func findElement(
+func findDeviceHubElement(
   root: AXUIElement,
   depth: Int,
+  deadline: TimeInterval,
   where matches: (AXUIElement) -> Bool
 ) -> AXUIElement? {
-  if depth > 14 {
+  let remaining = deadline - ProcessInfo.processInfo.systemUptime
+  if depth > 14 || remaining <= 0 {
     return nil
   }
+  AXUIElementSetMessagingTimeout(root, Float(min(0.25, remaining)))
   for child in children(of: root) {
+    let remaining = deadline - ProcessInfo.processInfo.systemUptime
+    guard remaining > 0 else { return nil }
+    AXUIElementSetMessagingTimeout(child, Float(min(0.25, remaining)))
     if matches(child) {
       return child
     }
     if stringAttribute(child, attribute: kAXSubroleAttribute as String) == "iOSContentGroup" {
       continue
     }
-    if let nested = findElement(root: child, depth: depth + 1, where: matches) {
+    if let nested = findDeviceHubElement(root: child, depth: depth + 1, deadline: deadline, where: matches) {
       return nested
     }
   }
diff --git a/apple/macos-helper/Sources/AgentDeviceMacOSHelper/DeviceHubSidebar.swift b/apple/macos-helper/Sources/AgentDeviceMacOSHelper/DeviceHubSidebar.swift
new file mode 100644
index 0000000000..efebba26ea
--- /dev/null
+++ b/apple/macos-helper/Sources/AgentDeviceMacOSHelper/DeviceHubSidebar.swift
@@ -0,0 +1,57 @@
+import AgentDeviceMacOSDeviceHub
+import ApplicationServices
+import Foundation
+
+func identifyDeviceHubRow(
+  udid: String,
+  candidate: DeviceHubWindowCandidate,
+  deadline: TimeInterval
+) -> DeviceHubRowLookup {
+  let now = ProcessInfo.processInfo.systemUptime
+  let visibleRowDeadline = now + max(0, deadline - now) / 3
+  if let row = deviceHubDeviceRow(udid: udid, in: candidate.window, deadline: visibleRowDeadline) {
+    return .identified(row, restoreSidebar: false)
+  }
+  let searchDeadline = deadline - 0.25
+  guard let button = deviceHubSidebarButton(visible: true, window: candidate.window, deadline: searchDeadline) else {
+    return ProcessInfo.processInfo.systemUptime >= searchDeadline ? .timedOut : .sidebarUnavailable
+  }
+  var transferCleanup = false
+  defer {
+    if !transferCleanup {
+      _ = setDeviceHubSidebar(visible: false, window: candidate.window, deadline: deadline)
+    }
+  }
+  let status = pressDeviceHubSidebarButton(button, deadline: searchDeadline)
+  guard status == .success || status == .cannotComplete else { return .unconfirmed }
+  repeat {
+    if let row = deviceHubDeviceRow(udid: udid, in: candidate.window, deadline: searchDeadline) {
+      transferCleanup = true
+      return .identified(row, restoreSidebar: true)
+    }
+    let remaining = searchDeadline - ProcessInfo.processInfo.systemUptime
+    if remaining <= 0 { return .timedOut }
+    Thread.sleep(forTimeInterval: min(0.05, remaining))
+  } while ProcessInfo.processInfo.systemUptime < searchDeadline
+  return .timedOut
+}
+
+func setDeviceHubSidebar(visible: Bool, window: AXUIElement, deadline: TimeInterval) -> Bool {
+  guard let button = deviceHubSidebarButton(visible: visible, window: window, deadline: deadline) else { return false }
+  return pressDeviceHubSidebarButton(button, deadline: deadline) == .success
+}
+
+private func deviceHubSidebarButton(visible: Bool, window: AXUIElement, deadline: TimeInterval) -> AXUIElement? {
+  let description = visible ? "Show Sidebar" : "Hide Sidebar"
+  return findDeviceHubElement(root: window, depth: 0, deadline: deadline) {
+    stringAttribute($0, attribute: kAXRoleAttribute as String) == "AXButton"
+      && stringAttribute($0, attribute: kAXDescriptionAttribute as String) == description
+  }
+}
+
+private func pressDeviceHubSidebarButton(_ button: AXUIElement, deadline: TimeInterval) -> AXError {
+  let remaining = deadline - ProcessInfo.processInfo.systemUptime
+  guard remaining > 0 else { return .cannotComplete }
+  AXUIElementSetMessagingTimeout(button, Float(min(0.1, remaining)))
+  return AXUIElementPerformAction(button, kAXPressAction as CFString)
+}
diff --git a/apple/macos-helper/Sources/AgentDeviceMacOSHelper/DeviceHubWindowDiscovery.swift b/apple/macos-helper/Sources/AgentDeviceMacOSHelper/DeviceHubWindowDiscovery.swift
new file mode 100644
index 0000000000..efc125c6da
--- /dev/null
+++ b/apple/macos-helper/Sources/AgentDeviceMacOSHelper/DeviceHubWindowDiscovery.swift
@@ -0,0 +1,108 @@
+import AgentDeviceMacOSDeviceHub
+import AppKit
+import ApplicationServices
+import Darwin
+
+struct DiscoveredDeviceHubWindow {
+  let window: AXUIElement
+  let reopened: Bool
+  let row: AXUIElement
+  let revealedSidebar: Bool
+}
+
+func discoverDeviceHubWindow(udid: String, deviceName: String) throws -> DiscoveredDeviceHubWindow {
+  let deadline = ProcessInfo.processInfo.systemUptime + 8
+  var reopened = Set<pid_t>()
+  var reopenFailures: [pid_t: String] = [:]
+  var inventory = DeviceHubWindowInventory()
+  var processIDs: [pid_t] = []
+  repeat {
+    processIDs = deviceHubProcessIdentifiers()
+    if processIDs.isEmpty {
+      throw HelperError.commandFailed(
+        "Xcode Device Hub is not running",
+        details: ["reason": "device-hub-not-running", "bundleId": "com.apple.dt.Devices"]
+      )
+    }
+    inventory = DeviceHubWindowInventory()
+    for pid in processIDs {
+      let remaining = deadline - ProcessInfo.processInfo.systemUptime
+      guard remaining > 0 else { inventory.expireBudget(); break }
+      let app = AXUIElementCreateApplication(pid)
+      AXUIElementSetMessagingTimeout(app, Float(min(0.5, remaining)))
+      var value: CFTypeRef?
+      let status = AXUIElementCopyAttributeValue(app, kAXWindowsAttribute as CFString, &value)
+      if status == .success, let windows = value as? [AXUIElement] {
+        for window in windows { AXUIElementSetMessagingTimeout(window, 0.5) }
+        inventory.record(processID: pid, read: .available(windows))
+      } else {
+        inventory.record(processID: pid, read: .failed(
+          status == .success ? AXError.illegalArgument.rawValue : status.rawValue
+        ))
+      }
+    }
+    for (index, candidate) in inventory.candidates.enumerated() {
+      let now = ProcessInfo.processInfo.systemUptime
+      guard now < deadline else { inventory.expireBudget(); break }
+      let candidateDeadline = now + (deadline - now) / Double(inventory.candidates.count - index) / 2
+      let outcome = identifyDeviceHubRow(udid: udid, candidate: candidate, deadline: candidateDeadline)
+      inventory.record(candidate: index, outcome: outcome)
+      if case .identified(let row, let restoreSidebar) = outcome {
+        return DiscoveredDeviceHubWindow(window: candidate.window,
+          reopened: reopened.contains(candidate.processID), row: row, revealedSidebar: restoreSidebar)
+      }
+    }
+    let attempted = reopened.union(reopenFailures.keys)
+    for pid in inventory.processesToReopen(attempted: attempted) {
+      guard ProcessInfo.processInfo.systemUptime < deadline else { inventory.expireBudget(); break }
+      do {
+        try sendDeviceHubReopenEvent(to: pid, timeout: deadline - ProcessInfo.processInfo.systemUptime)
+        reopened.insert(pid)
+      } catch let error as HelperError {
+        guard case .commandFailed(_, let details) = error else { throw error }
+        reopenFailures[pid] = details["reason"] ?? "device-hub-reopen-failed"
+      }
+    }
+    let remaining = deadline - ProcessInfo.processInfo.systemUptime
+    if remaining <= 0 { inventory.expireBudget(); break }
+    Thread.sleep(forTimeInterval: min(0.25, remaining))
+  } while ProcessInfo.processInfo.systemUptime < deadline
+
+  let statuses = inventory.failures.sorted { $0.key < $1.key }
+    .map { "\($0.key):\($0.value)" }.joined(separator: ",")
+  throw HelperError.commandFailed(
+    "Could not confirm a Device Hub window for the requested device",
+    details: [
+      "reason": inventory.failureReason(reopenFailures: reopenFailures),
+      "reopenFailures": reopenFailures.sorted { $0.key < $1.key }.map { "\($0.key):\($0.value)" }.joined(separator: ","),
+      "candidateOutcomes": inventory.candidateOutcomes.joined(separator: ","),
+      "udid": udid,
+      "deviceName": deviceName,
+      "processIDs": processIDs.map(String.init).joined(separator: ","),
+      "axWindowReadStatuses": statuses,
+      "hostDisplayIDs": deviceHubHostDisplays().map { String($0) }.joined(separator: ","),
+    ]
+  )
+}
+
+private func deviceHubProcessIdentifiers() -> [pid_t] {
+  let byteCount = proc_listpids(UInt32(PROC_ALL_PIDS), 0, nil, 0)
+  guard byteCount > 0 else { return [] }
+  var pids = [pid_t](repeating: 0, count: Int(byteCount) / MemoryLayout<pid_t>.size + 64)
+  let filled = proc_listpids(UInt32(PROC_ALL_PIDS), 0, &pids, Int32(pids.count * MemoryLayout<pid_t>.size))
+  guard filled > 0 else { return [] }
+  return pids.prefix(Int(filled) / MemoryLayout<pid_t>.size).filter { pid in
+    guard pid > 0 else { return false }
+    var path = [CChar](repeating: 0, count: 4096)
+    guard proc_pidpath(pid, &path, UInt32(path.count)) > 0 else { return false }
+    return String(cString: path).hasSuffix(deviceHubExecutableSuffix)
+  }.sorted()
+}
+
+private func deviceHubHostDisplays() -> [CGDirectDisplayID] {
+  var count: UInt32 = 0
+  guard CGGetActiveDisplayList(0, nil, &count) == .success else { return [] }
+  var displays = [CGDirectDisplayID](repeating: 0, count: Int(count))
+  guard CGGetActiveDisplayList(count, &displays, &count) == .success else { return [] }
+  return Array(displays.prefix(Int(count)))
+}
diff --git a/apple/macos-helper/Tests/AgentDeviceMacOSDeviceHubTests/DeviceHubWindowInventoryTests.swift b/apple/macos-helper/Tests/AgentDeviceMacOSDeviceHubTests/DeviceHubWindowInventoryTests.swift
new file mode 100644
index 0000000000..9ab682dcde
--- /dev/null
+++ b/apple/macos-helper/Tests/AgentDeviceMacOSDeviceHubTests/DeviceHubWindowInventoryTests.swift
@@ -0,0 +1,65 @@
+import ApplicationServices
+import XCTest
+@testable import AgentDeviceMacOSDeviceHub
+
+final class DeviceHubWindowInventoryTests: XCTestCase {
+  func testLaterWindowKeepsItsProcessAndDoesNotPreventEmptyProcessReopen() {
+    var inventory = DeviceHubWindowInventory()
+    let window = AXUIElementCreateApplication(20)
+    inventory.record(processID: 10, read: .available([]))
+    inventory.record(processID: 20, read: .available([window]))
+    XCTAssertEqual(inventory.candidates.map(\.processID), [20])
+    XCTAssertTrue(CFEqual(inventory.candidates[0].window, window))
+    inventory.record(candidate: 0, outcome: .sidebarUnavailable)
+    XCTAssertEqual(inventory.processesToReopen(attempted: []), [10])
+    XCTAssertEqual(inventory.failureReason(), "device-hub-identity-unconfirmed")
+    XCTAssertEqual(inventory.candidateOutcomes, ["20:0:sidebar-unavailable"])
+  }
+
+  func testFailedReadsAreNotReopenedOrMisreportedAsMissingWindows() {
+    var inventory = DeviceHubWindowInventory()
+    inventory.record(processID: 10, read: .failed(-25204))
+    inventory.record(processID: 20, read: .available([]))
+    XCTAssertEqual(inventory.processesToReopen(attempted: []), [20])
+    XCTAssertEqual(inventory.failures, [10: -25204])
+    XCTAssertEqual(inventory.failureReason(), "device-hub-window-read-failed")
+  }
+
+  func testSuccessfulEmptyReadIsMissingAndReopenIsAttemptedOnlyOnce() {
+    var inventory = DeviceHubWindowInventory()
+    inventory.record(processID: 10, read: .available([]))
+    XCTAssertEqual(inventory.failureReason(), "device-hub-window-missing")
+    XCTAssertEqual(inventory.processesToReopen(attempted: []), [10])
+    XCTAssertEqual(inventory.processesToReopen(attempted: [10]), [])
+  }
+
+  func testSharedBudgetExhaustionStopsReopenWithoutClaimingMissingDevice() {
+    var inventory = DeviceHubWindowInventory()
+    inventory.record(processID: 10, read: .available([]))
+    inventory.expireBudget()
+    XCTAssertEqual(inventory.processesToReopen(attempted: []), [])
+    XCTAssertEqual(inventory.failureReason(), "device-hub-discovery-timeout")
+  }
+
+  func testCandidateOutcomesRetainUncertaintyAndOwningProcess() {
+    var inventory = DeviceHubWindowInventory()
+    inventory.record(processID: 10, read: .available([AXUIElementCreateApplication(10)]))
+    inventory.record(processID: 20, read: .available([AXUIElementCreateApplication(20)]))
+    inventory.record(candidate: 0, outcome: .timedOut)
+    inventory.record(candidate: 1, outcome: .unconfirmed)
+    XCTAssertEqual(inventory.candidateOutcomes, ["10:0:timed-out", "20:1:row-unconfirmed"])
+    XCTAssertEqual(inventory.failureReason(), "device-hub-identity-unconfirmed")
+  }
+  func testUnrelatedReopenFailureDoesNotMaskCandidateUncertainty() {
+    var inventory = DeviceHubWindowInventory()
+    inventory.record(processID: 10, read: .available([]))
+    let failures: [Int32: String] = [10: "automation-permission"]
+    XCTAssertEqual(inventory.failureReason(reopenFailures: failures), "automation-permission")
+    inventory.record(processID: 20, read: .available([AXUIElementCreateApplication(20)]))
+    inventory.record(candidate: 0, outcome: .timedOut)
+    XCTAssertEqual(inventory.failureReason(reopenFailures: failures), "device-hub-identity-unconfirmed")
+    inventory.expireBudget()
+    XCTAssertEqual(inventory.failureReason(reopenFailures: failures), "device-hub-discovery-timeout")
+  }
+
+}
diff --git a/docs/adr/0025-foldable-apple-panels.md b/docs/adr/0025-foldable-apple-panels.md
index b8031df053..1be5ff2ac3 100644
--- a/docs/adr/0025-foldable-apple-panels.md
+++ b/docs/adr/0025-foldable-apple-panels.md
@@ -116,10 +116,26 @@ size, because the point size is what tells an agent its refs are stale.
 Requirements the command states in its own errors: Accessibility permission for the host
 (`accessibility-permission`), a running Device Hub (`fold` launches it in the background the way
 `open` does), a device window it can reopen (`device-hub-window-missing`), and a sidebar row for
-the UDID (`device-hub-device-missing`). A single-panel simulator is refused before anything is
+the UDID (otherwise `device-hub-identity-unconfirmed`). A single-panel simulator is refused before anything is
 pressed (`single-panel-device`), and the leaf fact refuses physical devices and every non-iPhone
 simulator OS.
 
+Window discovery reads `AXWindows` from every matching Device Hub process within one shared
+retry budget. These are application-wide windows; discovery does not click through monitors or
+move windows to the main display. A failed accessibility read retains its AX status and returns
+`device-hub-window-read-failed`, rather than masquerading as an empty window list. Only successful
+empty reads trigger a reopen. A matching UDID sidebar row is required before pressing, including
+when a window title already matches. An unrelated window does not stop attempts on other
+windows or empty processes. A hidden sidebar is revealed through that window’s own toolbar button;
+application-wide menus cannot redirect the action to another window. Sidebar reads and
+restoration use bounded AX calls. Cleanup is registered before a sidebar press, since an AX reply
+can time out after the action applied. Selection verifies the row's `AXSelected` state and the
+window title even after an uncertain reply. Discovery passes the proven row to selection instead
+of searching twice. Inconclusive candidates report `device-hub-identity-unconfirmed` with each
+candidate's outcome; exhausting the shared budget before finishing work reports
+`device-hub-discovery-timeout`. Neither claims a device is absent. Active host display IDs stay
+in discovery error details; display geometry does not participate in AX window selection.
+
 ## Amendment: an observed half-open angle is not a settled pose (issue #2730)
 
 The rule above first ended the other way: `half-open` was also reported when the four-read budget
@@ -353,24 +369,17 @@ explicit.
   was measured, so that path stays unverified. - **Quarter-turn detection.** Both Duo panels report
   `currentOrientation: rot90`, and no available path rotates a foldable, so the orientation half of
   the inventory is carried but never exercised against a changed value. - **Pose control on a
-  second Device Hub instance.** `fold` drives the first `DeviceHub` process in the process table.
-  Two Xcodes each running a Device Hub is not a state this was verified in. - **A hinge that
+  second Device Hub instance.** Discovery checks every matching process, but simultaneous Xcodes
+  and the secondary-display fold matrix remain unverified on live hardware. - **A hinge that
   settles slowly.** Four reads is twenty seconds of streams, and a Duo that needs longer to come to
   rest inside `half-open` is now refused where the superseded rule would have reported a pose.
   Every Duo run observed for this change settled inside the budget; no simulator that needs longer
   was seen, so the budget stays as it is rather than growing on a hypothesis.
 
-- **Pose control when two simulators share a name.** `fold` picks the device by the sidebar row's
-  `AXIdentifier`, but `selectDevice` in `DeviceHubPose.swift` confirms the switch through
-  `windowShows(deviceName:)`, which reads the window title, and it skips the selection altogether
-  when no row was found and that title already matches — and two simulators named `iPhone Duo` are
-  both titled `iPhone Duo – iOS 27.1`. Observed while pressing the poses for the captures above,
-  and consistent with that path, a `fold open` aimed at one Duo pressed the pose control of the
-  other, which unfolded while the intended device stayed closed; the `apple_fold_pose_pressed`
-  diagnostic reports `selected` and nothing gates the press on it. The hinge read-back is what
-  stopped the command reporting a pose it had not achieved, yet the untargeted device had already
-  moved. Selecting that device's row before pressing routed every later pose correctly, so the row
-  is the only device identity Device Hub offers and an unconfirmed selection leaves the press aimed
-  at whatever it happens to display. - **Physical foldables.** Device Hub poses simulators only;
-  the leaf fact refuses a physical device, and the hinge stream on one was not exercised.
-
+- **Pose control when two simulators share a name.** The earlier title-only fallback could press
+  a different Duo when the intended device's row was unavailable; hinge verification refused the
+  result only after the other device had moved. Discovery now requires the UDID row, and selection
+  confirms `AXSelected` as well as the window title before pressing. Live wrong-UDID refusal and
+  hidden-sidebar recovery were checked; the simultaneous same-name simulator matrix remains open.
+- **Physical foldables.** Device Hub poses simulators only; the leaf fact refuses a physical device,
+  and the hinge stream on one was not exercised.
diff --git a/packages/platform-apple/src/os/macos/helper.test.ts b/packages/platform-apple/src/os/macos/helper.test.ts
index eb8d24b0e9..41f4def72a 100644
--- a/packages/platform-apple/src/os/macos/helper.test.ts
+++ b/packages/platform-apple/src/os/macos/helper.test.ts
@@ -1,7 +1,12 @@
 import assert from 'node:assert/strict';
-import { test } from 'vitest';
+import { expect, test } from 'vitest';
 import { createLocalAppleToolProvider, withAppleToolProvider } from '../../core/tool-provider.ts';
-import { macOsClickScheduleMs, runMacOsPressAction, runMacOsSnapshotAction } from './helper.ts';
+import {
+  macOsClickScheduleMs,
+  runMacOsPressAction,
+  runMacOsSnapshotAction,
+  runMacOsDeviceHubPoseAction,
+} from './helper.ts';
 
 test('macOS helper snapshot passes cancellation to the helper process', async () => {
   const controller = new AbortController();
@@ -207,3 +212,42 @@ test('macOS helper press stays a single held click when nothing is repeated', as
   assert.equal(receivedArgs.includes('--hold-ms'), false);
   assert.equal(receivedArgs.includes('--interval-ms'), false);
 });
+
+test('Device Hub window read failures preserve AX status and process diagnostics', async () => {
+  const provider = createLocalAppleToolProvider({
+    macosHelper: {
+      run: async () => ({
+        exitCode: 1,
+        stdout: JSON.stringify({
+          ok: false,
+          error: {
+            message: "Could not read Device Hub's accessible windows",
+            details: {
+              reason: 'device-hub-window-read-failed',
+              processIDs: '10,20',
+              axWindowReadStatuses: '10:-25204',
+              hostDisplayIDs: '1,2',
+            },
+          },
+        }),
+        stderr: '',
+      }),
+    },
+  });
+  await withAppleToolProvider(provider, async () => {
+    await assert.rejects(
+      runMacOsDeviceHubPoseAction({ udid: 'duo', deviceName: 'iPhone Duo', pose: 'open' }),
+      (error: unknown) => {
+        expect(error).toMatchObject({
+          details: {
+            reason: 'device-hub-window-read-failed',
+            processIDs: '10,20',
+            axWindowReadStatuses: '10:-25204',
+            hostDisplayIDs: '1,2',
+          },
+        });
+        return true;
+      },
+    );
+  });
+});
diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md
index 44c99a6af7..08f8c42f3f 100644
--- a/website/docs/docs/commands.md
+++ b/website/docs/docs/commands.md
@@ -92,7 +92,8 @@ agent-device fold open
 - `action-button` does not activate or relaunch the session's app, and it takes no `--settle`: pressing a hardware button is not a navigation, so the app stays where it was.
 - `action-button` reports that the press was dispatched, not what the system did with it. Simulators run no Shortcuts and no App Intents, so what a press triggers can only be verified on a physical iPhone; on a Simulator the command proves the press was accepted and that the session app was not brought forward.
 - `fold <closed|half-open|open>` puts a foldable iPhone simulator (iPhone Duo) into a hinge pose. No official host API sets a pose (ADR 0025), so the command presses the pose control in the Xcode Device Hub window through macOS accessibility, then reads the hinge angle back with `devicectl device motion hinge-angle` and reports the pose only when that reading agrees: `closed` is 0°, `open` is 180°, and `half-open` is any angle between them (Device Hub's Book preset, 130° on iOS 27.1). An angle inside that interval only proves the category, so `half-open` is reported once two consecutive readings both fall inside it and agree within 0.5°. The response names the panel the device now lights and its native panel point size, marked `coordinateSpace: "native-panel"`; that size is the panel's own geometry, not the next snapshot's viewport (a 669x951 inner panel can host a 951x669 app window), so it cannot place a tap. Re-snapshot afterwards, and never carry refs or coordinates across a `fold`.
-- `fold` is simulator-only and needs Xcode 27.1 or newer with Device Hub. The host needs Accessibility permission (`settings permission grant accessibility --platform macos`), and Device Hub must list the simulator; the command reopens Device Hub's window when it shows none, selects the device through the sidebar row keyed by its UDID, and restores the sidebar afterwards. A single-panel simulator such as an iPhone 17 fails with `UNSUPPORTED_OPERATION`; Android, web, Linux, HarmonyOS, Vega, physical devices, and the tvOS, macOS, and visionOS leaves refuse it.
+- `fold` is simulator-only and needs Xcode 27.1 or newer with Device Hub. The host needs Accessibility permission (`settings permission grant accessibility --platform macos`), and Device Hub must list the simulator; the command reopens Device Hub's window when it shows none, selects the device through the sidebar row keyed by its UDID, and attempts to restore any sidebar it revealed afterwards within a bounded cleanup budget. Sidebar actions use the selected window’s toolbar button. A single-panel simulator such as an iPhone 17 fails with `UNSUPPORTED_OPERATION`; Android, web, Linux, HarmonyOS, Vega, physical devices, and the tvOS, macOS, and visionOS leaves refuse it.
+- `fold` discovers windows across running Device Hub processes without requiring main-display placement. Failed accessibility reads report `device-hub-window-read-failed` with AX status and process/display diagnostics; they do not count as an empty window list. Inconclusive row lookup reports `device-hub-identity-unconfirmed` with candidate outcomes; an interrupted discovery reports `device-hub-discovery-timeout`. Active host display IDs are included only in discovery errors.
 - `fold` costs one bounded hinge stream per read, and devicectl's smallest stream is five seconds: `closed` and `open` take about ten seconds, `half-open` about sixteen, because the hinge animates and the command waits for it to stop. A hinge whose last reading is some other pose fails with `COMMAND_FAILED` and `reason: fold-pose-unverified`, naming the angle CoreDevice still reports. A hinge seen `half-open` but never at rest fails with `reason: fold-pose-unsettled`, naming the observed and previous angles: the requested category was observed, and what is missing is a pose the hinge holds (#2730).
 - `action-button` is not a cheap command to loop. On an iPhone 17 Pro Simulator the press itself spent about five seconds inside XCUITest, while `home` and `app-switcher` on the same session took under two seconds each.
 - On iOS devices, `http(s)://` URLs open in Safari when no app is active. Custom scheme URLs require an active app in the session.

From d6ba1059287c9b28ce0775fbf23103950c322163 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Tue, 22 Sep 2026 13:08:17 +0200
Subject: [PATCH 008/132] refactor(capture-kit): resolve recording helper
 scripts from swift-cache (#2743)

---
 .../src/recording/__tests__/overlay.test.ts   | 22 +------
 packages/capture-kit/src/recording/overlay.ts | 61 ++++---------------
 .../src/recording/swift-cache.test.ts         | 26 +++++++-
 .../capture-kit/src/recording/swift-cache.ts  | 54 ++++++++++++++++
 4 files changed, 93 insertions(+), 70 deletions(-)

diff --git a/packages/capture-kit/src/recording/__tests__/overlay.test.ts b/packages/capture-kit/src/recording/__tests__/overlay.test.ts
index aabd5b73e8..47b1b34180 100644
--- a/packages/capture-kit/src/recording/__tests__/overlay.test.ts
+++ b/packages/capture-kit/src/recording/__tests__/overlay.test.ts
@@ -28,7 +28,7 @@ vi.mock('../video.ts', () => ({
   waitForPlayableVideo: vi.fn(async () => {}),
 }));
 
-import { buildRecordingScriptPathCandidates, overlayRecordingTouches } from '../overlay.ts';
+import { overlayRecordingTouches } from '../overlay.ts';
 import { AppError } from '@agent-device/kernel/errors';
 import { runCmd } from '@agent-device/host-kit/command';
 
@@ -130,23 +130,3 @@ test('overlay forwards the requested high export preset', async () => {
     expect.arrayContaining(['--events', telemetryPath, '--quality', 'high']),
   );
 });
-
-test('recording script candidates include packaged dist apple-runner source', () => {
-  const packageRoot = path.join(tmpDir, 'package');
-  const scriptPath = path.join(
-    packageRoot,
-    'dist/apple/runner/AgentDeviceRunner/RecordingScripts/recording-overlay.swift',
-  );
-  fs.mkdirSync(path.dirname(scriptPath), { recursive: true });
-  fs.writeFileSync(scriptPath, 'print("overlay")\n');
-
-  const candidates = buildRecordingScriptPathCandidates(
-    'recording-overlay.swift',
-    path.join(packageRoot, 'dist/src'),
-    packageRoot,
-    tmpDir,
-  );
-  const firstExisting = candidates.find((candidate) => fs.existsSync(candidate));
-
-  expect(firstExisting).toBe(scriptPath);
-});
diff --git a/packages/capture-kit/src/recording/overlay.ts b/packages/capture-kit/src/recording/overlay.ts
index 6dc03ccf82..9e4397072f 100644
--- a/packages/capture-kit/src/recording/overlay.ts
+++ b/packages/capture-kit/src/recording/overlay.ts
@@ -1,60 +1,19 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { runCmd } from '@agent-device/host-kit/command';
 import { AppError } from '@agent-device/kernel/errors';
-import { buildSwiftToolEnv, compileSwiftSourceFile } from './swift-cache.ts';
 import { findProjectRoot } from '@agent-device/host-kit/version';
+import {
+  buildSwiftToolEnv,
+  compileSwiftSourceFile,
+  resolveRecordingScriptPath,
+} from './swift-cache.ts';
 import { waitForPlayableVideo, waitForStableFile } from './video.ts';
 import {
   DEFAULT_RECORDING_EXPORT_QUALITY,
   type RecordingExportQuality,
 } from '@agent-device/contracts/recording';
 
-export function buildRecordingScriptPathCandidates(
-  scriptName: string,
-  moduleDir: string,
-  projectRoot: string,
-  cwd: string,
-): string[] {
-  const sourceScriptPath = `apple/runner/AgentDeviceRunner/RecordingScripts/${scriptName}`;
-  const packagedScriptPath = `dist/${sourceScriptPath}`;
-  return [
-    path.resolve(moduleDir, scriptName),
-    path.resolve(projectRoot, sourceScriptPath),
-    path.resolve(moduleDir, `../${sourceScriptPath}`),
-    path.resolve(moduleDir, `../../${sourceScriptPath}`),
-    path.resolve(moduleDir, `../../../${sourceScriptPath}`),
-    path.resolve(projectRoot, packagedScriptPath),
-    path.resolve(cwd, sourceScriptPath),
-  ];
-}
-
-function resolveRecordingScriptPath(scriptName: string): string {
-  const moduleDir = path.dirname(fileURLToPath(import.meta.url));
-  const scriptCandidates = buildRecordingScriptPathCandidates(
-    scriptName,
-    moduleDir,
-    findProjectRoot(),
-    process.cwd(),
-  );
-
-  for (const candidate of scriptCandidates) {
-    if (fs.existsSync(candidate)) {
-      return candidate;
-    }
-  }
-
-  throw new AppError('COMMAND_FAILED', `Missing recording helper script: ${scriptName}`, {
-    hint: 'Ensure apple/runner/AgentDeviceRunner/RecordingScripts is present in this checkout or bundled under dist/apple/runner in the package.',
-    scriptName,
-    searchedPaths: scriptCandidates,
-  });
-}
-
-let overlayScriptPath: string | undefined;
-let exportSupportScriptPath: string | undefined;
-
 export function getRecordingOverlaySupportWarning(
   hostPlatform: NodeJS.Platform = process.platform,
 ): string | undefined {
@@ -64,13 +23,19 @@ export function getRecordingOverlaySupportWarning(
   return 'touch overlay burn-in is only available on macOS hosts; returning raw video plus gesture telemetry';
 }
 
+let overlayScriptPath: string | undefined;
+let exportSupportScriptPath: string | undefined;
+
 function getOverlayScriptPath(): string {
-  overlayScriptPath ??= resolveRecordingScriptPath('recording-overlay.swift');
+  overlayScriptPath ??= resolveRecordingScriptPath('recording-overlay.swift', findProjectRoot());
   return overlayScriptPath;
 }
 
 function getExportSupportScriptPath(): string {
-  exportSupportScriptPath ??= resolveRecordingScriptPath('RecordingExportSupport.swift');
+  exportSupportScriptPath ??= resolveRecordingScriptPath(
+    'RecordingExportSupport.swift',
+    findProjectRoot(),
+  );
   return exportSupportScriptPath;
 }
 
diff --git a/packages/capture-kit/src/recording/swift-cache.test.ts b/packages/capture-kit/src/recording/swift-cache.test.ts
index 7ec3ca69a8..c008547f1b 100644
--- a/packages/capture-kit/src/recording/swift-cache.test.ts
+++ b/packages/capture-kit/src/recording/swift-cache.test.ts
@@ -14,7 +14,11 @@ vi.mock(import('@agent-device/host-kit/command'), async (importOriginal) => ({
 }));
 
 import { runCmd } from '@agent-device/host-kit/command';
-import { compileSwiftSourceFile, compileSwiftSourceText } from './swift-cache.ts';
+import {
+  buildRecordingScriptPathCandidates,
+  compileSwiftSourceFile,
+  compileSwiftSourceText,
+} from './swift-cache.ts';
 
 const mockRunCmd = vi.mocked(runCmd);
 
@@ -246,3 +250,23 @@ async function expectConcurrentCacheReuse(compile: () => Promise<string>): Promi
   expect(fs.readFileSync(firstExecutable, 'utf8')).toBe('compiled once');
   expect(mockRunCmd).toHaveBeenCalledTimes(1);
 }
+
+test('recording script candidates include packaged dist apple-runner source', () => {
+  const packageRoot = path.join(tmpDir, 'package');
+  const scriptPath = path.join(
+    packageRoot,
+    'dist/apple/runner/AgentDeviceRunner/RecordingScripts/recording-overlay.swift',
+  );
+  fs.mkdirSync(path.dirname(scriptPath), { recursive: true });
+  fs.writeFileSync(scriptPath, 'print("overlay")\n');
+
+  const candidates = buildRecordingScriptPathCandidates(
+    'recording-overlay.swift',
+    path.join(packageRoot, 'dist/src'),
+    packageRoot,
+    tmpDir,
+  );
+  const firstExisting = candidates.find((candidate) => fs.existsSync(candidate));
+
+  expect(firstExisting).toBe(scriptPath);
+});
diff --git a/packages/capture-kit/src/recording/swift-cache.ts b/packages/capture-kit/src/recording/swift-cache.ts
index 366a2db6b4..36471a8c3f 100644
--- a/packages/capture-kit/src/recording/swift-cache.ts
+++ b/packages/capture-kit/src/recording/swift-cache.ts
@@ -2,6 +2,7 @@ import { createHash } from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { trimEdgeDashes } from '@agent-device/kernel/collections';
 import { AppError } from '@agent-device/kernel/errors';
 import { runCmd } from '@agent-device/host-kit/command';
@@ -14,6 +15,59 @@ import {
 
 const SWIFT_CACHE_VERSION = '2';
 const LOCK_RETRY_DELAY_MS = 25;
+const RECORDING_SCRIPT_SUBDIRECTORY = 'apple/runner/AgentDeviceRunner/RecordingScripts';
+
+/**
+ * Where a recording helper script can live, in the order a checkout, a source build, and a
+ * published package each answer from.
+ */
+export function buildRecordingScriptPathCandidates(
+  scriptName: string,
+  moduleDir: string,
+  projectRoot: string,
+  cwd: string,
+): string[] {
+  const sourceScriptPath = `${RECORDING_SCRIPT_SUBDIRECTORY}/${scriptName}`;
+  const packagedScriptPath = `dist/${sourceScriptPath}`;
+  return [
+    path.resolve(moduleDir, scriptName),
+    path.resolve(projectRoot, sourceScriptPath),
+    path.resolve(moduleDir, `../${sourceScriptPath}`),
+    path.resolve(moduleDir, `../../${sourceScriptPath}`),
+    path.resolve(moduleDir, `../../../${sourceScriptPath}`),
+    path.resolve(projectRoot, packagedScriptPath),
+    path.resolve(cwd, sourceScriptPath),
+  ];
+}
+
+/**
+ * Resolves one recording helper script: checkout, built package, or working-directory fallback.
+ * The caller names the project root it trusts, so this module stays free of host metadata lookup.
+ */
+export function resolveRecordingScriptPath(
+  scriptName: string,
+  projectRoot: string,
+  moduleDir = path.dirname(fileURLToPath(import.meta.url)),
+  cwd = process.cwd(),
+): string {
+  const scriptCandidates = buildRecordingScriptPathCandidates(
+    scriptName,
+    moduleDir,
+    projectRoot,
+    cwd,
+  );
+  for (const candidate of scriptCandidates) {
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  throw new AppError('COMMAND_FAILED', `Missing recording helper script: ${scriptName}`, {
+    hint: `Ensure ${RECORDING_SCRIPT_SUBDIRECTORY} is present in this checkout or bundled under dist/${RECORDING_SCRIPT_SUBDIRECTORY} in the package.`,
+    scriptName,
+    searchedPaths: scriptCandidates,
+  });
+}
 
 export function buildSwiftToolEnv(env: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
   const root = getSwiftCacheRoot();

From 0f825dd913670086d491e83a0011ea372298b70a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Tue, 22 Sep 2026 13:08:18 +0200
Subject: [PATCH 009/132] feat(recording): decode contact-sheet frames from an
 exported clip (#2744)

---
 .../RecordingExportSupport.swift              |   3 +
 .../RecordingScripts/recording-frames.swift   | 203 ++++++++++
 .../capture-kit/src/png-pixels.fixtures.ts    |  21 +
 .../__tests__/recording-scripts.test.ts       |  31 ++
 .../recording/contact-sheet-frames.test.ts    | 363 ++++++++++++++++++
 .../src/recording/contact-sheet-frames.ts     | 278 ++++++++++++++
 .../src/recording/contact-sheet-report.ts     |  11 +
 .../src/recording/contact-sheet.fixtures.ts   |  94 +++++
 8 files changed, 1004 insertions(+)
 create mode 100644 apple/runner/AgentDeviceRunner/RecordingScripts/recording-frames.swift
 create mode 100644 packages/capture-kit/src/png-pixels.fixtures.ts
 create mode 100644 packages/capture-kit/src/recording/contact-sheet-frames.test.ts
 create mode 100644 packages/capture-kit/src/recording/contact-sheet-frames.ts
 create mode 100644 packages/capture-kit/src/recording/contact-sheet-report.ts
 create mode 100644 packages/capture-kit/src/recording/contact-sheet.fixtures.ts

diff --git a/apple/runner/AgentDeviceRunner/RecordingScripts/RecordingExportSupport.swift b/apple/runner/AgentDeviceRunner/RecordingScripts/RecordingExportSupport.swift
index 5837d32ff4..8892f41584 100644
--- a/apple/runner/AgentDeviceRunner/RecordingScripts/RecordingExportSupport.swift
+++ b/apple/runner/AgentDeviceRunner/RecordingScripts/RecordingExportSupport.swift
@@ -9,11 +9,14 @@ enum RecordingScriptError: Error, CustomStringConvertible {
   case invalidArgs(String)
   case missingVideoTrack
   case exportFailed(String)
+  case frameWriteFailed(String)
 
   var description: String {
     switch self {
     case .invalidArgs(let message):
       return message
+    case .frameWriteFailed(let message):
+      return message
     case .missingVideoTrack:
       return "Input video does not contain a video track."
     case .exportFailed(let message):
diff --git a/apple/runner/AgentDeviceRunner/RecordingScripts/recording-frames.swift b/apple/runner/AgentDeviceRunner/RecordingScripts/recording-frames.swift
new file mode 100644
index 0000000000..2fc72fbcf2
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/RecordingScripts/recording-frames.swift
@@ -0,0 +1,203 @@
+import AVFoundation
+import Foundation
+import ImageIO
+import UniformTypeIdentifiers
+
+/// Extracts the frames at the requested presentation times from a recording and writes each one as
+/// a PNG, then prints a JSON manifest naming the time each returned image actually carries.
+///
+/// The caller owns the sampling grid: it passes an explicit, bounded list of times, so this script
+/// never walks a whole clip. `--times` is the whole job description, which keeps the amount of
+/// decoding, the bytes on disk, and the wall clock all bounded by the request rather than by the
+/// recording's length.
+///
+/// Reported times are the generator's *actual* return times, not the ones that were asked for. A
+/// decoder answers a request with the frame it holds at that moment; the manifest says which frame
+/// that was, so nothing downstream can print a requested time as though it had been decoded.
+
+struct FrameManifest: Encodable {
+  struct Frame: Encodable {
+    let index: Int
+    let requestedTimeMs: Double
+    let actualTimeMs: Double
+    let width: Int
+    let height: Int
+    let path: String
+  }
+
+  struct Skipped: Encodable {
+    let index: Int
+    let requestedTimeMs: Double
+    let reason: String
+  }
+
+  let inputPath: String
+  let durationMs: Double
+  let frames: [Frame]
+  let skipped: [Skipped]
+}
+
+/// Entry point: `@main` because multi-file swiftc compilation reserves top-level statements for
+/// `main.swift`, which cannot be shared per-script.
+@main
+enum RecordingFrames {
+  static func main() {
+    do {
+      try run()
+    } catch {
+      fputs("recording-frames: \(error)\n", stderr)
+      exit(1)
+    }
+  }
+}
+
+func run() throws {
+  let arguments = Array(CommandLine.arguments.dropFirst())
+  let inputURL = URL(fileURLWithPath: try requiredOption(arguments, "--input"))
+  let outputDirectoryURL = URL(fileURLWithPath: try requiredOption(arguments, "--output-dir"), isDirectory: true)
+  let requestedTimesMs = try parseTimes(try requiredOption(arguments, "--times"))
+  let maxWidth = try parseMaxWidth(optionValue(arguments, "--max-width"))
+
+  guard !requestedTimesMs.isEmpty else {
+    throw RecordingScriptError.invalidArgs("--times must name at least one presentation time")
+  }
+  try FileManager.default.createDirectory(at: outputDirectoryURL, withIntermediateDirectories: true)
+
+  let asset = AVURLAsset(url: inputURL)
+  _ = try sourceVideoTrack(of: asset)
+  let durationMs = max(0, asset.duration.seconds * 1000)
+
+  let generator = AVAssetImageGenerator(asset: asset)
+  generator.appliesPreferredTrackTransform = true
+  generator.maximumSize = CGSize(width: maxWidth, height: maxWidth)
+  generator.requestedTimeToleranceBefore = .zero
+  generator.requestedTimeToleranceAfter = .zero
+
+  var frames: [FrameManifest.Frame] = []
+  var skipped: [FrameManifest.Skipped] = []
+
+  for (index, requestedTimeMs) in requestedTimesMs.enumerated() {
+    let requestedTime = CMTime(seconds: requestedTimeMs / 1000, preferredTimescale: 600)
+    var actualTime = CMTime.invalid
+    let cgImage: CGImage
+    do {
+      cgImage = try generator.copyCGImage(at: requestedTime, actualTime: &actualTime)
+    } catch {
+      skipped.append(
+        FrameManifest.Skipped(
+          index: index,
+          requestedTimeMs: requestedTimeMs,
+          reason: "\(error)"
+        )
+      )
+      continue
+    }
+
+    // A frame the decoder cannot place on the timeline is not a frame at 0 ms. Writing it would
+    // label a mid-clip moment as the opening one, so the sample goes unanswered instead and the
+    // manifest says so.
+    guard CMTIME_IS_VALID(actualTime), actualTime.timescale != 0 else {
+      skipped.append(
+        FrameManifest.Skipped(
+          index: index,
+          requestedTimeMs: requestedTimeMs,
+          reason: "Decoder returned no presentation time for this frame"
+        )
+      )
+      continue
+    }
+
+    let outputURL = outputDirectoryURL.appendingPathComponent(frameFileName(index: index))
+    do {
+      try writePNG(cgImage: cgImage, to: outputURL)
+    } catch {
+      // A frame the decoder produced but storage refused is a failed run, not a moment the
+      // recording has nothing to show: reporting it as skipped would let a partial sheet claim
+      // to cover the clip.
+      try? FileManager.default.removeItem(at: outputURL)
+      throw RecordingScriptError.frameWriteFailed(
+        "Could not write frame \(index) at \(requestedTimeMs)ms to \(outputURL.path): \(error)"
+      )
+    }
+
+    frames.append(
+      FrameManifest.Frame(
+        index: index,
+        requestedTimeMs: requestedTimeMs,
+        actualTimeMs: timeIntervalMs(actualTime),
+        width: cgImage.width,
+        height: cgImage.height,
+        path: outputURL.path
+      )
+    )
+  }
+
+  let manifest = FrameManifest(
+    inputPath: inputURL.path,
+    durationMs: durationMs,
+    frames: frames,
+    skipped: skipped
+  )
+  let encoder = JSONEncoder()
+  encoder.outputFormatting = [.sortedKeys]
+  FileHandle.standardOutput.write(try encoder.encode(manifest))
+}
+
+func requiredOption(_ arguments: [String], _ flag: String) throws -> String {
+  guard let index = arguments.firstIndex(of: flag) else {
+    throw RecordingScriptError.invalidArgs("Missing \(flag)")
+  }
+  return try recordingOptionValue(arguments, index + 1, flag)
+}
+
+func optionValue(_ arguments: [String], _ flag: String) -> String? {
+  guard let index = arguments.firstIndex(of: flag), index + 1 < arguments.count else {
+    return nil
+  }
+  return arguments[index + 1]
+}
+
+func parseTimes(_ value: String) throws -> [Double] {
+  let parts = value.split(separator: ",", omittingEmptySubsequences: true)
+  guard !parts.isEmpty else {
+    throw RecordingScriptError.invalidArgs("--times must be a comma-separated list of milliseconds")
+  }
+  return try parts.map { part in
+    guard let parsed = Double(part), parsed.isFinite, parsed >= 0 else {
+      throw RecordingScriptError.invalidArgs("Invalid sample time: \(part)")
+    }
+    return parsed
+  }
+}
+
+func parseMaxWidth(_ value: String?) throws -> Int {
+  guard let value else { return 360 }
+  guard let parsed = Int(value), parsed > 0 else {
+    throw RecordingScriptError.invalidArgs("Invalid --max-width: \(value)")
+  }
+  return parsed
+}
+
+func timeIntervalMs(_ time: CMTime) -> Double {
+  guard CMTIME_IS_VALID(time), time.timescale != 0 else { return 0 }
+  return CMTimeGetSeconds(time) * 1000
+}
+
+func frameFileName(index: Int) -> String {
+  String(format: "frame-%04d.png", index)
+}
+
+func writePNG(cgImage: CGImage, to url: URL) throws {
+  guard let destination = CGImageDestinationCreateWithURL(
+    url as CFURL,
+    UTType.png.identifier as CFString,
+    1,
+    nil
+  ) else {
+    throw RecordingScriptError.exportFailed("Failed to open PNG destination for \(url.lastPathComponent)")
+  }
+  CGImageDestinationAddImage(destination, cgImage, nil)
+  guard CGImageDestinationFinalize(destination) else {
+    throw RecordingScriptError.exportFailed("Failed to encode PNG for \(url.lastPathComponent)")
+  }
+}
diff --git a/packages/capture-kit/src/png-pixels.fixtures.ts b/packages/capture-kit/src/png-pixels.fixtures.ts
new file mode 100644
index 0000000000..5e8807d5bc
--- /dev/null
+++ b/packages/capture-kit/src/png-pixels.fixtures.ts
@@ -0,0 +1,21 @@
+import { PNG } from './png.ts';
+
+/**
+ * Decoded-frame builders for tests that reason about pixels: a solid fill is enough to name what a
+ * test claims a frame contains without shipping a PNG fixture through the repo.
+ */
+
+export type Rgba = readonly [number, number, number, number];
+
+export const BLACK: Rgba = [0, 0, 0, 255];
+
+export function solidPng(width: number, height: number, color: Rgba = BLACK): PNG {
+  const png = new PNG({ width, height });
+  for (let offset = 0; offset < png.data.length; offset += 4) {
+    png.data[offset] = color[0];
+    png.data[offset + 1] = color[1];
+    png.data[offset + 2] = color[2];
+    png.data[offset + 3] = color[3];
+  }
+  return png;
+}
diff --git a/packages/capture-kit/src/recording/__tests__/recording-scripts.test.ts b/packages/capture-kit/src/recording/__tests__/recording-scripts.test.ts
index b7620408f7..466627d398 100644
--- a/packages/capture-kit/src/recording/__tests__/recording-scripts.test.ts
+++ b/packages/capture-kit/src/recording/__tests__/recording-scripts.test.ts
@@ -3,6 +3,9 @@ import assert from 'node:assert/strict';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { runCmd } from '@agent-device/host-kit/command';
+import { AppError } from '@agent-device/kernel/errors';
+import { CONTACT_SHEET_UNSUPPORTED_HOST_REASON } from '../contact-sheet-report.ts';
+import { assertContactSheetHostSupport } from '../contact-sheet-frames.ts';
 import { getRecordingOverlaySupportWarning } from '../overlay.ts';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -71,6 +74,20 @@ test(
   SWIFT_TYPECHECK_TIMEOUT_MS,
 );
 
+test(
+  'recording frames Swift script typechecks',
+  async (t) => {
+    if (process.platform !== 'darwin') {
+      t.skip('Swift recording scripts are only validated on macOS');
+    }
+
+    await assertSwiftScriptTypechecks(path.join(recordingScriptsDir, 'recording-frames.swift'), [
+      path.join(recordingScriptsDir, 'RecordingExportSupport.swift'),
+    ]);
+  },
+  SWIFT_TYPECHECK_TIMEOUT_MS,
+);
+
 test('recording overlays are explicitly unsupported on non-macOS hosts', () => {
   assert.equal(
     getRecordingOverlaySupportWarning('linux'),
@@ -78,3 +95,17 @@ test('recording overlays are explicitly unsupported on non-macOS hosts', () => {
   );
   assert.equal(getRecordingOverlaySupportWarning('darwin'), undefined);
 });
+
+test('contact sheets are explicitly unsupported on non-macOS hosts', () => {
+  assert.throws(
+    () => assertContactSheetHostSupport('linux'),
+    (error: unknown) => {
+      return (
+        error instanceof AppError &&
+        error.code === 'UNSUPPORTED_OPERATION' &&
+        error.details?.reason === CONTACT_SHEET_UNSUPPORTED_HOST_REASON
+      );
+    },
+  );
+  assert.doesNotThrow(() => assertContactSheetHostSupport('darwin'));
+});
diff --git a/packages/capture-kit/src/recording/contact-sheet-frames.test.ts b/packages/capture-kit/src/recording/contact-sheet-frames.test.ts
new file mode 100644
index 0000000000..b8266c16ab
--- /dev/null
+++ b/packages/capture-kit/src/recording/contact-sheet-frames.test.ts
@@ -0,0 +1,363 @@
+import { beforeEach, describe, expect, test, vi } from 'vitest';
+import path from 'node:path';
+import {
+  CONTACT_SHEET_EXTRACTION_REASON,
+  CONTACT_SHEET_NO_FRAMES_REASON,
+  CONTACT_SHEET_UNSUPPORTED_HOST_REASON,
+} from './contact-sheet-report.ts';
+import { AppError, isRequestCanceledError } from '@agent-device/kernel/errors';
+import { mkdtempForTestSync } from '../tmp-dir.fixtures.ts';
+import { solidPng } from '../png-pixels.fixtures.ts';
+import { writeDecodedFrames, type StubFrame } from './contact-sheet.fixtures.ts';
+import { extractRecordingFrames } from './contact-sheet-frames.ts';
+
+vi.mock(import('@agent-device/host-kit/command'), async (importOriginal) => ({
+  ...(await importOriginal()),
+  runCmd: vi.fn(),
+}));
+
+vi.mock(import('./swift-cache.ts'), async (importOriginal) => ({
+  ...(await importOriginal<typeof import('./swift-cache.ts')>()),
+  compileSwiftSourceFile: vi.fn(async () => '/cached/bin/recording-frames'),
+}));
+
+import { runCmd } from '@agent-device/host-kit/command';
+
+const mockRunCmd = vi.mocked(runCmd);
+const scratchDir = mkdtempForTestSync('agent-device-contact-sheet-frames-');
+const CELL_WIDTH = 360;
+const VIDEO = '/tmp/recording.mp4';
+
+function reasonOf(action: () => Promise<unknown>): Promise<unknown> | unknown {
+  return action().then(
+    () => 'no error thrown',
+    (error: unknown) => (error instanceof AppError ? error.details?.reason : error),
+  );
+}
+
+/** Decoding is Apple tooling, so every case here states the host it is pretending to be. */
+function extract(
+  input: Omit<Parameters<typeof extractRecordingFrames>[0], 'hostPlatform'>,
+): Promise<Awaited<ReturnType<typeof extractRecordingFrames>>> {
+  return extractRecordingFrames({ ...input, hostPlatform: 'darwin' });
+}
+
+function withTimes(args: readonly string[], times: string): string[] {
+  const rewritten = [...args];
+  rewritten[rewritten.indexOf('--times') + 1] = times;
+  return rewritten;
+}
+
+function answerWith(framesByRequestedTimeMs: ReadonlyMap<number, StubFrame>) {
+  mockRunCmd.mockImplementation(async (_cmd, args) =>
+    writeDecodedFrames({ args: args as string[], framesByRequestedTimeMs }),
+  );
+}
+
+describe('extractRecordingFrames', () => {
+  beforeEach(() => {
+    mockRunCmd.mockReset();
+  });
+
+  test('refuses to decode at all on a host with no frame decoder', async () => {
+    expect(
+      await reasonOf(() =>
+        extractRecordingFrames({
+          videoPath: VIDEO,
+          scratchDir,
+          maxWidth: CELL_WIDTH,
+          timesMs: [0],
+          hostPlatform: 'linux',
+        }),
+      ),
+    ).toBe(CONTACT_SHEET_UNSUPPORTED_HOST_REASON);
+    // Refused before the compiler or the decoder ran, so a Linux host never pays for a spawn.
+    expect(mockRunCmd).not.toHaveBeenCalled();
+  });
+
+  test('asks the helper for exactly the grid it was given', async () => {
+    answerWith(
+      new Map([
+        [0, { png: solidPng(4, 4), actualTimeMs: 0 }],
+        [250, { png: solidPng(4, 4), actualTimeMs: 250 }],
+      ]),
+    );
+
+    await extract({
+      videoPath: VIDEO,
+      scratchDir,
+      maxWidth: CELL_WIDTH,
+      timesMs: [0, 250],
+    });
+
+    const [, args] = mockRunCmd.mock.calls[0]!;
+    expect(args).toEqual([
+      '--input',
+      VIDEO,
+      '--output-dir',
+      scratchDir,
+      '--times',
+      '0,250',
+      '--max-width',
+      '360',
+    ]);
+  });
+
+  test('reports the times the decoder actually returned', async () => {
+    answerWith(
+      new Map([
+        // A decoder answers a request with the frame it holds, and out of request order is legal:
+        // the sheet must still read left to right in time.
+        [0, { png: solidPng(4, 4), actualTimeMs: 500 }],
+        [250, { png: solidPng(4, 4), actualTimeMs: 0 }],
+        [500, { png: solidPng(4, 4), actualTimeMs: 250 }],
+      ]),
+    );
+
+    const extracted = await extract({
+      videoPath: VIDEO,
+      scratchDir,
+      maxWidth: CELL_WIDTH,
+      timesMs: [0, 250, 500],
+    });
+
+    expect(extracted.frames.map((frame) => frame.actualTimeMs)).toEqual([0, 250, 500]);
+    expect(extracted.frames.map((frame) => frame.requestedTimeMs)).toEqual([250, 500, 0]);
+    expect(extracted.skippedSampleCount).toBe(0);
+  });
+
+  test('counts the sample times the decoder declined', async () => {
+    answerWith(new Map([[0, { png: solidPng(4, 4), actualTimeMs: 0 }]]));
+
+    const extracted = await extract({
+      videoPath: VIDEO,
+      scratchDir,
+      maxWidth: CELL_WIDTH,
+      timesMs: [0, 250, 500],
+    });
+
+    expect(extracted.frames).toHaveLength(1);
+    expect(extracted.skippedSampleCount).toBe(2);
+  });
+
+  test('drops a frame the manifest names but the helper never wrote', async () => {
+    const written = new Map<number, StubFrame>([
+      [0, { png: solidPng(4, 4), actualTimeMs: 0 }],
+      [250, { png: solidPng(4, 4), actualTimeMs: 250 }],
+    ]);
+    mockRunCmd.mockImplementation(async (_cmd, args) => {
+      const result = writeDecodedFrames({
+        args: args as string[],
+        framesByRequestedTimeMs: written,
+      });
+      const manifest = JSON.parse(result.stdout) as { frames: { path: string }[] };
+      manifest.frames[0]!.path = path.join(scratchDir, 'frame-9999.png');
+      return { ...result, stdout: JSON.stringify(manifest) };
+    });
+
+    const extracted = await extract({
+      videoPath: VIDEO,
+      scratchDir,
+      maxWidth: CELL_WIDTH,
+      timesMs: [0, 250],
+    });
+
+    expect(extracted.frames.map((frame) => frame.actualTimeMs)).toEqual([250]);
+    // A frame the manifest promised and never delivered shrinks coverage, and the sheet has to say
+    // so rather than let one fewer cell look like a quieter recording.
+    expect(extracted.skippedSampleCount).toBe(1);
+  });
+
+  test('refuses a manifest that answers more samples than were asked for', async () => {
+    const answers = new Map<number, StubFrame>([
+      [0, { png: solidPng(4, 4), actualTimeMs: 0 }],
+      [250, { png: solidPng(4, 4), actualTimeMs: 250 }],
+    ]);
+    mockRunCmd.mockImplementation(async (_cmd, args) =>
+      writeDecodedFrames({
+        // The decoder was asked for one sample and hands back two: whatever those bytes are, they
+        // are not the grid this command budgeted to decode.
+        args: withTimes(args as string[], '0,250'),
+        framesByRequestedTimeMs: answers,
+      }),
+    );
+
+    expect(
+      await reasonOf(() =>
+        extract({
+          videoPath: VIDEO,
+          scratchDir,
+          maxWidth: CELL_WIDTH,
+          timesMs: [0],
+        }),
+      ),
+    ).toBe(CONTACT_SHEET_EXTRACTION_REASON);
+  });
+
+  test('refuses a frame entry that cannot say which frame it is', async () => {
+    mockRunCmd.mockResolvedValue({
+      stdout: JSON.stringify({
+        frames: [{ index: 0, path: 'frame-0.png', width: 4, height: 4 }],
+        skipped: [],
+      }),
+      stderr: '',
+      exitCode: 0,
+    });
+
+    expect(
+      await reasonOf(() =>
+        extract({
+          videoPath: VIDEO,
+          scratchDir,
+          maxWidth: CELL_WIDTH,
+          timesMs: [0],
+        }),
+      ),
+    ).toBe(CONTACT_SHEET_EXTRACTION_REASON);
+  });
+
+  test('counts samples the manifest neither answered nor declared skipped', async () => {
+    answerWith(new Map([[0, { png: solidPng(4, 4), actualTimeMs: 0 }]]));
+
+    const extracted = await extract({
+      videoPath: VIDEO,
+      scratchDir,
+      maxWidth: CELL_WIDTH,
+      timesMs: [0, 250, 500],
+    });
+
+    // A decoder that stays silent about the two samples it dropped still covered one of three, and
+    // a sheet may not report that as full coverage.
+    expect(extracted.frames).toHaveLength(1);
+    expect(extracted.skippedSampleCount).toBe(2);
+  });
+
+  test('keeps the extraction reason when the decoder cannot be built', async () => {
+    const { compileSwiftSourceFile } = await import('./swift-cache.ts');
+    vi.mocked(compileSwiftSourceFile).mockRejectedValueOnce(new Error('swiftc died'));
+
+    expect(
+      await reasonOf(() =>
+        extract({
+          videoPath: VIDEO,
+          scratchDir,
+          maxWidth: CELL_WIDTH,
+          timesMs: [0],
+        }),
+      ),
+    ).toBe(CONTACT_SHEET_EXTRACTION_REASON);
+  });
+
+  test('keeps the extraction reason when the decoder never started', async () => {
+    mockRunCmd.mockRejectedValue(new Error('spawn /cached/bin/recording-frames ENOENT'));
+
+    expect(
+      await reasonOf(() =>
+        extract({
+          videoPath: VIDEO,
+          scratchDir,
+          maxWidth: CELL_WIDTH,
+          timesMs: [0],
+        }),
+      ),
+    ).toBe(CONTACT_SHEET_EXTRACTION_REASON);
+  });
+
+  test('hands the decoder the cancellation of the request it serves', async () => {
+    answerWith(new Map([[0, { png: solidPng(4, 4), actualTimeMs: 0 }]]));
+    const controller = new AbortController();
+
+    await extract({
+      videoPath: VIDEO,
+      scratchDir,
+      maxWidth: CELL_WIDTH,
+      timesMs: [0],
+      signal: controller.signal,
+    });
+
+    expect(mockRunCmd.mock.calls[0]![2]).toMatchObject({
+      allowFailure: true,
+      signal: controller.signal,
+    });
+  });
+
+  test('answers a cancelled request as a cancellation, not an extraction failure', async () => {
+    const controller = new AbortController();
+    controller.abort();
+
+    const error = await extract({
+      videoPath: VIDEO,
+      scratchDir,
+      maxWidth: CELL_WIDTH,
+      timesMs: [0],
+      signal: controller.signal,
+    }).catch((error: unknown) => error);
+
+    expect(isRequestCanceledError(error)).toBe(true);
+    expect(mockRunCmd).not.toHaveBeenCalled();
+  });
+
+  test('reports a failed extraction run rather than an empty sheet', async () => {
+    answerWith(new Map());
+    mockRunCmd.mockImplementation(async (_cmd, args) =>
+      writeDecodedFrames({
+        args: args as string[],
+        framesByRequestedTimeMs: new Map(),
+        failWithExitCode: 1,
+      }),
+    );
+
+    await expect(
+      extract({ videoPath: VIDEO, scratchDir, maxWidth: CELL_WIDTH, timesMs: [0] }),
+    ).rejects.toThrow(/could not open asset/);
+    expect(
+      await reasonOf(() =>
+        extract({
+          videoPath: VIDEO,
+          scratchDir,
+          maxWidth: CELL_WIDTH,
+          timesMs: [0],
+        }),
+      ),
+    ).toBe(CONTACT_SHEET_EXTRACTION_REASON);
+  });
+
+  test('reports an unreadable manifest as an extraction failure', async () => {
+    mockRunCmd.mockResolvedValue({ stdout: 'not json', stderr: '', exitCode: 0 });
+
+    expect(
+      await reasonOf(() =>
+        extract({
+          videoPath: VIDEO,
+          scratchDir,
+          maxWidth: CELL_WIDTH,
+          timesMs: [0],
+        }),
+      ),
+    ).toBe(CONTACT_SHEET_EXTRACTION_REASON);
+  });
+
+  test('reports a clip that returned nothing usable', async () => {
+    answerWith(new Map());
+
+    expect(
+      await reasonOf(() =>
+        extract({
+          videoPath: VIDEO,
+          scratchDir,
+          maxWidth: CELL_WIDTH,
+          timesMs: [0],
+        }),
+      ),
+    ).toBe(CONTACT_SHEET_NO_FRAMES_REASON);
+  });
+
+  test('refuses to spawn a decoder for an empty grid', async () => {
+    expect(
+      await reasonOf(() =>
+        extract({ videoPath: VIDEO, scratchDir, maxWidth: CELL_WIDTH, timesMs: [] }),
+      ),
+    ).toBe(CONTACT_SHEET_NO_FRAMES_REASON);
+    expect(mockRunCmd).not.toHaveBeenCalled();
+  });
+});
diff --git a/packages/capture-kit/src/recording/contact-sheet-frames.ts b/packages/capture-kit/src/recording/contact-sheet-frames.ts
new file mode 100644
index 0000000000..fd6f92de77
--- /dev/null
+++ b/packages/capture-kit/src/recording/contact-sheet-frames.ts
@@ -0,0 +1,278 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  CONTACT_SHEET_EXTRACTION_REASON,
+  CONTACT_SHEET_NO_FRAMES_REASON,
+  CONTACT_SHEET_UNSUPPORTED_HOST_REASON,
+} from './contact-sheet-report.ts';
+import {
+  AppError,
+  createRequestCanceledError,
+  errorMessage,
+  isRequestCanceledError,
+} from '@agent-device/kernel/errors';
+import { runCmd } from '@agent-device/host-kit/command';
+import { findProjectRoot } from '@agent-device/host-kit/version';
+import {
+  buildSwiftToolEnv,
+  compileSwiftSourceFile,
+  resolveRecordingScriptPath,
+} from './swift-cache.ts';
+
+const FRAMES_SCRIPT = 'recording-frames.swift';
+const SHARED_SUPPORT_SCRIPT = 'RecordingExportSupport.swift';
+const EXTRACTION_TIMEOUT_MS = 90_000;
+const COMPILATION_TIMEOUT_MS = 120_000;
+
+/**
+ * Frame decoding is Apple AVFoundation tooling, so a non-macOS host cannot decode a single frame at
+ * all. A caller that derives something from a sheet as a convenience catches this and keeps what it
+ * has; a caller that was asked for frames reports it.
+ */
+export function assertContactSheetHostSupport(
+  hostPlatform: NodeJS.Platform = process.platform,
+): void {
+  if (hostPlatform === 'darwin') return;
+  throw new AppError(
+    'UNSUPPORTED_OPERATION',
+    'Contact sheets can only be built on macOS hosts, which is where the frame decoder runs',
+    {
+      reason: CONTACT_SHEET_UNSUPPORTED_HOST_REASON,
+      hostPlatform,
+      hint: 'Run this command on the macOS host that recorded the clip, or read the video artifact itself.',
+    },
+  );
+}
+
+export type ExtractedRecordingFrame = Readonly<{
+  /** The time that was asked for, in milliseconds from the clip start. */
+  requestedTimeMs: number;
+  /** The time the decoder says the returned frame carries. */
+  actualTimeMs: number;
+  path: string;
+}>;
+
+export type ExtractedRecordingFrames = Readonly<{
+  frames: readonly ExtractedRecordingFrame[];
+  /** Requested sample times the decoder declined to answer. */
+  skippedSampleCount: number;
+}>;
+
+/**
+ * Decodes the frames at `timesMs` out of a recording into `scratchDir`, which the caller owns.
+ *
+ * Decoding is Apple AVFoundation tooling compiled through the same cached Swift seam the touch
+ * overlay burn-in uses, so a sheet costs one cached compile and one bounded decode pass rather than
+ * a new runtime dependency.
+ */
+export async function extractRecordingFrames(
+  input: Readonly<{
+    videoPath: string;
+    scratchDir: string;
+    timesMs: readonly number[];
+    /** Widest cell the caller will draw, so no frame is decoded wider than it can be shown. */
+    maxWidth: number;
+    hostPlatform?: NodeJS.Platform;
+    signal?: AbortSignal;
+  }>,
+): Promise<ExtractedRecordingFrames> {
+  // Decoding is the Apple tooling, so the host question has to be answered before this module
+  // spawns anything; a caller that only asks for frames gets the same reason as one that asked
+  // for a sheet.
+  assertContactSheetHostSupport(input.hostPlatform ?? process.platform);
+  if (input.timesMs.length === 0) {
+    throw new AppError('COMMAND_FAILED', 'Contact sheet sampling requested no frames', {
+      reason: CONTACT_SHEET_NO_FRAMES_REASON,
+      videoPath: input.videoPath,
+    });
+  }
+  throwIfAborted(input.signal);
+
+  const executablePath = await compileDecoder(input);
+  throwIfAborted(input.signal);
+
+  let result;
+  try {
+    result = await runCmd(
+      executablePath,
+      [
+        '--input',
+        input.videoPath,
+        '--output-dir',
+        input.scratchDir,
+        '--times',
+        input.timesMs.join(','),
+        '--max-width',
+        String(input.maxWidth),
+      ],
+      {
+        timeoutMs: EXTRACTION_TIMEOUT_MS,
+        env: buildSwiftToolEnv(),
+        allowFailure: true,
+        ...(input.signal === undefined ? {} : { signal: input.signal }),
+      },
+    );
+  } catch (error) {
+    throwExtractionFailure(error, input.videoPath, 'Failed to run the frame decoder');
+  }
+  if (result.exitCode !== 0) {
+    throw new AppError(
+      'COMMAND_FAILED',
+      `Failed to extract frames from the recording: ${lastNonEmptyLine(result.stderr) || `exit ${result.exitCode}`}`,
+      {
+        reason: CONTACT_SHEET_EXTRACTION_REASON,
+        videoPath: input.videoPath,
+        exitCode: result.exitCode,
+      },
+    );
+  }
+
+  const extracted = parseExtractionManifest(
+    result.stdout,
+    input.videoPath,
+    input.scratchDir,
+    input.timesMs.length,
+  );
+  if (extracted.frames.length === 0) {
+    throw new AppError(
+      'COMMAND_FAILED',
+      'The recording returned no decodable frames for a contact sheet',
+      {
+        reason: CONTACT_SHEET_NO_FRAMES_REASON,
+        videoPath: input.videoPath,
+        skippedSampleCount: extracted.skippedSampleCount,
+      },
+    );
+  }
+  return extracted;
+}
+
+type FrameManifest = Readonly<{
+  frames: readonly ExtractedRecordingFrame[];
+  skippedSampleCount: number;
+}>;
+
+function parseExtractionManifest(
+  stdout: string,
+  videoPath: string,
+  scratchDir: string,
+  requestedSampleCount: number,
+): FrameManifest {
+  let decoded: unknown;
+  try {
+    decoded = JSON.parse(stdout);
+  } catch (error) {
+    throw extractionUnreadable(videoPath, `invalid manifest: ${String(error)}`);
+  }
+
+  const frames = readRecord(decoded).frames;
+  if (!Array.isArray(frames)) {
+    throw extractionUnreadable(videoPath, 'manifest has no frames array');
+  }
+  const skipped = readRecord(decoded).skipped;
+
+  if (frames.length > requestedSampleCount) {
+    throw extractionUnreadable(
+      videoPath,
+      `returned ${frames.length} frames for ${requestedSampleCount} requested samples`,
+    );
+  }
+
+  const readable = frames.flatMap((entry) => {
+    const frame = readRecord(entry);
+    const name = stringField(frame.path);
+    const actualTimeMs = numberField(frame.actualTimeMs);
+    if (name === undefined || actualTimeMs === undefined || actualTimeMs < 0) {
+      // An entry that cannot say which frame it is cannot be shown or counted; the manifest itself
+      // is broken, which is a different claim from a sample time the decoder declined.
+      throw extractionUnreadable(videoPath, `frame entry is missing a path or presentation time`);
+    }
+    const framePath = path.resolve(scratchDir, path.basename(name));
+    // Bytes that never arrived leave the sample unanswered, which the coverage shortfall below
+    // counts; a manifest that promised a frame and delivered nothing cannot be shown as a cell.
+    if (!fs.existsSync(framePath)) return [];
+    return [
+      {
+        requestedTimeMs: numberField(frame.requestedTimeMs) ?? actualTimeMs,
+        actualTimeMs,
+        path: framePath,
+      },
+    ];
+  });
+
+  return {
+    // A decoder asked out of order answers out of order; the sheet reads left to right in time.
+    frames: readable.sort((left, right) => left.actualTimeMs - right.actualTimeMs),
+    // Coverage is what was asked for minus what arrived. Counting the shortfall rather than
+    // trusting the manifest's own skipped list keeps a decoder that answers nothing silently
+    // impossible: the sheet has to say it saw less than it asked for.
+    skippedSampleCount: Math.max(
+      Array.isArray(skipped) ? skipped.length : 0,
+      requestedSampleCount - readable.length,
+    ),
+  };
+}
+
+function extractionError(message: string, videoPath: string, cause?: unknown): AppError {
+  return new AppError(
+    'COMMAND_FAILED',
+    message,
+    { reason: CONTACT_SHEET_EXTRACTION_REASON, videoPath },
+    cause,
+  );
+}
+
+function extractionUnreadable(videoPath: string, detail: string): AppError {
+  return extractionError(`Frame extraction returned an unreadable manifest: ${detail}`, videoPath);
+}
+
+/**
+ * A helper that could not start, was killed at its deadline, or never compiled is an extraction
+ * failure too; letting a raw process error escape would strand it outside the typed taxonomy. A
+ * canceled request and a failure that already names its reason are both answers the caller asked
+ * for, so they travel unchanged.
+ */
+function throwExtractionFailure(error: unknown, videoPath: string, stage: string): never {
+  if (isRequestCanceledError(error)) throw error;
+  if (error instanceof AppError && error.code === 'COMMAND_FAILED' && error.details?.reason) {
+    throw error;
+  }
+  throw extractionError(`${stage} for ${videoPath}: ${errorMessage(error)}`, videoPath, error);
+}
+
+function readRecord(value: unknown): Record<string, unknown> {
+  return typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : {};
+}
+
+function stringField(value: unknown): string | undefined {
+  return typeof value === 'string' && value !== '' ? value : undefined;
+}
+
+function numberField(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+function lastNonEmptyLine(text: string): string {
+  return (text.trim().split('\n').pop() ?? '').trim();
+}
+
+/**
+ * Compiles the decoder helper, or fails as an extraction failure: a cold Swift cache that cannot
+ * build the helper is exactly as unable to produce a sheet as a helper that exits nonzero.
+ */
+async function compileDecoder(input: { videoPath: string; signal?: AbortSignal }): Promise<string> {
+  try {
+    return await compileSwiftSourceFile({
+      sourcePath: resolveRecordingScriptPath(FRAMES_SCRIPT, findProjectRoot()),
+      extraSourcePaths: [resolveRecordingScriptPath(SHARED_SUPPORT_SCRIPT, findProjectRoot())],
+      cacheName: 'recording-frames',
+      timeoutMs: COMPILATION_TIMEOUT_MS,
+    });
+  } catch (error) {
+    throwExtractionFailure(error, input.videoPath, 'Could not build the frame decoder');
+  }
+}
+
+function throwIfAborted(signal: AbortSignal | undefined): void {
+  if (signal?.aborted) throw createRequestCanceledError();
+}
diff --git a/packages/capture-kit/src/recording/contact-sheet-report.ts b/packages/capture-kit/src/recording/contact-sheet-report.ts
new file mode 100644
index 0000000000..d0e5b6952c
--- /dev/null
+++ b/packages/capture-kit/src/recording/contact-sheet-report.ts
@@ -0,0 +1,11 @@
+/**
+ * Why a contact sheet was not drawn. Each reason is a typed constant the extraction path fails with,
+ * so a caller branches on the reason instead of reading an error message.
+ */
+
+/** The host cannot extract frames at all: frame decoding is Apple AVFoundation tooling. */
+export const CONTACT_SHEET_UNSUPPORTED_HOST_REASON = 'contact_sheet_unsupported_host';
+/** Frame extraction ran and failed, rather than returning fewer frames. */
+export const CONTACT_SHEET_EXTRACTION_REASON = 'contact_sheet_frame_extraction_failed';
+/** Extraction returned nothing usable, so there is no sheet to draw. */
+export const CONTACT_SHEET_NO_FRAMES_REASON = 'contact_sheet_no_frames';
diff --git a/packages/capture-kit/src/recording/contact-sheet.fixtures.ts b/packages/capture-kit/src/recording/contact-sheet.fixtures.ts
new file mode 100644
index 0000000000..e808b01b66
--- /dev/null
+++ b/packages/capture-kit/src/recording/contact-sheet.fixtures.ts
@@ -0,0 +1,94 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { encodePngPixels } from '../png-encode.ts';
+import type { PNG } from '../png.ts';
+
+/**
+ * The frame helper's side of a conversation, replayed against a scratch directory. Frames are
+ * written as the PNG bytes a real decoder hands back, so the pipeline decodes them the same way it
+ * decodes a simulator's recording.
+ */
+
+/** A frame the fake decoder answers with: the pixels plus the time it claims to carry. */
+export type StubFrame = Readonly<{ png: PNG; actualTimeMs: number }>;
+
+export type StubDecoderResult = Readonly<{
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}>;
+
+/**
+ * Answers the frame helper's argv by writing PNG files where it was told to write them and
+ * returning the manifest the real helper prints. A requested time with no stub frame is reported
+ * as skipped, exactly as a decoder that declines a request is.
+ */
+export function writeDecodedFrames(
+  input: Readonly<{
+    args: readonly string[];
+    framesByRequestedTimeMs: ReadonlyMap<number, StubFrame>;
+    failWithExitCode?: number;
+    manifest?: string;
+  }>,
+): StubDecoderResult {
+  if (input.failWithExitCode !== undefined) {
+    return {
+      stdout: '',
+      stderr: 'recording-frames: could not open asset',
+      exitCode: input.failWithExitCode,
+    };
+  }
+  if (input.manifest !== undefined) {
+    return { stdout: input.manifest, stderr: '', exitCode: 0 };
+  }
+
+  const outputDir = requireOption(input.args, '--output-dir');
+  const requestedTimes = parseTimes(requireOption(input.args, '--times'));
+  const frames: unknown[] = [];
+  const skipped: unknown[] = [];
+
+  requestedTimes.forEach((requestedTimeMs, index) => {
+    const frame = input.framesByRequestedTimeMs.get(requestedTimeMs);
+    if (!frame) {
+      skipped.push({ index, requestedTimeMs, reason: 'no frame at time' });
+      return;
+    }
+    const filePath = path.join(outputDir, frameFileName(index));
+    fs.writeFileSync(
+      filePath,
+      encodePngPixels(frame.png.data, frame.png.width, frame.png.height, 4),
+    );
+    frames.push({
+      index,
+      requestedTimeMs,
+      actualTimeMs: frame.actualTimeMs,
+      width: frame.png.width,
+      height: frame.png.height,
+      path: filePath,
+    });
+  });
+
+  return {
+    stdout: JSON.stringify({ inputPath: 'fixture.mp4', durationMs: 0, frames, skipped }),
+    stderr: '',
+    exitCode: 0,
+  };
+}
+
+function frameFileName(index: number): string {
+  return `frame-${String(index).padStart(4, '0')}.png`;
+}
+
+function requireOption(args: readonly string[], flag: string): string {
+  const index = args.indexOf(flag);
+  const value = index === -1 ? undefined : args[index + 1];
+  if (!value) throw new Error(`fixture decoder was called without ${flag}`);
+  return value;
+}
+
+function parseTimes(value: string): number[] {
+  return value
+    .split(',')
+    .filter((part) => part !== '')
+    .map(Number);
+}

From 6e765b6b9adb8e51a1149774f6fc56bee49a0e9a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Tue, 22 Sep 2026 13:08:18 +0200
Subject: [PATCH 010/132] feat(recording): choose the frames a contact sheet
 shows (#2745)

---
 .../src/png-changed-pixel-ratio.test.ts       |  47 ++++++++
 .../src/png-changed-pixel-ratio.ts            |  47 ++++++++
 .../capture-kit/src/png-pixels.fixtures.ts    |  38 +++++--
 .../src/recording/contact-sheet-plan.test.ts  |  69 ++++++++++++
 .../src/recording/contact-sheet-plan.ts       |  60 ++++++++++
 .../src/recording/contact-sheet-report.ts     |   2 +
 .../recording/contact-sheet-selection.test.ts |  98 +++++++++++++++++
 .../src/recording/contact-sheet-selection.ts  | 103 ++++++++++++++++++
 8 files changed, 456 insertions(+), 8 deletions(-)
 create mode 100644 packages/capture-kit/src/png-changed-pixel-ratio.test.ts
 create mode 100644 packages/capture-kit/src/png-changed-pixel-ratio.ts
 create mode 100644 packages/capture-kit/src/recording/contact-sheet-plan.test.ts
 create mode 100644 packages/capture-kit/src/recording/contact-sheet-plan.ts
 create mode 100644 packages/capture-kit/src/recording/contact-sheet-selection.test.ts
 create mode 100644 packages/capture-kit/src/recording/contact-sheet-selection.ts

diff --git a/packages/capture-kit/src/png-changed-pixel-ratio.test.ts b/packages/capture-kit/src/png-changed-pixel-ratio.test.ts
new file mode 100644
index 0000000000..24eb9b979e
--- /dev/null
+++ b/packages/capture-kit/src/png-changed-pixel-ratio.test.ts
@@ -0,0 +1,47 @@
+import { describe, expect, test } from 'vitest';
+import { computePngChangedPixelRatio } from './png-changed-pixel-ratio.ts';
+import { BLACK, paintPng, solidPng, WHITE } from './png-pixels.fixtures.ts';
+
+function pixels(png: { width: number; height: number; data: Buffer }) {
+  return { width: png.width, height: png.height, data: png.data };
+}
+
+describe('computePngChangedPixelRatio', () => {
+  test('reports nothing moved for identical frames', () => {
+    expect(
+      computePngChangedPixelRatio(pixels(solidPng(4, 4, BLACK)), pixels(solidPng(4, 4, BLACK))),
+    ).toEqual({ status: 'compared', changedPixelRatio: 0 });
+  });
+
+  test('counts a pixel whose blue channel alone moved', () => {
+    const blue = paintPng(
+      solidPng(4, 4, BLACK),
+      { x: 0, y: 0, width: 1, height: 1 },
+      [0, 0, 9, 255],
+    );
+    expect(computePngChangedPixelRatio(pixels(solidPng(4, 4, BLACK)), pixels(blue))).toEqual({
+      status: 'compared',
+      changedPixelRatio: 1 / 16,
+    });
+  });
+
+  test('ignores alpha, which never reaches the recorded screen', () => {
+    const transparent = solidPng(4, 4, BLACK);
+    transparent.data[3] = 0;
+    expect(computePngChangedPixelRatio(pixels(solidPng(4, 4, BLACK)), pixels(transparent))).toEqual(
+      { status: 'compared', changedPixelRatio: 0 },
+    );
+  });
+
+  test('counts every pixel when the whole frame moved', () => {
+    expect(
+      computePngChangedPixelRatio(pixels(solidPng(4, 4, BLACK)), pixels(solidPng(4, 4, WHITE))),
+    ).toEqual({ status: 'compared', changedPixelRatio: 1 });
+  });
+
+  test('refuses a ratio across frames of different shapes', () => {
+    expect(
+      computePngChangedPixelRatio(pixels(solidPng(4, 4, BLACK)), pixels(solidPng(4, 8, BLACK))),
+    ).toEqual({ status: 'dimension_mismatch' });
+  });
+});
diff --git a/packages/capture-kit/src/png-changed-pixel-ratio.ts b/packages/capture-kit/src/png-changed-pixel-ratio.ts
new file mode 100644
index 0000000000..f7b0fa0ebd
--- /dev/null
+++ b/packages/capture-kit/src/png-changed-pixel-ratio.ts
@@ -0,0 +1,47 @@
+import type { PngRgbImage } from './png-rgb-difference.ts';
+
+export type { PngRgbImage };
+
+export type PngChangedPixelRatioResult =
+  | { readonly status: 'compared'; readonly changedPixelRatio: number }
+  | { readonly status: 'dimension_mismatch' };
+
+/**
+ * The share of pixels whose color moved at all between two decoded PNGs.
+ *
+ * A pixel counts as changed when any of its RGB channels differs, ignoring alpha, so a
+ * translucent-layer fade that leaves the composite untouched is not reported. This is a
+ * coverage metric, not a magnitude one: `computePngRgbDifference` answers how far the colors
+ * moved, and this answers how much of the frame moved. A recording that only shifts a 1 px
+ * progress line scores a ratio near zero either way.
+ *
+ * Dimensions must match. Callers comparing frames of different sizes are asking a different
+ * question, and returning a made-up ratio would hide it.
+ */
+export function computePngChangedPixelRatio(
+  first: PngRgbImage,
+  second: PngRgbImage,
+): PngChangedPixelRatioResult {
+  if (first.width !== second.width || first.height !== second.height) {
+    return { status: 'dimension_mismatch' };
+  }
+
+  const totalPixels = first.width * first.height;
+  if (totalPixels === 0) return { status: 'compared', changedPixelRatio: 0 };
+  if (first.data.length !== second.data.length) {
+    return { status: 'dimension_mismatch' };
+  }
+
+  let changedPixels = 0;
+  for (let offset = 0; offset + 3 < first.data.length; offset += 4) {
+    if (
+      first.data[offset] !== second.data[offset] ||
+      first.data[offset + 1] !== second.data[offset + 1] ||
+      first.data[offset + 2] !== second.data[offset + 2]
+    ) {
+      changedPixels += 1;
+    }
+  }
+
+  return { status: 'compared', changedPixelRatio: changedPixels / totalPixels };
+}
diff --git a/packages/capture-kit/src/png-pixels.fixtures.ts b/packages/capture-kit/src/png-pixels.fixtures.ts
index 5e8807d5bc..4833b55ad5 100644
--- a/packages/capture-kit/src/png-pixels.fixtures.ts
+++ b/packages/capture-kit/src/png-pixels.fixtures.ts
@@ -1,21 +1,43 @@
 import { PNG } from './png.ts';
 
 /**
- * Decoded-frame builders for tests that reason about pixels: a solid fill is enough to name what a
- * test claims a frame contains without shipping a PNG fixture through the repo.
+ * Decoded-frame builders for tests that reason about pixels: a solid fill and one painted rectangle
+ * name exactly what a test claims changed between two frames.
  */
 
 export type Rgba = readonly [number, number, number, number];
+export type Rectangle = Readonly<{ x: number; y: number; width: number; height: number }>;
 
 export const BLACK: Rgba = [0, 0, 0, 255];
+export const WHITE: Rgba = [255, 255, 255, 255];
+export const RED: Rgba = [255, 0, 0, 255];
 
 export function solidPng(width: number, height: number, color: Rgba = BLACK): PNG {
-  const png = new PNG({ width, height });
-  for (let offset = 0; offset < png.data.length; offset += 4) {
-    png.data[offset] = color[0];
-    png.data[offset + 1] = color[1];
-    png.data[offset + 2] = color[2];
-    png.data[offset + 3] = color[3];
+  return fillPng(new PNG({ width, height }), () => true, color);
+}
+
+/** Paints one rectangle of `color` onto a copy of `source`, leaving the source untouched. */
+export function paintPng(source: PNG, rectangle: Rectangle, color: Rgba): PNG {
+  const copy = solidPng(source.width, source.height);
+  source.data.copy(copy.data);
+  const inside = (column: number, row: number) =>
+    column >= rectangle.x &&
+    column < rectangle.x + rectangle.width &&
+    row >= rectangle.y &&
+    row < rectangle.y + rectangle.height;
+  return fillPng(copy, inside, color);
+}
+
+function fillPng(png: PNG, paint: (column: number, row: number) => boolean, color: Rgba): PNG {
+  for (let row = 0; row < png.height; row += 1) {
+    for (let column = 0; column < png.width; column += 1) {
+      if (!paint(column, row)) continue;
+      const offset = (row * png.width + column) * 4;
+      png.data[offset] = color[0];
+      png.data[offset + 1] = color[1];
+      png.data[offset + 2] = color[2];
+      png.data[offset + 3] = color[3];
+    }
   }
   return png;
 }
diff --git a/packages/capture-kit/src/recording/contact-sheet-plan.test.ts b/packages/capture-kit/src/recording/contact-sheet-plan.test.ts
new file mode 100644
index 0000000000..c3c0ed5bc9
--- /dev/null
+++ b/packages/capture-kit/src/recording/contact-sheet-plan.test.ts
@@ -0,0 +1,69 @@
+import { describe, expect, test } from 'vitest';
+import { CONTACT_SHEET_DURATION_REASON } from './contact-sheet-report.ts';
+import { AppError } from '@agent-device/kernel/errors';
+import {
+  CONTACT_SHEET_SAMPLE_INTERVAL_MS,
+  MAX_CONTACT_SHEET_SAMPLED_FRAMES,
+  planContactSheetSampleTimes,
+} from './contact-sheet-plan.ts';
+
+const VIDEO = '/tmp/recording.mp4';
+
+function reasonOf(action: () => unknown): unknown {
+  try {
+    action();
+  } catch (error) {
+    return error instanceof AppError ? error.details?.reason : `not an AppError: ${String(error)}`;
+  }
+  return 'no error thrown';
+}
+
+describe('planContactSheetSampleTimes', () => {
+  test('names both endpoints of a clip no longer than one sample step', () => {
+    expect(planContactSheetSampleTimes(0, VIDEO)).toEqual({ durationMs: 0, timesMs: [0] });
+    // One step is not one frame: a clip can change between its first and last presentation sample,
+    // and the sheet promises its ending whatever the clip's length.
+    expect(planContactSheetSampleTimes(CONTACT_SHEET_SAMPLE_INTERVAL_MS, VIDEO)).toEqual({
+      durationMs: CONTACT_SHEET_SAMPLE_INTERVAL_MS,
+      timesMs: [0, CONTACT_SHEET_SAMPLE_INTERVAL_MS],
+    });
+    expect(planContactSheetSampleTimes(100, VIDEO)).toEqual({ durationMs: 100, timesMs: [0, 100] });
+  });
+
+  test('samples every step while the clip is shorter than the cap', () => {
+    expect(planContactSheetSampleTimes(1_000, VIDEO).timesMs).toEqual([0, 250, 500, 750, 1000]);
+  });
+
+  test('stretches the same grid over a long clip instead of adding samples', () => {
+    const hour = planContactSheetSampleTimes(3_600_000, VIDEO);
+
+    expect(hour.timesMs).toHaveLength(MAX_CONTACT_SHEET_SAMPLED_FRAMES);
+    expect(hour.timesMs[0]).toBe(0);
+    expect(hour.timesMs.at(-1)).toBe(3_600_000);
+    expect(new Set(hour.timesMs).size).toBe(MAX_CONTACT_SHEET_SAMPLED_FRAMES);
+    hour.timesMs.forEach((time, index) => {
+      if (index > 0) expect(time).toBeGreaterThan(hour.timesMs[index - 1]!);
+    });
+  });
+
+  test('keeps both endpoints, which is what a coverage claim rests on', () => {
+    for (const durationMs of [5_000, 41_000, 900_000, 7_200_000]) {
+      const plan = planContactSheetSampleTimes(durationMs, VIDEO);
+      expect(plan.durationMs).toBe(durationMs);
+      expect(plan.timesMs[0]).toBe(0);
+      expect(plan.timesMs.at(-1)).toBe(durationMs);
+    }
+  });
+
+  test('refuses to plan over a timeline the container cannot name', () => {
+    expect(reasonOf(() => planContactSheetSampleTimes(undefined, VIDEO))).toBe(
+      CONTACT_SHEET_DURATION_REASON,
+    );
+    expect(reasonOf(() => planContactSheetSampleTimes(Number.NaN, VIDEO))).toBe(
+      CONTACT_SHEET_DURATION_REASON,
+    );
+    expect(reasonOf(() => planContactSheetSampleTimes(-1, VIDEO))).toBe(
+      CONTACT_SHEET_DURATION_REASON,
+    );
+  });
+});
diff --git a/packages/capture-kit/src/recording/contact-sheet-plan.ts b/packages/capture-kit/src/recording/contact-sheet-plan.ts
new file mode 100644
index 0000000000..5a1c79db37
--- /dev/null
+++ b/packages/capture-kit/src/recording/contact-sheet-plan.ts
@@ -0,0 +1,60 @@
+import { CONTACT_SHEET_DURATION_REASON } from './contact-sheet-report.ts';
+import { AppError } from '@agent-device/kernel/errors';
+
+/** Spacing between requested sample times, in milliseconds. */
+export const CONTACT_SHEET_SAMPLE_INTERVAL_MS = 250;
+/** Sample times one sheet asks the decoder for, however long the clip runs. */
+export const MAX_CONTACT_SHEET_SAMPLED_FRAMES = 48;
+
+/**
+ * The times to sample from a clip of `durationMs`, spread evenly across the whole timeline.
+ *
+ * Coverage is the point: the grid always names the start and the end, and it never grows with the
+ * recording. A 5s take samples 21 times; a 2h take samples the same 48 times across its length, so
+ * a long recording costs the same decode budget as a short one and still shows both endpoints.
+ *
+ * A grid is a promise with a hole in it. A flash that opens and closes entirely between two sample
+ * times is not in the returned frames and no threshold can recover it; that is why the sheet
+ * reports how many times it sampled rather than claiming to have reviewed the footage.
+ *
+ * A clip whose timeline cannot be read is refused rather than guessed at. Sampling an unknown
+ * length would mean either walking the whole file or drawing a grid over a duration the container
+ * never claimed, and a sheet built that way could not say what it covered.
+ */
+export type ContactSheetSamplePlan = Readonly<{
+  /** Timeline the grid was planned over, in milliseconds. */
+  durationMs: number;
+  timesMs: readonly number[];
+}>;
+
+export function planContactSheetSampleTimes(
+  durationMs: number | undefined,
+  videoPath: string,
+): ContactSheetSamplePlan {
+  if (durationMs === undefined || !Number.isFinite(durationMs) || durationMs < 0) {
+    throw new AppError(
+      'COMMAND_FAILED',
+      `Cannot plan a contact sheet: the video timeline of ${videoPath} could not be read`,
+      {
+        reason: CONTACT_SHEET_DURATION_REASON,
+        videoPath,
+        hint: 'Retry once the recording finished finalizing; a clip whose container is still being written has no readable duration.',
+      },
+    );
+  }
+  if (durationMs <= CONTACT_SHEET_SAMPLE_INTERVAL_MS) {
+    // A clip shorter than one sampling interval still ends somewhere, and the sheet always promises
+    // its last frame, so the closing sample is asked for even when it is the only other one.
+    return { durationMs, timesMs: durationMs > 0 ? [0, Math.round(durationMs)] : [0] };
+  }
+
+  const count = Math.min(
+    MAX_CONTACT_SHEET_SAMPLED_FRAMES,
+    Math.floor(durationMs / CONTACT_SHEET_SAMPLE_INTERVAL_MS) + 1,
+  );
+  const step = durationMs / (count - 1);
+  return {
+    durationMs,
+    timesMs: Array.from({ length: count }, (_, index) => Math.round(index * step)),
+  };
+}
diff --git a/packages/capture-kit/src/recording/contact-sheet-report.ts b/packages/capture-kit/src/recording/contact-sheet-report.ts
index d0e5b6952c..fb872f89ff 100644
--- a/packages/capture-kit/src/recording/contact-sheet-report.ts
+++ b/packages/capture-kit/src/recording/contact-sheet-report.ts
@@ -5,6 +5,8 @@
 
 /** The host cannot extract frames at all: frame decoding is Apple AVFoundation tooling. */
 export const CONTACT_SHEET_UNSUPPORTED_HOST_REASON = 'contact_sheet_unsupported_host';
+/** The MP4 timeline could not be read, so no bounded sample grid can be planned. */
+export const CONTACT_SHEET_DURATION_REASON = 'contact_sheet_duration_unknown';
 /** Frame extraction ran and failed, rather than returning fewer frames. */
 export const CONTACT_SHEET_EXTRACTION_REASON = 'contact_sheet_frame_extraction_failed';
 /** Extraction returned nothing usable, so there is no sheet to draw. */
diff --git a/packages/capture-kit/src/recording/contact-sheet-selection.test.ts b/packages/capture-kit/src/recording/contact-sheet-selection.test.ts
new file mode 100644
index 0000000000..69791ef8b9
--- /dev/null
+++ b/packages/capture-kit/src/recording/contact-sheet-selection.test.ts
@@ -0,0 +1,98 @@
+import { describe, expect, test } from 'vitest';
+import { paintPng, RED, solidPng } from '../png-pixels.fixtures.ts';
+import {
+  MAX_CONTACT_SHEET_CELLS,
+  selectContactSheetCells,
+  type ContactSheetSample,
+} from './contact-sheet-selection.ts';
+
+const FRAME_SIZE = 10;
+
+function sample(timeMs: number, changedPixels: number, offset = 0): ContactSheetSample {
+  return {
+    timeMs,
+    image: paintPng(
+      solidPng(FRAME_SIZE, FRAME_SIZE),
+      { x: offset, y: 0, width: changedPixels, height: 1 },
+      RED,
+    ),
+  };
+}
+
+function distinctSample(index: number): ContactSheetSample {
+  // Frames of a different shape always count as fully changed, which keeps this fixture honest
+  // without asking it to invent pixels a video decoder would have had to produce.
+  return { timeMs: index * 100, image: solidPng(FRAME_SIZE + index, FRAME_SIZE) };
+}
+
+describe('selectContactSheetCells', () => {
+  test('returns nothing for no samples', () => {
+    expect(selectContactSheetCells([])).toEqual({ cells: [], keptCellCount: 0, thinned: false });
+  });
+
+  test('keeps the only frame it was given', () => {
+    const selection = selectContactSheetCells([sample(0, 0)]);
+
+    expect(selection.cells).toHaveLength(1);
+    expect(selection.cells[0]).toMatchObject({ timeMs: 0, changedPixelRatio: 1 });
+    expect(selection.thinned).toBe(false);
+  });
+
+  test('ends with the final frame even when nothing visibly moved', () => {
+    const selection = selectContactSheetCells([sample(0, 0), sample(250, 0), sample(500, 0)], 0.04);
+
+    expect(selection.cells.map((cell) => cell.timeMs)).toEqual([0, 500]);
+    expect(selection.cells.at(-1)?.changedPixelRatio).toBe(0);
+  });
+
+  test('measures against the last kept cell so small changes add up', () => {
+    const selection = selectContactSheetCells(
+      [
+        sample(0, 0),
+        // 1% of the frame: too small on its own, and it does not become the baseline.
+        sample(250, 1),
+        // 10% of the frame, but only 9% against the previous sample.
+        sample(500, FRAME_SIZE),
+      ],
+      0.1,
+    );
+
+    expect(selection.cells.map((cell) => cell.timeMs)).toEqual([0, 500]);
+    expect(selection.cells[1]?.changedPixelRatio).toBeCloseTo(0.1, 10);
+  });
+
+  test('keeps a frame whose shape changed', () => {
+    const selection = selectContactSheetCells(
+      [sample(0, 0), { timeMs: 250, image: solidPng(20, FRAME_SIZE) }],
+      0.5,
+    );
+
+    expect(selection.cells.map((cell) => cell.timeMs)).toEqual([0, 250]);
+    expect(selection.cells[1]?.changedPixelRatio).toBe(1);
+  });
+
+  test('thins evenly across the kept sequence and keeps both ends', () => {
+    const samples = Array.from({ length: 30 }, (_, index) => distinctSample(index));
+
+    const selection = selectContactSheetCells(samples, 0.04, 4);
+
+    expect(selection.keptCellCount).toBe(30);
+    expect(selection.thinned).toBe(true);
+    expect(selection.cells).toHaveLength(4);
+    expect(selection.cells[0]?.timeMs).toBe(0);
+    expect(selection.cells.at(-1)?.timeMs).toBe(2_900);
+    const times = selection.cells.map((cell) => cell.timeMs);
+    expect(new Set(times).size).toBe(times.length);
+  });
+
+  test('prints every kept cell while the count stays under the sheet cap', () => {
+    const samples = Array.from({ length: MAX_CONTACT_SHEET_CELLS }, (_, index) =>
+      distinctSample(index),
+    );
+
+    const selection = selectContactSheetCells(samples);
+
+    expect(selection.thinned).toBe(false);
+    expect(selection.cells).toHaveLength(MAX_CONTACT_SHEET_CELLS);
+  });
+});
diff --git a/packages/capture-kit/src/recording/contact-sheet-selection.ts b/packages/capture-kit/src/recording/contact-sheet-selection.ts
new file mode 100644
index 0000000000..18ae835bec
--- /dev/null
+++ b/packages/capture-kit/src/recording/contact-sheet-selection.ts
@@ -0,0 +1,103 @@
+import { computePngChangedPixelRatio, type PngRgbImage } from '../png-changed-pixel-ratio.ts';
+
+/**
+ * Which sampled frames earn a cell of their own.
+ *
+ * A cell is kept when it moves enough of the frame relative to the cell kept *before* it, not
+ * relative to its immediate predecessor. Comparing with the previous kept cell is what lets small
+ * changes add up: a list that scrolls one row per frame keeps nothing against its own predecessor
+" * and everything against the last frame that was shown.
+ *
+ * Calibrated on iOS simulator recordings at this sheet's 360px comparison width: an idle status-bar
+ * clock tick measures up to 0.009, while the smallest change worth a cell — a pane arriving over
+ * unchanged chrome — measured 0.030. Any value in that gap separates the two, and this one sits
+ * nearer the noise so a quiet change costs an extra cell instead of going unshown.
+ */
+const CONTACT_SHEET_CHANGED_PIXEL_THRESHOLD = 0.02;
+
+/** Cells one sheet prints. The grid thins evenly across time to hold this, keeping both ends. */
+export const MAX_CONTACT_SHEET_CELLS = 24;
+
+export type ContactSheetSample = Readonly<{
+  /** Presentation time the decoder reported for this frame, in milliseconds from the clip start. */
+  timeMs: number;
+  image: PngRgbImage;
+}>;
+
+export type ContactSheetCell = Readonly<{
+  timeMs: number;
+  changedPixelRatio: number;
+  image: PngRgbImage;
+}>;
+
+export type ContactSheetSelection = Readonly<{
+  cells: readonly ContactSheetCell[];
+  /** Cells the rule kept before the grid was thinned to `MAX_CONTACT_SHEET_CELLS`. */
+  keptCellCount: number;
+  /** Whether thinning dropped kept cells, which the sheet discloses rather than hides. */
+  thinned: boolean;
+}>;
+
+export function selectContactSheetCells(
+  samples: readonly ContactSheetSample[],
+  threshold: number = CONTACT_SHEET_CHANGED_PIXEL_THRESHOLD,
+  maxCells: number = MAX_CONTACT_SHEET_CELLS,
+): ContactSheetSelection {
+  const kept: ContactSheetCell[] = [];
+  let baseline: PngRgbImage | undefined;
+
+  for (const sample of samples) {
+    const changedPixelRatio = baseline
+      ? changedRatioAgainst(baseline, sample.image)
+      : // The first frame has nothing to differ from; it establishes the sheet's starting state.
+        1;
+    if (changedPixelRatio < threshold) continue;
+    kept.push({ timeMs: sample.timeMs, changedPixelRatio, image: sample.image });
+    baseline = sample.image;
+  }
+
+  keepFinalState(kept, samples);
+
+  const cells = kept.length > maxCells ? thinEvenly(kept, maxCells) : kept;
+  return {
+    cells,
+    keptCellCount: kept.length,
+    thinned: cells.length < kept.length,
+  };
+}
+
+/**
+ * Ends the sheet with the last frame the decoder returned.
+ *
+ * The rule alone would drop a clip that settles quietly: a screen that fades rather than moves
+ * keeps only its opening cell, and the caller is left with no picture of where the recording
+ * ended — which is the state a caller most often wants checked. The endpoint is appended with the
+ * ratio it actually measured, so a cell that is there for coverage rather than change still says
+ * so.
+ */
+function keepFinalState(kept: ContactSheetCell[], samples: readonly ContactSheetSample[]): void {
+  const final = samples.at(-1);
+  if (!final) return;
+  const previous = kept.at(-1);
+  if (!previous || previous.timeMs === final.timeMs) return;
+  kept.push({
+    timeMs: final.timeMs,
+    changedPixelRatio: changedRatioAgainst(previous.image, final.image),
+    image: final.image,
+  });
+}
+
+function changedRatioAgainst(baseline: PngRgbImage, candidate: PngRgbImage): number {
+  const result = computePngChangedPixelRatio(baseline, candidate);
+  // A frame that changed shape reshaped the whole picture, which is the largest change there is.
+  return result.status === 'compared' ? result.changedPixelRatio : 1;
+}
+
+function thinEvenly(
+  kept: readonly ContactSheetCell[],
+  maxCells: number,
+): readonly ContactSheetCell[] {
+  if (maxCells <= 1) return [kept.at(-1)!];
+  const stride = (kept.length - 1) / (maxCells - 1);
+  return Array.from({ length: maxCells }, (_, index) => kept[Math.round(index * stride)]!);
+}

From d8d3b35640ebb4651033de8ebc5078a3a0e59c51 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Tue, 22 Sep 2026 13:08:19 +0200
Subject: [PATCH 011/132] feat(capture-kit): paint the contact-sheet grid onto
 one PNG (#2746)

---
 .../capture-kit/src/png-pixels.fixtures.ts    |  10 +-
 packages/capture-kit/src/png-resize.ts        |   2 +-
 .../src/recording/contact-sheet-plan.ts       |   2 +
 .../recording/contact-sheet-render.test.ts    |  88 ++++++++
 .../src/recording/contact-sheet-render.ts     | 205 ++++++++++++++++++
 .../src/recording/contact-sheet-report.ts     |   2 +
 .../src/screenshot-overlay-draw.test.ts       |  64 ++++++
 .../src/screenshot-overlay-draw.ts            | 157 ++++++++------
 8 files changed, 461 insertions(+), 69 deletions(-)
 create mode 100644 packages/capture-kit/src/recording/contact-sheet-render.test.ts
 create mode 100644 packages/capture-kit/src/recording/contact-sheet-render.ts
 create mode 100644 packages/capture-kit/src/screenshot-overlay-draw.test.ts

diff --git a/packages/capture-kit/src/png-pixels.fixtures.ts b/packages/capture-kit/src/png-pixels.fixtures.ts
index 4833b55ad5..ef525331f0 100644
--- a/packages/capture-kit/src/png-pixels.fixtures.ts
+++ b/packages/capture-kit/src/png-pixels.fixtures.ts
@@ -1,11 +1,12 @@
 import { PNG } from './png.ts';
+import { setPngPixel, type PngGlyphColor } from './screenshot-overlay-draw.ts';
 
 /**
  * Decoded-frame builders for tests that reason about pixels: a solid fill and one painted rectangle
  * name exactly what a test claims changed between two frames.
  */
 
-export type Rgba = readonly [number, number, number, number];
+export type Rgba = PngGlyphColor;
 export type Rectangle = Readonly<{ x: number; y: number; width: number; height: number }>;
 
 export const BLACK: Rgba = [0, 0, 0, 255];
@@ -31,12 +32,7 @@ export function paintPng(source: PNG, rectangle: Rectangle, color: Rgba): PNG {
 function fillPng(png: PNG, paint: (column: number, row: number) => boolean, color: Rgba): PNG {
   for (let row = 0; row < png.height; row += 1) {
     for (let column = 0; column < png.width; column += 1) {
-      if (!paint(column, row)) continue;
-      const offset = (row * png.width + column) * 4;
-      png.data[offset] = color[0];
-      png.data[offset + 1] = color[1];
-      png.data[offset + 2] = color[2];
-      png.data[offset + 3] = color[3];
+      if (paint(column, row)) setPngPixel(png, column, row, color);
     }
   }
   return png;
diff --git a/packages/capture-kit/src/png-resize.ts b/packages/capture-kit/src/png-resize.ts
index 7bbab74696..f759956514 100644
--- a/packages/capture-kit/src/png-resize.ts
+++ b/packages/capture-kit/src/png-resize.ts
@@ -39,7 +39,7 @@ export async function resizePngFile(
   await fs.writeFile(filePath, await encodePngAsync(resizePngBox(source, width, height)));
 }
 
-function resizePngBox(source: PNG, width: number, height: number): PNG {
+export function resizePngBox(source: PNG, width: number, height: number): PNG {
   const output = new PNG({ width, height });
   for (let y = 0; y < height; y += 1) {
     const sourceTop = (y * source.height) / height;
diff --git a/packages/capture-kit/src/recording/contact-sheet-plan.ts b/packages/capture-kit/src/recording/contact-sheet-plan.ts
index 5a1c79db37..049a7c21f4 100644
--- a/packages/capture-kit/src/recording/contact-sheet-plan.ts
+++ b/packages/capture-kit/src/recording/contact-sheet-plan.ts
@@ -5,6 +5,8 @@ import { AppError } from '@agent-device/kernel/errors';
 export const CONTACT_SHEET_SAMPLE_INTERVAL_MS = 250;
 /** Sample times one sheet asks the decoder for, however long the clip runs. */
 export const MAX_CONTACT_SHEET_SAMPLED_FRAMES = 48;
+/** Width the decoder is asked to return frames at, which is also the widest cell the sheet draws. */
+export const CONTACT_SHEET_FRAME_WIDTH = 360;
 
 /**
  * The times to sample from a clip of `durationMs`, spread evenly across the whole timeline.
diff --git a/packages/capture-kit/src/recording/contact-sheet-render.test.ts b/packages/capture-kit/src/recording/contact-sheet-render.test.ts
new file mode 100644
index 0000000000..a7086e4945
--- /dev/null
+++ b/packages/capture-kit/src/recording/contact-sheet-render.test.ts
@@ -0,0 +1,88 @@
+import { describe, expect, test } from 'vitest';
+import { AppError } from '@agent-device/kernel/errors';
+import { BLACK, solidPng, WHITE } from '../png-pixels.fixtures.ts';
+import { decodePng } from '../png.ts';
+import { CONTACT_SHEET_FRAME_WIDTH } from './contact-sheet-plan.ts';
+import {
+  MIN_CONTACT_SHEET_CELL_WIDTH,
+  formatContactSheetTimestamp,
+  renderContactSheet,
+} from './contact-sheet-render.ts';
+import type { ContactSheetCell } from './contact-sheet-selection.ts';
+
+function cell(timeMs: number, width = 20, height = 10): ContactSheetCell {
+  return { timeMs, changedPixelRatio: 1, image: solidPng(width, height, BLACK) };
+}
+
+function countPixels(png: ReturnType<typeof decodePng>, color: readonly number[]): number {
+  let count = 0;
+  for (let offset = 0; offset < png.data.length; offset += 4) {
+    if (
+      png.data[offset] === color[0] &&
+      png.data[offset + 1] === color[1] &&
+      png.data[offset + 2] === color[2]
+    ) {
+      count += 1;
+    }
+  }
+  return count;
+}
+
+describe('formatContactSheetTimestamp', () => {
+  test('prints elapsed time the glyph table can spell', () => {
+    expect(formatContactSheetTimestamp(0)).toBe('00:00:00.000');
+    expect(formatContactSheetTimestamp(1_234)).toBe('00:00:01.234');
+    expect(formatContactSheetTimestamp(3_723_456)).toBe('01:02:03.456');
+    expect(formatContactSheetTimestamp(3_600_000)).toBe('01:00:00.000');
+  });
+});
+
+describe('renderContactSheet', () => {
+  test('encodes one grid whose bytes carry the reported size', () => {
+    const sheet = renderContactSheet({
+      cells: [cell(0), cell(250)],
+      maxPixels: 20_000_000,
+    });
+
+    const decoded = decodePng(sheet.bytes, 'contact sheet');
+    expect([decoded.width, decoded.height]).toEqual([sheet.width, sheet.height]);
+    // Two cells in one row of four columns: padding, two cells, and the gap between them.
+    expect(sheet.width).toBe(CONTACT_SHEET_FRAME_WIDTH * 2 + 8 * 3);
+  });
+
+  test('burns a timestamp label above every cell', () => {
+    const sheet = renderContactSheet({
+      cells: [cell(0), cell(250), cell(500)],
+      maxPixels: 20_000_000,
+    });
+
+    const decoded = decodePng(sheet.bytes, 'contact sheet');
+    expect(countPixels(decoded, WHITE)).toBeGreaterThan(0);
+  });
+
+  test('shrinks cells to stay inside the caller’s pixel budget', () => {
+    const sheet = renderContactSheet({
+      cells: Array.from({ length: 12 }, (_, index) => cell(index * 250, 80, 40)),
+      maxPixels: 250_000,
+    });
+
+    expect(sheet.width * sheet.height).toBeLessThanOrEqual(250_000);
+    expect(sheet.cellWidth).toBeLessThan(CONTACT_SHEET_FRAME_WIDTH);
+    expect(sheet.cellWidth).toBeGreaterThanOrEqual(MIN_CONTACT_SHEET_CELL_WIDTH);
+  });
+
+  test('refuses rather than printing a sheet nobody can read', () => {
+    expect(() =>
+      renderContactSheet({ cells: [cell(0, 40, 400), cell(250, 40, 400)], maxPixels: 4_000 }),
+    ).toThrow(/maxImagePixels/);
+  });
+
+  test('refuses a sheet with no cells instead of writing an empty page', () => {
+    try {
+      renderContactSheet({ cells: [], maxPixels: 20_000_000 });
+      throw new Error('expected renderContactSheet to refuse');
+    } catch (error) {
+      expect(error).toBeInstanceOf(AppError);
+    }
+  });
+});
diff --git a/packages/capture-kit/src/recording/contact-sheet-render.ts b/packages/capture-kit/src/recording/contact-sheet-render.ts
new file mode 100644
index 0000000000..d6c0827c03
--- /dev/null
+++ b/packages/capture-kit/src/recording/contact-sheet-render.ts
@@ -0,0 +1,205 @@
+import { CONTACT_SHEET_PIXEL_BUDGET_REASON } from './contact-sheet-report.ts';
+import { AppError } from '@agent-device/kernel/errors';
+import { encodePngPixels } from '../png-encode.ts';
+import { PNG } from '../png.ts';
+import { resizePngBox } from '../png-resize.ts';
+import {
+  drawPngGlyphText,
+  measurePngGlyphTextHeight,
+  setPngPixel,
+  type PngGlyphColor,
+} from '../screenshot-overlay-draw.ts';
+import { CONTACT_SHEET_FRAME_WIDTH } from './contact-sheet-plan.ts';
+import type { ContactSheetCell } from './contact-sheet-selection.ts';
+
+/** Cells per row. Four keeps a portrait phone frame readable without a canvas wider than a screen. */
+const CONTACT_SHEET_COLUMNS = 4;
+/** Narrowest a cell may shrink to before the sheet refuses rather than print unreadable frames. */
+export const MIN_CONTACT_SHEET_CELL_WIDTH = 160;
+/**
+ * Cell widths tried, widest first. A cell never grows past the width frames were decoded at, and it
+ * shrinks in readable steps before the sheet refuses.
+ */
+const LAYOUT_CELL_WIDTHS = [
+  CONTACT_SHEET_FRAME_WIDTH,
+  320,
+  280,
+  240,
+  200,
+  MIN_CONTACT_SHEET_CELL_WIDTH,
+] as const;
+
+const SHEET_PADDING = 8;
+const CELL_GAP = 8;
+const LABEL_INSET = 4;
+const LABEL_SCALE = 2;
+const LABEL_COLOR = [255, 255, 255, 255] as const;
+const SHEET_BACKGROUND = [17, 24, 39, 255] as const;
+const LABEL_HEIGHT = measurePngGlyphTextHeight(LABEL_SCALE) + LABEL_INSET * 2;
+
+export type ContactSheetRenderInput = Readonly<{
+  cells: readonly ContactSheetCell[];
+  maxPixels: number;
+}>;
+
+export type ContactSheetRenderResult = Readonly<{
+  bytes: Buffer;
+  width: number;
+  height: number;
+  cellWidth: number;
+}>;
+
+/** Lays the kept cells out in one row-major grid and encodes it as PNG. */
+export function renderContactSheet(input: ContactSheetRenderInput): ContactSheetRenderResult {
+  const { cells } = input;
+  if (cells.length === 0) {
+    throw new AppError('COMMAND_FAILED', 'Contact sheet has no cells to render');
+  }
+
+  const aspect = cells[0]!.image.height / Math.max(1, cells[0]!.image.width);
+  const layout = fitLayout(aspect, cells.length, input);
+  const canvas = createCanvas(layout.width, layout.height, SHEET_BACKGROUND);
+
+  cells.forEach((cell, index) => {
+    const column = index % layout.columns;
+    const row = Math.floor(index / layout.columns);
+    drawCell(
+      canvas,
+      SHEET_PADDING + column * (layout.cellWidth + CELL_GAP),
+      SHEET_PADDING + row * (LABEL_HEIGHT + layout.cellHeight + CELL_GAP),
+      cell,
+      layout.cellWidth,
+      layout.cellHeight,
+    );
+  });
+
+  return {
+    bytes: encodePngPixels(canvas.data, layout.width, layout.height, 4),
+    width: layout.width,
+    height: layout.height,
+    cellWidth: layout.cellWidth,
+  };
+}
+
+function drawCell(
+  canvas: PNG,
+  x: number,
+  y: number,
+  cell: ContactSheetCell,
+  cellWidth: number,
+  cellHeight: number,
+): void {
+  drawPngGlyphText(canvas, {
+    x: x + LABEL_INSET,
+    y: y + LABEL_INSET,
+    text: formatContactSheetTimestamp(cell.timeMs),
+    color: LABEL_COLOR,
+    scale: LABEL_SCALE,
+  });
+  blit(canvas, resizePngBox(toPng(cell.image), cellWidth, cellHeight), x, y + LABEL_HEIGHT);
+}
+
+type ContactSheetLayout = Readonly<{
+  width: number;
+  height: number;
+  columns: number;
+  cellWidth: number;
+  cellHeight: number;
+}>;
+
+/**
+ * Sizes the grid so it fits the caller's pixel budget.
+ *
+ * A cell shrinks before a sheet refuses: an over-budget clip is ordinary (a tall iPad recording
+ * with many changes), and re-laying the same cells out at a smaller cell is always available.
+ */
+function fitLayout(
+  aspect: number,
+  cellCount: number,
+  input: ContactSheetRenderInput,
+): ContactSheetLayout {
+  const fitted = fitToBudget(aspect, cellCount, input.maxPixels);
+  if (fitted) return fitted;
+  const smallest = layoutAt(aspect, cellCount, MIN_CONTACT_SHEET_CELL_WIDTH);
+  throw new AppError(
+    'COMMAND_FAILED',
+    `Contact sheet would be ${smallest.width * smallest.height} pixels, above the configured maxImagePixels limit of ${input.maxPixels}`,
+    {
+      reason: CONTACT_SHEET_PIXEL_BUDGET_REASON,
+      cellCount: input.cells.length,
+      maxPixels: input.maxPixels,
+      hint: 'Shorten the recording or raise the command policy maxImagePixels limit.',
+    },
+  );
+}
+
+/**
+ * Walks the cell-width ladder until the grid fits, because the label strip does not shrink with the
+ * cell and a single proportional guess can land over budget. The ladder is finite and strictly
+ * descending, so the narrowest readable cell is always the last thing tried.
+ */
+function fitToBudget(
+  aspect: number,
+  cellCount: number,
+  budget: number,
+): ContactSheetLayout | undefined {
+  for (const cellWidth of LAYOUT_CELL_WIDTHS) {
+    const layout = layoutAt(aspect, cellCount, cellWidth);
+    if (layout.width * layout.height <= budget) return layout;
+  }
+  return undefined;
+}
+
+function layoutAt(aspect: number, cellCount: number, cellWidth: number): ContactSheetLayout {
+  const columns = Math.min(CONTACT_SHEET_COLUMNS, cellCount);
+  const rows = Math.ceil(cellCount / columns);
+  const cellHeight = Math.max(1, Math.round(cellWidth * aspect));
+  return {
+    columns,
+    cellWidth,
+    cellHeight,
+    width: SHEET_PADDING * 2 + columns * cellWidth + (columns - 1) * CELL_GAP,
+    height: SHEET_PADDING * 2 + rows * (LABEL_HEIGHT + cellHeight) + (rows - 1) * CELL_GAP,
+  };
+}
+
+function createCanvas(width: number, height: number, color: PngGlyphColor): PNG {
+  const canvas = new PNG({ width, height });
+  for (let row = 0; row < height; row += 1) {
+    for (let column = 0; column < width; column += 1) {
+      setPngPixel(canvas, column, row, color);
+    }
+  }
+  return canvas;
+}
+
+function blit(canvas: PNG, source: PNG, x: number, y: number): void {
+  for (let row = 0; row < source.height; row += 1) {
+    for (let column = 0; column < source.width; column += 1) {
+      const sourceOffset = (row * source.width + column) * 4;
+      setPngPixel(canvas, x + column, y + row, [
+        source.data[sourceOffset]!,
+        source.data[sourceOffset + 1]!,
+        source.data[sourceOffset + 2]!,
+        source.data[sourceOffset + 3]!,
+      ]);
+    }
+  }
+}
+
+function toPng(image: ContactSheetCell['image']): PNG {
+  const png = new PNG({ width: image.width, height: image.height });
+  Buffer.from(image.data.buffer, image.data.byteOffset, image.data.byteLength).copy(png.data);
+  return png;
+}
+
+/** Elapsed time from the clip start as `HH:MM:SS.mmm`, the shape the glyph table spells. */
+export function formatContactSheetTimestamp(timeMs: number): string {
+  const wholeSeconds = Math.floor(timeMs / 1000);
+  const hours = Math.floor(wholeSeconds / 3600);
+  const minutes = Math.floor((wholeSeconds % 3600) / 60);
+  const seconds = wholeSeconds % 60;
+  const milliseconds = Math.floor(timeMs % 1000);
+  const clock = [hours, minutes, seconds].map((part) => String(part).padStart(2, '0')).join(':');
+  return `${clock}.${String(milliseconds).padStart(3, '0')}`;
+}
diff --git a/packages/capture-kit/src/recording/contact-sheet-report.ts b/packages/capture-kit/src/recording/contact-sheet-report.ts
index fb872f89ff..7c519fdc98 100644
--- a/packages/capture-kit/src/recording/contact-sheet-report.ts
+++ b/packages/capture-kit/src/recording/contact-sheet-report.ts
@@ -11,3 +11,5 @@ export const CONTACT_SHEET_DURATION_REASON = 'contact_sheet_duration_unknown';
 export const CONTACT_SHEET_EXTRACTION_REASON = 'contact_sheet_frame_extraction_failed';
 /** Extraction returned nothing usable, so there is no sheet to draw. */
 export const CONTACT_SHEET_NO_FRAMES_REASON = 'contact_sheet_no_frames';
+/** The requested sheet would exceed the caller's image pixel budget even at the smallest cell. */
+export const CONTACT_SHEET_PIXEL_BUDGET_REASON = 'contact_sheet_pixel_budget_exceeded';
diff --git a/packages/capture-kit/src/screenshot-overlay-draw.test.ts b/packages/capture-kit/src/screenshot-overlay-draw.test.ts
new file mode 100644
index 0000000000..5ed0932700
--- /dev/null
+++ b/packages/capture-kit/src/screenshot-overlay-draw.test.ts
@@ -0,0 +1,64 @@
+import { describe, expect, test } from 'vitest';
+import { BLACK, solidPng, WHITE } from './png-pixels.fixtures.ts';
+import { PNG } from './png.ts';
+import { drawPngGlyphText, measurePngGlyphTextHeight } from './screenshot-overlay-draw.ts';
+
+/** One glyph column count plus the gap after it; the distance the painter moves per character. */
+const GLYPH_PITCH = 6;
+
+function countPixels(png: PNG, color: readonly number[]): number {
+  let count = 0;
+  for (let offset = 0; offset < png.data.length; offset += 4) {
+    if (
+      png.data[offset] === color[0] &&
+      png.data[offset + 1] === color[1] &&
+      png.data[offset + 2] === color[2] &&
+      png.data[offset + 3] === color[3]
+    ) {
+      count += 1;
+    }
+  }
+  return count;
+}
+
+describe('png glyph text', () => {
+  test('paints the timestamp characters an elapsed-time label is built from', () => {
+    for (const text of ['0', '9', ':', '.', '00:00:01.234']) {
+      const png = solidPng(140, 12, BLACK);
+      drawPngGlyphText(png, { x: 2, y: 2, text, color: WHITE });
+      expect(countPixels(png, WHITE), text).toBeGreaterThan(0);
+    }
+  });
+
+  test('scales a glyph to whole blocks so a label stays crisp', () => {
+    const single = solidPng(40, 12, BLACK);
+    drawPngGlyphText(single, { x: 2, y: 2, text: '1', color: WHITE });
+    const doubled = solidPng(40, 20, BLACK);
+    drawPngGlyphText(doubled, { x: 2, y: 2, text: '1', color: WHITE, scale: 2 });
+
+    expect(countPixels(doubled, WHITE)).toBe(countPixels(single, WHITE) * 4);
+    expect(measurePngGlyphTextHeight()).toBe(7);
+    expect(measurePngGlyphTextHeight(2)).toBe(14);
+  });
+
+  test('advances past a character the table does not cover', () => {
+    const blank = solidPng(40, 12, BLACK);
+    drawPngGlyphText(blank, { x: 2, y: 2, text: 'z', color: WHITE });
+    expect(countPixels(blank, WHITE)).toBe(0);
+
+    const shifted = solidPng(40, 12, BLACK);
+    drawPngGlyphText(shifted, { x: 2, y: 2, text: 'z1', color: WHITE });
+    const aligned = solidPng(40, 12, BLACK);
+    drawPngGlyphText(aligned, { x: 2 + GLYPH_PITCH, y: 2, text: '1', color: WHITE });
+
+    expect(shifted.data.equals(aligned.data)).toBe(true);
+  });
+
+  test('clips at the image edge instead of writing past it', () => {
+    const png = solidPng(4, 4, BLACK);
+    expect(() =>
+      drawPngGlyphText(png, { x: -3, y: -3, text: '00:00', color: WHITE, scale: 2 }),
+    ).not.toThrow();
+    expect(png.data.length).toBe(4 * 4 * 4);
+  });
+});
diff --git a/packages/capture-kit/src/screenshot-overlay-draw.ts b/packages/capture-kit/src/screenshot-overlay-draw.ts
index ef6a7ba920..eeacc94675 100644
--- a/packages/capture-kit/src/screenshot-overlay-draw.ts
+++ b/packages/capture-kit/src/screenshot-overlay-draw.ts
@@ -3,20 +3,28 @@ import type { PNG } from './png.ts';
 import { clamp } from './screenshot-overlay-rects.ts';
 
 /**
- * Rasterizing one overlay ref onto a decoded PNG: border, badge, and the bitmap glyphs the badge
- * needs. Which node earns a ref, and where its rect lands, is `screenshot-overlay.ts`'s question —
- * this module only paints what it is handed.
+ * Rasterizing onto a decoded PNG: border, badge, and the elapsed-time labels other annotators paint.
+ * Which node earns a ref, and where its rect lands, is `screenshot-overlay.ts`'s question — this
+ * module only paints what it is handed.
  */
-const BORDER_COLOR = [255, 59, 48, 255] as const;
-const BADGE_COLOR = [255, 214, 10, 255] as const;
-const TEXT_COLOR = [0, 0, 0, 255] as const;
-const FONT_WIDTH = 5;
-const FONT_HEIGHT = 7;
-const FONT_SPACING = 1;
+const BORDER_COLOR: PngGlyphColor = [255, 59, 48, 255];
+const BADGE_COLOR: PngGlyphColor = [255, 214, 10, 255];
+const TEXT_COLOR: PngGlyphColor = [0, 0, 0, 255];
+const GLYPH_WIDTH = 5;
+const GLYPH_HEIGHT = 7;
+const GLYPH_SPACING = 1;
+const GLYPH_PITCH = GLYPH_WIDTH + GLYPH_SPACING;
 const BADGE_PADDING_X = 3;
 const BADGE_PADDING_Y = 2;
 const BADGE_MARGIN = 2;
 const BORDER_THICKNESS = 2;
+
+/**
+ * The bitmap glyph table every capture annotator paints with. It covers the characters those labels
+ * are built from — the `e` ref prefix, digits, and the separator and decimal point of an elapsed
+ * time — and nothing else, so an unsupported character paints as blank rather than inventing a
+ * shape nobody reviewed.
+ */
 const FONT: Record<string, readonly string[]> = {
   e: ['01110', '10000', '11110', '10000', '10000', '10001', '01110'],
   '0': ['01110', '10001', '10011', '10101', '11001', '10001', '01110'],
@@ -29,20 +37,79 @@ const FONT: Record<string, readonly string[]> = {
   '7': ['11111', '00001', '00010', '00100', '01000', '01000', '01000'],
   '8': ['01110', '10001', '10001', '01110', '10001', '10001', '01110'],
   '9': ['01110', '10001', '10001', '01111', '00001', '00001', '01110'],
-} as const;
-// Badges currently render only `eN` refs, so the bitmap font intentionally covers `e` and digits.
+  ':': ['00000', '00100', '00100', '00000', '00100', '00100', '00000'],
+  '.': ['00000', '00000', '00000', '00000', '00000', '00110', '00110'],
+};
+
+/** One RGBA pixel, in the order PNG rows store them. */
+export type PngGlyphColor = readonly [number, number, number, number];
 
 export function drawOverlayRef(png: PNG, overlayRef: ScreenshotOverlayRef): void {
   drawRectBorder(png, overlayRef.overlayRect, BORDER_COLOR, BORDER_THICKNESS);
   drawBadge(png, overlayRef.overlayRect, overlayRef.ref);
 }
 
-function drawRectBorder(
+/** Width the painted text occupies at scale 1, with no trailing inter-character gap. */
+function measurePngGlyphTextWidth(text: string): number {
+  if (text === '') return 0;
+  return text.length * GLYPH_PITCH - GLYPH_SPACING;
+}
+
+export function measurePngGlyphTextHeight(scale = 1): number {
+  return GLYPH_HEIGHT * scale;
+}
+
+/**
+ * Paints `text` at `x, y`, each glyph block `scale` pixels wide and tall, clipping at the image
+ * edge. A character the table does not cover still advances the cursor, so a partially supported
+ * label keeps its layout.
+ */
+export function drawPngGlyphText(
+  png: PNG,
+  input: Readonly<{
+    x: number;
+    y: number;
+    text: string;
+    color: PngGlyphColor;
+    scale?: number;
+  }>,
+): void {
+  const scale = input.scale ?? 1;
+  let cursorX = input.x;
+  for (const character of input.text.toLowerCase()) {
+    const glyph = FONT[character];
+    if (glyph) drawGlyph(png, glyph, cursorX, input.y, scale, input.color);
+    cursorX += GLYPH_PITCH * scale;
+  }
+}
+
+function drawGlyph(
   png: PNG,
-  rect: Rect,
-  color: readonly [number, number, number, number],
-  thickness: number,
+  glyph: readonly string[],
+  x: number,
+  y: number,
+  scale: number,
+  color: PngGlyphColor,
 ): void {
+  for (let row = 0; row < glyph.length; row += 1) {
+    for (let column = 0; column < glyph[row]!.length; column += 1) {
+      if (glyph[row]![column] !== '1') continue;
+      fillRect(png, x + column * scale, y + row * scale, scale, scale, color);
+    }
+  }
+}
+
+/** Writes one pixel, dropping anything outside the image. */
+export function setPngPixel(png: PNG, x: number, y: number, color: PngGlyphColor): void {
+  if (x < 0 || y < 0 || x >= png.width || y >= png.height) return;
+  const index = (png.width * y + x) * 4;
+  png.data[index] = color[0];
+  png.data[index + 1] = color[1];
+  png.data[index + 2] = color[2];
+  png.data[index + 3] = color[3];
+}
+
+function drawRectBorder(png: PNG, rect: Rect, color: PngGlyphColor, thickness: number): void {
   for (let offset = 0; offset < thickness; offset += 1) {
     drawHorizontalLine(png, rect.x, rect.x + rect.width - 1, rect.y + offset, color);
     drawHorizontalLine(
@@ -64,9 +131,8 @@ function drawRectBorder(
 }
 
 function drawBadge(png: PNG, rect: Rect, text: string): void {
-  const badgeWidth =
-    BADGE_PADDING_X * 2 + text.length * FONT_WIDTH + Math.max(0, text.length - 1) * FONT_SPACING;
-  const badgeHeight = BADGE_PADDING_Y * 2 + FONT_HEIGHT;
+  const badgeWidth = BADGE_PADDING_X * 2 + measurePngGlyphTextWidth(text);
+  const badgeHeight = BADGE_PADDING_Y * 2 + GLYPH_HEIGHT;
   const x = clamp(rect.x, 0, Math.max(0, png.width - badgeWidth));
   const preferredY = rect.y - badgeHeight - BADGE_MARGIN;
   const y =
@@ -74,29 +140,12 @@ function drawBadge(png: PNG, rect: Rect, text: string): void {
       ? preferredY
       : clamp(rect.y + BADGE_MARGIN, 0, Math.max(0, png.height - badgeHeight));
   fillRect(png, x, y, badgeWidth, badgeHeight, BADGE_COLOR);
-  drawText(png, x + BADGE_PADDING_X, y + BADGE_PADDING_Y, text, TEXT_COLOR);
-}
-
-function drawText(
-  png: PNG,
-  x: number,
-  y: number,
-  text: string,
-  color: readonly [number, number, number, number],
-): void {
-  let cursorX = x;
-  for (const character of text.toLowerCase()) {
-    const glyph = FONT[character];
-    if (glyph) {
-      for (let row = 0; row < glyph.length; row += 1) {
-        for (let column = 0; column < glyph[row]!.length; column += 1) {
-          if (glyph[row]![column] !== '1') continue;
-          setPixel(png, cursorX + column, y + row, color);
-        }
-      }
-    }
-    cursorX += FONT_WIDTH + FONT_SPACING;
-  }
+  drawPngGlyphText(png, {
+    x: x + BADGE_PADDING_X,
+    y: y + BADGE_PADDING_Y,
+    text,
+    color: TEXT_COLOR,
+  });
 }
 
 function fillRect(
@@ -105,11 +154,11 @@ function fillRect(
   y: number,
   width: number,
   height: number,
-  color: readonly [number, number, number, number],
+  color: PngGlyphColor,
 ): void {
   for (let row = 0; row < height; row += 1) {
     for (let column = 0; column < width; column += 1) {
-      setPixel(png, x + column, y + row, color);
+      setPngPixel(png, x + column, y + row, color);
     }
   }
 }
@@ -119,10 +168,10 @@ function drawHorizontalLine(
   startX: number,
   endX: number,
   y: number,
-  color: readonly [number, number, number, number],
+  color: PngGlyphColor,
 ): void {
   for (let x = startX; x <= endX; x += 1) {
-    setPixel(png, x, y, color);
+    setPngPixel(png, x, y, color);
   }
 }
 
@@ -131,23 +180,9 @@ function drawVerticalLine(
   x: number,
   startY: number,
   endY: number,
-  color: readonly [number, number, number, number],
+  color: PngGlyphColor,
 ): void {
   for (let y = startY; y <= endY; y += 1) {
-    setPixel(png, x, y, color);
+    setPngPixel(png, x, y, color);
   }
 }
-
-function setPixel(
-  png: PNG,
-  x: number,
-  y: number,
-  color: readonly [number, number, number, number],
-): void {
-  if (x < 0 || y < 0 || x >= png.width || y >= png.height) return;
-  const index = (png.width * y + x) * 4;
-  png.data[index] = color[0];
-  png.data[index + 1] = color[1];
-  png.data[index + 2] = color[2];
-  png.data[index + 3] = color[3];
-}

From bb4ccffbacc85d952c762be5fe0a4bdcc0d89148 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Tue, 22 Sep 2026 13:08:19 +0200
Subject: [PATCH 012/132] feat(recording): build a contact sheet from a
 finished recording (#2752)

---
 .../src/recording/artifact-paths.test.ts      |  23 ++
 .../src/recording/artifact-paths.ts           |  11 +
 .../src/recording/contact-sheet-report.ts     |  41 ++-
 .../src/recording/contact-sheet-selection.ts  |   2 +-
 .../src/recording/contact-sheet.test.ts       | 335 ++++++++++++++++++
 .../src/recording/contact-sheet.ts            | 244 +++++++++++++
 packages/capture-kit/src/recording/video.ts   |  13 +-
 .../host-kit/src/internal/atomic-file.test.ts |  45 +++
 packages/host-kit/src/internal/atomic-file.ts |  18 +-
 9 files changed, 717 insertions(+), 15 deletions(-)
 create mode 100644 packages/capture-kit/src/recording/artifact-paths.test.ts
 create mode 100644 packages/capture-kit/src/recording/contact-sheet.test.ts
 create mode 100644 packages/capture-kit/src/recording/contact-sheet.ts
 create mode 100644 packages/host-kit/src/internal/atomic-file.test.ts

diff --git a/packages/capture-kit/src/recording/artifact-paths.test.ts b/packages/capture-kit/src/recording/artifact-paths.test.ts
new file mode 100644
index 0000000000..cd85d4649d
--- /dev/null
+++ b/packages/capture-kit/src/recording/artifact-paths.test.ts
@@ -0,0 +1,23 @@
+import { describe, expect, test } from 'vitest';
+import {
+  collectedRecordingPath,
+  nativeRecordingPath,
+  recordingContactSheetPath,
+} from './artifact-paths.ts';
+
+describe('recording artifact sibling paths', () => {
+  test('keeps the recorder file and the collected copy beside the export', () => {
+    expect(nativeRecordingPath('/tmp/recording.mp4')).toBe('/tmp/recording.native.mp4');
+    expect(collectedRecordingPath('/tmp/recording.mp4')).toBe('/tmp/recording.collected.mp4');
+  });
+
+  test('names the contact sheet after the report it is, not the container it came from', () => {
+    expect(recordingContactSheetPath('/tmp/recording.mp4')).toBe(
+      '/tmp/recording.contact-sheet.png',
+    );
+    expect(recordingContactSheetPath('/tmp/rec')).toBe('/tmp/rec.contact-sheet.png');
+    expect(recordingContactSheetPath('/tmp/rec.TAKE-2.MP4')).toBe(
+      '/tmp/rec.TAKE-2.contact-sheet.png',
+    );
+  });
+});
diff --git a/packages/capture-kit/src/recording/artifact-paths.ts b/packages/capture-kit/src/recording/artifact-paths.ts
index 80cacd48d7..294d35bdf8 100644
--- a/packages/capture-kit/src/recording/artifact-paths.ts
+++ b/packages/capture-kit/src/recording/artifact-paths.ts
@@ -19,6 +19,17 @@ export function collectedRecordingPath(exportPath: string): string {
   return siblingRecordingPath(exportPath, 'collected');
 }
 
+/**
+ * The report a caller asks a finished export to carry: one PNG holding the frames that changed, so
+ * an agent can read a recording without playing it. It is derived, so unlike the paths above it is
+ * never a recorder's and is always safe to rebuild from the export.
+ */
+export function recordingContactSheetPath(exportPath: string): string {
+  const extension = path.extname(exportPath);
+  const base = extension === '' ? exportPath : exportPath.slice(0, -extension.length);
+  return `${base}.contact-sheet.png`;
+}
+
 function siblingRecordingPath(exportPath: string, role: 'native' | 'collected'): string {
   const extension = path.extname(exportPath);
   const base = extension === '' ? exportPath : exportPath.slice(0, -extension.length);
diff --git a/packages/capture-kit/src/recording/contact-sheet-report.ts b/packages/capture-kit/src/recording/contact-sheet-report.ts
index 7c519fdc98..cfbd653551 100644
--- a/packages/capture-kit/src/recording/contact-sheet-report.ts
+++ b/packages/capture-kit/src/recording/contact-sheet-report.ts
@@ -1,6 +1,8 @@
 /**
- * Why a contact sheet was not drawn. Each reason is a typed constant the extraction path fails with,
- * so a caller branches on the reason instead of reading an error message.
+ * What a contact sheet reports: the shape of the finished grid, and the typed reasons it refuses with
+ * when there is no grid to draw. Both stay here rather than in cross-layer contracts because nothing
+ * but this package's pipeline produces them and the surface that reads them already imports this
+ * package; a caller branches on a reason instead of reading an error message.
  */
 
 /** The host cannot extract frames at all: frame decoding is Apple AVFoundation tooling. */
@@ -13,3 +15,38 @@ export const CONTACT_SHEET_EXTRACTION_REASON = 'contact_sheet_frame_extraction_f
 export const CONTACT_SHEET_NO_FRAMES_REASON = 'contact_sheet_no_frames';
 /** The requested sheet would exceed the caller's image pixel budget even at the smallest cell. */
 export const CONTACT_SHEET_PIXEL_BUDGET_REASON = 'contact_sheet_pixel_budget_exceeded';
+/** The file is present but is not a container this feature decodes, such as a WebM recording. */
+export const CONTACT_SHEET_CONTAINER_REASON = 'contact_sheet_container_unsupported';
+/** The sheet could not be written where it was asked to land. */
+export const CONTACT_SHEET_OUTPUT_WRITE_REASON = 'contact_sheet_output_write_failed';
+/** The output resolves to the recording itself, which a sheet must never replace. */
+export const CONTACT_SHEET_OUTPUT_COLLISION_REASON = 'contact_sheet_output_collides_with_input';
+
+export type RecordingContactSheetCell = {
+  /** Presentation time of the decoded frame this cell shows, in milliseconds from the clip start. */
+  readonly timeMs: number;
+  /** Share of pixels that moved since the previously kept cell, from 0 to 1. */
+  readonly changedPixelRatio: number;
+};
+
+export type RecordingContactSheetResult = {
+  readonly path: string;
+  readonly videoPath: string;
+  /** Video timeline the grid was planned over, in milliseconds. */
+  readonly durationMs: number;
+  readonly width: number;
+  readonly height: number;
+  /**
+   * Sample times the grid asked for. Sampling is a grid, not a scan: a transient that falls wholly
+   * between two sample times is absent from the sheet.
+   */
+  readonly sampledFrameCount: number;
+  /** Frames the decoder actually returned. */
+  readonly decodedFrameCount: number;
+  /** Requested sample times the decoder declined to answer. */
+  readonly skippedSampleCount: number;
+  /** Changed-pixel share a frame had to exceed to earn its own cell. */
+  readonly changedPixelThreshold: number;
+  readonly cells: readonly RecordingContactSheetCell[];
+  readonly warning?: string;
+};
diff --git a/packages/capture-kit/src/recording/contact-sheet-selection.ts b/packages/capture-kit/src/recording/contact-sheet-selection.ts
index 18ae835bec..0a128f094e 100644
--- a/packages/capture-kit/src/recording/contact-sheet-selection.ts
+++ b/packages/capture-kit/src/recording/contact-sheet-selection.ts
@@ -13,7 +13,7 @@ import { computePngChangedPixelRatio, type PngRgbImage } from '../png-changed-pi
  * unchanged chrome — measured 0.030. Any value in that gap separates the two, and this one sits
  * nearer the noise so a quiet change costs an extra cell instead of going unshown.
  */
-const CONTACT_SHEET_CHANGED_PIXEL_THRESHOLD = 0.02;
+export const CONTACT_SHEET_CHANGED_PIXEL_THRESHOLD = 0.02;
 
 /** Cells one sheet prints. The grid thins evenly across time to hold this, keeping both ends. */
 export const MAX_CONTACT_SHEET_CELLS = 24;
diff --git a/packages/capture-kit/src/recording/contact-sheet.test.ts b/packages/capture-kit/src/recording/contact-sheet.test.ts
new file mode 100644
index 0000000000..464f65dd3b
--- /dev/null
+++ b/packages/capture-kit/src/recording/contact-sheet.test.ts
@@ -0,0 +1,335 @@
+import { beforeEach, describe, expect, test, vi } from 'vitest';
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  CONTACT_SHEET_CONTAINER_REASON,
+  CONTACT_SHEET_DURATION_REASON,
+  CONTACT_SHEET_EXTRACTION_REASON,
+  CONTACT_SHEET_OUTPUT_COLLISION_REASON,
+  CONTACT_SHEET_PIXEL_BUDGET_REASON,
+  CONTACT_SHEET_UNSUPPORTED_HOST_REASON,
+} from './contact-sheet-report.ts';
+import { AppError } from '@agent-device/kernel/errors';
+import { BLACK, RED, WHITE, paintPng, solidPng } from '../png-pixels.fixtures.ts';
+import { mkdtempForTestSync } from '../tmp-dir.fixtures.ts';
+import { decodePng } from '../png.ts';
+import { mp4Atom, mp4MovieHeader } from './mp4.fixtures.ts';
+import { writeDecodedFrames, type StubFrame } from './contact-sheet.fixtures.ts';
+import { buildRecordingContactSheet, recordingContactSheetPath } from './contact-sheet.ts';
+
+vi.mock(import('@agent-device/host-kit/command'), async (importOriginal) => ({
+  ...(await importOriginal()),
+  runCmd: vi.fn(),
+}));
+
+vi.mock(import('./swift-cache.ts'), async (importOriginal) => ({
+  ...(await importOriginal<typeof import('./swift-cache.ts')>()),
+  compileSwiftSourceFile: vi.fn(async () => '/cached/bin/recording-frames'),
+}));
+
+import { runCmd } from '@agent-device/host-kit/command';
+import { likelyPlayableWebmContainer } from '../__tests__/test-utils/video-fixtures.ts';
+
+const mockRunCmd = vi.mocked(runCmd);
+const directory = mkdtempForTestSync('agent-device-contact-sheet-pipeline-');
+
+/** A recording the container sniff and the timeline reader both recognise, at a chosen length. */
+function recording(name: string, durationMs: number): string {
+  const filePath = path.join(directory, `${name}.mp4`);
+  fs.writeFileSync(
+    filePath,
+    Buffer.concat([
+      mp4Atom('ftyp', Buffer.alloc(24)),
+      mp4Atom('mdat', Buffer.alloc(16)),
+      mp4Atom(
+        'moov',
+        mp4Atom(
+          'mvhd',
+          mp4MovieHeader({ version: 0, timescale: 1_000, duration: unknownable(durationMs) }),
+        ),
+      ),
+    ]),
+  );
+  return filePath;
+}
+
+function unknownable(durationMs: number): number {
+  return durationMs < 0 ? 0xffffffff : durationMs;
+}
+
+function frame(timeMs: number, changed: boolean): StubFrame {
+  return {
+    png: changed
+      ? paintPng(solidPng(8, 8, BLACK), { x: 0, y: 0, width: 8, height: 8 }, RED)
+      : solidPng(8, 8, BLACK),
+    actualTimeMs: timeMs,
+  };
+}
+
+/**
+ * Answers the grid the planner will ask for. `presentMs` names the times the decoder answers;
+ * anything the grid asked for and is left out is reported skipped, as a real decoder declines.
+ */
+function answerForGrid(
+  input: Readonly<{
+    timesMs: readonly number[];
+    presentMs?: readonly number[];
+    changedMs?: readonly number[];
+  }>,
+): void {
+  const present = new Set(input.presentMs ?? input.timesMs);
+  const changed = new Set(input.changedMs ?? []);
+  const byRequestedTime = new Map<number, StubFrame>();
+  for (const timeMs of input.timesMs) {
+    if (present.has(timeMs)) byRequestedTime.set(timeMs, frame(timeMs, changed.has(timeMs)));
+  }
+  mockRunCmd.mockImplementation(async (_cmd, args) =>
+    writeDecodedFrames({ args: args as string[], framesByRequestedTimeMs: byRequestedTime }),
+  );
+}
+
+/**
+ * Every case runs on a macOS host unless it names another, because frame decoding is Apple tooling
+ * and the unit lane also runs on Linux.
+ */
+type BuildInput = Partial<
+  Omit<Parameters<typeof buildRecordingContactSheet>[0], 'videoPath' | 'hostPlatform'>
+> & { hostPlatform?: NodeJS.Platform };
+
+function build(videoPath: string, input: BuildInput = {}) {
+  return buildRecordingContactSheet({
+    ...input,
+    videoPath,
+    maxPixels: input.maxPixels ?? 20_000_000,
+    changedPixelThreshold: input.changedPixelThreshold ?? 0.1,
+    hostPlatform: input.hostPlatform ?? 'darwin',
+  });
+}
+
+async function reasonOf(action: () => Promise<unknown>): Promise<unknown> {
+  try {
+    await action();
+  } catch (error) {
+    return error instanceof AppError ? error.details?.reason : error;
+  }
+  return 'no error thrown';
+}
+
+describe('buildRecordingContactSheet', () => {
+  beforeEach(() => {
+    mockRunCmd.mockReset();
+  });
+
+  test('writes the sheet beside the recording and says what it covered', async () => {
+    const video = recording('cover', 1_000);
+    answerForGrid({ timesMs: [0, 250, 500, 750, 1000], changedMs: [500] });
+
+    const sheet = await build(video);
+
+    expect(sheet.path).toBe(recordingContactSheetPath(video));
+    expect(fs.existsSync(sheet.path)).toBe(true);
+    expect(sheet.videoPath).toBe(video);
+    expect(sheet.durationMs).toBe(1_000);
+    expect(sheet.sampledFrameCount).toBe(5);
+    expect(sheet.decodedFrameCount).toBe(5);
+    expect(sheet.skippedSampleCount).toBe(0);
+    // 750 returns to the opening screen, which is a change against the frame kept before it.
+    expect(sheet.cells.map((cell) => cell.timeMs)).toEqual([0, 500, 750, 1000]);
+    expect(sheet.warning).toBeUndefined();
+
+    const decoded = decodePng(fs.readFileSync(sheet.path), 'sheet');
+    expect([decoded.width, decoded.height]).toEqual([sheet.width, sheet.height]);
+    expect(
+      [...fs.readdirSync(directory)].some(
+        (name) => name.endsWith('.writing') || name.endsWith('.tmp'),
+      ),
+    ).toBe(false);
+  });
+
+  test('honours an explicit output path', async () => {
+    const video = recording('explicit', 500);
+    const outputPath = path.join(directory, 'named', 'sheet.png');
+    answerForGrid({ timesMs: [0, 250, 500], changedMs: [250] });
+
+    const sheet = await build(video, { outputPath });
+
+    expect(sheet.path).toBe(outputPath);
+    expect(fs.existsSync(outputPath)).toBe(true);
+  });
+
+  test('keeps one cell when the recorded screen never changed', async () => {
+    const video = recording('static', 500);
+    answerForGrid({ timesMs: [0, 250, 500] });
+
+    const sheet = await build(video);
+
+    expect(sheet.cells).toHaveLength(2);
+    expect(sheet.cells.at(-1)).toMatchObject({ timeMs: 500, changedPixelRatio: 0 });
+  });
+
+  test('discloses the sample times the decoder declined', async () => {
+    const video = recording('skipped', 1_000);
+    answerForGrid({
+      timesMs: [0, 250, 500, 750, 1000],
+      presentMs: [0, 750, 1000],
+      changedMs: [750],
+    });
+
+    const sheet = await build(video);
+
+    expect(sheet.sampledFrameCount).toBe(5);
+    expect(sheet.decodedFrameCount).toBe(3);
+    expect(sheet.skippedSampleCount).toBe(2);
+    expect(sheet.warning).toMatch(/2 sample times returned no frame/);
+  });
+
+  test('refuses a WebM recording rather than decoding nothing and calling it a sheet', async () => {
+    const webm = path.join(directory, 'web.webm');
+    fs.writeFileSync(webm, likelyPlayableWebmContainer());
+
+    const error = await build(webm).catch((error: unknown) => error);
+
+    expect(error).toBeInstanceOf(AppError);
+    expect((error as AppError).details?.reason).toBe(CONTACT_SHEET_CONTAINER_REASON);
+    expect((error as AppError).message).toMatch(/WebM/);
+  });
+
+  test('refuses a file that is not a readable MP4', async () => {
+    const notAVideo = path.join(directory, 'broken.mp4');
+    fs.writeFileSync(notAVideo, 'not a video at all');
+
+    expect(await reasonOf(() => build(notAVideo))).toBe(CONTACT_SHEET_CONTAINER_REASON);
+  });
+
+  test('refuses a clip whose timeline the container cannot name', async () => {
+    expect(await reasonOf(() => build(recording('no-duration', -1)))).toBe(
+      CONTACT_SHEET_DURATION_REASON,
+    );
+  });
+
+  test('surfaces a failed extraction and writes no sheet', async () => {
+    const video = recording('extraction-fails', 1_000);
+    mockRunCmd.mockImplementation(async (_cmd, args) =>
+      writeDecodedFrames({
+        args: args as string[],
+        framesByRequestedTimeMs: new Map(),
+        failWithExitCode: 1,
+      }),
+    );
+
+    expect(await reasonOf(() => build(video))).toBe(CONTACT_SHEET_EXTRACTION_REASON);
+    expect(fs.existsSync(recordingContactSheetPath(video))).toBe(false);
+  });
+
+  test('refuses to try on a host with no frame decoder', async () => {
+    const video = recording('unsupported-host', 1_000);
+
+    expect(await reasonOf(() => build(video, { hostPlatform: 'linux' }))).toBe(
+      CONTACT_SHEET_UNSUPPORTED_HOST_REASON,
+    );
+    expect(mockRunCmd).not.toHaveBeenCalled();
+  });
+
+  test('draws the sheet on a decoded frame whatever the source pixels were', async () => {
+    const video = recording('pixels', 250);
+    const byRequestedTime = new Map<number, StubFrame>([
+      [0, { png: solidPng(8, 8, WHITE), actualTimeMs: 0 }],
+    ]);
+    mockRunCmd.mockImplementation(async (_cmd, args) =>
+      writeDecodedFrames({ args: args as string[], framesByRequestedTimeMs: byRequestedTime }),
+    );
+
+    const sheet = await build(video);
+    const decoded = decodePng(fs.readFileSync(sheet.path), 'sheet');
+
+    let white = 0;
+    for (let offset = 0; offset < decoded.data.length; offset += 4) {
+      if (decoded.data[offset] === 255 && decoded.data[offset + 1] === 255) white += 1;
+    }
+    expect(white).toBeGreaterThan(0);
+  });
+
+  test('refuses to write the sheet where the recording it describes is', async () => {
+    const video = recording('collision', 1_000);
+
+    expect(await reasonOf(() => build(video, { outputPath: video }))).toBe(
+      CONTACT_SHEET_OUTPUT_COLLISION_REASON,
+    );
+    // Refused before the decoder ran, so a mistyped --out cannot cost a ruined recording.
+    expect(mockRunCmd).not.toHaveBeenCalled();
+    expect(fs.readFileSync(video).length).toBeGreaterThan(0);
+  });
+
+  test('refuses an output path that reaches the recording through a second name', async () => {
+    const video = recording('aliased', 1_000);
+    const symlink = path.join(path.dirname(video), 'sheet-of-my-recording.mp4');
+    const hardLink = path.join(path.dirname(video), 'recording-copy.mp4');
+    fs.symlinkSync(video, symlink);
+    fs.linkSync(video, hardLink);
+
+    for (const outputPath of [symlink, hardLink]) {
+      expect(await reasonOf(() => build(video, { outputPath }))).toBe(
+        CONTACT_SHEET_OUTPUT_COLLISION_REASON,
+      );
+    }
+    // Neither alias was opened for writing, so the recording is still whole behind both names.
+    expect(mockRunCmd).not.toHaveBeenCalled();
+    expect(fs.readFileSync(video).length).toBe(fs.statSync(hardLink).size);
+  });
+
+  test('refuses a decoded frame too large for the sheet it was meant to fill', async () => {
+    const video = recording('oversized', 250);
+    mockRunCmd.mockImplementation(async (_cmd, args) =>
+      writeDecodedFrames({
+        args: args as string[],
+        framesByRequestedTimeMs: new Map([
+          [0, { png: solidPng(16, 16, BLACK), actualTimeMs: 0 }],
+          [250, { png: solidPng(16, 16, BLACK), actualTimeMs: 250 }],
+        ]),
+      }),
+    );
+
+    expect(await reasonOf(() => build(video, { maxPixels: 100 }))).toBe(
+      CONTACT_SHEET_EXTRACTION_REASON,
+    );
+  });
+
+  test('refuses a wider frame than the cells the decoder was asked to draw', async () => {
+    const video = recording('wide', 250);
+    mockRunCmd.mockImplementation(async (_cmd, args) =>
+      writeDecodedFrames({
+        args: args as string[],
+        framesByRequestedTimeMs: new Map([
+          [0, { png: solidPng(400, 40, BLACK), actualTimeMs: 0 }],
+          [250, { png: solidPng(400, 40, BLACK), actualTimeMs: 250 }],
+        ]),
+      }),
+    );
+
+    expect(await reasonOf(() => build(video))).toBe(CONTACT_SHEET_EXTRACTION_REASON);
+  });
+
+  test('refuses a sheet the pixel budget cannot hold and leaves nothing at the output', async () => {
+    const video = recording('budget', 1_000);
+    const out = path.join(directory, 'budget-sheet.png');
+    answerForGrid({ timesMs: [0, 250, 500, 750, 1000], changedMs: [250, 500, 750, 1000] });
+
+    expect(await reasonOf(() => build(video, { outputPath: out, maxPixels: 200 }))).toBe(
+      CONTACT_SHEET_PIXEL_BUDGET_REASON,
+    );
+    expect(fs.existsSync(out)).toBe(false);
+    expect(fs.readdirSync(directory).filter((name) => name.endsWith('.writing'))).toEqual([]);
+  });
+
+  test('replaces a sheet that is already at the output path', async () => {
+    const video = recording('replace', 1_000);
+    const out = path.join(directory, 'replace-sheet.png');
+    fs.writeFileSync(out, 'a sheet from an earlier run');
+    answerForGrid({ timesMs: [0, 250, 500, 750, 1000], changedMs: [500] });
+
+    const sheet = await build(video, { outputPath: out });
+
+    expect(sheet.path).toBe(out);
+    expect(fs.readFileSync(out).subarray(1, 4).toString()).toBe('PNG');
+  });
+});
diff --git a/packages/capture-kit/src/recording/contact-sheet.ts b/packages/capture-kit/src/recording/contact-sheet.ts
new file mode 100644
index 0000000000..8510a73401
--- /dev/null
+++ b/packages/capture-kit/src/recording/contact-sheet.ts
@@ -0,0 +1,244 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {
+  CONTACT_SHEET_CONTAINER_REASON,
+  CONTACT_SHEET_EXTRACTION_REASON,
+  CONTACT_SHEET_OUTPUT_COLLISION_REASON,
+  CONTACT_SHEET_OUTPUT_WRITE_REASON,
+  type RecordingContactSheetCell,
+  type RecordingContactSheetResult,
+} from './contact-sheet-report.ts';
+import { publishFileSync } from '@agent-device/host-kit/file';
+import { AppError, createRequestCanceledError } from '@agent-device/kernel/errors';
+import { decodePngAsync } from '../png-worker-client.ts';
+import { readPngSize } from '../png-size.ts';
+import { recordingContactSheetPath } from './artifact-paths.ts';
+import {
+  assertContactSheetHostSupport,
+  extractRecordingFrames,
+  type ExtractedRecordingFrames,
+} from './contact-sheet-frames.ts';
+import { CONTACT_SHEET_FRAME_WIDTH, planContactSheetSampleTimes } from './contact-sheet-plan.ts';
+import { renderContactSheet } from './contact-sheet-render.ts';
+import {
+  CONTACT_SHEET_CHANGED_PIXEL_THRESHOLD,
+  MAX_CONTACT_SHEET_CELLS,
+  selectContactSheetCells,
+  type ContactSheetSample,
+} from './contact-sheet-selection.ts';
+import { readMp4DurationMs } from './mp4-duration.ts';
+import { readVideoContainerKind } from './video.ts';
+
+export { recordingContactSheetPath };
+
+/**
+ * Builds the one PNG that lets a caller read a recording without playing it.
+ *
+ * Frames come out of the finished export, never from a parallel capture: the sheet is drawn from
+ * the same bytes the caller was handed, so it cannot describe a screen the delivered video does not
+ * contain. The grid it samples is bounded by the sheet, not by the clip's length.
+ */
+export async function buildRecordingContactSheet(
+  input: Readonly<{
+    videoPath: string;
+    outputPath?: string;
+    maxPixels: number;
+    changedPixelThreshold?: number;
+    hostPlatform?: NodeJS.Platform;
+    signal?: AbortSignal;
+  }>,
+): Promise<RecordingContactSheetResult> {
+  assertContactSheetHostSupport(input.hostPlatform ?? process.platform);
+  const videoPath = path.resolve(input.videoPath);
+  const outputPath = path.resolve(input.outputPath ?? recordingContactSheetPath(videoPath));
+  assertOutputDoesNotReplaceRecording(videoPath, outputPath);
+
+  const container = await readVideoContainerKind(videoPath);
+  if (container !== 'mp4') {
+    throw new AppError(
+      'INVALID_ARGS',
+      container === 'webm'
+        ? `Contact sheets need an MP4 recording; ${videoPath} is WebM, whose frames this decoder does not read`
+        : `Contact sheets need an MP4 recording; ${videoPath} is not a readable MP4`,
+      {
+        reason: CONTACT_SHEET_CONTAINER_REASON,
+        videoPath,
+        container: container ?? 'unknown',
+        hint: 'Re-record on a backend that exports MP4, or pass the MP4 artifact the recording produced.',
+      },
+    );
+  }
+
+  const grid = planContactSheetSampleTimes(readMp4DurationMs(videoPath), videoPath);
+  const scratchDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-contact-sheet-'));
+  try {
+    const extracted = await extractRecordingFrames({
+      videoPath,
+      scratchDir,
+      timesMs: grid.timesMs,
+      maxWidth: CONTACT_SHEET_FRAME_WIDTH,
+      hostPlatform: input.hostPlatform ?? process.platform,
+      ...(input.signal === undefined ? {} : { signal: input.signal }),
+    });
+    const samples = await decodeFrameSamples(extracted.frames, input.maxPixels);
+    throwIfCanceled(input.signal);
+    const selection = selectContactSheetCells(
+      samples,
+      input.changedPixelThreshold ?? CONTACT_SHEET_CHANGED_PIXEL_THRESHOLD,
+    );
+    const sheet = renderContactSheet({ cells: selection.cells, maxPixels: input.maxPixels });
+    writeContactSheetFile(outputPath, sheet.bytes);
+
+    return {
+      path: outputPath,
+      videoPath,
+      durationMs: grid.durationMs,
+      width: sheet.width,
+      height: sheet.height,
+      sampledFrameCount: grid.timesMs.length,
+      decodedFrameCount: extracted.frames.length,
+      skippedSampleCount: extracted.skippedSampleCount,
+      changedPixelThreshold: input.changedPixelThreshold ?? CONTACT_SHEET_CHANGED_PIXEL_THRESHOLD,
+      cells: selection.cells.map(toCellSummary),
+      ...joinContactSheetWarnings(selection, extracted),
+    };
+  } finally {
+    fs.rmSync(scratchDir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Decodes what the decoder handed over, refusing any frame that is bigger than the whole sheet it
+ * is meant to fill. The sheet's pixel budget is the caller's ceiling on this command's memory, and
+ * a decoder asked for 360px-wide cells that returns something else broke the contract.
+ */
+async function decodeFrameSamples(
+  frames: ExtractedRecordingFrames['frames'],
+  maxPixels: number,
+): Promise<readonly ContactSheetSample[]> {
+  const samples: ContactSheetSample[] = [];
+  for (const frame of frames) {
+    const size = await readPngSize(frame.path);
+    if (size.width > CONTACT_SHEET_FRAME_WIDTH) {
+      throw new AppError(
+        'COMMAND_FAILED',
+        `Frame extraction returned a ${size.width}px-wide frame when the sheet asked for ${CONTACT_SHEET_FRAME_WIDTH}px cells`,
+        {
+          reason: CONTACT_SHEET_EXTRACTION_REASON,
+          framePath: frame.path,
+          frameWidth: size.width,
+          frameWidthLimit: CONTACT_SHEET_FRAME_WIDTH,
+        },
+      );
+    }
+    if (size.width * size.height > maxPixels) {
+      throw new AppError(
+        'COMMAND_FAILED',
+        `Frame extraction returned a ${size.width}x${size.height} frame, above the ${maxPixels}-pixel budget for the whole sheet`,
+        {
+          reason: CONTACT_SHEET_EXTRACTION_REASON,
+          framePath: frame.path,
+          framePixels: size.width * size.height,
+          maxPixels,
+        },
+      );
+    }
+    const image = await decodePngAsync(fs.readFileSync(frame.path), 'recording frame');
+    samples.push({ timeMs: frame.actualTimeMs, image });
+  }
+  return samples;
+}
+
+function throwIfCanceled(signal: AbortSignal | undefined): void {
+  if (signal?.aborted) throw createRequestCanceledError();
+}
+
+/**
+ * A sheet is derived from the recording, so it can never be the thing the recording becomes. The
+ * check runs before any decoding so a mistyped --out cannot cost a failed sheet on top of the
+ * recording it was pointing at.
+ *
+ * Resolved path strings cannot answer this on their own: a case-insensitive volume spells the same
+ * file two ways, and a hard link or symlink names it from a second path entirely. So an output that
+ * already exists is compared by the file it opens, and only an output that does not exist yet —
+ * where there is no file to open — falls back to comparing the names.
+ */
+function assertOutputDoesNotReplaceRecording(videoPath: string, outputPath: string): void {
+  const collides = existingFileIdentity(videoPath, outputPath) ?? outputPath === videoPath;
+  if (!collides) return;
+  throw new AppError(
+    'INVALID_ARGS',
+    `A contact sheet cannot be written over the recording it describes: ${outputPath}`,
+    {
+      reason: CONTACT_SHEET_OUTPUT_COLLISION_REASON,
+      videoPath,
+      outputPath,
+      hint: 'Choose a different --out path, or omit it to write beside the recording.',
+    },
+  );
+}
+
+/** Whether both paths open the same file, or `undefined` while one of them opens nothing. */
+function existingFileIdentity(left: string, right: string): boolean | undefined {
+  const leftStats = statExisting(left);
+  const rightStats = statExisting(right);
+  if (leftStats === undefined || rightStats === undefined) return undefined;
+  return leftStats.dev === rightStats.dev && leftStats.ino === rightStats.ino;
+}
+
+function statExisting(target: string): fs.Stats | undefined {
+  try {
+    return fs.statSync(target);
+  } catch {
+    return undefined;
+  }
+}
+
+function toCellSummary(cell: {
+  timeMs: number;
+  changedPixelRatio: number;
+}): RecordingContactSheetCell {
+  return { timeMs: cell.timeMs, changedPixelRatio: cell.changedPixelRatio };
+}
+
+/**
+ * Discloses what the grid did not show rather than letting a full-looking sheet imply completeness.
+ */
+function joinContactSheetWarnings(
+  selection: ReturnType<typeof selectContactSheetCells>,
+  extracted: ExtractedRecordingFrames,
+): { warning?: string } {
+  const warnings: string[] = [];
+  if (extracted.skippedSampleCount > 0) {
+    warnings.push(
+      `${extracted.skippedSampleCount} sample times returned no frame, so the sheet covers less of the recording than it asked for`,
+    );
+  }
+  if (selection.thinned) {
+    warnings.push(
+      `${selection.keptCellCount} changes were found and ${MAX_CONTACT_SHEET_CELLS} cells are printed, so the sheet thins evenly across the recording instead of showing every change`,
+    );
+  }
+  return warnings.length === 0 ? {} : { warning: warnings.join('; ') };
+}
+
+/**
+ * Publishes the sheet in one move, so a caller can never read a half-written PNG.
+ *
+ * The staging, the exclusive temp name, and the rename belong to the host's atomic publisher; this
+ * only makes sure a directory exists for the sheet it was asked to write and answers a failed write
+ * with the reason the command documents.
+ */
+function writeContactSheetFile(outputPath: string, bytes: Buffer): void {
+  try {
+    fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+    publishFileSync({ destination: outputPath, contents: bytes });
+  } catch (error) {
+    throw new AppError(
+      'COMMAND_FAILED',
+      `Failed to write the contact sheet to ${outputPath}: ${error instanceof Error ? error.message : String(error)}`,
+      { reason: CONTACT_SHEET_OUTPUT_WRITE_REASON, outputPath },
+    );
+  }
+}
diff --git a/packages/capture-kit/src/recording/video.ts b/packages/capture-kit/src/recording/video.ts
index 16e9f13e79..adf1ca25b6 100644
--- a/packages/capture-kit/src/recording/video.ts
+++ b/packages/capture-kit/src/recording/video.ts
@@ -68,7 +68,7 @@ export async function waitForStableFile(
 }
 
 export async function isPlayableVideo(filePath: string): Promise<boolean> {
-  const container = await likelyPlayableVideoContainer(filePath);
+  const container = await readVideoContainerKind(filePath);
   if (!container) return false;
   // AVFoundation is the MP4 semantic validator. It does not reliably load WebM on supported
   // macOS hosts, so WebM completion is established by its EBML document type + Segment marker.
@@ -146,10 +146,17 @@ function isSwiftVideoValidatorUnavailable(stderr: string, stdout: string): boole
  * spawns nothing, which is what lets a stop check a copy before it trusts it (ADR 0024 2.3).
  */
 export async function hasVideoContainer(filePath: string): Promise<boolean> {
-  return (await likelyPlayableVideoContainer(filePath)) !== undefined;
+  return (await readVideoContainerKind(filePath)) !== undefined;
 }
 
-async function likelyPlayableVideoContainer(filePath: string): Promise<'mp4' | 'webm' | undefined> {
+/**
+ * Which video container a file actually is, sniffed from its bytes rather than its name. Callers
+ * that can only decode one container ask this before they spawn a decoder, because a `.mp4` that
+ * is not an MP4 and a WebM that is named well both answer differently.
+ */
+export async function readVideoContainerKind(
+  filePath: string,
+): Promise<'mp4' | 'webm' | undefined> {
   try {
     const stats = fs.statSync(filePath);
     if (!stats.isFile() || stats.size <= 0) {
diff --git a/packages/host-kit/src/internal/atomic-file.test.ts b/packages/host-kit/src/internal/atomic-file.test.ts
new file mode 100644
index 0000000000..a35f010209
--- /dev/null
+++ b/packages/host-kit/src/internal/atomic-file.test.ts
@@ -0,0 +1,45 @@
+import { describe, expect, test } from 'vitest';
+import fs from 'node:fs';
+import path from 'node:path';
+import { mkdtempForTestSync } from './tmp-dir.fixtures.ts';
+import { publishFileSync } from './atomic-file.ts';
+
+const directory = mkdtempForTestSync('host-kit-atomic-file-');
+
+function destination(name: string): string {
+  return path.join(directory, name);
+}
+
+describe('publishFileSync', () => {
+  test('writes text as UTF-8', () => {
+    const target = destination('note.json');
+    publishFileSync({ destination: target, contents: '{"ok":true,"mark":"é"}' });
+
+    expect(fs.readFileSync(target, 'utf8')).toBe('{"ok":true,"mark":"é"}');
+  });
+
+  test('writes bytes exactly as the caller built them', () => {
+    // PNG magic plus bytes a UTF-8 round trip would not hand back unchanged.
+    const bytes = Uint8Array.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0xc3, 0x28]);
+    const target = destination('sheet.png');
+    publishFileSync({ destination: target, contents: bytes });
+
+    expect([...fs.readFileSync(target)]).toEqual([...bytes]);
+  });
+
+  test('replaces what was already published at the destination', () => {
+    const target = destination('replaced.txt');
+    publishFileSync({ destination: target, contents: 'first' });
+    publishFileSync({ destination: target, contents: Uint8Array.from([2, 3, 4]) });
+
+    expect([...fs.readFileSync(target)]).toEqual([2, 3, 4]);
+  });
+
+  test('leaves no staging file beside what it published', () => {
+    const target = destination('clean.txt');
+    publishFileSync({ destination: target, contents: 'body' });
+
+    const siblings = fs.readdirSync(directory).filter((name) => name.startsWith('clean.txt.'));
+    expect(siblings).toEqual([]);
+  });
+});
diff --git a/packages/host-kit/src/internal/atomic-file.ts b/packages/host-kit/src/internal/atomic-file.ts
index 1d91a615e8..3df81e87ec 100644
--- a/packages/host-kit/src/internal/atomic-file.ts
+++ b/packages/host-kit/src/internal/atomic-file.ts
@@ -8,25 +8,25 @@ export type AtomicPublishMode = 'replace' | 'link-exclusive';
 /**
  * Publishes a complete file from a same-directory temporary sibling.
  *
+ * Contents are either UTF-8 text or bytes: an encoding is only ever passed when the caller handed
+ * over text, so a PNG or a video chunk reaches the disk exactly as the caller built it.
+ *
  * The temporary file is always removed after the publish attempt. Cleanup is
  * best effort and never replaces the write or publish error; when a request
  * diagnostics scope exists, a cleanup failure is retained as secondary evidence.
  */
 export function publishFileSync(options: {
   destination: string;
-  contents: string;
+  contents: string | Uint8Array;
   mode?: number;
   publish?: AtomicPublishMode;
 }): void {
   withAtomicPublishTempPathSync(options.destination, (temporaryPath) => {
-    if (options.mode === undefined) {
-      fs.writeFileSync(temporaryPath, options.contents, 'utf8');
-    } else {
-      fs.writeFileSync(temporaryPath, options.contents, {
-        encoding: 'utf8',
-        mode: options.mode,
-      });
-    }
+    const writeOptions = {
+      encoding: typeof options.contents === 'string' ? ('utf8' as const) : undefined,
+      ...(options.mode === undefined ? {} : { mode: options.mode }),
+    };
+    fs.writeFileSync(temporaryPath, options.contents, writeOptions);
     if (options.publish === 'link-exclusive') {
       fs.linkSync(temporaryPath, options.destination);
     } else {

From 9d6291f0f821acb67ce1a3f633563f333e817670 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Tue, 22 Sep 2026 13:08:20 +0200
Subject: [PATCH 013/132] feat(cli): read a recording with record contact-sheet
 (#2747)

* feat(cli): read a recording with record contact-sheet

* chore(gates): publish the contact-sheet capture-kit facade
---
 .fallowrc.json                                |   3 +-
 docs/agents/cli-flags.md                      |   6 +
 packages/capture-kit/package.json             |   4 +
 .../src/recording/contact-sheet-report.ts     |   2 +
 .../src/recording/contact-sheet.ts            |   9 +
 .../command-registry/src/command-schema.ts    |  11 +
 packages/kernel/src/contracts.ts              |   1 +
 scripts/__tests__/eager-closure-budgets.ts    |   9 +-
 scripts/layering/package-boundaries.test.ts   |   1 +
 src/cli/commands/__tests__/recording.test.ts  |  48 ++++
 src/cli/commands/recording.ts                 |  64 +++++
 src/cli/commands/router.ts                    |   1 +
 .../parser/__tests__/args-validation.test.ts  |  59 +++++
 src/cli/parser/args.ts                        |  44 ++++
 src/cli/resolve-cli-options.test.ts           |  40 +++
 src/commands/recording/index.test.ts          |  12 +
 src/commands/recording/index.ts               |  33 ++-
 .../recording/runtime/contact-sheet.test.ts   | 214 ++++++++++++++++
 .../recording/runtime/contact-sheet.ts        | 132 ++++++++++
 src/commands/recording/runtime/index.ts       |  10 +
 src/commands/schema/cli-help.ts               |   1 +
 .../recording-contact-sheet.test.ts           | 238 ++++++++++++++++++
 test/wire-compat/ledger.json                  |   6 +-
 website/docs/docs/commands.md                 |   3 +
 24 files changed, 940 insertions(+), 11 deletions(-)
 create mode 100644 src/cli/commands/__tests__/recording.test.ts
 create mode 100644 src/cli/commands/recording.ts
 create mode 100644 src/cli/resolve-cli-options.test.ts
 create mode 100644 src/commands/recording/runtime/contact-sheet.test.ts
 create mode 100644 src/commands/recording/runtime/contact-sheet.ts
 create mode 100644 test/integration/recording-contact-sheet.test.ts

diff --git a/.fallowrc.json b/.fallowrc.json
index 84cd610a37..ebe7cf1436 100644
--- a/.fallowrc.json
+++ b/.fallowrc.json
@@ -217,7 +217,7 @@
     },
     {
       "comment": "Dedicated CLI command handlers are reached only through the dynamic `import()` table `dedicatedCliCommandHandlerLoaders` in src/cli/commands/router.ts, which --production analysis cannot follow to a consumer. Same shape as the daemon route-handler entry above; that table is what enumerates this list, so add/remove here whenever a loader is added/removed.",
-      "file": "src/cli/commands/{auth,connection,daemon,device,proxy,replay,screenshot,takeover}.ts",
+      "file": "src/cli/commands/{auth,connection,daemon,device,proxy,recording,replay,screenshot,takeover}.ts",
       "exports": [
         "authCommand",
         "connectCommand",
@@ -226,6 +226,7 @@
         "daemonCommand",
         "deviceCommand",
         "proxyCommand",
+        "recordingCommand",
         "replayCommand",
         "screenshotCommand",
         "diffCommand",
diff --git a/docs/agents/cli-flags.md b/docs/agents/cli-flags.md
index 56b0c3662c..0291f5531c 100644
--- a/docs/agents/cli-flags.md
+++ b/docs/agents/cli-flags.md
@@ -51,6 +51,12 @@ steps 1-3, plus step 9.
   everything in `allowedFlags`. Keep a cross-cutting opt-in out of every synopsis with
   `usageHidden: true` on its flag definition. `src/commands/schema/usage.test.ts` fails a tail that names
   an option the command does not accept, or one the hand-written grammar already wrote.
+- A command whose first positional picks an action declares `flagsByAction` on its CLI schema, mapping
+  each action to the options it reads, and derives `allowedFlags` from that table. The parser then
+  refuses a typed option its action never reads, off the keys the caller provided: config, env, and
+  remote-config defaults fill `flags` without becoming a request, so `AGENT_DEVICE_FPS=30` never breaks
+  `record stop`. Keep an option every action reads out of the table — a row list is the only set the
+  parser refuses, and refusing `--json` would refuse the command.
 - Command-specific usage/flag metadata lives with the command family metadata that owns the command.
 - Parser/help *rendering* stays in `src/cli/parser/`; command schema metadata is derived from command
   metadata, family declarations, and the schema-only merge path in
diff --git a/packages/capture-kit/package.json b/packages/capture-kit/package.json
index 139662c3d2..f22fb90cc9 100644
--- a/packages/capture-kit/package.json
+++ b/packages/capture-kit/package.json
@@ -166,6 +166,10 @@
       "types": "./src/recording/artifact.fixtures.ts",
       "default": "./src/recording/artifact.fixtures.ts"
     },
+    "./recording-contact-sheet": {
+      "types": "./src/recording/contact-sheet.ts",
+      "default": "./src/recording/contact-sheet.ts"
+    },
     "./recording-facts": {
       "types": "./src/recording/recording-facts.ts",
       "default": "./src/recording/recording-facts.ts"
diff --git a/packages/capture-kit/src/recording/contact-sheet-report.ts b/packages/capture-kit/src/recording/contact-sheet-report.ts
index cfbd653551..6647c10240 100644
--- a/packages/capture-kit/src/recording/contact-sheet-report.ts
+++ b/packages/capture-kit/src/recording/contact-sheet-report.ts
@@ -21,6 +21,8 @@ export const CONTACT_SHEET_CONTAINER_REASON = 'contact_sheet_container_unsupport
 export const CONTACT_SHEET_OUTPUT_WRITE_REASON = 'contact_sheet_output_write_failed';
 /** The output resolves to the recording itself, which a sheet must never replace. */
 export const CONTACT_SHEET_OUTPUT_COLLISION_REASON = 'contact_sheet_output_collides_with_input';
+/** The change threshold is not a finite share between 0 and 1. */
+export const CONTACT_SHEET_THRESHOLD_REASON = 'contact_sheet_threshold_invalid';
 
 export type RecordingContactSheetCell = {
   /** Presentation time of the decoded frame this cell shows, in milliseconds from the clip start. */
diff --git a/packages/capture-kit/src/recording/contact-sheet.ts b/packages/capture-kit/src/recording/contact-sheet.ts
index 8510a73401..131f9859f2 100644
--- a/packages/capture-kit/src/recording/contact-sheet.ts
+++ b/packages/capture-kit/src/recording/contact-sheet.ts
@@ -32,6 +32,15 @@ import { readVideoContainerKind } from './video.ts';
 
 export { recordingContactSheetPath };
 
+/**
+ * Publishes what a caller has to name to read the answer: the report the pipeline returns, and the one
+ * refusal reason a caller can act on by retrying with another threshold. Every other reason already
+ * travels on the error the pipeline threw, so it stays in the module that raises it until some surface
+ * asks for it by name.
+ */
+export { CONTACT_SHEET_THRESHOLD_REASON } from './contact-sheet-report.ts';
+export type { RecordingContactSheetResult } from './contact-sheet-report.ts';
+
 /**
  * Builds the one PNG that lets a caller read a recording without playing it.
  *
diff --git a/packages/command-registry/src/command-schema.ts b/packages/command-registry/src/command-schema.ts
index c4e03c1fd4..50ab6793eb 100644
--- a/packages/command-registry/src/command-schema.ts
+++ b/packages/command-registry/src/command-schema.ts
@@ -10,6 +10,17 @@ export type CommandSchema = {
   positionalArgs?: readonly string[];
   allowsExtraPositionals?: boolean;
   allowedFlags?: readonly FlagKey[];
+  /**
+   * For a command whose first positional selects an action: the options that action reads.
+   *
+   * `allowedFlags` is command-wide, because the parser does not know actions, so every option the
+   * command declares reaches every one of its actions. An option the action never reads is then
+   * dropped without a word: `record start --out take.mp4` looks like it recorded there, and
+   * `record contact-sheet clip.mp4 --fps 30` looks like it sampled frames. Declaring the split lets
+   * the parser refuse a typed option its action cannot read — on the keys the caller typed, never on
+   * the config, env, or remote-config defaults that also fill the flag bag.
+   */
+  flagsByAction?: Readonly<Record<string, readonly FlagKey[]>>;
   supportedFlags?: readonly FlagKey[];
   /**
    * Replaces the generated synopsis grammar in `--help`, for shapes the generator cannot express.
diff --git a/packages/kernel/src/contracts.ts b/packages/kernel/src/contracts.ts
index 3e3fedc3dc..1ef172702a 100644
--- a/packages/kernel/src/contracts.ts
+++ b/packages/kernel/src/contracts.ts
@@ -125,6 +125,7 @@ export type DaemonArtifactKnownType =
   | 'screenshot-diff'
   | 'screen-recording'
   | 'screen-recording-chunk'
+  | 'screen-recording-contact-sheet'
   | 'screen-recording-telemetry'
   | 'trace-log'
   | 'test-artifacts';
diff --git a/scripts/__tests__/eager-closure-budgets.ts b/scripts/__tests__/eager-closure-budgets.ts
index 337a4b6e5a..c59dd07e78 100644
--- a/scripts/__tests__/eager-closure-budgets.ts
+++ b/scripts/__tests__/eager-closure-budgets.ts
@@ -127,7 +127,14 @@ export const NEW_ENTRY_CEILINGS: Readonly<Record<EntryCategory, number>> = Objec
  */
 export const APPROVED_OVER_CEILING: Readonly<
   Record<string, { issue: string; reason: string; owner: string }>
-> = Object.freeze({});
+> = Object.freeze({
+  'packages/capture-kit/src/recording/contact-sheet.ts': {
+    issue: '#2747',
+    reason:
+      'Reading a recording through one PNG needs the sample grid, the frame decoder seam, and the PNG codec behind a single surface. Every module it evaluates is capture-kit mechanics, so the property the ceiling guards — no façade evaluating a concrete platform implementation — holds; only its weight is above the p75 of façades that answer a narrower question.',
+    owner: 'capture-kit',
+  },
+});
 
 /** The category is a function of the path, never a hand-written column. */
 export function entryCategoryOf(entryFile: string): EntryCategory {
diff --git a/scripts/layering/package-boundaries.test.ts b/scripts/layering/package-boundaries.test.ts
index dd3402c096..d852129882 100644
--- a/scripts/layering/package-boundaries.test.ts
+++ b/scripts/layering/package-boundaries.test.ts
@@ -423,6 +423,7 @@ test('the real tree parses, declares, and passes R11', () => {
     '@agent-device/capture-kit/quality-warnings',
     '@agent-device/capture-kit/react-native-overlay',
     '@agent-device/capture-kit/recording-artifact-fixtures',
+    '@agent-device/capture-kit/recording-contact-sheet',
     '@agent-device/capture-kit/recording-facts',
     '@agent-device/capture-kit/recording-mp4-duration',
     '@agent-device/capture-kit/recording-mp4-fixtures',
diff --git a/src/cli/commands/__tests__/recording.test.ts b/src/cli/commands/__tests__/recording.test.ts
new file mode 100644
index 0000000000..72963b7106
--- /dev/null
+++ b/src/cli/commands/__tests__/recording.test.ts
@@ -0,0 +1,48 @@
+import { describe, expect, test, vi } from 'vitest';
+import { AppError } from '@agent-device/kernel/errors';
+import type { ClientCommandParams } from '../router-types.ts';
+import { recordingCommand } from '../recording.ts';
+
+function params(positionals: string[]): ClientCommandParams {
+  return {
+    positionals,
+    flags: {} as ClientCommandParams['flags'],
+    client: {} as ClientCommandParams['client'],
+  };
+}
+
+async function failure(action: () => Promise<unknown>): Promise<unknown> {
+  try {
+    await action();
+  } catch (error) {
+    return error;
+  }
+  return 'resolved without an error';
+}
+
+describe('record contact-sheet CLI action', () => {
+  test('declines every action the generic route owns', async () => {
+    const handled = await recordingCommand({
+      ...params(['start', '/tmp/recording.mp4']),
+      client: { recording: { record: vi.fn() } } as unknown as ClientCommandParams['client'],
+    });
+
+    expect(handled).toBe(false);
+  });
+
+  test('refuses a contact sheet with no recording to read', async () => {
+    const error = await failure(() => recordingCommand(params(['contact-sheet'])));
+
+    expect(error).toBeInstanceOf(AppError);
+    expect((error as AppError).code).toBe('INVALID_ARGS');
+    expect((error as AppError).message).toMatch(/requires a recording path/);
+  });
+
+  test('refuses more than one recording path', async () => {
+    const error = await failure(() =>
+      recordingCommand(params(['contact-sheet', '/tmp/a.mp4', '/tmp/b.mp4'])),
+    );
+
+    expect((error as AppError).message).toMatch(/one recording path/);
+  });
+});
diff --git a/src/cli/commands/recording.ts b/src/cli/commands/recording.ts
new file mode 100644
index 0000000000..286abfb649
--- /dev/null
+++ b/src/cli/commands/recording.ts
@@ -0,0 +1,64 @@
+import { AppError } from '@agent-device/kernel/errors';
+import type { RecordingContactSheetCommandResult } from '../../commands/recording/runtime/contact-sheet.ts';
+import { resolveUserPath } from '@agent-device/host-kit/file';
+import { writeCommandOutput } from './shared.ts';
+import type { ClientCommandHandler } from './router-types.ts';
+
+/** The `record` action that reads a finished file locally instead of asking a device for anything. */
+const CONTACT_SHEET_ACTION = 'contact-sheet';
+
+export const recordingCommand: ClientCommandHandler = async ({ positionals, flags }) => {
+  if (positionals[0] !== CONTACT_SHEET_ACTION) return false;
+  if (positionals.length > 2) {
+    throw new AppError(
+      'INVALID_ARGS',
+      'record contact-sheet accepts one recording path: record contact-sheet <video.mp4> [--out <sheet.png>]',
+    );
+  }
+
+  const recordingPath = resolveUserPath(readRequiredPositional(positionals[1]));
+  const outputPath = typeof flags.out === 'string' ? resolveUserPath(flags.out) : undefined;
+
+  // Lazy: createAgentDevice pulls in the client-side command runtime, which only this action needs.
+  const [{ createAgentDevice, localCommandPolicy }, { createLocalArtifactAdapter }] =
+    await Promise.all([import('../../runtime.ts'), import('../../io.ts')]);
+  const runtime = createAgentDevice({
+    backend: { platform: 'ios' },
+    artifacts: createLocalArtifactAdapter(),
+    sessions: {
+      get: (name) => ({ name }),
+      set: () => {},
+    },
+    policy: localCommandPolicy(),
+  });
+
+  const result = await runtime.recording.contactSheet({
+    video: { kind: 'path', path: recordingPath },
+    ...(outputPath ? { out: { kind: 'path', path: outputPath } } : {}),
+  });
+
+  await writeCommandOutput(flags, result, () => formatContactSheetSummary(result));
+  return true;
+};
+
+function readRequiredPositional(value: string | undefined): string {
+  if (value) return value;
+  throw new AppError(
+    'INVALID_ARGS',
+    'record contact-sheet requires a recording path: record contact-sheet <video.mp4>',
+  );
+}
+
+/**
+ * Leads with the path so a caller can capture it the way it captures `record stop`, then says how
+ * much of the recording the sheet actually covers — a full grid is not the same claim as a review.
+ */
+function formatContactSheetSummary(result: RecordingContactSheetCommandResult): string {
+  const seconds = (result.durationMs / 1000).toFixed(result.durationMs % 1000 === 0 ? 0 : 1);
+  const lines = [
+    result.path,
+    `${result.cells.length} cells over ${seconds}s ` +
+      `(${result.sampledFrameCount} sample times, ${result.decodedFrameCount} frames decoded)`,
+  ];
+  return result.warning ? [...lines, result.warning].join('\n') : lines.join('\n');
+}
diff --git a/src/cli/commands/router.ts b/src/cli/commands/router.ts
index 0d717d52cf..38a7a6afd1 100644
--- a/src/cli/commands/router.ts
+++ b/src/cli/commands/router.ts
@@ -20,6 +20,7 @@ const dedicatedCliCommandHandlerLoaders = {
   replay: async () => (await import('./replay.ts')).replayCommand,
   screenshot: async () => (await import('./screenshot.ts')).screenshotCommand,
   diff: async () => (await import('./screenshot.ts')).diffCommand,
+  record: async () => (await import('./recording.ts')).recordingCommand,
 } satisfies ClientCommandHandlerMap;
 
 export async function tryRunClientBackedCommand(params: {
diff --git a/src/cli/parser/__tests__/args-validation.test.ts b/src/cli/parser/__tests__/args-validation.test.ts
index 2f729d841d..c08b39976a 100644
--- a/src/cli/parser/__tests__/args-validation.test.ts
+++ b/src/cli/parser/__tests__/args-validation.test.ts
@@ -32,6 +32,65 @@ test('parseArgs rejects invalid record --fps range', () => {
   );
 });
 
+test('parseArgs refuses a record option the chosen action never reads', () => {
+  const cases: Array<[string[], string]> = [
+    [
+      ['record', 'start', './capture.mp4', '--out', './elsewhere.mp4'],
+      'record start does not read --out',
+    ],
+    [['record', 'stop', '--fps', '30'], 'record stop does not read --fps'],
+    [['record', 'stop', '--hide-touches'], 'record stop does not read --hide-touches'],
+    [
+      ['record', 'contact-sheet', './clip.mp4', '--fps', '30'],
+      'record contact-sheet does not read --fps',
+    ],
+  ];
+
+  for (const [argv, message] of cases) {
+    assert.throws(
+      () => parseArgs(argv, { strictFlags: true }),
+      (error: unknown) =>
+        error instanceof AppError &&
+        error.code === 'INVALID_ARGS' &&
+        error.message.startsWith(message),
+      `expected ${argv.join(' ')} to be refused`,
+    );
+  }
+});
+
+test('parseArgs accepts the options each record action reads', () => {
+  const cases: string[][] = [
+    ['record', 'start', './capture.mp4', '--fps', '30', '--quality', 'high', '--hide-touches'],
+    ['record', 'stop'],
+    ['record', 'contact-sheet', './clip.mp4', '--out', './sheet.png'],
+  ];
+
+  for (const argv of cases) {
+    assert.doesNotThrow(() => parseArgs(argv, { strictFlags: true }), `expected ${argv.join(' ')}`);
+  }
+});
+
+test('parseArgs leaves an option every action reads to the command itself', () => {
+  // --json and --no-record are read whatever action follows the command name, so an action table that
+  // does not list them must not turn them into unread options.
+  for (const argv of [
+    ['record', 'stop', '--json'],
+    ['record', 'contact-sheet', './clip.mp4', '--no-record'],
+  ]) {
+    assert.doesNotThrow(() => parseArgs(argv, { strictFlags: true }), `expected ${argv.join(' ')}`);
+  }
+});
+
+test('parseArgs leaves a command without an action table to its own validation', () => {
+  // `perf` declares no action option table at all, and `record nonsense` names an action the record
+  // table never lists. Neither may be refused as an unread option here: the first is validated by its
+  // own command, and an action the table does not list belongs to the reader that owns the action list.
+  assert.doesNotThrow(() => parseArgs(['perf', 'start', './perf.json'], { strictFlags: true }));
+  assert.doesNotThrow(() =>
+    parseArgs(['record', 'nonsense', '--fps', '30'], { strictFlags: true }),
+  );
+});
+
 test('parseArgs rejects invalid swipe pattern', () => {
   assert.throws(
     () => parseArgs(['swipe', '0', '0', '10', '10', '--pattern', 'diagonal']),
diff --git a/src/cli/parser/args.ts b/src/cli/parser/args.ts
index fae48dad9a..cf7cc19230 100644
--- a/src/cli/parser/args.ts
+++ b/src/cli/parser/args.ts
@@ -197,6 +197,18 @@ export function finalizeParsedArgs(
       delete (flags as Record<string, unknown>)[entry.key];
     }
   }
+
+  const unread = findFlagsTheActionCannotRead(parsed);
+  if (unread.length > 0) {
+    const message = formatUnreadActionFlagMessage(parsed.command, parsed.positionals[0]!, unread);
+    if (strictFlags) {
+      throw new AppError('INVALID_ARGS', message);
+    }
+    warnings.push(message);
+    for (const entry of unread) {
+      delete (flags as Record<string, unknown>)[entry.key];
+    }
+  }
   for (const key of Object.keys(flags) as FlagKey[]) {
     if (flags[key] === undefined) continue;
     if (!isFlagSupportedForCommand(key, parsed.command)) {
@@ -373,6 +385,38 @@ function normalizeParsedCommandAliases(parsed: ParsedArgs): ParsedArgs {
   return parsed;
 }
 
+/**
+ * The typed options the selected action of a command cannot read.
+ *
+ * Only the options the table splits across actions are its business: a global flag such as `--json`
+ * or `--no-record` is read by every action, and refusing one would refuse the command itself. A
+ * command without the table, or an action it does not list, is left to the rest of the parser.
+ *
+ * Config, env, and remote-config defaults never appear in `providedFlags`, which is why
+ * `AGENT_DEVICE_FPS=30` does not fail `record stop`: a default the action ignores was never requested.
+ */
+function findFlagsTheActionCannotRead(parsed: RawParsedArgs): ParsedFlagRecord[] {
+  const flagsByAction = getCommandSchema(parsed.command)?.flagsByAction;
+  const action = parsed.positionals[0];
+  if (flagsByAction === undefined || action === undefined) return [];
+  if (!Object.hasOwn(flagsByAction, action)) return [];
+  const reads = flagsByAction[action];
+  if (reads === undefined) return [];
+  const actionScoped = new Set(Object.values(flagsByAction).flat());
+  return parsed.providedFlags.filter(
+    (entry) => actionScoped.has(entry.key) && !reads.includes(entry.key),
+  );
+}
+
+function formatUnreadActionFlagMessage(
+  command: string | null,
+  action: string,
+  unread: ParsedFlagRecord[],
+): string {
+  const tokens = unread.map((entry) => entry.token).join(', ');
+  return `${command} ${action} does not read ${tokens}. Run \`${command} ${action} --help\` for the options it reads.`;
+}
+
 function formatUnsupportedFlagMessage(command: string | null, unsupported: string[]): string {
   if (!command) {
     return unsupported.length === 1
diff --git a/src/cli/resolve-cli-options.test.ts b/src/cli/resolve-cli-options.test.ts
new file mode 100644
index 0000000000..31e6d293b8
--- /dev/null
+++ b/src/cli/resolve-cli-options.test.ts
@@ -0,0 +1,40 @@
+import { test } from 'vitest';
+import assert from 'node:assert/strict';
+import { mkdtempForTestSync } from '../__tests__/test-utils/tmp-dir.ts';
+import { resolveCliOptions } from './resolve-cli-options.ts';
+
+/**
+ * Points `~` at an empty directory so a developer's own ~/.agent-device/config.json cannot add
+ * defaults to what a test asserts, and keeps PATH so the rest of resolution behaves.
+ */
+function isolatedEnv(env: Record<string, string>): Record<string, string> {
+  const home = mkdtempForTestSync('agent-device-cli-env-');
+  return { HOME: home, USERPROFILE: home, PATH: process.env.PATH ?? '', ...env };
+}
+
+test('a frame rate from the environment is not a flag the caller typed', () => {
+  // `record stop` reads no recording option. A default it ignores must not become a refusal, or
+  // AGENT_DEVICE_FPS in a CI shell would break every `record stop`.
+  const parsed = resolveCliOptions(['record', 'stop'], {
+    cwd: process.cwd(),
+    env: isolatedEnv({ AGENT_DEVICE_FPS: '30' }),
+  });
+
+  assert.equal(parsed.flags.fps, 30);
+  assert.deepEqual(
+    parsed.providedFlags.map((entry) => entry.key),
+    [],
+  );
+});
+
+test('a frame rate the caller typed stays a typed flag', () => {
+  const parsed = resolveCliOptions(['record', 'start', './capture.mp4', '--fps', '30'], {
+    cwd: process.cwd(),
+    env: isolatedEnv({}),
+  });
+
+  assert.deepEqual(
+    parsed.providedFlags.map((entry) => entry.key),
+    ['fps'],
+  );
+});
diff --git a/src/commands/recording/index.test.ts b/src/commands/recording/index.test.ts
index be24156946..55be43f6c6 100644
--- a/src/commands/recording/index.test.ts
+++ b/src/commands/recording/index.test.ts
@@ -1,5 +1,6 @@
 import { describe, expect, test } from 'vitest';
 import type { CliFlags } from '@agent-device/contracts/command';
+import { getCliCommandSchema } from '../schema/command-schema.ts';
 import {
   recordCliReader,
   recordCommandFacet,
@@ -75,3 +76,14 @@ describe('recording command interface', () => {
     });
   });
 });
+
+describe('record CLI option declaration', () => {
+  test('hands the parser the table of which action reads which option', () => {
+    // The parser is what refuses an option its action cannot read, on the keys the caller typed. That
+    // holds only while this family's table reaches the schema the parser reads.
+    const reads = getCliCommandSchema('record').flagsByAction;
+
+    expect(reads?.['stop']).toEqual([]);
+    expect(reads?.['contact-sheet']).toContain('out');
+  });
+});
diff --git a/src/commands/recording/index.ts b/src/commands/recording/index.ts
index 9168864416..62435afd63 100644
--- a/src/commands/recording/index.ts
+++ b/src/commands/recording/index.ts
@@ -9,6 +9,7 @@ import {
 } from '@agent-device/contracts/recording';
 import { AppError } from '@agent-device/kernel/errors';
 import type { CommandSchemaOverride } from '@agent-device/command-registry/command-schema';
+import type { FlagKey } from '@agent-device/command-registry/flag-types';
 import { commonInputFromFlags, direct, optionalString } from '../cli-grammar/common.ts';
 import type { CliReader, DaemonWriter } from '../cli-grammar/types.ts';
 import {
@@ -28,7 +29,7 @@ const TRACE_COMMAND_NAME = 'trace';
 const RECORDING_ACTION_VALUES = ['start', 'stop'] as const;
 
 const recordCommandDescription =
-  'Start or stop a screen recording for the active app session or, where supported, the selected device. Long Android recordings can return multiple video artifacts; HarmonyOS supports whole-screen recording on physical devices.';
+  'Start or stop a screen recording for the active app session or, where supported, the selected device, or build a contact-sheet PNG from a recording already exported. Long Android recordings can return multiple video artifacts; HarmonyOS supports whole-screen recording on physical devices.';
 const traceCommandDescription =
   'Start or stop trace-log capture and return the resulting artifact when capture ends. Use the same artifact path for the matching start and stop requests when an explicit path is required.';
 
@@ -58,13 +59,33 @@ export const traceCommandMetadata = defineFieldCommandMetadata(
   },
 );
 
+/**
+ * Which `record` action reads which option.
+ *
+ * A new option has to name the action that reads it. That is what keeps one shared list from letting
+ * `record start --out take.mp4` look like it recorded to that path, and `record contact-sheet
+ * clip.mp4 --fps 30` look like frame sampling was configured. The parser is handed this table as
+ * `flagsByAction` and refuses an option the action cannot read.
+ */
+const RECORD_FLAGS_BY_ACTION: Readonly<Record<string, readonly FlagKey[]>> = {
+  start: ['recordingScope', 'fps', 'quality', 'hideTouches'],
+  // `record stop` takes a session and a target, and reads no recording option.
+  stop: [],
+  'contact-sheet': ['out'],
+};
+
+const RECORD_CLI_FLAGS: readonly FlagKey[] = [
+  ...new Set(Object.values(RECORD_FLAGS_BY_ACTION).flat()),
+];
+
 const recordCliSchema = {
   usageOverride:
-    'record start [path] [--scope <app|device|system>] [--fps <n>] [--quality <medium|high>] [--hide-touches] | record stop',
+    'record start [path] [--scope <app|device|system>] [--fps <n>] [--quality <medium|high>] [--hide-touches] | record stop | record contact-sheet <video.mp4> [--out <sheet.png>]',
   usageFlags: [],
-  listUsageOverride: 'record start [path] | record stop',
-  positionalArgs: ['start|stop', 'path?'],
-  allowedFlags: ['recordingScope', 'fps', 'quality', 'hideTouches'],
+  listUsageOverride: 'record start [path] | record stop | record contact-sheet <video>',
+  positionalArgs: ['start|stop|contact-sheet', 'path?'],
+  allowedFlags: RECORD_CLI_FLAGS,
+  flagsByAction: RECORD_FLAGS_BY_ACTION,
 } as const satisfies CommandSchemaOverride;
 
 const traceCliSchema = {
@@ -107,7 +128,7 @@ export const recordCommandFacet = defineCommandFacet({
   text: {
     summary: 'Start or stop screen recording',
     cliDetail:
-      'The default --scope app requires an active app session from open <app>; use --scope device/system to explicitly request whole-screen recording where the selected backend supports it. Android record start publishes a durable device manifest, recordings longer than the 180s adb screenrecord limit are returned as multiple MP4 chunks while the daemon stays alive, and daemon-restart recovery uses only manifest-owned chunks. Android screenrecord encodes a frame only when the screen changes, so a clip can end at the last frame the recorder encoded instead of at record stop; durationMs is host wall clock from record start until the export finished, and capturedDurationMs reports the video timeline when it can be measured, with a warning naming how much of the window that video covers. An Android manifest left by an unreachable recording is retired on the next start once its recorders are proven gone; one still owned refuses with non-retriable DEVICE_IN_USE and reason native_recovery_evidence_open naming the session to run record stop for, and a recorder that is still writing an artifact refuses with DEVICE_IN_USE and reason native_recording_artifact_claimed, which clears itself once that recorder ends at the 180s limit. HarmonyOS supports whole-screen recording on physical devices only: use --scope device/system; --fps, --quality, and --hide-touches are unsupported. Use --quality to choose medium or high export quality on supported backends. An iOS simulator host recording lock returns non-retriable DEVICE_IN_USE with reason apple_simulator_recording_busy. Stop the recording in its owning session; if a dead recorder left the host locked, ask the host operator to restart the CoreSimulator stream service. A record stop that cannot produce its export keeps what a retry reads back — on Android the device-side artifact and the native manifest — leaves the recording manifest of that session open, and returns its own error, so retry record stop in that session; only closing the session disposes them. Every stopped recording also reports what became of its recorder and of the file that recorder writes to: recorder is confirmed, or lost when the session holding it died, and nativePathDisposition is retirable while that file still owes a removal or retired once its removal was verified. Both are optional disclosures, not failures; ADR 0024 declares further states (unconfirmed, pending) for the steps that gain those probes, and no stop reports them yet.',
+      'The default --scope app requires an active app session from open <app>; use --scope device/system to explicitly request whole-screen recording where the selected backend supports it. Android record start publishes a durable device manifest, recordings longer than the 180s adb screenrecord limit are returned as multiple MP4 chunks while the daemon stays alive, and daemon-restart recovery uses only manifest-owned chunks. Android screenrecord encodes a frame only when the screen changes, so a clip can end at the last frame the recorder encoded instead of at record stop; durationMs is host wall clock from record start until the export finished, and capturedDurationMs reports the video timeline when it can be measured, with a warning naming how much of the window that video covers. An Android manifest left by an unreachable recording is retired on the next start once its recorders are proven gone; one still owned refuses with non-retriable DEVICE_IN_USE and reason native_recovery_evidence_open naming the session to run record stop for, and a recorder that is still writing an artifact refuses with DEVICE_IN_USE and reason native_recording_artifact_claimed, which clears itself once that recorder ends at the 180s limit. HarmonyOS supports whole-screen recording on physical devices only: use --scope device/system; --fps, --quality, and --hide-touches are unsupported. Use --quality to choose medium or high export quality on supported backends. An iOS simulator host recording lock returns non-retriable DEVICE_IN_USE with reason apple_simulator_recording_busy. Stop the recording in its owning session; if a dead recorder left the host locked, ask the host operator to restart the CoreSimulator stream service. A record stop that cannot produce its export keeps what a retry reads back — on Android the device-side artifact and the native manifest — leaves the recording manifest of that session open, and returns its own error, so retry record stop in that session; only closing the session disposes them. Every stopped recording also reports what became of its recorder and of the file that recorder writes to: recorder is confirmed, or lost when the session holding it died, and nativePathDisposition is retirable while that file still owes a removal or retired once its removal was verified. Both are optional disclosures, not failures; ADR 0024 declares further states (unconfirmed, pending) for the steps that gain those probes, and no stop reports them yet. record contact-sheet <video.mp4> [--out <sheet.png>] is a local report over a file you already exported: it decodes frames out of that MP4 and writes one PNG holding the cells where the screen visibly changed, each labeled with its elapsed time on the clip timeline. It needs no session and no device, rebuilds any past recording, and works for every backend that exports MP4; a WebM recording is refused with reason contact_sheet_container_unsupported. The sample grid is bounded and spread across the whole clip, so it reports coverage rather than a review: a flash that opens and closes entirely between two sample times is not in the sheet, which is why the result also reports how many times it sampled and how many frames came back. Frame decoding is Apple AVFoundation tooling, so the command runs only on macOS hosts and refuses elsewhere with reason contact_sheet_unsupported_host.',
   },
   metadata: recordCommandMetadata,
   run: (client, input) => client.recording.record(input as RecordOptions),
diff --git a/src/commands/recording/runtime/contact-sheet.test.ts b/src/commands/recording/runtime/contact-sheet.test.ts
new file mode 100644
index 0000000000..53b22fda42
--- /dev/null
+++ b/src/commands/recording/runtime/contact-sheet.test.ts
@@ -0,0 +1,214 @@
+import assert from 'node:assert/strict';
+import { beforeEach, test, vi } from 'vitest';
+import {
+  buildRecordingContactSheet,
+  CONTACT_SHEET_THRESHOLD_REASON,
+} from '@agent-device/capture-kit/recording-contact-sheet';
+import type { ArtifactAdapter, ArtifactDescriptor, FileInputRef } from '../../../io.ts';
+import {
+  createAgentDevice,
+  localCommandPolicy,
+  restrictedCommandPolicy,
+} from '../../../runtime.ts';
+
+vi.mock('@agent-device/capture-kit/recording-contact-sheet', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('@agent-device/capture-kit/recording-contact-sheet')>()),
+  buildRecordingContactSheet: vi.fn(),
+}));
+
+const mockBuild = vi.mocked(buildRecordingContactSheet);
+
+let reserved: { path: string; cleaned: boolean; published: boolean }[] = [];
+let materializedCleanups = 0;
+
+const artifacts = {
+  resolveInput: async (ref: FileInputRef) => ({
+    path: ref.kind === 'path' ? ref.path : `/tmp/uploaded/${ref.id}.mp4`,
+    cleanup:
+      ref.kind === 'uploadedArtifact'
+        ? async () => {
+            materializedCleanups += 1;
+          }
+        : undefined,
+  }),
+  reserveOutput: async (ref, options) => {
+    const path = ref?.kind === 'path' ? ref.path : `/tmp/${options.field}${options.ext}`;
+    const reservation = { path, cleaned: false, published: false };
+    reserved.push(reservation);
+    return {
+      path,
+      visibility: options.visibility ?? 'client-visible',
+      publish: async (): Promise<ArtifactDescriptor> => {
+        reservation.published = true;
+        return ref?.kind === 'path'
+          ? {
+              kind: 'localPath',
+              field: options.field,
+              artifactType: options.artifactType,
+              path,
+            }
+          : {
+              kind: 'artifact',
+              field: options.field,
+              artifactType: options.artifactType,
+              artifactId: 'artifact-1',
+              clientPath: '/Users/me/Downloads/sheet.png',
+            };
+      },
+      cleanup: async () => {
+        reservation.cleaned = true;
+      },
+    };
+  },
+  createTempFile: async (options) => ({
+    path: `/tmp/${options.prefix}${options.ext}`,
+    visibility: 'internal' as const,
+    cleanup: async () => {},
+  }),
+} satisfies ArtifactAdapter;
+
+function sheetResult(path: string) {
+  return {
+    path,
+    videoPath: '/tmp/recording.mp4',
+    durationMs: 1000,
+    width: 744,
+    height: 218,
+    sampledFrameCount: 5,
+    decodedFrameCount: 5,
+    skippedSampleCount: 0,
+    changedPixelThreshold: 0.02,
+    cells: [{ timeMs: 0, changedPixelRatio: 1 }],
+  };
+}
+
+function device(policy = localCommandPolicy()) {
+  return createAgentDevice({ backend: { platform: 'ios' }, artifacts, policy });
+}
+
+beforeEach(() => {
+  reserved = [];
+  materializedCleanups = 0;
+  mockBuild.mockReset();
+  mockBuild.mockImplementation(async (input) => sheetResult(input.outputPath ?? 'unset'));
+});
+
+test('record contact-sheet defaults to the sheet beside the recording it was given', async () => {
+  const result = await device().recording.contactSheet({
+    video: { kind: 'path', path: '/tmp/recording.mp4' },
+  });
+
+  assert.equal(mockBuild.mock.calls[0]![0].outputPath, '/tmp/recording.contact-sheet.png');
+  assert.equal(result.path, '/tmp/recording.contact-sheet.png');
+  assert.equal(result.artifact?.kind, 'localPath');
+  assert.equal(reserved[0]?.published, true);
+  assert.equal(reserved[0]?.cleaned, false);
+});
+
+test('record contact-sheet passes the pixel budget and honours an explicit output', async () => {
+  await device().recording.contactSheet({
+    video: { kind: 'path', path: '/tmp/recording.mp4' },
+    out: { kind: 'path', path: '/tmp/named/sheet.png' },
+    changedPixelThreshold: 0.2,
+  });
+
+  const input = mockBuild.mock.calls[0]![0];
+  assert.equal(input.outputPath, '/tmp/named/sheet.png');
+  assert.equal(input.maxPixels, 20_000_000);
+  assert.equal(input.changedPixelThreshold, 0.2);
+});
+
+test('record contact-sheet reports the caller-visible path of a downloaded artifact', async () => {
+  const result = await device().recording.contactSheet({
+    video: { kind: 'uploadedArtifact', id: 'rec-1' },
+    out: { kind: 'downloadableArtifact' },
+  });
+
+  assert.equal(result.path, '/Users/me/Downloads/sheet.png');
+  assert.equal(result.artifact?.kind, 'artifact');
+});
+
+test('record contact-sheet requires an output when the recording has no caller-side sibling', async () => {
+  await assert.rejects(
+    () =>
+      device().recording.contactSheet({
+        video: { kind: 'uploadedArtifact', id: 'rec-1' },
+      }),
+    /needs an output path/,
+  );
+  assert.equal(mockBuild.mock.calls.length, 0);
+  // The recording was already downloaded to answer the call, so refusing must put it back.
+  assert.equal(materializedCleanups, 1);
+});
+
+test('record contact-sheet releases a downloaded recording once the sheet fails', async () => {
+  mockBuild.mockRejectedValue(new Error('decoder refused the clip'));
+
+  await assert.rejects(
+    () =>
+      device().recording.contactSheet({
+        video: { kind: 'uploadedArtifact', id: 'rec-1' },
+        out: { kind: 'downloadableArtifact' },
+      }),
+    /decoder refused the clip/,
+  );
+
+  assert.equal(materializedCleanups, 1);
+});
+
+test('record contact-sheet refuses a change threshold that is not a share of the frame', async () => {
+  for (const changedPixelThreshold of [Number.NaN, -0.1, 1.5]) {
+    await assert.rejects(
+      () =>
+        device().recording.contactSheet({
+          video: { kind: 'path', path: '/tmp/recording.mp4' },
+          changedPixelThreshold,
+        }),
+      (error: unknown) =>
+        (error as { details?: { reason?: string } }).details?.reason ===
+        CONTACT_SHEET_THRESHOLD_REASON,
+    );
+  }
+  // Nothing is decoded for an argument that could only print every frame or none of them.
+  assert.equal(mockBuild.mock.calls.length, 0);
+});
+
+test('record contact-sheet file paths are policy-gated on both sides', async () => {
+  await assert.rejects(
+    () =>
+      device(restrictedCommandPolicy()).recording.contactSheet({
+        video: { kind: 'path', path: '/tmp/recording.mp4' },
+      }),
+    /Local video paths are not allowed by command policy/,
+  );
+  await assert.rejects(
+    () =>
+      device(localCommandPolicy({ allowLocalOutputPaths: false })).recording.contactSheet({
+        video: { kind: 'path', path: '/tmp/recording.mp4' },
+        out: { kind: 'path', path: '/tmp/sheet.png' },
+      }),
+    /Local output paths are not allowed by command policy/,
+  );
+});
+
+test('a failed sheet releases the output it reserved', async () => {
+  mockBuild.mockRejectedValue(new Error('decoder refused the clip'));
+
+  await assert.rejects(
+    () =>
+      device().recording.contactSheet({
+        video: { kind: 'path', path: '/tmp/recording.mp4' },
+      }),
+    /decoder refused the clip/,
+  );
+
+  assert.equal(reserved[0]?.cleaned, true);
+  assert.equal(reserved[0]?.published, false);
+});
+
+test('record contact-sheet needs a recording to read', async () => {
+  await assert.rejects(
+    () => device().recording.contactSheet({ video: undefined as never }),
+    /requires a recording/,
+  );
+});
diff --git a/src/commands/recording/runtime/contact-sheet.ts b/src/commands/recording/runtime/contact-sheet.ts
new file mode 100644
index 0000000000..fd0173b2d6
--- /dev/null
+++ b/src/commands/recording/runtime/contact-sheet.ts
@@ -0,0 +1,132 @@
+import path from 'node:path';
+import {
+  buildRecordingContactSheet,
+  CONTACT_SHEET_THRESHOLD_REASON,
+  recordingContactSheetPath,
+  type RecordingContactSheetResult,
+} from '@agent-device/capture-kit/recording-contact-sheet';
+import { AppError } from '@agent-device/kernel/errors';
+import type {
+  ArtifactDescriptor,
+  FileInputRef,
+  FileOutputRef,
+  ReservedOutputFile,
+} from '../../../io.ts';
+import type { CommandContext } from '../../../runtime-contract.ts';
+import type { RuntimeCommand } from '../../runtime-types.ts';
+import { reserveCommandOutput, resolveCommandInput } from '../../io-policy.ts';
+
+export type RecordingContactSheetCommandOptions = CommandContext & {
+  /** The exported recording to read. A file the caller already holds, not a live capture. */
+  video: FileInputRef;
+  out?: FileOutputRef;
+  changedPixelThreshold?: number;
+};
+
+export type RecordingContactSheetCommandResult = RecordingContactSheetResult & {
+  artifact?: ArtifactDescriptor;
+};
+
+/**
+ * Draws a contact sheet from an already exported recording.
+ *
+ * The sheet is a report over a file, so it goes through the local file policy the way a screenshot
+ * diff does: it needs no session, no device, and no daemon, and it can be rebuilt from a recording
+ * that finished yesterday.
+ */
+export const contactSheetCommand: RuntimeCommand<
+  RecordingContactSheetCommandOptions,
+  RecordingContactSheetCommandResult
+> = async (runtime, options): Promise<RecordingContactSheetCommandResult> => {
+  if (!options.video) {
+    throw new AppError('INVALID_ARGS', 'record contact-sheet requires a recording to read');
+  }
+  assertContactSheetThreshold(options.changedPixelThreshold);
+
+  const video = await resolveCommandInput(runtime, options.video, {
+    usage: 'record contact-sheet',
+    field: 'video',
+  });
+  let output: ReservedOutputFile | undefined;
+
+  try {
+    // Resolved after the input is materialized so an uploaded recording is released even when no
+    // output could be named for it.
+    const outputRef = resolveSheetOutputRef(options, options.video, video.path);
+    output = await reserveCommandOutput(runtime, outputRef, {
+      field: 'path',
+      ext: '.png',
+      artifactType: 'screen-recording-contact-sheet',
+    });
+    const sheet = await buildRecordingContactSheet({
+      videoPath: video.path,
+      outputPath: output.path,
+      maxPixels: runtime.policy.maxImagePixels,
+      ...(options.changedPixelThreshold === undefined
+        ? {}
+        : { changedPixelThreshold: options.changedPixelThreshold }),
+      signal: options.signal ?? runtime.signal,
+    });
+    const artifact = await output.publish();
+    return {
+      ...sheet,
+      path: publishedSheetPath(sheet.path, artifact),
+      ...(artifact ? { artifact } : {}),
+    };
+  } catch (error) {
+    await output?.cleanup?.();
+    throw error;
+  } finally {
+    await video.cleanup?.();
+  }
+};
+
+/**
+ * Picks where the sheet lands.
+ *
+ * A recording addressed by path gets its sibling, which is the convention every other recording
+ * report follows. A recording handed over as an uploaded artifact has no caller-visible sibling to
+ * derive, so an explicit output is required rather than a path nobody can open.
+ */
+function resolveSheetOutputRef(
+  options: RecordingContactSheetCommandOptions,
+  videoRef: FileInputRef,
+  resolvedVideoPath: string,
+): FileOutputRef {
+  if (options.out) return options.out;
+  if (videoRef.kind === 'path') {
+    return {
+      kind: 'path',
+      path: path.resolve(recordingContactSheetPath(videoRef.path || resolvedVideoPath)),
+    };
+  }
+  throw new AppError(
+    'INVALID_ARGS',
+    'record contact-sheet needs an output path when the recording is an uploaded artifact',
+    { hint: 'Pass --out <sheet.png> (CLI) or `out` (Node) to name where the sheet is written.' },
+  );
+}
+
+/**
+ * A threshold outside 0..1 is a caller mistake that would either print every sampled frame or
+ * refuse every one of them, so it is answered before any decoding is paid for.
+ */
+function assertContactSheetThreshold(threshold: number | undefined): void {
+  if (threshold === undefined) return;
+  if (!Number.isFinite(threshold) || threshold < 0 || threshold > 1) {
+    throw new AppError(
+      'INVALID_ARGS',
+      `record contact-sheet needs a changedPixelThreshold between 0 and 1, got ${threshold}`,
+      {
+        reason: CONTACT_SHEET_THRESHOLD_REASON,
+        changedPixelThreshold: threshold,
+        hint: 'Omit it to use the calibrated default, or pass a share of the frame between 0 and 1.',
+      },
+    );
+  }
+}
+
+function publishedSheetPath(sheetPath: string, artifact: ArtifactDescriptor | undefined): string {
+  if (!artifact) return sheetPath;
+  return artifact.kind === 'localPath' ? artifact.path : (artifact.clientPath ?? sheetPath);
+}
diff --git a/src/commands/recording/runtime/index.ts b/src/commands/recording/runtime/index.ts
index 3051b8da55..20fe6dfec7 100644
--- a/src/commands/recording/runtime/index.ts
+++ b/src/commands/recording/runtime/index.ts
@@ -1,4 +1,9 @@
 import type { BoundOf, RuntimeCommand } from '../../runtime-types.ts';
+import {
+  contactSheetCommand,
+  type RecordingContactSheetCommandOptions,
+  type RecordingContactSheetCommandResult,
+} from './contact-sheet.ts';
 import {
   recordCommand,
   traceCommand,
@@ -11,6 +16,10 @@ import {
 export type RecordingCommands = {
   record: RuntimeCommand<RecordingRecordCommandOptions, RecordingRecordCommandResult>;
   trace: RuntimeCommand<RecordingTraceCommandOptions, RecordingTraceCommandResult>;
+  contactSheet: RuntimeCommand<
+    RecordingContactSheetCommandOptions,
+    RecordingContactSheetCommandResult
+  >;
 };
 
 export type BoundRecordingCommands = BoundOf<RecordingCommands>;
@@ -18,4 +27,5 @@ export type BoundRecordingCommands = BoundOf<RecordingCommands>;
 export const recordingCommands: RecordingCommands = {
   record: recordCommand,
   trace: traceCommand,
+  contactSheet: contactSheetCommand,
 };
diff --git a/src/commands/schema/cli-help.ts b/src/commands/schema/cli-help.ts
index f49706c7ee..a2c5912e7e 100644
--- a/src/commands/schema/cli-help.ts
+++ b/src/commands/schema/cli-help.ts
@@ -238,6 +238,7 @@ Batch:
 
 Recording:
   record start/stop. Default scope is app (needs an active open session); use --scope device/system for whole-screen capture spanning multiple apps/home/settings. --quality medium|high on Android and Apple targets. stop burns touch overlays into the video by default; --hide-touches skips that for the fastest raw recording, and is recommended for gesture-heavy iOS simulator proof videos since overlay timing depends on a stable runner session. Android adb screenrecord has a 180s limit, so long Android recordings return as multiple MP4 chunks while the daemon stays alive; after a daemon restart, record stop recovers only manifest-owned chunks. record stop is safe to repeat: if its request window ended while the daemon was still exporting, running it again in that session returns the completed recording instead of starting a second one.
+  record contact-sheet <video.mp4> [--out <sheet.png>] reads an exported MP4 back and writes one PNG holding the frames where the screen visibly changed, each labeled with its elapsed time. It is how you read a recording you cannot play, and it needs no session or device; the frames come out of that file, so the sheet cannot describe a screen the video does not contain. The sample grid is bounded and spread over the whole clip, so it reports coverage, not a review: a flash that opens and closes between two sample times is not in it. Needs a macOS host and an MP4 (a WebM recording is refused).
   Tracing: trace start ./trace.log, trace stop ./trace.log (path is positional, not --path).`,
   },
   gestures: {
diff --git a/test/integration/recording-contact-sheet.test.ts b/test/integration/recording-contact-sheet.test.ts
new file mode 100644
index 0000000000..0d1fde63eb
--- /dev/null
+++ b/test/integration/recording-contact-sheet.test.ts
@@ -0,0 +1,238 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { createIntegrationTestContext, type CliJsonResult } from './test-helpers.ts';
+
+const recordingE2EEnabled = isTruthy(process.env.AGENT_DEVICE_RECORDING_E2E);
+
+test(
+  'record contact-sheet reads a live iOS simulator recording',
+  {
+    skip: shouldSkipContactSheetE2E(),
+  },
+  () => {
+    const testName = 'record contact-sheet';
+    const integration = createRecordingIntegrationContext('ios', testName);
+    const videoPath = path.join(integration.artifactDir(), 'contact-sheet.mp4');
+    const sheetPath = path.join(integration.artifactDir(), 'contact-sheet.png');
+    const session = ['--session', 'recording-ios-contact-sheet'];
+    const target = process.env.AGENT_DEVICE_IOS_UDID
+      ? ['--udid', process.env.AGENT_DEVICE_IOS_UDID]
+      : [];
+    let recordingStarted = false;
+    let recordingStopped = false;
+
+    try {
+      integration.runStep('open settings', [
+        'open',
+        'com.apple.Preferences',
+        '--platform',
+        'ios',
+        '--relaunch',
+        '--json',
+        ...target,
+        ...session,
+      ]);
+      integration.runStep('record start', [
+        'record',
+        'start',
+        videoPath,
+        '--json',
+        ...target,
+        ...session,
+      ]);
+      recordingStarted = true;
+      integration.runStep('open general', [
+        'click',
+        'role=cell',
+        'label=General',
+        '--json',
+        ...target,
+        ...session,
+      ]);
+      integration.runStep('scroll down', [
+        'scroll',
+        'down',
+        '0.6',
+        '--json',
+        ...target,
+        ...session,
+      ]);
+      integration.runStep('go back', ['back', '--json', ...target, ...session]);
+      const stop = integration.runStep('record stop', [
+        'record',
+        'stop',
+        '--json',
+        ...target,
+        ...session,
+      ]);
+      recordingStopped = true;
+      assert.equal(stop.json?.success, true, JSON.stringify(stop.json ?? stop.stderr));
+      assert.ok(existsSync(videoPath), `expected recording at ${videoPath}`);
+
+      const sheet = integration.runStep('record contact-sheet', [
+        'record',
+        'contact-sheet',
+        videoPath,
+        '--out',
+        sheetPath,
+        '--json',
+      ]);
+      assertContactSheet(sheet, videoPath, sheetPath);
+    } finally {
+      if (recordingStarted && !recordingStopped) {
+        integration.runCleanupStep('cleanup record stop', [
+          'record',
+          'stop',
+          '--json',
+          ...target,
+          ...session,
+        ]);
+      }
+      integration.runCleanupStep('cleanup close', ['close', '--json', ...target, ...session]);
+    }
+  },
+);
+
+type ContactSheetData = {
+  path?: string;
+  videoPath?: string;
+  durationMs?: number;
+  width?: number;
+  height?: number;
+  sampledFrameCount?: number;
+  decodedFrameCount?: number;
+  skippedSampleCount?: number;
+  changedPixelThreshold?: number;
+  cells?: Array<{ timeMs?: number; changedPixelRatio?: number }>;
+};
+
+/** The shortest grid the planner produces for a clip long enough to navigate. */
+const MIN_SAMPLED_FRAMES = 4;
+/** The grid cap `planContactSheetSampleTimes` holds however long the clip runs. */
+const MAX_SAMPLED_FRAMES = 48;
+/** Cells one sheet prints. */
+const MAX_SHEET_CELLS = 24;
+
+function assertContactSheet(
+  result: CliJsonResult,
+  videoPath: string,
+  sheetPath: string,
+): ContactSheetData {
+  assert.equal(result.status, 0, JSON.stringify(result.json ?? result.stderr));
+  assert.equal(result.json?.success, true, JSON.stringify(result.json ?? result.stderr));
+  const data = (result.json?.data ?? {}) as ContactSheetData;
+
+  assert.equal(data.path, sheetPath);
+  assert.equal(data.videoPath, videoPath);
+  assert.ok(existsSync(sheetPath), `expected contact sheet at ${sheetPath}`);
+
+  const bytes = readFileSync(sheetPath);
+  assertPngHeader(bytes);
+  assertReportedSizeMatchesHeader(bytes, data);
+  assertCoverage(data);
+  assertCells(data);
+  return data;
+}
+
+function assertPngHeader(bytes: Buffer): void {
+  assert.deepEqual(
+    [...bytes.subarray(0, 8)],
+    [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a],
+    'expected contact sheet to be a PNG',
+  );
+}
+
+/** The sheet reports the bytes it wrote, not a size it hoped for. */
+function assertReportedSizeMatchesHeader(bytes: Buffer, data: ContactSheetData): void {
+  assert.ok((data.width ?? 0) > 0 && (data.height ?? 0) > 0, 'expected reported dimensions');
+  assert.equal(bytes.readUInt32BE(16), data.width, 'reported width must match the PNG header');
+  assert.equal(bytes.readUInt32BE(20), data.height, 'reported height must match the PNG header');
+}
+
+/** What the sheet says it looked at: a bounded grid over a measurable clip, with nothing dropped. */
+function assertCoverage(data: ContactSheetData): void {
+  assert.ok((data.durationMs ?? 0) > 0, 'expected a measurable clip length');
+  const sampled = data.sampledFrameCount ?? 0;
+  assert.ok(
+    sampled >= MIN_SAMPLED_FRAMES && sampled <= MAX_SAMPLED_FRAMES,
+    `expected a bounded sample grid, saw ${String(sampled)}`,
+  );
+  assert.ok(
+    (data.decodedFrameCount ?? 0) >= MIN_SAMPLED_FRAMES,
+    `expected the decoder to answer sample times, saw ${String(data.decodedFrameCount)}`,
+  );
+  assert.equal(data.skippedSampleCount, 0, 'expected no declined sample times');
+}
+
+function assertCells(data: ContactSheetData): void {
+  const cells = data.cells ?? [];
+  assert.ok(cells.length >= 2, 'expected a navigation to earn cells beyond the opening frame');
+  assert.ok(
+    cells.length <= MAX_SHEET_CELLS,
+    `expected at most ${MAX_SHEET_CELLS} cells, saw ${cells.length}`,
+  );
+  assert.equal(cells[0]?.timeMs, 0, 'expected the sheet to open on the first frame');
+  assertCellTimesIncreaseWithinTheClip(cells, data.durationMs ?? 0);
+  assertEveryCellClearedTheThreshold(cells, data.changedPixelThreshold ?? 0);
+}
+
+function assertCellTimesIncreaseWithinTheClip(
+  cells: ContactSheetData['cells'],
+  durationMs: number,
+): void {
+  const list = cells ?? [];
+  list.forEach((cell, index) => {
+    if (index === 0) return;
+    const previous = list[index - 1] as { timeMs?: number };
+    assert.ok(
+      (cell.timeMs ?? 0) > (previous.timeMs ?? 0),
+      `expected strictly increasing cell times at index ${index}`,
+    );
+  });
+  assert.ok(
+    (list.at(-1)?.timeMs ?? 0) <= durationMs,
+    'expected every cell inside the clip timeline',
+  );
+}
+
+function assertEveryCellClearedTheThreshold(
+  cells: ContactSheetData['cells'],
+  threshold: number,
+): void {
+  for (const cell of (cells ?? []).slice(1)) {
+    assert.ok(
+      (cell.changedPixelRatio ?? 0) > threshold,
+      `expected cell ${String(cell.timeMs)} to clear the ${String(threshold)} threshold`,
+    );
+  }
+}
+
+function createRecordingIntegrationContext(platform: 'ios' | 'android', testName: string) {
+  const runId = new Date().toISOString().replaceAll(':', '-');
+  const stateDir = path.resolve('test/artifacts', platform, sanitize(testName), runId, 'state');
+  return createIntegrationTestContext({
+    platform,
+    testName,
+    extraEnv: { ...process.env, AGENT_DEVICE_STATE_DIR: stateDir },
+  });
+}
+
+function shouldSkipContactSheetE2E(): string | false {
+  if (!recordingE2EEnabled) return 'set AGENT_DEVICE_RECORDING_E2E=1 to run live recording tests';
+  if (process.platform !== 'darwin') return 'contact sheets need a macOS host';
+  return false;
+}
+
+function isTruthy(value: string | undefined): boolean {
+  return ['1', 'true', 'yes', 'on'].includes((value ?? '').toLowerCase());
+}
+
+function sanitize(input: string): string {
+  return input
+    .trim()
+    .toLowerCase()
+    .replaceAll(/[^a-z0-9._-]+/g, '-')
+    .replaceAll(/-+/g, '-');
+}
diff --git a/test/wire-compat/ledger.json b/test/wire-compat/ledger.json
index f8bef2d1a5..181e04ba82 100644
--- a/test/wire-compat/ledger.json
+++ b/test/wire-compat/ledger.json
@@ -16,7 +16,7 @@
     "packages/kernel/src/contracts.ts#CommandRpcParams": "sha256:3a400b0d815920d9cf4c6236531931f6ba6f9debf7ac26915e0116b493f1c97a",
     "packages/kernel/src/contracts.ts#DAEMON_LOCK_POLICIES": "sha256:625cc33bb574aa6119add45878a0f6adc445244edc2957737da975f91605c786",
     "packages/kernel/src/contracts.ts#DaemonArtifact": "sha256:967c919d878b83b6e0324c56c1bf41e63b0c31c2e42cf41cd5a12902c2b5034a",
-    "packages/kernel/src/contracts.ts#DaemonArtifactKnownType": "sha256:21886407c3fbc30d8c0c544503b831c78db2408aeaef1b9b2c6a4139144aef28",
+    "packages/kernel/src/contracts.ts#DaemonArtifactKnownType": "sha256:b16ce8169a6314168b36b42cc3c042f722781b49695cb290674f4e5216d83b3b",
     "packages/kernel/src/contracts.ts#DaemonArtifactType": "sha256:5e5017276fefe880b8ab32001888011d2e02a8670f0978afdb9b56a77ab37f09",
     "packages/kernel/src/contracts.ts#DaemonInstallSource": "sha256:fe26e202e62d997cdd3855fd96002511783a6c26a9ce27210d7c6cc084c66e4e",
     "packages/kernel/src/contracts.ts#DaemonLockPolicy": "sha256:f33d0ce7200a7d97c11e91bd2889b5d9bc7f35935a5370a29930118d091468f4",
@@ -188,8 +188,8 @@
     },
     {
       "declaration": "packages/kernel/src/contracts.ts#DaemonArtifactKnownType",
-      "digest": "sha256:21886407c3fbc30d8c0c544503b831c78db2408aeaef1b9b2c6a4139144aef28",
-      "rationale": "#2246 adds the 'test-artifacts' literal for the new remote `test` suite-directory artifact. DaemonArtifactType already widens to `(string & {})`, so an artifactType value outside the known set was always valid on the wire; the literal only sharpens the type hint for code that opts into recognizing it. A released peer that does not know it either never receives it (an old client's daemon-artifacts.ts has no 'test' redirect, so it never sets clientArtifactPaths.artifactsDir, so a new daemon's attachRemoteReplayTestArtifacts never attaches this artifact) or, receiving it from an old daemon that cannot produce it, is a case that cannot occur."
+      "digest": "sha256:b16ce8169a6314168b36b42cc3c042f722781b49695cb290674f4e5216d83b3b",
+      "rationale": "#2747 adds the 'screen-recording-contact-sheet' literal for the PNG that `record contact-sheet` publishes beside the recording it read. DaemonArtifactType already widens to `(string & {})`, so an artifactType value outside the known set was always valid on the wire; the literal only sharpens the type hint for code that opts into recognizing it. A released peer that does not know it never requests that field in a download and parses the artifact record by its `field`, so it carries the sheet as an unknown artifact instead of failing."
     },
     {
       "declaration": "src/remote/daemon-artifacts.ts#DownloadRemoteArtifactParams",
diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md
index 08f8c42f3f..8cd20917df 100644
--- a/website/docs/docs/commands.md
+++ b/website/docs/docs/commands.md
@@ -1055,6 +1055,9 @@ agent-device record stop                # Stop active recording
 - `record stop` is safe to repeat. When its request window ends while the daemon is still exporting — typical for a long touch-overlay burn-in on a remote daemon — the export keeps running there, and a second `record stop` in the same session returns that completed recording, including the caller-side output path, without starting another recording. A finished recording whose video file is already gone reports `no active recording`.
 - A recording answers two independent questions, and `record stop` reports both: whether a playable export exists, and whether the recorder stopped. `recorder` is `confirmed` when the recorder exited or acknowledged a stop meant for this recording, and `lost` when the session holding it died — an Apple recording invalidated by a runner restart. `nativePathDisposition` says what became of the artifact path the recorder itself writes to: `retirable` while that file still sits there owed a removal, and `retired` once its removal was verified. Both are optional disclosures — the export is served either way, a replay of a recording stopped before they existed omits them, and so does a backend whose recorder writes the served file itself. The vocabulary is deliberately wider than today's answers: `recorder: unconfirmed` (a probe that could not be read, or no exit inside the stop budget), the identity-mismatch reasons under `lost`, and `nativePathDisposition: pending` are declared by [ADR 0024](https://github.com/callstack/agent-device/blob/main/docs/adr/0024-screen-recording-provable-signal.md) for the steps that gain those probes, and no stop reports them yet.
 
+- `record contact-sheet <video.mp4> [--out <sheet.png>]` turns a recording you already exported into one PNG: the frames where the screen visibly changed, laid out in a grid and each labeled with its elapsed time (`HH:MM:SS.mmm`) on the clip timeline. It is how an agent reads a recording it cannot play. It reads the file you pass — no session, no device, no daemon — so it can rebuild an old take and the sheet can only describe screens that export contains. Any backend that exports MP4 works (Apple, Android, HarmonyOS, Limrun); a WebM recording from the web backend is refused with `details.reason: contact_sheet_container_unsupported`. The default output is `<recording>.contact-sheet.png`, and `--out` is refused when it points back at the recording itself, because a sheet is derived from a take and never replaces it. `--json` reports each cell's time and changed-pixel share alongside `sampledFrameCount`, `decodedFrameCount`, and `skippedSampleCount`.
+- A contact sheet is coverage, not a review. The sample grid is bounded and spread across the whole clip (every 250ms until 48 samples, then those 48 spread over the length) and at most 24 cells are printed, so a two-hour take costs no more than a five-second one. A transient that opens and closes entirely between two sample times is not in the returned frames and no threshold recovers it; when the sheet had to thin kept cells or the decoder declined sample times, `warning` says so. Frame decoding is Apple AVFoundation tooling, so the command is macOS-host only and refuses elsewhere with `details.reason: contact_sheet_unsupported_host`.
+
 **Session app logs (token-efficient debugging):** Logging is off by default in normal flows. Enable it on demand for debugging. Logs are written to a file so agents can grep instead of loading full output into context.
 
 ```bash

From ee9d203db040204ed8c63980d4d780d0ab8d6398 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Tue, 22 Sep 2026 13:11:00 +0200
Subject: [PATCH 014/132] fix(ios): target the active window for foldable
 interactions (#2724)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(ios): rotate synthesized gestures in the capture viewport

The synthesized lane derived its rotation frame from
XCUIScreen.main.screenshot() image size while capture normalizes node
rects into the acquisition viewport (app.frame). On an iPhone Duo in the
open pose the runner's main screen is the dark outer panel, so dispatch
was not the inverse of capture and taps drifted by a constant offset
(hit the Home tab by luck, missed Settings). Use app.frame as the
reference frame for every synthesized lane so dispatch is capture's
inverse on any panel and orientation, and assert that inverse as a
round-trip unit test including the Duo inner panel (669x951, rot90).
Drops the per-gesture main-screen screenshot.

* fix(ios): route foldable interactions through the resolved window

* test(apple): read snapshot capture guard from the acquisition module

captureSnapshotRootBounded moved to RunnerTests+SnapshotAcquisition.swift with the
capture split; the source-shape guard still read RunnerTests+Snapshot.swift, failing
the Coverage job.

* feat(ios-runner): log synthesized dispatch geometry and record routing

The dispatch point after rotation, the reference window it was computed against, and
the display a record is routed to are the three facts that decide whether a
synthesized event lands. runner.log now carries them (SYNTHESIZED_DISPATCH,
SYNTHESIZED_RECORD) so delivery regressions are readable without instrumenting a
build. Documents the origin invariant CoordinateSpaceRotation relies on.

* fix(ios-runner): keep the os(iOS) directive on its own line in synthesizedCoordinateContext

The formatter had joined it to the opening brace, which the selection scanner's
line-start directive match misses, so the else branch parsed as unmatched.

* refactor(ios-runner): resolve the interaction window through one helper

The viewport, the interaction root, and the synthesized reference frame each
walked app.windows with their own exists/frame rules, so a sheet or a fold
could move one consumer without the others. resolveRunnerWindow is now the
single walk: the first window with a non-empty frame, the application
otherwise. Alert activation logs the chosen button's label and frame center
so a tap that lands beside its button is visible in runner.log.

* fix(ios-runner): route synthesized display IDs through the resolved window

The gesture reference frame is booked against the window resolveRunnerWindow
picks, but record creation re-walked windows.firstMatch for the display ID.
With an empty window 0 beside a lit window N the reference lands on N while
the gesture routes to window 0's display, or fails outright. The bridge now
takes the resolved window: the gesture entry points accept it, record
creation reads the display from it, and every remaining firstMatch geometry
read (keyboard avoidance, touch reference frame, system edge gestures) goes
through the shared resolver. The interaction anchor and its frame come from
one resolution pass, keeping the coordinate offset on the window the tap was
measured against. Unit tests cover empty-window-0, absent windows, and the
pure window-index rule.

* fix(ios-runner): anchor iOS coordinate interactions at the app origin

`interactionCoordinate` resolved the interaction root through
`resolveRunnerWindow`, so an iOS coordinate tap/double-tap/long-press/drag
anchored on the first qualifying window and subtracted its frame origin. On
SpringBoard that first window is not necessarily the alert's — the wallpaper or
status-bar window can qualify first — so `alert accept` (reached via activateElement,
tapAt, performCoordinateTap) missed the Open button, which is why iOS Smoke failed
at "wait for Automation lab" after the deep-link confirmation.

Restore the main-branch iOS app-origin anchor (app.coordinate(0,0) + the
snapshot-space point). Reference frames and the synthesized display ID still
resolve through `resolveRunnerWindow`, so a foldable tap keeps its panel and
routes on the resolved window's display. macOS keeps the window-relative anchor.

Refs #2724

* refactor(ios-runner): fail a gesture with no resolved window directly

The gesture callers resolve the window in Swift before the call, so a nil
resolved window already means no window qualified. Walking
windows.firstMatch a second time in record creation could only book a display
that every Swift caller had refused to book geometry against; the missing
window is now the error.

* fix(ios-runner): refuse a synthesized context with no resolved window

resolveRunnerWindow reports "no window" honestly: it returns nil alongside
app.frame when no window has a non-empty frame. synthesizedCoordinateContext
still built a context from that frame, so a synthesized drag or pinch carried a
nil window into record creation and failed with "no resolved application
window" on a case main dispatched. The context now refuses to exist without its
window, which sends the gesture down the XCUITest fallback that already covers
it and lets SynthesizedCoordinateContext.resolvedWindow be non-optional.

Refs #2724

* refactor(ios-runner): drop the unused application display ID resolver

Every synthesized gesture routes its display through the window it already
resolved for geometry, so the wrapper that re-walked windows.firstMatch had no
production caller left. Its assertions move to RunnerResolveWindowDisplayID, so
the resolve-before-read ordering, the primary-window identity, and both refusal
branches stay under test.

Refs #2724
---
 ...AgentDeviceRunnerUITests-Bridging-Header.h |   1 +
 .../RunnerSynthesizedGesture.h                |  12 +-
 .../RunnerSynthesizedGesture.m                |  57 +-
 .../RunnerTests+Alert.swift                   |   8 +
 .../RunnerTests+CommandExecution.swift        |  11 +-
 .../RunnerTests+Interaction.swift             | 773 +-----------------
 .../RunnerTests+Snapshot.swift                | 567 +------------
 .../RunnerTests+SnapshotAcquisition.swift     | 566 +++++++++++++
 ...RunnerTests+SynthesizedGesturePolicy.swift |   6 +-
 .../RunnerTests+SynthesizedInteraction.swift  | 594 ++++++++++++++
 .../RunnerXCTestEventBridge.h                 |  10 +-
 .../RunnerXCTestEventBridge.m                 |  20 +
 ...nerTests+SynthesizedInteractionTests.swift | 116 +++
 .../RunnerTests+XCTestEventBridgeTests.swift  |  66 ++
 .../SnapshotCoordinateSpace.swift             |   5 +
 .../fixtures/window-coordinate-space.json     |   7 +
 docs/adr/0025-foldable-apple-panels.md        |  23 +
 docs/agents/device-verification.md            |   3 +
 .../apple-runner-package-source.test.ts       |   2 +-
 src/commands/system/index.ts                  |   2 +-
 website/docs/docs/commands.md                 |   2 +-
 21 files changed, 1528 insertions(+), 1323 deletions(-)
 create mode 100644 apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotAcquisition.swift
 create mode 100644 apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SynthesizedInteraction.swift
 create mode 100644 apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SynthesizedInteractionTests.swift
 create mode 100644 apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+XCTestEventBridgeTests.swift

diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/AgentDeviceRunnerUITests-Bridging-Header.h b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/AgentDeviceRunnerUITests-Bridging-Header.h
index a571613e70..90898722a2 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/AgentDeviceRunnerUITests-Bridging-Header.h
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/AgentDeviceRunnerUITests-Bridging-Header.h
@@ -2,3 +2,4 @@
 #import "RunnerAXSnapshotBridge.h"
 #import "RunnerSynthesizedGesture.h"
 #import "RunnerSynthesizedTextEntry.h"
+#import "RunnerXCTestEventBridge.h"
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerSynthesizedGesture.h b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerSynthesizedGesture.h
index b6c23da7b1..e606041e8d 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerSynthesizedGesture.h
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerSynthesizedGesture.h
@@ -8,7 +8,11 @@ FOUNDATION_EXPORT double RunnerControlledScrollProgress(double t);
 
 @interface RunnerSynthesizedGesture : NSObject
 
+// `resolvedWindow` is the app window the caller already resolved for the gesture's reference
+// frame. The record's display ID is read from that same window so geometry and routing can never
+// name different windows; pass nil to fall back to the application's first window.
 + (NSString * _Nullable)synthesizeSwipeWithApplication:(id)application
+                                        resolvedWindow:(id _Nullable)resolvedWindow
                                                     x:(double)x
                                                     y:(double)y
                                                    x2:(double)x2
@@ -16,26 +20,30 @@ FOUNDATION_EXPORT double RunnerControlledScrollProgress(double t);
                                             durationMs:(double)durationMs;
 
 + (NSString * _Nullable)synthesizeContinuousDragWithApplication:(id)application
+                                                resolvedWindow:(id _Nullable)resolvedWindow
                                                              x:(double)x
                                                              y:(double)y
                                                             x2:(double)x2
-                                                             y2:(double)y2
+                                                            y2:(double)y2
                                                      durationMs:(double)durationMs;
 
 + (NSString * _Nullable)synthesizeControlledScrollWithApplication:(id)application
+                                                 resolvedWindow:(id _Nullable)resolvedWindow
                                                                 x:(double)x
                                                                 y:(double)y
                                                                x2:(double)x2
-                                                                y2:(double)y2
+                                                               y2:(double)y2
                                                         durationMs:(double)durationMs;
 
 + (NSString * _Nullable)synthesizeTapWithApplication:(id)application
+                                      resolvedWindow:(id _Nullable)resolvedWindow
                                                    x:(double)x
                                                    y:(double)y;
 
 // Each pointer is an ordered array of { x, y, offsetMs } samples. The first sample
 // starts contact; subsequent samples move it; all pointers lift at their final offset.
 + (NSString * _Nullable)synthesizeGestureWithApplication:(id)application
+                                          resolvedWindow:(id _Nullable)resolvedWindow
                                           pointerSamples:(NSArray<NSArray<NSDictionary<NSString *, NSNumber *> *> *> *)pointerSamples;
 
 // UIInterfaceOrientation of the app (1 portrait, 2 upsideDown, 3 landscapeRight,
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerSynthesizedGesture.m b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerSynthesizedGesture.m
index dbbf4ed5b0..5767bb0c7d 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerSynthesizedGesture.m
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerSynthesizedGesture.m
@@ -6,13 +6,13 @@
 
 static NSString *const RunnerGestureSynthesisSurface = @"event";
 
-typedef id (*RunnerMsgSendInitRecord)(id, SEL, NSString *, NSInteger);
+typedef id (*RunnerMsgSendInitRecord)(id, SEL, NSString *, NSUInteger, NSInteger);
 typedef id (*RunnerMsgSendInitPath)(id, SEL, CGPoint, NSTimeInterval);
 typedef void (*RunnerMsgSendPathMove)(id, SEL, CGPoint, NSTimeInterval);
 typedef void (*RunnerMsgSendPathOffset)(id, SEL, NSTimeInterval);
 
-// Gesture-specific extension of the shared bridge: the 2-arg
-// `initWithName:interfaceOrientation:` record initializer and the touch-path
+// Gesture-specific extension of the shared bridge: the display-aware
+// `initWithName:displayID:interfaceOrientation:` record initializer and the touch-path
 // factory/mutator selectors, none of which text-entry synthesis needs.
 typedef struct {
   RunnerXCTestEventBridge core;
@@ -37,6 +37,7 @@ typedef id (*RunnerDragPointerPathFactory)(
 );
 static NSString * _Nullable RunnerCreateEventRecord(
   id application,
+  id _Nullable resolvedWindow,
   NSString *recordName,
   RunnerGestureEventBridge *bridge,
   id *record
@@ -74,13 +75,14 @@ static id RunnerSampledDragPointerPath(
 static double RunnerSmoothstepProgress(double t);
 static NSString * _Nullable RunnerTrySynthesizeDrag(
   id application,
+  id _Nullable resolvedWindow,
   CGPoint start,
   CGPoint end,
   double durationMs,
   NSString *recordName,
   RunnerDragPointerPathFactory pathFactory
 );
-static NSString * _Nullable RunnerTrySynthesizeTap(id application, CGPoint point);
+static NSString * _Nullable RunnerTrySynthesizeTap(id application, id _Nullable resolvedWindow, CGPoint point);
 // XCTest's proven swipe profile reaches the endpoint in 100 ms, then holds for the planned
 // fling duration. Fast movement is what lets UIKit distinguish a fling from a timed pan.
 static const NSTimeInterval RunnerSwipeMovementDurationSeconds = 0.1;
@@ -94,14 +96,16 @@ static id RunnerTapPointerPath(
 @implementation RunnerSynthesizedGesture
 
 + (NSString * _Nullable)synthesizeSwipeWithApplication:(id)application
-                                                    x:(double)x
-                                                    y:(double)y
-                                                   x2:(double)x2
-                                                   y2:(double)y2
+                                        resolvedWindow:(id _Nullable)resolvedWindow
+                                                     x:(double)x
+                                                     y:(double)y
+                                                    x2:(double)x2
+                                                    y2:(double)y2
                                             durationMs:(double)durationMs {
   @try {
     return RunnerTrySynthesizeDrag(
       application,
+      resolvedWindow,
       CGPointMake(x, y),
       CGPointMake(x2, y2),
       durationMs,
@@ -114,6 +118,7 @@ + (NSString * _Nullable)synthesizeSwipeWithApplication:(id)application
 }
 
 + (NSString * _Nullable)synthesizeContinuousDragWithApplication:(id)application
+                                                resolvedWindow:(id _Nullable)resolvedWindow
                                                              x:(double)x
                                                              y:(double)y
                                                             x2:(double)x2
@@ -122,6 +127,7 @@ + (NSString * _Nullable)synthesizeContinuousDragWithApplication:(id)application
   @try {
     return RunnerTrySynthesizeDrag(
       application,
+      resolvedWindow,
       CGPointMake(x, y),
       CGPointMake(x2, y2),
       durationMs,
@@ -134,14 +140,16 @@ + (NSString * _Nullable)synthesizeContinuousDragWithApplication:(id)application
 }
 
 + (NSString * _Nullable)synthesizeControlledScrollWithApplication:(id)application
+                                                 resolvedWindow:(id _Nullable)resolvedWindow
                                                                 x:(double)x
                                                                 y:(double)y
                                                                x2:(double)x2
-                                                                y2:(double)y2
-                                                        durationMs:(double)durationMs {
+                                                               y2:(double)y2
+                                                       durationMs:(double)durationMs {
   @try {
     return RunnerTrySynthesizeDrag(
       application,
+      resolvedWindow,
       CGPointMake(x, y),
       CGPointMake(x2, y2),
       durationMs,
@@ -154,22 +162,25 @@ + (NSString * _Nullable)synthesizeControlledScrollWithApplication:(id)applicatio
 }
 
 + (NSString * _Nullable)synthesizeTapWithApplication:(id)application
+                                      resolvedWindow:(id _Nullable)resolvedWindow
                                                    x:(double)x
                                                    y:(double)y {
   @try {
-    return RunnerTrySynthesizeTap(application, CGPointMake(x, y));
+    return RunnerTrySynthesizeTap(application, resolvedWindow, CGPointMake(x, y));
   } @catch (NSException *exception) {
     return RunnerFormatXCTestException(exception, @"private XCTest event synthesis failed");
   }
 }
 
 + (NSString * _Nullable)synthesizeGestureWithApplication:(id)application
+                                          resolvedWindow:(id _Nullable)resolvedWindow
                                           pointerSamples:(NSArray<NSArray<NSDictionary<NSString *, NSNumber *> *> *> *)pointerSamples {
   @try {
     RunnerGestureEventBridge bridge;
     id record = nil;
     NSString *error = RunnerCreateEventRecord(
       application,
+      resolvedWindow,
       @"agent-device-gesture-plan",
       &bridge,
       &record
@@ -224,6 +235,7 @@ + (NSInteger)interfaceOrientationForApplication:(id)application {
 
 static NSString * _Nullable RunnerTrySynthesizeDrag(
   id application,
+  id _Nullable resolvedWindow,
   CGPoint start,
   CGPoint end,
   double durationMs,
@@ -232,7 +244,7 @@ + (NSInteger)interfaceOrientationForApplication:(id)application {
 ) {
   RunnerGestureEventBridge bridge;
   id record = nil;
-  NSString *error = RunnerCreateEventRecord(application, recordName, &bridge, &record);
+  NSString *error = RunnerCreateEventRecord(application, resolvedWindow, recordName, &bridge, &record);
   if (error != nil) return error;
 
   id path = pathFactory(&bridge, start, end, durationMs);
@@ -244,11 +256,12 @@ + (NSInteger)interfaceOrientationForApplication:(id)application {
   return RunnerSynthesizeEventRecord(&bridge, record);
 }
 
-static NSString * _Nullable RunnerTrySynthesizeTap(id application, CGPoint point) {
+static NSString * _Nullable RunnerTrySynthesizeTap(id application, id _Nullable resolvedWindow, CGPoint point) {
   RunnerGestureEventBridge bridge;
   id record = nil;
   NSString *error = RunnerCreateEventRecord(
     application,
+    resolvedWindow,
     @"agent-device-tap",
     &bridge,
     &record
@@ -271,14 +284,14 @@ + (NSInteger)interfaceOrientationForApplication:(id)application {
   NSString *missing = RunnerResolveXCTestEventBridge(application, RunnerGestureSynthesisSurface, &core);
   if (missing != nil) return missing;
 
-  SEL initRecordSelector = NSSelectorFromString(@"initWithName:interfaceOrientation:");
+  SEL initRecordSelector = NSSelectorFromString(@"initWithName:displayID:interfaceOrientation:");
   SEL interfaceOrientationSelector = NSSelectorFromString(@"interfaceOrientation");
   SEL initPathSelector = NSSelectorFromString(@"initForTouchAtPoint:offset:");
   SEL moveSelector = NSSelectorFromString(@"moveToPoint:atOffset:");
   SEL liftSelector = NSSelectorFromString(@"liftUpAtOffset:");
 
   missing = RunnerRequireSelector(
-    core.recordClass, initRecordSelector, @"initWithName:interfaceOrientation:", RunnerGestureSynthesisSurface
+    core.recordClass, initRecordSelector, @"initWithName:displayID:interfaceOrientation:", RunnerGestureSynthesisSurface
   );
   if (missing != nil) return missing;
   missing = RunnerRequireSelector(
@@ -311,6 +324,7 @@ + (NSInteger)interfaceOrientationForApplication:(id)application {
 
 static NSString * _Nullable RunnerCreateEventRecord(
   id application,
+  id _Nullable resolvedWindow,
   NSString *recordName,
   RunnerGestureEventBridge *bridge,
   id *record
@@ -318,6 +332,12 @@ + (NSInteger)interfaceOrientationForApplication:(id)application {
   NSString *missing = RunnerResolveGestureEventBridge(application, bridge);
   if (missing != nil) return missing;
 
+  NSUInteger displayID = 0;
+  if (resolvedWindow == nil) {
+    return @"private XCTest event synthesis unavailable: no resolved application window";
+  }
+  NSString *displayError = RunnerResolveWindowDisplayID(resolvedWindow, &displayID);
+  if (displayError != nil) return displayError;
   NSInteger interfaceOrientation =
     ((RunnerMsgSendInteger)objc_msgSend)(application, bridge->interfaceOrientationSelector);
   NSInteger targetProcessID =
@@ -330,11 +350,18 @@ + (NSInteger)interfaceOrientationForApplication:(id)application {
     [bridge->core.recordClass alloc],
     bridge->initRecordSelector,
     recordName,
+    displayID,
     interfaceOrientation
   );
   if (eventRecord == nil) {
     return @"private XCTest event synthesis failed: could not create event record";
   }
+  NSLog(
+    @"AGENT_DEVICE_RUNNER_SYNTHESIZED_RECORD name=%@ displayID=%lu interfaceOrientation=%ld",
+    recordName,
+    (unsigned long)displayID,
+    (long)interfaceOrientation
+  );
   ((RunnerMsgSendSetInteger)objc_msgSend)(
     eventRecord,
     bridge->core.setTargetProcessIDSelector,
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Alert.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Alert.swift
index 9e06410820..4503003d31 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Alert.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Alert.swift
@@ -68,6 +68,14 @@ extension RunnerTests {
       guard waitUntilAlertButtonHittable(button, deadline: deadline) else {
         return alertVerificationResponse(.timedOut, action: action, activated: false)
       }
+      let buttonFrame = button.frame
+      NSLog(
+        "AGENT_DEVICE_RUNNER_ALERT_ACTIVATION action=%@ label=%@ frame=(%.1f,%.1f,%.1f,%.1f) point=(%.1f,%.1f)",
+        action,
+        button.label,
+        buttonFrame.origin.x, buttonFrame.origin.y, buttonFrame.size.width, buttonFrame.size.height,
+        buttonFrame.midX, buttonFrame.midY
+      )
       // The hittable read above is this activation's readiness gate, so XCTest's pre-synthesis wait
       // adds nothing and can cost more than the command has: the tap would land after the deadline
       // expired and the alert would be answered by a button the caller was told nothing about
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
index e05ac00ae6..a4bed87200 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
@@ -5,9 +5,10 @@ import AgentDeviceSnapshotPresentation
 import ObjectiveC.runtime
 
 private final class RunnerSynthesizedSwipeFailureStub: NSObject {
-  @objc(synthesizeSwipeWithApplication:x:y:x2:y2:durationMs:)
+  @objc(synthesizeSwipeWithApplication:resolvedWindow:x:y:x2:y2:durationMs:)
   class func synthesizeSwipe(
     application: XCUIApplication,
+    resolvedWindow: Any?,
     x: Double,
     y: Double,
     x2: Double,
@@ -19,8 +20,8 @@ private final class RunnerSynthesizedSwipeFailureStub: NSObject {
 }
 
 private final class RunnerSynthesizedTapFailureStub: NSObject {
-  @objc(synthesizeTapWithApplication:x:y:)
-  class func synthesizeTap(application: XCUIApplication, x: Double, y: Double) -> String? {
+  @objc(synthesizeTapWithApplication:resolvedWindow:x:y:)
+  class func synthesizeTap(application: XCUIApplication, resolvedWindow: Any?, x: Double, y: Double) -> String? {
     "forced private synthesis failure"
   }
 }
@@ -261,7 +262,7 @@ extension RunnerTests {
 #if os(iOS)
   func testSinglePointerFlingFallsBackToXCTestCoordinateDragWhenPrivateSynthesisFails() throws {
     let selector = NSSelectorFromString(
-      "synthesizeSwipeWithApplication:x:y:x2:y2:durationMs:"
+      "synthesizeSwipeWithApplication:resolvedWindow:x:y:x2:y2:durationMs:"
     )
     guard
       let synthesizedSwipeMethod = class_getClassMethod(RunnerSynthesizedGesture.self, selector),
@@ -305,7 +306,7 @@ extension RunnerTests {
   }
 
   func testSelectorTapFallsBackToXCTestCoordinateWhenPrivateSynthesisFails() throws {
-    let selector = NSSelectorFromString("synthesizeTapWithApplication:x:y:")
+    let selector = NSSelectorFromString("synthesizeTapWithApplication:resolvedWindow:x:y:")
     guard
       let synthesizedTapMethod = class_getClassMethod(RunnerSynthesizedGesture.self, selector),
       let failureStubMethod = class_getClassMethod(RunnerSynthesizedTapFailureStub.self, selector)
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift
index b4eb25b33d..ba896c9164 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift
@@ -76,7 +76,7 @@ extension RunnerTests {
 
   private func performCoordinateBackGesture(app: XCUIApplication) {
 #if !os(tvOS)
-    let target = app.windows.firstMatch.exists ? app.windows.firstMatch : app
+    let target = resolveRunnerWindow(app: app).window ?? app
     let start = target.coordinate(withNormalizedOffset: CGVector(dx: 0.05, dy: 0.5))
     let end = target.coordinate(withNormalizedOffset: CGVector(dx: 0.8, dy: 0.5))
     start.press(forDuration: 0.05, thenDragTo: end)
@@ -106,7 +106,7 @@ extension RunnerTests {
 
   private func performCoordinateAppSwitcherGesture(app: XCUIApplication) {
 #if !os(tvOS)
-    let target = app.windows.firstMatch.exists ? app.windows.firstMatch : app
+    let target = resolveRunnerWindow(app: app).window ?? app
     let start = target.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.99))
     let end = target.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.7))
     start.press(forDuration: 0.6, thenDragTo: end)
@@ -219,15 +219,35 @@ extension RunnerTests {
   // transformed subtrees, so a closed drawer at negative x inflates it and
   // out-of-window coordinates still pass containment. Falls back to app.frame
   // when no window frame is readable.
-  func onScreenWindowFrame(app: XCUIApplication) -> CGRect {
-    let window = app.windows.element(boundBy: 0)
-    if window.exists {
-      let frame = window.frame
-      if !frame.isEmpty {
-        return frame
+  /// The app window interactions and captures are booked against: the first window the app
+  /// reports with a non-empty frame, and no window at all when none qualifies. The viewport,
+  /// the interaction anchor, and the synthesized reference frame all resolve through here, so a
+  /// fold, a sheet, or a rotation moves every consumer to the same window in the same pass.
+  /// Synthesized gestures route their display ID through the returned window so the record's
+  /// display can never name a different window than the one the reference frame was measured on.
+  func resolveRunnerWindow(app: XCUIApplication) -> (window: XCUIElement?, frame: CGRect) {
+    let windows = app.windows.allElementsBoundByIndex
+    var frames: [CGRect?] = []
+    for window in windows {
+      frames.append(window.exists ? window.frame : nil)
+    }
+    if let index = Self.firstUsableWindowIndex(frames: frames) {
+      return (windows[index], frames[index] ?? .zero)
+    }
+    return (nil, app.frame)
+  }
+
+  static func firstUsableWindowIndex(frames: [CGRect?]) -> Int? {
+    for (index, frame) in frames.enumerated() {
+      if let frame, !frame.isEmpty {
+        return index
       }
     }
-    return app.frame
+    return nil
+  }
+
+  func onScreenWindowFrame(app: XCUIApplication) -> CGRect {
+    resolveRunnerWindow(app: app).frame
   }
 
   func queryElement(app: XCUIApplication, selectorKey: String, selectorValue: String) -> Response {
@@ -505,580 +525,6 @@ extension RunnerTests {
     return performCoordinateDrag(app: app, x: x, y: y, x2: x2, y2: y2, holdDuration: holdDuration)
   }
 
-  func synthesizedDragAt(
-    app: XCUIApplication,
-    x: Double,
-    y: Double,
-    x2: Double,
-    y2: Double,
-    durationMs: Double,
-    profile: SynthesizedDragProfile = .continuous,
-    context: SynthesizedCoordinateContext? = nil
-  ) -> RunnerInteractionOutcome {
-#if os(iOS)
-    guard x.isFinite, y.isFinite, x2.isFinite, y2.isFinite else {
-      return .unsupported(
-        message: "synthesized coordinate drag requires finite coordinates",
-        hint: "Retry with finite x, y, x2, and y2 values."
-      )
-    }
-    let orientation = Int(RunnerSynthesizedGesture.interfaceOrientation(forApplication: app))
-    guard let context = context ?? synthesizedCoordinateContext(
-      app: app,
-      policy: synthesizedGesturePolicy(.synthesizedDrag)
-    ) else {
-      return .unsupported(
-        message: "synthesized coordinate drag could not resolve a finite screen frame",
-        hint: "Retry after the app is foregrounded, or use a plain screenshot to choose coordinates."
-      )
-    }
-    let frame = context.referenceFrame
-    let start = CoordinateSpaceRotation.native(
-      point: CGPoint(x: x, y: y),
-      in: frame,
-      interfaceOrientation: orientation
-    )
-    let end = CoordinateSpaceRotation.native(
-      point: CGPoint(x: x2, y: y2),
-      in: frame,
-      interfaceOrientation: orientation
-    )
-    let message = switch profile {
-    case .continuous:
-      RunnerSynthesizedGesture.synthesizeContinuousDrag(
-        withApplication: app,
-        x: Double(start.x),
-        y: Double(start.y),
-        x2: Double(end.x),
-        y2: Double(end.y),
-        durationMs: durationMs
-      )
-    case .controlledScroll:
-      RunnerSynthesizedGesture.synthesizeControlledScroll(
-        withApplication: app,
-        x: Double(start.x),
-        y: Double(start.y),
-        x2: Double(end.x),
-        y2: Double(end.y),
-        durationMs: durationMs
-      )
-    case .fastSwipe:
-      RunnerSynthesizedGesture.synthesizeSwipe(
-        withApplication: app,
-        x: Double(start.x),
-        y: Double(start.y),
-        x2: Double(end.x),
-        y2: Double(end.y),
-        durationMs: durationMs
-      )
-    }
-    if let message {
-      return .unsupported(
-        message: message,
-        hint: "Private XCTest event synthesis is required for AX-free coordinate drag on iOS; update Xcode if this persists."
-      )
-    }
-    return .performed
-#elseif os(tvOS)
-    return .unsupported(
-      message: "coordinate drag is not supported on tvOS",
-      hint: "tvOS has no coordinate input; use remote-driven swipe/scroll to move focus instead."
-    )
-#else
-    return .unsupported(
-      message: "coordinate drag is not supported on macOS",
-      hint: "macOS automation has no touchscreen; use mouse-driven interactions instead."
-    )
-#endif
-  }
-
-  func synthesizedTapAt(
-    app: XCUIApplication,
-    x: Double,
-    y: Double,
-    context: SynthesizedCoordinateContext? = nil
-  ) -> RunnerInteractionOutcome {
-#if os(iOS)
-    guard x.isFinite, y.isFinite else {
-      return .unsupported(
-        message: "synthesized coordinate tap requires finite coordinates",
-        hint: "Retry with finite x and y values."
-      )
-    }
-    let orientation = Int(RunnerSynthesizedGesture.interfaceOrientation(forApplication: app))
-    guard let context = context ?? synthesizedCoordinateContext(
-      app: app,
-      policy: synthesizedGesturePolicy(.coordinateTap)
-    ) else {
-      return .unsupported(
-        message: "synthesized coordinate tap could not resolve a finite screen frame",
-        hint: "Retry after the app is foregrounded, or use a plain screenshot to choose coordinates."
-      )
-    }
-    let frame = context.referenceFrame
-    let point = CoordinateSpaceRotation.native(
-      point: CGPoint(x: x, y: y),
-      in: frame,
-      interfaceOrientation: orientation
-    )
-    if let message = RunnerSynthesizedGesture.synthesizeTap(
-      withApplication: app,
-      x: Double(point.x),
-      y: Double(point.y)
-    ) {
-      return .unsupported(
-        message: message,
-        hint: "Falling back to XCTest coordinate tap may be slower and can still need a healthy accessibility tree."
-      )
-    }
-    return .performed
-#elseif os(tvOS)
-    return .unsupported(
-      message: "coordinate tap is not supported on tvOS; move focus with swipe or scroll, then select the focused element",
-      hint: "tvOS has no coordinate input; move focus with swipe/scroll to the target, then select it."
-    )
-#else
-    return .unsupported(
-      message: "synthesized coordinate tap is not supported on macOS",
-      hint: "macOS automation has no touchscreen; use mouse-driven interactions instead."
-    )
-#endif
-  }
-
-  func keyboardAvoidingDragPoints(
-    app: XCUIApplication,
-    x: Double,
-    y: Double,
-    x2: Double,
-    y2: Double
-  ) -> DragPoints {
-    let original = DragPoints(x: x, y: y, x2: x2, y2: y2)
-#if os(iOS)
-    guard let keyboardFrame = visibleKeyboardFrame(app: app) else {
-      return original
-    }
-    let minX = min(x, x2)
-    let minY = min(y, y2)
-    let gestureBounds = CGRect(
-      x: CGFloat(minX),
-      y: CGFloat(minY),
-      width: CGFloat(max(abs(x2 - x), 1)),
-      height: CGFloat(max(abs(y2 - y), 1))
-    )
-    guard gestureBounds.intersects(keyboardFrame) else {
-      return original
-    }
-
-    let window = app.windows.firstMatch
-    let appFrame = window.exists && !window.frame.isEmpty ? window.frame : app.frame
-    guard !appFrame.isEmpty else {
-      return original
-    }
-
-    let padding: Double = 12
-    let targetMaxY = Double(keyboardFrame.minY) - padding
-    let currentMaxY = max(y, y2)
-    let shift = currentMaxY - targetMaxY
-    guard shift > 0 else {
-      return original
-    }
-
-    let adjustedY = y - shift
-    let adjustedY2 = y2 - shift
-    guard min(adjustedY, adjustedY2) >= Double(appFrame.minY) + padding else {
-      return original
-    }
-
-    NSLog(
-      "AGENT_DEVICE_RUNNER_KEYBOARD_AVOIDING_DRAG from=(%.1f,%.1f)->(%.1f,%.1f) adjusted=(%.1f,%.1f)->(%.1f,%.1f) keyboardMinY=%.1f",
-      x,
-      y,
-      x2,
-      y2,
-      x,
-      adjustedY,
-      x2,
-      adjustedY2,
-      Double(keyboardFrame.minY)
-    )
-    return DragPoints(x: x, y: adjustedY, x2: x2, y2: adjustedY2)
-#else
-    return original
-#endif
-  }
-
-  func resolvedTouchVisualizationFrame(app: XCUIApplication, x: Double, y: Double) -> TouchVisualizationFrame {
-    let appFrame = app.frame
-    let referenceFrame = resolvedTouchReferenceFrame(app: app, appFrame: appFrame)
-    let originX = appFrame.isEmpty ? referenceFrame.minX : appFrame.minX
-    let originY = appFrame.isEmpty ? referenceFrame.minY : appFrame.minY
-    return TouchVisualizationFrame(
-      x: originX + x,
-      y: originY + y,
-      referenceWidth: referenceFrame.width,
-      referenceHeight: referenceFrame.height
-    )
-  }
-
-  func resolvedDragVisualizationFrame(
-    app: XCUIApplication,
-    x: Double,
-    y: Double,
-    x2: Double,
-    y2: Double
-  ) -> DragVisualizationFrame {
-    let start = resolvedTouchVisualizationFrame(app: app, x: x, y: y)
-    let end = resolvedTouchVisualizationFrame(app: app, x: x2, y: y2)
-    return DragVisualizationFrame(
-      x: start.x,
-      y: start.y,
-      x2: end.x,
-      y2: end.y,
-      referenceWidth: start.referenceWidth,
-      referenceHeight: start.referenceHeight
-    )
-  }
-
-  func resolvedTouchReferenceFrame(app: XCUIApplication, appFrame: CGRect) -> CGRect {
-    let window = app.windows.firstMatch
-    if window.exists {
-      let windowFrame = window.frame
-      if !windowFrame.isEmpty {
-        return frameAvoidingKeyboard(app: app, frame: windowFrame)
-      }
-    }
-    if !appFrame.isEmpty {
-      return frameAvoidingKeyboard(app: app, frame: appFrame)
-    }
-    return CGRect(x: 0, y: 0, width: 0, height: 0)
-  }
-
-  private func frameAvoidingKeyboard(app: XCUIApplication, frame: CGRect) -> CGRect {
-#if os(iOS)
-    guard let keyboardFrame = visibleKeyboardFrame(app: app), !frame.isEmpty else {
-      return frame
-    }
-    let intersection = frame.intersection(keyboardFrame)
-    guard !intersection.isNull && intersection.height > 0 else {
-      return frame
-    }
-    let keyboardCoverage = intersection.width / max(frame.width, 1)
-    guard keyboardCoverage >= 0.5 else {
-      return frame
-    }
-    let safeHeight = keyboardFrame.minY - frame.minY
-    guard safeHeight >= frame.height * 0.25 else {
-      return frame
-    }
-    return CGRect(x: frame.minX, y: frame.minY, width: frame.width, height: safeHeight)
-#else
-    return frame
-#endif
-  }
-
-  func axFreeSynthesizedDragPlan(
-    app: XCUIApplication,
-    x: Double,
-    y: Double,
-    x2: Double,
-    y2: Double,
-    context: SynthesizedCoordinateContext? = nil
-  ) -> SynthesizedDragPlan? {
-#if os(iOS)
-    let context = context ?? synthesizedCoordinateContext(
-      app: app,
-      policy: synthesizedGesturePolicy(.synthesizedDrag)
-    )
-    guard x.isFinite, y.isFinite, x2.isFinite, y2.isFinite,
-      let context
-    else {
-      return nil
-    }
-    let points = keyboardAvoidingSynthesizedDragPoints(
-      app: app,
-      x: x,
-      y: y,
-      x2: x2,
-      y2: y2,
-      context: context
-    )
-    return SynthesizedDragPlan(
-      points: points,
-      context: context
-    )
-#else
-    return nil
-#endif
-  }
-
-  func axFreeDragVisualizationFrame(
-    x: Double,
-    y: Double,
-    x2: Double,
-    y2: Double,
-    referenceFrame: CGRect
-  ) -> DragVisualizationFrame {
-    return DragVisualizationFrame(
-      x: x,
-      y: y,
-      x2: x2,
-      y2: y2,
-      referenceWidth: Double(referenceFrame.width),
-      referenceHeight: Double(referenceFrame.height)
-    )
-  }
-
-  func synthesizedCoordinateContext(
-    app: XCUIApplication,
-    policy: SynthesizedGesturePolicy
-  ) -> SynthesizedCoordinateContext? {
-#if os(iOS)
-    let health = runnerAccessibilityHealth
-    let orientation = Int(
-      RunnerSynthesizedGesture.interfaceOrientation(forApplication: app)
-    )
-    guard let referenceFrame = orientedSynthesizedScreenshotReferenceFrame(
-      screenshotSize: XCUIScreen.main.screenshot().image.size,
-      interfaceOrientation: orientation
-    ) else {
-      return nil
-    }
-    return SynthesizedCoordinateContext(
-      referenceFrame: referenceFrame,
-      keyboardPolicy: policy.keyboardPolicy,
-      fallbackPolicy: policy.fallbackPolicy,
-      accessibilityHealth: health
-    )
-#else
-    return nil
-#endif
-  }
-
-  func orientedSynthesizedScreenshotReferenceFrame(
-    screenshotSize: CGSize,
-    interfaceOrientation: Int
-  ) -> CGRect? {
-    // Physical iOS screenshots can retain portrait dimensions after the interface rotates,
-    // while accessibility frames remain in the logical landscape coordinate space.
-    guard screenshotSize.width.isFinite, screenshotSize.height.isFinite,
-      screenshotSize.width > 0,
-      screenshotSize.height > 0
-    else {
-      return nil
-    }
-    let isLandscape = interfaceOrientation == RunnerInterfaceOrientation.landscapeLeft
-      || interfaceOrientation == RunnerInterfaceOrientation.landscapeRight
-    let isPortrait = interfaceOrientation == RunnerInterfaceOrientation.portrait
-      || interfaceOrientation == RunnerInterfaceOrientation.portraitUpsideDown
-    let width: CGFloat
-    let height: CGFloat
-    if isLandscape {
-      width = max(screenshotSize.width, screenshotSize.height)
-      height = min(screenshotSize.width, screenshotSize.height)
-    } else if isPortrait {
-      width = min(screenshotSize.width, screenshotSize.height)
-      height = max(screenshotSize.width, screenshotSize.height)
-    } else {
-      width = screenshotSize.width
-      height = screenshotSize.height
-    }
-    return CGRect(x: 0, y: 0, width: width, height: height)
-  }
-
-  func keyboardAvoidingSynthesizedDragPoints(
-    app: XCUIApplication,
-    x: Double,
-    y: Double,
-    x2: Double,
-    y2: Double,
-    context: SynthesizedCoordinateContext
-  ) -> DragPoints {
-#if os(iOS)
-    guard context.allowsKeyboardProbe else {
-      return DragPoints(x: x, y: y, x2: x2, y2: y2)
-    }
-    return keyboardAvoidingDragPoints(app: app, x: x, y: y, x2: x2, y2: y2)
-#else
-    return DragPoints(x: x, y: y, x2: x2, y2: y2)
-#endif
-  }
-
-  func swipe(app: XCUIApplication, direction: String) -> DragVisualizationFrame? {
-    if performTvRemoteSwipeIfAvailable(direction: direction) {
-      let frame = resolvedTouchReferenceFrame(app: app, appFrame: app.frame)
-      let midX = frame.midX
-      let midY = frame.midY
-      return DragVisualizationFrame(
-        x: midX,
-        y: midY,
-        x2: midX,
-        y2: midY,
-        referenceWidth: frame.width,
-        referenceHeight: frame.height
-      )
-    }
-    return nil
-  }
-
-  private func performTvRemoteSwipeIfAvailable(direction: String) -> Bool {
-    switch direction {
-    case "up":
-      return pressTvRemote(.up)
-    case "down":
-      return pressTvRemote(.down)
-    case "left":
-      return pressTvRemote(.left)
-    case "right":
-      return pressTvRemote(.right)
-    default:
-      return false
-    }
-  }
-
-  func plannedGestureValidationError(_ plan: RunnerGesturePlan) -> String? {
-    guard plan.topology == "single" || plan.topology == "two" else {
-      return "planned gesture topology must be single or two"
-    }
-    let supportedIntent = plan.topology == "single"
-      ? plan.intent == "fling" || plan.intent == "pan"
-      : plan.intent == "pan" || plan.intent == "pinch" || plan.intent == "rotate"
-        || plan.intent == "transform"
-    guard supportedIntent else { return "planned gesture has unsupported intent for its topology" }
-    if plan.topology == "single" {
-      guard plan.executionProfile == "endpoint-hold" || plan.executionProfile == "timed-pan" else {
-        return "single-pointer gesture requires a supported execution profile"
-      }
-    } else if plan.executionProfile != nil {
-      return "multi-touch gesture cannot define a single-pointer execution profile"
-    }
-    guard plan.durationMs.isFinite, plan.durationMs >= 16, plan.durationMs <= 10_000 else {
-      return "planned gesture durationMs must be between 16 and 10000"
-    }
-    let viewport = plan.viewport
-    guard viewport.x.isFinite, viewport.y.isFinite, viewport.width.isFinite,
-      viewport.height.isFinite, viewport.width > 0, viewport.height > 0
-    else {
-      return "planned gesture viewport must be finite and positive"
-    }
-    let expectedPointerCount = plan.topology == "single" ? 1 : 2
-    guard plan.pointers.count == expectedPointerCount else {
-      return "planned gesture pointer count does not match topology"
-    }
-    for (index, pointer) in plan.pointers.enumerated() where pointer.pointerId != index {
-      return "planned gesture requires ordered pointer ids"
-    }
-    let firstSamples = plan.pointers[0].samples
-    guard firstSamples.count >= 2 else { return "planned pointer paths require at least two samples" }
-    for pointer in plan.pointers {
-      guard pointer.samples.count == firstSamples.count else {
-        return "planned pointer paths require matching samples"
-      }
-      var previousOffset = -1.0
-      for (index, sample) in pointer.samples.enumerated() {
-        guard sample.offsetMs.isFinite,
-          sample.offsetMs == firstSamples[index].offsetMs,
-          sample.offsetMs > previousOffset
-        else {
-          return "planned pointer sample offsets must match and strictly increase"
-        }
-        let point = sample.point
-        guard point.x.isFinite, point.y.isFinite,
-          point.x >= viewport.x,
-          point.x <= viewport.x + viewport.width,
-          point.y >= viewport.y,
-          point.y <= viewport.y + viewport.height
-        else {
-          return "planned pointer sample lies outside the viewport"
-        }
-        previousOffset = sample.offsetMs
-      }
-      guard pointer.samples.first?.offsetMs == 0,
-        pointer.samples.last?.offsetMs == plan.durationMs
-      else {
-        return "planned pointer paths must start at 0 and end at durationMs"
-      }
-    }
-    if plan.topology == "two" {
-      guard let firstStart = firstSamples.first?.point,
-        let secondStart = plan.pointers[1].samples.first?.point,
-        hypot(firstStart.x - secondStart.x, firstStart.y - secondStart.y) > 0
-      else {
-        return "planned pointer paths require a positive initial span"
-      }
-    }
-    return nil
-  }
-
-  func plannedGestureExecution(for plan: RunnerGesturePlan) -> PlannedGestureExecution {
-    plan.topology == "single" && plan.executionProfile == "endpoint-hold"
-      ? .fastSwipe
-      : .sampled
-  }
-
-  func sampledPlannedGesture(
-    app: XCUIApplication,
-    plan: RunnerGesturePlan
-  ) -> RunnerInteractionOutcome {
-#if os(iOS)
-    let orientation = Int(RunnerSynthesizedGesture.interfaceOrientation(forApplication: app))
-    // The portable planner and validation use this exact viewport. Using app.frame here can
-    // diverge when XCTest unions transformed/off-screen descendants into the application frame.
-    let frame = CGRect(
-      x: plan.viewport.x,
-      y: plan.viewport.y,
-      width: plan.viewport.width,
-      height: plan.viewport.height
-    )
-    let pointerSamples: [[[String: NSNumber]]] = plan.pointers.map { pointer in
-      pointer.samples.map { sample in
-        let point = CoordinateSpaceRotation.native(
-          point: CGPoint(x: sample.point.x, y: sample.point.y),
-          in: frame,
-          interfaceOrientation: orientation
-        )
-        return [
-          "x": NSNumber(value: Double(point.x)),
-          "y": NSNumber(value: Double(point.y)),
-          "offsetMs": NSNumber(value: sample.offsetMs),
-        ]
-      }
-    }
-    if let message = RunnerSynthesizedGesture.synthesizeGesture(
-      withApplication: app,
-      pointerSamples: pointerSamples
-    ) {
-      return .unsupported(
-        message: message,
-        hint: "This gesture uses private XCTest event-synthesis APIs; rebuild the runner with a supported Xcode if this persists."
-      )
-    }
-    return .performed
-#elseif os(tvOS)
-    return .unsupported(
-      message: "two-finger gestures are not supported on tvOS",
-      hint: "tvOS has no touch input; use remote-driven navigation."
-    )
-#elseif os(visionOS)
-    return .unsupported(
-      message: "two-finger touch gestures are not supported on visionOS",
-      hint: "The current XCTest synthesizer supports iOS and iPadOS touch simulators only."
-    )
-#else
-    return .unsupported(
-      message: "two-finger gestures are not supported on macOS",
-      hint: "macOS automation has no multi-touch input; run on an iOS simulator."
-    )
-#endif
-  }
-
-  private func interactionRoot(app: XCUIApplication) -> XCUIElement {
-    let windows = app.windows.allElementsBoundByIndex
-    if let window = windows.first(where: { $0.exists && !$0.frame.isEmpty }) {
-      return window
-    }
-    return app
-  }
-
   private func performCoordinateTap(app: XCUIApplication, x: Double, y: Double) -> RunnerInteractionOutcome {
 #if os(tvOS)
     return .unsupported(
@@ -1139,167 +585,26 @@ extension RunnerTests {
 #if !os(tvOS)
   private func interactionCoordinate(app: XCUIApplication, x: Double, y: Double) -> XCUICoordinate {
 #if os(iOS)
+    // Coordinate taps, double taps, long presses, and drags anchor at the app origin, not the
+    // resolved window: on iOS the snapshot hands back app-space points, and the first qualifying
+    // window is not always the one under the finger — a SpringBoard `alert accept` can live in an
+    // alert window while the wallpaper or status-bar window qualifies first, so a window-relative
+    // anchor misses the button. Reference frames and the synthesized display ID still resolve
+    // through `resolveRunnerWindow`, so a foldable tap keeps its panel and stays on its display.
     let origin = app.coordinate(withNormalizedOffset: CGVector(dx: 0, dy: 0))
     return origin.withOffset(CGVector(dx: x, dy: y))
 #else
-    let root = interactionRoot(app: app)
+    let resolved = resolveRunnerWindow(app: app)
+    let root = resolved.window ?? app
     let origin = root.coordinate(withNormalizedOffset: CGVector(dx: 0, dy: 0))
-    let rootFrame = root.frame
-    let offsetX = x - Double(rootFrame.origin.x)
-    let offsetY = y - Double(rootFrame.origin.y)
+    let offsetX = x - Double(resolved.frame.origin.x)
+    let offsetY = y - Double(resolved.frame.origin.y)
     return origin.withOffset(CGVector(dx: offsetX, dy: offsetY))
 #endif
   }
 #endif
 
 #if AGENT_DEVICE_RUNNER_UNIT_TESTS
-  func testSynthesizedScreenshotReferenceFrameUsesScreenshotSize() throws {
-    let resolved = try XCTUnwrap(
-      orientedSynthesizedScreenshotReferenceFrame(
-        screenshotSize: CGSize(width: 430, height: 932),
-        interfaceOrientation: RunnerInterfaceOrientation.portrait
-      )
-    )
-
-    XCTAssertEqual(resolved, CGRect(x: 0, y: 0, width: 430, height: 932))
-  }
-
-  func testOrientedSynthesizedScreenshotReferenceFrameUsesLandscapeLogicalDimensions() {
-    let portraitCapture = CGSize(width: 430, height: 932)
-    let landscapeCapture = CGSize(width: 932, height: 430)
-
-    for orientation in [
-      RunnerInterfaceOrientation.landscapeLeft,
-      RunnerInterfaceOrientation.landscapeRight,
-    ] {
-      XCTAssertEqual(
-        orientedSynthesizedScreenshotReferenceFrame(
-          screenshotSize: portraitCapture,
-          interfaceOrientation: orientation
-        ),
-        CGRect(x: 0, y: 0, width: 932, height: 430)
-      )
-      XCTAssertEqual(
-        orientedSynthesizedScreenshotReferenceFrame(
-          screenshotSize: landscapeCapture,
-          interfaceOrientation: orientation
-        ),
-        CGRect(x: 0, y: 0, width: 932, height: 430)
-      )
-    }
-
-    for orientation in [
-      RunnerInterfaceOrientation.portrait,
-      RunnerInterfaceOrientation.portraitUpsideDown,
-    ] {
-      XCTAssertEqual(
-        orientedSynthesizedScreenshotReferenceFrame(
-          screenshotSize: portraitCapture,
-          interfaceOrientation: orientation
-        ),
-        CGRect(x: 0, y: 0, width: 430, height: 932)
-      )
-      XCTAssertEqual(
-        orientedSynthesizedScreenshotReferenceFrame(
-          screenshotSize: landscapeCapture,
-          interfaceOrientation: orientation
-        ),
-        CGRect(x: 0, y: 0, width: 430, height: 932)
-      )
-    }
-
-    XCTAssertEqual(
-      orientedSynthesizedScreenshotReferenceFrame(
-        screenshotSize: landscapeCapture,
-        interfaceOrientation: RunnerInterfaceOrientation.unknown
-      ),
-      CGRect(x: 0, y: 0, width: 932, height: 430)
-    )
-  }
-
-  func testSynthesizedScreenshotReferenceFrameRejectsInvalidSize() {
-    XCTAssertNil(
-      orientedSynthesizedScreenshotReferenceFrame(
-        screenshotSize: CGSize(width: CGFloat.infinity, height: 932),
-        interfaceOrientation: RunnerInterfaceOrientation.portrait
-      )
-    )
-  }
-
-  func testPlannedMultiTouchGestureAcceptsMatchingInBoundsTrajectories() throws {
-    let plan = try JSONDecoder().decode(
-      RunnerGesturePlan.self,
-      from: Data(
-        #"{"topology":"two","intent":"pan","durationMs":32,"viewport":{"x":0,"y":0,"width":200,"height":300},"pointers":[{"pointerId":0,"samples":[{"offsetMs":0,"point":{"x":80,"y":80}},{"offsetMs":16,"point":{"x":90,"y":85}},{"offsetMs":32,"point":{"x":100,"y":90}}]},{"pointerId":1,"samples":[{"offsetMs":0,"point":{"x":80,"y":120}},{"offsetMs":16,"point":{"x":90,"y":125}},{"offsetMs":32,"point":{"x":100,"y":130}}]}]}"#.utf8
-      )
-    )
-
-    XCTAssertNil(plannedGestureValidationError(plan))
-    XCTAssertEqual(plannedGestureExecution(for: plan), .sampled)
-  }
-
-  func testPlannedMultiTouchGestureRejectsMismatchedOffsets() throws {
-    let plan = try JSONDecoder().decode(
-      RunnerGesturePlan.self,
-      from: Data(
-        #"{"topology":"two","intent":"transform","durationMs":32,"viewport":{"x":0,"y":0,"width":200,"height":300},"pointers":[{"pointerId":0,"samples":[{"offsetMs":0,"point":{"x":80,"y":80}},{"offsetMs":32,"point":{"x":100,"y":90}}]},{"pointerId":1,"samples":[{"offsetMs":0,"point":{"x":80,"y":120}},{"offsetMs":31,"point":{"x":100,"y":130}}]}]}"#.utf8
-      )
-    )
-
-    XCTAssertEqual(
-      plannedGestureValidationError(plan),
-      "planned pointer sample offsets must match and strictly increase"
-    )
-  }
-
-  func testSinglePointerFlingUsesFastSwipeExecution() throws {
-    let plan = try JSONDecoder().decode(
-      RunnerGesturePlan.self,
-      from: Data(
-        #"{"topology":"single","intent":"fling","executionProfile":"endpoint-hold","durationMs":100,"viewport":{"x":0,"y":0,"width":200,"height":300},"pointers":[{"pointerId":0,"samples":[{"offsetMs":0,"point":{"x":160,"y":150}},{"offsetMs":100,"point":{"x":40,"y":150}}]}]}"#.utf8
-      )
-    )
-
-    XCTAssertEqual(plannedGestureExecution(for: plan), .fastSwipe)
-  }
-
-  func testSinglePointerTimedPanUsesSampledExecution() throws {
-    let plan = try JSONDecoder().decode(
-      RunnerGesturePlan.self,
-      from: Data(
-        #"{"topology":"single","intent":"pan","executionProfile":"timed-pan","durationMs":500,"viewport":{"x":0,"y":0,"width":200,"height":300},"pointers":[{"pointerId":0,"samples":[{"offsetMs":0,"point":{"x":160,"y":150}},{"offsetMs":250,"point":{"x":100,"y":150}},{"offsetMs":500,"point":{"x":40,"y":150}}]}]}"#.utf8
-      )
-    )
-
-    XCTAssertEqual(plannedGestureExecution(for: plan), .sampled)
-  }
-
-  func testSinglePointerEndpointHoldUsesFastSwipeExecution() throws {
-    let plan = try JSONDecoder().decode(
-      RunnerGesturePlan.self,
-      from: Data(
-        #"{"topology":"single","intent":"pan","executionProfile":"endpoint-hold","durationMs":500,"viewport":{"x":0,"y":0,"width":200,"height":300},"pointers":[{"pointerId":0,"samples":[{"offsetMs":0,"point":{"x":160,"y":150}},{"offsetMs":500,"point":{"x":40,"y":150}}]}]}"#.utf8
-      )
-    )
-
-    XCTAssertNil(plannedGestureValidationError(plan))
-    XCTAssertEqual(plannedGestureExecution(for: plan), .fastSwipe)
-  }
-
-  func testSinglePointerGestureRejectsMissingExecutionProfile() throws {
-    let plan = try JSONDecoder().decode(
-      RunnerGesturePlan.self,
-      from: Data(
-        #"{"topology":"single","intent":"pan","durationMs":500,"viewport":{"x":0,"y":0,"width":200,"height":300},"pointers":[{"pointerId":0,"samples":[{"offsetMs":0,"point":{"x":160,"y":150}},{"offsetMs":500,"point":{"x":40,"y":150}}]}]}"#.utf8
-      )
-    )
-
-    XCTAssertEqual(
-      plannedGestureValidationError(plan),
-      "single-pointer gesture requires a supported execution profile"
-    )
-  }
-
   func testDesktopScrollWheelDeltasMapDirections() {
     XCTAssertEqual(desktopScrollWheelDeltas(direction: .up, pixels: 120).vertical, 120)
     XCTAssertEqual(desktopScrollWheelDeltas(direction: .down, pixels: 120).vertical, -120)
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Snapshot.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Snapshot.swift
index 40b23e6a08..04e83a38f3 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Snapshot.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Snapshot.swift
@@ -2,11 +2,11 @@ import XCTest
 import AgentDeviceSnapshotPresentation
 
 extension RunnerTests {
-  private static let axSnapshotErrorCode = "IOS_AX_SNAPSHOT_FAILED"
-  private static let axSnapshotFailureMessage =
+  static let axSnapshotErrorCode = "IOS_AX_SNAPSHOT_FAILED"
+  static let axSnapshotFailureMessage =
     "iOS XCTest snapshot failed while serializing the accessibility tree."
   private static let axSnapshotUnavailableReason = "ax_snapshot_unavailable"
-  private static let axSnapshotHint =
+  static let axSnapshotHint =
     "Snapshot state is unavailable because XCTest could not serialize this iOS accessibility tree. This can be specific to the current screen. Use plain screenshot, not screenshot --overlay-refs, as visual truth; navigate with coordinate commands if needed; then retry snapshot -i after reaching another screen. If you own the app and need full-tree inspection, simplify this screen's accessibility tree and expose stable ids on actionable controls."
   private static let rawSnapshotTooLargeCode = "IOS_RAW_SNAPSHOT_TOO_LARGE"
   private static let rawSnapshotMaxNodes = 5_000
@@ -32,7 +32,7 @@ extension RunnerTests {
     let keyboardBand: RunnerKeyboardBandFact?
   }
 
-  private struct SnapshotEvaluation {
+  struct SnapshotEvaluation {
     let label: String
     let identifier: String
     let valueText: String?
@@ -117,7 +117,7 @@ extension RunnerTests {
     "ScrollView"
   ]
 
-  private static let collapsedTabCandidateTypes: Set<XCUIElement.ElementType> = [
+  static let collapsedTabCandidateTypes: Set<XCUIElement.ElementType> = [
     .button,
     .link,
     .menuItem,
@@ -800,561 +800,4 @@ extension RunnerTests {
   }
 #endif
 
-  private func interactiveRootNode(rect: CGRect) -> RawAXNode {
-    RawAXNode(
-      index: 0,
-      type: "Application",
-      label: nil,
-      identifier: nil,
-      value: nil,
-      rect: SnapshotRect(rect),
-      enabled: true,
-      focused: nil,
-      selected: nil,
-      hittable: false,
-      depth: 0,
-      parentIndex: nil,
-      hiddenContentAbove: nil,
-      hiddenContentBelow: nil
-    )
-  }
-
-  private func interactiveRootFrame(for candidates: [RawAXNode]) -> CGRect {
-    guard !candidates.isEmpty else {
-      return .zero
-    }
-    let maxX = candidates.map { CGFloat($0.rect.x + $0.rect.width) }.max() ?? 0
-    let maxY = candidates.map { CGFloat($0.rect.y + $0.rect.height) }.max() ?? 0
-    return CGRect(x: 0, y: 0, width: max(1, maxX), height: max(1, maxY))
-  }
-
-  // MARK: - Snapshot Filtering
-
-  func makeSnapshotTraversalContext(
-    app: XCUIApplication,
-    hint: CaptureHint,
-    captureDeadline: Date = .distantFuture,
-    treeCaptureSliceBudgetOverride: TimeInterval? = nil
-  ) throws -> SnapshotTraversalContext? {
-    // The viewport and the interface orientation are one hop: geometry that arrives in the device's
-    // native space can only be placed relative to the app's own frame and rotation, and asking for
-    // the pair twice would read them at two different moments of a rotation.
-    let geometry = try runMainThreadWork(
-      "snapshot_viewport",
-      timeout: min(1.0, max(0.1, captureDeadline.timeIntervalSinceNow)),
-      timeoutError: snapshotMainThreadTimeoutError("preparing tree snapshot")
-    ) {
-      (
-        viewport: self.safeSnapshotViewport(app: app),
-        interfaceOrientation: self.capturedInterfaceOrientation(app: app)
-      )
-    }
-    let viewport = geometry.viewport
-    let interfaceOrientation = geometry.interfaceOrientation
-    let treeSliceBudget = treeCaptureSliceBudgetOverride ?? treeCaptureSliceBudget
-    let slice = min(treeSliceBudget, max(0.5, captureDeadline.timeIntervalSinceNow))
-    guard let rootSnapshot = try captureSnapshotRootBounded(app, sliceSeconds: slice) else {
-      return nil
-    }
-
-    // Read after the tree, so the band is never older than the tree it will be compared against: a
-    // keyboard that appeared while the tree was being captured would otherwise publish `absent`
-    // beside key nodes that the tap guard would then have to trust less than the absence (#2660).
-    // It keeps its own hop and slice rather than joining the geometry pair above, because a keyboard
-    // this capture cannot measure must cost the fact and not the tree tier behind it.
-    let keyboardBand = captureKeyboardBandFact(app: app, deadline: captureDeadline)
-
-    return SnapshotTraversalContext(
-      queryRoot: app,
-      rootSnapshot: rootSnapshot,
-      viewport: viewport,
-      interfaceOrientation: interfaceOrientation,
-      keyboardBand: keyboardBand
-    )
-  }
-
-  static let xCTestSnapshotTimeoutCode = "IOS_TREE_CAPTURE_TIMEOUT"
-
-  /// Runs the blocking tree-snapshot XPC on the main thread bounded by `sliceSeconds`. On
-  /// timeout the XPC keeps running on main (it cannot be cancelled); the capture is marked
-  /// abandoned so plans avoid XCTest-backed tiers until it drains, the timed-out attempt
-  /// penalizes the tree backend for this bundle (unless the fresh-process warmup exemption
-  /// applies), and the plan moves to the platform's independent recovery tier when one exists
-  /// (#1105/#1122).
-  private func captureSnapshotRootBounded(
-    _ element: XCUIElement,
-    sliceSeconds: TimeInterval
-  ) throws -> XCUIElementSnapshot? {
-    if Thread.isMainThread {
-      return try captureSnapshotRoot(element)
-    }
-    return try runMainThreadWork(
-      "tree_capture",
-      timeout: sliceSeconds,
-      timeoutError: treeCaptureTimeoutError(sliceSeconds: sliceSeconds)
-    ) {
-      try self.captureSnapshotRoot(element)
-    }
-  }
-
-  private func treeCaptureTimeoutError(sliceSeconds: TimeInterval) -> () -> Error {
-    {
-      SnapshotCaptureFailure(
-        code: Self.xCTestSnapshotTimeoutCode,
-        message: "the XCTest tree capture exceeded its \(Int(sliceSeconds))s time slice",
-        hint: "The capture plan will avoid or tightly bound XCTest-backed snapshot tiers on this screen."
-      )
-    }
-  }
-
-  func snapshotMainThreadTimeoutError(_ operation: String) -> () -> Error {
-    {
-      SnapshotCaptureFailure(
-        code: Self.xCTestSnapshotTimeoutCode,
-        message: "timed out while \(operation) on the XCTest main thread",
-        hint: "The capture plan will skip XCTest-backed snapshot tiers while the previous main-thread work drains."
-      )
-    }
-  }
-
-  private func captureSnapshotRoot(_ element: XCUIElement) throws -> XCUIElementSnapshot? {
-    var rootSnapshot: XCUIElementSnapshot?
-    var swiftErrorMessage: String?
-    let exceptionMessage = RunnerObjCExceptionCatcher.catchException({
-      do {
-        rootSnapshot = try element.snapshot()
-      } catch {
-        swiftErrorMessage = describeSnapshotError(error)
-      }
-    })
-
-    if let rootSnapshot {
-      return rootSnapshot
-    }
-    let message = exceptionMessage ?? swiftErrorMessage ?? "snapshot returned no root"
-    if Self.isAxIllegalArgument(message) {
-      throw axSnapshotFailure(message)
-    }
-    return nil
-  }
-
-  func safeSnapshotViewport(app: XCUIApplication) -> CGRect {
-    safely("SNAPSHOT_VIEWPORT", CGRect.infinite) { snapshotViewport(app: app) }
-  }
-
-  private func describeSnapshotError(_ error: Error) -> String {
-    let localized = error.localizedDescription
-    let debug = String(describing: error)
-    if localized.isEmpty { return debug }
-    if debug == localized { return localized }
-    return "\(localized) (\(debug))"
-  }
-
-  private func axSnapshotFailure(_ message: String) -> SnapshotCaptureFailure {
-    let detail = message.trimmingCharacters(in: .whitespacesAndNewlines)
-    let failureMessage: String
-    if detail.isEmpty {
-      failureMessage = Self.axSnapshotFailureMessage
-    } else {
-      failureMessage = "\(Self.axSnapshotFailureMessage) \(detail)"
-    }
-    return SnapshotCaptureFailure(
-      code: Self.axSnapshotErrorCode,
-      message: failureMessage,
-      hint: Self.axSnapshotHint
-    )
-  }
-
-  private static func isAxIllegalArgument(_ message: String) -> Bool {
-    let normalized = message.lowercased()
-    return normalized.contains("kaxerrorillegalargument")
-      || (normalized.contains("illegal argument") && normalized.contains("snapshot"))
-  }
-
-  static func isAxSnapshotFailure(_ failure: SnapshotCaptureFailure) -> Bool {
-    failure.code == Self.axSnapshotErrorCode || isAxIllegalArgument(failure.message)
-  }
-
-  private func evaluateSnapshot(_ snapshot: XCUIElementSnapshot) -> SnapshotEvaluation {
-    let label = aggregatedLabel(for: snapshot) ?? snapshot.label.trimmingCharacters(in: .whitespacesAndNewlines)
-    let identifier = snapshot.identifier.trimmingCharacters(in: .whitespacesAndNewlines)
-    let valueText = snapshotValueText(snapshot)
-    return SnapshotEvaluation(
-      label: label,
-      identifier: identifier,
-      valueText: valueText,
-      focused: snapshotHasFocus(snapshot),
-      selected: snapshotIsSelected(snapshot)
-    )
-  }
-
-  private func makeSnapshotNode(
-    snapshot: XCUIElementSnapshot,
-    evaluation: SnapshotEvaluation,
-    depth: Int,
-    index: Int,
-    parentIndex: Int?
-  ) -> RawAXNode {
-    // Acquisition carries the frame the platform reported; `SnapshotGeometrySpace.normalized` turns
-    // it into the app's orientation space and recomputes `hittable` from that one pass (#2661).
-    return RawAXNode(
-      index: index,
-      type: elementTypeName(snapshot.elementType),
-      label: evaluation.label.isEmpty ? nil : evaluation.label,
-      identifier: evaluation.identifier.isEmpty ? nil : evaluation.identifier,
-      value: evaluation.valueText,
-      rect: SnapshotRect(snapshot.frame),
-      enabled: snapshot.isEnabled,
-      focused: evaluation.focused ? true : nil,
-      selected: evaluation.selected ? true : nil,
-      hittable: false,
-      depth: depth,
-      parentIndex: parentIndex,
-      hiddenContentAbove: nil,
-      hiddenContentBelow: nil
-    )
-  }
-
-  /// The app's own interface orientation: the fact that names which way the device's native space is
-  /// turned from the space the capture publishes. Unreadable or unnamed means no rotation.
-  func capturedInterfaceOrientation(app: XCUIApplication) -> Int {
-    safely("SNAPSHOT_INTERFACE_ORIENTATION", RunnerInterfaceOrientation.unknown) {
-      Int(RunnerSynthesizedGesture.interfaceOrientation(forApplication: app))
-    }
-  }
-
-  private func snapshotValueText(_ snapshot: XCUIElementSnapshot) -> String? {
-    guard let value = snapshot.value else { return nil }
-    let text = String(describing: value).trimmingCharacters(in: .whitespacesAndNewlines)
-    return text.isEmpty ? nil : text
-  }
-
-  private func snapshotViewport(app: XCUIApplication) -> CGRect {
-    let appFrame = app.frame
-    if !appFrame.isNull && !appFrame.isEmpty {
-      return appFrame
-    }
-    return .infinite
-  }
-
-  static func snapshotTraversalIdentity(
-    elementType: XCUIElement.ElementType,
-    label: String,
-    identifier: String,
-    frame: CGRect
-  ) -> String {
-    #if os(iOS)
-    "\(elementType)-\(label)-\(identifier)-\(frame.origin.x)-\(frame.origin.y)-\(frame.width)-\(frame.height)"
-    #else
-    return "\(elementType)-\(label)-\(identifier)-\(frame.origin.x)-\(frame.origin.y)"
-    #endif
-  }
-
-  private func aggregatedLabel(for snapshot: XCUIElementSnapshot, depth: Int = 0) -> String? {
-    if depth > 4 { return nil }
-    let text = snapshot.label.trimmingCharacters(in: .whitespacesAndNewlines)
-    if !text.isEmpty { return text }
-    if let valueText = snapshotValueText(snapshot) { return valueText }
-    for child in snapshot.children {
-      if let childLabel = aggregatedLabel(for: child, depth: depth + 1) {
-        return childLabel
-      }
-    }
-    return nil
-  }
-
-  private func appendCollapsedTabFallbackNodes(
-    to nodes: inout [RawAXNode],
-    containerSnapshot: XCUIElementSnapshot,
-    resolveElements: () -> [XCUIElement],
-    depth: Int,
-    parentIndex: Int
-  ) {
-    let fallbackNodes = collapsedTabFallbackNodes(
-      for: containerSnapshot,
-      resolveElements: resolveElements,
-      startingIndex: nodes.count,
-      depth: depth,
-      parentIndex: parentIndex
-    )
-    nodes.append(contentsOf: fallbackNodes)
-  }
-
-  private func collapsedTabFallbackNodes(
-    for containerSnapshot: XCUIElementSnapshot,
-    resolveElements: () -> [XCUIElement],
-    startingIndex: Int,
-    depth: Int,
-    parentIndex: Int
-  ) -> [RawAXNode] {
-    if !containerSnapshot.children.isEmpty { return [] }
-    // This fallback reads live element frames, which XCTest reports in the app's own space, and a
-    // collapsed tab container sits under the app's own window. `SnapshotGeometrySpace.normalized`
-    // keys rotation on ancestry, so these nodes never enter a declared native space and need no
-    // special case here; the containment and area rules below compare reported frames to each other.
-    guard shouldExpandCollapsedTabContainer(containerSnapshot) else { return [] }
-    let containerFrame = containerSnapshot.frame
-    if containerFrame.isNull || containerFrame.isEmpty { return [] }
-
-    // Collapsed tab containers should be rare, so a full descendant scan is acceptable once per
-    // snapshot as a fallback for XCTest omitting the tab children from the snapshot tree.
-    let elements = resolveElements()
-    let candidates = elements.compactMap { element in
-      collapsedTabCandidateNode(
-        element: element,
-        containerSnapshot: containerSnapshot,
-        containerFrame: containerFrame
-      )
-    }
-    .sorted { left, right in
-      if left.rect.x != right.rect.x {
-        return left.rect.x < right.rect.x
-      }
-      return left.rect.y < right.rect.y
-    }
-
-    if candidates.count < 2 { return [] }
-    let rowMidpoints = candidates.map { $0.rect.y + ($0.rect.height / 2) }
-    let rowSpread = (rowMidpoints.max() ?? 0) - (rowMidpoints.min() ?? 0)
-    // Allow modest vertical jitter and short two-row wraps while still rejecting unrelated controls.
-    if rowSpread > max(24.0, Double(containerFrame.height) * 0.6) { return [] }
-
-    var seen = Set<String>()
-    let uniqueCandidates = candidates.filter { node in
-      let key = "\(node.type)-\(node.label ?? "")-\(node.identifier ?? "")-\(node.value ?? "")-\(node.rect.x)-\(node.rect.y)-\(node.rect.width)-\(node.rect.height)"
-      if seen.contains(key) { return false }
-      seen.insert(key)
-      return true
-    }
-    if uniqueCandidates.count < 2 { return [] }
-
-    return uniqueCandidates.enumerated().map { offset, node in
-      RawAXNode(
-        index: startingIndex + offset,
-        type: node.type,
-        label: node.label,
-        identifier: node.identifier,
-        value: node.value,
-        rect: node.rect,
-        enabled: node.enabled,
-        focused: node.focused,
-        selected: node.selected,
-        hittable: node.hittable,
-        depth: depth,
-        parentIndex: parentIndex,
-        hiddenContentAbove: nil,
-        hiddenContentBelow: nil
-      )
-    }
-  }
-
-  private func collapsedTabCandidateNode(
-    element: XCUIElement,
-    containerSnapshot: XCUIElementSnapshot,
-    containerFrame: CGRect
-  ) -> RawAXNode? {
-    var node: RawAXNode?
-    let exceptionMessage = RunnerObjCExceptionCatcher.catchException({
-      if !element.exists { return }
-      let elementType = element.elementType
-      if !Self.collapsedTabCandidateTypes.contains(elementType) { return }
-      let frame = element.frame
-      if frame.isNull || frame.isEmpty { return }
-      if frame.equalTo(containerFrame) { return }
-      let area = max(CGFloat(1), frame.width * frame.height)
-      let containerArea = max(CGFloat(1), containerFrame.width * containerFrame.height)
-      if area >= containerArea * 0.9 { return }
-      let center = CGPoint(x: frame.midX, y: frame.midY)
-      if !containerFrame.contains(center) { return }
-
-      let label = element.label.trimmingCharacters(in: .whitespacesAndNewlines)
-      let identifier = element.identifier.trimmingCharacters(in: .whitespacesAndNewlines)
-      let valueText = snapshotValueText(element)
-      let hasContent = !label.isEmpty || !identifier.isEmpty || valueText != nil
-      if !hasContent { return }
-      if sameSemanticElement(
-        containerSnapshot: containerSnapshot,
-        elementType: elementType,
-        label: label,
-        identifier: identifier
-      ) {
-        return
-      }
-
-      // The containment and area rules above compared reported frames with each other; the node
-      // joins the tree carrying the frame the platform reported, and normalization places it.
-      node = RawAXNode(
-        index: 0,
-        type: elementTypeName(elementType),
-        label: label.isEmpty ? nil : label,
-        identifier: identifier.isEmpty ? nil : identifier,
-        value: valueText,
-        rect: SnapshotRect(frame),
-        enabled: element.isEnabled,
-        focused: elementHasFocus(element) ? true : nil,
-        selected: element.isSelected ? true : nil,
-        hittable: false,
-        depth: 0,
-        parentIndex: nil,
-        hiddenContentAbove: nil,
-        hiddenContentBelow: nil
-      )
-    })
-    if let exceptionMessage {
-      NSLog(
-        "AGENT_DEVICE_RUNNER_SNAPSHOT_TAB_FALLBACK_IGNORED_EXCEPTION=%@",
-        exceptionMessage
-      )
-      return nil
-    }
-    return node
-  }
-
-  private func snapshotHasFocus(_ snapshot: XCUIElementSnapshot) -> Bool {
-    var focused = false
-    _ = RunnerObjCExceptionCatcher.catchException({
-      if let value = (snapshot as! NSObject).value(forKey: "hasFocus") as? Bool {
-        focused = value
-      }
-    })
-    return focused
-  }
-
-  private func snapshotIsSelected(_ snapshot: XCUIElementSnapshot) -> Bool {
-    return snapshot.isSelected
-  }
-
-  private func shouldExpandCollapsedTabContainer(_ snapshot: XCUIElementSnapshot) -> Bool {
-    let frame = snapshot.frame
-    if frame.isNull || frame.isEmpty { return false }
-    if frame.width < max(CGFloat(160), frame.height * 1.75) { return false }
-    switch snapshot.elementType {
-    case .tabBar, .segmentedControl, .slider:
-      return true
-    default:
-      return false
-    }
-  }
-
-  private func snapshotValueText(_ element: XCUIElement) -> String? {
-    let text = String(describing: element.value ?? "")
-      .trimmingCharacters(in: .whitespacesAndNewlines)
-    return text.isEmpty ? nil : text
-  }
-
-  private func sameSemanticElement(
-    containerSnapshot: XCUIElementSnapshot,
-    elementType: XCUIElement.ElementType,
-    label: String,
-    identifier: String
-  ) -> Bool {
-    if containerSnapshot.elementType != elementType { return false }
-    let containerLabel = containerSnapshot.label.trimmingCharacters(in: .whitespacesAndNewlines)
-    let containerIdentifier = containerSnapshot.identifier
-      .trimmingCharacters(in: .whitespacesAndNewlines)
-    return containerLabel == label && containerIdentifier == identifier
-  }
-
-  private func flatInteractiveElements(
-    app: XCUIApplication,
-    deadline: Date
-  ) -> (elements: [XCUIElement], truncated: Bool) {
-    let queries: [XCUIElementQuery] = [
-      app.buttons,
-      app.links,
-      app.textFields,
-      app.secureTextFields,
-      app.searchFields,
-      app.textViews,
-      app.switches,
-      app.sliders,
-      app.segmentedControls,
-      app.cells,
-      app.collectionViews,
-      app.tables,
-      app.scrollViews,
-      app.pickers,
-      app.steppers,
-      app.tabBars,
-      app.menuItems,
-      app.staticTexts,
-      app.images
-    ]
-
-    var elements: [XCUIElement] = []
-    var truncated = false
-    for query in queries {
-      if Date() >= deadline {
-        NSLog("AGENT_DEVICE_RUNNER_SNAPSHOT_FLAT_FALLBACK_DEADLINE")
-        truncated = true
-        break
-      }
-      let result = snapshotElementsQuery {
-        query.allElementsBoundByIndex
-      }
-      elements.append(contentsOf: result.elements)
-      if result.axUnavailable {
-        break
-      }
-    }
-    return (elements, truncated)
-  }
-
-  private func snapshotElementsQuery(
-    _ fetch: () -> [XCUIElement]
-  ) -> (elements: [XCUIElement], axUnavailable: Bool) {
-    let (elements, exceptionMessage) = catchingObjCException(fallback: [], fetch)
-    guard let exceptionMessage else {
-      return (elements, false)
-    }
-    NSLog("AGENT_DEVICE_RUNNER_SNAPSHOT_QUERY_IGNORED_EXCEPTION=%@", exceptionMessage)
-    if Self.isAxIllegalArgument(exceptionMessage) {
-      invalidateCachedTarget(reason: "ax_snapshot_query_unavailable")
-      return ([], true)
-    }
-    return ([], false)
-  }
-
-  private func flatSnapshotNode(
-    element: XCUIElement,
-    index: Int,
-    parentIndex: Int?
-  ) -> RawAXNode? {
-    var node: RawAXNode?
-    let exceptionMessage = RunnerObjCExceptionCatcher.catchException({
-      if !element.exists { return }
-      // Declared residue: a flat element query has no hierarchy for geometryless semantics to
-      // attach to, so frameless elements are dropped at acquisition rather than presented.
-      let frame = element.frame
-      if frame.isNull || frame.isEmpty { return }
-      let label = element.label.trimmingCharacters(in: .whitespacesAndNewlines)
-      let identifier = element.identifier.trimmingCharacters(in: .whitespacesAndNewlines)
-      let valueText = snapshotValueText(element)
-      let elementType = element.elementType
-      let enabled = element.isEnabled
-
-      node = RawAXNode(
-        index: index,
-        type: elementTypeName(elementType),
-        label: label.isEmpty ? nil : label,
-        identifier: identifier.isEmpty ? nil : identifier,
-        value: valueText,
-        rect: SnapshotRect(frame),
-        enabled: enabled,
-        focused: elementHasFocus(element) ? true : nil,
-        selected: element.isSelected ? true : nil,
-        hittable: false,
-        depth: 1,
-        parentIndex: parentIndex,
-        hiddenContentAbove: nil,
-        hiddenContentBelow: nil
-      )
-    })
-    if let exceptionMessage {
-      NSLog("AGENT_DEVICE_RUNNER_SNAPSHOT_FLAT_IGNORED_EXCEPTION=%@", exceptionMessage)
-      return nil
-    }
-    return node
-  }
-
 }
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotAcquisition.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotAcquisition.swift
new file mode 100644
index 0000000000..2c1d834786
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotAcquisition.swift
@@ -0,0 +1,566 @@
+import XCTest
+import AgentDeviceSnapshotPresentation
+
+extension RunnerTests {
+  func interactiveRootNode(rect: CGRect) -> RawAXNode {
+    RawAXNode(
+      index: 0,
+      type: "Application",
+      label: nil,
+      identifier: nil,
+      value: nil,
+      rect: SnapshotRect(rect),
+      enabled: true,
+      focused: nil,
+      selected: nil,
+      hittable: false,
+      depth: 0,
+      parentIndex: nil,
+      hiddenContentAbove: nil,
+      hiddenContentBelow: nil
+    )
+  }
+
+  func interactiveRootFrame(for candidates: [RawAXNode]) -> CGRect {
+    guard !candidates.isEmpty else {
+      return .zero
+    }
+    let maxX = candidates.map { CGFloat($0.rect.x + $0.rect.width) }.max() ?? 0
+    let maxY = candidates.map { CGFloat($0.rect.y + $0.rect.height) }.max() ?? 0
+    return CGRect(x: 0, y: 0, width: max(1, maxX), height: max(1, maxY))
+  }
+
+  // MARK: - Snapshot Filtering
+
+  func makeSnapshotTraversalContext(
+    app: XCUIApplication,
+    hint: CaptureHint,
+    captureDeadline: Date = .distantFuture,
+    treeCaptureSliceBudgetOverride: TimeInterval? = nil
+  ) throws -> SnapshotTraversalContext? {
+    // The viewport and the interface orientation are one hop: geometry that arrives in the device's
+    // native space can only be placed relative to the app's own frame and rotation, and asking for
+    // the pair twice would read them at two different moments of a rotation.
+    let geometry = try runMainThreadWork(
+      "snapshot_viewport",
+      timeout: min(1.0, max(0.1, captureDeadline.timeIntervalSinceNow)),
+      timeoutError: snapshotMainThreadTimeoutError("preparing tree snapshot")
+    ) {
+      (
+        viewport: self.safeSnapshotViewport(app: app),
+        interfaceOrientation: self.capturedInterfaceOrientation(app: app)
+      )
+    }
+    let viewport = geometry.viewport
+    let interfaceOrientation = geometry.interfaceOrientation
+    let treeSliceBudget = treeCaptureSliceBudgetOverride ?? treeCaptureSliceBudget
+    let slice = min(treeSliceBudget, max(0.5, captureDeadline.timeIntervalSinceNow))
+    guard let rootSnapshot = try captureSnapshotRootBounded(app, sliceSeconds: slice) else {
+      return nil
+    }
+
+    // Read after the tree, so the band is never older than the tree it will be compared against: a
+    // keyboard that appeared while the tree was being captured would otherwise publish `absent`
+    // beside key nodes that the tap guard would then have to trust less than the absence (#2660).
+    // It keeps its own hop and slice rather than joining the geometry pair above, because a keyboard
+    // this capture cannot measure must cost the fact and not the tree tier behind it.
+    let keyboardBand = captureKeyboardBandFact(app: app, deadline: captureDeadline)
+
+    return SnapshotTraversalContext(
+      queryRoot: app,
+      rootSnapshot: rootSnapshot,
+      viewport: viewport,
+      interfaceOrientation: interfaceOrientation,
+      keyboardBand: keyboardBand
+    )
+  }
+
+  static let xCTestSnapshotTimeoutCode = "IOS_TREE_CAPTURE_TIMEOUT"
+
+  /// Runs the blocking tree-snapshot XPC on the main thread bounded by `sliceSeconds`. On
+  /// timeout the XPC keeps running on main (it cannot be cancelled); the capture is marked
+  /// abandoned so plans avoid XCTest-backed tiers until it drains, the timed-out attempt
+  /// penalizes the tree backend for this bundle (unless the fresh-process warmup exemption
+  /// applies), and the plan moves to the platform's independent recovery tier when one exists
+  /// (#1105/#1122).
+  private func captureSnapshotRootBounded(
+    _ element: XCUIElement,
+    sliceSeconds: TimeInterval
+  ) throws -> XCUIElementSnapshot? {
+    if Thread.isMainThread {
+      return try captureSnapshotRoot(element)
+    }
+    return try runMainThreadWork(
+      "tree_capture",
+      timeout: sliceSeconds,
+      timeoutError: treeCaptureTimeoutError(sliceSeconds: sliceSeconds)
+    ) {
+      try self.captureSnapshotRoot(element)
+    }
+  }
+
+  private func treeCaptureTimeoutError(sliceSeconds: TimeInterval) -> () -> Error {
+    {
+      SnapshotCaptureFailure(
+        code: Self.xCTestSnapshotTimeoutCode,
+        message: "the XCTest tree capture exceeded its \(Int(sliceSeconds))s time slice",
+        hint: "The capture plan will avoid or tightly bound XCTest-backed snapshot tiers on this screen."
+      )
+    }
+  }
+
+  func snapshotMainThreadTimeoutError(_ operation: String) -> () -> Error {
+    {
+      SnapshotCaptureFailure(
+        code: Self.xCTestSnapshotTimeoutCode,
+        message: "timed out while \(operation) on the XCTest main thread",
+        hint: "The capture plan will skip XCTest-backed snapshot tiers while the previous main-thread work drains."
+      )
+    }
+  }
+
+  private func captureSnapshotRoot(_ element: XCUIElement) throws -> XCUIElementSnapshot? {
+    var rootSnapshot: XCUIElementSnapshot?
+    var swiftErrorMessage: String?
+    let exceptionMessage = RunnerObjCExceptionCatcher.catchException({
+      do {
+        rootSnapshot = try element.snapshot()
+      } catch {
+        swiftErrorMessage = describeSnapshotError(error)
+      }
+    })
+
+    if let rootSnapshot {
+      return rootSnapshot
+    }
+    let message = exceptionMessage ?? swiftErrorMessage ?? "snapshot returned no root"
+    if Self.isAxIllegalArgument(message) {
+      throw axSnapshotFailure(message)
+    }
+    return nil
+  }
+
+  func safeSnapshotViewport(app: XCUIApplication) -> CGRect {
+    safely("SNAPSHOT_VIEWPORT", CGRect.infinite) { snapshotViewport(app: app) }
+  }
+
+  private func describeSnapshotError(_ error: Error) -> String {
+    let localized = error.localizedDescription
+    let debug = String(describing: error)
+    if localized.isEmpty { return debug }
+    if debug == localized { return localized }
+    return "\(localized) (\(debug))"
+  }
+
+  private func axSnapshotFailure(_ message: String) -> SnapshotCaptureFailure {
+    let detail = message.trimmingCharacters(in: .whitespacesAndNewlines)
+    let failureMessage: String
+    if detail.isEmpty {
+      failureMessage = Self.axSnapshotFailureMessage
+    } else {
+      failureMessage = "\(Self.axSnapshotFailureMessage) \(detail)"
+    }
+    return SnapshotCaptureFailure(
+      code: Self.axSnapshotErrorCode,
+      message: failureMessage,
+      hint: Self.axSnapshotHint
+    )
+  }
+
+  private static func isAxIllegalArgument(_ message: String) -> Bool {
+    let normalized = message.lowercased()
+    return normalized.contains("kaxerrorillegalargument")
+      || (normalized.contains("illegal argument") && normalized.contains("snapshot"))
+  }
+
+  static func isAxSnapshotFailure(_ failure: SnapshotCaptureFailure) -> Bool {
+    failure.code == Self.axSnapshotErrorCode || isAxIllegalArgument(failure.message)
+  }
+
+  func evaluateSnapshot(_ snapshot: XCUIElementSnapshot) -> SnapshotEvaluation {
+    let label = aggregatedLabel(for: snapshot) ?? snapshot.label.trimmingCharacters(in: .whitespacesAndNewlines)
+    let identifier = snapshot.identifier.trimmingCharacters(in: .whitespacesAndNewlines)
+    let valueText = snapshotValueText(snapshot)
+    return SnapshotEvaluation(
+      label: label,
+      identifier: identifier,
+      valueText: valueText,
+      focused: snapshotHasFocus(snapshot),
+      selected: snapshotIsSelected(snapshot)
+    )
+  }
+
+  func makeSnapshotNode(
+    snapshot: XCUIElementSnapshot,
+    evaluation: SnapshotEvaluation,
+    depth: Int,
+    index: Int,
+    parentIndex: Int?
+  ) -> RawAXNode {
+    // Acquisition carries the frame the platform reported; `SnapshotGeometrySpace.normalized` turns
+    // it into the app's orientation space and recomputes `hittable` from that one pass (#2661).
+    return RawAXNode(
+      index: index,
+      type: elementTypeName(snapshot.elementType),
+      label: evaluation.label.isEmpty ? nil : evaluation.label,
+      identifier: evaluation.identifier.isEmpty ? nil : evaluation.identifier,
+      value: evaluation.valueText,
+      rect: SnapshotRect(snapshot.frame),
+      enabled: snapshot.isEnabled,
+      focused: evaluation.focused ? true : nil,
+      selected: evaluation.selected ? true : nil,
+      hittable: false,
+      depth: depth,
+      parentIndex: parentIndex,
+      hiddenContentAbove: nil,
+      hiddenContentBelow: nil
+    )
+  }
+
+  /// The app's own interface orientation: the fact that names which way the device's native space is
+  /// turned from the space the capture publishes. Unreadable or unnamed means no rotation.
+  func capturedInterfaceOrientation(app: XCUIApplication) -> Int {
+    safely("SNAPSHOT_INTERFACE_ORIENTATION", RunnerInterfaceOrientation.unknown) {
+      Int(RunnerSynthesizedGesture.interfaceOrientation(forApplication: app))
+    }
+  }
+
+  private func snapshotValueText(_ snapshot: XCUIElementSnapshot) -> String? {
+    guard let value = snapshot.value else { return nil }
+    let text = String(describing: value).trimmingCharacters(in: .whitespacesAndNewlines)
+    return text.isEmpty ? nil : text
+  }
+
+  private func snapshotViewport(app: XCUIApplication) -> CGRect {
+#if os(iOS)
+    let appFrame = onScreenWindowFrame(app: app)
+#else
+    let appFrame = app.frame
+#endif
+    if !appFrame.isNull && !appFrame.isEmpty {
+      return appFrame
+    }
+    return .infinite
+  }
+
+  static func snapshotTraversalIdentity(
+    elementType: XCUIElement.ElementType,
+    label: String,
+    identifier: String,
+    frame: CGRect
+  ) -> String {
+    #if os(iOS)
+    "\(elementType)-\(label)-\(identifier)-\(frame.origin.x)-\(frame.origin.y)-\(frame.width)-\(frame.height)"
+    #else
+    return "\(elementType)-\(label)-\(identifier)-\(frame.origin.x)-\(frame.origin.y)"
+    #endif
+  }
+
+  private func aggregatedLabel(for snapshot: XCUIElementSnapshot, depth: Int = 0) -> String? {
+    if depth > 4 { return nil }
+    let text = snapshot.label.trimmingCharacters(in: .whitespacesAndNewlines)
+    if !text.isEmpty { return text }
+    if let valueText = snapshotValueText(snapshot) { return valueText }
+    for child in snapshot.children {
+      if let childLabel = aggregatedLabel(for: child, depth: depth + 1) {
+        return childLabel
+      }
+    }
+    return nil
+  }
+
+  func appendCollapsedTabFallbackNodes(
+    to nodes: inout [RawAXNode],
+    containerSnapshot: XCUIElementSnapshot,
+    resolveElements: () -> [XCUIElement],
+    depth: Int,
+    parentIndex: Int
+  ) {
+    let fallbackNodes = collapsedTabFallbackNodes(
+      for: containerSnapshot,
+      resolveElements: resolveElements,
+      startingIndex: nodes.count,
+      depth: depth,
+      parentIndex: parentIndex
+    )
+    nodes.append(contentsOf: fallbackNodes)
+  }
+
+  private func collapsedTabFallbackNodes(
+    for containerSnapshot: XCUIElementSnapshot,
+    resolveElements: () -> [XCUIElement],
+    startingIndex: Int,
+    depth: Int,
+    parentIndex: Int
+  ) -> [RawAXNode] {
+    if !containerSnapshot.children.isEmpty { return [] }
+    // This fallback reads live element frames, which XCTest reports in the app's own space, and a
+    // collapsed tab container sits under the app's own window. `SnapshotGeometrySpace.normalized`
+    // keys rotation on ancestry, so these nodes never enter a declared native space and need no
+    // special case here; the containment and area rules below compare reported frames to each other.
+    guard shouldExpandCollapsedTabContainer(containerSnapshot) else { return [] }
+    let containerFrame = containerSnapshot.frame
+    if containerFrame.isNull || containerFrame.isEmpty { return [] }
+
+    // Collapsed tab containers should be rare, so a full descendant scan is acceptable once per
+    // snapshot as a fallback for XCTest omitting the tab children from the snapshot tree.
+    let elements = resolveElements()
+    let candidates = elements.compactMap { element in
+      collapsedTabCandidateNode(
+        element: element,
+        containerSnapshot: containerSnapshot,
+        containerFrame: containerFrame
+      )
+    }
+    .sorted { left, right in
+      if left.rect.x != right.rect.x {
+        return left.rect.x < right.rect.x
+      }
+      return left.rect.y < right.rect.y
+    }
+
+    if candidates.count < 2 { return [] }
+    let rowMidpoints = candidates.map { $0.rect.y + ($0.rect.height / 2) }
+    let rowSpread = (rowMidpoints.max() ?? 0) - (rowMidpoints.min() ?? 0)
+    // Allow modest vertical jitter and short two-row wraps while still rejecting unrelated controls.
+    if rowSpread > max(24.0, Double(containerFrame.height) * 0.6) { return [] }
+
+    var seen = Set<String>()
+    let uniqueCandidates = candidates.filter { node in
+      let key = "\(node.type)-\(node.label ?? "")-\(node.identifier ?? "")-\(node.value ?? "")-\(node.rect.x)-\(node.rect.y)-\(node.rect.width)-\(node.rect.height)"
+      if seen.contains(key) { return false }
+      seen.insert(key)
+      return true
+    }
+    if uniqueCandidates.count < 2 { return [] }
+
+    return uniqueCandidates.enumerated().map { offset, node in
+      RawAXNode(
+        index: startingIndex + offset,
+        type: node.type,
+        label: node.label,
+        identifier: node.identifier,
+        value: node.value,
+        rect: node.rect,
+        enabled: node.enabled,
+        focused: node.focused,
+        selected: node.selected,
+        hittable: node.hittable,
+        depth: depth,
+        parentIndex: parentIndex,
+        hiddenContentAbove: nil,
+        hiddenContentBelow: nil
+      )
+    }
+  }
+
+  private func collapsedTabCandidateNode(
+    element: XCUIElement,
+    containerSnapshot: XCUIElementSnapshot,
+    containerFrame: CGRect
+  ) -> RawAXNode? {
+    var node: RawAXNode?
+    let exceptionMessage = RunnerObjCExceptionCatcher.catchException({
+      if !element.exists { return }
+      let elementType = element.elementType
+      if !Self.collapsedTabCandidateTypes.contains(elementType) { return }
+      let frame = element.frame
+      if frame.isNull || frame.isEmpty { return }
+      if frame.equalTo(containerFrame) { return }
+      let area = max(CGFloat(1), frame.width * frame.height)
+      let containerArea = max(CGFloat(1), containerFrame.width * containerFrame.height)
+      if area >= containerArea * 0.9 { return }
+      let center = CGPoint(x: frame.midX, y: frame.midY)
+      if !containerFrame.contains(center) { return }
+
+      let label = element.label.trimmingCharacters(in: .whitespacesAndNewlines)
+      let identifier = element.identifier.trimmingCharacters(in: .whitespacesAndNewlines)
+      let valueText = snapshotValueText(element)
+      let hasContent = !label.isEmpty || !identifier.isEmpty || valueText != nil
+      if !hasContent { return }
+      if sameSemanticElement(
+        containerSnapshot: containerSnapshot,
+        elementType: elementType,
+        label: label,
+        identifier: identifier
+      ) {
+        return
+      }
+
+      // The containment and area rules above compared reported frames with each other; the node
+      // joins the tree carrying the frame the platform reported, and normalization places it.
+      node = RawAXNode(
+        index: 0,
+        type: elementTypeName(elementType),
+        label: label.isEmpty ? nil : label,
+        identifier: identifier.isEmpty ? nil : identifier,
+        value: valueText,
+        rect: SnapshotRect(frame),
+        enabled: element.isEnabled,
+        focused: elementHasFocus(element) ? true : nil,
+        selected: element.isSelected ? true : nil,
+        hittable: false,
+        depth: 0,
+        parentIndex: nil,
+        hiddenContentAbove: nil,
+        hiddenContentBelow: nil
+      )
+    })
+    if let exceptionMessage {
+      NSLog(
+        "AGENT_DEVICE_RUNNER_SNAPSHOT_TAB_FALLBACK_IGNORED_EXCEPTION=%@",
+        exceptionMessage
+      )
+      return nil
+    }
+    return node
+  }
+
+  private func snapshotHasFocus(_ snapshot: XCUIElementSnapshot) -> Bool {
+    var focused = false
+    _ = RunnerObjCExceptionCatcher.catchException({
+      if let value = (snapshot as! NSObject).value(forKey: "hasFocus") as? Bool {
+        focused = value
+      }
+    })
+    return focused
+  }
+
+  private func snapshotIsSelected(_ snapshot: XCUIElementSnapshot) -> Bool {
+    return snapshot.isSelected
+  }
+
+  private func shouldExpandCollapsedTabContainer(_ snapshot: XCUIElementSnapshot) -> Bool {
+    let frame = snapshot.frame
+    if frame.isNull || frame.isEmpty { return false }
+    if frame.width < max(CGFloat(160), frame.height * 1.75) { return false }
+    switch snapshot.elementType {
+    case .tabBar, .segmentedControl, .slider:
+      return true
+    default:
+      return false
+    }
+  }
+
+  private func snapshotValueText(_ element: XCUIElement) -> String? {
+    let text = String(describing: element.value ?? "")
+      .trimmingCharacters(in: .whitespacesAndNewlines)
+    return text.isEmpty ? nil : text
+  }
+
+  private func sameSemanticElement(
+    containerSnapshot: XCUIElementSnapshot,
+    elementType: XCUIElement.ElementType,
+    label: String,
+    identifier: String
+  ) -> Bool {
+    if containerSnapshot.elementType != elementType { return false }
+    let containerLabel = containerSnapshot.label.trimmingCharacters(in: .whitespacesAndNewlines)
+    let containerIdentifier = containerSnapshot.identifier
+      .trimmingCharacters(in: .whitespacesAndNewlines)
+    return containerLabel == label && containerIdentifier == identifier
+  }
+
+  func flatInteractiveElements(
+    app: XCUIApplication,
+    deadline: Date
+  ) -> (elements: [XCUIElement], truncated: Bool) {
+    let queries: [XCUIElementQuery] = [
+      app.buttons,
+      app.links,
+      app.textFields,
+      app.secureTextFields,
+      app.searchFields,
+      app.textViews,
+      app.switches,
+      app.sliders,
+      app.segmentedControls,
+      app.cells,
+      app.collectionViews,
+      app.tables,
+      app.scrollViews,
+      app.pickers,
+      app.steppers,
+      app.tabBars,
+      app.menuItems,
+      app.staticTexts,
+      app.images
+    ]
+
+    var elements: [XCUIElement] = []
+    var truncated = false
+    for query in queries {
+      if Date() >= deadline {
+        NSLog("AGENT_DEVICE_RUNNER_SNAPSHOT_FLAT_FALLBACK_DEADLINE")
+        truncated = true
+        break
+      }
+      let result = snapshotElementsQuery {
+        query.allElementsBoundByIndex
+      }
+      elements.append(contentsOf: result.elements)
+      if result.axUnavailable {
+        break
+      }
+    }
+    return (elements, truncated)
+  }
+
+  func snapshotElementsQuery(
+    _ fetch: () -> [XCUIElement]
+  ) -> (elements: [XCUIElement], axUnavailable: Bool) {
+    let (elements, exceptionMessage) = catchingObjCException(fallback: [], fetch)
+    guard let exceptionMessage else {
+      return (elements, false)
+    }
+    NSLog("AGENT_DEVICE_RUNNER_SNAPSHOT_QUERY_IGNORED_EXCEPTION=%@", exceptionMessage)
+    if Self.isAxIllegalArgument(exceptionMessage) {
+      invalidateCachedTarget(reason: "ax_snapshot_query_unavailable")
+      return ([], true)
+    }
+    return ([], false)
+  }
+
+  func flatSnapshotNode(
+    element: XCUIElement,
+    index: Int,
+    parentIndex: Int?
+  ) -> RawAXNode? {
+    var node: RawAXNode?
+    let exceptionMessage = RunnerObjCExceptionCatcher.catchException({
+      if !element.exists { return }
+      // Declared residue: a flat element query has no hierarchy for geometryless semantics to
+      // attach to, so frameless elements are dropped at acquisition rather than presented.
+      let frame = element.frame
+      if frame.isNull || frame.isEmpty { return }
+      let label = element.label.trimmingCharacters(in: .whitespacesAndNewlines)
+      let identifier = element.identifier.trimmingCharacters(in: .whitespacesAndNewlines)
+      let valueText = snapshotValueText(element)
+      let elementType = element.elementType
+      let enabled = element.isEnabled
+
+      node = RawAXNode(
+        index: index,
+        type: elementTypeName(elementType),
+        label: label.isEmpty ? nil : label,
+        identifier: identifier.isEmpty ? nil : identifier,
+        value: valueText,
+        rect: SnapshotRect(frame),
+        enabled: enabled,
+        focused: elementHasFocus(element) ? true : nil,
+        selected: element.isSelected ? true : nil,
+        hittable: false,
+        depth: 1,
+        parentIndex: parentIndex,
+        hiddenContentAbove: nil,
+        hiddenContentBelow: nil
+      )
+    })
+    if let exceptionMessage {
+      NSLog("AGENT_DEVICE_RUNNER_SNAPSHOT_FLAT_IGNORED_EXCEPTION=%@", exceptionMessage)
+      return nil
+    }
+    return node
+  }
+
+}
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SynthesizedGesturePolicy.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SynthesizedGesturePolicy.swift
index c22c0cfb66..15af0ebee6 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SynthesizedGesturePolicy.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SynthesizedGesturePolicy.swift
@@ -59,6 +59,9 @@ struct SynthesizedGesturePolicy: Equatable, Hashable {
 
 struct SynthesizedCoordinateContext {
   let referenceFrame: CGRect
+  /// The window `referenceFrame` was measured on. Synthesized records route their display ID
+  /// through this same window so geometry and routing can never name different windows.
+  let resolvedWindow: XCUIElement
   let keyboardPolicy: SynthesizedKeyboardPolicy
   let fallbackPolicy: SynthesizedFallbackPolicy
   let accessibilityHealth: RunnerAccessibilityHealth
@@ -66,6 +69,7 @@ struct SynthesizedCoordinateContext {
   func withReferenceFrame(_ frame: CGRect) -> SynthesizedCoordinateContext {
     SynthesizedCoordinateContext(
       referenceFrame: frame,
+      resolvedWindow: resolvedWindow,
       keyboardPolicy: keyboardPolicy,
       fallbackPolicy: fallbackPolicy,
       accessibilityHealth: accessibilityHealth
@@ -144,7 +148,7 @@ extension RunnerTests {
       return
     }
     NSLog(
-      "AGENT_DEVICE_RUNNER_SYNTHESIZED_GESTURE_POLICY kind=%@ axHealth=%@ frameSource=screenshot keyboardPolicy=%@ fallbackPolicy=%@ fallbackAllowed=%@ fallbackAttempted=%@",
+      "AGENT_DEVICE_RUNNER_SYNTHESIZED_GESTURE_POLICY kind=%@ axHealth=%@ frameSource=window keyboardPolicy=%@ fallbackPolicy=%@ fallbackAllowed=%@ fallbackAttempted=%@",
       kind.rawValue,
       context.accessibilityHealth.rawValue,
       context.keyboardPolicy.rawValue,
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SynthesizedInteraction.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SynthesizedInteraction.swift
new file mode 100644
index 0000000000..b1e8db0915
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SynthesizedInteraction.swift
@@ -0,0 +1,594 @@
+import XCTest
+import AgentDeviceSnapshotPresentation
+
+extension RunnerTests {
+  func synthesizedDragAt(
+    app: XCUIApplication,
+    x: Double,
+    y: Double,
+    x2: Double,
+    y2: Double,
+    durationMs: Double,
+    profile: SynthesizedDragProfile = .continuous,
+    context: SynthesizedCoordinateContext? = nil
+  ) -> RunnerInteractionOutcome {
+#if os(iOS)
+    guard x.isFinite, y.isFinite, x2.isFinite, y2.isFinite else {
+      return .unsupported(
+        message: "synthesized coordinate drag requires finite coordinates",
+        hint: "Retry with finite x, y, x2, and y2 values."
+      )
+    }
+    let orientation = Int(RunnerSynthesizedGesture.interfaceOrientation(forApplication: app))
+    guard let context = context ?? synthesizedCoordinateContext(
+      app: app,
+      policy: synthesizedGesturePolicy(.synthesizedDrag)
+    ) else {
+      return .unsupported(
+        message: "synthesized coordinate drag could not resolve an app window with a finite screen frame",
+        hint: "Retry after the app is foregrounded, or use a plain screenshot to choose coordinates."
+      )
+    }
+    let frame = context.referenceFrame
+    let start = CoordinateSpaceRotation.native(
+      point: CGPoint(x: x, y: y),
+      in: frame,
+      interfaceOrientation: orientation
+    )
+    let end = CoordinateSpaceRotation.native(
+      point: CGPoint(x: x2, y: y2),
+      in: frame,
+      interfaceOrientation: orientation
+    )
+    logSynthesizedDispatch(
+      kind: "drag",
+      start: start,
+      end: end,
+      referenceFrame: frame,
+      orientation: orientation
+    )
+    let message = switch profile {
+    case .continuous:
+      RunnerSynthesizedGesture.synthesizeContinuousDrag(
+        withApplication: app,
+        resolvedWindow: context.resolvedWindow,
+        x: Double(start.x),
+        y: Double(start.y),
+        x2: Double(end.x),
+        y2: Double(end.y),
+        durationMs: durationMs
+      )
+    case .controlledScroll:
+      RunnerSynthesizedGesture.synthesizeControlledScroll(
+        withApplication: app,
+        resolvedWindow: context.resolvedWindow,
+        x: Double(start.x),
+        y: Double(start.y),
+        x2: Double(end.x),
+        y2: Double(end.y),
+        durationMs: durationMs
+      )
+    case .fastSwipe:
+      RunnerSynthesizedGesture.synthesizeSwipe(
+        withApplication: app,
+        resolvedWindow: context.resolvedWindow,
+        x: Double(start.x),
+        y: Double(start.y),
+        x2: Double(end.x),
+        y2: Double(end.y),
+        durationMs: durationMs
+      )
+    }
+    if let message {
+      return .unsupported(
+        message: message,
+        hint: "Private XCTest event synthesis is required for AX-free coordinate drag on iOS; update Xcode if this persists."
+      )
+    }
+    return .performed
+#elseif os(tvOS)
+    return .unsupported(
+      message: "coordinate drag is not supported on tvOS",
+      hint: "tvOS has no coordinate input; use remote-driven swipe/scroll to move focus instead."
+    )
+#else
+    return .unsupported(
+      message: "coordinate drag is not supported on macOS",
+      hint: "macOS automation has no touchscreen; use mouse-driven interactions instead."
+    )
+#endif
+  }
+
+  func synthesizedTapAt(
+    app: XCUIApplication,
+    x: Double,
+    y: Double,
+    context: SynthesizedCoordinateContext? = nil
+  ) -> RunnerInteractionOutcome {
+#if os(iOS)
+    guard x.isFinite, y.isFinite else {
+      return .unsupported(
+        message: "synthesized coordinate tap requires finite coordinates",
+        hint: "Retry with finite x and y values."
+      )
+    }
+    let orientation = Int(RunnerSynthesizedGesture.interfaceOrientation(forApplication: app))
+    guard let context = context ?? synthesizedCoordinateContext(
+      app: app,
+      policy: synthesizedGesturePolicy(.coordinateTap)
+    ) else {
+      return .unsupported(
+        message: "synthesized coordinate tap could not resolve an app window with a finite screen frame",
+        hint: "Retry after the app is foregrounded, or use a plain screenshot to choose coordinates."
+      )
+    }
+    let point = CoordinateSpaceRotation.native(
+      point: CGPoint(x: x, y: y),
+      in: context.referenceFrame,
+      interfaceOrientation: orientation
+    )
+    logSynthesizedDispatch(
+      kind: "tap",
+      start: point,
+      end: nil,
+      referenceFrame: context.referenceFrame,
+      orientation: orientation
+    )
+    if let message = RunnerSynthesizedGesture.synthesizeTap(
+      withApplication: app,
+      resolvedWindow: context.resolvedWindow,
+      x: Double(point.x),
+      y: Double(point.y)
+    ) {
+      return .unsupported(
+        message: message,
+        hint: "Falling back to XCTest coordinate tap may be slower and can still need a healthy accessibility tree."
+      )
+    }
+    return .performed
+#elseif os(tvOS)
+    return .unsupported(
+      message: "coordinate tap is not supported on tvOS; move focus with swipe or scroll, then select the focused element",
+      hint: "tvOS has no coordinate input; move focus with swipe/scroll to the target, then select it."
+    )
+#else
+    return .unsupported(
+      message: "synthesized coordinate tap is not supported on macOS",
+      hint: "macOS automation has no touchscreen; use mouse-driven interactions instead."
+    )
+#endif
+  }
+
+  func keyboardAvoidingDragPoints(
+    app: XCUIApplication,
+    x: Double,
+    y: Double,
+    x2: Double,
+    y2: Double
+  ) -> DragPoints {
+    let original = DragPoints(x: x, y: y, x2: x2, y2: y2)
+#if os(iOS)
+    guard let keyboardFrame = visibleKeyboardFrame(app: app) else {
+      return original
+    }
+    let minX = min(x, x2)
+    let minY = min(y, y2)
+    let gestureBounds = CGRect(
+      x: CGFloat(minX),
+      y: CGFloat(minY),
+      width: CGFloat(max(abs(x2 - x), 1)),
+      height: CGFloat(max(abs(y2 - y), 1))
+    )
+    guard gestureBounds.intersects(keyboardFrame) else {
+      return original
+    }
+
+    let appFrame = onScreenWindowFrame(app: app)
+    guard !appFrame.isEmpty else {
+      return original
+    }
+
+    let padding: Double = 12
+    let targetMaxY = Double(keyboardFrame.minY) - padding
+    let currentMaxY = max(y, y2)
+    let shift = currentMaxY - targetMaxY
+    guard shift > 0 else {
+      return original
+    }
+
+    let adjustedY = y - shift
+    let adjustedY2 = y2 - shift
+    guard min(adjustedY, adjustedY2) >= Double(appFrame.minY) + padding else {
+      return original
+    }
+
+    NSLog(
+      "AGENT_DEVICE_RUNNER_KEYBOARD_AVOIDING_DRAG from=(%.1f,%.1f)->(%.1f,%.1f) adjusted=(%.1f,%.1f)->(%.1f,%.1f) keyboardMinY=%.1f",
+      x,
+      y,
+      x2,
+      y2,
+      x,
+      adjustedY,
+      x2,
+      adjustedY2,
+      Double(keyboardFrame.minY)
+    )
+    return DragPoints(x: x, y: adjustedY, x2: x2, y2: adjustedY2)
+#else
+    return original
+#endif
+  }
+
+  func resolvedTouchVisualizationFrame(app: XCUIApplication, x: Double, y: Double) -> TouchVisualizationFrame {
+    let appFrame = app.frame
+    let referenceFrame = resolvedTouchReferenceFrame(app: app, appFrame: appFrame)
+    let originX = appFrame.isEmpty ? referenceFrame.minX : appFrame.minX
+    let originY = appFrame.isEmpty ? referenceFrame.minY : appFrame.minY
+    return TouchVisualizationFrame(
+      x: originX + x,
+      y: originY + y,
+      referenceWidth: referenceFrame.width,
+      referenceHeight: referenceFrame.height
+    )
+  }
+
+  func resolvedDragVisualizationFrame(
+    app: XCUIApplication,
+    x: Double,
+    y: Double,
+    x2: Double,
+    y2: Double
+  ) -> DragVisualizationFrame {
+    let start = resolvedTouchVisualizationFrame(app: app, x: x, y: y)
+    let end = resolvedTouchVisualizationFrame(app: app, x: x2, y: y2)
+    return DragVisualizationFrame(
+      x: start.x,
+      y: start.y,
+      x2: end.x,
+      y2: end.y,
+      referenceWidth: start.referenceWidth,
+      referenceHeight: start.referenceHeight
+    )
+  }
+
+  func resolvedTouchReferenceFrame(app: XCUIApplication, appFrame: CGRect) -> CGRect {
+    let resolved = resolveRunnerWindow(app: app)
+    if resolved.window != nil {
+      return frameAvoidingKeyboard(app: app, frame: resolved.frame)
+    }
+    if !appFrame.isEmpty {
+      return frameAvoidingKeyboard(app: app, frame: appFrame)
+    }
+    return CGRect(x: 0, y: 0, width: 0, height: 0)
+  }
+
+  private func frameAvoidingKeyboard(app: XCUIApplication, frame: CGRect) -> CGRect {
+#if os(iOS)
+    guard let keyboardFrame = visibleKeyboardFrame(app: app), !frame.isEmpty else {
+      return frame
+    }
+    let intersection = frame.intersection(keyboardFrame)
+    guard !intersection.isNull && intersection.height > 0 else {
+      return frame
+    }
+    let keyboardCoverage = intersection.width / max(frame.width, 1)
+    guard keyboardCoverage >= 0.5 else {
+      return frame
+    }
+    let safeHeight = keyboardFrame.minY - frame.minY
+    guard safeHeight >= frame.height * 0.25 else {
+      return frame
+    }
+    return CGRect(x: frame.minX, y: frame.minY, width: frame.width, height: safeHeight)
+#else
+    return frame
+#endif
+  }
+
+  func axFreeSynthesizedDragPlan(
+    app: XCUIApplication,
+    x: Double,
+    y: Double,
+    x2: Double,
+    y2: Double,
+    context: SynthesizedCoordinateContext? = nil
+  ) -> SynthesizedDragPlan? {
+#if os(iOS)
+    let context = context ?? synthesizedCoordinateContext(
+      app: app,
+      policy: synthesizedGesturePolicy(.synthesizedDrag)
+    )
+    guard x.isFinite, y.isFinite, x2.isFinite, y2.isFinite,
+      let context
+    else {
+      return nil
+    }
+    let points = keyboardAvoidingSynthesizedDragPoints(
+      app: app,
+      x: x,
+      y: y,
+      x2: x2,
+      y2: y2,
+      context: context
+    )
+    return SynthesizedDragPlan(
+      points: points,
+      context: context
+    )
+#else
+    return nil
+#endif
+  }
+
+  func axFreeDragVisualizationFrame(
+    x: Double,
+    y: Double,
+    x2: Double,
+    y2: Double,
+    referenceFrame: CGRect
+  ) -> DragVisualizationFrame {
+    return DragVisualizationFrame(
+      x: x,
+      y: y,
+      x2: x2,
+      y2: y2,
+      referenceWidth: Double(referenceFrame.width),
+      referenceHeight: Double(referenceFrame.height)
+    )
+  }
+
+  func logSynthesizedDispatch(
+    kind: String,
+    start: CGPoint,
+    end: CGPoint?,
+    referenceFrame: CGRect,
+    orientation: Int
+  ) {
+    if let end {
+      NSLog(
+        "AGENT_DEVICE_RUNNER_SYNTHESIZED_DISPATCH kind=%@ start=(%.1f,%.1f) end=(%.1f,%.1f) reference=(%.1f,%.1f,%.1f,%.1f) orientation=%d",
+        kind,
+        Double(start.x),
+        Double(start.y),
+        Double(end.x),
+        Double(end.y),
+        Double(referenceFrame.origin.x),
+        Double(referenceFrame.origin.y),
+        Double(referenceFrame.width),
+        Double(referenceFrame.height),
+        orientation
+      )
+      return
+    }
+    NSLog(
+      "AGENT_DEVICE_RUNNER_SYNTHESIZED_DISPATCH kind=%@ point=(%.1f,%.1f) reference=(%.1f,%.1f,%.1f,%.1f) orientation=%d",
+      kind,
+      Double(start.x),
+      Double(start.y),
+      Double(referenceFrame.origin.x),
+      Double(referenceFrame.origin.y),
+      Double(referenceFrame.width),
+      Double(referenceFrame.height),
+      orientation
+    )
+  }
+
+  func synthesizedCoordinateContext(
+    app: XCUIApplication,
+    policy: SynthesizedGesturePolicy
+  ) -> SynthesizedCoordinateContext? {
+#if os(iOS)
+    let health = runnerAccessibilityHealth
+    let resolved = resolveRunnerWindow(app: app)
+    guard let window = resolved.window else {
+      return nil
+    }
+    let referenceFrame = resolved.frame
+    guard referenceFrame.width.isFinite, referenceFrame.height.isFinite,
+      referenceFrame.width > 0, referenceFrame.height > 0
+    else {
+      return nil
+    }
+    return SynthesizedCoordinateContext(
+      referenceFrame: referenceFrame,
+      resolvedWindow: window,
+      keyboardPolicy: policy.keyboardPolicy,
+      fallbackPolicy: policy.fallbackPolicy,
+      accessibilityHealth: health
+    )
+#else
+    return nil
+#endif
+  }
+
+
+  func keyboardAvoidingSynthesizedDragPoints(
+    app: XCUIApplication,
+    x: Double,
+    y: Double,
+    x2: Double,
+    y2: Double,
+    context: SynthesizedCoordinateContext
+  ) -> DragPoints {
+#if os(iOS)
+    guard context.allowsKeyboardProbe else {
+      return DragPoints(x: x, y: y, x2: x2, y2: y2)
+    }
+    return keyboardAvoidingDragPoints(app: app, x: x, y: y, x2: x2, y2: y2)
+#else
+    return DragPoints(x: x, y: y, x2: x2, y2: y2)
+#endif
+  }
+
+  func swipe(app: XCUIApplication, direction: String) -> DragVisualizationFrame? {
+    if performTvRemoteSwipeIfAvailable(direction: direction) {
+      let frame = resolvedTouchReferenceFrame(app: app, appFrame: app.frame)
+      let midX = frame.midX
+      let midY = frame.midY
+      return DragVisualizationFrame(
+        x: midX,
+        y: midY,
+        x2: midX,
+        y2: midY,
+        referenceWidth: frame.width,
+        referenceHeight: frame.height
+      )
+    }
+    return nil
+  }
+
+  private func performTvRemoteSwipeIfAvailable(direction: String) -> Bool {
+    switch direction {
+    case "up":
+      return pressTvRemote(.up)
+    case "down":
+      return pressTvRemote(.down)
+    case "left":
+      return pressTvRemote(.left)
+    case "right":
+      return pressTvRemote(.right)
+    default:
+      return false
+    }
+  }
+
+  func plannedGestureValidationError(_ plan: RunnerGesturePlan) -> String? {
+    guard plan.topology == "single" || plan.topology == "two" else {
+      return "planned gesture topology must be single or two"
+    }
+    let supportedIntent = plan.topology == "single"
+      ? plan.intent == "fling" || plan.intent == "pan"
+      : plan.intent == "pan" || plan.intent == "pinch" || plan.intent == "rotate"
+        || plan.intent == "transform"
+    guard supportedIntent else { return "planned gesture has unsupported intent for its topology" }
+    if plan.topology == "single" {
+      guard plan.executionProfile == "endpoint-hold" || plan.executionProfile == "timed-pan" else {
+        return "single-pointer gesture requires a supported execution profile"
+      }
+    } else if plan.executionProfile != nil {
+      return "multi-touch gesture cannot define a single-pointer execution profile"
+    }
+    guard plan.durationMs.isFinite, plan.durationMs >= 16, plan.durationMs <= 10_000 else {
+      return "planned gesture durationMs must be between 16 and 10000"
+    }
+    let viewport = plan.viewport
+    guard viewport.x.isFinite, viewport.y.isFinite, viewport.width.isFinite,
+      viewport.height.isFinite, viewport.width > 0, viewport.height > 0
+    else {
+      return "planned gesture viewport must be finite and positive"
+    }
+    let expectedPointerCount = plan.topology == "single" ? 1 : 2
+    guard plan.pointers.count == expectedPointerCount else {
+      return "planned gesture pointer count does not match topology"
+    }
+    for (index, pointer) in plan.pointers.enumerated() where pointer.pointerId != index {
+      return "planned gesture requires ordered pointer ids"
+    }
+    let firstSamples = plan.pointers[0].samples
+    guard firstSamples.count >= 2 else { return "planned pointer paths require at least two samples" }
+    for pointer in plan.pointers {
+      guard pointer.samples.count == firstSamples.count else {
+        return "planned pointer paths require matching samples"
+      }
+      var previousOffset = -1.0
+      for (index, sample) in pointer.samples.enumerated() {
+        guard sample.offsetMs.isFinite,
+          sample.offsetMs == firstSamples[index].offsetMs,
+          sample.offsetMs > previousOffset
+        else {
+          return "planned pointer sample offsets must match and strictly increase"
+        }
+        let point = sample.point
+        guard point.x.isFinite, point.y.isFinite,
+          point.x >= viewport.x,
+          point.x <= viewport.x + viewport.width,
+          point.y >= viewport.y,
+          point.y <= viewport.y + viewport.height
+        else {
+          return "planned pointer sample lies outside the viewport"
+        }
+        previousOffset = sample.offsetMs
+      }
+      guard pointer.samples.first?.offsetMs == 0,
+        pointer.samples.last?.offsetMs == plan.durationMs
+      else {
+        return "planned pointer paths must start at 0 and end at durationMs"
+      }
+    }
+    if plan.topology == "two" {
+      guard let firstStart = firstSamples.first?.point,
+        let secondStart = plan.pointers[1].samples.first?.point,
+        hypot(firstStart.x - secondStart.x, firstStart.y - secondStart.y) > 0
+      else {
+        return "planned pointer paths require a positive initial span"
+      }
+    }
+    return nil
+  }
+
+  func plannedGestureExecution(for plan: RunnerGesturePlan) -> PlannedGestureExecution {
+    plan.topology == "single" && plan.executionProfile == "endpoint-hold"
+      ? .fastSwipe
+      : .sampled
+  }
+
+  func sampledPlannedGesture(
+    app: XCUIApplication,
+    plan: RunnerGesturePlan
+  ) -> RunnerInteractionOutcome {
+#if os(iOS)
+    let orientation = Int(RunnerSynthesizedGesture.interfaceOrientation(forApplication: app))
+    // The portable planner and validation use this exact viewport. Using app.frame here can
+    // diverge when XCTest unions transformed/off-screen descendants into the application frame.
+    let frame = CGRect(
+      x: plan.viewport.x,
+      y: plan.viewport.y,
+      width: plan.viewport.width,
+      height: plan.viewport.height
+    )
+    let pointerSamples: [[[String: NSNumber]]] = plan.pointers.map { pointer in
+      pointer.samples.map { sample in
+        let point = CoordinateSpaceRotation.native(
+          point: CGPoint(x: sample.point.x, y: sample.point.y),
+          in: frame,
+          interfaceOrientation: orientation
+        )
+        return [
+          "x": NSNumber(value: Double(point.x)),
+          "y": NSNumber(value: Double(point.y)),
+          "offsetMs": NSNumber(value: sample.offsetMs),
+        ]
+      }
+    }
+    let resolvedWindow = resolveRunnerWindow(app: app).window
+    if let message = RunnerSynthesizedGesture.synthesizeGesture(
+      withApplication: app,
+      resolvedWindow: resolvedWindow,
+      pointerSamples: pointerSamples
+    ) {
+      return .unsupported(
+        message: message,
+        hint: "This gesture uses private XCTest event-synthesis APIs; rebuild the runner with a supported Xcode if this persists."
+      )
+    }
+    return .performed
+#elseif os(tvOS)
+    return .unsupported(
+      message: "two-finger gestures are not supported on tvOS",
+      hint: "tvOS has no touch input; use remote-driven navigation."
+    )
+#elseif os(visionOS)
+    return .unsupported(
+      message: "two-finger touch gestures are not supported on visionOS",
+      hint: "The current XCTest synthesizer supports iOS and iPadOS touch simulators only."
+    )
+#else
+    return .unsupported(
+      message: "two-finger gestures are not supported on macOS",
+      hint: "macOS automation has no multi-touch input; run on an iOS simulator."
+    )
+#endif
+  }
+
+}
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerXCTestEventBridge.h b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerXCTestEventBridge.h
index 8b1499f828..bae0abb9c3 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerXCTestEventBridge.h
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerXCTestEventBridge.h
@@ -10,7 +10,7 @@ NS_ASSUME_NONNULL_BEGIN
 //
 // Each caller additionally resolves whichever XCSynthesizedEventRecord init
 // overload and XCPointerEventPath factory/mutator selectors its own event kind
-// needs: gesture uses the 2-arg `initWithName:interfaceOrientation:` plus
+// needs: gesture uses `initWithName:displayID:interfaceOrientation:` plus
 // touch-path selectors (`initForTouchAtPoint:offset:`, `moveToPoint:atOffset:`,
 // `liftUpAtOffset:`); text entry uses the 1-arg `initWithName:` plus text-input
 // selectors (`initForTextInput`, `typeText:atOffset:typingSpeed:shouldRedact:`,
@@ -43,6 +43,14 @@ FOUNDATION_EXPORT NSString * _Nullable RunnerResolveXCTestEventBridge(
   RunnerXCTestEventBridge *bridge
 );
 
+// Reads the display ID off an already-resolved window. When a caller has resolved the app window
+// for geometry, routing the synthesized gesture by this window keeps the record's display and the
+// booked reference frame on the same window instead of re-walking `windows.firstMatch`.
+FOUNDATION_EXPORT NSString * _Nullable RunnerResolveWindowDisplayID(
+  id window,
+  NSUInteger *displayID
+);
+
 FOUNDATION_EXPORT NSString * _Nullable RunnerRequireClass(
   Class cls,
   NSString *className,
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerXCTestEventBridge.m b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerXCTestEventBridge.m
index 1b5829ce2a..df4f403f95 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerXCTestEventBridge.m
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerXCTestEventBridge.m
@@ -1,4 +1,6 @@
 #import "RunnerXCTestEventBridge.h"
+#import <CoreGraphics/CoreGraphics.h>
+#import <math.h>
 
 NSString * _Nullable RunnerResolveXCTestEventBridge(
   id application,
@@ -87,3 +89,21 @@
   NSString *reason = exception.reason ?: fallbackReason;
   return [NSString stringWithFormat:@"%@: %@", name, reason];
 }
+
+NSString * _Nullable RunnerResolveWindowDisplayID(id window, NSUInteger *displayID) {
+  NSValue *frameValue = [window valueForKey:@"frame"];
+  CGRect frame = CGRectNull;
+  [frameValue getValue:&frame size:sizeof(frame)];
+  if (CGRectIsEmpty(frame) || CGRectIsInfinite(frame) || CGRectIsNull(frame)
+      || !isfinite(frame.origin.x) || !isfinite(frame.origin.y)
+      || !isfinite(frame.size.width) || !isfinite(frame.size.height)) {
+    return @"private XCTest event synthesis unavailable: no resolved application window";
+  }
+  // The frame read resolves the window snapshot. Before resolution its screen can name main.
+  NSNumber *identifier = [[window valueForKey:@"screen"] valueForKey:@"displayID"];
+  if (![identifier isKindOfClass:NSNumber.class] || identifier.unsignedIntegerValue == 0) {
+    return @"private XCTest event synthesis unavailable: no resolved window display ID";
+  }
+  *displayID = identifier.unsignedIntegerValue;
+  return nil;
+}
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SynthesizedInteractionTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SynthesizedInteractionTests.swift
new file mode 100644
index 0000000000..9937ba8362
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SynthesizedInteractionTests.swift
@@ -0,0 +1,116 @@
+import XCTest
+import AgentDeviceSnapshotPresentation
+
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS
+extension RunnerTests {
+  func testSynthesizedDispatchInvertsCaptureOnEveryInterfaceOrientation() {
+    let frames = [
+      CGRect(x: 0, y: 0, width: 430, height: 932),
+      CGRect(x: 0, y: 0, width: 951, height: 669),
+    ]
+    for frame in frames {
+      for orientation in [
+        RunnerInterfaceOrientation.portrait,
+        RunnerInterfaceOrientation.portraitUpsideDown,
+        RunnerInterfaceOrientation.landscapeLeft,
+        RunnerInterfaceOrientation.landscapeRight,
+      ] {
+        let corners = [
+          CGPoint(x: frame.minX + 1, y: frame.minY + 1),
+          CGPoint(x: frame.midX, y: frame.midY),
+          CGPoint(x: frame.maxX - 2, y: frame.maxY - 3),
+        ]
+        for displayed in corners {
+          let captured = CoordinateSpaceRotation.oriented(
+            point: displayed,
+            in: frame,
+            interfaceOrientation: orientation
+          )
+          let dispatched = CoordinateSpaceRotation.native(
+            point: captured,
+            in: frame,
+            interfaceOrientation: orientation
+          )
+          XCTAssertEqual(dispatched.x, displayed.x, accuracy: 0.001, "orientation \(orientation)")
+          XCTAssertEqual(dispatched.y, displayed.y, accuracy: 0.001, "orientation \(orientation)")
+        }
+      }
+    }
+  }
+
+  func testPlannedMultiTouchGestureAcceptsMatchingInBoundsTrajectories() throws {
+    let plan = try JSONDecoder().decode(
+      RunnerGesturePlan.self,
+      from: Data(
+        #"{"topology":"two","intent":"pan","durationMs":32,"viewport":{"x":0,"y":0,"width":200,"height":300},"pointers":[{"pointerId":0,"samples":[{"offsetMs":0,"point":{"x":80,"y":80}},{"offsetMs":16,"point":{"x":90,"y":85}},{"offsetMs":32,"point":{"x":100,"y":90}}]},{"pointerId":1,"samples":[{"offsetMs":0,"point":{"x":80,"y":120}},{"offsetMs":16,"point":{"x":90,"y":125}},{"offsetMs":32,"point":{"x":100,"y":130}}]}]}"#.utf8
+      )
+    )
+
+    XCTAssertNil(plannedGestureValidationError(plan))
+    XCTAssertEqual(plannedGestureExecution(for: plan), .sampled)
+  }
+
+  func testPlannedMultiTouchGestureRejectsMismatchedOffsets() throws {
+    let plan = try JSONDecoder().decode(
+      RunnerGesturePlan.self,
+      from: Data(
+        #"{"topology":"two","intent":"transform","durationMs":32,"viewport":{"x":0,"y":0,"width":200,"height":300},"pointers":[{"pointerId":0,"samples":[{"offsetMs":0,"point":{"x":80,"y":80}},{"offsetMs":32,"point":{"x":100,"y":90}}]},{"pointerId":1,"samples":[{"offsetMs":0,"point":{"x":80,"y":120}},{"offsetMs":31,"point":{"x":100,"y":130}}]}]}"#.utf8
+      )
+    )
+
+    XCTAssertEqual(
+      plannedGestureValidationError(plan),
+      "planned pointer sample offsets must match and strictly increase"
+    )
+  }
+
+  func testSinglePointerFlingUsesFastSwipeExecution() throws {
+    let plan = try JSONDecoder().decode(
+      RunnerGesturePlan.self,
+      from: Data(
+        #"{"topology":"single","intent":"fling","executionProfile":"endpoint-hold","durationMs":100,"viewport":{"x":0,"y":0,"width":200,"height":300},"pointers":[{"pointerId":0,"samples":[{"offsetMs":0,"point":{"x":160,"y":150}},{"offsetMs":100,"point":{"x":40,"y":150}}]}]}"#.utf8
+      )
+    )
+
+    XCTAssertEqual(plannedGestureExecution(for: plan), .fastSwipe)
+  }
+
+  func testSinglePointerTimedPanUsesSampledExecution() throws {
+    let plan = try JSONDecoder().decode(
+      RunnerGesturePlan.self,
+      from: Data(
+        #"{"topology":"single","intent":"pan","executionProfile":"timed-pan","durationMs":500,"viewport":{"x":0,"y":0,"width":200,"height":300},"pointers":[{"pointerId":0,"samples":[{"offsetMs":0,"point":{"x":160,"y":150}},{"offsetMs":250,"point":{"x":100,"y":150}},{"offsetMs":500,"point":{"x":40,"y":150}}]}]}"#.utf8
+      )
+    )
+
+    XCTAssertEqual(plannedGestureExecution(for: plan), .sampled)
+  }
+
+  func testSinglePointerEndpointHoldUsesFastSwipeExecution() throws {
+    let plan = try JSONDecoder().decode(
+      RunnerGesturePlan.self,
+      from: Data(
+        #"{"topology":"single","intent":"pan","executionProfile":"endpoint-hold","durationMs":500,"viewport":{"x":0,"y":0,"width":200,"height":300},"pointers":[{"pointerId":0,"samples":[{"offsetMs":0,"point":{"x":160,"y":150}},{"offsetMs":500,"point":{"x":40,"y":150}}]}]}"#.utf8
+      )
+    )
+
+    XCTAssertNil(plannedGestureValidationError(plan))
+    XCTAssertEqual(plannedGestureExecution(for: plan), .fastSwipe)
+  }
+
+  func testSinglePointerGestureRejectsMissingExecutionProfile() throws {
+    let plan = try JSONDecoder().decode(
+      RunnerGesturePlan.self,
+      from: Data(
+        #"{"topology":"single","intent":"pan","durationMs":500,"viewport":{"x":0,"y":0,"width":200,"height":300},"pointers":[{"pointerId":0,"samples":[{"offsetMs":0,"point":{"x":160,"y":150}},{"offsetMs":500,"point":{"x":40,"y":150}}]}]}"#.utf8
+      )
+    )
+
+    XCTAssertEqual(
+      plannedGestureValidationError(plan),
+      "single-pointer gesture requires a supported execution profile"
+    )
+  }
+
+}
+#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+XCTestEventBridgeTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+XCTestEventBridgeTests.swift
new file mode 100644
index 0000000000..9dec8afe2d
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+XCTestEventBridgeTests.swift
@@ -0,0 +1,66 @@
+import XCTest
+
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS
+private final class DisplayScreenFixture: NSObject {
+  @objc let displayID: UInt
+  init(_ displayID: UInt) { self.displayID = displayID }
+}
+
+/// A window that only reports the display it was built with once its frame has been read, which is
+/// when XCTest resolves the snapshot. Before that read, `screen` still names main.
+private final class DisplayWindowFixture: NSObject {
+  let windowFrame: CGRect
+  let resolvedDisplayID: UInt
+  var resolved = false
+  init(frame: CGRect, displayID: UInt) {
+    self.windowFrame = frame
+    self.resolvedDisplayID = displayID
+  }
+  @objc var frame: CGRect {
+    resolved = true
+    return windowFrame
+  }
+  @objc var screen: NSObject { DisplayScreenFixture(resolved ? resolvedDisplayID : 1) }
+}
+
+extension RunnerTests {
+  func testSynthesizedDisplayRoutesByTheResolvedWindow() {
+    let window = DisplayWindowFixture(frame: CGRect(x: 0, y: 0, width: 951, height: 669), displayID: 3)
+    var displayID: UInt = 0
+    XCTAssertNil(RunnerResolveWindowDisplayID(window, &displayID))
+    XCTAssertEqual(displayID, 3)
+    XCTAssertTrue(window.resolved)
+  }
+
+  func testSynthesizedDisplayPreservesPrimaryWindowIdentity() {
+    let window = DisplayWindowFixture(frame: CGRect(x: 0, y: 0, width: 466, height: 678), displayID: 1)
+    var displayID: UInt = 0
+    XCTAssertNil(RunnerResolveWindowDisplayID(window, &displayID))
+    XCTAssertEqual(displayID, 1)
+  }
+
+  func testSynthesizedDisplayRefusesDisplaylessWindow() {
+    let window = DisplayWindowFixture(frame: CGRect(x: 0, y: 0, width: 951, height: 669), displayID: 0)
+    var displayID: UInt = 99
+    XCTAssertNotNil(RunnerResolveWindowDisplayID(window, &displayID))
+    XCTAssertEqual(displayID, 99)
+  }
+
+  func testSynthesizedDisplayRefusesWindowWithoutQualifyingFrame() {
+    for frame in [CGRect.zero, .null, .infinite] {
+      let window = DisplayWindowFixture(frame: frame, displayID: 3)
+      var displayID: UInt = 99
+      XCTAssertNotNil(RunnerResolveWindowDisplayID(window, &displayID))
+      XCTAssertEqual(displayID, 99)
+    }
+  }
+
+  func testFirstUsableWindowSkipsAbsentAndEmptyWindows() {
+    let lit = CGRect(x: 0, y: 0, width: 402, height: 874)
+    XCTAssertEqual(RunnerTests.firstUsableWindowIndex(frames: [lit]), 0)
+    XCTAssertEqual(RunnerTests.firstUsableWindowIndex(frames: [nil, .zero, lit]), 2)
+    XCTAssertNil(RunnerTests.firstUsableWindowIndex(frames: [nil, .zero, nil]))
+    XCTAssertNil(RunnerTests.firstUsableWindowIndex(frames: []))
+  }
+}
+#endif
diff --git a/apple/snapshot-presentation/Sources/AgentDeviceSnapshotPresentation/SnapshotCoordinateSpace.swift b/apple/snapshot-presentation/Sources/AgentDeviceSnapshotPresentation/SnapshotCoordinateSpace.swift
index a17f91e7db..561861bc29 100644
--- a/apple/snapshot-presentation/Sources/AgentDeviceSnapshotPresentation/SnapshotCoordinateSpace.swift
+++ b/apple/snapshot-presentation/Sources/AgentDeviceSnapshotPresentation/SnapshotCoordinateSpace.swift
@@ -14,6 +14,11 @@ public enum RunnerInterfaceOrientation {
 }
 
 public enum CoordinateSpaceRotation {
+  // Dispatch rotates a point about the reference frame's top-left. The origin is localized away
+  // and never added back: an XCUIApplication session observes only its own scene surface, so its
+  // windows report (0,0)-anchored frames (measured on iPhone landscape both ways and on every
+  // system window in window-coordinate-space.json), and displacement between panels or panes is
+  // carried by the record's displayID, not by an origin.
   public static func native(
     point: CGPoint,
     in frame: CGRect,
diff --git a/contracts/fixtures/window-coordinate-space.json b/contracts/fixtures/window-coordinate-space.json
index a8497d9b07..ca92a01a71 100644
--- a/contracts/fixtures/window-coordinate-space.json
+++ b/contracts/fixtures/window-coordinate-space.json
@@ -159,6 +159,13 @@
       "app": { "x": 0, "y": 0, "width": 402, "height": 874 },
       "native": { "x": 3, "y": 68, "width": 99, "height": 54 },
       "oriented": { "x": 300, "y": 752, "width": 99, "height": 54 }
+    },
+    {
+      "name": "Duo inner panel automation button: native digitizer to landscape window (measured UITouch)",
+      "interfaceOrientation": 4,
+      "app": { "x": 0, "y": 0, "width": 951, "height": 669 },
+      "native": { "x": 226, "y": 475, "width": 0, "height": 0 },
+      "oriented": { "x": 476, "y": 226, "width": 0, "height": 0 }
     }
   ]
 }
diff --git a/docs/adr/0025-foldable-apple-panels.md b/docs/adr/0025-foldable-apple-panels.md
index 1be5ff2ac3..505a595f44 100644
--- a/docs/adr/0025-foldable-apple-panels.md
+++ b/docs/adr/0025-foldable-apple-panels.md
@@ -344,6 +344,29 @@ On the single-panel control every surface agreed: one screen, `1206x2622`, `rot0
 rotation to repair. A window-resolved source changes nothing there except that its identity becomes
 explicit.
 
+## Interaction display and viewport
+
+On an unfolded Duo, `XCUIApplication.frame` reports the inner panel in native portrait
+coordinates (669x951), while the app window and its controls report landscape coordinates
+(951x669). The iOS capture viewport and synthesized gesture reference frame therefore come
+from the resolved app window. Normalizing against the application frame rotates an already
+oriented window; inverting that normalization alone does not produce native digitizer coordinates.
+The measured inner-panel button row in `contracts/fixtures/window-coordinate-space.json` maps
+window (476,226) to native digitizer (226,475).
+
+Synthesized gesture records use `initWithName:displayID:interfaceOrientation:` and the resolved
+window's `screen.displayID`. Reading the window frame must precede reading its screen: an
+unresolved element can still report the main screen. `app.screen` is not the display authority
+for interactions on this device. Coordinate-based XCTest actions also originate at the resolved
+window, so long presses and coordinate fallbacks carry its display identity.
+
+CoreDevice remains the capture-panel authority for host screenshots and recordings. Gesture
+routing follows the window hosting the target app, without a hard-coded panel ID or cached pose.
+Verification must observe a fresh app-visible outcome: event synthesis success and
+`TouchEventsCompleted` alone do not prove a hit. On iOS 27.1, explicit inner-panel events reach
+UIKit; the silent misses investigated here came from the default outer-display route and the
+incorrect viewport, not an inner-panel delivery prohibition.
+
 ## Accepted evidence gaps
 
 - **Runner capture migration.** `XCUIScreen.main` is six call expressions in four files, and the
diff --git a/docs/agents/device-verification.md b/docs/agents/device-verification.md
index d53b4f3fe0..24522ed9cf 100644
--- a/docs/agents/device-verification.md
+++ b/docs/agents/device-verification.md
@@ -71,6 +71,9 @@ toolchain per command:
 
 - Panels: that command lists each integrated panel with `backlightState`. Only the lit panel is
   capturable — a capture of the dark panel exits 0 and writes an all-black PNG.
+- Input routing: verify a fresh control after each pose change. A successful synthesis acknowledgement
+  does not prove a hit. Inspect the runner and simulator `testmanagerd`/BackBoard logs for display
+  identity and delivery; the resolved app window owns gesture coordinates and its target screen.
 - Pose: `agent-device fold closed|half-open|open` presses the Device Hub pose control and reads the
   hinge back through `devicectl device motion hinge-angle`; re-snapshot afterwards, because refs
   and coordinates do not survive the pose change. Expect 10-16s per fold. The host needs
diff --git a/src/__tests__/apple-runner-package-source.test.ts b/src/__tests__/apple-runner-package-source.test.ts
index 81d66fe7cc..b031298007 100644
--- a/src/__tests__/apple-runner-package-source.test.ts
+++ b/src/__tests__/apple-runner-package-source.test.ts
@@ -10,7 +10,7 @@ const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../
 const packageScript = path.join(repoRoot, 'scripts', 'package-apple-runner-source.mjs');
 const runnerSnapshotSwiftPath = path.join(
   repoRoot,
-  'apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Snapshot.swift',
+  'apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotAcquisition.swift',
 );
 
 test('package apple runner source strips unit-test blocks without mutating checkout source', async () => {
diff --git a/src/commands/system/index.ts b/src/commands/system/index.ts
index e2ba1eb557..f7ed8b014a 100644
--- a/src/commands/system/index.ts
+++ b/src/commands/system/index.ts
@@ -60,7 +60,7 @@ const homeCommandDescription =
   'Send the selected device to its home screen. This leaves the app session open but moves the foreground away from the app.';
 const orientationCommandDescription = 'Set device orientation on iOS and Android';
 const foldCommandDescription =
-  'Fold or unfold a foldable iPhone simulator (iPhone Duo) into the closed, half-open, or open pose by pressing the pose control in Xcode Device Hub, then read the hinge angle back from CoreDevice to confirm it. A pose change moves the app to a different panel with a different point size, so every ref and coordinate from before it is stale: re-snapshot after this command. Simulator-only; the device window must be open in Device Hub and the host needs Accessibility permission.';
+  'Fold or unfold a foldable iPhone simulator (iPhone Duo) into the closed, half-open, or open pose by pressing the pose control in Xcode Device Hub, then read the hinge angle back from CoreDevice to confirm it. A pose change moves the app to a different panel with a different point size, so every ref and coordinate from before it is stale: re-snapshot after this command. Taps, long presses, and scrolling target the app window on its current panel in closed, half-open, and open poses. Simulator-only; the device window must be open in Device Hub and the host needs Accessibility permission.';
 const appSwitcherCommandDescription =
   'Open the device app switcher to inspect or change foreground apps. This changes the visible system UI and may move focus away from the current app.';
 const keyboardCommandDescription =
diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md
index 8cd20917df..20e9389c2f 100644
--- a/website/docs/docs/commands.md
+++ b/website/docs/docs/commands.md
@@ -91,7 +91,7 @@ agent-device fold open
 - `action-button` asks the device whether it has the button before pressing it. A target whose model has none — an iPhone SE beside an iPhone 15, or most iPad simulators — fails with `UNSUPPORTED_OPERATION` rather than reporting a press that never happened.
 - `action-button` does not activate or relaunch the session's app, and it takes no `--settle`: pressing a hardware button is not a navigation, so the app stays where it was.
 - `action-button` reports that the press was dispatched, not what the system did with it. Simulators run no Shortcuts and no App Intents, so what a press triggers can only be verified on a physical iPhone; on a Simulator the command proves the press was accepted and that the session app was not brought forward.
-- `fold <closed|half-open|open>` puts a foldable iPhone simulator (iPhone Duo) into a hinge pose. No official host API sets a pose (ADR 0025), so the command presses the pose control in the Xcode Device Hub window through macOS accessibility, then reads the hinge angle back with `devicectl device motion hinge-angle` and reports the pose only when that reading agrees: `closed` is 0°, `open` is 180°, and `half-open` is any angle between them (Device Hub's Book preset, 130° on iOS 27.1). An angle inside that interval only proves the category, so `half-open` is reported once two consecutive readings both fall inside it and agree within 0.5°. The response names the panel the device now lights and its native panel point size, marked `coordinateSpace: "native-panel"`; that size is the panel's own geometry, not the next snapshot's viewport (a 669x951 inner panel can host a 951x669 app window), so it cannot place a tap. Re-snapshot afterwards, and never carry refs or coordinates across a `fold`.
+- `fold <closed|half-open|open>` puts a foldable iPhone simulator (iPhone Duo) into a hinge pose. No official host API sets a pose (ADR 0025), so the command presses the pose control in the Xcode Device Hub window through macOS accessibility, then reads the hinge angle back with `devicectl device motion hinge-angle` and reports the pose only when that reading agrees: `closed` is 0°, `open` is 180°, and `half-open` is any angle between them (Device Hub's Book preset, 130° on iOS 27.1). An angle inside that interval only proves the category, so `half-open` is reported once two consecutive readings both fall inside it and agree within 0.5°. The response names the panel the device now lights and its native panel point size, marked `coordinateSpace: "native-panel"`; that size is the panel's own geometry, not the next snapshot's viewport (a 669x951 inner panel can host a 951x669 app window), so it cannot place a tap. Re-snapshot afterwards, and never carry refs or coordinates across a `fold`. After that snapshot, taps, long presses, and scrolling follow the app window on the active panel in closed, half-open, and open poses.
 - `fold` is simulator-only and needs Xcode 27.1 or newer with Device Hub. The host needs Accessibility permission (`settings permission grant accessibility --platform macos`), and Device Hub must list the simulator; the command reopens Device Hub's window when it shows none, selects the device through the sidebar row keyed by its UDID, and attempts to restore any sidebar it revealed afterwards within a bounded cleanup budget. Sidebar actions use the selected window’s toolbar button. A single-panel simulator such as an iPhone 17 fails with `UNSUPPORTED_OPERATION`; Android, web, Linux, HarmonyOS, Vega, physical devices, and the tvOS, macOS, and visionOS leaves refuse it.
 - `fold` discovers windows across running Device Hub processes without requiring main-display placement. Failed accessibility reads report `device-hub-window-read-failed` with AX status and process/display diagnostics; they do not count as an empty window list. Inconclusive row lookup reports `device-hub-identity-unconfirmed` with candidate outcomes; an interrupted discovery reports `device-hub-discovery-timeout`. Active host display IDs are included only in discovery errors.
 - `fold` costs one bounded hinge stream per read, and devicectl's smallest stream is five seconds: `closed` and `open` take about ten seconds, `half-open` about sixteen, because the hinge animates and the command waits for it to stop. A hinge whose last reading is some other pose fails with `COMMAND_FAILED` and `reason: fold-pose-unverified`, naming the angle CoreDevice still reports. A hinge seen `half-open` but never at rest fails with `reason: fold-pose-unsettled`, naming the observed and previous angles: the requested category was observed, and what is missing is a pose the hinge holds (#2730).

From b566eb414f5317207aba7be49eae49e1a539a860 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Tue, 22 Sep 2026 13:11:01 +0200
Subject: [PATCH 015/132] test(examples): add manual iPhone Duo pose-transition
 semantic check (#2738)

Drives one booted iPhone Duo through closed -> half-open -> open -> closed
and asserts the app reacts after every pose change: a tab press routes and
selects, Add to cart moves the cart counter, a scroll reveals a canary, a
long press moves its dedicated count, and one multipointer pinch changes a
recognized scale. Coordinates are derived from the current target's bounds
and refs are re-resolved after each fold, never reused across a pose change.

Local/manual coverage only; GitHub Actions cannot schedule it yet (no hosted
Duo runtime or registered Duo runner). --demo-geometry-mutation derives the
pinch origin from a different control's bounds to prove the scale assertion
is sensitive to targeting geometry.

Refs #2731
---
 examples/test-app/README.md                   |  48 ++
 .../test-app/foldable/duo-pose-semantic.mjs   | 621 ++++++++++++++++++
 2 files changed, 669 insertions(+)
 create mode 100644 examples/test-app/foldable/duo-pose-semantic.mjs

diff --git a/examples/test-app/README.md b/examples/test-app/README.md
index 232b70017c..088f145011 100644
--- a/examples/test-app/README.md
+++ b/examples/test-app/README.md
@@ -296,3 +296,51 @@ local bundle.
 The suite intentionally covers the compat layer syntax used by public Maestro suites:
 `runFlow` file/inline blocks, `when.platform`, config hooks, deterministic `repeat.times`,
 flow `env`, selectors, input, assertions, and swipe.
+
+## Local iPhone Duo pose-transition semantic checks (manual)
+
+`examples/test-app/foldable/duo-pose-semantic.mjs` drives one booted iPhone Duo through
+closed → half-open → open → closed and asserts the app reacts after **every** pose change —
+a Catalog tap is proved to activate by an absent→present `catalog-title` transition measured from
+the same snapshot that resolved the tap's ref (with `home-title` gone after), the Home reset is
+asserted before the next fold, Add to cart moves the cart counter, a scroll reveals a canary,
+a long press moves a dedicated count, and one multipointer pinch changes a recognized scale.
+It reuses the `agent-device` CLI/daemon and this fixture app; it adds no framework.
+
+This is **local/manual coverage only, never automatic regression coverage.** GitHub Actions
+cannot select it yet (no hosted iPhone Duo runtime, no registered Duo runner), so it is not a CI
+gate and does not change the ordinary iPhone lane.
+
+Requirements: `DEVELOPER_DIR` pinned to a Duo-capable Xcode (iOS 27.1 ships only with Xcode 27.1+);
+exactly one booted iPhone Duo not shared with a concurrent run (concurrent runs rebuild the shared
+Apple runner and race capture/pose state); Xcode Device Hub reachable with Accessibility permission
+(`fold` presses its pose control — a Device Hub window on a secondary display makes the control
+unreachable and reports `device-hub-window-missing`; move it to the main display); the Agent Device
+Tester app installed on that simulator.
+
+```bash
+# List booted Duo simulators, then run the scenario against one:
+DEVELOPER_DIR=/Applications/Xcode-27.1.0-Beta.app/Contents/Developer \
+  node examples/test-app/foldable/duo-pose-semantic.mjs --udid <DUO-UDID>
+
+# Prove the activation check is sensitive to targeting geometry: derive the pinch origin from a
+# different control's bounds. This flips the pinch scale check to FAIL (red is expected here):
+DEVELOPER_DIR=/Applications/Xcode-27.1.0-Beta.app/Contents/Developer \
+  node examples/test-app/foldable/duo-pose-semantic.mjs --udid <DUO-UDID> --demo-geometry-mutation
+
+# Prove the activation check is sensitive to a missed reset: skip the return-to-Home tap so a
+# closed/half-open activation or Home-reset check FAILS (red is expected here):
+DEVELOPER_DIR=/Applications/Xcode-27.1.0-Beta.app/Contents/Developer \
+  node examples/test-app/foldable/duo-pose-semantic.mjs --udid <DUO-UDID> --demo-skip-home-reset
+```
+
+A clean run prints `15/15 semantic checks passed` and exits 0; each pose's Catalog check reports a
+`catalog absent->present, home present->absent` transition. Failure snapshots land under
+`--artifacts-dir` (default `<state-dir>/artifacts`). The scenario never reuses a ref or coordinate
+across a pose change or mutation (a dropped session re-opens but never replays an `@ref`), saves
+failure artifacts, closes the session, and restores the starting pose.
+
+**Deferred GitHub Actions enablement (not a completion condition).** Wiring an automatic Duo job
+later requires, all at once: a Duo runtime/device type on the runner image, working Device Hub pose
+controls with Accessibility permission on the runner host, and one actual successful lane run — then
+re-check the runner-image inventories, which are dated, not permanent.
diff --git a/examples/test-app/foldable/duo-pose-semantic.mjs b/examples/test-app/foldable/duo-pose-semantic.mjs
new file mode 100644
index 0000000000..33881e063e
--- /dev/null
+++ b/examples/test-app/foldable/duo-pose-semantic.mjs
@@ -0,0 +1,621 @@
+#!/usr/bin/env node
+// LOCAL / MANUAL ONLY — not automatic regression coverage and not wired to any CI gate.
+//
+// Semantic interaction replay across iPhone Duo pose transitions (issue #2731, parent #2725).
+//
+// It drives the existing `agent-device` CLI/daemon against one explicit, booted iPhone Duo
+// simulator and asserts the app reacts after every pose change: a Catalog tap is proved to activate
+// by an absent->present `catalog-title` transition (measured from the same snapshot that resolved
+// the tap's ref, with `home-title` gone after), the Home reset is asserted before the next fold,
+// Add to cart moves the cart counter, a scroll reveals a canary, a long press moves a dedicated
+// count, and a multipointer pinch changes a recognized scale. It never reuses a ref or coordinate
+// across a pose change or a mutation: every tap resolves a fresh ref from the snapshot taken
+// immediately before it, and a dropped session re-opens but never replays an interaction ref.
+//
+// GitHub Actions cannot schedule this yet: hosted macOS images carry no iPhone Duo runtime and no
+// self-hosted Duo runner is registered (see the issue investigation). Run it locally on a host
+// that owns exactly one booted iPhone Duo for the duration of the run.
+//
+// Requirements (enforced up front with an actionable failure, never a silent skip):
+//   * DEVELOPER_DIR pinned to a Duo-capable Xcode (the iOS 27.1 runtime ships only with Xcode 27.1+).
+//   * An iPhone Duo simulator already booted on that toolchain, not shared with a concurrent run
+//     (concurrent runs rebuild the shared Apple runner and race the pose/capture state).
+//   * Xcode Device Hub reachable with Accessibility permission, because `fold` presses the Device
+//     Hub pose control. If Device Hub's window is on a secondary display, pose control is
+//     unreachable and `fold` reports `device-hub-window-missing`; move it to the main display.
+//   * The Agent Device Tester fixture app installed on that simulator.
+//
+// Usage (from the repository root):
+//   DEVELOPER_DIR=<Xcode-27.1>/Contents/Developer \
+//     node examples/test-app/foldable/duo-pose-semantic.mjs --udid <DUO-UDID>
+//
+// Flags:
+//   --udid <UDID>              Booted iPhone Duo simulator (required).
+//   --session <name>           Session name (default: duo-pose-semantic).
+//   --state-dir <dir>          Isolated daemon state dir (default: a /private/tmp path).
+//   --app <target>             App target for `open` (default: "Agent Device Tester").
+//   --artifacts-dir <dir>      Failure artifacts (default: <state-dir>/artifacts).
+//   --demo-geometry-mutation   Derive the pinch origin from a different control's bounds instead
+//                              of the target's own bounds, so the semantic scale assertion FAILS.
+//                              Proves the assertion is sensitive to targeting geometry. A red run
+//                              is the expected outcome here.
+//   --demo-skip-home-reset     Skip the reset-to-Home tap so the "Home is the active route" check
+//                              and the next pose's before-state FAIL in a closed/half-open pose.
+//                              Proves the activation check is sensitive to a missed Home reset.
+//                              A red run is the expected outcome here.
+import { execFile } from 'node:child_process';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+const CLI = join(REPO_ROOT, 'bin', 'agent-device.mjs');
+const DEVELOPER_DIR = process.env.DEVELOPER_DIR;
+const POSES = ['closed', 'half-open', 'open', 'closed'];
+const START_POSE = 'closed';
+const STRUCTURAL = new Set(['open', 'fold', 'snapshot', 'close']);
+const TRANSIENT =
+  /XCTEST_RECORDED_FAILURE|runner session was invalidated|may not have been performed|No active session|SESSION_NOT_FOUND|Daemon request timed out|CommandRunnerStarting|Starting XCTest runner/i;
+
+function parseArgs(argv) {
+  const opts = {
+    udid: undefined,
+    session: 'duo-pose-semantic',
+    stateDir: join(tmpdir(), 'duo-pose-semantic-state'),
+    app: 'Agent Device Tester',
+    artifactsDir: undefined,
+    demoGeometryMutation: false,
+    demoSkipHomeReset: false,
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const flag = argv[i];
+    const next = () => {
+      const value = argv[i + 1];
+      if (value === undefined) fail(`missing value for ${flag}`, `Pass a value after ${flag}.`);
+      i += 1;
+      return value;
+    };
+    switch (flag) {
+      case '--udid':
+        opts.udid = next();
+        break;
+      case '--session':
+        opts.session = next();
+        break;
+      case '--state-dir':
+        opts.stateDir = next();
+        break;
+      case '--app':
+        opts.app = next();
+        break;
+      case '--artifacts-dir':
+        opts.artifactsDir = next();
+        break;
+      case '--demo-geometry-mutation':
+        opts.demoGeometryMutation = true;
+        break;
+      case '--demo-skip-home-reset':
+        opts.demoSkipHomeReset = true;
+        break;
+      default:
+        fail(`unknown flag ${flag}`, 'Run with no flags to see usage.');
+    }
+  }
+  opts.artifactsDir ??= join(opts.stateDir, 'artifacts');
+  return opts;
+}
+
+function fail(message, hint) {
+  process.stderr.write(`\nSETUP FAILED: ${message}\n${hint ? `HINT: ${hint}\n` : ''}`);
+  process.exit(1);
+}
+
+function assertSetup(condition, message, hint) {
+  if (!condition) fail(message, hint);
+}
+
+const opts = parseArgs(process.argv.slice(2));
+assertSetup(
+  Boolean(DEVELOPER_DIR),
+  'DEVELOPER_DIR is not set.',
+  'Pin it to a Duo-capable Xcode, e.g. DEVELOPER_DIR=/Applications/Xcode-27.1.0-Beta.app/Contents/Developer.',
+);
+assertSetup(
+  Boolean(opts.udid),
+  '--udid is required.',
+  'Pass the UDID of a booted iPhone Duo simulator.',
+);
+
+// Keep the long fold/waits from tripping the default 5-minute idle reap for this local run.
+const CHILD_ENV = {
+  ...process.env,
+  DEVELOPER_DIR,
+  FORCE_COLOR: '0',
+  AGENT_DEVICE_DAEMON_IDLE_TIMEOUT_MS: '1800000',
+  AGENT_DEVICE_IOS_RUNNER_IDLE_STOP_MS: '1800000',
+};
+const GLOBALS = [
+  '--platform',
+  'ios',
+  '--udid',
+  opts.udid,
+  '--session',
+  opts.session,
+  '--state-dir',
+  opts.stateDir,
+];
+
+function exec(cmd, args) {
+  return new Promise((res, rej) => {
+    execFile(cmd, args, { env: CHILD_ENV, maxBuffer: 64 * 1024 * 1024 }, (err, stdout, stderr) => {
+      if (err) rej(Object.assign(err, { stdout, stderr }));
+      else res(stdout);
+    });
+  });
+}
+
+function cli(args, { json = false, allowFail = false } = {}) {
+  const full = [...args, ...GLOBALS, ...(json ? ['--json'] : [])];
+  return exec(process.execPath, [CLI, ...full])
+    .then((stdout) => {
+      if (!json) return stdout;
+      let parsed;
+      try {
+        parsed = JSON.parse(stdout);
+      } catch {
+        throw new Error(`non-JSON output for: ${args.join(' ')}`);
+      }
+      if (parsed.success) return parsed.data;
+      throw Object.assign(
+        new Error(parsed.error?.code ? `${parsed.error.code}: ${parsed.error.message}` : 'failed'),
+        {
+          code: parsed.error?.code,
+        },
+      );
+    })
+    .catch((error) => {
+      if (allowFail) return undefined;
+      throw error;
+    });
+}
+
+async function command(args, { json = false } = {}) {
+  try {
+    return await cli(args, { json });
+  } catch (error) {
+    const dropped =
+      error.code === 'SESSION_NOT_FOUND' || /No active session/i.test(String(error.message));
+    if (!dropped) throw error;
+    process.stderr.write('  (session dropped; re-opening)\n');
+    await cli(['open', opts.app]);
+    // Reopening relaunches the app, so it is a state change: never resend an interaction that
+    // carries an @ref or raw coordinates. Only pose/observation commands retry transparently;
+    // interactions surface as transient so actOn/snapshotNodes re-resolve a fresh ref.
+    if (!STRUCTURAL.has(args[0])) throw error;
+    return await cli(args, { json });
+  }
+}
+
+// ---- device / toolchain admission -----------------------------------------------------------
+
+async function admitDevice() {
+  let listing;
+  try {
+    listing = JSON.parse(await exec('xcrun', ['simctl', 'list', 'devices', '--json', 'available']));
+  } catch (error) {
+    fail('could not query simctl for available devices.', String(error.stderr || error.message));
+  }
+  const me = Object.values(listing.devices ?? {})
+    .flat()
+    .find((d) => d.udid === opts.udid);
+  assertSetup(
+    me,
+    `UDID ${opts.udid} is not an available simulator on ${DEVELOPER_DIR}.`,
+    'Boot an iPhone Duo on this toolchain and pass its UDID.',
+  );
+  assertSetup(
+    me.state === 'Booted',
+    `${me.name} (${opts.udid}) is not booted.`,
+    `Boot it: xcrun simctl boot ${opts.udid}`,
+  );
+  assertSetup(
+    /Duo/i.test(me.name),
+    `${me.name} is not an iPhone Duo.`,
+    'This scenario only exercises the iPhone Duo device type.',
+  );
+  return me;
+}
+
+// ---- interaction helpers --------------------------------------------------------------------
+
+async function snapshotNodes() {
+  let lastError;
+  for (let attempt = 0; attempt < 6; attempt += 1) {
+    try {
+      const data = await command(['snapshot', '-i'], { json: true });
+      return data.nodes ?? [];
+    } catch (error) {
+      lastError = error;
+      if (!TRANSIENT.test(String(error.message))) throw error;
+      await sleep(2000);
+    }
+  }
+  throw lastError;
+}
+
+async function warmRunner(maxMs = 150000) {
+  const deadline = Date.now() + maxMs;
+  for (let attempt = 1; Date.now() < deadline; attempt += 1) {
+    const data = await cli(['snapshot', '-i'], { json: true, allowFail: true });
+    if (data?.nodes) return;
+    process.stderr.write(`  (warming Apple runner… attempt ${attempt})\n`);
+    await sleep(3000);
+  }
+  throw new Error(
+    'Apple runner did not become ready; run `agent-device prepare ios-runner` first.',
+  );
+}
+
+async function waitForIdentifier(identifier, maxMs = 40000) {
+  const deadline = Date.now() + maxMs;
+  let nodes = await snapshotNodes();
+  while (!nodes.some((n) => n.identifier === identifier) && Date.now() < deadline) {
+    await sleep(1000);
+    nodes = await snapshotNodes();
+  }
+  return nodes;
+}
+
+// ---- semantic checks ------------------------------------------------------------------------
+
+const results = [];
+function record(name, ok, detail) {
+  results.push({ name, ok, detail });
+  process.stdout.write(`  [${ok ? 'PASS' : 'FAIL'}] ${name}${detail ? ` — ${detail}` : ''}\n`);
+}
+
+function findByIdentifier(nodes, id) {
+  return nodes.find((n) => n.identifier === id);
+}
+function findButtonByLabel(nodes, label) {
+  return nodes.find((n) => n.type === 'Button' && n.label === label);
+}
+function labelOf(nodes, identifier) {
+  return findByIdentifier(nodes, identifier)?.label;
+}
+
+// Performs a UI action against a freshly-resolved ref, retrying with a fresh snapshot on a
+// transient runner/orientation failure. Never reuses a ref across attempts. Returns the node, the
+// snapshot that ultimately resolved it, and `firstNodes`: the very first snapshot that resolved the
+// target, before any tap attempt. Callers reading a before-state must use `firstNodes`, because a
+// retried action's resolve snapshot can already reflect a tap that landed.
+async function actOnFresh(findNode, perform, what, { retries = 4 } = {}) {
+  let lastError;
+  let firstNodes;
+  for (let attempt = 0; attempt < retries; attempt += 1) {
+    const nodes = await snapshotNodes();
+    const node = findNode(nodes);
+    if (node) {
+      firstNodes ??= nodes;
+      try {
+        await perform(node);
+        return { node, nodes, firstNodes };
+      } catch (error) {
+        lastError = error;
+        if (!TRANSIENT.test(String(error.message))) throw error;
+      }
+    } else {
+      lastError = new Error(`${what}: target not present in snapshot`);
+    }
+    await sleep(1500 + attempt * 1000);
+  }
+  throw lastError ?? new Error(`${what}: action failed`);
+}
+
+function actOn(findNode, perform, what, opts) {
+  return actOnFresh(findNode, perform, what, opts).then((r) => r.node);
+}
+
+// Waits until the route identified by `want` is active and `gone` has left the tree, then returns
+// that snapshot. The `-i` snapshot carries only the active screen, so an absent route title proves
+// the previous screen is no longer mounted.
+async function waitForActiveRoute(want, gone, { maxMs = 8000, pollMs = 400 } = {}) {
+  const deadline = Date.now() + maxMs;
+  let nodes = await snapshotNodes();
+  while (Date.now() < deadline) {
+    if (findByIdentifier(nodes, want) && !findByIdentifier(nodes, gone)) return nodes;
+    await sleep(pollMs);
+    nodes = await snapshotNodes();
+  }
+  return nodes;
+}
+
+function gotoTab(label) {
+  return actOn(
+    (n) => findButtonByLabel(n, label),
+    (node) => command(['click', `@${node.ref}`]),
+    `tab ${label}`,
+  );
+}
+function tapIdentifier(identifier, what) {
+  return actOn(
+    (n) => findByIdentifier(n, identifier),
+    (node) => command(['click', `@${node.ref}`]),
+    what ?? identifier,
+  );
+}
+function longPressIdentifier(identifier, what) {
+  return actOn(
+    (n) => findByIdentifier(n, identifier),
+    (node) => command(['longpress', `@${node.ref}`, '700']),
+    what ?? identifier,
+  );
+}
+
+// A fold re-lays-out the app; a tap during the re-layout fails as a recorded XCTest failure. Wait
+// until the tab-bar geometry stops changing between snapshots.
+async function waitForStable({ maxMs = 18000, pollMs = 1500 } = {}) {
+  const deadline = Date.now() + maxMs;
+  let previous;
+  while (Date.now() < deadline) {
+    await sleep(pollMs);
+    const nodes = await snapshotNodes();
+    const sig = JSON.stringify(
+      nodes
+        .filter((n) => n.type === 'Button')
+        .map((n) => [
+          n.label ?? n.identifier,
+          Math.round(n.rect?.x ?? -1),
+          Math.round(n.rect?.y ?? -1),
+        ]),
+    );
+    if (sig && sig === previous) return;
+    previous = sig;
+  }
+}
+
+async function fold(pose) {
+  const data = await command(['fold', pose], { json: true });
+  const screen = data.screen
+    ? `${data.screen.widthPt}x${data.screen.heightPt}pt on ${data.screen.display}`
+    : 'unknown';
+  process.stdout.write(`\n# fold ${pose}: hinge ${data.hingeAngleDegrees}°, lit ${screen}\n`);
+  await waitForStable();
+  return data;
+}
+
+// ---- scenario -------------------------------------------------------------------------------
+
+function parseScale(status) {
+  const m = /scale\s+([0-9.]+)/.exec(String(status));
+  return m ? Number(m[1]) : Number.NaN;
+}
+function cartCounts(nodes) {
+  return nodes
+    .filter((n) => /In cart:\s*\d+/.test(String(n.label)))
+    .map((n) => Number(/In cart:\s*(\d+)/.exec(n.label)[1]));
+}
+
+// Presses the Catalog tab and requires a real route transition, not just a presence that could be
+// stale. From the same snapshot that resolved the tap's ref, `catalog-title` must be ABSENT (we are
+// on Home) before the tap; after it `catalog-title` must be PRESENT while `home-title` is GONE. The
+// `-i` snapshot carries only the active screen, so proving absent->present rejects a no-op tap, an
+// off-target tap, and any navigator that kept the previous screen mounted. In the open pose it also
+// increments the cart counter — a value-based activation effect.
+async function activateCatalog(pose, artifacts) {
+  const { firstNodes: before } = await actOnFresh(
+    (n) => findButtonByLabel(n, 'Catalog'),
+    (node) => command(['click', `@${node.ref}`]),
+    'Catalog tab',
+  );
+  const catalogBefore = Boolean(findByIdentifier(before, 'catalog-title'));
+  const homeBefore = Boolean(findByIdentifier(before, 'home-title'));
+  const after = await waitForActiveRoute('catalog-title', 'home-title');
+  const catalogAfter = Boolean(findByIdentifier(after, 'catalog-title'));
+  const homeAfter = Boolean(findByIdentifier(after, 'home-title'));
+  const ok = !catalogBefore && homeBefore && catalogAfter && !homeAfter;
+  record(
+    `press Catalog tab routes and activates it (${pose})`,
+    ok,
+    `catalog ${catalogBefore ? 'present' : 'absent'}->${catalogAfter ? 'present' : 'absent'}, ` +
+      `home ${homeBefore ? 'present' : 'absent'}->${homeAfter ? 'present' : 'absent'}`,
+  );
+  if (!ok) await saveFailureSnapshot(artifacts, `catalog-${pose}`);
+
+  if (pose === 'open') {
+    let nodes = await snapshotNodes();
+    const cartBefore = cartCounts(nodes);
+    await tapIdentifier('add-citrus-kit', 'add to cart');
+    nodes = await snapshotNodes();
+    const cartAfter = cartCounts(nodes);
+    record(
+      'Add to cart increments the cart counter (open)',
+      cartAfter.some((c, i) => c > (cartBefore[i] ?? -1)),
+      `${JSON.stringify(cartBefore)} -> ${JSON.stringify(cartAfter)}`,
+    );
+  }
+}
+
+// The loop returns to Home before every subsequent fold. Assert Home is actually the active route so
+// a missed reset surfaces here instead of being mistaken for the next pose's activation result. A
+// lingering `catalog-title`/`settings-title` (a navigator that kept the screen mounted) also fails.
+async function resetToHomeAndAssert(pose, artifacts) {
+  if (!opts.demoSkipHomeReset) await gotoTab('Home');
+  const nodes = await waitForActiveRoute('home-title', 'catalog-title');
+  const home = Boolean(findByIdentifier(nodes, 'home-title'));
+  const catalog = Boolean(findByIdentifier(nodes, 'catalog-title'));
+  const settings = Boolean(findByIdentifier(nodes, 'settings-title'));
+  const ok = home && !catalog && !settings;
+  record(
+    `Home is the active route before the next fold (${pose})`,
+    ok,
+    `home=${home} catalog=${catalog} settings=${settings}`,
+  );
+  if (!ok) await saveFailureSnapshot(artifacts, `home-reset-${pose}`);
+}
+
+// Item 3: scroll to reveal a canary, then long-press it and assert its dedicated count moves.
+// Item 4: one multipointer pinch whose origin is derived from the current target bounds.
+async function openPoseChecks() {
+  await gotoTab('Settings');
+  let nodes = await snapshotNodes();
+  assertRecord(findByIdentifier(nodes, 'settings-title'), 'Settings surface opened (open pose)');
+  await tapIdentifier('open-automation-lab', 'open automation lab');
+  nodes = await snapshotNodes();
+  assertRecord(findByIdentifier(nodes, 'automation-title'), 'Automation lab opened (open pose)');
+
+  const beforeScroll = new Set(nodes.map((n) => n.identifier).filter(Boolean));
+  await command(['scroll', 'down']);
+  nodes = await snapshotNodes();
+  const count = findByIdentifier(nodes, 'automation-longpress-count');
+  record(
+    'scroll reveals a new canary (open)',
+    Boolean(count && !beforeScroll.has('automation-longpress-count')),
+    count
+      ? `automation-longpress-count visible with "${count.label}"`
+      : 'automation-longpress-count still hidden',
+  );
+
+  const countBefore = Number(/Long presses:\s*(\d+)/.exec(String(count?.label))?.[1]);
+  await longPressIdentifier('automation-longpress', 'long-press canary');
+  nodes = await snapshotNodes();
+  const after = labelOf(nodes, 'automation-longpress-count');
+  const countAfter = Number(/Long presses:\s*(\d+)/.exec(String(after))?.[1]);
+  // Require a strict increment, not an exact +1: a transient retry can deliver two presses, and
+  // two still proves the long press registered, while zero (an unregistered press) must fail.
+  record(
+    'long press increments its dedicated count (open)',
+    Number.isFinite(countBefore) && Number.isFinite(countAfter) && countAfter > countBefore,
+    `"Long presses: ${countBefore}" -> "${after}"`,
+  );
+
+  // The automation lab is pushed over the tab stack, so return to a tab surface before the Home
+  // pinch canary. Its own "Continue to catalog" control pops back onto the tab navigator.
+  await tapIdentifier('automation-continue-catalog', 'continue to catalog');
+  await gotoTab('Home');
+  nodes = await snapshotNodes();
+  const target = findByIdentifier(nodes, 'transform-gesture-target');
+  if (!target) throw new Error('transform-gesture-target not present on Home in the open pose');
+  const scaleBefore = parseScale(labelOf(nodes, 'gesture-transform-status'));
+  let origin;
+  if (opts.demoGeometryMutation) {
+    // Stale/wrong geometry: derive the origin from a DIFFERENT control's bounds (the drag source,
+    // above the transform target) instead of the target's own bounds. The pinch is a valid
+    // in-viewport gesture that lands off-target, so the transform scale never moves.
+    const wrong = findByIdentifier(nodes, 'drag-source') ?? findByIdentifier(nodes, 'home-title');
+    if (!wrong)
+      throw new Error('demo-geometry-mutation: no off-target control to derive wrong bounds from');
+    origin = [
+      Math.round(wrong.rect.x + wrong.rect.width / 2),
+      Math.round(wrong.rect.y + wrong.rect.height / 2),
+    ];
+    process.stdout.write(`  MUTATED pinch origin (wrong control bounds): ${origin.join(',')}\n`);
+  } else {
+    origin = [
+      Math.round(target.rect.x + target.rect.width / 2),
+      Math.round(target.rect.y + target.rect.height / 2),
+    ];
+    process.stdout.write(`  derived pinch origin: ${origin.join(',')}\n`);
+  }
+  await command(['gesture', 'pinch', '1.5', String(origin[0]), String(origin[1])]);
+  nodes = await snapshotNodes();
+  const scaleAfter = parseScale(labelOf(nodes, 'gesture-transform-status'));
+  record(
+    'multipointer pinch changes recognized scale (open)',
+    Number.isFinite(scaleAfter) && Math.abs(scaleAfter - 1) > 0.01,
+    `scale ${scaleBefore} -> ${scaleAfter} at origin ${origin.join(',')}`,
+  );
+}
+
+function assertRecord(node, name) {
+  record(name, Boolean(node));
+  if (!node) throw new Error(`${name}: not present`);
+}
+
+async function saveFailureSnapshot(artifacts, tag) {
+  try {
+    const data = await command(['snapshot', '-i'], { json: true });
+    const path = join(artifacts, `${tag}-${Date.now()}.json`);
+    writeFileSync(path, JSON.stringify(data, null, 2));
+    process.stdout.write(`  (failure snapshot: ${path})\n`);
+    return path;
+  } catch {
+    return undefined;
+  }
+}
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+async function main() {
+  const device = await admitDevice();
+  process.stdout.write(
+    `Duo pose semantic check\n  device: ${device.name} (${device.udid})\n  toolchain: ${DEVELOPER_DIR}\n  session: ${opts.session}\n  demo-geometry-mutation: ${opts.demoGeometryMutation}\n  demo-skip-home-reset: ${opts.demoSkipHomeReset}\n\n`,
+  );
+  mkdirSync(opts.artifactsDir, { recursive: true });
+
+  let cleaned = false;
+  const cleanup = async () => {
+    if (cleaned) return;
+    cleaned = true;
+    try {
+      await fold(START_POSE);
+    } catch {
+      process.stderr.write('  (could not restore starting pose)\n');
+    }
+    await cli(['close'], { allowFail: true });
+  };
+
+  try {
+    await command(['open', opts.app, '--relaunch']);
+    await warmRunner();
+    const nodes = await waitForIdentifier('home-title');
+    record(
+      'fixture surface verified (Home)',
+      Boolean(findByIdentifier(nodes, 'home-title')),
+      'home-title present after launch',
+    );
+
+    for (const pose of POSES) {
+      await fold(pose);
+      await activateCatalog(pose, opts.artifactsDir);
+      if (pose === 'open') await openPoseChecks();
+      await resetToHomeAndAssert(pose, opts.artifactsDir);
+    }
+    await cleanup();
+  } catch (error) {
+    process.stderr.write(`\nRUN ERROR: ${error && error.message ? error.message : error}\n`);
+    await saveFailureSnapshot(opts.artifactsDir, 'run-error');
+    await cleanup();
+    report();
+    process.exit(1);
+  }
+
+  report();
+  process.exit(results.some((r) => !r.ok) ? 1 : 0);
+}
+
+function report() {
+  const failed = results.filter((r) => !r.ok);
+  process.stdout.write(
+    `\n${results.length - failed.length}/${results.length} semantic checks passed\n`,
+  );
+  if (opts.demoGeometryMutation) {
+    process.stdout.write(
+      '(geometry-mutation demo: the pinch scale check is EXPECTED to fail here)\n',
+    );
+  }
+  if (opts.demoSkipHomeReset) {
+    process.stdout.write(
+      '(skip-home-reset demo: a closed/half-open activation or Home-reset check is EXPECTED to fail)\n',
+    );
+  }
+  for (const r of failed) process.stdout.write(`  FAILED: ${r.name} — ${r.detail ?? ''}\n`);
+}
+
+main().catch((error) => {
+  process.stderr.write(`\nUNEXPECTED: ${error && error.stack ? error.stack : error}\n`);
+  process.exit(1);
+});

From 215229b4aefc3fc243391ef676f7e59fa9d9abbc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Tue, 22 Sep 2026 13:11:55 +0200
Subject: [PATCH 016/132] =?UTF-8?q?docs(adr):=20scroll=20clip=20authority?=
 =?UTF-8?q?=20=E2=80=94=20ownership=20is=20the=20parent=20edge=20(#2755)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* docs(adr): record scroll clip authority for iOS snapshot presentation

An interactive snapshot of a list dropped every row after a row holding
selectable text: a UITextView is a UIScrollView, XCTest publishes its
indicator inside the text, and the presentation attributed that indicator
to the surrounding list, so the list's visible band became one line of
text and everything below it was clipped (#2214, fixed by #2740).

The type-specific fix closed one instance. ADR 0026 records the rule that
keeps the class out: indicator ownership is a fact the producer reports,
the visible band stays host interpretation, and an inferred attribution
gets hint authority only — it cannot eject a node. Reshape and eject
become separate rule APIs, scroll capability becomes a matrix instead of
one boolean answered five different ways, and every ejection carries a
typed reason the differential can check.

Design contract: #2754.

* docs(adr): read scroll indicator ownership from the parent edge

Review found the first draft built eight contracts on top of a bug that a
parent-edge lookup removes. UIKit publishes an indicator inside its own
scroll view and projection preserves that edge, because every scroll host
is regular-eligible in both languages; the ancestor walk past the parent is
what misattributed the text view's indicator in the first place. Reading the
parent instead retires the proposed IosRunnerPresentation field, its
capture-local indexing and remapping, the ownership capability matrix, and
the two-tree split.

Also corrects the band's premise: the pinned Settings tree has the
CollectionView frame at 0-874 with an indicator track at 116-812, so the
frame spans the bars and safe area rather than reporting a content extent.
Drops the two-API reshape/eject split, which does not hold against ~23
suppression sites across ten rules, and against a reshape surface that still
accepts rect. Keeps the decision: ownership is read, ejection needs
evidence, every removal carries a disposition.

Measured while revising: the full unit suite passes with parent-edge
ownership, and a synthetic WebView row keeps rows that main drops.

* docs(adr): name scrollarea as the iOS-scoped exception

Review asked the eligibility claim be scoped, since isScrollableSnapshotType
also accepts scrollarea and neither eligible set contains it. Verified the
scope is real rather than hypothetical: macOS desktop capture reaches these
rules through snapshot-desktop-surface -> ios-snapshot-runtime ->
publishIosSnapshot, and its helper emits ScrollArea from AXScrollArea while
the iOS runner never does. So "every scroll host is regular-eligible" is
written as an iOS claim, with a ScrollArea decision owed on that surface
before the parent-edge rule is reused there.

Also names the divergence left vague before: only tree.ts accepts scrollarea.
Counts made exact while there: 23 suppression sites across ten rules, and
scroll and noise-overlay already patch rects while ejecting.

* docs(adr): scope visibility ejection and name the real rect-rewriting pair

The removal row read as if every ejection needed a clip-fold result or a
parent-edge owner. Nineteen of the 23 sites delegate semantics or drop
decoration and keep their own authority, so the row and the paragraph now
name the four visibility-driven sites the ADR actually governs, plus the
clip fold's inclusion decision, and a second row states that compaction is
out of scope.

Corrects the rect-rewriting pair: transitions rewrites a field's rect and
ejects the title and image in one pass, while noise-overlay patches rects
in a presentation function that receives replacements only and ejects from
a separate suppression function. That module already has the split the
rejected API proposed, so it is cited as the precedent instead.

Names why the runtime guard was rejected: a threshold either fires on
ordinary compaction or is loose enough to pass a 74 to 20 collapse. Cites
#1797 for the fold's leak class with #1784 adjacent instead of claiming one
class, drops the drafting narrative from the refuted field, records the
unpinned self branch, and notes the table's own self case.
---
 docs/adr/0026-scroll-clip-authority.md | 114 +++++++++++++++++++++++++
 docs/adr/README.md                     |   1 +
 2 files changed, 115 insertions(+)
 create mode 100644 docs/adr/0026-scroll-clip-authority.md

diff --git a/docs/adr/0026-scroll-clip-authority.md b/docs/adr/0026-scroll-clip-authority.md
new file mode 100644
index 0000000000..9a4eaff9aa
--- /dev/null
+++ b/docs/adr/0026-scroll-clip-authority.md
@@ -0,0 +1,114 @@
+# ADR 0026: Scroll Clip Authority — Ownership Is the Parent Edge
+
+## Status
+
+Proposed (2026-09-22). Refines ADR 0004's fact/interpretation boundary for scroll geometry; does not
+supersede it. Implementation contract: #2754.
+
+An interactive iOS snapshot of a list dropped every row after a row holding selectable text. A
+`UITextView` is a UIScrollView and XCTest publishes its scroll indicator inside the text, so the
+indicator was attributed to the surrounding list, the list's visible band became one 22 px line, and
+everything below it was clipped out of `snapshot -i` (#2214 in 0.21.0, patched for that one type by
+#2740). The root cause is not the unrecognised type — it is that presentation **inferred** an owner by
+walking up past the indicator's parent, and that guess decided which nodes existed in the output.
+
+## Rules at a glance
+
+| Situation | Behavior |
+| --- | --- |
+| Which scroll view an indicator reports on | Its **parent**, when that parent is a scroll type (or the scroll host itself when it carries the label — open, below). UIKit publishes an indicator inside its own scroll view, and the producer's tree already says so |
+| An indicator whose parent is not a scroll type — `TextView`, `WebView`, a cell | Owns nothing. No band, no clip, and the host's own scrollability stays with that host |
+| The visible band | Derived by presentation from the owner's frame and the indicator's track. Never reported by a producer |
+| Removing a node **because a scroll band hides it** | Requires evidence: the clip fold's result, or a band whose owner is the indicator's parent. A guess about ownership may not do it |
+| Removing a node by semantic delegation — a collapsed row, a duplicate label, a wrapper's content | Out of scope here. That is compaction, and it keeps its own authority |
+| Weaker evidence than a parent edge | Directional hints (`hiddenContentAbove` / `hiddenContentBelow`) and nothing that changes membership |
+| Every removed source | Ends with a typed disposition. Internal evidence, never wire vocabulary |
+
+## Contracts
+
+**Ownership is read, not inferred.** A scroll view's indicators arrive as its children, so the parent
+edge is the producer's own claim and no new contract field, cross-language ownership table, or
+capture-local index remapping is needed. That edge survives to presentation on both input stages
+because every scroll host iOS can emit is regular-eligible, so projection re-parents an indicator only to
+that host: `REGULAR_ELIGIBLE_TYPES` in `ios-snapshot-engine/projection.ts` and `eligibleInteractiveTypes`
+in `SnapshotPresentationProjection.swift` both carry `Cell`, `CollectionView`, `ScrollView`, `Table`,
+`TextView`, and `WebView`. Those two lists are one fact in two languages and must stay in step.
+
+That eligibility claim is scoped to iOS, and `scrollarea` is why. `isScrollableSnapshotType` accepts it,
+neither eligible set contains it, and the iOS runner never emits it — it originates in the macOS helper's
+`AXScrollArea` mapping. That helper's trees do reach these rules, through `snapshot-desktop-surface.ts`
+→ `ios-snapshot-runtime.ts` → `publishIosSnapshot`, so on that surface a `ScrollArea` host can be dropped
+by eligibility while its children re-parent past it, which leaves a parent-edge lookup with no owner.
+Reusing this rule for macOS therefore needs a `ScrollArea` eligibility decision made there, not carried
+over from the iOS claim above.
+
+**Why the band exists at all.** XCTest reports a scroll view's frame spanning the bars and the safe
+area, not the visible track. In the pinned Settings tree the `CollectionView` frame is the whole screen,
+0–874, while its indicator track is 116–812 (`runner-presentation.test.ts`). The frame alone therefore
+cannot express visibility, and deleting indicator clipping would return content that is scrolled under
+the chrome. The band is necessary; only *who owns it* was ever in question.
+
+**Visibility ejection needs evidence, and every ejection is recorded.** Most of the engine's 23 removal
+sites delegate semantics or drop decoration — a collapsed row, a duplicate label, a wrapper's content, a
+system indicator — and this ADR does not touch their authority. It governs the four visibility-driven
+sites among them, the scroll band's one and the keyboard band's three, alongside the clip fold's own
+inclusion decision in `geometry-policy.ts`. Of those, the scroll band is the one a weak signal can reach,
+and directional hints are its safe outlet when nothing is the indicator's parent. Every source index ends
+either presented, with its representatives, or removed with a typed reason, which makes the ledger complete
+by construction rather than gated. The existing `presentedIndexesBySourceIndex` in
+`ios-snapshot-engine/semantic-index.ts` is the shape to extend; a second parallel ledger would be a second
+source of truth.
+
+## Refuted alternatives
+
+- **A producer-reported ownership field on `IosRunnerPresentation`.** The parent edge already carries the
+  fact, so a field would add validation, capture-local indexing, and remapping hazards of its own for
+  nothing.
+- **Producer-computed visible bands.** Moves interpretation back across the process boundary ADR 0004
+  removed it from. The band stays host-side.
+- **An owner found by walking ancestors.** That walk is the incident. Skipping only the types known to
+  scroll — #2740's fix — leaves the next scroll-shaped host (`WebView`, a map view, a paged cell) to
+  reopen it.
+- **One universal "is a scroll container" set, or a capability matrix of ownership/clip/termination
+  booleans.** Five sites answer variants of this question today (`ios-snapshot-engine/tree.ts`,
+  `geometry-policy.ts`, `invariants.ts`, `SnapshotVisibilityFold.swift`, `RunnerTests+Snapshot.swift`)
+  and their contents already differ: only `tree.ts` accepts `scrollarea`, the type the macOS helper emits
+  and the iOS runner never does. Characterise each site before reshaping any of them; with parent-edge
+  ownership the shape this rule needs is the existing `isScrollableSnapshotType`.
+- **A rule-graph or effect system, and a two-API reshape/eject split.** Rejected on the shape of the
+  code. Nineteen of the 23 `suppressNode` sites legitimately eject, so handing a membership API to "one
+  clip rule" restores the convention it claims to enforce. Two functions already rewrite rects *and* eject
+  in one pass — the scroll rule and the navigation-bar affordance rule in `transitions.ts` — while
+  `noise-overlay` shows the split done properly: its presentation pass receives replacements only and a
+  separate suppression pass receives the ejecting surface. And a reshape surface that still accepts `rect`
+  would permit the exact rewrite that caused this incident. Inventory the sites in #2754 first; redesign
+  only what the inventory justifies.
+- **A runtime guard on shrinkage instead of the differential.** A threshold would either fire on ordinary
+  compaction — the Settings tree legitimately drops rows under the chrome — or sit loose enough to wave
+  through a 74 → 20 collapse. The differential already asserts interactive ⊆ regular ⊆ raw; what it lacks
+  is coverage of the runner stage, since `assertProjectionSubsets`
+  (`ios-snapshot-engine/properties.test.ts`) builds acquired inputs only and the Swift differential drops
+  interactive cases. Extending it to `stage: 'presented'` is what makes any future shrinkage visible.
+
+## Consequences and open evidence
+
+- **Under-clipping is the new risk.** Dropping the walk means a tree that places an indicator under a
+  labelled wrapper rather than directly under its scroll view gets no band, so content scrolled under the
+  chrome survives in the output. That is a leak of a different kind from the one the clip fold owns
+  (#1797, with #1784 adjacent on private-AX projection); it is the band's own job, and nothing else covers
+  it. Measured so far: the full unit suite passes with parent-edge ownership, and a synthetic `WebView` row
+  keeps rows that `main` drops. Real captured trees must be surveyed for that wrapper shape before landing.
+- **The `WebView` instance is synthetic.** The mechanism is confirmed in a hand-built tree; that XCTest
+  publishes a `WKWebView`'s indicator the same way is unverified.
+- **The self case is unpinned.** The rule also treats a scroll-typed node carrying an indicator label as
+  its own owner. No test exercises that branch — parent-only ownership without it passes the full suite —
+  so #2754 step 1 keeps it with a case or deletes it deliberately, rather than inheriting it.
+- **macOS is already a second consumer of these rules.** Desktop capture runs the engine through
+  `snapshot-desktop-surface.ts` → `ios-snapshot-runtime.ts` → `publishIosSnapshot`, and its trees carry
+  `ScrollArea`, which neither eligible set admits. The parent-edge rule needs its own decision there
+  before it is reused, not a carry-over from the iOS claim.
+- **Ejection inventory precedes any API change.** 23 suppression sites across ten rules, and two of them
+  (`scroll`, `transitions`) already rewrite rects on other nodes in the same pass that ejects — the
+  combination the proposed API split claimed to make impossible.
+- **The 74 → 67 node delta on the reporting screen is unexplained.** No captured artifact exists, so
+  neither number is an acceptance baseline.
diff --git a/docs/adr/README.md b/docs/adr/README.md
index dc651acea7..809f5aa11c 100644
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@ -27,6 +27,7 @@
 | [0023 End-State Entry-to-Platform Hop Trace](0023-end-state-hop-trace.md) | the hop counting definition, the ordered `press`/Android and dual-arm `snapshot`/iOS chains, per-hop roles, and the deletion test behind the numbers ADR 0019 and ADR 0022 quote |
 | [0024 Screen Recording — One Coordinator, Two Facts (Proposed)](0024-screen-recording-provable-signal.md) | `record start`/`stop` lifecycle, the export-exists / recorder-stopped split, backend stop-and-collect contract, recovery through the coordinator, the ADR 0019 §5 amendment and the failed-finish cleanup fix |
 | [0025 Foldable Apple Panels — Capture the Lit Panel](0025-foldable-apple-panels.md) | iPhone Duo outer/inner panels, CoreDevice display info as the only screen authority, why `simctl`'s implicit display default captures a black panel, derived (never asserted) pose, and why no pose-control command exists |
+| [0026 Scroll Clip Authority — Ownership Is the Parent Edge (Proposed)](0026-scroll-clip-authority.md) | iOS scroll indicators and the visible band, why ownership is read from the parent edge instead of an ancestor walk, what may remove a node from an interactive snapshot, and ejection dispositions |
 
 ADRs record *why*; the registries and gates they describe are the living source of truth — when
 prose and a registry disagree, the registry wins and the ADR needs a follow-up.

From 6f4a9dc88461961af69911b9dda1e79aeb067b2b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Tue, 22 Sep 2026 13:31:50 +0200
Subject: [PATCH 017/132] fix(ios): capture the display that hosts the app, not
 the main screen (#2741)

* fix(ios): capture the display that owns a window, not the main screen

A foldable lights one panel at a time while XCUIScreen.main names one fixed
panel, so an app on the other panel was captured as a valid PNG of black. The
runner now asks the target app's window first and the system surface's window
second, reads the display off that same window instance, and encodes the
capture upright, reporting the display ID, the pixel size it encoded, and the
pixels-per-point of that image so the host normalizes density from the capture
instead of a panel it guessed.

The home screen is SpringBoard's window, so a capture with no session app still
has a display that owns a window; a capture fails closed with a typed reason
only when neither resolves one. An app with no window is refused on the query's
own answer rather than on geometry alone. The screenshot command skips the
app-activation preflight, so it resolves the requested bundle id for observation
without ever foregrounding an app to see which display it is on.

Co-authored-by: Apex <noreply@callstack.com>

* test(ios-runner): restore the window-path order proof and refuse typed screens

The fixture resolved on the exists read, so the window-path tests resolved
the window before the call and could no longer see a screen-first change
route a foldable gesture to display 1. The frame read resolves again, the
exists pre-reads are gone, and two new refusals pin the window path to the
typed screen reason: a window answering display ID 0 and a window whose
screen read raises both fail with no resolved window display ID. The window
resolver's frame read now sits inside the exception catcher, so the raise
answer carries the same typed window refusal and log line the application
walk gives.

* test(ios-runner): pin the caught frame read on the window display path

The window resolver moved its frame read inside the exception catcher, but
no test drove a frame lookup that raises, so the catcher was carried on the
comment alone. KVC raises on a key the runtime stops answering, which is how
a private XCTest read fails when it renames, and the gesture path hands this
window across a command boundary. The case now expects the typed window
refusal and leaves the caller's display ID untouched.

---------

Co-authored-by: Apex <noreply@callstack.com>
---
 .../RunnerAppScreenCapture.swift              | 175 +++++++++++++++++
 .../RunnerTests+CommandExecution.swift        |  66 ++++---
 .../RunnerTests+Keyboard.swift                |  24 ++-
 .../RunnerTests+Lifecycle.swift               |  64 ++++++-
 .../RunnerTests+Models.swift                  |  13 ++
 .../RunnerTests+Navigation.swift              |  35 +++-
 .../RunnerXCTestEventBridge.h                 |  26 +++
 .../RunnerXCTestEventBridge.m                 | 164 ++++++++++++++--
 .../RunnerTests+AppScreenCaptureTests.swift   | 123 ++++++++++++
 .../RunnerTests+LifecycleTests.swift          |  44 +++++
 .../RunnerTests+XCTestEventBridgeTests.swift  | 179 ++++++++++++++++--
 docs/adr/0025-foldable-apple-panels.md        |  76 +++++---
 .../core/__tests__/display-inventory.test.ts  |  70 +++++--
 .../src/core/__tests__/screenshot.test.ts     | 110 ++++++++++-
 .../platform-apple/src/core/screenshot.ts     | 101 ++++++++--
 .../runner-error-classification.test.ts       |  18 ++
 .../src/runner/runner-contract.ts             |  19 ++
 17 files changed, 1188 insertions(+), 119 deletions(-)
 create mode 100644 apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerAppScreenCapture.swift
 create mode 100644 apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+AppScreenCaptureTests.swift

diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerAppScreenCapture.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerAppScreenCapture.swift
new file mode 100644
index 0000000000..9429ad3e0a
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerAppScreenCapture.swift
@@ -0,0 +1,175 @@
+import XCTest
+#if canImport(UIKit)
+import UIKit
+#endif
+
+/// One capture of the display that actually hosts the target app, with the facts needed to read its
+/// pixels without guessing a panel: which display was captured, how many pixels the encoded image
+/// holds, and how many of them represent one point.
+struct CapturedAppScreen {
+  let image: RunnerImage
+  let displayID: UInt
+  let pixelWidth: Int
+  let pixelHeight: Int
+  let pixelsPerPoint: Double
+}
+
+/// Why the runner could not name the display hosting the target app. Carried as a reason code
+/// rather than as message text so a required capture can fail closed with a code the host keys on,
+/// and an optional observation can report "unknown" without parsing a sentence (#2728).
+enum RunnerAppScreenCaptureFailure: String, Error {
+  case unresolvedWindow = "APP_SCREEN_WINDOW_UNRESOLVED"
+  case unresolvedScreen = "APP_SCREEN_UNRESOLVED"
+  case unrenderableImage = "APP_SCREEN_CAPTURE_UNRENDERABLE"
+
+  init(_ failure: RunnerApplicationScreenFailure) {
+    switch failure {
+    case .unresolvedWindow:
+      self = .unresolvedWindow
+    default:
+      self = .unresolvedScreen
+    }
+  }
+
+  var message: String {
+    switch self {
+    case .unresolvedWindow:
+      return "Neither the target app nor the system surface resolved a window, so no display could be named."
+    case .unresolvedScreen:
+      return "The resolved app window did not report the display it is shown on."
+    case .unrenderableImage:
+      return "The resolved display handed back an image that could not be drawn upright."
+    }
+  }
+
+  var hint: String {
+    switch self {
+    case .unresolvedWindow:
+      return "The capture follows the display that owns a window, so this is a runtime that is answering no window for any process; runner.log names the window frame and the query answer it refused."
+    case .unresolvedScreen:
+      return "Retry the capture. If it persists, the XCTest runtime is not reporting the window's display; runner.log names the window frame it resolved."
+    case .unrenderableImage:
+      return "Retry the capture. The display was resolved, so this is the capture itself failing, not a panel question."
+    }
+  }
+}
+
+#if canImport(UIKit) && os(iOS)
+extension RunnerTests {
+  /// Captures the display hosting `app` instead of `XCUIScreen.main`.
+  ///
+  /// On a foldable, `XCUIScreen.main` names one fixed panel while the app can be on the other, and
+  /// the panel that is dark still answers with a valid PNG of black — a capture that looks like
+  /// evidence and proves nothing. The window's own screen is the only source that follows the app,
+  /// and on a panel the system presents turned it hands back an image whose buffer is sideways, so
+  /// the pixels are redrawn upright at that image's own logical size and scale before anyone
+  /// encodes or compares them (#2728).
+  ///
+  /// Never activates `app`: an observation must not change which app is foregrounded just to get a
+  /// screen, so the caller passes the app context it already intends to observe.
+  func captureResolvedAppScreen(
+    app: XCUIApplication
+  ) -> Result<CapturedAppScreen, RunnerAppScreenCaptureFailure> {
+    var outcome: Result<CapturedAppScreen, RunnerAppScreenCaptureFailure> = .failure(
+      .unresolvedScreen
+    )
+    let capture = {
+      outcome = Self.resolveCapturedAppScreen(app: app)
+    }
+    if Thread.isMainThread {
+      capture()
+    } else {
+      DispatchQueue.main.sync(execute: capture)
+    }
+    return outcome
+  }
+
+  /// Captures the display a caller should observe, asking `app` first and the system surface second.
+  ///
+  /// A capture with no session app, or with one that is not running, still has a window on screen:
+  /// the home screen is SpringBoard's window, and its panel is the lit one. Asking the system surface
+  /// keeps that capture honest — it names a display a window actually occupies instead of reaching
+  /// for `XCUIScreen.main`, which on a foldable is one fixed panel whether or not it is dark (#2728).
+  ///
+  /// Only an unresolved *window* moves on to the system surface. A window that resolved and then
+  /// refused to name its display is the failure the host has to see, and no second question about a
+  /// different process should bury it.
+  func captureObservedScreen(app: XCUIApplication) -> Result<
+    CapturedAppScreen, RunnerAppScreenCaptureFailure
+  > {
+    selectObservedScreenCapture(
+      resolving: { captureResolvedAppScreen(app: app) },
+      fallingBack: { captureResolvedAppScreen(app: springboard) }
+    )
+  }
+
+  /// The target rule, kept apart from the two queries so the rule itself is testable: an unresolved
+  /// window asks the system surface, and nothing else does.
+  func selectObservedScreenCapture(
+    resolving: () -> Result<CapturedAppScreen, RunnerAppScreenCaptureFailure>,
+    fallingBack: () -> Result<CapturedAppScreen, RunnerAppScreenCaptureFailure>
+  ) -> Result<CapturedAppScreen, RunnerAppScreenCaptureFailure> {
+    let outcome = resolving()
+    if case .failure(.unresolvedWindow) = outcome {
+      return fallingBack()
+    }
+    return outcome
+  }
+
+  private static func resolveCapturedAppScreen(
+    app: XCUIApplication
+  ) -> Result<CapturedAppScreen, RunnerAppScreenCaptureFailure> {
+    var screen: AnyObject?
+    var displayID: UInt = 0
+    var resolution: RunnerApplicationScreenFailure = .unresolvedScreen
+    guard RunnerResolveApplicationScreen(app, &screen, &displayID, &resolution),
+      let captureScreen = screen as? XCUIScreen
+    else {
+      return .failure(RunnerAppScreenCaptureFailure(resolution))
+    }
+    let image = captureScreen.screenshot().image
+    guard let upright = runnerUprightCaptureImage(image) else {
+      return .failure(.unrenderableImage)
+    }
+    // A scale that is not a finite positive number cannot be reported to a host that divides by it,
+    // and cannot be drawn at, so the capture is refused rather than encoded with a value JSON cannot
+    // carry (#2728).
+    guard upright.scale.isFinite, upright.scale > 0 else {
+      return .failure(.unrenderableImage)
+    }
+    guard let cgImage = runnerCGImage(from: upright) else {
+      return .failure(.unrenderableImage)
+    }
+    return .success(
+      CapturedAppScreen(
+        image: upright,
+        displayID: displayID,
+        pixelWidth: cgImage.width,
+        pixelHeight: cgImage.height,
+        pixelsPerPoint: Double(upright.scale)
+      )
+    )
+  }
+
+  /// Redraws a turned capture so its encoded rows run the way the panel is presented, and leaves an
+  /// already-upright capture untouched so a single-panel capture keeps the exact bytes it produced
+  /// before panels existed. The draw box is the image's own oriented logical size and the renderer's
+  /// scale is the image's own scale: neither comes from a nominal panel size, and the one-pixel
+  /// difference between what XCTest hands back and what CoreDevice calls the panel is preserved
+  /// rather than stretched away (#2728).
+  private static func runnerUprightCaptureImage(_ image: UIImage) -> UIImage? {
+    if image.imageOrientation == .up {
+      return image
+    }
+    guard image.size.width > 0, image.size.height > 0, image.scale.isFinite, image.scale > 0 else {
+      return nil
+    }
+    let format = UIGraphicsImageRendererFormat()
+    format.scale = image.scale
+    let renderer = UIGraphicsImageRenderer(size: image.size, format: format)
+    return renderer.image { _ in
+      image.draw(in: CGRect(origin: .zero, size: image.size))
+    }
+  }
+}
+#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
index a4bed87200..e23dd7952f 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
@@ -1466,7 +1466,7 @@ extension RunnerTests {
           fps: command.fps.map { Int32($0) }
         )
         try recorder.start { [weak self] in
-          return self?.captureRunnerFrame()
+          return self?.captureRunnerFrame(app: activeApp)
         }
         activeRecording = recorder
         return Response(ok: true, data: DataPayload(message: "recording started"))
@@ -2055,7 +2055,6 @@ extension RunnerTests {
     case .snapshot:
       return try executeSnapshotPrepared(command: command, activeApp: activeApp)
     case .screenshot:
-      let screenshot: XCUIScreenshot
 #if os(macOS)
       // macOS keeps the app-targeted capture behavior for window-level screenshots.
       if let bundleId = command.appBundleId, !bundleId.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
@@ -2065,6 +2064,7 @@ extension RunnerTests {
         // Brief wait for the app transition animation to complete
         sleepFor(0.5)
       }
+      let screenshot: XCUIScreenshot
       if command.fullscreen == true {
         screenshot = XCUIScreen.main.screenshot()
       } else if let bundleId = command.appBundleId, !bundleId.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
@@ -2072,30 +2072,52 @@ extension RunnerTests {
       } else {
         screenshot = XCUIScreen.main.screenshot()
       }
-#else
-      screenshot = XCUIScreen.main.screenshot()
-#endif
-      guard let pngData = runnerPngData(for: screenshot.image) else {
-        return Response(ok: false, error: ErrorPayload(message: "Failed to encode screenshot as PNG"))
-      }
-      if command.inlineScreenshot == true {
+      return screenshotResponse(
+        image: screenshot.image,
+        inlineScreenshot: command.inlineScreenshot == true
+      )
+    #elseif os(iOS)
+      // A foldable lights one panel at a time while `XCUIScreen.main` names one fixed panel, so an
+      // app on the other panel is captured as a valid PNG of nothing. The capture comes from the
+      // display owning a window, and a display that no window can name fails this required capture
+      // instead of answering with the main screen (#2728).
+      //
+      // `.screenshot` is a runner-lifecycle command, which skips the preflight that resolves the
+      // session app, so on a fresh runner process `activeApp` is still the runner host app. The
+      // requested bundle id is resolved here and never activated: an observation must not change
+      // which app is foregrounded in order to see which display it is on (#2728).
+      switch captureObservedScreen(app: resolveAppWithoutActivation(command: command)) {
+      case .failure(let failure):
         return Response(
-          ok: true,
-          data: DataPayload(imageBase64: pngData.base64EncodedString())
+          ok: false,
+          error: ErrorPayload(code: failure.rawValue, message: failure.message, hint: failure.hint)
+        )
+      case .success(let captured):
+        // The facts travel to the host in the response and to the operator in runner.log, because a
+        // capture whose density is in question is argued from what the capture itself measured.
+        NSLog(
+          "AGENT_DEVICE_RUNNER_SCREEN_CAPTURE display=%lu pixels=%ldx%ld pixelsPerPoint=%g",
+          captured.displayID,
+          captured.pixelWidth,
+          captured.pixelHeight,
+          captured.pixelsPerPoint
+        )
+        return screenshotResponse(
+          image: captured.image,
+          inlineScreenshot: command.inlineScreenshot == true,
+          metadata: ScreenshotMetadataPayload(
+            displayID: captured.displayID,
+            pixelWidth: captured.pixelWidth,
+            pixelHeight: captured.pixelHeight,
+            pixelsPerPoint: captured.pixelsPerPoint
+          )
         )
       }
-      let fileName = "screenshot-\(Int(Date().timeIntervalSince1970 * 1000)).png"
-      let filePath = (NSTemporaryDirectory() as NSString).appendingPathComponent(fileName)
-      do {
-        try pngData.write(to: URL(fileURLWithPath: filePath))
-      } catch {
-        return Response(ok: false, error: ErrorPayload(message: "Failed to write screenshot: \(error.localizedDescription)"))
-      }
-#if os(macOS)
-      return Response(ok: true, data: DataPayload(message: filePath))
 #else
-      // Return path relative to app container root (tmp/ maps to NSTemporaryDirectory)
-      return Response(ok: true, data: DataPayload(message: "tmp/\(fileName)"))
+      return screenshotResponse(
+        image: XCUIScreen.main.screenshot().image,
+        inlineScreenshot: command.inlineScreenshot == true
+      )
 #endif
     case .back, .backInApp:
       if tapInAppBackControl(app: activeApp) {
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Keyboard.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Keyboard.swift
index de384d2ee6..a3fab3fad7 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Keyboard.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Keyboard.swift
@@ -212,6 +212,7 @@ extension RunnerTests {
     if tapKeyboardDismissControl(app: app) {
       _ = keyboard.waitForNonExistence(timeout: KeyboardDismissObservationTiming.timeout)
       waitForScreenshotStability(
+        app: app,
         timeout: KeyboardDismissObservationTiming.settleTimeout,
         sampleInterval: KeyboardDismissObservationTiming.settleSampleInterval,
         requiredConsecutiveMatches: KeyboardDismissObservationTiming.settleRequiredConsecutiveMatches
@@ -240,23 +241,38 @@ extension RunnerTests {
   // so far, so it is unit-testable without a real screenshot pipeline; this loop
   // is the thin, untestable I/O shell around it.
   private func waitForScreenshotStability(
+    app: XCUIApplication,
     timeout: TimeInterval,
     sampleInterval: TimeInterval,
     requiredConsecutiveMatches: Int
   ) {
     let deadline = Date().addingTimeInterval(timeout)
-    var samples: [Data?] = [screenshotFingerprintForStabilityCheck()]
+    var samples: [Data?] = [screenshotFingerprintForStabilityCheck(app: app)]
     while Date() < deadline {
       sleepFor(sampleInterval)
-      samples.append(screenshotFingerprintForStabilityCheck())
+      samples.append(screenshotFingerprintForStabilityCheck(app: app))
       if runnerScreenshotStabilitySettled(samples, requiredConsecutiveMatches: requiredConsecutiveMatches) {
+        logScreenshotStability(samples: samples, settled: true)
         return
       }
     }
+    logScreenshotStability(samples: samples, settled: false)
+  }
+
+  /// Says what the settle actually looked at: samples that are all `nil` means the capture refused to
+  /// produce a frame, which is a different fact from a screen that never held still, and the two read
+  /// identically from the outside (#2728).
+  private func logScreenshotStability(samples: [Data?], settled: Bool) {
+    NSLog(
+      "AGENT_DEVICE_RUNNER_KEYBOARD_STABILITY samples=%ld captured=%ld settled=%@",
+      samples.count,
+      samples.compactMap { $0 }.count,
+      settled ? "yes" : "no"
+    )
   }
 
-  private func screenshotFingerprintForStabilityCheck() -> Data? {
-    guard let image = captureRunnerFrame() else { return nil }
+  private func screenshotFingerprintForStabilityCheck(app: XCUIApplication) -> Data? {
+    guard let image = captureRunnerFrame(app: app) else { return nil }
     return runnerPngData(for: image)
   }
 
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Lifecycle.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Lifecycle.swift
index 34fe74d579..67c689cb1c 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Lifecycle.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Lifecycle.swift
@@ -42,7 +42,20 @@ enum RunnerInteractionIdleWaits {
 extension RunnerTests {
   // MARK: - Recording
 
-  func captureRunnerFrame() -> RunnerImage? {
+  /// One frame for the recording pump and the keyboard settle sample.
+  ///
+  /// On iOS the frame comes from the display owning a window, because a foldable's
+  /// `XCUIScreen.main` can be the dark outer panel while the app runs on the inner one — a stream of
+  /// identical black frames would then read as a settled screen and as a finished recording (#2728).
+  /// An observation with no session window falls to the system surface's window, which is what the
+  /// home screen is. macOS keeps recording the host display the way it always has.
+  func captureRunnerFrame(app: XCUIApplication) -> RunnerImage? {
+#if os(iOS)
+    guard case .success(let captured) = captureObservedScreen(app: app) else {
+      return nil
+    }
+    return captured.image
+#else
     var image: RunnerImage?
     let capture = {
       let screenshot = XCUIScreen.main.screenshot()
@@ -54,6 +67,7 @@ extension RunnerTests {
       DispatchQueue.main.sync(execute: capture)
     }
     return image
+#endif
   }
 
   func screenshotRoot(app: XCUIApplication) -> XCUIElement {
@@ -66,6 +80,54 @@ extension RunnerTests {
     return app
   }
 
+  /// Answers a `screenshot` command with one encoded image: inline when the caller asked for bytes,
+  /// otherwise as a path the host reads out of the runner's own container. `metadata` carries the
+  /// display the image came from whenever the capture resolved one, so the host never has to guess
+  /// the density of a panel it did not measure (#2728).
+  func screenshotResponse(
+    pngData: Data,
+    inlineScreenshot: Bool,
+    metadata: ScreenshotMetadataPayload? = nil
+  ) -> Response {
+    if inlineScreenshot {
+      return Response(
+        ok: true,
+        data: DataPayload(imageBase64: pngData.base64EncodedString(), screenshotMetadata: metadata)
+      )
+    }
+    let fileName = "screenshot-\(Int(Date().timeIntervalSince1970 * 1000)).png"
+    let filePath = (NSTemporaryDirectory() as NSString).appendingPathComponent(fileName)
+    do {
+      try pngData.write(to: URL(fileURLWithPath: filePath))
+    } catch {
+      return Response(
+        ok: false,
+        error: ErrorPayload(message: "Failed to write screenshot: \(error.localizedDescription)")
+      )
+    }
+#if os(macOS)
+    return Response(ok: true, data: DataPayload(message: filePath, screenshotMetadata: metadata))
+#else
+    // Return path relative to app container root (tmp/ maps to NSTemporaryDirectory)
+    return Response(
+      ok: true,
+      data: DataPayload(message: "tmp/\(fileName)", screenshotMetadata: metadata)
+    )
+#endif
+  }
+
+  /// Encodes a captured image as PNG and answers with it, or with the failure to encode it.
+  func screenshotResponse(
+    image: RunnerImage,
+    inlineScreenshot: Bool,
+    metadata: ScreenshotMetadataPayload? = nil
+  ) -> Response {
+    guard let pngData = runnerPngData(for: image) else {
+      return Response(ok: false, error: ErrorPayload(message: "Failed to encode screenshot as PNG"))
+    }
+    return screenshotResponse(pngData: pngData, inlineScreenshot: inlineScreenshot, metadata: metadata)
+  }
+
   func stopRecordingIfNeeded() {
     guard let recorder = activeRecording else { return }
     do {
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift
index 4e5c1974a7..81068ab004 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift
@@ -260,6 +260,16 @@ extension Response {
   }
 }
 
+/// The display one runner screenshot came from, as the capture measured it rather than as the host
+/// could guess. A runner capture can come from a different panel than the one the host resolved, so
+/// density normalization has to read the scale of the image that was actually taken (#2728).
+struct ScreenshotMetadataPayload: Codable {
+  let displayID: UInt
+  let pixelWidth: Int
+  let pixelHeight: Int
+  let pixelsPerPoint: Double
+}
+
 /// Foreground repair the runner performed while serving one command (#2682). `priorState` is the
 /// bound app's `XCApplicationState` raw value read BEFORE `XCUIApplication.activate()` ran, so the
 /// fact describes what was repaired rather than what the repair produced. `otherActiveApplicationPid`
@@ -330,6 +340,9 @@ struct DataPayload: Codable {
   var failedStepIndex: Int?
   var sequenceResults: [SequenceStepResult]?
   var targetActivation: TargetActivationFactPayload?
+  /// Present on a screenshot the runner captured from a display it resolved, alongside the
+  /// `message` path or `imageBase64` payload that carries the image itself (#2728).
+  var screenshotMetadata: ScreenshotMetadataPayload?
 }
 
 /// `kind` mirrors the TS `SnapshotKeyboardBandFact`: "visible" carries `frame`, "unmeasurable"
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Navigation.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Navigation.swift
index 7e4fcc3952..98b41d3bb5 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Navigation.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Navigation.swift
@@ -115,7 +115,7 @@ extension RunnerTests {
     guard let point = Self.topLeadingNavigationFallbackPoint(in: frame) else {
       return false
     }
-    let before = captureNavigationFallbackVisualState()
+    let before = captureNavigationFallbackVisualState(app: app)
     let context = synthesizedCoordinateContext(
       app: app,
       policy: synthesizedGesturePolicy(.coordinateTap)
@@ -124,33 +124,48 @@ extension RunnerTests {
       synthesizedTapAt(app: app, x: point.x, y: point.y, context: context)
     }
     if case .performed = synthesized.outcome {
-      return didNavigationFallbackChangeVisualState(before: before)
+      return didNavigationFallbackChangeVisualState(app: app, before: before)
     }
     let fallback = performGesture(app) {
       tapAt(app: app, x: point.x, y: point.y)
     }
     if case .performed = fallback.outcome {
-      return didNavigationFallbackChangeVisualState(before: before)
+      return didNavigationFallbackChangeVisualState(app: app, before: before)
     }
 #endif
     return false
   }
 
-  private func captureNavigationFallbackVisualState() -> Data? {
+  private func captureNavigationFallbackVisualState(app: XCUIApplication) -> Data? {
 #if os(iOS)
-    runnerPngData(for: XCUIScreen.main.screenshot().image)
+    // A visual check is optional evidence: a display that owns no window reports unknown by returning
+    // no sample, which the comparison below already reads as "nothing proved". It never reaches for
+    // a screen nobody is on, whose stable black would then be read as evidence that the tap did
+    // nothing (#2728).
+    guard case .success(let captured) = captureObservedScreen(app: app) else {
+      return nil
+    }
+    return runnerPngData(for: captured.image)
 #else
     return nil
 #endif
   }
 
-  private func didNavigationFallbackChangeVisualState(before: Data?) -> Bool {
+  private func didNavigationFallbackChangeVisualState(
+    app: XCUIApplication,
+    before: Data?
+  ) -> Bool {
     sleepFor(Self.navigationFallbackVerificationDelay)
-    let after = captureNavigationFallbackVisualState()
+    let after = captureNavigationFallbackVisualState(app: app)
     let changed = Self.didNavigationFallbackChangeVisualState(before: before, after: after)
-    if !changed {
-      NSLog("AGENT_DEVICE_RUNNER_IN_APP_BACK_FALLBACK_NO_STATE_CHANGE")
-    }
+    // The sample sizes are what tells a refused capture apart from an unchanged screen, and the
+    // fallback is rare enough that saying so every time costs nothing (#2728).
+    NSLog(
+      "AGENT_DEVICE_RUNNER_IN_APP_BACK_VISUAL_VERIFICATION beforeBytes=%ld afterBytes=%ld changed=%@",
+      before?.count ?? -1,
+      after?.count ?? -1,
+      changed ? "yes" : "no"
+    )
     return changed
   }
 
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerXCTestEventBridge.h b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerXCTestEventBridge.h
index bae0abb9c3..b346785f24 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerXCTestEventBridge.h
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerXCTestEventBridge.h
@@ -30,6 +30,16 @@ typedef void (*RunnerMsgSendSetInteger)(id, SEL, NSInteger);
 typedef void (*RunnerMsgSendAddPath)(id, SEL, id);
 typedef BOOL (*RunnerMsgSendSynthesize)(id, SEL, NSError **);
 
+// Why the display hosting the target app could not be named. Callers branch on this rather than
+// on the message, so a refusal keeps its reason across the language boundary (#2728).
+typedef NS_ENUM(NSUInteger, RunnerApplicationScreenFailure) {
+  RunnerApplicationScreenFailureNone,
+  // No window with a usable frame, so nothing resolves and its screen would only report main.
+  RunnerApplicationScreenFailureUnresolvedWindow,
+  // A resolved window whose screen or display identity the XCTest runtime would not answer.
+  RunnerApplicationScreenFailureUnresolvedScreen,
+};
+
 // Resolves the shared core described above against the live XCTest runtime.
 // Returns nil and populates `bridge` on success. Returns a non-nil
 // "private XCTest <surface> synthesis unavailable: ..." message and leaves
@@ -43,6 +53,22 @@ FOUNDATION_EXPORT NSString * _Nullable RunnerResolveXCTestEventBridge(
   RunnerXCTestEventBridge *bridge
 );
 
+// Resolves the `XCUIScreen` hosting the application's window and that screen's `displayID`, which
+// is the only display identity that follows a foldable app to whichever panel it currently lights.
+// Reading the window frame must precede reading its screen: an unresolved element still reports the
+// main screen. Never selects a screen by number or by position in `XCUIScreen.screens`.
+// Returns YES and writes the screen to capture into `screen` and its identity into `displayID`.
+// Otherwise returns NO, leaves both empty, and names the reason in `failure` so callers branch on
+// the reason rather than on message text (#2728). Private KVC raises rather than returns nil when
+// XCTest has no such value, so both reads are guarded here and surface as a typed failure instead
+// of an exception reaching the caller.
+FOUNDATION_EXPORT BOOL RunnerResolveApplicationScreen(
+  id application,
+  id _Nullable *screen,
+  NSUInteger *displayID,
+  RunnerApplicationScreenFailure *failure
+);
+
 // Reads the display ID off an already-resolved window. When a caller has resolved the app window
 // for geometry, routing the synthesized gesture by this window keeps the record's display and the
 // booked reference frame on the same window instead of re-walking `windows.firstMatch`.
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerXCTestEventBridge.m b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerXCTestEventBridge.m
index df4f403f95..169b79580e 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerXCTestEventBridge.m
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerXCTestEventBridge.m
@@ -1,4 +1,5 @@
 #import "RunnerXCTestEventBridge.h"
+#import "RunnerObjCExceptionCatcher.h"
 #import <CoreGraphics/CoreGraphics.h>
 #import <math.h>
 
@@ -90,20 +91,159 @@
   return [NSString stringWithFormat:@"%@: %@", name, reason];
 }
 
+static BOOL RunnerUsableWindowFrame(CGRect frame) {
+  if (CGRectIsEmpty(frame) || CGRectIsInfinite(frame) || CGRectIsNull(frame)) {
+    return NO;
+  }
+  return isfinite(frame.origin.x) && isfinite(frame.origin.y)
+    && isfinite(frame.size.width) && isfinite(frame.size.height);
+}
+
+static NSString *RunnerApplicationScreenFailureDescription(
+  RunnerApplicationScreenFailure failure
+) {
+  switch (failure) {
+    case RunnerApplicationScreenFailureUnresolvedWindow:
+      return @"no resolved application window";
+    case RunnerApplicationScreenFailureUnresolvedScreen:
+      return @"no resolved window display ID";
+    case RunnerApplicationScreenFailureNone:
+      return @"application screen resolved";
+  }
+}
+
+// One window read. XCTest answers with a value or raises. The window object is handed back because
+// resolving this instance is what its `screen` will answer from — re-querying `firstMatch` would
+// return an unresolved element that still names the main screen.
+//
+// Both answers are required. An app with no window answers `frame` with `(0,0 0x0)` without raising,
+// which geometry alone would read as a window the runtime has not measured, and only the query
+// itself says whether it has one. Measured on a live Duo: the runner host process, which has no
+// window, answers `exists` NO and `frame` `(0,0 0x0)` (#2728).
+//
+// The frame the read produced is reported even when it is refused: a capture that fails closed has
+// to say what it looked at, or the reason code cannot be told apart from a stale device.
+static RunnerApplicationScreenFailure RunnerResolveUsableWindow(
+  id application,
+  id _Nullable *window,
+  CGRect *observedFrame
+) {
+  __block id readWindow = nil;
+  __block CGRect frame = CGRectNull;
+  __block BOOL resolved = NO;
+  NSString *exception = [RunnerObjCExceptionCatcher catchException:^{
+    id candidate = [[application valueForKey:@"windows"] valueForKey:@"firstMatch"];
+    NSNumber *present = [candidate valueForKey:@"exists"];
+    resolved = [present isKindOfClass:NSNumber.class] && present.boolValue;
+    NSValue *frameValue = [candidate valueForKey:@"frame"];
+    [frameValue getValue:&frame size:sizeof(frame)];
+    readWindow = candidate;
+  }];
+  *observedFrame = frame;
+  if (exception != nil || !resolved || !RunnerUsableWindowFrame(frame)) {
+    NSLog(
+      @"AGENT_DEVICE_RUNNER_APP_SCREEN_UNRESOLVED stage=window frame=(%g,%g %gx%g) raised=%@ resolved=%@",
+      frame.origin.x,
+      frame.origin.y,
+      frame.size.width,
+      frame.size.height,
+      exception != nil ? @"yes" : @"no",
+      resolved ? @"yes" : @"no"
+    );
+    return RunnerApplicationScreenFailureUnresolvedWindow;
+  }
+  *window = readWindow;
+  return RunnerApplicationScreenFailureNone;
+}
+
+// The screen read that must follow window resolution on that same window instance. Before the
+// frame above is asked for, the window's `screen` can still name main, so this is never merged
+// into the read ahead of it.
+static RunnerApplicationScreenFailure RunnerReadResolvedWindowScreen(
+  id window,
+  CGRect windowFrame,
+  id _Nullable *screen,
+  NSUInteger *displayID
+) {
+  __block id readScreen = nil;
+  __block NSUInteger readDisplayID = 0;
+  NSString *exception = [RunnerObjCExceptionCatcher catchException:^{
+    id windowScreen = [window valueForKey:@"screen"];
+    NSNumber *identifier = [windowScreen valueForKey:@"displayID"];
+    if (![identifier isKindOfClass:NSNumber.class] || identifier.unsignedIntegerValue == 0) {
+      return;
+    }
+    readScreen = windowScreen;
+    readDisplayID = identifier.unsignedIntegerValue;
+  }];
+  if (exception != nil || readScreen == nil) {
+    NSLog(
+      @"AGENT_DEVICE_RUNNER_APP_SCREEN_UNRESOLVED stage=screen frame=(%g,%g %gx%g) raised=%@",
+      windowFrame.origin.x,
+      windowFrame.origin.y,
+      windowFrame.size.width,
+      windowFrame.size.height,
+      exception != nil ? @"yes" : @"no"
+    );
+    return RunnerApplicationScreenFailureUnresolvedScreen;
+  }
+  *screen = readScreen;
+  *displayID = readDisplayID;
+  return RunnerApplicationScreenFailureNone;
+}
+
+BOOL RunnerResolveApplicationScreen(
+  id application,
+  id _Nullable *screen,
+  NSUInteger *displayID,
+  RunnerApplicationScreenFailure *failure
+) {
+  *screen = nil;
+  *displayID = 0;
+  id window = nil;
+  CGRect windowFrame = CGRectNull;
+  *failure = RunnerResolveUsableWindow(application, &window, &windowFrame);
+  if (*failure != RunnerApplicationScreenFailureNone) {
+    return NO;
+  }
+  *failure = RunnerReadResolvedWindowScreen(window, windowFrame, screen, displayID);
+  return *failure == RunnerApplicationScreenFailureNone;
+}
+
+// Reads the display ID off a window the caller already resolved, so a synthesized record can be
+// routed by the same window its reference frame was measured on. The window still resolves here:
+// its frame is read before its screen, and a window that answers empty or raises fails closed with
+// the same reasons the application walk gives.
 NSString * _Nullable RunnerResolveWindowDisplayID(id window, NSUInteger *displayID) {
-  NSValue *frameValue = [window valueForKey:@"frame"];
-  CGRect frame = CGRectNull;
-  [frameValue getValue:&frame size:sizeof(frame)];
-  if (CGRectIsEmpty(frame) || CGRectIsInfinite(frame) || CGRectIsNull(frame)
-      || !isfinite(frame.origin.x) || !isfinite(frame.origin.y)
-      || !isfinite(frame.size.width) || !isfinite(frame.size.height)) {
-    return @"private XCTest event synthesis unavailable: no resolved application window";
+  __block CGRect frame = CGRectNull;
+  NSString *frameException = [RunnerObjCExceptionCatcher catchException:^{
+    NSValue *frameValue = [window valueForKey:@"frame"];
+    [frameValue getValue:&frame size:sizeof(frame)];
+  }];
+  if (frameException != nil || !RunnerUsableWindowFrame(frame)) {
+    NSLog(
+      @"AGENT_DEVICE_RUNNER_APP_SCREEN_UNRESOLVED stage=window frame=(%g,%g %gx%g) raised=%@",
+      frame.origin.x,
+      frame.origin.y,
+      frame.size.width,
+      frame.size.height,
+      frameException != nil ? @"yes" : @"no"
+    );
+    return [NSString stringWithFormat:
+      @"private XCTest event synthesis unavailable: %@",
+      RunnerApplicationScreenFailureDescription(RunnerApplicationScreenFailureUnresolvedWindow)
+    ];
   }
-  // The frame read resolves the window snapshot. Before resolution its screen can name main.
-  NSNumber *identifier = [[window valueForKey:@"screen"] valueForKey:@"displayID"];
-  if (![identifier isKindOfClass:NSNumber.class] || identifier.unsignedIntegerValue == 0) {
-    return @"private XCTest event synthesis unavailable: no resolved window display ID";
+  id screen = nil;
+  NSUInteger resolvedDisplayID = 0;
+  RunnerApplicationScreenFailure failure =
+    RunnerReadResolvedWindowScreen(window, frame, &screen, &resolvedDisplayID);
+  if (failure != RunnerApplicationScreenFailureNone) {
+    return [NSString stringWithFormat:
+      @"private XCTest event synthesis unavailable: %@",
+      RunnerApplicationScreenFailureDescription(failure)
+    ];
   }
-  *displayID = identifier.unsignedIntegerValue;
+  *displayID = resolvedDisplayID;
   return nil;
 }
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+AppScreenCaptureTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+AppScreenCaptureTests.swift
new file mode 100644
index 0000000000..6c9730d0f1
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+AppScreenCaptureTests.swift
@@ -0,0 +1,123 @@
+import XCTest
+
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS
+extension RunnerTests {
+  func testScreenCaptureFailureCarriesTheBridgeReasonAsItsOwnCode() {
+    XCTAssertEqual(
+      RunnerAppScreenCaptureFailure(.unresolvedWindow).rawValue,
+      "APP_SCREEN_WINDOW_UNRESOLVED"
+    )
+    XCTAssertEqual(
+      RunnerAppScreenCaptureFailure(.unresolvedScreen).rawValue,
+      "APP_SCREEN_UNRESOLVED"
+    )
+    // The display resolved and the image did not: a distinct code, because an operator chasing a
+    // panel problem is chasing the wrong thing here. This one has no bridge counterpart, so it is
+    // named on the Swift reason rather than mapped from one.
+    XCTAssertEqual(
+      RunnerAppScreenCaptureFailure.unrenderableImage.rawValue,
+      "APP_SCREEN_CAPTURE_UNRENDERABLE"
+    )
+    // A success-shaped reason cannot become a success: the only way here is a caller that forgot to
+    // branch, and the capture it describes did not happen.
+    XCTAssertEqual(
+      RunnerAppScreenCaptureFailure(RunnerApplicationScreenFailure.none).rawValue,
+      "APP_SCREEN_UNRESOLVED"
+    )
+  }
+
+  func testScreenshotResultEncodesDisplayFactsUnderTheKeyTheHostReads() throws {
+    // The measured open-Duo inner panel: 2852x2006 at scale 3 on display 3. The host reads these to
+    // rescale an image it did not measure, so the key and the shape are a cross-language contract.
+    let payload = DataPayload(
+      message: "tmp/screenshot-1.png",
+      screenshotMetadata: ScreenshotMetadataPayload(
+        displayID: 3,
+        pixelWidth: 2852,
+        pixelHeight: 2006,
+        pixelsPerPoint: 3
+      )
+    )
+    let encoded = try JSONSerialization.jsonObject(
+      with: JSONEncoder().encode(payload)
+    ) as? [String: Any]
+    XCTAssertEqual(encoded?["message"] as? String, "tmp/screenshot-1.png")
+    let metadata = encoded?["screenshotMetadata"] as? [String: Any]
+    XCTAssertEqual(metadata?["displayID"] as? UInt, 3)
+    XCTAssertEqual(metadata?["pixelWidth"] as? Int, 2852)
+    XCTAssertEqual(metadata?["pixelHeight"] as? Int, 2006)
+    XCTAssertEqual(metadata?["pixelsPerPoint"] as? Double, 3)
+  }
+
+  func testScreenshotResultCarriesNoDisplayFactsWhenNothingResolved() throws {
+    let encoded = try JSONSerialization.jsonObject(
+      with: JSONEncoder().encode(DataPayload(message: "tmp/screenshot-1.png"))
+    ) as? [String: Any]
+    XCTAssertNil(encoded?["screenshotMetadata"])
+  }
+}
+#endif
+
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS && os(iOS)
+  extension RunnerTests {
+    /// The no-session-app and not-running-app cases both reach the resolver as an unresolved window,
+    /// and the capture is still owed a display: the home screen owns one (#2728).
+    func testObservedScreenCaptureAsksTheSystemSurfaceWhenTheSessionWindowIsUnresolved() {
+      var askedSystemSurface = false
+      let outcome = selectObservedScreenCapture(
+        resolving: { .failure(.unresolvedWindow) },
+        fallingBack: {
+          askedSystemSurface = true
+          return .failure(.unrenderableImage)
+        }
+      )
+      XCTAssertTrue(askedSystemSurface, "an unresolved window has to move the question on")
+      guard case .failure(let systemAnswer) = outcome else {
+        return XCTFail("the system surface refused, so a refusal is what the caller must get")
+      }
+      XCTAssertEqual(
+        systemAnswer.rawValue,
+        "APP_SCREEN_CAPTURE_UNRENDERABLE",
+        "the system surface's answer is the answer, not the session app's"
+      )
+    }
+
+    /// A window that resolved and then refused to name its display is the failure the host has to
+    /// see; asking a second process would replace a real refusal with an unrelated capture.
+    func testObservedScreenCaptureReportsADisplayRefusalWithoutAskingTheSystemSurface() {
+      var askedSystemSurface = false
+      let outcome = selectObservedScreenCapture(
+        resolving: { .failure(.unresolvedScreen) },
+        fallingBack: {
+          askedSystemSurface = true
+          return .failure(.unrenderableImage)
+        }
+      )
+      XCTAssertFalse(askedSystemSurface, "only an unresolved window may reach the system surface")
+      guard case .failure(let refusal) = outcome else {
+        return XCTFail("a display that refused must not become a capture")
+      }
+      XCTAssertEqual(refusal.rawValue, "APP_SCREEN_UNRESOLVED")
+    }
+
+    func testObservedScreenCaptureKeepsTheSessionAppCaptureItResolved() {
+      var askedSystemSurface = false
+      let captured = CapturedAppScreen(
+        image: UIImage(),
+        displayID: 3,
+        pixelWidth: 2852,
+        pixelHeight: 2006,
+        pixelsPerPoint: 3
+      )
+      let outcome = selectObservedScreenCapture(
+        resolving: { .success(captured) },
+        fallingBack: {
+          askedSystemSurface = true
+          return .failure(.unresolvedWindow)
+        }
+      )
+      XCTAssertFalse(askedSystemSurface, "a resolved app is never second-guessed")
+      XCTAssertEqual(try? outcome.get().displayID, 3)
+    }
+  }
+#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+LifecycleTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+LifecycleTests.swift
index 281e6ad43d..c9c14b436d 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+LifecycleTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+LifecycleTests.swift
@@ -27,5 +27,49 @@ extension RunnerTests {
       XCTAssertEqual(isReadOnlyCommand(fixture.command), fixture.readOnly, fixture.name)
     }
   }
+
+  func testInlineScreenshotResponseKeepsDisplayFactsBesideTheImage() throws {
+    let pngData = Data([0x89, 0x50, 0x4E, 0x47])
+    let response = screenshotResponse(
+      pngData: pngData,
+      inlineScreenshot: true,
+      metadata: ScreenshotMetadataPayload(
+        displayID: 3,
+        pixelWidth: 2852,
+        pixelHeight: 2006,
+        pixelsPerPoint: 3
+      )
+    )
+    XCTAssertTrue(response.ok)
+    XCTAssertEqual(response.data?.imageBase64, pngData.base64EncodedString())
+    XCTAssertEqual(response.data?.screenshotMetadata?.displayID, 3)
+    XCTAssertNil(response.data?.message, "an inline answer must not also name a file")
+  }
+
+  func testFileScreenshotResponseWritesTheImageAndStillReportsItsDisplay() throws {
+    let pngData = Data([0x89, 0x50, 0x4E, 0x47])
+    let response = screenshotResponse(
+      pngData: pngData,
+      inlineScreenshot: false,
+      metadata: ScreenshotMetadataPayload(
+        displayID: 1,
+        pixelWidth: 1398,
+        pixelHeight: 2034,
+        pixelsPerPoint: 3
+      )
+    )
+    XCTAssertTrue(response.ok)
+    XCTAssertNil(response.data?.imageBase64, "a file answer must not also carry bytes")
+    let message = try XCTUnwrap(response.data?.message)
+    // The answer names the file rather than carrying bytes, and the name is a host-resolvable form:
+    // absolute on macOS, container-relative `tmp/…` on iOS. Both name the one file just written
+    // into the runner's temporary directory.
+    let fileName = URL(fileURLWithPath: message).lastPathComponent
+    XCTAssertTrue(message.hasSuffix(fileName), message)
+    let storedPath = (NSTemporaryDirectory() as NSString).appendingPathComponent(fileName)
+    XCTAssertEqual(try Data(contentsOf: URL(fileURLWithPath: storedPath)), pngData)
+    XCTAssertEqual(response.data?.screenshotMetadata?.pixelsPerPoint, 3)
+    try? FileManager.default.removeItem(atPath: storedPath)
+  }
 }
 #endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+XCTestEventBridgeTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+XCTestEventBridgeTests.swift
index 9dec8afe2d..22350597db 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+XCTestEventBridgeTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+XCTestEventBridgeTests.swift
@@ -6,21 +6,57 @@ private final class DisplayScreenFixture: NSObject {
   init(_ displayID: UInt) { self.displayID = displayID }
 }
 
-/// A window that only reports the display it was built with once its frame has been read, which is
-/// when XCTest resolves the snapshot. Before that read, `screen` still names main.
+/// A window the runtime answers only once its query has resolved. `frame` is the read that
+/// resolves it: while the query is unresolved `screen` names main, which is what a fresh runner
+/// process that has not queried this app yet reports (#2728).
 private final class DisplayWindowFixture: NSObject {
-  let windowFrame: CGRect
-  let resolvedDisplayID: UInt
-  var resolved = false
-  init(frame: CGRect, displayID: UInt) {
+  private let windowFrame: CGRect
+  private let resolvedDisplayID: UInt
+  private let present: Bool
+  private(set) var resolved = false
+  private lazy var windowScreen = DisplayScreenFixture(resolvedDisplayID)
+  init(frame: CGRect, displayID: UInt, present: Bool = true) {
     self.windowFrame = frame
     self.resolvedDisplayID = displayID
+    self.present = present
   }
+  @objc var exists: Bool { present }
   @objc var frame: CGRect {
     resolved = true
     return windowFrame
   }
-  @objc var screen: NSObject { DisplayScreenFixture(resolved ? resolvedDisplayID : 1) }
+  // Handed back as one object so a test can prove the resolver captures the screen the window
+  // reported rather than a fresh value for the same key. Unresolved, it names main.
+  @objc var screen: NSObject { resolved ? windowScreen : DisplayScreenFixture(1) }
+}
+
+private final class DisplayWindowsFixture: NSObject {
+  @objc let firstMatch: NSObject
+  init(_ window: NSObject) { firstMatch = window }
+}
+
+private final class DisplayApplicationFixture: NSObject {
+  @objc let windows: NSObject
+  convenience init(_ window: NSObject) {
+    self.init(windows: DisplayWindowsFixture(window))
+  }
+  init(windows: NSObject) { self.windows = windows }
+}
+
+/// A `windows` query the runtime refuses to answer. KVC raises on a key an object does not expose
+/// rather than returning nil, which is exactly how a private XCTest read fails when it renames.
+private final class UnanswerableWindowsFixture: NSObject {}
+
+/// A window whose frame resolves but whose screen key the runtime would not answer.
+private final class ScreenlessWindowFixture: NSObject {
+  @objc let exists: Bool = true
+  @objc var frame: CGRect { CGRect(x: 0, y: 0, width: 951, height: 669) }
+}
+
+/// A window whose frame key the runtime would not answer. The gesture path holds this object across
+/// a command boundary, so a frame read that raises must fail closed inside the resolver.
+private final class FramelessWindowFixture: NSObject {
+  @objc let exists: Bool = true
 }
 
 extension RunnerTests {
@@ -29,7 +65,7 @@ extension RunnerTests {
     var displayID: UInt = 0
     XCTAssertNil(RunnerResolveWindowDisplayID(window, &displayID))
     XCTAssertEqual(displayID, 3)
-    XCTAssertTrue(window.resolved)
+    XCTAssertTrue(window.resolved, "the window path must resolve the frame before reading its screen")
   }
 
   func testSynthesizedDisplayPreservesPrimaryWindowIdentity() {
@@ -39,13 +75,6 @@ extension RunnerTests {
     XCTAssertEqual(displayID, 1)
   }
 
-  func testSynthesizedDisplayRefusesDisplaylessWindow() {
-    let window = DisplayWindowFixture(frame: CGRect(x: 0, y: 0, width: 951, height: 669), displayID: 0)
-    var displayID: UInt = 99
-    XCTAssertNotNil(RunnerResolveWindowDisplayID(window, &displayID))
-    XCTAssertEqual(displayID, 99)
-  }
-
   func testSynthesizedDisplayRefusesWindowWithoutQualifyingFrame() {
     for frame in [CGRect.zero, .null, .infinite] {
       let window = DisplayWindowFixture(frame: frame, displayID: 3)
@@ -55,6 +84,32 @@ extension RunnerTests {
     }
   }
 
+  func testSynthesizedDisplayRefusesWindowWithNoDisplayIDOrNoScreenAnswer() {
+    let noDisplayWindow = DisplayWindowFixture(frame: CGRect(x: 0, y: 0, width: 951, height: 669), displayID: 0)
+    let screenlessWindow = ScreenlessWindowFixture()
+    for window in [noDisplayWindow, screenlessWindow] as [NSObject] {
+      var displayID: UInt = 99
+      let error = RunnerResolveWindowDisplayID(window, &displayID)
+      XCTAssertNotNil(error)
+      XCTAssertTrue(
+        error?.contains("no resolved window display ID") ?? false,
+        "expected the typed screen refusal, got \(error ?? "nil")"
+      )
+      XCTAssertEqual(displayID, 99)
+    }
+  }
+
+  func testSynthesizedDisplayRefusesAWindowWhoseFrameLookupRaises() {
+    var displayID: UInt = 99
+    let reason = RunnerResolveWindowDisplayID(FramelessWindowFixture(), &displayID)
+    XCTAssertNotNil(reason, "a frame read that raises must be caught, not handed to the gesture path")
+    XCTAssertTrue(
+      reason?.contains("no resolved application window") ?? false,
+      "expected the typed window refusal, got \(reason ?? "nil")"
+    )
+    XCTAssertEqual(displayID, 99)
+  }
+
   func testFirstUsableWindowSkipsAbsentAndEmptyWindows() {
     let lit = CGRect(x: 0, y: 0, width: 402, height: 874)
     XCTAssertEqual(RunnerTests.firstUsableWindowIndex(frames: [lit]), 0)
@@ -62,5 +117,99 @@ extension RunnerTests {
     XCTAssertNil(RunnerTests.firstUsableWindowIndex(frames: [nil, .zero, nil]))
     XCTAssertNil(RunnerTests.firstUsableWindowIndex(frames: []))
   }
+
+  func testResolvedScreenHandsBackTheScreenTheResolvedWindowReported() {
+    let window = DisplayWindowFixture(frame: CGRect(x: 0, y: 0, width: 951, height: 669), displayID: 3)
+    var screen: AnyObject?
+    var displayID: UInt = 0
+    var failure = RunnerApplicationScreenFailure.unresolvedScreen
+    XCTAssertTrue(
+      RunnerResolveApplicationScreen(DisplayApplicationFixture(window), &screen, &displayID, &failure)
+    )
+    XCTAssertEqual(displayID, 3)
+    XCTAssertTrue(window.resolved, "the window's screen only answers once its query resolved")
+    XCTAssertTrue(
+      screen === window.screen,
+      "the capture must go to the screen object this window reported, not a re-queried one"
+    )
+  }
+
+  func testResolvedScreenRefusesAWindowLookupThatRaises() {
+    var screen: AnyObject? = NSObject()
+    var displayID: UInt = 99
+    var failure = RunnerApplicationScreenFailure.none
+    XCTAssertFalse(
+      RunnerResolveApplicationScreen(
+        DisplayApplicationFixture(windows: UnanswerableWindowsFixture()),
+        &screen,
+        &displayID,
+        &failure
+      )
+    )
+    XCTAssertEqual(failure, .unresolvedWindow)
+    XCTAssertNil(screen)
+    XCTAssertEqual(displayID, 0)
+  }
+
+  func testResolvedScreenRefusesAResolvedWindowWithNoAnswerableScreen() {
+    var screen: AnyObject? = NSObject()
+    var displayID: UInt = 99
+    var failure = RunnerApplicationScreenFailure.none
+    XCTAssertFalse(
+      RunnerResolveApplicationScreen(
+        DisplayApplicationFixture(ScreenlessWindowFixture()),
+        &screen,
+        &displayID,
+        &failure
+      )
+    )
+    XCTAssertEqual(failure, .unresolvedScreen)
+    XCTAssertNil(screen)
+    XCTAssertEqual(displayID, 0)
+  }
+
+  func testResolvedScreenRefusesAWindowReportingNoDisplayID() {
+    let window = DisplayWindowFixture(frame: CGRect(x: 0, y: 0, width: 466, height: 678), displayID: 0)
+    var screen: AnyObject? = NSObject()
+    var displayID: UInt = 99
+    var failure = RunnerApplicationScreenFailure.none
+    XCTAssertFalse(
+      RunnerResolveApplicationScreen(DisplayApplicationFixture(window), &screen, &displayID, &failure)
+    )
+    XCTAssertEqual(failure, .unresolvedScreen)
+    XCTAssertNil(screen)
+    XCTAssertEqual(displayID, 0)
+  }
+
+  func testResolvedScreenRefusesAnEmptyWindowFrameWithoutNamingAnyDisplay() {
+    let window = DisplayWindowFixture(frame: .zero, displayID: 3)
+    var screen: AnyObject? = NSObject()
+    var displayID: UInt = 99
+    var failure = RunnerApplicationScreenFailure.none
+    XCTAssertFalse(
+      RunnerResolveApplicationScreen(DisplayApplicationFixture(window), &screen, &displayID, &failure)
+    )
+    XCTAssertEqual(failure, .unresolvedWindow)
+    XCTAssertNil(screen, "a dark panel must never become the capture target by default")
+  }
+
+  /// A cold query answers `frame` with a usable rect on some runtimes while its `exists` says the
+  /// window is not there. Geometry alone must not be trusted into capturing a panel nobody resolved.
+  func testResolvedScreenRefusesAWindowTheQuerySaysIsNotThere() {
+    let window = DisplayWindowFixture(
+      frame: CGRect(x: 0, y: 0, width: 951, height: 669),
+      displayID: 3,
+      present: false
+    )
+    var screen: AnyObject? = NSObject()
+    var displayID: UInt = 99
+    var failure = RunnerApplicationScreenFailure.none
+    XCTAssertFalse(
+      RunnerResolveApplicationScreen(DisplayApplicationFixture(window), &screen, &displayID, &failure)
+    )
+    XCTAssertEqual(failure, .unresolvedWindow)
+    XCTAssertNil(screen)
+    XCTAssertEqual(displayID, 0)
+  }
 }
 #endif
diff --git a/docs/adr/0025-foldable-apple-panels.md b/docs/adr/0025-foldable-apple-panels.md
index 505a595f44..cdde3e4f93 100644
--- a/docs/adr/0025-foldable-apple-panels.md
+++ b/docs/adr/0025-foldable-apple-panels.md
@@ -19,7 +19,7 @@ device is in**. The first is answered by an official host API; the second only b
 | Device has more than one integrated panel | Pass `--display=<panel name>` on every `simctl io screenshot`; never rely on the implicit default |
 | Panel power is ambiguous (zero or several lit panels) | Still name a panel — the `primary` one — emit `apple_display_capture_ambiguous`, and report the pose as `unknown` |
 | Device has one integrated panel | Keep the pre-panel behavior exactly: no display flag, no pose, unchanged scale probe |
-| Density normalization | Use the captured panel's own `pointScale`; a runner-fallback capture keeps the scale probe because `XCUIScreen.main` names the outer panel even while the inner one is lit, which the Runner capture migration below would retire |
+| Density normalization | Use the captured panel's own `pointScale`; a runner-fallback capture uses the pixels-per-point that capture reported about itself |
 | Pose must be reported | From panel power alone, report `closed`, `fully-open`, or `unknown`, and never narrower; `fold` reports the exact pose because it reads the hinge angle |
 | A pose change is requested | `agent-device fold <closed\|half-open\|open>`: press the pose control in the Device Hub window through macOS accessibility, then read the hinge angle back from CoreDevice until it agrees — for `half-open`, until two consecutive readings agree; refuse the pose if it never does |
 | The hinge reaches `half-open` but keeps moving | Refuse it as `fold-pose-unsettled` with the observed and previous angles: an angle inside the open interval is an observed category, not a pose the hinge holds |
@@ -87,6 +87,45 @@ fix, and no screen-selection flag is warranted.
 `SIMULATOR_MAINSCREEN_SCALE` is likewise fixed to one panel while the captured panel can be the
 other, so density normalization now takes `pointScale` from the panel that was captured.
 
+### Runner capture follows the app's window (#2728)
+
+Naming the lit panel only helps a capture that asks CoreDevice. The runner captured
+`XCUIScreen.main`, one fixed panel, so a capture reached through the runner — the fallback when
+`simctl` fails, and every visual verification inside the runner — followed a panel chosen at build
+time instead of the app. The runner now resolves the app window first, reads the display off that
+same window instance, and encodes the capture upright, because the image handed back for a panel
+the system presents turned has its buffer sideways.
+
+The capture reports the display ID it used, the pixel size it encoded, and the pixels-per-point of
+that image, so density normalization reads the source it captured instead of applying a scale the
+host inferred. A runner that reports nothing measured nothing, and normalization keeps the pre-panel
+answer rather than borrowing a scale from a panel nobody captured.
+
+A capture asks the target app's window first and the system surface's window second. The home screen
+is SpringBoard's window, so a capture with no session app — or with one that is not running — still
+has a display that owns a window, and asking for it keeps the foldable rule intact: the answer is
+always a display a window actually occupies, never `XCUIScreen.main`, which on a Duo is the dark
+panel whenever the app is inside. A capture fails closed with a typed reason only when neither
+resolves a window. An app with no window is refused on the query's own `exists` answer as well as on
+its frame: a windowless app answers `frame` with `(0,0 0x0)` without raising, so geometry alone
+cannot say "no window".
+
+Both answers are measured rather than assumed. A session with no app, and one whose app was terminated while still bound, answer the window query with `resolved=no`, and the capture that follows names the lit panel — on an unfolded Duo that is `LCD-1`, and the resulting home-screen image contains no black pixel. An app suspended by `home` keeps answering with a usable window, so it takes the first branch and still captures the panel it is on.
+
+`screenshot` is a runner-lifecycle command and skips the app-activation preflight, which left its
+app as the runner host process on a fresh runner — a process with no window at all. It resolves the
+requested bundle id for observation instead, and never activates an app to learn what it is
+foregrounded on. Measured on a live Duo through the runner route, one command with unchanged flags:
+
+| Pose | Lit panel | Capture | Mean luma |
+| --- | --- | --- | --- |
+| Open (hinge 180°) | `LCD-1` (ID 3) | 951x669 @1x | 214 |
+| Half-open (hinge 130°) | `LCD-1` (ID 3) | 951x669 @1x | 214 |
+| Closed (hinge 0°) | `LCD` (ID 1) | 466x678 @1x | 177 |
+
+The closed row is the point: the same command followed the app onto the other panel without being
+told, and every row is real content where a main-screen capture of the unlit panel is black.
+
 ## Pose control: Device Hub's control, CoreDevice's verdict
 
 `agent-device fold` sets the pose, and the split above still holds: the press is not evidence,
@@ -369,27 +408,20 @@ incorrect viewport, not an inner-panel delivery prohibition.
 
 ## Accepted evidence gaps
 
-- **Runner capture migration.** `XCUIScreen.main` is six call expressions in four files, and the
-  iOS-reachable ones capture a dark panel once an unfolded Duo moves the app to the inner one: the
-  `screenshot` command's non-macOS branch in `RunnerTests+CommandExecution.swift`; its two `#if
-  os(macOS)` siblings are `XCUIScreen.main` captures too and only the branch between them captures
-  the app's own root, so the desktop's behavior stays unmeasured here and the desktop also reaches
-  the screen through Screen Capture Kit in `AgentDeviceMacOSHelper`. Then `captureRunnerFrame` in
-  `RunnerTests+Lifecycle.swift`, which feeds both the recorder and the keyboard stability
-  fingerprint in `RunnerTests+Keyboard.swift`; the in-app-back visual-state probe in
-  `RunnerTests+Navigation.swift`; and the synthesized-gesture reference frame in
-  `RunnerTests+Interaction.swift`, which only the unmerged #2724 replaces. All of them call the
-  expression the measurement above ran, so they follow by construction and not by measurement, and
-  two fail less visibly than a black screenshot: identical black samples satisfy
-  `runnerScreenshotStabilitySettled` on its first interval whatever the keyboard is doing, and an
-  unchanged black pair logs `AGENT_DEVICE_RUNNER_IN_APP_BACK_FALLBACK_NO_STATE_CHANGE` and reports
-  a back navigation that worked as one that failed. Host-side, `screenshot.ts` passes no scale
-  precisely because the runner captures `XCUIScreen.main`, `display-inventory.test.ts` asserts
-  that, and `commands.md` tells users the physical capture is built from
-  `XCUIScreen.main.screenshot()` frames, so all three move with the runner; #2727's comment carries
-  the line-numbered inventory. CoreDevice still names the panel, since `XCUIScreen` has no
-  panel-power fact to trade on. Physical devices compile the same source and no physical foldable
-  was measured, so that path stays unverified. - **Quarter-turn detection.** Both Duo panels report
+- **Runner capture on a physical foldable.** The runner resolves the app's own display and was
+  verified across the open, half-open, and closed poses on a simulated Duo, but the same route on a
+  physical foldable was never exercised.
+- **Runner observation paths that sample a frame.** Keyboard settling, screen recording, and the
+  navigation fallback now take their frame from the display owning a window and each states in
+  `runner.log` what it looked at, but none was watched on a device that changes panel under it. A
+  pose change mid-recording still changes the captured display under a writer sized from the first
+  frame, and that mismatch was never exercised.
+- **Desktop capture paths.** The two `#if os(macOS)` siblings of the `screenshot` capture in
+  `RunnerTests+CommandExecution.swift` keep capturing the desktop screen, which also reaches the
+  screen through Screen Capture Kit in `AgentDeviceMacOSHelper`; only the iOS branches changed
+  target, and the desktop behavior stays unmeasured here.
+
+- **Quarter-turn detection.** Both Duo panels report
   `currentOrientation: rot90`, and no available path rotates a foldable, so the orientation half of
   the inventory is carried but never exercised against a changed value. - **Pose control on a
   second Device Hub instance.** Discovery checks every matching process, but simultaneous Xcodes
diff --git a/packages/platform-apple/src/core/__tests__/display-inventory.test.ts b/packages/platform-apple/src/core/__tests__/display-inventory.test.ts
index 78c5aff6aa..479f404cb6 100644
--- a/packages/platform-apple/src/core/__tests__/display-inventory.test.ts
+++ b/packages/platform-apple/src/core/__tests__/display-inventory.test.ts
@@ -440,32 +440,80 @@ describe('captureSimulatorScreenshotWithRetry display targeting', () => {
 });
 
 describe('captureSimulatorScreenshotWithFallback runner fallback', () => {
-  test('never rescales a runner capture with the resolved panel point scale', async () => {
-    const densityScales: (AppleDeviceDisplay | undefined)[] = [];
-    let runnerCaptures = 0;
+  test('rescales a runner capture with the scale that capture reported, not the resolved panel', async () => {
+    const sourceScales: (number | undefined)[] = [];
+    // A panel whose `pointScale` deliberately disagrees with the runner's report, so the assertion
+    // can tell the two sources apart rather than passing on a coincidence.
+    const litPanel = displayWith({ pointScale: 2 });
     await captureSimulatorScreenshotWithFallback(IOS_TEST_SIMULATOR, '/tmp/duo.png', {
       skipIosSimulatorBootCheck: true,
       pixelDensity: 2,
       deps: {
         ensureBooted: async () => {},
-        resolveCaptureDisplay: async () => outerPanel,
+        resolveCaptureDisplay: async () => litPanel,
         captureWithRetry: async () => {
           throw new Error('simctl screenshot failed');
         },
-        normalizeDensity: async (_device, _path, _density, display) => {
-          densityScales.push(display);
+        normalizeDensity: async (_device, _path, _density, sourcePixelDensity) => {
+          sourceScales.push(sourcePixelDensity);
         },
-        captureWithRunner: async () => {
-          runnerCaptures += 1;
+        captureWithRunner: async () => ({
+          displayID: 3,
+          pixelWidth: 2852,
+          pixelHeight: 2006,
+          pixelsPerPoint: 3,
+        }),
+        shouldFallbackToRunner: () => true,
+      },
+    });
+    assert.deepEqual(
+      sourceScales,
+      [3],
+      'the runner captured the panel hosting the app and reported that capture at scale 3',
+    );
+  });
+
+  test('keeps the source unmeasured when a runner reports no display facts', async () => {
+    const sourceScales: (number | undefined)[] = [];
+    await captureSimulatorScreenshotWithFallback(IOS_TEST_SIMULATOR, '/tmp/duo.png', {
+      skipIosSimulatorBootCheck: true,
+      pixelDensity: 2,
+      deps: {
+        ensureBooted: async () => {},
+        resolveCaptureDisplay: async () => outerPanel,
+        captureWithRetry: async () => {
+          throw new Error('simctl screenshot failed');
+        },
+        normalizeDensity: async (_device, _path, _density, sourcePixelDensity) => {
+          sourceScales.push(sourcePixelDensity);
         },
+        captureWithRunner: async () => undefined,
         shouldFallbackToRunner: () => true,
       },
     });
-    assert.equal(runnerCaptures, 1);
     assert.deepEqual(
-      densityScales,
+      sourceScales,
       [undefined],
-      'the runner captures XCUIScreen.main, so no resolved panel scale may be applied',
+      'a runner that measured nothing leaves the source unmeasured rather than borrowing the resolved panel scale',
     );
   });
+
+  test('names the resolved panel as the source for a simctl capture', async () => {
+    const sourceScales: (number | undefined)[] = [];
+    await captureSimulatorScreenshotWithFallback(IOS_TEST_SIMULATOR, '/tmp/duo.png', {
+      skipIosSimulatorBootCheck: true,
+      pixelDensity: 2,
+      deps: {
+        ensureBooted: async () => {},
+        resolveCaptureDisplay: async () => outerPanel,
+        captureWithRetry: async () => {},
+        normalizeDensity: async (_device, _path, _density, sourcePixelDensity) => {
+          sourceScales.push(sourcePixelDensity);
+        },
+        captureWithRunner: async () => undefined,
+        shouldFallbackToRunner: () => true,
+      },
+    });
+    assert.deepEqual(sourceScales, [outerPanel.pointScale]);
+  });
 });
diff --git a/packages/platform-apple/src/core/__tests__/screenshot.test.ts b/packages/platform-apple/src/core/__tests__/screenshot.test.ts
index d232bdd96c..971e2cc881 100644
--- a/packages/platform-apple/src/core/__tests__/screenshot.test.ts
+++ b/packages/platform-apple/src/core/__tests__/screenshot.test.ts
@@ -49,6 +49,7 @@ import {
   captureSimulatorScreenshotWithFallback,
   captureSimulatorScreenshotWithRetry,
   captureScreenshotViaRunner,
+  readRunnerScreenCaptureMetadata,
   resolveSimulatorRunnerScreenshotCandidatePaths,
   shouldRetryIosSimulatorScreenshot,
 } from '../screenshot.ts';
@@ -257,7 +258,7 @@ test('captureSimulatorScreenshotWithFallback boots skipped-check simulator after
       });
     }
   });
-  const captureWithRunner = vi.fn(async () => {});
+  const captureWithRunner = vi.fn(async () => undefined);
 
   await captureSimulatorScreenshotWithFallback(IOS_TEST_SIMULATOR, '/tmp/out.png', {
     appBundleId: 'com.example.app',
@@ -295,7 +296,7 @@ test('captureSimulatorScreenshotWithFallback keeps runner fallback after skipped
       timeoutMs: 20_000,
     });
   });
-  const captureWithRunner = vi.fn(async () => {});
+  const captureWithRunner = vi.fn(async () => undefined);
 
   await captureSimulatorScreenshotWithFallback(IOS_TEST_SIMULATOR, '/tmp/out.png', {
     appBundleId: 'com.example.app',
@@ -495,6 +496,62 @@ test('captureScreenshotViaRunner reuses a verified simulator container path', as
   }
 });
 
+test('captureScreenshotViaRunner reports the display facts a runner capture measured', async () => {
+  const tmpDir = await mkdtempForTest('agent-device-runner-metadata-');
+  const containerPath = path.join(tmpDir, 'container');
+  const runnerImage = path.join(containerPath, 'tmp', 'duo.png');
+  const device = { ...IOS_TEST_SIMULATOR, id: 'sim-runner-metadata' };
+  await fs.mkdir(path.dirname(runnerImage), { recursive: true });
+  await fs.writeFile(runnerImage, 'runner-image', 'utf8');
+  mockRunAppleRunnerCommand.mockResolvedValue({
+    message: 'tmp/duo.png',
+    screenshotMetadata: { displayID: 3, pixelWidth: 2852, pixelHeight: 2006, pixelsPerPoint: 3 },
+  });
+  mockRunCmd.mockImplementation(async (_cmd, args) => {
+    if (args.includes('get_app_container')) {
+      return { exitCode: 0, stdout: `${containerPath}\n`, stderr: '' };
+    }
+    throw new Error(`Unexpected xcrun args: ${args.join(' ')}`);
+  });
+
+  try {
+    const outPath = path.join(tmpDir, 'out.png');
+    const metadata = await captureScreenshotViaRunner(device, outPath);
+    assert.deepEqual(metadata, {
+      displayID: 3,
+      pixelWidth: 2852,
+      pixelHeight: 2006,
+      pixelsPerPoint: 3,
+    });
+    assert.equal(await fs.readFile(outPath, 'utf8'), 'runner-image');
+  } finally {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  }
+});
+
+test('captureScreenshotViaRunner reports no display facts for a pre-panel runner', async () => {
+  const tmpDir = await mkdtempForTest('agent-device-runner-no-metadata-');
+  const containerPath = path.join(tmpDir, 'container');
+  const runnerImage = path.join(containerPath, 'tmp', 'legacy.png');
+  const device = { ...IOS_TEST_SIMULATOR, id: 'sim-runner-no-metadata' };
+  await fs.mkdir(path.dirname(runnerImage), { recursive: true });
+  await fs.writeFile(runnerImage, 'runner-image', 'utf8');
+  mockRunAppleRunnerCommand.mockResolvedValue({ message: 'tmp/legacy.png' });
+  mockRunCmd.mockImplementation(async (_cmd, args) => {
+    if (args.includes('get_app_container')) {
+      return { exitCode: 0, stdout: `${containerPath}\n`, stderr: '' };
+    }
+    throw new Error(`Unexpected xcrun args: ${args.join(' ')}`);
+  });
+
+  try {
+    const outPath = path.join(tmpDir, 'out.png');
+    assert.equal(await captureScreenshotViaRunner(device, outPath), undefined);
+  } finally {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  }
+});
+
 test('captureScreenshotViaRunner copies macOS runner screenshots from the host', async () => {
   const tmpDir = await mkdtempForTest('agent-device-macos-screenshot-');
   const sourcePath = path.join(tmpDir, 'runner.png');
@@ -511,3 +568,52 @@ test('captureScreenshotViaRunner copies macOS runner screenshots from the host',
     await fs.rm(tmpDir, { recursive: true, force: true });
   }
 });
+
+// The open-Duo row of the #2727 measurement: a resolved inner panel reports 2852x2006 at scale 3,
+// one pixel per axis smaller than the size CoreDevice calls the panel.
+const OPEN_DUO_CAPTURE = {
+  displayID: 3,
+  pixelWidth: 2852,
+  pixelHeight: 2006,
+  pixelsPerPoint: 3,
+};
+
+// The wire key is spelled as a literal because the Swift encoder, not this module, owns it (#2728).
+function runnerCapturePayload(metadata: unknown): Record<string, unknown> {
+  return { message: 'tmp/screenshot-1.png', screenshotMetadata: metadata };
+}
+
+test('reads the display facts a resolved runner capture reported', () => {
+  assert.deepEqual(
+    readRunnerScreenCaptureMetadata(runnerCapturePayload(OPEN_DUO_CAPTURE)),
+    OPEN_DUO_CAPTURE,
+  );
+  assert.deepEqual(
+    readRunnerScreenCaptureMetadata(
+      runnerCapturePayload({
+        displayID: 1,
+        pixelWidth: 1398,
+        pixelHeight: 2034,
+        pixelsPerPoint: 3,
+      }),
+    ),
+    { displayID: 1, pixelWidth: 1398, pixelHeight: 2034, pixelsPerPoint: 3 },
+  );
+});
+
+test('reports no source fact when the runner carried no metadata', () => {
+  assert.equal(readRunnerScreenCaptureMetadata({ message: 'tmp/screenshot-1.png' }), undefined);
+});
+
+test.each([
+  ['a non-object payload', 'not-an-object'],
+  ['an array payload', [OPEN_DUO_CAPTURE]],
+  ['the pre-panel scale probe value leaking in as zero', { ...OPEN_DUO_CAPTURE, displayID: 0 }],
+  ['a zero-scale image', { ...OPEN_DUO_CAPTURE, pixelsPerPoint: 0 }],
+  ['a non-integer pixel box', { ...OPEN_DUO_CAPTURE, pixelWidth: 2852.5 }],
+  ['a missing side', { displayID: 3, pixelWidth: 2852, pixelsPerPoint: 3 }],
+  ['a negative scale', { ...OPEN_DUO_CAPTURE, pixelsPerPoint: -3 }],
+  ['a non-numeric scale', { ...OPEN_DUO_CAPTURE, pixelsPerPoint: '3' }],
+])('refuses %s rather than guessing a capture scale', (_case, metadata) => {
+  assert.equal(readRunnerScreenCaptureMetadata(runnerCapturePayload(metadata)), undefined);
+});
diff --git a/packages/platform-apple/src/core/screenshot.ts b/packages/platform-apple/src/core/screenshot.ts
index 621da08b32..1879149d2a 100644
--- a/packages/platform-apple/src/core/screenshot.ts
+++ b/packages/platform-apple/src/core/screenshot.ts
@@ -9,7 +9,6 @@ import { AppError } from '@agent-device/kernel/errors';
 import { resizePngFile } from '@agent-device/capture-kit/png-resize';
 import { readPngSize } from '@agent-device/capture-kit/png-size';
 import { computeDensityScaledScreenshotSize } from '@agent-device/capture-kit/screenshot-density';
-
 import {
   IOS_RUNNER_SCREENSHOT_COPY_TIMEOUT_MS,
   IOS_SIMULATOR_SCREENSHOT_RETRY_BASE_DELAY_MS,
@@ -34,6 +33,58 @@ import { runSimctlForDevice } from './simctl.ts';
 import { appleToolFailureText, extractAppleToolErrorMeta } from './tool-diagnostics.ts';
 import { resolveIosPhysicalDeviceControl } from './physical-device-control.ts';
 
+/** The `data` key a runner screenshot result carries its display facts under. */
+const RUNNER_SCREEN_CAPTURE_METADATA_KEY = 'screenshotMetadata';
+
+/**
+ * What one runner capture measured about itself. `pixelsPerPoint` is the scale of the image the
+ * runner encoded, `pixelWidth`/`pixelHeight` are that encoded image's own box after the runner drew
+ * it upright, and `displayID` is the screen the window reported — never a screen chosen by number
+ * or by position in a screen list. The runner owns this vocabulary; the literals are pinned against
+ * the Swift encoder in the screenshot tests.
+ */
+export type RunnerScreenCaptureMetadata = Readonly<{
+  displayID: number;
+  pixelWidth: number;
+  pixelHeight: number;
+  pixelsPerPoint: number;
+}>;
+
+/**
+ * Reads the display facts out of a runner `data` payload. Returns undefined when the payload carries
+ * none or carries a value that cannot describe a real capture, which leaves the consumer with no
+ * source fact — the honest pre-panel state — rather than a number invented from a panel nobody
+ * measured.
+ */
+export function readRunnerScreenCaptureMetadata(
+  data: Record<string, unknown>,
+): RunnerScreenCaptureMetadata | undefined {
+  const raw = data[RUNNER_SCREEN_CAPTURE_METADATA_KEY];
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return undefined;
+  const payload = raw as Record<string, unknown>;
+  const displayID = readPositiveInteger(payload.displayID);
+  const pixelWidth = readPositiveInteger(payload.pixelWidth);
+  const pixelHeight = readPositiveInteger(payload.pixelHeight);
+  const pixelsPerPoint = readPositiveFinite(payload.pixelsPerPoint);
+  if (
+    displayID === undefined ||
+    pixelWidth === undefined ||
+    pixelHeight === undefined ||
+    pixelsPerPoint === undefined
+  ) {
+    return undefined;
+  }
+  return Object.freeze({ displayID, pixelWidth, pixelHeight, pixelsPerPoint });
+}
+
+function readPositiveInteger(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isInteger(value) && value > 0 ? value : undefined;
+}
+
+function readPositiveFinite(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : undefined;
+}
+
 function runSimctl(device: DeviceInfo, args: string[], options?: ExecOptions) {
   return runSimctlForDevice(device, args, options);
 }
@@ -47,11 +98,18 @@ type SimulatorScreenshotFlowDeps = {
     outPath: string,
     display: AppleDeviceDisplay | undefined,
   ) => Promise<void>;
+  /**
+   * Rescales the captured file to the requested density using the scale of the image that was
+   * actually taken. `sourcePixelDensity` is that image's own measured scale — the panel the host
+   * named for a `simctl` capture, or what the runner reported for a runner capture. Undefined means
+   * nobody measured the source: a single-panel `simctl` capture, or a multi-panel device whose
+   * display inventory never resolved, and the scale probe is the answer either way.
+   */
   normalizeDensity: (
     device: DeviceInfo,
     outPath: string,
     pixelDensity: number | undefined,
-    display: AppleDeviceDisplay | undefined,
+    sourcePixelDensity: number | undefined,
   ) => Promise<void>;
   captureWithRunner: (
     device: DeviceInfo,
@@ -59,7 +117,7 @@ type SimulatorScreenshotFlowDeps = {
     appBundleId?: string,
     fullscreen?: boolean,
     runnerOptions?: AppleRunnerCommandOptions,
-  ) => Promise<void>;
+  ) => Promise<RunnerScreenCaptureMetadata | undefined>;
   shouldFallbackToRunner: (error: unknown) => boolean;
 };
 
@@ -136,7 +194,7 @@ export async function captureSimulatorScreenshotWithFallback(
   const display = await deps.resolveCaptureDisplay(device);
   const captureAndNormalize = async () => {
     await deps.captureWithRetry(device, outPath, display);
-    await deps.normalizeDensity(device, outPath, options.pixelDensity, display);
+    await deps.normalizeDensity(device, outPath, options.pixelDensity, display?.pointScale);
   };
   let restoreStatusBar = async () => {};
   if (options.normalizeStatusBar === true) {
@@ -169,17 +227,18 @@ export async function captureSimulatorScreenshotWithFallback(
       }
       emitScreenshotFallbackDiagnostic(device, 'simctl_screenshot', screenshotError);
     }
-    await deps.captureWithRunner(
+    const captured = await deps.captureWithRunner(
       device,
       outPath,
       options.appBundleId,
       options.fullscreen,
       options.runnerOptions,
     );
-    // The runner captures `XCUIScreen.main`, which is not necessarily the panel just
-    // resolved, so its scale stays unknown here. Applying the resolved panel's
-    // pointScale would rescale an image against a panel nobody measured.
-    await deps.normalizeDensity(device, outPath, options.pixelDensity, undefined);
+    // The runner captures the display that actually hosts the app and reports the scale it encoded
+    // that image at, so normalization reads the source instead of applying a panel the host guessed.
+    // A runner that reports nothing measured nothing: the probe stays the pre-panel answer rather
+    // than borrowing a scale from a panel nobody captured (#2728).
+    await deps.normalizeDensity(device, outPath, options.pixelDensity, captured?.pixelsPerPoint);
   } finally {
     await restoreStatusBar().catch((error) =>
       emitStatusBarDiagnostic(device, 'restore_failed', error),
@@ -226,7 +285,7 @@ export async function captureScreenshotViaRunner(
   appBundleId?: string,
   fullscreen?: boolean,
   runnerOptions?: AppleRunnerCommandOptions,
-): Promise<void> {
+): Promise<RunnerScreenCaptureMetadata | undefined> {
   if (device.kind === 'device' && !isMacOs(device)) {
     await resolveIosPhysicalDeviceControl(device).captureScreenshot(device, outPath, {
       appBundleId,
@@ -235,7 +294,7 @@ export async function captureScreenshotViaRunner(
       preferRunner: true,
       runRunnerCommand: runAppleRunnerCommand,
     });
-    return;
+    return undefined;
   }
 
   const result = await runAppleRunnerCommand(
@@ -256,14 +315,15 @@ export async function captureScreenshotViaRunner(
     );
   }
 
+  const metadata = readRunnerScreenCaptureMetadata(result);
   if (isMacOs(device)) {
     await copyHostFile(remoteFileName, outPath);
-    return;
+    return metadata;
   }
 
   if (device.kind === 'simulator') {
     await copyRunnerScreenshotFromSimulator(device, remoteFileName, outPath);
-    return;
+    return metadata;
   }
   throw new AppError('COMMAND_FAILED', 'Unsupported Apple screenshot target');
 }
@@ -463,16 +523,17 @@ async function normalizeIosSimulatorScreenshotDensity(
   device: DeviceInfo,
   outPath: string,
   pixelDensity: number | undefined,
-  display?: AppleDeviceDisplay,
+  sourcePixelDensity?: number,
 ): Promise<void> {
-  // `SIMULATOR_MAINSCREEN_SCALE` describes one fixed panel, so on a foldable it can
-  // disagree with the panel just captured. The captured panel reports its own scale.
-  const sourcePixelDensity = display
-    ? display.pointScale
-    : await readIosSimulatorMainScreenScale(device);
+  // Both the captured panel's `pointScale` and the runner's reported scale describe the image that
+  // was actually taken. `SIMULATOR_MAINSCREEN_SCALE` describes one fixed panel, so on a foldable it
+  // can disagree with the panel that was captured, and it is only ever consulted when nothing
+  // measured the source — which a multi-panel capture and every runner capture do.
+  const measuredSourcePixelDensity =
+    sourcePixelDensity ?? (await readIosSimulatorMainScreenScale(device));
   const targetSize = computeDensityScaledScreenshotSize(
     await readPngSize(outPath),
-    sourcePixelDensity,
+    measuredSourcePixelDensity,
     pixelDensity,
   );
   if (targetSize) await resizePngFile(outPath, targetSize.width, targetSize.height);
diff --git a/packages/platform-apple/src/runner/__tests__/runner-error-classification.test.ts b/packages/platform-apple/src/runner/__tests__/runner-error-classification.test.ts
index eb8590480d..1cd6c6fa1a 100644
--- a/packages/platform-apple/src/runner/__tests__/runner-error-classification.test.ts
+++ b/packages/platform-apple/src/runner/__tests__/runner-error-classification.test.ts
@@ -2,7 +2,9 @@ import assert from 'node:assert/strict';
 import { test } from 'vitest';
 import { AppError, createRequestCanceledError } from '@agent-device/kernel/errors';
 import {
+  classifyRunnerReportedError,
   RUNNER_ERROR_RULES,
+  RUNNER_SCREEN_CAPTURE_REFUSAL_RUNNER_CODES,
   isRetryableRunnerError,
   resolveRunnerFatalErrorReason,
   shouldRebuildCachedRunnerArtifact,
@@ -210,3 +212,19 @@ test('a terminal connect verdict refuses the restart even when the message match
   assert.equal(shouldRestartRunnerBeforeCommandSend(both), false);
   assert.equal(shouldRestartRunnerBeforeCommandSend(commandFailed('socket hang up')), false);
 });
+
+// The literals are what the Swift runner encodes, so they are the contract and not the constant
+// names: a rename on one side has to fail here rather than silently split the pair (#2728).
+test('a refused screen capture keeps the runner reason and stays off the wire code', () => {
+  assert.deepEqual([...RUNNER_SCREEN_CAPTURE_REFUSAL_RUNNER_CODES].sort(), [
+    'APP_SCREEN_CAPTURE_UNRENDERABLE',
+    'APP_SCREEN_UNRESOLVED',
+    'APP_SCREEN_WINDOW_UNRESOLVED',
+  ]);
+  for (const runnerCode of RUNNER_SCREEN_CAPTURE_REFUSAL_RUNNER_CODES) {
+    const classified = classifyRunnerReportedError(runnerCode);
+    assert.equal(classified.code, 'COMMAND_FAILED');
+    assert.equal(classified.details.runnerErrorCode, runnerCode);
+    assert.equal(classified.details.retriable, undefined);
+  }
+});
diff --git a/packages/platform-apple/src/runner/runner-contract.ts b/packages/platform-apple/src/runner/runner-contract.ts
index bd1848724a..aabcd91638 100644
--- a/packages/platform-apple/src/runner/runner-contract.ts
+++ b/packages/platform-apple/src/runner/runner-contract.ts
@@ -695,6 +695,24 @@ export function shouldRestartRunnerBeforeCommandSend(error: unknown): boolean {
  */
 export const SCROLL_KEYBOARD_OCCLUDES_SURFACE_RUNNER_CODE = 'SCROLL_KEYBOARD_OCCLUDES_SURFACE';
 
+/**
+ * The codes the XCTest runner answers with when a screenshot did not happen (#2728): no window
+ * resolved so no display could be named, the resolved window named no display, or the resolved
+ * display handed back an image it could not encode upright. They are the runner's own vocabulary, so
+ * they are declared here beside the set that keeps them off the wire, and a required capture fails
+ * closed on them rather than falling back to a screen nobody is on.
+ */
+const RUNNER_SCREEN_WINDOW_UNRESOLVED_RUNNER_CODE = 'APP_SCREEN_WINDOW_UNRESOLVED';
+const RUNNER_SCREEN_UNRESOLVED_RUNNER_CODE = 'APP_SCREEN_UNRESOLVED';
+const RUNNER_SCREEN_CAPTURE_UNRENDERABLE_RUNNER_CODE = 'APP_SCREEN_CAPTURE_UNRENDERABLE';
+
+/** Every runner code meaning "this capture did not happen", covering the display and the image. */
+export const RUNNER_SCREEN_CAPTURE_REFUSAL_RUNNER_CODES: ReadonlySet<string> = new Set([
+  RUNNER_SCREEN_WINDOW_UNRESOLVED_RUNNER_CODE,
+  RUNNER_SCREEN_UNRESOLVED_RUNNER_CODE,
+  RUNNER_SCREEN_CAPTURE_UNRENDERABLE_RUNNER_CODE,
+]);
+
 /**
  * Runner codes that classify a failure for the host without renaming it on the wire. They stay
  * `COMMAND_FAILED` and survive as `details.runnerErrorCode`, which is what family policy reads:
@@ -706,6 +724,7 @@ const DIAGNOSTIC_ONLY_RUNNER_ERROR_CODES: ReadonlySet<string> = new Set([
   MAIN_THREAD_TIMEOUT_RUNNER_CODE,
   ALERT_NOT_FOUND_RUNNER_CODE,
   SCROLL_KEYBOARD_OCCLUDES_SURFACE_RUNNER_CODE,
+  ...RUNNER_SCREEN_CAPTURE_REFUSAL_RUNNER_CODES,
 ]);
 
 /** Wire code plus the details every path must publish for one runner-reported error code. */

From 7a13d2d5ee15ff6f56afcd89468f3264d857e3f3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Tue, 22 Sep 2026 13:33:53 +0200
Subject: [PATCH 018/132] 0.21.9

---
 package.json | 2 +-
 server.json  | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/package.json b/package.json
index 82ef4cda98..1cdb9b0b9b 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "agent-device",
-  "version": "0.21.8",
+  "version": "0.21.9",
   "description": "Mobile app automation and verification for AI coding agents. CLI, MCP server, and typed Node.js API for iOS, Android, HarmonyOS, TV, web, macOS, and Linux.",
   "mcpName": "io.github.callstack/agent-device",
   "license": "MIT",
diff --git a/server.json b/server.json
index f71924f5d7..0b38841606 100644
--- a/server.json
+++ b/server.json
@@ -7,12 +7,12 @@
     "url": "https://github.com/callstack/agent-device",
     "source": "github"
   },
-  "version": "0.21.8",
+  "version": "0.21.9",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "agent-device",
-      "version": "0.21.8",
+      "version": "0.21.9",
       "transport": {
         "type": "stdio"
       },

From 078741316de7f241a14061fc730de4d284563b46 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Tue, 22 Sep 2026 14:38:26 +0200
Subject: [PATCH 019/132] fix(ios): bind Safari as the target app for simulator
 web-URL opens (#2761)

---
 .../__tests__/session-open-existing.test.ts   | 50 +++++++++++++++++++
 .../session-open-url-prewarm.test.ts          |  6 +--
 src/platform-runtime-open-target.ts           |  4 +-
 3 files changed, 56 insertions(+), 4 deletions(-)

diff --git a/src/daemon/session-lifecycle/internal/__tests__/session-open-existing.test.ts b/src/daemon/session-lifecycle/internal/__tests__/session-open-existing.test.ts
index 446e8ebe46..554d189172 100644
--- a/src/daemon/session-lifecycle/internal/__tests__/session-open-existing.test.ts
+++ b/src/daemon/session-lifecycle/internal/__tests__/session-open-existing.test.ts
@@ -59,6 +59,56 @@ test('open web URL on iOS device session without active app falls back to Safari
   expect(dispatchedContext?.appBundleId).toBe('com.apple.mobilesafari');
 });
 
+test('open web URL on iOS simulator session without active app falls back to Safari', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'ios-simulator-session';
+  sessionStore.set(
+    sessionName,
+    makeSession(sessionName, {
+      platform: 'apple',
+      id: 'ios-simulator-1',
+      name: 'iPhone Simulator',
+      kind: 'simulator',
+      booted: true,
+    }),
+  );
+
+  mockResolveTargetDevice.mockResolvedValue({
+    platform: 'apple',
+    id: 'ios-simulator-1',
+    name: 'iPhone Simulator',
+    kind: 'simulator',
+    booted: true,
+  });
+
+  let dispatchedContext: Record<string, unknown> | undefined;
+  mockDispatch.mockImplementation(async (_device, _command, _positionals, _out, context) => {
+    dispatchedContext = context as Record<string, unknown> | undefined;
+    return {};
+  });
+
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'open',
+      positionals: ['https://example.com/path'],
+      flags: {},
+    },
+    sessionName,
+    logPath: path.join(mkdtempForTestSync('daemon'), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+  });
+
+  expect(response).toBeTruthy();
+  expect(response?.ok).toBe(true);
+  const updated = sessionStore.get(sessionName);
+  expect(updated?.appBundleId).toBe('com.apple.mobilesafari');
+  expect(updated?.appName).toBe('https://example.com/path');
+  expect(dispatchedContext?.appBundleId).toBe('com.apple.mobilesafari');
+});
+
 test('open app and URL on existing iOS device session keeps app context', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'ios-device-session';
diff --git a/src/daemon/session-lifecycle/internal/__tests__/session-open-url-prewarm.test.ts b/src/daemon/session-lifecycle/internal/__tests__/session-open-url-prewarm.test.ts
index b2651327ba..aae46b5573 100644
--- a/src/daemon/session-lifecycle/internal/__tests__/session-open-url-prewarm.test.ts
+++ b/src/daemon/session-lifecycle/internal/__tests__/session-open-url-prewarm.test.ts
@@ -134,7 +134,7 @@ function sessionRequest(
   };
 }
 
-test('open URL on existing iOS session clears stale app bundle id', async () => {
+test('open web URL on existing iOS simulator session binds Safari and drops stale app bundle id', async () => {
   const sessionStore = makeSessionStore('agent-device-session-open-url-prewarm-');
   const sessionName = 'ios-session';
   sessionStore.set(
@@ -171,9 +171,9 @@ test('open URL on existing iOS session clears stale app bundle id', async () =>
 
   expect(response.ok).toBe(true);
   const updated = sessionStore.get(sessionName);
-  expect(updated?.appBundleId).toBe(undefined);
+  expect(updated?.appBundleId).toBe('com.apple.mobilesafari');
   expect(updated?.appName).toBe('https://example.com/path');
-  expect(dispatchedContext?.appBundleId).toBe(undefined);
+  expect(dispatchedContext?.appBundleId).toBe('com.apple.mobilesafari');
 });
 
 test('open URL on existing macOS session clears stale app bundle id', async () => {
diff --git a/src/platform-runtime-open-target.ts b/src/platform-runtime-open-target.ts
index 4d6930c4af..9519b9429f 100644
--- a/src/platform-runtime-open-target.ts
+++ b/src/platform-runtime-open-target.ts
@@ -1,4 +1,5 @@
 import {
+  IOS_SAFARI_BUNDLE_ID,
   isDeepLinkTarget,
   isWebUrl,
   resolveIosDeviceDeepLinkBundleId,
@@ -115,7 +116,8 @@ async function resolveIosBundleIdForOpen(
         currentAppBundleId ?? (await tryResolveIosSimulatorDeepLinkBundleId(device, openTarget))
       );
     }
-    return undefined;
+    // simctl openurl opens a web URL in Safari, so Safari is the target app for later interactions.
+    return IOS_SAFARI_BUNDLE_ID;
   }
   return await tryResolveIosAppBundleId(device, openTarget);
 }

From efc5a29fb373a6ff5e42141c5475c45dcde56dd0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Tue, 22 Sep 2026 14:56:49 +0200
Subject: [PATCH 020/132] 0.21.10

---
 package.json | 2 +-
 server.json  | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/package.json b/package.json
index 1cdb9b0b9b..279e5413fb 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "agent-device",
-  "version": "0.21.9",
+  "version": "0.21.10",
   "description": "Mobile app automation and verification for AI coding agents. CLI, MCP server, and typed Node.js API for iOS, Android, HarmonyOS, TV, web, macOS, and Linux.",
   "mcpName": "io.github.callstack/agent-device",
   "license": "MIT",
diff --git a/server.json b/server.json
index 0b38841606..6ef73a44c6 100644
--- a/server.json
+++ b/server.json
@@ -7,12 +7,12 @@
     "url": "https://github.com/callstack/agent-device",
     "source": "github"
   },
-  "version": "0.21.9",
+  "version": "0.21.10",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "agent-device",
-      "version": "0.21.9",
+      "version": "0.21.10",
       "transport": {
         "type": "stdio"
       },

From d69ee4b70e46932ce2118bd542132d5ef22787e8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Tue, 22 Sep 2026 16:48:26 +0200
Subject: [PATCH 021/132] chore(gates): drop the contact-sheet over-ceiling
 approval now that main carries it (#2757)

#2747 approved packages/capture-kit/src/recording/contact-sheet.ts over its
domain-facade ceiling. Main now carries the entry, so the no-growth rule
governs it and the row can no longer change a verdict. The stale-row check
defers on main itself, so every branch based on main after #2747 failed
Coverage with "no APPROVED_OVER_CEILING row is stale".

Co-authored-by: Claude <noreply@anthropic.com>
---
 scripts/__tests__/eager-closure-budgets.ts | 9 +--------
 1 file changed, 1 insertion(+), 8 deletions(-)

diff --git a/scripts/__tests__/eager-closure-budgets.ts b/scripts/__tests__/eager-closure-budgets.ts
index c59dd07e78..337a4b6e5a 100644
--- a/scripts/__tests__/eager-closure-budgets.ts
+++ b/scripts/__tests__/eager-closure-budgets.ts
@@ -127,14 +127,7 @@ export const NEW_ENTRY_CEILINGS: Readonly<Record<EntryCategory, number>> = Objec
  */
 export const APPROVED_OVER_CEILING: Readonly<
   Record<string, { issue: string; reason: string; owner: string }>
-> = Object.freeze({
-  'packages/capture-kit/src/recording/contact-sheet.ts': {
-    issue: '#2747',
-    reason:
-      'Reading a recording through one PNG needs the sample grid, the frame decoder seam, and the PNG codec behind a single surface. Every module it evaluates is capture-kit mechanics, so the property the ceiling guards — no façade evaluating a concrete platform implementation — holds; only its weight is above the p75 of façades that answer a narrower question.',
-    owner: 'capture-kit',
-  },
-});
+> = Object.freeze({});
 
 /** The category is a function of the path, never a hand-written column. */
 export function entryCategoryOf(entryFile: string): EntryCategory {

From 5ec737d5a9d5828707b0cf8cb0f835daa52d02b6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Tue, 22 Sep 2026 16:48:26 +0200
Subject: [PATCH 022/132] fix(ios): read scroll indicator ownership from the
 parent edge (#2754 step 1) (#2758)

Ownership of a scroll indicator is now read from the producer's parent
edge, passing up only through ancestors that share the scroller's exact
frame, instead of walking for the nearest scrollable or text node. A
scroll-typed node labelled as an indicator describes itself and owns
nothing. This stops an indicator from a scroll-shaped host that publishes
as a non-scroll type (a WebView row, a map, a paged cell) from clipping
the enclosing list to the host's band (#2214), while a WKWebView page
whose wrappers fill the ScrollView keeps its visible band (#1784/#1797).
The walk stops at the first frame change, so a host smaller than its
list still owns nothing. ADR 0026.
---
 CHANGELOG.md                                  |  10 +
 .../ios-snapshot-engine-conformance.json      | 167 +++++++++++++
 docs/adr/0026-scroll-clip-authority.md        |  41 +++-
 .../runner-presentation.test.ts               | 231 ++++++++++++++++++
 .../src/ios-snapshot-engine/scroll.ts         |  52 ++--
 5 files changed, 469 insertions(+), 32 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5870d0eeee..7301f3b3f4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+- Fixed (ios): an interactive snapshot no longer drops the rows of a list whose row hosts a scroll
+  view of its own. Ownership of a scroll indicator is now read from its parent edge — a visible band
+  derives only when the indicator's parent is itself a scroll type — instead of walking ancestors for
+  the nearest scrollable or text node. #2740 closed the class for `TextView` alone; the walk still
+  misattributed the indicator of any other scroll-shaped host that publishes as a non-scroll type (a
+  `WebView`, a map view, a paged cell) to the enclosing list and clipped that list to the host's
+  one-line band. Ownership still passes up through ancestors that share the scroller's exact frame, so a
+  `WKWebView` page — whose indicator sits under `WebView` wrappers that fill the scroll view — keeps its
+  visible band; the walk stops at the first frame change, so a host smaller than its list still owns
+  nothing. ADR 0026.
 - Fixed (ios): `fold half-open` no longer reports a pose the hinge never held. The command accepted
   the requested category as the answer whenever its four-read budget happened to end on a
   `half-open` angle, so a hinge still sweeping from 180° toward 0° — which passes through every
diff --git a/contracts/fixtures/ios-snapshot-engine-conformance.json b/contracts/fixtures/ios-snapshot-engine-conformance.json
index 40be79491c..983931ef98 100644
--- a/contracts/fixtures/ios-snapshot-engine-conformance.json
+++ b/contracts/fixtures/ios-snapshot-engine-conformance.json
@@ -1165,6 +1165,173 @@
           }
         ]
       }
+    },
+    {
+      "name": "scroll indicator owned by a parent web view keeps list rows",
+      "swift": false,
+      "projection": "regular",
+      "interactiveOnly": true,
+      "depth": null,
+      "scope": null,
+      "foldPolicy": "cursor-projected",
+      "truncated": false,
+      "residue": [],
+      "nodes": [
+        {
+          "index": 0,
+          "type": "Application",
+          "label": "App",
+          "rect": { "x": 0, "y": 0, "width": 320, "height": 240 },
+          "enabled": true,
+          "hittable": false,
+          "depth": 0
+        },
+        {
+          "index": 1,
+          "type": "Table",
+          "label": "Feed",
+          "rect": { "x": 0, "y": 40, "width": 320, "height": 200 },
+          "enabled": true,
+          "hittable": false,
+          "depth": 1,
+          "parentIndex": 0
+        },
+        {
+          "index": 2,
+          "type": "Other",
+          "label": "Story",
+          "rect": { "x": 16, "y": 60, "width": 288, "height": 22 },
+          "enabled": true,
+          "hittable": false,
+          "depth": 2,
+          "parentIndex": 1
+        },
+        {
+          "index": 3,
+          "type": "WebView",
+          "label": "Story",
+          "rect": { "x": 16, "y": 60, "width": 288, "height": 22 },
+          "enabled": true,
+          "hittable": false,
+          "depth": 3,
+          "parentIndex": 2
+        },
+        {
+          "index": 4,
+          "type": "Other",
+          "label": "Vertical scroll bar, 1 page",
+          "value": "0%",
+          "rect": { "x": 300, "y": 60, "width": 10, "height": 22 },
+          "enabled": true,
+          "hittable": false,
+          "depth": 4,
+          "parentIndex": 3
+        },
+        {
+          "index": 5,
+          "type": "Button",
+          "label": "Reply",
+          "rect": { "x": 16, "y": 100, "width": 60, "height": 28 },
+          "enabled": true,
+          "hittable": true,
+          "depth": 2,
+          "parentIndex": 1
+        },
+        {
+          "index": 6,
+          "type": "Button",
+          "label": "Like",
+          "rect": { "x": 16, "y": 140, "width": 60, "height": 28 },
+          "enabled": true,
+          "hittable": true,
+          "depth": 2,
+          "parentIndex": 1
+        },
+        {
+          "index": 7,
+          "type": "Other",
+          "label": "Vertical scroll bar, 3 pages",
+          "value": "0%",
+          "rect": { "x": 306, "y": 40, "width": 10, "height": 150 },
+          "enabled": true,
+          "hittable": false,
+          "depth": 2,
+          "parentIndex": 1
+        }
+      ],
+      "expected": {
+        "outcome": "success",
+        "truncated": false,
+        "residue": [],
+        "nodes": [
+          {
+            "index": 0,
+            "type": "Application",
+            "label": "App",
+            "rect": { "x": 0, "y": 0, "width": 320, "height": 240 },
+            "depth": 0,
+            "parentIndex": null,
+            "hittable": false,
+            "hiddenContentAbove": false,
+            "hiddenContentBelow": false
+          },
+          {
+            "index": 1,
+            "type": "Table",
+            "label": "Feed",
+            "rect": { "x": 0, "y": 40, "width": 320, "height": 150 },
+            "depth": 1,
+            "parentIndex": 0,
+            "hittable": false,
+            "hiddenContentAbove": false,
+            "hiddenContentBelow": true
+          },
+          {
+            "index": 2,
+            "type": "Other",
+            "label": "Story",
+            "rect": { "x": 16, "y": 60, "width": 288, "height": 22 },
+            "depth": 2,
+            "parentIndex": 1,
+            "hittable": false,
+            "hiddenContentAbove": false,
+            "hiddenContentBelow": false
+          },
+          {
+            "index": 3,
+            "type": "WebView",
+            "label": "Story",
+            "rect": { "x": 16, "y": 60, "width": 288, "height": 22 },
+            "depth": 3,
+            "parentIndex": 2,
+            "hittable": false,
+            "hiddenContentAbove": false,
+            "hiddenContentBelow": false
+          },
+          {
+            "index": 4,
+            "type": "Button",
+            "label": "Reply",
+            "rect": { "x": 16, "y": 100, "width": 60, "height": 28 },
+            "depth": 2,
+            "parentIndex": 1,
+            "hittable": true,
+            "hiddenContentAbove": false,
+            "hiddenContentBelow": false
+          },
+          {
+            "index": 5,
+            "type": "Button",
+            "label": "Like",
+            "rect": { "x": 16, "y": 140, "width": 60, "height": 28 },
+            "depth": 2,
+            "parentIndex": 1,
+            "hittable": true,
+            "hiddenContentAbove": false,
+            "hiddenContentBelow": false
+          }
+        ]
+      }
     }
   ]
 }
diff --git a/docs/adr/0026-scroll-clip-authority.md b/docs/adr/0026-scroll-clip-authority.md
index 9a4eaff9aa..c4c0bc1d59 100644
--- a/docs/adr/0026-scroll-clip-authority.md
+++ b/docs/adr/0026-scroll-clip-authority.md
@@ -16,8 +16,8 @@ walking up past the indicator's parent, and that guess decided which nodes exist
 
 | Situation | Behavior |
 | --- | --- |
-| Which scroll view an indicator reports on | Its **parent**, when that parent is a scroll type (or the scroll host itself when it carries the label — open, below). UIKit publishes an indicator inside its own scroll view, and the producer's tree already says so |
-| An indicator whose parent is not a scroll type — `TextView`, `WebView`, a cell | Owns nothing. No band, no clip, and the host's own scrollability stays with that host |
+| Which scroll view an indicator reports on | Its **parent**, when that parent is a scroll type. UIKit publishes an indicator inside its own scroll view, and the producer's tree already says so. Ownership also passes **up through ancestors that share their own parent's exact frame** — the producer's transparent wrappers around one scroll region (Safari nests `Other` → `WebView` → `WebView` above a `WKWebView`'s `ScrollView`, all one frame). A node that is **itself** a scroll type and carries the label describes itself, not its parent, so it owns nothing (resolved: #2754 step 1 — banding its parent would clip a sibling list to the host's band, mirroring #2214 upward) |
+| An indicator whose nearest scroll-typed ancestor is reached only across a frame change — a smaller `TextView`/`WebView`/cell host | Owns nothing. No band, no clip, and the host's own scrollability stays with that host. The frame change, not a label or type, is what ends the walk (resolved: #2754 step 3 on a real `WKWebView` capture) |
 | The visible band | Derived by presentation from the owner's frame and the indicator's track. Never reported by a producer |
 | Removing a node **because a scroll band hides it** | Requires evidence: the clip fold's result, or a band whose owner is the indicator's parent. A guess about ownership may not do it |
 | Removing a node by semantic delegation — a collapsed row, a duplicate label, a wrapper's content | Out of scope here. That is compaction, and it keeps its own authority |
@@ -34,6 +34,14 @@ that host: `REGULAR_ELIGIBLE_TYPES` in `ios-snapshot-engine/projection.ts` and `
 in `SnapshotPresentationProjection.swift` both carry `Cell`, `CollectionView`, `ScrollView`, `Table`,
 `TextView`, and `WebView`. Those two lists are one fact in two languages and must stay in step.
 
+Passing ownership up through **same-frame** ancestors keeps ownership read rather than inferred: the
+producer states two nodes are the same rectangle, which is a structural fact, not a label or type guess.
+It is needed because a `WKWebView`'s page indicator is published under `WebView` wrappers that fill the
+`ScrollView` exactly (#1784/#1797, and real captures in #2754 step 3); strict parent-edge ownership left
+that scroller unbanded and returned content scrolled under the toolbar. The walk stops at the first frame
+change, so a host that is smaller than its parent — a `WebView` row in a list — is a different scroll
+region and still owns nothing, which is the #2214 bug the pass-through must not reintroduce.
+
 That eligibility claim is scoped to iOS, and `scrollarea` is why. `isScrollableSnapshotType` accepts it,
 neither eligible set contains it, and the iOS runner never emits it — it originates in the macOS helper's
 `AXScrollArea` mapping. That helper's trees do reach these rules, through `snapshot-desktop-surface.ts`
@@ -92,17 +100,24 @@ source of truth.
 
 ## Consequences and open evidence
 
-- **Under-clipping is the new risk.** Dropping the walk means a tree that places an indicator under a
-  labelled wrapper rather than directly under its scroll view gets no band, so content scrolled under the
-  chrome survives in the output. That is a leak of a different kind from the one the clip fold owns
-  (#1797, with #1784 adjacent on private-AX projection); it is the band's own job, and nothing else covers
-  it. Measured so far: the full unit suite passes with parent-edge ownership, and a synthetic `WebView` row
-  keeps rows that `main` drops. Real captured trees must be surveyed for that wrapper shape before landing.
-- **The `WebView` instance is synthetic.** The mechanism is confirmed in a hand-built tree; that XCTest
-  publishes a `WKWebView`'s indicator the same way is unverified.
-- **The self case is unpinned.** The rule also treats a scroll-typed node carrying an indicator label as
-  its own owner. No test exercises that branch — parent-only ownership without it passes the full suite —
-  so #2754 step 1 keeps it with a case or deletes it deliberately, rather than inheriting it.
+- **Under-clipping was the open risk; same-frame pass-through resolves the real instance.** Strict
+  parent-edge ownership left a `WKWebView` page scroller unbanded because the page indicator is published
+  under `WebView` wrappers, leaking content under the toolbar (#1797, with #1784 adjacent). #2754 step 3
+  surveyed real captures (Settings, Settings › Privacy & Security, a Safari `WKWebView` page — 25 indicators,
+  18 under a non-scroll parent) and found exactly this shape on the web surface. Resolved by passing
+  ownership through same-frame ancestors, which reproduces `main`'s clip on all three real captures while
+  the smaller-host row cases (#2214) still own nothing. A genuinely frame-mismatched non-scroll wrapper
+  would still under-clip, but no captured iOS tree has that shape.
+- **The `WebView` shape is now confirmed on real data.** A Safari `snapshot -i --raw` capture shows the
+  `WKWebView`'s indicator published under `Other` → `WebView` → `WebView` ancestors that fill the
+  `ScrollView` exactly; the fixture in `runner-presentation.test.ts` reduces that live tree.
+- **The self case is resolved: a scroll-typed indicator owns nothing.** #2754 step 1 deleted the
+  self-ownership branch. Reading a scroll-typed node labelled as an indicator onto its own band is a
+  no-op (the indicator and container are the same rect, which `deriveScrollableViewportRect` refuses),
+  while reading it onto its parent clips a sibling list to that host — the #2214 failure mirrored
+  upward. So `findScrollIndicatorContainer` returns null when the node is itself a scroll type;
+  `runner-presentation.test.ts` pins a scroll host labelled as an indicator leaving its parent list's
+  band intact.
 - **macOS is already a second consumer of these rules.** Desktop capture runs the engine through
   `snapshot-desktop-surface.ts` → `ios-snapshot-runtime.ts` → `publishIosSnapshot`, and its trees carry
   `ScrollArea`, which neither eligible set admits. The parent-edge rule needs its own decision there
diff --git a/packages/capture-kit/src/ios-snapshot-engine/runner-presentation.test.ts b/packages/capture-kit/src/ios-snapshot-engine/runner-presentation.test.ts
index 2835749567..f655b4c935 100644
--- a/packages/capture-kit/src/ios-snapshot-engine/runner-presentation.test.ts
+++ b/packages/capture-kit/src/ios-snapshot-engine/runner-presentation.test.ts
@@ -51,6 +51,99 @@ test('a text view scroll indicator inside a list does not clip the list to that
     labels.some((label) => label === 'Vertical scroll bar, 1 page'),
     false,
   );
+  // Source-level membership: the text view's indicator (source index 5) owns nothing.
+  assert.deepEqual(result.presentedIndexesBySourceIndex.get(5), []);
+  assert.ok((result.presentedIndexesBySourceIndex.get(6) ?? []).length > 0);
+});
+
+// #2214 was patched for `TextView` alone (#2740); ADR 0026 generalises the rule to the parent edge,
+// so every scroll-shaped host that publishes as a non-scroll type keeps its own indicator. A
+// `WKWebView` (a UIScrollView underneath) and a paged `Cell` both reopen the class on `origin/main`:
+// the ancestor walk skips the non-scroll host and clips the enclosing list to the host's one-line
+// band. These cases are red before the parent-edge change and green after it.
+for (const hostType of ['WebView', 'Cell']) {
+  test(`a ${hostType} row's own scroll indicator does not clip the enclosing list`, () => {
+    const request = createIosSnapshotRequest({ interactiveOnly: true });
+    const result = presentIosSnapshot(runnerInput(request, hostRowNodes(hostType)), request);
+    const labels = result.nodes.map((node) => node.label);
+
+    assert.deepEqual(result.nodes.find((node) => node.type === 'ScrollView')?.rect, {
+      x: 0,
+      y: 110,
+      width: 402,
+      height: 702,
+    });
+    assert.ok(labels.includes('Reply (58 replies)'));
+    assert.ok(labels.includes('Reply 37'));
+    assert.ok(labels.includes('Like (0 likes)'));
+    assert.equal(
+      labels.some((label) => label === 'Vertical scroll bar, 1 page'),
+      false,
+    );
+    // Source-level membership: the host's indicator (source index 4) presents no representative, so it
+    // owns nothing, while every row below the host (indices 5-7) keeps one. On `origin/main` the
+    // indicator is attributed to the list, so index 4 would map to the list's representative instead.
+    assert.deepEqual(result.presentedIndexesBySourceIndex.get(4), []);
+    for (const rowSourceIndex of [5, 6, 7]) {
+      assert.ok(
+        (result.presentedIndexesBySourceIndex.get(rowSourceIndex) ?? []).length > 0,
+        `row source index ${rowSourceIndex} must survive`,
+      );
+    }
+  });
+}
+
+// A scroll-typed node that carries an indicator label describes itself, not its parent. It must own
+// nothing: banding its parent would clip a sibling list to the host's band, mirroring #2214 upward.
+test('a scroll-typed node labelled as an indicator does not band its parent list', () => {
+  const request = createIosSnapshotRequest({ interactiveOnly: true });
+  const result = presentIosSnapshot(runnerInput(request, nestedScrollIndicatorNodes()), request);
+  const labels = result.nodes.map((node) => node.label);
+
+  assert.deepEqual(result.nodes.find((node) => node.type === 'Table')?.rect, {
+    x: 0,
+    y: 116,
+    width: 402,
+    height: 696,
+  });
+  assert.ok(labels.includes('Row low'));
+});
+
+// The pass-through stops at the first frame change (ADR 0026). A wrapper that fills the scroll view is
+// a transparent part of that one scroll region, but a smaller wrapper is a different scroll region.
+// Here the walk climbs `Wrapper` → `Scroller` (same frame) and then hits a smaller sibling — so the
+// indicator below the frame change resolves no owner and the list keeps its full extent, rather than
+// banding `Scroller` to the smaller wrapper's sub-region.
+test('a frame change stops the pass-through so a sub-region indicator owns nothing', () => {
+  const request = createIosSnapshotRequest({ interactiveOnly: true });
+  const result = presentIosSnapshot(runnerInput(request, frameChangeIndicatorNodes()), request);
+  const scrollView = result.nodes.find((node) => node.type === 'ScrollView');
+  const labels = result.nodes.map((node) => node.label);
+
+  assert.deepEqual(scrollView?.rect, { x: 0, y: 110, width: 402, height: 764 });
+  assert.equal(scrollView?.hiddenContentBelow, undefined);
+  assert.ok(labels.includes('Row below'));
+  assert.deepEqual(result.presentedIndexesBySourceIndex.get(4), []);
+});
+
+// Reduced from a real `snapshot -i --raw` capture of a WKWebView page in Safari (survey, #2754 step
+// 3): the page scroller is `ScrollView` → `Other` → `WebView` → `WebView`, all one frame
+// {0,0,402,874}, and the page's indicator ("Vertical scroll bar, 6 pages", {369,62,30,750}) is
+// published under the inner `WebView`. Because those ancestors share the scroller's exact frame,
+// ownership passes up to the `ScrollView`, so the page clips to the visible band {0,62,402,750} with
+// `History` scrolled below it — the same output `origin/main` produces, confirmed byte-for-byte on the
+// full capture. This is the leak #1784/#1797 under strict parent-edge ownership; the frame
+// pass-through is the tolerance, and here the host fills the scroller, so it is the scroller's own
+// region rather than a nested one (the `WebView`-row case above stays owned by nothing).
+test('a WKWebView page whose web hosts fill the scroller clips to the page band', () => {
+  const request = createIosSnapshotRequest({ interactiveOnly: true });
+  const result = presentIosSnapshot(runnerInput(request, safariWebViewNodes()), request);
+  const scrollView = result.nodes.find((node) => node.type === 'ScrollView');
+  const labels = result.nodes.map((node) => node.label);
+
+  assert.deepEqual(scrollView?.rect, { x: 0, y: 62, width: 402, height: 750 });
+  assert.equal(scrollView?.hiddenContentBelow, true);
+  assert.equal(labels.includes('History'), false);
 });
 
 function runnerInput(request: IosSnapshotRequest, nodes: RawSnapshotNode[]): IosSnapshotInput {
@@ -181,6 +274,144 @@ function threadNodes(): RawSnapshotNode[] {
   ];
 }
 
+/**
+ * A list whose row is a scroll-shaped host that publishes as a non-scroll type. The host carries an
+ * indicator of its own (a one-page band over the row), while the list's own indicator reports the real
+ * multi-page track. Correct ownership keeps the list's band and every row below the host.
+ */
+function hostRowNodes(hostType: string): RawSnapshotNode[] {
+  const rowRect = { x: 16, y: 180, width: 370, height: 22 };
+  return [
+    runnerNode(0, 'Application', 'Reader', viewport),
+    runnerNode(
+      1,
+      'ScrollView',
+      'Vertical scroll bar, 3 pages',
+      { x: 0, y: 110, width: 402, height: 764 },
+      0,
+      1,
+    ),
+    runnerNode(2, 'Other', 'Article', { x: 0, y: 110, width: 402, height: 764 }, 1, 2),
+    runnerNode(3, hostType, 'Page', rowRect, 2, 3),
+    {
+      ...runnerNode(
+        4,
+        'Other',
+        'Vertical scroll bar, 1 page',
+        { x: 353, y: 180, width: 30, height: 22 },
+        3,
+        4,
+      ),
+      value: '0%',
+    },
+    runnerNode(5, 'Button', 'Reply (58 replies)', { x: 9, y: 232, width: 54, height: 32 }, 2, 3),
+    runnerNode(6, 'Link', 'Reply 37', { x: 16, y: 274, width: 370, height: 165 }, 2, 3),
+    runnerNode(7, 'Button', 'Like (0 likes)', { x: 209, y: 412, width: 28, height: 28 }, 6, 4),
+    {
+      ...runnerNode(
+        8,
+        'Other',
+        'Vertical scroll bar, 3 pages',
+        { x: 369, y: 110, width: 30, height: 702 },
+        1,
+        2,
+      ),
+      value: '0%',
+    },
+  ];
+}
+
+/**
+ * A list that holds a nested scroll host (a `ScrollView`) which itself carries a scroll-bar label and
+ * a percent value. That node describes itself, so it owns nothing; the list's real multi-page band
+ * comes from its own indicator, keeping `Row low`.
+ */
+function nestedScrollIndicatorNodes(): RawSnapshotNode[] {
+  return [
+    runnerNode(0, 'Application', 'Reader', viewport),
+    runnerNode(1, 'Table', 'Feed', { x: 0, y: 40, width: 402, height: 800 }, 0, 1),
+    {
+      ...runnerNode(
+        2,
+        'ScrollView',
+        'Vertical scroll bar, 2 pages',
+        { x: 0, y: 300, width: 402, height: 40 },
+        1,
+        2,
+      ),
+      value: '50%',
+    },
+    runnerNode(3, 'Button', 'Row high', { x: 16, y: 60, width: 370, height: 40 }, 1, 2),
+    runnerNode(4, 'Button', 'Row low', { x: 16, y: 700, width: 370, height: 40 }, 1, 2),
+    {
+      ...runnerNode(
+        5,
+        'Other',
+        'Vertical scroll bar, 3 pages',
+        { x: 369, y: 116, width: 30, height: 696 },
+        1,
+        2,
+      ),
+      value: '0%',
+    },
+  ];
+}
+
+/**
+ * A list (`ScrollView`, {0,110,402,764}) holding a smaller `Card` sub-region ({0,300,402,400}) that
+ * nests an `Inner` wrapper of the same sub-frame and the indicator. The walk climbs `Inner` → `Card`
+ * (same frame) but then hits the frame change against `ScrollView`, so the indicator resolves no owner
+ * and `ScrollView` keeps its full extent — the frame change, not a label, is what stops ownership.
+ */
+function frameChangeIndicatorNodes(): RawSnapshotNode[] {
+  return [
+    runnerNode(0, 'Application', 'Reader', viewport),
+    runnerNode(1, 'ScrollView', 'Feed', { x: 0, y: 110, width: 402, height: 764 }, 0, 1),
+    runnerNode(2, 'Other', 'Card', { x: 0, y: 300, width: 402, height: 400 }, 1, 2),
+    runnerNode(3, 'Other', 'Inner', { x: 0, y: 300, width: 402, height: 400 }, 2, 3),
+    {
+      ...runnerNode(
+        4,
+        'Other',
+        'Vertical scroll bar, 3 pages',
+        { x: 369, y: 300, width: 30, height: 400 },
+        3,
+        4,
+      ),
+      value: '0%',
+    },
+    runnerNode(5, 'Button', 'Row above', { x: 16, y: 120, width: 370, height: 40 }, 1, 2),
+    runnerNode(6, 'Button', 'Row below', { x: 16, y: 800, width: 370, height: 40 }, 1, 2),
+  ];
+}
+
+/**
+ * Reduced from a real Safari `snapshot -i --raw` capture (indices mirror the live tree): the page
+ * scroller `ScrollView` holds an `Other` → `WebView` → `WebView` chain, and the page's indicator is
+ * published under the inner `WebView`. A link sits below where the walk-derived band would land.
+ */
+function safariWebViewNodes(): RawSnapshotNode[] {
+  return [
+    runnerNode(0, 'Application', 'Safari', viewport),
+    runnerNode(1, 'ScrollView', 'iOS - Wikipedia', { x: 0, y: 0, width: 402, height: 874 }, 0, 1),
+    runnerNode(2, 'Other', undefined, { x: 0, y: 0, width: 402, height: 874 }, 1, 2),
+    runnerNode(3, 'WebView', undefined, { x: 0, y: 0, width: 402, height: 874 }, 2, 3),
+    runnerNode(4, 'WebView', undefined, { x: 0, y: 0, width: 402, height: 874 }, 3, 4),
+    {
+      ...runnerNode(
+        5,
+        'Other',
+        'Vertical scroll bar, 6 pages',
+        { x: 369, y: 62, width: 30, height: 750 },
+        4,
+        5,
+      ),
+      value: '0%',
+    },
+    runnerNode(6, 'Link', 'History', { x: 16, y: 820, width: 370, height: 28 }, 1, 2),
+  ];
+}
+
 function runnerNode(
   index: number,
   type: string,
diff --git a/packages/capture-kit/src/ios-snapshot-engine/scroll.ts b/packages/capture-kit/src/ios-snapshot-engine/scroll.ts
index 854d15f8b9..8d67e330ae 100644
--- a/packages/capture-kit/src/ios-snapshot-engine/scroll.ts
+++ b/packages/capture-kit/src/ios-snapshot-engine/scroll.ts
@@ -4,9 +4,7 @@ import {
   inferVerticalScrollIndicatorDirections,
   isSystemScrollIndicatorLabel,
 } from '@agent-device/kernel/scroll-indicator';
-import { normalizeType } from '@agent-device/contracts/snapshot';
 import {
-  findNearestAncestor,
   isScrollableSnapshotType,
   mergeReplacement,
   updateReplacement,
@@ -59,28 +57,44 @@ function collectIosScrollIndicatorNodePresentation(
 
 /**
  * The scroll container an indicator reports on. XCTest publishes a UIScrollView's indicators as
- * children of that view, so the nearest scroll-typed ancestor is normally the owner. A UITextView
- * is a UIScrollView too but publishes as `TextView`, and its indicators sit inside the text. When
- * such an indicator was treated as the surrounding list's, the list's viewport shrank to that one
- * line of text and every row after it was clipped away (a post thread whose root post is
- * selectable text lost all of its replies). An indicator whose nearest scrolling ancestor is a
- * text view belongs to that text view, which derives no viewport, so it resolves no container.
+ * children of that view, so the indicator's parent edge is the producer's own claim of ownership and
+ * a band derives only when that parent is itself a scroll type. Reading the parent rather than
+ * walking ancestors is what keeps a scroll-shaped host that publishes as a non-scroll type — a
+ * `UITextView` row (#2214, patched for that one type by #2740), a `WKWebView`, a map view, a paged
+ * cell — from misattributing its indicator to the enclosing list and clipping the list to one line of
+ * the host. An indicator whose parent is not a scroll type owns nothing (ADR 0026).
+ *
+ * A node that is itself a scroll type and carries an indicator label describes itself, not its
+ * parent, so it owns nothing too: banding its parent would clip a sibling list to the host's band —
+ * the same over-clip as #2214, mirrored upward.
  */
-function findScrollIndicatorContainer(
+function scrollIndicatorParent(
   node: RawSnapshotNode,
   byIndex: ReadonlyMap<number, RawSnapshotNode>,
-): RawSnapshotNode | null {
-  if (isScrollableSnapshotType(node.type)) return node;
-  const host = findNearestAncestor(
-    node,
-    byIndex,
-    (ancestor) => isScrollableSnapshotType(ancestor.type) || isTextViewType(ancestor.type),
-  );
-  return host && isScrollableSnapshotType(host.type) ? host : null;
+): RawSnapshotNode | undefined {
+  return typeof node.parentIndex === 'number' ? byIndex.get(node.parentIndex) : undefined;
+}
+
+function occupiesSameFrame(node: RawSnapshotNode, ancestor: RawSnapshotNode): boolean {
+  return node.rect != null && ancestor.rect != null && rectsEqual(node.rect, ancestor.rect);
 }
 
-function isTextViewType(type: string | undefined): boolean {
-  return normalizeType(type ?? '') === 'textview';
+// Ownership follows the parent edge, but a scroll region can be wrapped by transparent ancestors that
+// fill it exactly — Safari nests `Other` → `WebView` → `WebView` above a `WKWebView`'s `ScrollView`, all
+// one frame. The walk climbs only through such same-frame ancestors and stops at the first frame change,
+// so a host smaller than its list (a `WebView` row) is a separate region and owns nothing (ADR 0026).
+function findScrollIndicatorContainer(
+  node: RawSnapshotNode,
+  byIndex: ReadonlyMap<number, RawSnapshotNode>,
+): RawSnapshotNode | null {
+  if (isScrollableSnapshotType(node.type)) return null;
+  let current = scrollIndicatorParent(node, byIndex);
+  while (current && !isScrollableSnapshotType(current.type)) {
+    const parent = scrollIndicatorParent(current, byIndex);
+    if (!parent || !occupiesSameFrame(current, parent)) return null;
+    current = parent;
+  }
+  return current ?? null;
 }
 
 function clipDescendantsToDerivedScrollViewports(

From 0151b729f56991d9d8aba6f769cd59726583c030 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Tue, 22 Sep 2026 16:48:27 +0200
Subject: [PATCH 023/132] test(ios): enforce scroll-eligibility parity and
 settle ScrollArea for macOS (#2754 step 4) (#2759)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`REGULAR_ELIGIBLE_TYPES` (projection.ts) and `eligibleInteractiveTypes`
(SnapshotPresentationProjection.swift) are one fact in two languages: they keep
a scroll host alive through regular projection so the parent-edge ownership rule
can find it. No test referenced either list, so they could silently drift.

`eligibility-parity.test.ts` reads both literals from source, normalizes them
with the runtime's `normalizeType`, and fails on drift (verified by planting an
extra member). A production export was rejected in favor of source parsing so
the sets stay module-private.

The `scrollarea` asymmetry is settled for the macOS surface with a case rather
than by editing a set for iOS's sake: the desktop path
(snapshot-desktop-surface -> ios-snapshot-runtime -> publishIosSnapshot) reaches
these rules and its helper emits `ScrollArea`. A content-bearing `ScrollArea`
survives eligibility and owns its band under parent-edge ownership; a label-less
one is dropped and its indicator resolves no owner, which under-clips (safe)
instead of mis-clipping the enclosing list — strictly safer than the retired
ancestor walk. So the type stays out of both eligible sets, and the guard pins
that exclusion.

Co-authored-by: opencode <noreply@opencode.ai>
---
 .../SnapshotPresentationProjection.swift      |   2 +
 .../eligibility-parity.test.ts                | 215 ++++++++++++++++++
 .../src/ios-snapshot-engine/projection.ts     |   3 +
 3 files changed, 220 insertions(+)
 create mode 100644 packages/capture-kit/src/ios-snapshot-engine/eligibility-parity.test.ts

diff --git a/apple/snapshot-presentation/Sources/AgentDeviceSnapshotPresentation/SnapshotPresentationProjection.swift b/apple/snapshot-presentation/Sources/AgentDeviceSnapshotPresentation/SnapshotPresentationProjection.swift
index 3d1ccd8b53..644e0810bc 100644
--- a/apple/snapshot-presentation/Sources/AgentDeviceSnapshotPresentation/SnapshotPresentationProjection.swift
+++ b/apple/snapshot-presentation/Sources/AgentDeviceSnapshotPresentation/SnapshotPresentationProjection.swift
@@ -1,6 +1,8 @@
 import Foundation
 
 extension SnapshotPresentation {
+  // Kept in step with `REGULAR_ELIGIBLE_TYPES` in ios-snapshot-engine/projection.ts by
+  // eligibility-parity.test.ts. Excludes `scrollarea` (ADR 0026): the iOS runner never emits it.
   static let eligibleInteractiveTypes: Set<String> = [
     "Button",
     "Cell",
diff --git a/packages/capture-kit/src/ios-snapshot-engine/eligibility-parity.test.ts b/packages/capture-kit/src/ios-snapshot-engine/eligibility-parity.test.ts
new file mode 100644
index 0000000000..6fda0b4ad5
--- /dev/null
+++ b/packages/capture-kit/src/ios-snapshot-engine/eligibility-parity.test.ts
@@ -0,0 +1,215 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { test } from 'vitest';
+import { normalizeType } from '@agent-device/contracts/snapshot';
+import type {
+  IosSnapshotAcquisition,
+  IosSnapshotInput,
+} from '@agent-device/contracts/ios-snapshot';
+import {
+  createIosSnapshotRequest,
+  deriveIosCaptureHint,
+} from '@agent-device/capture-kit/ios-snapshot-planning';
+import type { RawSnapshotNode, Rect } from '@agent-device/kernel/snapshot';
+import { presentIosSnapshot } from './index.ts';
+
+// ADR 0026: `REGULAR_ELIGIBLE_TYPES` (TypeScript) and `eligibleInteractiveTypes` (Swift) are one
+// fact in two languages — the set that lets a scroll host survive regular projection so the
+// parent-edge ownership rule can find it. No runtime shares the two lists, so this guard reads both
+// literals from source and fails if they drift. Parsing source (rather than a production export)
+// keeps the sets private to their modules while still enforcing parity.
+
+const TYPESCRIPT_PROJECTION = path.join(import.meta.dirname, 'projection.ts');
+const SWIFT_PROJECTION = path.join(
+  import.meta.dirname,
+  '..',
+  '..',
+  '..',
+  '..',
+  'apple',
+  'snapshot-presentation',
+  'Sources',
+  'AgentDeviceSnapshotPresentation',
+  'SnapshotPresentationProjection.swift',
+);
+
+const SHARED_MEMBERS = [
+  'button',
+  'cell',
+  'collectionview',
+  'scrollview',
+  'table',
+  'textview',
+  'webview',
+] as const;
+
+const TYPESCRIPT_LITERAL = /const REGULAR_ELIGIBLE_TYPES = new Set\(\[([\s\S]*?)\]\)/;
+const SWIFT_LITERAL = /eligibleInteractiveTypes: Set<String> = \[([\s\S]*?)\]/;
+
+test('the two regular-eligibility lists are one fact in two languages', () => {
+  const typescript = normalizedEligible(readSource(TYPESCRIPT_PROJECTION), TYPESCRIPT_LITERAL);
+  const swift = normalizedEligible(readSource(SWIFT_PROJECTION), SWIFT_LITERAL);
+
+  // A regex that stopped matching would yield an empty set and pass by accident; pin non-emptiness
+  // and the scroll-host members that carry the ownership rule.
+  assert.ok(typescript.size >= SHARED_MEMBERS.length, 'TypeScript eligibility list parsed empty');
+  assert.ok(swift.size >= SHARED_MEMBERS.length, 'Swift eligibility list parsed empty');
+  for (const member of SHARED_MEMBERS) {
+    assert.ok(typescript.has(member), `TypeScript list missing ${member}`);
+    assert.ok(swift.has(member), `Swift list missing ${member}`);
+  }
+  assert.deepEqual(
+    [...typescript].sort(),
+    [...swift].sort(),
+    'REGULAR_ELIGIBLE_TYPES and eligibleInteractiveTypes diverged',
+  );
+
+  // Spelling discipline. Normalized equality alone hides a casing flip that breaks only one runtime,
+  // because each matches `node.type` differently: TypeScript normalizes before lookup
+  // (`projection.ts` `.has(normalizeType(node.type))`), so its members must already be normalized;
+  // Swift matches the raw producer spelling (`contains(node.type)`), so its members must stay in the
+  // un-normalized PascalCase the Apple producer emits. Without this, lowercasing the Swift literals
+  // would keep the normalized parity check green while silently dropping every macOS row.
+  for (const raw of rawEligible(readSource(TYPESCRIPT_PROJECTION), TYPESCRIPT_LITERAL)) {
+    assert.equal(raw, normalizeType(raw), `TypeScript literal "${raw}" is not in normalized form`);
+  }
+  for (const raw of rawEligible(readSource(SWIFT_PROJECTION), SWIFT_LITERAL)) {
+    assert.notEqual(
+      raw,
+      normalizeType(raw),
+      `Swift literal "${raw}" was normalized; Swift matches raw node.type`,
+    );
+  }
+});
+
+// `scrollarea` is accepted by `isScrollableSnapshotType` yet excluded from both eligible sets: the
+// iOS runner never emits it, and macOS desktop capture reaches these rules through the same engine.
+// The macOS surface is answered with a case below rather than by admitting the type for iOS's sake.
+test('the eligible sets deliberately exclude the macOS-only scrollarea type', () => {
+  const typescript = normalizedEligible(readSource(TYPESCRIPT_PROJECTION), TYPESCRIPT_LITERAL);
+  const swift = normalizedEligible(readSource(SWIFT_PROJECTION), SWIFT_LITERAL);
+  assert.equal(typescript.has('scrollarea'), false);
+  assert.equal(swift.has('scrollarea'), false);
+});
+
+// macOS desktop capture (snapshot-desktop-surface → ios-snapshot-runtime → publishIosSnapshot) uses
+// these rules and its helper emits `ScrollArea` from AXScrollArea. The decision: keep the type out
+// of the eligible sets. A `ScrollArea` that carries content survives eligibility and owns its band
+// under the parent-edge rule; a label-less one is dropped and its indicator resolves no owner, which
+// under-clips (safe) rather than mis-clipping the enclosing list — strictly safer than the retired
+// ancestor walk, which could re-attribute the re-parented indicator to an unrelated scroll host.
+test('a content-bearing ScrollArea scroll host owns its band on the shared engine', () => {
+  const viewport: Rect = { x: 0, y: 0, width: 320, height: 240 };
+  const result = presentInteractive([
+    node(0, 'Application', 'Finder', viewport),
+    node(1, 'ScrollArea', 'Documents', { x: 0, y: 40, width: 320, height: 200 }, 0),
+    node(
+      2,
+      'Other',
+      'Vertical scroll bar, 3 pages',
+      { x: 306, y: 40, width: 10, height: 150 },
+      1,
+      '0%',
+    ),
+    node(3, 'Button', 'Row above', { x: 16, y: -40, width: 288, height: 28 }, 1),
+    node(4, 'Button', 'Row visible', { x: 16, y: 60, width: 288, height: 28 }, 1),
+    node(5, 'Button', 'Row below', { x: 16, y: 200, width: 288, height: 28 }, 1),
+  ]);
+  const scrollArea = result.nodes.find((entry) => entry.type === 'ScrollArea');
+  const labels = result.nodes.map((entry) => entry.label);
+
+  assert.ok(scrollArea, 'a content-bearing ScrollArea must survive regular projection');
+  assert.deepEqual(scrollArea?.rect, { x: 0, y: 40, width: 320, height: 150 });
+  assert.equal(scrollArea?.hiddenContentBelow, true);
+  assert.deepEqual(
+    labels.filter((label) => label?.startsWith('Row ')),
+    ['Row visible'],
+  );
+});
+
+// Decision pin from the other side of the same rule. Because `scrollarea` is excluded from both
+// eligible sets, a label-less ScrollArea carries no semantic content to survive on and is dropped
+// from regular projection — the type simply does not appear, whichever producer reaches the engine.
+// Admitting `scrollarea` would make it survive as a node, failing the absence assertion below. (The
+// dropped host's own indicator still bands the tree it leaves behind; that band is a separate concern
+// from eligibility, so this case only pins the survival decision.)
+test('a label-less ScrollArea does not survive regular projection', () => {
+  const viewport: Rect = { x: 0, y: 0, width: 320, height: 240 };
+  const result = presentInteractive([
+    node(0, 'Application', 'Finder', viewport),
+    node(1, 'ScrollArea', undefined, { x: 0, y: 40, width: 320, height: 200 }, 0),
+    node(
+      2,
+      'Other',
+      'Vertical scroll bar, 3 pages',
+      { x: 306, y: 40, width: 10, height: 150 },
+      1,
+      '0%',
+    ),
+    node(3, 'Button', 'Row above', { x: 16, y: -40, width: 288, height: 28 }, 1),
+    node(4, 'Button', 'Row visible', { x: 16, y: 60, width: 288, height: 28 }, 1),
+    node(5, 'Button', 'Row below', { x: 16, y: 200, width: 288, height: 28 }, 1),
+  ]);
+
+  assert.equal(
+    result.nodes.find((entry) => entry.type === 'ScrollArea'),
+    undefined,
+    'a label-less ScrollArea must not survive regular projection',
+  );
+});
+
+function readSource(file: string): string {
+  return fs.readFileSync(file, 'utf8');
+}
+
+function normalizedEligible(source: string, literal: RegExp): Set<string> {
+  return new Set(rawEligible(source, literal).map((member) => normalizeType(member)));
+}
+
+function rawEligible(source: string, literal: RegExp): string[] {
+  const body = source.match(literal)?.[1];
+  assert.ok(body, 'eligibility list literal not found — did it get renamed?');
+  return [...body.matchAll(/["']([^"']+)["']/g)].map((match) => match[1]!);
+}
+
+function presentInteractive(nodes: RawSnapshotNode[]) {
+  const request = createIosSnapshotRequest({
+    projection: 'regular',
+    interactiveOnly: true,
+    acquisitionIntent: 'full',
+  });
+  const acquisition: IosSnapshotAcquisition = {
+    producer: 'simulator-ax-bridge',
+    intent: 'full',
+    hint: { ...deriveIosCaptureHint(request), acquisitionIntent: 'full' },
+    nodes,
+    truncated: false,
+    viewport: { kind: 'reported', rect: { x: 0, y: 0, width: 320, height: 240 } },
+    lineage: { targetId: 'parity-target', generation: 'parity-generation' },
+    residue: [],
+  };
+  const input: IosSnapshotInput = { stage: 'acquired', acquisition };
+  return presentIosSnapshot(input, request);
+}
+
+function node(
+  index: number,
+  type: string,
+  label: string | undefined,
+  rect: Rect,
+  parentIndex?: number,
+  value?: string,
+): RawSnapshotNode {
+  return {
+    index,
+    type,
+    ...(label ? { label } : {}),
+    ...(value ? { value } : {}),
+    rect,
+    enabled: true,
+    hittable: true,
+    depth: parentIndex === undefined ? 0 : 1,
+    ...(parentIndex === undefined ? {} : { parentIndex }),
+  };
+}
diff --git a/packages/capture-kit/src/ios-snapshot-engine/projection.ts b/packages/capture-kit/src/ios-snapshot-engine/projection.ts
index 1eea69c80b..863a081afd 100644
--- a/packages/capture-kit/src/ios-snapshot-engine/projection.ts
+++ b/packages/capture-kit/src/ios-snapshot-engine/projection.ts
@@ -2,6 +2,9 @@ import type { RawSnapshotNode } from '@agent-device/kernel/snapshot';
 import { normalizeType } from '@agent-device/contracts/snapshot';
 import type { IosSnapshotFoldPolicy, IosSnapshotPresentationNode } from './types.ts';
 
+// Kept in step with `eligibleInteractiveTypes` in SnapshotPresentationProjection.swift by
+// ios-snapshot-engine/eligibility-parity.test.ts. Excludes `scrollarea`, which `isScrollableSnapshotType`
+// accepts but the iOS runner never emits (ADR 0026; macOS decision recorded in that test).
 const REGULAR_ELIGIBLE_TYPES = new Set([
   'button',
   'cell',

From fde74ac4c689aecf2dca14bd686af9de46a9497f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Tue, 22 Sep 2026 16:50:04 +0200
Subject: [PATCH 024/132] 0.21.11

---
 package.json | 2 +-
 server.json  | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/package.json b/package.json
index 279e5413fb..71decd72c9 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "agent-device",
-  "version": "0.21.10",
+  "version": "0.21.11",
   "description": "Mobile app automation and verification for AI coding agents. CLI, MCP server, and typed Node.js API for iOS, Android, HarmonyOS, TV, web, macOS, and Linux.",
   "mcpName": "io.github.callstack/agent-device",
   "license": "MIT",
diff --git a/server.json b/server.json
index 6ef73a44c6..f23a9b184a 100644
--- a/server.json
+++ b/server.json
@@ -7,12 +7,12 @@
     "url": "https://github.com/callstack/agent-device",
     "source": "github"
   },
-  "version": "0.21.10",
+  "version": "0.21.11",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "agent-device",
-      "version": "0.21.10",
+      "version": "0.21.11",
       "transport": {
         "type": "stdio"
       },

From ff678bb093f917e7b9dbc6c3c89b31e220d56ba8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Tue, 22 Sep 2026 20:44:57 +0200
Subject: [PATCH 025/132] feat(ios): replace Device Hub folding with simulator
 HID (#2762)

---
 apple/fold-helper/Fold.m                      |  43 ++++
 apple/macos-helper/Package.swift              |   9 +-
 .../DeviceHubPose.swift                       |  47 ----
 .../DeviceHubWindowInventory.swift            |  65 -----
 .../DeviceHubPose.swift                       | 225 ------------------
 .../DeviceHubSidebar.swift                    |  57 -----
 .../DeviceHubWindowDiscovery.swift            | 108 ---------
 .../Sources/AgentDeviceMacOSHelper/main.swift |   2 -
 .../DeviceHubPoseTests.swift                  |  30 ---
 .../DeviceHubWindowInventoryTests.swift       |  65 -----
 docs/adr/0025-foldable-apple-panels.md        |  20 +-
 docs/agents/device-verification.md            |  15 +-
 package.json                                  |   1 +
 .../platform-apple/src/foldable/pose.test.ts  |  44 +---
 packages/platform-apple/src/foldable/pose.ts  |  54 +----
 .../src/foldable/simulator-hid.test.ts        |  47 ++++
 .../src/foldable/simulator-hid.ts             |  65 +++++
 .../src/os/macos/helper.test.ts               |  48 +---
 .../platform-apple/src/os/macos/helper.ts     |  35 ---
 src/commands/schema/cli-help.ts               |   4 +-
 src/commands/system/index.ts                  |   6 +-
 website/docs/docs/commands.md                 |   5 +-
 22 files changed, 216 insertions(+), 779 deletions(-)
 create mode 100644 apple/fold-helper/Fold.m
 delete mode 100644 apple/macos-helper/Sources/AgentDeviceMacOSDeviceHub/DeviceHubPose.swift
 delete mode 100644 apple/macos-helper/Sources/AgentDeviceMacOSDeviceHub/DeviceHubWindowInventory.swift
 delete mode 100644 apple/macos-helper/Sources/AgentDeviceMacOSHelper/DeviceHubPose.swift
 delete mode 100644 apple/macos-helper/Sources/AgentDeviceMacOSHelper/DeviceHubSidebar.swift
 delete mode 100644 apple/macos-helper/Sources/AgentDeviceMacOSHelper/DeviceHubWindowDiscovery.swift
 delete mode 100644 apple/macos-helper/Tests/AgentDeviceMacOSDeviceHubTests/DeviceHubPoseTests.swift
 delete mode 100644 apple/macos-helper/Tests/AgentDeviceMacOSDeviceHubTests/DeviceHubWindowInventoryTests.swift
 create mode 100644 packages/platform-apple/src/foldable/simulator-hid.test.ts
 create mode 100644 packages/platform-apple/src/foldable/simulator-hid.ts

diff --git a/apple/fold-helper/Fold.m b/apple/fold-helper/Fold.m
new file mode 100644
index 0000000000..64601b3094
--- /dev/null
+++ b/apple/fold-helper/Fold.m
@@ -0,0 +1,43 @@
+#import <Foundation/Foundation.h>
+#import <mach/mach_time.h>
+
+// Private simulator HID entry points; the host verifies the resulting hinge independently.
+extern CFDataRef IOCFSerialize(CFTypeRef object, CFOptionFlags options);
+extern CFTypeRef IOHIDEventCreateVendorDefinedEvent(CFAllocatorRef allocator, uint64_t timestamp,
+    uint32_t usagePage, uint32_t usage, uint32_t version, const uint8_t *data,
+    CFIndex length, uint32_t options);
+extern CFTypeRef IOHIDEventSystemClientCreate(CFAllocatorRef allocator);
+extern void IOHIDEventSystemClientDispatchEvent(CFTypeRef client, CFTypeRef event);
+
+int main(int argc, const char *argv[]) {
+  @autoreleasepool {
+    if (argc != 2) return 2;
+    NSDictionary *angles = @{@"closed": @0, @"half-open": @130, @"open": @180};
+    NSNumber *angle = angles[@(argv[1])];
+    if (!angle) {
+      fprintf(stderr, "Expected closed, half-open, or open\n");
+      return 2;
+    }
+    NSDictionary *payload = @{
+      @"provider": @"com.apple.Virtualization.VirtualMachines",
+      @"source": @"hinge-slider-control",
+      @"type": @"range",
+      @"value": angle,
+    };
+    CFDataRef data = IOCFSerialize((__bridge CFTypeRef)payload, 1);
+    if (!data) {
+      fprintf(stderr, "Unable to serialize simulator hinge payload\n");
+      return 1;
+    }
+    CFTypeRef client = IOHIDEventSystemClientCreate(kCFAllocatorDefault);
+    CFTypeRef event = IOHIDEventCreateVendorDefinedEvent(kCFAllocatorDefault,
+        mach_absolute_time(), 0xff61, 0x5b, 0, CFDataGetBytePtr(data), CFDataGetLength(data), 0);
+    if (client && event) IOHIDEventSystemClientDispatchEvent(client, event);
+    BOOL dispatched = client && event;
+    if (event) CFRelease(event);
+    if (client) CFRelease(client);
+    CFRelease(data);
+    if (!dispatched) fprintf(stderr, "Unable to create simulator HID client or event\n");
+    return dispatched ? 0 : 1;
+  }
+}
diff --git a/apple/macos-helper/Package.swift b/apple/macos-helper/Package.swift
index a287ecdb48..3a472a3ca2 100644
--- a/apple/macos-helper/Package.swift
+++ b/apple/macos-helper/Package.swift
@@ -14,20 +14,13 @@ let package = Package(
     .target(
       name: "AgentDeviceMacOSInput"
     ),
-    .target(
-      name: "AgentDeviceMacOSDeviceHub"
-    ),
     .executableTarget(
       name: "AgentDeviceMacOSHelper",
-      dependencies: ["AgentDeviceMacOSInput", "AgentDeviceMacOSDeviceHub"]
+      dependencies: ["AgentDeviceMacOSInput"]
     ),
     .testTarget(
       name: "AgentDeviceMacOSInputTests",
       dependencies: ["AgentDeviceMacOSInput"]
     ),
-    .testTarget(
-      name: "AgentDeviceMacOSDeviceHubTests",
-      dependencies: ["AgentDeviceMacOSDeviceHub"]
-    ),
   ]
 )
diff --git a/apple/macos-helper/Sources/AgentDeviceMacOSDeviceHub/DeviceHubPose.swift b/apple/macos-helper/Sources/AgentDeviceMacOSDeviceHub/DeviceHubPose.swift
deleted file mode 100644
index 0cde6aa94f..0000000000
--- a/apple/macos-helper/Sources/AgentDeviceMacOSDeviceHub/DeviceHubPose.swift
+++ /dev/null
@@ -1,47 +0,0 @@
-import Foundation
-
-/// The decisions the Device Hub pose press makes without a window server: which control a pose
-/// names, which window belongs to a device, and which sidebar row identifies it. They live apart
-/// from the helper executable so the tests can exercise them without an accessibility session.
-
-/// Device Hub's three pose presets for a foldable simulator, named as the helper's `--pose`
-/// argument spells them. Each maps to the accessibility description of its action-bar button.
-public enum DeviceHubPose: String, CaseIterable, Sendable {
-  case closed
-  case book
-  case open
-
-  public init?(argument: String) {
-    self.init(rawValue: argument.lowercased())
-  }
-
-  /// The `AXDescription` Device Hub gives the button for this pose.
-  public var controlDescription: String {
-    switch self {
-    case .closed: return "Closed"
-    case .book: return "Book"
-    case .open: return "Open"
-    }
-  }
-}
-
-/// Device Hub is launched through a trampoline, so LaunchServices registers it with no process
-/// identifier; the process table is matched on the executable path instead.
-public let deviceHubExecutableSuffix = "/DeviceHub.app/Contents/MacOS/DeviceHub"
-
-/// The separator Device Hub puts between the device name and the OS in a window title.
-public let deviceHubWindowTitleSeparator = " – "
-
-/// Device Hub titles a device window `<device name> – <OS> <version>`, so a window shows the
-/// device when its title is the name or the name followed by that exact separator. A bare
-/// space would also match a simulator whose name merely extends this one ("iPhone Duo Lab").
-public func deviceHubWindowShows(deviceName: String, title: String?) -> Bool {
-  guard let title else { return false }
-  return title == deviceName || title.hasPrefix(deviceName + deviceHubWindowTitleSeparator)
-}
-
-/// The accessibility identifier of the sidebar row for one simulator. The UDID is the one device
-/// identity Device Hub exposes that two simulators sharing a name cannot confuse.
-public func deviceHubDeviceRowIdentifier(udid: String) -> String {
-  return "TableRow.Device.\(udid)"
-}
diff --git a/apple/macos-helper/Sources/AgentDeviceMacOSDeviceHub/DeviceHubWindowInventory.swift b/apple/macos-helper/Sources/AgentDeviceMacOSDeviceHub/DeviceHubWindowInventory.swift
deleted file mode 100644
index 066c86f340..0000000000
--- a/apple/macos-helper/Sources/AgentDeviceMacOSDeviceHub/DeviceHubWindowInventory.swift
+++ /dev/null
@@ -1,65 +0,0 @@
-import ApplicationServices
-
-package enum DeviceHubWindowRead {
-  case available([AXUIElement])
-  case failed(Int32)
-}
-
-package struct DeviceHubWindowCandidate {
-  package let processID: Int32
-  package let window: AXUIElement
-}
-
-package enum DeviceHubRowLookup {
-  case identified(AXUIElement, restoreSidebar: Bool)
-  case sidebarUnavailable
-  case unconfirmed
-  case timedOut
-
-  package var diagnostic: String {
-    switch self {
-    case .identified: return "identified"
-    case .sidebarUnavailable: return "sidebar-unavailable"
-    case .unconfirmed: return "row-unconfirmed"
-    case .timedOut: return "timed-out"
-    }
-  }
-}
-
-package struct DeviceHubWindowInventory {
-  package private(set) var candidates: [DeviceHubWindowCandidate] = []
-  package private(set) var emptyProcessIDs: [Int32] = []
-  package private(set) var failures: [Int32: Int32] = [:]
-  package private(set) var candidateOutcomes: [String] = []
-  package private(set) var budgetExpired = false
-
-  package init() {}
-
-  package mutating func record(processID: Int32, read: DeviceHubWindowRead) {
-    switch read {
-    case .available(let windows):
-      if windows.isEmpty { emptyProcessIDs.append(processID) }
-      candidates.append(contentsOf: windows.map { DeviceHubWindowCandidate(processID: processID, window: $0) })
-    case .failed(let status):
-      failures[processID] = status
-    }
-  }
-
-  package mutating func record(candidate: Int, outcome: DeviceHubRowLookup) {
-    candidateOutcomes.append("\(candidates[candidate].processID):\(candidate):\(outcome.diagnostic)")
-  }
-
-  package mutating func expireBudget() { budgetExpired = true }
-
-  package func processesToReopen(attempted: Set<Int32>) -> [Int32] {
-    budgetExpired ? [] : emptyProcessIDs.filter { !attempted.contains($0) }
-  }
-
-  package func failureReason(reopenFailures: [Int32: String] = [:]) -> String {
-    if !failures.isEmpty { return "device-hub-window-read-failed" }
-    if budgetExpired { return "device-hub-discovery-timeout" }
-    if !candidates.isEmpty { return "device-hub-identity-unconfirmed" }
-    if let reason = reopenFailures.sorted(by: { $0.key < $1.key }).first?.value { return reason }
-    return "device-hub-window-missing"
-  }
-}
diff --git a/apple/macos-helper/Sources/AgentDeviceMacOSHelper/DeviceHubPose.swift b/apple/macos-helper/Sources/AgentDeviceMacOSHelper/DeviceHubPose.swift
deleted file mode 100644
index 05a6cce6e7..0000000000
--- a/apple/macos-helper/Sources/AgentDeviceMacOSHelper/DeviceHubPose.swift
+++ /dev/null
@@ -1,225 +0,0 @@
-import AgentDeviceMacOSDeviceHub
-import AppKit
-import ApplicationServices
-import Darwin
-import Foundation
-
-/// How long sidebar selection and pose-control discovery may each wait before refusing a press.
-private let deviceHubSettleDeadline: TimeInterval = 8
-private let deviceHubPoll: TimeInterval = 0.25
-
-struct DeviceHubPoseResponse: Encodable {
-  let pose: String
-  let control: String
-  let windowTitle: String
-  /** Whether Device Hub had to be asked to reopen a window before the device could be selected. */
-  let reopened: Bool
-  /** Whether the window was switched to the device through its sidebar row. */
-  let selected: Bool
-}
-
-func handleDeviceHub(arguments: [String]) throws -> any Encodable {
-  guard arguments.first == "pose" else {
-    throw HelperError.invalidArgs("device-hub requires pose")
-  }
-  let rest = Array(arguments.dropFirst())
-  guard let udid = helperOptionValue(arguments: rest, name: "--udid")?
-    .trimmingCharacters(in: .whitespacesAndNewlines),
-    !udid.isEmpty
-  else {
-    throw HelperError.invalidArgs("device-hub pose requires --udid <udid>")
-  }
-  guard let deviceName = helperOptionValue(arguments: rest, name: "--device-name")?
-    .trimmingCharacters(in: .whitespacesAndNewlines),
-    !deviceName.isEmpty
-  else {
-    throw HelperError.invalidArgs("device-hub pose requires --device-name <name>")
-  }
-  guard let pose = helperOptionValue(arguments: rest, name: "--pose").flatMap(DeviceHubPose.init(argument:))
-  else {
-    throw HelperError.invalidArgs("device-hub pose requires --pose <closed|book|open>")
-  }
-  let control = pose.controlDescription
-  guard AXIsProcessTrusted() else {
-    throw HelperError.commandFailed(
-      "fold needs Accessibility permission to press the Device Hub pose control",
-      details: ["reason": "accessibility-permission", "permission": "accessibility"]
-    )
-  }
-  let discovery = try discoverDeviceHubWindow(udid: udid, deviceName: deviceName)
-  let window = discovery.window
-  defer {
-    if discovery.revealedSidebar {
-      _ = setDeviceHubSidebar(visible: false, window: window,
-        deadline: ProcessInfo.processInfo.systemUptime + 0.5)
-    }
-  }
-  let selected = try selectDevice(row: discovery.row, deviceName: deviceName, in: window)
-  let windowTitle = stringAttribute(window, attribute: kAXTitleAttribute as String) ?? ""
-  guard let button = awaitPoseButton(in: window, description: control) else {
-    throw HelperError.commandFailed(
-      "Device Hub shows no \(control) pose control for \(deviceName)",
-      details: [
-        "reason": "device-hub-pose-control-missing",
-        "windowTitle": windowTitle,
-        "control": control,
-      ]
-    )
-  }
-  let status = AXUIElementPerformAction(button, kAXPressAction as CFString)
-  guard status == .success else {
-    throw HelperError.commandFailed(
-      "Device Hub refused the \(control) pose press",
-      details: ["reason": "device-hub-press-failed", "status": "\(status.rawValue)"]
-    )
-  }
-  return SuccessEnvelope(
-    data: DeviceHubPoseResponse(
-      pose: pose.rawValue,
-      control: control,
-      windowTitle: windowTitle,
-      reopened: discovery.reopened,
-      selected: selected
-    )
-  )
-}
-
-private func windowShows(deviceName: String, _ window: AXUIElement) -> Bool {
-  return deviceHubWindowShows(
-    deviceName: deviceName,
-    title: stringAttribute(window, attribute: kAXTitleAttribute as String)
-  )
-}
-
-/// `kAEReopenApplication` is what the Dock sends when an app with no open windows is clicked, and
-/// it is the one event Device Hub answers by restoring the device window. Sent to the process
-/// directly, because LaunchServices cannot address a trampolined app by bundle identifier.
-func sendDeviceHubReopenEvent(to pid: pid_t, timeout: TimeInterval) throws {
-  let target = NSAppleEventDescriptor(processIdentifier: pid)
-  let event = NSAppleEventDescriptor(
-    eventClass: AEEventClass(kCoreEventClass),
-    eventID: AEEventID(kAEReopenApplication),
-    targetDescriptor: target,
-    returnID: AEReturnID(kAutoGenerateReturnID),
-    transactionID: AETransactionID(kAnyTransactionID)
-  )
-  do {
-    _ = try event.sendEvent(options: [.noReply], timeout: min(5, max(0.001, timeout)))
-  } catch {
-    let code = (error as NSError).code
-    throw HelperError.commandFailed(
-      "fold could not ask Device Hub to reopen its device window",
-      details: [
-        "reason": code == -1743 ? "automation-permission" : "device-hub-reopen-failed",
-        "error": String(describing: error),
-      ]
-    )
-  }
-}
-
-/// Switches the window to the device through its sidebar row, whose accessibility identifier is
-/// `TableRow.Device.<udid>` — the one place Device Hub exposes a device identity that two
-/// simulators sharing a name cannot confuse. A window already titled with the device still gets
-/// the selection, because the title alone cannot tell such twins apart.
-private func selectDevice(
-  row: AXUIElement,
-  deviceName: String,
-  in window: AXUIElement
-) throws -> Bool {
-  let deadline = ProcessInfo.processInfo.systemUptime + deviceHubSettleDeadline
-  AXUIElementSetMessagingTimeout(row, 0.25)
-  AXUIElementSetMessagingTimeout(window, 0.25)
-  let status = AXUIElementSetAttributeValue(row, kAXSelectedAttribute as CFString, kCFBooleanTrue)
-  guard status == .success || status == .cannotComplete else {
-    throw HelperError.commandFailed(
-      "Device Hub refused to select \(deviceName) in its sidebar",
-      details: ["reason": "device-hub-select-failed", "status": "\(status.rawValue)"]
-    )
-  }
-  while ProcessInfo.processInfo.systemUptime < deadline {
-    var selected: CFTypeRef?
-    if AXUIElementCopyAttributeValue(row, kAXSelectedAttribute as CFString, &selected) == .success,
-      (selected as? Bool) == true, windowShows(deviceName: deviceName, window) { return true }
-    Thread.sleep(forTimeInterval: deviceHubPoll)
-  }
-  throw HelperError.commandFailed(
-    "Device Hub did not confirm selection of \(deviceName)",
-    details: ["reason": "device-hub-select-unconfirmed", "status": "\(status.rawValue)"]
-  )
-}
-
-func deviceHubDeviceRow(udid: String, in window: AXUIElement, deadline: TimeInterval) -> AXUIElement? {
-  guard let label = findDeviceHubElement(root: window, depth: 0, deadline: deadline, where: {
-    stringAttribute($0, attribute: "AXIdentifier") == deviceHubDeviceRowIdentifier(udid: udid)
-  }) else {
-    return nil
-  }
-  var current: AXUIElement? = label
-  while let element = current, ProcessInfo.processInfo.systemUptime < deadline {
-    AXUIElementSetMessagingTimeout(element, Float(max(0.001, min(0.25, deadline - ProcessInfo.processInfo.systemUptime))))
-    if stringAttribute(element, attribute: kAXRoleAttribute as String) == "AXRow" {
-      return element
-    }
-    current = elementAttribute(element, attribute: kAXParentAttribute as String)
-  }
-  return nil
-}
-
-/// The action bar is rebuilt for the device the window shows, so right after a sidebar selection
-/// the window already carries the new title while the pose controls are still being laid out.
-/// The controls are therefore awaited, not looked up once.
-private func awaitPoseButton(in window: AXUIElement, description: String) -> AXUIElement? {
-  let deadline = ProcessInfo.processInfo.systemUptime + deviceHubSettleDeadline
-  while true {
-    if let button = poseButton(in: window, description: description, deadline: deadline) {
-      return button
-    }
-    guard ProcessInfo.processInfo.systemUptime < deadline else { return nil }
-    Thread.sleep(forTimeInterval: deviceHubPoll)
-  }
-}
-
-/// The pose controls sit in the window's action bar as `AXButton`s described by their preset
-/// name; the simulated screen inside the same window is an iOS content group whose own buttons
-/// carry app labels, never these three.
-private func poseButton(in window: AXUIElement, description: String, deadline: TimeInterval) -> AXUIElement? {
-  return findDeviceHubElement(root: window, depth: 0, deadline: deadline) {
-    stringAttribute($0, attribute: kAXRoleAttribute as String) == "AXButton"
-      && stringAttribute($0, attribute: kAXDescriptionAttribute as String) == description
-  }
-}
-
-func findDeviceHubElement(
-  root: AXUIElement,
-  depth: Int,
-  deadline: TimeInterval,
-  where matches: (AXUIElement) -> Bool
-) -> AXUIElement? {
-  let remaining = deadline - ProcessInfo.processInfo.systemUptime
-  if depth > 14 || remaining <= 0 {
-    return nil
-  }
-  AXUIElementSetMessagingTimeout(root, Float(min(0.25, remaining)))
-  for child in children(of: root) {
-    let remaining = deadline - ProcessInfo.processInfo.systemUptime
-    guard remaining > 0 else { return nil }
-    AXUIElementSetMessagingTimeout(child, Float(min(0.25, remaining)))
-    if matches(child) {
-      return child
-    }
-    if stringAttribute(child, attribute: kAXSubroleAttribute as String) == "iOSContentGroup" {
-      continue
-    }
-    if let nested = findDeviceHubElement(root: child, depth: depth + 1, deadline: deadline, where: matches) {
-      return nested
-    }
-  }
-  return nil
-}
-
-func helperOptionValue(arguments: [String], name: String) -> String? {
-  guard let index = arguments.firstIndex(of: name), arguments.indices.contains(index + 1) else {
-    return nil
-  }
-  return arguments[index + 1]
-}
diff --git a/apple/macos-helper/Sources/AgentDeviceMacOSHelper/DeviceHubSidebar.swift b/apple/macos-helper/Sources/AgentDeviceMacOSHelper/DeviceHubSidebar.swift
deleted file mode 100644
index efebba26ea..0000000000
--- a/apple/macos-helper/Sources/AgentDeviceMacOSHelper/DeviceHubSidebar.swift
+++ /dev/null
@@ -1,57 +0,0 @@
-import AgentDeviceMacOSDeviceHub
-import ApplicationServices
-import Foundation
-
-func identifyDeviceHubRow(
-  udid: String,
-  candidate: DeviceHubWindowCandidate,
-  deadline: TimeInterval
-) -> DeviceHubRowLookup {
-  let now = ProcessInfo.processInfo.systemUptime
-  let visibleRowDeadline = now + max(0, deadline - now) / 3
-  if let row = deviceHubDeviceRow(udid: udid, in: candidate.window, deadline: visibleRowDeadline) {
-    return .identified(row, restoreSidebar: false)
-  }
-  let searchDeadline = deadline - 0.25
-  guard let button = deviceHubSidebarButton(visible: true, window: candidate.window, deadline: searchDeadline) else {
-    return ProcessInfo.processInfo.systemUptime >= searchDeadline ? .timedOut : .sidebarUnavailable
-  }
-  var transferCleanup = false
-  defer {
-    if !transferCleanup {
-      _ = setDeviceHubSidebar(visible: false, window: candidate.window, deadline: deadline)
-    }
-  }
-  let status = pressDeviceHubSidebarButton(button, deadline: searchDeadline)
-  guard status == .success || status == .cannotComplete else { return .unconfirmed }
-  repeat {
-    if let row = deviceHubDeviceRow(udid: udid, in: candidate.window, deadline: searchDeadline) {
-      transferCleanup = true
-      return .identified(row, restoreSidebar: true)
-    }
-    let remaining = searchDeadline - ProcessInfo.processInfo.systemUptime
-    if remaining <= 0 { return .timedOut }
-    Thread.sleep(forTimeInterval: min(0.05, remaining))
-  } while ProcessInfo.processInfo.systemUptime < searchDeadline
-  return .timedOut
-}
-
-func setDeviceHubSidebar(visible: Bool, window: AXUIElement, deadline: TimeInterval) -> Bool {
-  guard let button = deviceHubSidebarButton(visible: visible, window: window, deadline: deadline) else { return false }
-  return pressDeviceHubSidebarButton(button, deadline: deadline) == .success
-}
-
-private func deviceHubSidebarButton(visible: Bool, window: AXUIElement, deadline: TimeInterval) -> AXUIElement? {
-  let description = visible ? "Show Sidebar" : "Hide Sidebar"
-  return findDeviceHubElement(root: window, depth: 0, deadline: deadline) {
-    stringAttribute($0, attribute: kAXRoleAttribute as String) == "AXButton"
-      && stringAttribute($0, attribute: kAXDescriptionAttribute as String) == description
-  }
-}
-
-private func pressDeviceHubSidebarButton(_ button: AXUIElement, deadline: TimeInterval) -> AXError {
-  let remaining = deadline - ProcessInfo.processInfo.systemUptime
-  guard remaining > 0 else { return .cannotComplete }
-  AXUIElementSetMessagingTimeout(button, Float(min(0.1, remaining)))
-  return AXUIElementPerformAction(button, kAXPressAction as CFString)
-}
diff --git a/apple/macos-helper/Sources/AgentDeviceMacOSHelper/DeviceHubWindowDiscovery.swift b/apple/macos-helper/Sources/AgentDeviceMacOSHelper/DeviceHubWindowDiscovery.swift
deleted file mode 100644
index efc125c6da..0000000000
--- a/apple/macos-helper/Sources/AgentDeviceMacOSHelper/DeviceHubWindowDiscovery.swift
+++ /dev/null
@@ -1,108 +0,0 @@
-import AgentDeviceMacOSDeviceHub
-import AppKit
-import ApplicationServices
-import Darwin
-
-struct DiscoveredDeviceHubWindow {
-  let window: AXUIElement
-  let reopened: Bool
-  let row: AXUIElement
-  let revealedSidebar: Bool
-}
-
-func discoverDeviceHubWindow(udid: String, deviceName: String) throws -> DiscoveredDeviceHubWindow {
-  let deadline = ProcessInfo.processInfo.systemUptime + 8
-  var reopened = Set<pid_t>()
-  var reopenFailures: [pid_t: String] = [:]
-  var inventory = DeviceHubWindowInventory()
-  var processIDs: [pid_t] = []
-  repeat {
-    processIDs = deviceHubProcessIdentifiers()
-    if processIDs.isEmpty {
-      throw HelperError.commandFailed(
-        "Xcode Device Hub is not running",
-        details: ["reason": "device-hub-not-running", "bundleId": "com.apple.dt.Devices"]
-      )
-    }
-    inventory = DeviceHubWindowInventory()
-    for pid in processIDs {
-      let remaining = deadline - ProcessInfo.processInfo.systemUptime
-      guard remaining > 0 else { inventory.expireBudget(); break }
-      let app = AXUIElementCreateApplication(pid)
-      AXUIElementSetMessagingTimeout(app, Float(min(0.5, remaining)))
-      var value: CFTypeRef?
-      let status = AXUIElementCopyAttributeValue(app, kAXWindowsAttribute as CFString, &value)
-      if status == .success, let windows = value as? [AXUIElement] {
-        for window in windows { AXUIElementSetMessagingTimeout(window, 0.5) }
-        inventory.record(processID: pid, read: .available(windows))
-      } else {
-        inventory.record(processID: pid, read: .failed(
-          status == .success ? AXError.illegalArgument.rawValue : status.rawValue
-        ))
-      }
-    }
-    for (index, candidate) in inventory.candidates.enumerated() {
-      let now = ProcessInfo.processInfo.systemUptime
-      guard now < deadline else { inventory.expireBudget(); break }
-      let candidateDeadline = now + (deadline - now) / Double(inventory.candidates.count - index) / 2
-      let outcome = identifyDeviceHubRow(udid: udid, candidate: candidate, deadline: candidateDeadline)
-      inventory.record(candidate: index, outcome: outcome)
-      if case .identified(let row, let restoreSidebar) = outcome {
-        return DiscoveredDeviceHubWindow(window: candidate.window,
-          reopened: reopened.contains(candidate.processID), row: row, revealedSidebar: restoreSidebar)
-      }
-    }
-    let attempted = reopened.union(reopenFailures.keys)
-    for pid in inventory.processesToReopen(attempted: attempted) {
-      guard ProcessInfo.processInfo.systemUptime < deadline else { inventory.expireBudget(); break }
-      do {
-        try sendDeviceHubReopenEvent(to: pid, timeout: deadline - ProcessInfo.processInfo.systemUptime)
-        reopened.insert(pid)
-      } catch let error as HelperError {
-        guard case .commandFailed(_, let details) = error else { throw error }
-        reopenFailures[pid] = details["reason"] ?? "device-hub-reopen-failed"
-      }
-    }
-    let remaining = deadline - ProcessInfo.processInfo.systemUptime
-    if remaining <= 0 { inventory.expireBudget(); break }
-    Thread.sleep(forTimeInterval: min(0.25, remaining))
-  } while ProcessInfo.processInfo.systemUptime < deadline
-
-  let statuses = inventory.failures.sorted { $0.key < $1.key }
-    .map { "\($0.key):\($0.value)" }.joined(separator: ",")
-  throw HelperError.commandFailed(
-    "Could not confirm a Device Hub window for the requested device",
-    details: [
-      "reason": inventory.failureReason(reopenFailures: reopenFailures),
-      "reopenFailures": reopenFailures.sorted { $0.key < $1.key }.map { "\($0.key):\($0.value)" }.joined(separator: ","),
-      "candidateOutcomes": inventory.candidateOutcomes.joined(separator: ","),
-      "udid": udid,
-      "deviceName": deviceName,
-      "processIDs": processIDs.map(String.init).joined(separator: ","),
-      "axWindowReadStatuses": statuses,
-      "hostDisplayIDs": deviceHubHostDisplays().map { String($0) }.joined(separator: ","),
-    ]
-  )
-}
-
-private func deviceHubProcessIdentifiers() -> [pid_t] {
-  let byteCount = proc_listpids(UInt32(PROC_ALL_PIDS), 0, nil, 0)
-  guard byteCount > 0 else { return [] }
-  var pids = [pid_t](repeating: 0, count: Int(byteCount) / MemoryLayout<pid_t>.size + 64)
-  let filled = proc_listpids(UInt32(PROC_ALL_PIDS), 0, &pids, Int32(pids.count * MemoryLayout<pid_t>.size))
-  guard filled > 0 else { return [] }
-  return pids.prefix(Int(filled) / MemoryLayout<pid_t>.size).filter { pid in
-    guard pid > 0 else { return false }
-    var path = [CChar](repeating: 0, count: 4096)
-    guard proc_pidpath(pid, &path, UInt32(path.count)) > 0 else { return false }
-    return String(cString: path).hasSuffix(deviceHubExecutableSuffix)
-  }.sorted()
-}
-
-private func deviceHubHostDisplays() -> [CGDirectDisplayID] {
-  var count: UInt32 = 0
-  guard CGGetActiveDisplayList(0, nil, &count) == .success else { return [] }
-  var displays = [CGDirectDisplayID](repeating: 0, count: Int(count))
-  guard CGGetActiveDisplayList(count, &displays, &count) == .success else { return [] }
-  return Array(displays.prefix(Int(count)))
-}
diff --git a/apple/macos-helper/Sources/AgentDeviceMacOSHelper/main.swift b/apple/macos-helper/Sources/AgentDeviceMacOSHelper/main.swift
index 21b10d0bff..cc9be1260a 100644
--- a/apple/macos-helper/Sources/AgentDeviceMacOSHelper/main.swift
+++ b/apple/macos-helper/Sources/AgentDeviceMacOSHelper/main.swift
@@ -127,8 +127,6 @@ struct AgentDeviceMacOSHelper {
       return try handleScreenshot(arguments: Array(arguments.dropFirst()))
     case "audio-probe":
       return try handleAudioProbe(arguments: Array(arguments.dropFirst()))
-    case "device-hub":
-      return try handleDeviceHub(arguments: Array(arguments.dropFirst()))
     default:
       throw HelperError.invalidArgs("unknown command: \(command)")
     }
diff --git a/apple/macos-helper/Tests/AgentDeviceMacOSDeviceHubTests/DeviceHubPoseTests.swift b/apple/macos-helper/Tests/AgentDeviceMacOSDeviceHubTests/DeviceHubPoseTests.swift
deleted file mode 100644
index c6ef1b49e5..0000000000
--- a/apple/macos-helper/Tests/AgentDeviceMacOSDeviceHubTests/DeviceHubPoseTests.swift
+++ /dev/null
@@ -1,30 +0,0 @@
-import XCTest
-
-@testable import AgentDeviceMacOSDeviceHub
-
-final class DeviceHubPoseTests: XCTestCase {
-  func testEveryPoseNamesTheActionBarControlDeviceHubDescribes() {
-    XCTAssertEqual(DeviceHubPose(argument: "closed")?.controlDescription, "Closed")
-    XCTAssertEqual(DeviceHubPose(argument: "book")?.controlDescription, "Book")
-    XCTAssertEqual(DeviceHubPose(argument: "OPEN")?.controlDescription, "Open")
-    XCTAssertNil(DeviceHubPose(argument: "half-open"), "the helper takes Device Hub's names, not the CLI's")
-    XCTAssertEqual(Set(DeviceHubPose.allCases.map(\.controlDescription)), ["Closed", "Book", "Open"])
-  }
-
-  // Device Hub titles the window `<name> – iOS 27.1`; a simulator whose name merely starts
-  // with another's must not claim that window.
-  func testWindowTitleMatchesTheDeviceNameAsAPrefixWord() {
-    XCTAssertTrue(deviceHubWindowShows(deviceName: "iPhone Duo", title: "iPhone Duo – iOS 27.1"))
-    XCTAssertTrue(deviceHubWindowShows(deviceName: "iPhone Duo", title: "iPhone Duo"))
-    XCTAssertFalse(deviceHubWindowShows(deviceName: "iPhone Duo", title: "iPhone Duo Lab – iOS 27.1"))
-    XCTAssertFalse(deviceHubWindowShows(deviceName: "iPhone Duo", title: "bench-golden-v1 – iOS 27.0"))
-    XCTAssertFalse(deviceHubWindowShows(deviceName: "iPhone Duo", title: nil))
-  }
-
-  func testSidebarRowIsKeyedByUdid() {
-    XCTAssertEqual(
-      deviceHubDeviceRowIdentifier(udid: "4F879835-4AB3-4046-B033-5AB769209DD4"),
-      "TableRow.Device.4F879835-4AB3-4046-B033-5AB769209DD4"
-    )
-  }
-}
diff --git a/apple/macos-helper/Tests/AgentDeviceMacOSDeviceHubTests/DeviceHubWindowInventoryTests.swift b/apple/macos-helper/Tests/AgentDeviceMacOSDeviceHubTests/DeviceHubWindowInventoryTests.swift
deleted file mode 100644
index 9ab682dcde..0000000000
--- a/apple/macos-helper/Tests/AgentDeviceMacOSDeviceHubTests/DeviceHubWindowInventoryTests.swift
+++ /dev/null
@@ -1,65 +0,0 @@
-import ApplicationServices
-import XCTest
-@testable import AgentDeviceMacOSDeviceHub
-
-final class DeviceHubWindowInventoryTests: XCTestCase {
-  func testLaterWindowKeepsItsProcessAndDoesNotPreventEmptyProcessReopen() {
-    var inventory = DeviceHubWindowInventory()
-    let window = AXUIElementCreateApplication(20)
-    inventory.record(processID: 10, read: .available([]))
-    inventory.record(processID: 20, read: .available([window]))
-    XCTAssertEqual(inventory.candidates.map(\.processID), [20])
-    XCTAssertTrue(CFEqual(inventory.candidates[0].window, window))
-    inventory.record(candidate: 0, outcome: .sidebarUnavailable)
-    XCTAssertEqual(inventory.processesToReopen(attempted: []), [10])
-    XCTAssertEqual(inventory.failureReason(), "device-hub-identity-unconfirmed")
-    XCTAssertEqual(inventory.candidateOutcomes, ["20:0:sidebar-unavailable"])
-  }
-
-  func testFailedReadsAreNotReopenedOrMisreportedAsMissingWindows() {
-    var inventory = DeviceHubWindowInventory()
-    inventory.record(processID: 10, read: .failed(-25204))
-    inventory.record(processID: 20, read: .available([]))
-    XCTAssertEqual(inventory.processesToReopen(attempted: []), [20])
-    XCTAssertEqual(inventory.failures, [10: -25204])
-    XCTAssertEqual(inventory.failureReason(), "device-hub-window-read-failed")
-  }
-
-  func testSuccessfulEmptyReadIsMissingAndReopenIsAttemptedOnlyOnce() {
-    var inventory = DeviceHubWindowInventory()
-    inventory.record(processID: 10, read: .available([]))
-    XCTAssertEqual(inventory.failureReason(), "device-hub-window-missing")
-    XCTAssertEqual(inventory.processesToReopen(attempted: []), [10])
-    XCTAssertEqual(inventory.processesToReopen(attempted: [10]), [])
-  }
-
-  func testSharedBudgetExhaustionStopsReopenWithoutClaimingMissingDevice() {
-    var inventory = DeviceHubWindowInventory()
-    inventory.record(processID: 10, read: .available([]))
-    inventory.expireBudget()
-    XCTAssertEqual(inventory.processesToReopen(attempted: []), [])
-    XCTAssertEqual(inventory.failureReason(), "device-hub-discovery-timeout")
-  }
-
-  func testCandidateOutcomesRetainUncertaintyAndOwningProcess() {
-    var inventory = DeviceHubWindowInventory()
-    inventory.record(processID: 10, read: .available([AXUIElementCreateApplication(10)]))
-    inventory.record(processID: 20, read: .available([AXUIElementCreateApplication(20)]))
-    inventory.record(candidate: 0, outcome: .timedOut)
-    inventory.record(candidate: 1, outcome: .unconfirmed)
-    XCTAssertEqual(inventory.candidateOutcomes, ["10:0:timed-out", "20:1:row-unconfirmed"])
-    XCTAssertEqual(inventory.failureReason(), "device-hub-identity-unconfirmed")
-  }
-  func testUnrelatedReopenFailureDoesNotMaskCandidateUncertainty() {
-    var inventory = DeviceHubWindowInventory()
-    inventory.record(processID: 10, read: .available([]))
-    let failures: [Int32: String] = [10: "automation-permission"]
-    XCTAssertEqual(inventory.failureReason(reopenFailures: failures), "automation-permission")
-    inventory.record(processID: 20, read: .available([AXUIElementCreateApplication(20)]))
-    inventory.record(candidate: 0, outcome: .timedOut)
-    XCTAssertEqual(inventory.failureReason(reopenFailures: failures), "device-hub-identity-unconfirmed")
-    inventory.expireBudget()
-    XCTAssertEqual(inventory.failureReason(reopenFailures: failures), "device-hub-discovery-timeout")
-  }
-
-}
diff --git a/docs/adr/0025-foldable-apple-panels.md b/docs/adr/0025-foldable-apple-panels.md
index cdde3e4f93..08bc4659c1 100644
--- a/docs/adr/0025-foldable-apple-panels.md
+++ b/docs/adr/0025-foldable-apple-panels.md
@@ -21,7 +21,7 @@ device is in**. The first is answered by an official host API; the second only b
 | Device has one integrated panel | Keep the pre-panel behavior exactly: no display flag, no pose, unchanged scale probe |
 | Density normalization | Use the captured panel's own `pointScale`; a runner-fallback capture uses the pixels-per-point that capture reported about itself |
 | Pose must be reported | From panel power alone, report `closed`, `fully-open`, or `unknown`, and never narrower; `fold` reports the exact pose because it reads the hinge angle |
-| A pose change is requested | `agent-device fold <closed\|half-open\|open>`: press the pose control in the Device Hub window through macOS accessibility, then read the hinge angle back from CoreDevice until it agrees — for `half-open`, until two consecutive readings agree; refuse the pose if it never does |
+| A pose change is requested | `agent-device fold <closed\|half-open\|open>`: send private HID inside the simulator (see headless amendment), then read the hinge angle back from CoreDevice until it agrees — for `half-open`, until two consecutive readings agree; refuse the pose if it never does |
 | The hinge reaches `half-open` but keeps moving | Refuse it as `fold-pose-unsettled` with the observed and previous angles: an angle inside the open interval is an observed category, not a pose the hinge holds |
 | An external display is attached | It is not a panel: it never makes the device multi-screen and never produces a pose |
 | CoreDevice cannot answer | Return an unresolved inventory and keep the single-panel capture path; a missing host feature is not a capture failure |
@@ -126,6 +126,24 @@ foregrounded on. Measured on a live Duo through the runner route, one command wi
 The closed row is the point: the same command followed the app onto the other panel without being
 told, and every row is real content where a main-screen capture of the unlit panel is black.
 
+## Amendment: headless simulator HID replaces Device Hub (2026-09-22)
+
+The guest HID experiment supersedes the Device Hub pose decision and its private-API rejection
+below. UI discovery and sidebar sections, and their outstanding evidence gaps, are historical.
+`fold` now runs a small Objective-C helper through `simctl spawn <udid>` with no Device Hub or
+host Accessibility requirement. The optional `open --device-hub` UI choice remains independent.
+The helper serializes `{provider: "com.apple.Virtualization.VirtualMachines", source:
+"hinge-slider-control", type: "range", value: angle}` with IOCFSerialize and dispatches a vendor
+HID event (usage page 0xff61, usage 0x5b, version 0) inside the simulator. Requested angles are
+0°, 130°, and 180°; half-open preserves the observed Book angle, without promising UI animation
+or orientation parity. CoreDevice readback and the half-open stability rule remain authoritative.
+This explicitly accepts the private HID dependency for simulator folding. The selected Xcode
+compiles the packaged source into a unique temporary directory per request; cleanup follows both
+success and failure. Build and dispatch are bounded and cancellable, with no UI fallback.
+Local headless tests verified all three poses, panel switching, and an inner-panel screenshot.
+Physical devices, logged-out hosts, and hosted CI are unverified; Duo coverage remains local.
+Absence of a public setter did not establish that Device Hub was required.
+
 ## Pose control: Device Hub's control, CoreDevice's verdict
 
 `agent-device fold` sets the pose, and the split above still holds: the press is not evidence,
diff --git a/docs/agents/device-verification.md b/docs/agents/device-verification.md
index 24522ed9cf..247dee1152 100644
--- a/docs/agents/device-verification.md
+++ b/docs/agents/device-verification.md
@@ -74,14 +74,13 @@ toolchain per command:
 - Input routing: verify a fresh control after each pose change. A successful synthesis acknowledgement
   does not prove a hit. Inspect the runner and simulator `testmanagerd`/BackBoard logs for display
   identity and delivery; the resolved app window owns gesture coordinates and its target screen.
-- Pose: `agent-device fold closed|half-open|open` presses the Device Hub pose control and reads the
-  hinge back through `devicectl device motion hinge-angle`; re-snapshot afterwards, because refs
-  and coordinates do not survive the pose change. Expect 10-16s per fold. The host needs
-  Accessibility permission, and the command reopens Device Hub's window and selects the simulator
-  by UDID itself — unless the sidebar row is missing and the window title already matches, which two
-  same-named simulators defeat (ADR 0025 records it). To read the angle by hand:
-  `xcrun devicectl device motion hinge-angle --device <udid> --session-timeout 1 --timeout 5`
-  (the stream never ends on its own; 5 is the smallest timeout devicectl accepts).
+- Pose: `agent-device fold closed|half-open|open` sends private HID inside the simulator and reads
+  the hinge back through `devicectl device motion hinge-angle`. Device Hub and host Accessibility
+  permission are not required. Re-snapshot afterwards: refs and coordinates do not survive folds.
+  Verify locally with Device Hub stopped and the simulator booted through `simctl boot`; test all
+  three poses, active panel capture, and an app interaction. Duo coverage remains local until GHA
+  supports the runtime. To inspect the angle independently:
+  `xcrun devicectl device motion hinge-angle --device <udid> --session-timeout 1 --timeout 5`.
 - When a recording must show touches, assume it cannot. The touch-overlay exporter loses the track
   geometry whenever it has touch events to draw — `220x480` on a plain iPhone 17 as well as on the
   inner panel — and returns all-black frames on long clips, always with exit 0. Record with
diff --git a/package.json b/package.json
index 71decd72c9..7453a6a4ce 100644
--- a/package.json
+++ b/package.json
@@ -214,6 +214,7 @@
     "apple/macos-helper",
     "!apple/macos-helper/**/.build",
     "apple/snapshot-bridge",
+    "apple/fold-helper",
     "android/snapshot-helper/dist",
     "!android/snapshot-helper/dist/*.idsig",
     "!android/snapshot-helper/README.md",
diff --git a/packages/platform-apple/src/foldable/pose.test.ts b/packages/platform-apple/src/foldable/pose.test.ts
index 5a7b83413e..ea4b631488 100644
--- a/packages/platform-apple/src/foldable/pose.test.ts
+++ b/packages/platform-apple/src/foldable/pose.test.ts
@@ -8,14 +8,7 @@ vi.mock('../core/hinge-angle.ts', async (importOriginal) => {
   const actual = await importOriginal<typeof import('../core/hinge-angle.ts')>();
   return { ...actual, readAppleHingeAngle: vi.fn() };
 });
-vi.mock('../core/simulator.ts', async (importOriginal) => {
-  const actual = await importOriginal<typeof import('../core/simulator.ts')>();
-  return { ...actual, openIosSimulatorApp: vi.fn(async () => {}) };
-});
-vi.mock('../os/macos/helper.ts', async (importOriginal) => {
-  const actual = await importOriginal<typeof import('../os/macos/helper.ts')>();
-  return { ...actual, runMacOsDeviceHubPoseAction: vi.fn() };
-});
+vi.mock('./simulator-hid.ts', () => ({ sendSimulatorFoldPose: vi.fn() }));
 vi.mock('@agent-device/host-kit/diagnostics', async (importOriginal) => {
   const actual = await importOriginal<typeof import('@agent-device/host-kit/diagnostics')>();
   return { ...actual, emitDiagnostic: vi.fn() };
@@ -28,12 +21,12 @@ import {
   type AppleDeviceDisplay,
 } from '../core/display-inventory.ts';
 import { readAppleHingeAngle } from '../core/hinge-angle.ts';
-import { runMacOsDeviceHubPoseAction } from '../os/macos/helper.ts';
+import { sendSimulatorFoldPose } from './simulator-hid.ts';
 import { setAppleFoldPose } from './pose.ts';
 
 const mockInventory = vi.mocked(queryAppleDisplayInventory);
 const mockHinge = vi.mocked(readAppleHingeAngle);
-const mockPress = vi.mocked(runMacOsDeviceHubPoseAction);
+const mockSend = vi.mocked(sendSimulatorFoldPose);
 
 const duo: DeviceInfo = {
   platform: 'apple',
@@ -79,17 +72,11 @@ function duoInventory(lit: 'outer' | 'inner') {
 beforeEach(() => {
   mockInventory.mockReset();
   mockHinge.mockReset();
-  mockPress.mockReset();
-  mockPress.mockResolvedValue({
-    pose: 'open',
-    control: 'Open',
-    windowTitle: 'iPhone Duo – iOS 27.1',
-    reopened: false,
-    selected: true,
-  });
+  mockSend.mockReset();
+  mockSend.mockResolvedValue(undefined);
 });
 
-test('presses the Device Hub control for the pose and reports the pose CoreDevice read back', async () => {
+test('sends the simulator HID pose and reports the pose CoreDevice read back', async () => {
   mockInventory
     .mockResolvedValueOnce(duoInventory('outer'))
     .mockResolvedValueOnce(duoInventory('inner'));
@@ -102,12 +89,7 @@ test('presses the Device Hub control for the pose and reports the pose CoreDevic
     screen: { display: 'LCD-1', coordinateSpace: 'native-panel', widthPt: 669, heightPt: 951 },
   });
 
-  expect(mockPress).toHaveBeenCalledWith({
-    udid: duo.id,
-    deviceName: 'iPhone Duo',
-    pose: 'open',
-    signal: undefined,
-  });
+  expect(mockSend).toHaveBeenCalledWith(duo.id, 'open', undefined);
   expect(mockHinge).toHaveBeenCalledTimes(2);
 });
 
@@ -167,7 +149,7 @@ test('omits the screen report when panel selection is ambiguous, never inventing
   });
 });
 
-test('maps half-open onto the Book preset and reports it only once the hinge has stopped', async () => {
+test('sends half-open and reports it only once the hinge has stopped', async () => {
   mockInventory
     .mockResolvedValueOnce(duoInventory('inner'))
     .mockResolvedValueOnce(duoInventory('inner'));
@@ -180,7 +162,7 @@ test('maps half-open onto the Book preset and reports it only once the hinge has
     hingeAngleDegrees: 130,
     screen: { display: 'LCD-1', coordinateSpace: 'native-panel', widthPt: 669, heightPt: 951 },
   });
-  expect(mockPress).toHaveBeenCalledWith(expect.objectContaining({ pose: 'book' }));
+  expect(mockSend).toHaveBeenCalledWith(duo.id, 'half-open', undefined);
   expect(mockHinge).toHaveBeenCalledTimes(3);
 });
 
@@ -315,18 +297,18 @@ test('propagates a cancellation raised by a hinge read and stops polling', async
   expect(mockHinge).toHaveBeenCalledTimes(1);
 });
 
-test('refuses a single-panel simulator before pressing anything', async () => {
+test('refuses a single-panel simulator before sending anything', async () => {
   mockInventory.mockResolvedValueOnce(buildInventory([panel({})]));
 
   await expect(setAppleFoldPose({ ...duo, name: 'iPhone 17' }, 'open')).rejects.toMatchObject({
     code: 'UNSUPPORTED_OPERATION',
     details: expect.objectContaining({ reason: 'single-panel-device' }),
   });
-  expect(mockPress).not.toHaveBeenCalled();
+  expect(mockSend).not.toHaveBeenCalled();
   expect(mockHinge).not.toHaveBeenCalled();
 });
 
-test('refuses a physical device and an unreadable display table before pressing anything', async () => {
+test('refuses a physical device and an unreadable display table before sending anything', async () => {
   await expect(setAppleFoldPose({ ...duo, kind: 'device' }, 'open')).rejects.toMatchObject({
     code: 'UNSUPPORTED_OPERATION',
   });
@@ -340,5 +322,5 @@ test('refuses a physical device and an unreadable display table before pressing
     code: 'COMMAND_FAILED',
     details: expect.objectContaining({ hint: expect.stringContaining('displays') }),
   });
-  expect(mockPress).not.toHaveBeenCalled();
+  expect(mockSend).not.toHaveBeenCalled();
 });
diff --git a/packages/platform-apple/src/foldable/pose.ts b/packages/platform-apple/src/foldable/pose.ts
index 9cab525785..e8fdade1f8 100644
--- a/packages/platform-apple/src/foldable/pose.ts
+++ b/packages/platform-apple/src/foldable/pose.ts
@@ -15,21 +15,11 @@ import {
   type AppleDisplayInventory,
 } from '../core/display-inventory.ts';
 import { readAppleHingeAngle } from '../core/hinge-angle.ts';
-import { openIosSimulatorApp, requireSimulatorDevice } from '../core/simulator.ts';
-import { runMacOsDeviceHubPoseAction, type MacOsDeviceHubPose } from '../os/macos/helper.ts';
-
-/**
- * The Device Hub action-bar control each pose maps to. Device Hub labels its presets after the
- * shape of the device (Closed, Book, Open); the command names them after what the app sees.
- */
-const DEVICE_HUB_POSE_CONTROLS = {
-  closed: 'closed',
-  'half-open': 'book',
-  open: 'open',
-} as const satisfies Record<FoldPose, MacOsDeviceHubPose>;
+import { requireSimulatorDevice } from '../core/simulator.ts';
+import { sendSimulatorFoldPose } from './simulator-hid.ts';
 
 const FOLDABLE_REQUIRED_HINT =
-  'fold drives the pose controls Xcode Device Hub shows for a foldable simulator such as iPhone Duo; this simulator reports one integrated panel, so it has no hinge to pose.';
+  'fold sets the hinge angle of a foldable simulator such as iPhone Duo; this simulator reports one integrated panel, so it has no hinge to pose.';
 
 const INVENTORY_REQUIRED_HINT =
   "fold needs 'devicectl device info displays' to tell a foldable from a single-panel simulator; update Xcode to a version that ships the display-information feature.";
@@ -37,44 +27,22 @@ const INVENTORY_REQUIRED_HINT =
 const POSE_UNSETTLED_HINT =
   'The hinge reached the requested pose and was still moving when the read budget ended. Retry the fold, then read the angle directly with xcrun devicectl device motion hinge-angle --device <udid> --session-timeout 1 --timeout 5 to see whether the simulator holds the pose.';
 
-/**
- * Puts a foldable simulator into `pose` and verifies it did get there.
- *
- * No official host API sets a hinge pose (ADR 0025): Device Hub sends it to the simulator through
- * a private CoreDevice channel, and the only public seam onto that channel is the pose control in
- * Device Hub's own window. The press is therefore a macOS accessibility action on that control,
- * and the truth of the outcome comes from CoreDevice, not from the press: the hinge angle is read
- * back until it agrees with the request, and the pose is refused if it never does.
- */
+/** Sets a simulator hinge through guest HID and verifies the pose through CoreDevice. */
 export async function setAppleFoldPose(
   device: DeviceInfo,
   pose: FoldPose,
   options: { signal?: AbortSignal } = {},
 ): Promise<SetFoldPoseResult> {
+  options.signal?.throwIfAborted();
   requireSimulatorDevice(device, 'fold');
   const inventory = await queryAppleDisplayInventory(device, { signal: options.signal });
   requireFoldableInventory(device, inventory);
 
-  // A headless boot leaves Device Hub unlaunched; the same launch `open` performs brings it up
-  // in the background, and the helper then drives whichever window it shows.
-  await openIosSimulatorApp({ deviceHub: true, background: true, signal: options.signal });
-  const pressed = await runMacOsDeviceHubPoseAction({
-    udid: device.id,
-    deviceName: device.name,
-    pose: DEVICE_HUB_POSE_CONTROLS[pose],
-    signal: options.signal,
-  });
+  await sendSimulatorFoldPose(device.id, pose, options.signal);
   emitDiagnostic({
     level: 'info',
-    phase: 'apple_fold_pose_pressed',
-    data: {
-      deviceId: device.id,
-      pose,
-      control: pressed.control,
-      windowTitle: pressed.windowTitle,
-      reopened: pressed.reopened,
-      selected: pressed.selected,
-    },
+    phase: 'apple_fold_pose_dispatched',
+    data: { deviceId: device.id, pose },
   });
 
   const hingeAngleDegrees = await awaitHingePose(device, pose, options.signal);
@@ -108,8 +76,8 @@ function requireFoldableInventory(device: DeviceInfo, inventory: AppleDisplayInv
 
 /**
  * Reads the hinge until it reports the requested pose. Each read costs one bounded devicectl
- * stream, so the attempt count is the whole settle budget: the Device Hub press animates the
- * hinge, and a press that landed on some other device's window never moves this one.
+ * stream, so the attempt count is the whole settle budget. HID delivery alone cannot prove
+ * the runtime accepted the requested hinge state.
  *
  * `closed` and `open` are the hinge's two end stops, so one read at the stop is the pose. A
  * `half-open` angle proves only the category, because a hinge travelling between the stops passes
@@ -168,7 +136,7 @@ function unverifiedPoseError(device: DeviceInfo, pose: FoldPose, observed: numbe
     {
       ...hingePoseDetails(device, pose, observed),
       reason: 'fold-pose-unverified',
-      hint: 'The Device Hub pose control was pressed, but the hinge did not follow. If several Device Hub windows are titled with this device name, close the ones for other simulators so the press reaches this one, then retry.',
+      hint: 'The simulator HID command completed, but the hinge did not follow. Verify that the selected Xcode and simulator runtime support foldable HID control, then retry.',
     },
   );
 }
diff --git a/packages/platform-apple/src/foldable/simulator-hid.test.ts b/packages/platform-apple/src/foldable/simulator-hid.test.ts
new file mode 100644
index 0000000000..db0f60d879
--- /dev/null
+++ b/packages/platform-apple/src/foldable/simulator-hid.test.ts
@@ -0,0 +1,47 @@
+import { expect, test } from 'vitest';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { withAppleToolProvider, createLocalAppleToolProvider } from '../core/tool-provider.ts';
+import { sendSimulatorFoldPose } from './simulator-hid.ts';
+
+test.each(['success', 'build', 'dispatch', 'cancel'] as const)(
+  'HID route targets the UDID, cleans temporary artifacts, and handles %s',
+  async (failure) => {
+    const calls: string[][] = [];
+    const controller = new AbortController();
+    let binary = '';
+    await withAppleToolProvider(
+      createLocalAppleToolProvider({
+        runCommand: async (command, args, options) => {
+          expect(command).toBe('xcrun');
+          expect(options?.signal).toBe(controller.signal);
+          expect(options?.timeoutMs).toBeGreaterThan(0);
+          calls.push(args);
+          if (args.includes('clang')) {
+            binary = args.at(-1)!;
+            expect(existsSync(path.dirname(binary))).toBe(true);
+            expect(existsSync(args[args.indexOf('-o') - 1]!)).toBe(true);
+            if (failure === 'cancel') controller.abort(new Error('cancelled'));
+            return { stdout: '', stderr: 'compiler detail', exitCode: failure === 'build' ? 1 : 0 };
+          }
+          expect(args).toEqual(['simctl', 'spawn', 'selected-duo', binary, 'half-open']);
+          return { stdout: '', stderr: 'spawn detail', exitCode: failure === 'dispatch' ? 1 : 0 };
+        },
+      }),
+      async () => {
+        const operation = sendSimulatorFoldPose('selected-duo', 'half-open', controller.signal);
+        if (failure === 'success') await expect(operation).resolves.toBeUndefined();
+        else if (failure === 'cancel') await expect(operation).rejects.toThrow('cancelled');
+        else
+          await expect(operation).rejects.toMatchObject({
+            code: 'COMMAND_FAILED',
+            details: {
+              reason: failure === 'build' ? 'fold-helper-build-failed' : 'fold-hid-dispatch-failed',
+            },
+          });
+      },
+    );
+    expect(calls).toHaveLength(failure === 'build' || failure === 'cancel' ? 1 : 2);
+    expect(existsSync(path.dirname(binary))).toBe(false);
+  },
+);
diff --git a/packages/platform-apple/src/foldable/simulator-hid.ts b/packages/platform-apple/src/foldable/simulator-hid.ts
new file mode 100644
index 0000000000..e79382d60f
--- /dev/null
+++ b/packages/platform-apple/src/foldable/simulator-hid.ts
@@ -0,0 +1,65 @@
+import path from 'node:path';
+import type { FoldPose } from '@agent-device/contracts/device';
+import { AppError } from '@agent-device/kernel/errors';
+import { execFailureDetails } from '@agent-device/host-kit/command';
+import { makeHostTemporaryDirectory, removeHostDirectory } from '@agent-device/host-kit/host-file';
+import { findProjectRoot } from '@agent-device/host-kit/version';
+import { runXcrun } from '../core/tool-provider.ts';
+
+/** Compiles for the selected Xcode and dispatches inside exactly the requested simulator. */
+export async function sendSimulatorFoldPose(
+  udid: string,
+  pose: FoldPose,
+  signal?: AbortSignal,
+): Promise<void> {
+  signal?.throwIfAborted();
+  const directory = await makeHostTemporaryDirectory('agent-device-fold-');
+  try {
+    const binary = path.join(directory, 'fold');
+    const build = await runXcrun(
+      [
+        '--sdk',
+        'iphonesimulator',
+        'clang',
+        '-mios-simulator-version-min=15.0',
+        '-fobjc-arc',
+        '-Wall',
+        '-Wextra',
+        '-Werror',
+        '-framework',
+        'Foundation',
+        '-framework',
+        'IOKit',
+        path.join(findProjectRoot(), 'apple', 'fold-helper', 'Fold.m'),
+        '-o',
+        binary,
+      ],
+      { signal, timeoutMs: 30_000, allowFailure: true },
+    );
+    if (build.exitCode !== 0) {
+      throw new AppError(
+        'COMMAND_FAILED',
+        'Unable to build the simulator fold helper',
+        execFailureDetails(build, {
+          reason: 'fold-helper-build-failed',
+          hint: 'Select an Xcode with the iOS simulator SDK and foldable HID support using DEVELOPER_DIR.',
+        }),
+      );
+    }
+    signal?.throwIfAborted();
+    const sent = await runXcrun(['simctl', 'spawn', udid, binary, pose], {
+      signal,
+      timeoutMs: 10_000,
+      allowFailure: true,
+    });
+    if (sent.exitCode !== 0) {
+      throw new AppError(
+        'COMMAND_FAILED',
+        'Unable to send the simulator hinge pose',
+        execFailureDetails(sent, { reason: 'fold-hid-dispatch-failed', deviceId: udid }),
+      );
+    }
+  } finally {
+    await removeHostDirectory(directory);
+  }
+}
diff --git a/packages/platform-apple/src/os/macos/helper.test.ts b/packages/platform-apple/src/os/macos/helper.test.ts
index 41f4def72a..eb8d24b0e9 100644
--- a/packages/platform-apple/src/os/macos/helper.test.ts
+++ b/packages/platform-apple/src/os/macos/helper.test.ts
@@ -1,12 +1,7 @@
 import assert from 'node:assert/strict';
-import { expect, test } from 'vitest';
+import { test } from 'vitest';
 import { createLocalAppleToolProvider, withAppleToolProvider } from '../../core/tool-provider.ts';
-import {
-  macOsClickScheduleMs,
-  runMacOsPressAction,
-  runMacOsSnapshotAction,
-  runMacOsDeviceHubPoseAction,
-} from './helper.ts';
+import { macOsClickScheduleMs, runMacOsPressAction, runMacOsSnapshotAction } from './helper.ts';
 
 test('macOS helper snapshot passes cancellation to the helper process', async () => {
   const controller = new AbortController();
@@ -212,42 +207,3 @@ test('macOS helper press stays a single held click when nothing is repeated', as
   assert.equal(receivedArgs.includes('--hold-ms'), false);
   assert.equal(receivedArgs.includes('--interval-ms'), false);
 });
-
-test('Device Hub window read failures preserve AX status and process diagnostics', async () => {
-  const provider = createLocalAppleToolProvider({
-    macosHelper: {
-      run: async () => ({
-        exitCode: 1,
-        stdout: JSON.stringify({
-          ok: false,
-          error: {
-            message: "Could not read Device Hub's accessible windows",
-            details: {
-              reason: 'device-hub-window-read-failed',
-              processIDs: '10,20',
-              axWindowReadStatuses: '10:-25204',
-              hostDisplayIDs: '1,2',
-            },
-          },
-        }),
-        stderr: '',
-      }),
-    },
-  });
-  await withAppleToolProvider(provider, async () => {
-    await assert.rejects(
-      runMacOsDeviceHubPoseAction({ udid: 'duo', deviceName: 'iPhone Duo', pose: 'open' }),
-      (error: unknown) => {
-        expect(error).toMatchObject({
-          details: {
-            reason: 'device-hub-window-read-failed',
-            processIDs: '10,20',
-            axWindowReadStatuses: '10:-25204',
-            hostDisplayIDs: '1,2',
-          },
-        });
-        return true;
-      },
-    );
-  });
-});
diff --git a/packages/platform-apple/src/os/macos/helper.ts b/packages/platform-apple/src/os/macos/helper.ts
index 2174ffdf89..a0bd002176 100644
--- a/packages/platform-apple/src/os/macos/helper.ts
+++ b/packages/platform-apple/src/os/macos/helper.ts
@@ -471,41 +471,6 @@ export async function runMacOsPressAction(
   });
 }
 
-export type MacOsDeviceHubPose = 'closed' | 'book' | 'open';
-
-/**
- * Presses one pose control in the Xcode Device Hub window for a foldable simulator. The helper
- * asks Device Hub to reopen a window when it shows none, switches that window to the device
- * through the sidebar row keyed by the simulator's UDID, and only then presses the control; it
- * reports which of those steps it had to take.
- */
-export async function runMacOsDeviceHubPoseAction(options: {
-  udid: string;
-  deviceName: string;
-  pose: MacOsDeviceHubPose;
-  signal?: AbortSignal;
-}): Promise<{
-  pose: MacOsDeviceHubPose;
-  control: string;
-  windowTitle: string;
-  reopened: boolean;
-  selected: boolean;
-}> {
-  return await runMacOsHelper(
-    [
-      'device-hub',
-      'pose',
-      '--udid',
-      options.udid,
-      '--device-name',
-      options.deviceName,
-      '--pose',
-      options.pose,
-    ],
-    { signal: options.signal },
-  );
-}
-
 export async function runMacOsScreenshotAction(
   outPath: string,
   options: { surface?: SessionSurface; fullscreen?: boolean } = {},
diff --git a/src/commands/schema/cli-help.ts b/src/commands/schema/cli-help.ts
index a2c5912e7e..8c4674efd8 100644
--- a/src/commands/schema/cli-help.ts
+++ b/src/commands/schema/cli-help.ts
@@ -748,9 +748,9 @@ Screens are handled for you:
 
 Changing the pose:
   agent-device fold closed | half-open | open
-  fold presses the pose control in the Xcode Device Hub window for this simulator (Closed, Book, Open) and then reads the hinge angle back from CoreDevice until it agrees: closed is 0 degrees, open is 180, and half-open is any angle between them (Device Hub's Book preset, 130 degrees on iOS 27.1). An angle in that interval only proves the category, so half-open is reported once two consecutive readings both fall inside it and agree within 0.5 degrees. The response reports the verified pose, the hinge angle, and the panel the device now lights with its native panel point size, marked coordinateSpace "native-panel". That point size is the panel's own geometry, not the next snapshot's viewport, so it cannot place a tap: the active app window can differ (a 669x951 inner panel hosts a 951x669 window). A hinge whose last reading is some other pose fails with COMMAND_FAILED and reason fold-pose-unverified, naming the angle CoreDevice still reports; a hinge seen half-open but never at rest fails with reason fold-pose-unsettled, naming the observed and previous angles. A single-panel simulator fails with UNSUPPORTED_OPERATION.
+  fold sends a private HID hinge event inside the selected simulator and then reads the hinge angle back from CoreDevice until it agrees: closed is 0 degrees, open is 180, and half-open is any angle between them (requested at 130 degrees). An angle in that interval only proves the category, so half-open is reported once two consecutive readings both fall inside it and agree within 0.5 degrees. The response reports the verified pose, the hinge angle, and the panel the device now lights with its native panel point size, marked coordinateSpace "native-panel". That point size is the panel's own geometry, not the next snapshot's viewport, so it cannot place a tap: the active app window can differ (a 669x951 inner panel hosts a 951x669 window). A hinge whose last reading is some other pose fails with COMMAND_FAILED and reason fold-pose-unverified, naming the angle CoreDevice still reports; a hinge seen half-open but never at rest fails with reason fold-pose-unsettled, naming the observed and previous angles. A single-panel simulator fails with UNSUPPORTED_OPERATION.
   Expect a fold to take 10-16 seconds: each hinge read is a five-second devicectl stream, and half-open waits for the hinge to stop moving. Re-snapshot after every fold; refs and coordinates from before it are stale, and the command's message says so.
-  Requirements: an iOS simulator session on a foldable device, Xcode 27.1 or newer with Device Hub, and Accessibility permission for the host (agent-device settings permission grant accessibility --platform macos). The command launches Device Hub if needed, reopens its window when it shows none, and selects the simulator through its sidebar by UDID, so no operator step is needed. No official host API sets the pose; the app under test still reads it as UIHinge.status.
+  Requirements: an iOS simulator session on a foldable device and an Xcode toolchain with the iOS simulator SDK and foldable HID support (verified on Xcode 27.1). Device Hub and host Accessibility permission are not required. The command builds a small temporary helper with the selected Xcode and runs it through simctl spawn for the session UDID; build or dispatch failures are reported without a UI fallback. The app under test reads the resulting pose as UIHinge.status.
   If a task asserts behavior for more than one pose, fold to each pose and re-snapshot, and report which poses the run covered.`,
   },
   remote: {
diff --git a/src/commands/system/index.ts b/src/commands/system/index.ts
index f7ed8b014a..9626f13210 100644
--- a/src/commands/system/index.ts
+++ b/src/commands/system/index.ts
@@ -60,7 +60,7 @@ const homeCommandDescription =
   'Send the selected device to its home screen. This leaves the app session open but moves the foreground away from the app.';
 const orientationCommandDescription = 'Set device orientation on iOS and Android';
 const foldCommandDescription =
-  'Fold or unfold a foldable iPhone simulator (iPhone Duo) into the closed, half-open, or open pose by pressing the pose control in Xcode Device Hub, then read the hinge angle back from CoreDevice to confirm it. A pose change moves the app to a different panel with a different point size, so every ref and coordinate from before it is stale: re-snapshot after this command. Taps, long presses, and scrolling target the app window on its current panel in closed, half-open, and open poses. Simulator-only; the device window must be open in Device Hub and the host needs Accessibility permission.';
+  'Fold or unfold a foldable iPhone simulator (iPhone Duo) into the closed, half-open, or open pose by sending a simulator HID hinge event, then read the hinge angle back from CoreDevice to confirm it. A pose change moves the app to a different panel with a different point size, so every ref and coordinate from before it is stale: re-snapshot after this command. Taps, long presses, and scrolling target the app window on its current panel in closed, half-open, and open poses. Simulator-only; requires the iOS simulator SDK; Device Hub and host Accessibility permission are not required.';
 const appSwitcherCommandDescription =
   'Open the device app switcher to inspect or change foreground apps. This changes the visible system UI and may move focus away from the current app.';
 const keyboardCommandDescription =
@@ -89,7 +89,7 @@ const foldCommandMetadata = defineFieldCommandMetadata(FOLD_COMMAND_NAME, foldCo
   pose: requiredField(
     enumField(
       FOLD_POSES,
-      'The hinge pose to reach: closed lights the outer panel; half-open (Device Hub Book) and open light the inner panel.',
+      'The hinge pose to reach: closed lights the outer panel; half-open (130 degrees) and open light the inner panel.',
     ),
   ),
 });
@@ -269,7 +269,7 @@ const foldCommandFacet = defineCommandFacet({
   text: {
     summary: 'Fold or unfold a foldable iPhone simulator',
     cliDetail:
-      'iPhone Duo simulators only. Presses the pose control in Xcode Device Hub and confirms the hinge angle through CoreDevice; refs and coordinates do not survive a pose change.',
+      'iPhone Duo simulators only. Sends a simulator HID hinge event and confirms the hinge angle through CoreDevice; refs and coordinates do not survive a pose change.',
   },
   metadata: foldCommandMetadata,
   run: (client, input) => client.command.fold(input),
diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md
index 20e9389c2f..3e20fa5767 100644
--- a/website/docs/docs/commands.md
+++ b/website/docs/docs/commands.md
@@ -91,9 +91,8 @@ agent-device fold open
 - `action-button` asks the device whether it has the button before pressing it. A target whose model has none — an iPhone SE beside an iPhone 15, or most iPad simulators — fails with `UNSUPPORTED_OPERATION` rather than reporting a press that never happened.
 - `action-button` does not activate or relaunch the session's app, and it takes no `--settle`: pressing a hardware button is not a navigation, so the app stays where it was.
 - `action-button` reports that the press was dispatched, not what the system did with it. Simulators run no Shortcuts and no App Intents, so what a press triggers can only be verified on a physical iPhone; on a Simulator the command proves the press was accepted and that the session app was not brought forward.
-- `fold <closed|half-open|open>` puts a foldable iPhone simulator (iPhone Duo) into a hinge pose. No official host API sets a pose (ADR 0025), so the command presses the pose control in the Xcode Device Hub window through macOS accessibility, then reads the hinge angle back with `devicectl device motion hinge-angle` and reports the pose only when that reading agrees: `closed` is 0°, `open` is 180°, and `half-open` is any angle between them (Device Hub's Book preset, 130° on iOS 27.1). An angle inside that interval only proves the category, so `half-open` is reported once two consecutive readings both fall inside it and agree within 0.5°. The response names the panel the device now lights and its native panel point size, marked `coordinateSpace: "native-panel"`; that size is the panel's own geometry, not the next snapshot's viewport (a 669x951 inner panel can host a 951x669 app window), so it cannot place a tap. Re-snapshot afterwards, and never carry refs or coordinates across a `fold`. After that snapshot, taps, long presses, and scrolling follow the app window on the active panel in closed, half-open, and open poses.
-- `fold` is simulator-only and needs Xcode 27.1 or newer with Device Hub. The host needs Accessibility permission (`settings permission grant accessibility --platform macos`), and Device Hub must list the simulator; the command reopens Device Hub's window when it shows none, selects the device through the sidebar row keyed by its UDID, and attempts to restore any sidebar it revealed afterwards within a bounded cleanup budget. Sidebar actions use the selected window’s toolbar button. A single-panel simulator such as an iPhone 17 fails with `UNSUPPORTED_OPERATION`; Android, web, Linux, HarmonyOS, Vega, physical devices, and the tvOS, macOS, and visionOS leaves refuse it.
-- `fold` discovers windows across running Device Hub processes without requiring main-display placement. Failed accessibility reads report `device-hub-window-read-failed` with AX status and process/display diagnostics; they do not count as an empty window list. Inconclusive row lookup reports `device-hub-identity-unconfirmed` with candidate outcomes; an interrupted discovery reports `device-hub-discovery-timeout`. Active host display IDs are included only in discovery errors.
+- `fold <closed|half-open|open>` puts a foldable iPhone simulator (iPhone Duo) into a hinge pose. The command sends a private HID hinge event inside the selected simulator (ADR 0025), then reads the hinge angle back with `devicectl device motion hinge-angle` and reports the pose only when that reading agrees: `closed` is 0°, `open` is 180°, and `half-open` is any angle between them (requested at 130°). An angle inside that interval only proves the category, so `half-open` is reported once two consecutive readings both fall inside it and agree within 0.5°. The response names the panel the device now lights and its native panel point size, marked `coordinateSpace: "native-panel"`; that size is the panel's own geometry, not the next snapshot's viewport (a 669x951 inner panel can host a 951x669 app window), so it cannot place a tap. Re-snapshot afterwards, and never carry refs or coordinates across a `fold`. After that snapshot, taps, long presses, and scrolling follow the app window on the active panel in closed, half-open, and open poses.
+- `fold` is simulator-only and requires an Xcode toolchain with the iOS simulator SDK and foldable HID support (verified on Xcode 27.1). It compiles a temporary helper and runs it against the session UDID. Device Hub and host Accessibility permission are not required. Build failures report `fold-helper-build-failed`; dispatch failures report `fold-hid-dispatch-failed`. There is no UI fallback. Single-panel simulators and physical devices are refused.
 - `fold` costs one bounded hinge stream per read, and devicectl's smallest stream is five seconds: `closed` and `open` take about ten seconds, `half-open` about sixteen, because the hinge animates and the command waits for it to stop. A hinge whose last reading is some other pose fails with `COMMAND_FAILED` and `reason: fold-pose-unverified`, naming the angle CoreDevice still reports. A hinge seen `half-open` but never at rest fails with `reason: fold-pose-unsettled`, naming the observed and previous angles: the requested category was observed, and what is missing is a pose the hinge holds (#2730).
 - `action-button` is not a cheap command to loop. On an iPhone 17 Pro Simulator the press itself spent about five seconds inside XCUITest, while `home` and `app-switcher` on the same session took under two seconds each.
 - On iOS devices, `http(s)://` URLs open in Safari when no app is active. Custom scheme URLs require an active app in the session.

From abba01e644dd646381ee8856e6a53b34455f2c06 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Tue, 22 Sep 2026 20:44:57 +0200
Subject: [PATCH 026/132] feat(ios): animate fold with timed hinge keyframes
 (#2763)

* feat(ios): support timed hinge keyframes

* fix(ios): preserve fold timelines in replay and verify boundary angles

* fix(ios): terminate guest fold animation on cancellation

* chore(gates): classify timed fold keyframes as device-observable

* chore(ci): retrigger checks for fold trajectories
---
 apple/fold-helper/Fold.m                      | 102 +++++++++++++----
 contracts/fixtures/fold-keyframes.json        | 106 ++++++++++++++++++
 docs/adr/0025-foldable-apple-panels.md        |  14 +++
 .../ad-script/src/internal/script-utils.ts    |   8 ++
 packages/ad-script/src/internal/script.ts     |   2 +-
 .../src/flag-definitions-action.ts            |  10 ++
 packages/command-registry/src/flag-groups.ts  |   2 +
 .../command-registry/src/timeout-policy.ts    |   4 +-
 packages/contracts/package.json               |   3 +
 packages/contracts/src/cli-flags.ts           |   1 +
 packages/contracts/src/client-system.ts       |   6 +-
 .../src/device-rotation-fold-input.test.ts    |  52 +++++++++
 packages/contracts/src/device-rotation.ts     |  74 ++++++++++++
 packages/contracts/src/facades/device.ts      |  11 +-
 packages/contracts/src/fold-runtime.ts        |   9 +-
 packages/platform-apple/src/core/config.ts    |   2 +-
 .../src/foldable/fixtures/keyframes.m         |  21 ++++
 .../platform-apple/src/foldable/pose.test.ts  |  87 +++++++++++---
 packages/platform-apple/src/foldable/pose.ts  |  92 ++++++++++++---
 .../platform-apple/src/foldable/runtime.ts    |  10 +-
 .../src/foldable/simulator-hid-native.test.ts |  45 ++++++++
 .../src/foldable/simulator-hid.test.ts        |  23 ++++
 .../src/foldable/simulator-hid.ts             |  12 +-
 pnpm-lock.yaml                                |   4 +
 scripts/integration-progress-model.ts         |   1 +
 .../command-descriptor-timeout-policy.test.ts |   2 +-
 src/commands/command-contract.ts              |   2 +
 src/commands/schema/cli-help.ts               |   2 +
 src/commands/system/index.test.ts             |  17 ++-
 src/commands/system/index.ts                  |  88 ++++++++++++---
 src/daemon/__tests__/fold-runtime.test.ts     |  38 +++++++
 src/daemon/fold-runtime.ts                    |  23 +++-
 src/daemon/generic-runtime-execution.ts       |   1 +
 .../provider-scenarios/ios-fold.test.ts       |  92 +++++++++++++++
 website/docs/docs/client-api.md               |  10 ++
 website/docs/docs/commands.md                 |   1 +
 36 files changed, 871 insertions(+), 106 deletions(-)
 create mode 100644 contracts/fixtures/fold-keyframes.json
 create mode 100644 packages/contracts/src/device-rotation-fold-input.test.ts
 create mode 100644 packages/platform-apple/src/foldable/fixtures/keyframes.m
 create mode 100644 packages/platform-apple/src/foldable/simulator-hid-native.test.ts
 create mode 100644 test/integration/provider-scenarios/ios-fold.test.ts

diff --git a/apple/fold-helper/Fold.m b/apple/fold-helper/Fold.m
index 64601b3094..f028c6438e 100644
--- a/apple/fold-helper/Fold.m
+++ b/apple/fold-helper/Fold.m
@@ -1,5 +1,6 @@
 #import <Foundation/Foundation.h>
 #import <mach/mach_time.h>
+#import <math.h>
 
 // Private simulator HID entry points; the host verifies the resulting hinge independently.
 extern CFDataRef IOCFSerialize(CFTypeRef object, CFOptionFlags options);
@@ -9,35 +10,88 @@ extern CFTypeRef IOHIDEventCreateVendorDefinedEvent(CFAllocatorRef allocator, ui
 extern CFTypeRef IOHIDEventSystemClientCreate(CFAllocatorRef allocator);
 extern void IOHIDEventSystemClientDispatchEvent(CFTypeRef client, CFTypeRef event);
 
+static BOOL sendAngle(CFTypeRef client, double angle) {
+  NSDictionary *payload = @{
+    @"provider": @"com.apple.Virtualization.VirtualMachines",
+    @"source": @"hinge-slider-control", @"type": @"range", @"value": @(angle),
+  };
+  CFDataRef data = IOCFSerialize((__bridge CFTypeRef)payload, 1);
+  if (!data) return NO;
+  CFTypeRef event = IOHIDEventCreateVendorDefinedEvent(kCFAllocatorDefault,
+      mach_absolute_time(), 0xff61, 0x5b, 0, CFDataGetBytePtr(data), CFDataGetLength(data), 0);
+  if (event) IOHIDEventSystemClientDispatchEvent(client, event);
+  CFRelease(data);
+  if (!event) return NO;
+  CFRelease(event);
+  return YES;
+}
+
+static BOOL validNumber(id value) {
+  return [value isKindOfClass:NSNumber.class] &&
+      CFGetTypeID((__bridge CFTypeRef)value) != CFBooleanGetTypeID() && isfinite([value doubleValue]);
+}
+
+static NSArray *readFrames(NSString *argument) {
+  NSNumber *preset = (@{@"closed": @0, @"half-open": @130, @"open": @180})[argument];
+  if (preset) return @[@{@"atMs": @0, @"angle": preset}];
+  id frames = [NSJSONSerialization JSONObjectWithData:[argument dataUsingEncoding:NSUTF8StringEncoding]
+      options:0 error:NULL];
+  if (![frames isKindOfClass:NSArray.class] || [frames count] < 2 || [frames count] > 64) return nil;
+  double previous = -1;
+  for (id frame in frames) {
+    if (![frame isKindOfClass:NSDictionary.class] || [frame count] != 2 ||
+        !validNumber(frame[@"atMs"]) || !validNumber(frame[@"angle"])) return nil;
+    double time = [frame[@"atMs"] doubleValue], angle = [frame[@"angle"] doubleValue];
+    if (time < 0 || time > 60000 || floor(time) != time || time <= previous ||
+        (previous == -1 && time != 0) || angle < 0 || angle > 180) return nil;
+    previous = time;
+  }
+  return frames;
+}
+
+static double angleAtTime(NSArray *frames, double elapsed) {
+  NSUInteger segment = 0;
+  while (segment + 1 < frames.count && [frames[segment + 1][@"atMs"] doubleValue] <= elapsed) segment++;
+  double angle = [frames[segment][@"angle"] doubleValue];
+  if (segment + 1 < frames.count) {
+    double from = [frames[segment][@"atMs"] doubleValue];
+    double to = [frames[segment + 1][@"atMs"] doubleValue];
+    angle += ([frames[segment + 1][@"angle"] doubleValue] - angle) * (elapsed - from) / (to - from);
+  }
+  return angle;
+}
+
+static BOOL runFrames(CFTypeRef client, NSArray *frames) {
+  mach_timebase_info_data_t clock;
+  mach_timebase_info(&clock);
+  uint64_t start = mach_absolute_time();
+  double duration = [frames.lastObject[@"atMs"] doubleValue];
+  double elapsed = 0;
+  while (YES) {
+    @autoreleasepool {
+      if (!sendAngle(client, angleAtTime(frames, elapsed))) return NO;
+    }
+    if (elapsed >= duration) return YES;
+    double now = (mach_absolute_time() - start) * clock.numer / (double)clock.denom / 1e6;
+    // Absolute deadlines skip missed frames instead of extending the user's timeline.
+    double next = fmin(duration, (floor(now * 60 / 1000) + 1) * 1000 / 60);
+    mach_wait_until(start + (uint64_t)(next * 1e6 * clock.denom / clock.numer));
+    elapsed = fmin(duration, (mach_absolute_time() - start) * clock.numer / (double)clock.denom / 1e6);
+  }
+}
+
 int main(int argc, const char *argv[]) {
   @autoreleasepool {
-    if (argc != 2) return 2;
-    NSDictionary *angles = @{@"closed": @0, @"half-open": @130, @"open": @180};
-    NSNumber *angle = angles[@(argv[1])];
-    if (!angle) {
-      fprintf(stderr, "Expected closed, half-open, or open\n");
+    NSArray *frames = argc == 2 ? readFrames(@(argv[1])) : nil;
+    if (!frames) {
+      fprintf(stderr, "Expected a pose or 2-64 {atMs,angle} keyframes spanning 0 to at most 60000ms\n");
       return 2;
     }
-    NSDictionary *payload = @{
-      @"provider": @"com.apple.Virtualization.VirtualMachines",
-      @"source": @"hinge-slider-control",
-      @"type": @"range",
-      @"value": angle,
-    };
-    CFDataRef data = IOCFSerialize((__bridge CFTypeRef)payload, 1);
-    if (!data) {
-      fprintf(stderr, "Unable to serialize simulator hinge payload\n");
-      return 1;
-    }
     CFTypeRef client = IOHIDEventSystemClientCreate(kCFAllocatorDefault);
-    CFTypeRef event = IOHIDEventCreateVendorDefinedEvent(kCFAllocatorDefault,
-        mach_absolute_time(), 0xff61, 0x5b, 0, CFDataGetBytePtr(data), CFDataGetLength(data), 0);
-    if (client && event) IOHIDEventSystemClientDispatchEvent(client, event);
-    BOOL dispatched = client && event;
-    if (event) CFRelease(event);
-    if (client) CFRelease(client);
-    CFRelease(data);
-    if (!dispatched) fprintf(stderr, "Unable to create simulator HID client or event\n");
+    if (!client) return 1;
+    BOOL dispatched = runFrames(client, frames);
+    CFRelease(client);
+    if (!dispatched) fprintf(stderr, "Unable to create simulator HID event\n");
     return dispatched ? 0 : 1;
   }
 }
diff --git a/contracts/fixtures/fold-keyframes.json b/contracts/fixtures/fold-keyframes.json
new file mode 100644
index 0000000000..14d081c984
--- /dev/null
+++ b/contracts/fixtures/fold-keyframes.json
@@ -0,0 +1,106 @@
+[
+  {
+    "name": "opening reversal",
+    "valid": true,
+    "samples": [
+      {
+        "atMs": 0,
+        "angle": 0
+      },
+      {
+        "atMs": 833.5,
+        "angle": 80
+      },
+      {
+        "atMs": 1667,
+        "angle": 160
+      },
+      {
+        "atMs": 2500,
+        "angle": 130
+      },
+      {
+        "atMs": 3333,
+        "angle": 100
+      },
+      {
+        "atMs": 4166.5,
+        "angle": 140
+      },
+      {
+        "atMs": 5000,
+        "angle": 180
+      }
+    ],
+    "keyframesJson": "[{\"atMs\":0,\"angle\":0},{\"atMs\":1667,\"angle\":160},{\"atMs\":3333,\"angle\":100},{\"atMs\":5000,\"angle\":180}]"
+  },
+  {
+    "name": "hold and fractional angle",
+    "valid": true,
+    "samples": [
+      {
+        "atMs": 0,
+        "angle": 42.5
+      },
+      {
+        "atMs": 30000,
+        "angle": 42.5
+      },
+      {
+        "atMs": 60000,
+        "angle": 42.5
+      }
+    ],
+    "keyframesJson": "[{\"atMs\":0,\"angle\":42.5},{\"atMs\":60000,\"angle\":42.5}]"
+  },
+  {
+    "name": "empty",
+    "valid": false,
+    "keyframesJson": "[]"
+  },
+  {
+    "name": "single",
+    "valid": false,
+    "keyframesJson": "[{\"atMs\":0,\"angle\":0}]"
+  },
+  {
+    "name": "late start",
+    "valid": false,
+    "keyframesJson": "[{\"atMs\":1,\"angle\":0},{\"atMs\":5000,\"angle\":180}]"
+  },
+  {
+    "name": "duplicate time",
+    "valid": false,
+    "keyframesJson": "[{\"atMs\":0,\"angle\":0},{\"atMs\":0,\"angle\":180}]"
+  },
+  {
+    "name": "reverse time",
+    "valid": false,
+    "keyframesJson": "[{\"atMs\":0,\"angle\":0},{\"atMs\":5000,\"angle\":100},{\"atMs\":4000,\"angle\":180}]"
+  },
+  {
+    "name": "duration bound",
+    "valid": false,
+    "keyframesJson": "[{\"atMs\":0,\"angle\":0},{\"atMs\":60001,\"angle\":180}]"
+  },
+  {
+    "name": "angle bound",
+    "valid": false,
+    "keyframesJson": "[{\"atMs\":0,\"angle\":0},{\"atMs\":5000,\"angle\":181}]"
+  },
+  {
+    "name": "boolean",
+    "valid": false,
+    "keyframesJson": "[{\"atMs\":0,\"angle\":false},{\"atMs\":5000,\"angle\":180}]"
+  },
+  {
+    "name": "fractional time",
+    "valid": false,
+    "keyframesJson": "[{\"atMs\":0,\"angle\":0},{\"atMs\":1.5,\"angle\":180}]"
+  },
+  {
+    "name": "unknown field",
+    "valid": false,
+    "keyframesJson": "[{\"atMs\":0,\"angle\":0,\"ease\":\"out\"},{\"atMs\":5000,\"angle\":180}]"
+  }
+]
diff --git a/docs/adr/0025-foldable-apple-panels.md b/docs/adr/0025-foldable-apple-panels.md
index 08bc4659c1..f25ace6c96 100644
--- a/docs/adr/0025-foldable-apple-panels.md
+++ b/docs/adr/0025-foldable-apple-panels.md
@@ -144,6 +144,20 @@ Local headless tests verified all three poses, panel switching, and an inner-pan
 Physical devices, logged-out hosts, and hosted CI are unverified; Duo coverage remains local.
 Absence of a public setter did not establish that Device Hub was required.
 
+### Timed hinge trajectories
+
+`fold` accepts either a preset or 2–64 `{atMs, angle}` keyframes. Times start at zero and increase
+strictly up to 60 seconds; angles stay in 0–180°. A single simulator process interpolates linearly
+against a monotonic clock at approximately 60Hz, skipping missed frames instead of extending the
+timeline. Equal angles express holds. Preparation and final verification are outside motion time.
+Cancellation sends SIGTERM to simctl before a bounded SIGKILL escalation, allowing it to terminate
+the guest helper. Abruptly killing simctl can orphan the animation. A live cancellation at two
+seconds removed the guest process and left 67.9° unchanged beyond the five-second deadline. No automatic reset
+runs on cancellation. Final custom angles require a readback within 0.5° and the existing interior
+stability check; category agreement alone is insufficient. Shared golden fixtures define native
+and TypeScript validation. Refs expire on successful or interrupted mutation through the existing
+fold request policy. Hosted Duo tests remain local-only.
+
 ## Pose control: Device Hub's control, CoreDevice's verdict
 
 `agent-device fold` sets the pose, and the split above still holds: the press is not evidence,
diff --git a/packages/ad-script/src/internal/script-utils.ts b/packages/ad-script/src/internal/script-utils.ts
index b8491fa3aa..b30f3c6bd7 100644
--- a/packages/ad-script/src/internal/script-utils.ts
+++ b/packages/ad-script/src/internal/script-utils.ts
@@ -261,6 +261,9 @@ export function appendGenericActionScriptArgs(parts: string[], action: SessionAc
       ),
     );
   }
+  if (action.command === 'fold' && action.flags?.keyframes !== undefined) {
+    parts.push('--keyframes', formatScriptArg(action.flags.keyframes));
+  }
   appendScriptSeriesFlags(parts, action);
 }
 
@@ -290,6 +293,11 @@ export function parseReplaySeriesFlags(
       continue;
     }
     const nextArg = args[index + 1];
+    if (command === 'fold' && token === '--keyframes' && nextArg !== undefined) {
+      flags.keyframes = nextArg;
+      index += 1;
+      continue;
+    }
     if (isClickLikeCommand(command) && token === '--button' && nextArg !== undefined) {
       const clickButton = nextArg;
       if (clickButton === 'primary' || clickButton === 'secondary' || clickButton === 'middle') {
diff --git a/packages/ad-script/src/internal/script.ts b/packages/ad-script/src/internal/script.ts
index d5e972d5a2..c5f6970d04 100644
--- a/packages/ad-script/src/internal/script.ts
+++ b/packages/ad-script/src/internal/script.ts
@@ -406,7 +406,7 @@ function parseReplayScriptLine(line: string): SessionAction | null {
     return action;
   }
 
-  if (command === 'swipe' || command === 'type' || command === 'gesture') {
+  if (command === 'swipe' || command === 'type' || command === 'gesture' || command === 'fold') {
     const parsed = parseReplaySeriesFlags(command, args);
     Object.assign(action.flags, parsed.flags);
     action.positionals = parsed.positionals;
diff --git a/packages/command-registry/src/flag-definitions-action.ts b/packages/command-registry/src/flag-definitions-action.ts
index 72593a63db..7eed5127ff 100644
--- a/packages/command-registry/src/flag-definitions-action.ts
+++ b/packages/command-registry/src/flag-definitions-action.ts
@@ -3,6 +3,16 @@ import { RECORDING_SCOPE_VALUES } from '@agent-device/contracts/recording';
 import type { FlagDefinition } from './flag-types.ts';
 
 export const ACTION_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
+  {
+    key: 'keyframes',
+    names: ['--keyframes'],
+    type: 'string',
+    usageLabel: '--keyframes <json>',
+    usageDescription:
+      'Fold: timed {atMs, angle} keyframes; final atMs is motion duration (up to 60000ms)',
+    projectConfig: false,
+    recorded: true,
+  },
   {
     key: 'count',
     names: ['--count'],
diff --git a/packages/command-registry/src/flag-groups.ts b/packages/command-registry/src/flag-groups.ts
index 5a156a0a70..c8dc16507d 100644
--- a/packages/command-registry/src/flag-groups.ts
+++ b/packages/command-registry/src/flag-groups.ts
@@ -4,6 +4,8 @@ function flagKeys<const TKeys extends readonly FlagKey[]>(...keys: TKeys): TKeys
   return keys;
 }
 
+export const FOLD_FLAGS = flagKeys('keyframes');
+
 export const SNAPSHOT_FLAGS = flagKeys(
   'snapshotInteractiveOnly',
   'snapshotDepth',
diff --git a/packages/command-registry/src/timeout-policy.ts b/packages/command-registry/src/timeout-policy.ts
index 366c731fb5..29bddc8c1d 100644
--- a/packages/command-registry/src/timeout-policy.ts
+++ b/packages/command-registry/src/timeout-policy.ts
@@ -44,10 +44,10 @@ export const DEFAULT_TIMEOUT_POLICY: CommandTimeoutPolicy = {
 
 /**
  * `fold` spends up to four bounded CoreDevice hinge reads (`IOS_HINGE_ANGLE_TIMEOUT_MS` each on a
- * wedged host) after one macOS helper press with its own 30s deadline, which can sum past the
+ * wedged host) after a 30s helper build and up to 60s of timed HID motion, which can sum past the
  * standard envelope; the envelope covers that worst case with the usual margin.
  */
-const FOLD_REQUEST_TIMEOUT_MS = 150_000;
+const FOLD_REQUEST_TIMEOUT_MS = 210_000;
 
 export const FOLD_TIMEOUT_POLICY: CommandTimeoutPolicy = {
   budget: { source: 'none' },
diff --git a/packages/contracts/package.json b/packages/contracts/package.json
index 38a33e18aa..8a1000fb98 100644
--- a/packages/contracts/package.json
+++ b/packages/contracts/package.json
@@ -488,5 +488,8 @@
       "types": "./src/wait-runtime-plan.ts",
       "default": "./src/wait-runtime-plan.ts"
     }
+  },
+  "devDependencies": {
+    "fast-check": "^4.9.0"
   }
 }
diff --git a/packages/contracts/src/cli-flags.ts b/packages/contracts/src/cli-flags.ts
index 3a5ed79ae0..ea76cea5ae 100644
--- a/packages/contracts/src/cli-flags.ts
+++ b/packages/contracts/src/cli-flags.ts
@@ -106,6 +106,7 @@ export type CliFlags = CloudProviderProfileFields &
     /** Fill: publish the live text as a late-bound ${VAR} in a recorded .ad script. */
     recordAs?: string;
     durationMs?: number;
+    keyframes?: string;
     holdMs?: number;
     jitterPx?: number;
     pixels?: number;
diff --git a/packages/contracts/src/client-system.ts b/packages/contracts/src/client-system.ts
index de53f8a736..1bf5dd6ca5 100644
--- a/packages/contracts/src/client-system.ts
+++ b/packages/contracts/src/client-system.ts
@@ -5,7 +5,7 @@ import type { BackMode } from './back-mode.ts';
 import type { SelectorSnapshotCommandOptions } from './client-capture.ts';
 import type { DeviceCommandBaseOptions } from './client-connection.ts';
 import type { SettleCommandOptions } from './client-gesture.ts';
-import type { DeviceRotation, FoldPose } from './device-rotation.ts';
+import type { DeviceRotation, SetFoldPoseInput } from './device-rotation.ts';
 import type { TvRemoteButton } from './tv-remote.ts';
 
 export type WaitCommandTarget =
@@ -90,9 +90,7 @@ export type OrientationCommandOptions = DeviceCommandBaseOptions & {
   orientation: DeviceRotation;
 };
 
-export type FoldCommandOptions = DeviceCommandBaseOptions & {
-  pose: FoldPose;
-};
+export type FoldCommandOptions = DeviceCommandBaseOptions & SetFoldPoseInput;
 
 export type AppSwitcherCommandOptions = DeviceCommandBaseOptions;
 
diff --git a/packages/contracts/src/device-rotation-fold-input.test.ts b/packages/contracts/src/device-rotation-fold-input.test.ts
new file mode 100644
index 0000000000..55d05f5d01
--- /dev/null
+++ b/packages/contracts/src/device-rotation-fold-input.test.ts
@@ -0,0 +1,52 @@
+import { readFileSync } from 'node:fs';
+import { expect, test } from 'vitest';
+import fc from 'fast-check';
+import { parseFoldInput, parseFoldKeyframesJson } from './device-rotation.ts';
+
+const cases: Array<{ name: string; valid: boolean; keyframesJson: string }> = JSON.parse(
+  readFileSync(new URL('../../../contracts/fixtures/fold-keyframes.json', import.meta.url), 'utf8'),
+);
+test.each(cases)('keyframes: $name', ({ valid, keyframesJson }) => {
+  const parse = () => parseFoldKeyframesJson(keyframesJson);
+  if (valid) expect(parse()).toEqual(JSON.parse(keyframesJson));
+  else expect(parse).toThrow(expect.objectContaining({ code: 'INVALID_ARGS' }));
+});
+
+test('rejects conflicting intent, malformed JSON and nonfinite angles', () => {
+  const keyframes = [
+    { atMs: 0, angle: 0 },
+    { atMs: 10, angle: 180 },
+  ];
+  expect(() => parseFoldInput({ pose: 'open', keyframes })).toThrow();
+  expect(() => parseFoldKeyframesJson('[oops')).toThrow();
+  expect(() =>
+    parseFoldInput({ keyframes: [{ atMs: 0, angle: Number.NaN }, keyframes[1]] }),
+  ).toThrow();
+  expect(() =>
+    parseFoldInput({ keyframes: Array.from({ length: 65 }, (_, atMs) => ({ atMs, angle: 0 })) }),
+  ).toThrow();
+});
+
+test('valid timelines round-trip; duplicate timestamps are always rejected', () => {
+  fc.assert(
+    fc.property(
+      fc.array(
+        fc.record({
+          step: fc.integer({ min: 1, max: 900 }),
+          angle: fc.integer({ min: 0, max: 1800 }),
+        }),
+        { minLength: 2, maxLength: 64 },
+      ),
+      (values) => {
+        let time = 0;
+        const keyframes = values.map((value, index) => ({
+          atMs: index === 0 ? 0 : (time += value.step),
+          angle: value.angle / 10,
+        }));
+        expect(parseFoldKeyframesJson(JSON.stringify(keyframes))).toEqual(keyframes);
+        keyframes[1]!.atMs = 0;
+        expect(() => parseFoldInput({ keyframes })).toThrow();
+      },
+    ),
+  );
+});
diff --git a/packages/contracts/src/device-rotation.ts b/packages/contracts/src/device-rotation.ts
index e913d4b13d..b3e7abc3bc 100644
--- a/packages/contracts/src/device-rotation.ts
+++ b/packages/contracts/src/device-rotation.ts
@@ -119,3 +119,77 @@ export function parseFoldPose(input: string | undefined): FoldPose {
       throw new AppError('INVALID_ARGS', `Invalid fold pose: ${input}. Use ${FOLD_POSE_USAGE}.`);
   }
 }
+
+export type FoldKeyframe = Readonly<{ atMs: number; angle: number }>;
+export type SetFoldPoseInput =
+  | Readonly<{ pose: FoldPose; keyframes?: never }>
+  | Readonly<{ keyframes: readonly FoldKeyframe[]; pose?: never }>;
+
+export const MAX_FOLD_DURATION_MS = 60_000;
+export const MAX_FOLD_KEYFRAMES = 64;
+
+/** Validates both public structured input and decoded daemon intent before any mutation. */
+export function parseFoldInput(input: { pose?: unknown; keyframes?: unknown }): SetFoldPoseInput {
+  if (input.keyframes === undefined) {
+    if (input.pose === undefined)
+      throw new AppError('INVALID_ARGS', 'fold requires a pose or keyframes');
+    if (typeof input.pose !== 'string') {
+      throw new AppError('INVALID_ARGS', 'fold pose must be a string');
+    }
+    return { pose: parseFoldPose(input.pose) };
+  }
+  if (input.pose !== undefined)
+    throw new AppError('INVALID_ARGS', 'fold accepts either pose or keyframes');
+  return { keyframes: parseFoldKeyframes(input.keyframes) };
+}
+
+function parseFoldKeyframes(frames: unknown): readonly FoldKeyframe[] {
+  if (!Array.isArray(frames) || frames.length < 2 || frames.length > MAX_FOLD_KEYFRAMES) {
+    throw new AppError('INVALID_ARGS', `fold requires 2–${MAX_FOLD_KEYFRAMES} keyframes`);
+  }
+  const keyframes = frames.map(parseKeyframe);
+  if (
+    keyframes[0]!.atMs !== 0 ||
+    keyframes.some((frame, index) => index > 0 && frame.atMs <= keyframes[index - 1]!.atMs)
+  ) {
+    throw new AppError('INVALID_ARGS', 'Fold keyframes must start at 0ms and increase strictly');
+  }
+  return keyframes;
+}
+
+function isBoundedNumber(value: unknown, maximum: number): value is number {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= maximum;
+}
+
+function parseKeyframe(frame: unknown): FoldKeyframe {
+  if (!frame || typeof frame !== 'object' || Array.isArray(frame)) {
+    throw new AppError('INVALID_ARGS', 'Each fold keyframe requires atMs and angle');
+  }
+  const { atMs, angle } = frame as Record<string, unknown>;
+  if (Object.keys(frame).some((key) => key !== 'atMs' && key !== 'angle')) {
+    throw new AppError('INVALID_ARGS', 'Fold keyframes only accept atMs and angle');
+  }
+  if (!isBoundedNumber(atMs, MAX_FOLD_DURATION_MS) || !Number.isSafeInteger(atMs)) {
+    throw new AppError(
+      'INVALID_ARGS',
+      `Fold keyframe times must be integers from 0 to ${MAX_FOLD_DURATION_MS}ms`,
+    );
+  }
+  if (!isBoundedNumber(angle, 180)) {
+    throw new AppError('INVALID_ARGS', 'Fold keyframe angles must be finite numbers from 0 to 180');
+  }
+  return { atMs, angle };
+}
+
+export function parseFoldKeyframesJson(value: string): readonly FoldKeyframe[] {
+  let decoded: unknown;
+  try {
+    decoded = JSON.parse(value);
+  } catch {
+    throw new AppError(
+      'INVALID_ARGS',
+      '--keyframes requires a JSON array of {atMs, angle} objects',
+    );
+  }
+  return parseFoldKeyframes(decoded);
+}
diff --git a/packages/contracts/src/facades/device.ts b/packages/contracts/src/facades/device.ts
index 23b1ce5caa..d35b88114e 100644
--- a/packages/contracts/src/facades/device.ts
+++ b/packages/contracts/src/facades/device.ts
@@ -31,6 +31,10 @@ export type {
 export {
   DEVICE_ROTATIONS,
   DEVICE_ROTATION_SURFACE_INDEX,
+  MAX_FOLD_DURATION_MS,
+  MAX_FOLD_KEYFRAMES,
+  parseFoldInput,
+  parseFoldKeyframesJson,
   FOLD_POSES,
   FOLD_POSE_USAGE,
   deviceRotationOrientation,
@@ -39,7 +43,12 @@ export {
   parseDeviceRotation,
   parseFoldPose,
 } from '../device-rotation.ts';
-export type { DeviceRotation, FoldPose } from '../device-rotation.ts';
+export type {
+  DeviceRotation,
+  FoldPose,
+  FoldKeyframe,
+  SetFoldPoseInput,
+} from '../device-rotation.ts';
 export type { BootCommandResult, ShutdownCommandResult } from '../device.ts';
 export type {
   ProviderDeviceInstallOptions,
diff --git a/packages/contracts/src/fold-runtime.ts b/packages/contracts/src/fold-runtime.ts
index c20b3480e8..603c91cb05 100644
--- a/packages/contracts/src/fold-runtime.ts
+++ b/packages/contracts/src/fold-runtime.ts
@@ -1,13 +1,6 @@
-import type { FoldPose } from './device-rotation.ts';
+import type { FoldPose, SetFoldPoseInput } from './device-rotation.ts';
 import type { RuntimeOperationFact } from './platform-runtime.ts';
 
-/**
- * Neutral intent for one hinge pose change. `pose` is already parsed by the caller
- * (`parseFoldPose`); the operation names no command, request, session, or CLI flag, and it
- * carries no runner metadata because no runner takes part in a fold.
- */
-export type SetFoldPoseInput = Readonly<{ pose: FoldPose }>;
-
 /** Single source of truth for the discriminator the Apple owner sets and the MCP schema advertises. */
 export const FOLD_SCREEN_COORDINATE_SPACE = 'native-panel' as const;
 
diff --git a/packages/platform-apple/src/core/config.ts b/packages/platform-apple/src/core/config.ts
index efd7f58418..8f2ebbe96f 100644
--- a/packages/platform-apple/src/core/config.ts
+++ b/packages/platform-apple/src/core/config.ts
@@ -25,7 +25,7 @@ export const IOS_APPLE_DISPLAY_PROBE_TIMEOUT_MS = 5_000;
  */
 export const IOS_HINGE_ANGLE_STREAM_SECONDS = 5;
 export const IOS_HINGE_ANGLE_TIMEOUT_MS = 20_000;
-/** How many hinge reads a pressed Device Hub pose control gets to reach its pose before the pose is refused. */
+/** How many hinge reads a dispatched hinge request gets to reach its pose before the pose is refused. */
 export const IOS_FOLD_POSE_SETTLE_ATTEMPTS = 4;
 /** Two consecutive reads this close together mean the hinge has stopped moving. */
 export const IOS_FOLD_POSE_STABLE_DEGREES = 0.5;
diff --git a/packages/platform-apple/src/foldable/fixtures/keyframes.m b/packages/platform-apple/src/foldable/fixtures/keyframes.m
new file mode 100644
index 0000000000..ebdb0e5e47
--- /dev/null
+++ b/packages/platform-apple/src/foldable/fixtures/keyframes.m
@@ -0,0 +1,21 @@
+#define main fold_helper_main
+#import "Fold.m"
+#undef main
+int main(int argc, const char *argv[]) {
+  @autoreleasepool {
+    if (argc != 2) return 2;
+    NSArray *cases = [NSJSONSerialization JSONObjectWithData:[NSData dataWithContentsOfFile:@(argv[1])] options:0 error:NULL];
+    if (!cases) return 2;
+    for (NSDictionary *entry in cases) {
+      NSArray *frames = readFrames(entry[@"keyframesJson"]);
+      BOOL valid = frames != nil;
+      if (valid) {
+        for (NSDictionary *sample in entry[@"samples"]) {
+          if (fabs(angleAtTime(frames, [sample[@"atMs"] doubleValue]) - [sample[@"angle"] doubleValue]) > 1e-6) { fprintf(stderr, "%s at %sms\n", [entry[@"name"] UTF8String], [[sample[@"atMs"] description] UTF8String]); return 1; }
+        }
+      }
+      if (valid != [entry[@"valid"] boolValue]) { fprintf(stderr, "%s\n", [entry[@"name"] UTF8String]); return 1; }
+    }
+    return 0;
+  }
+}
diff --git a/packages/platform-apple/src/foldable/pose.test.ts b/packages/platform-apple/src/foldable/pose.test.ts
index ea4b631488..244f0b04e5 100644
--- a/packages/platform-apple/src/foldable/pose.test.ts
+++ b/packages/platform-apple/src/foldable/pose.test.ts
@@ -83,7 +83,7 @@ test('sends the simulator HID pose and reports the pose CoreDevice read back', a
   // The first read catches the hinge mid-animation; the verifier polls until it settles.
   mockHinge.mockResolvedValueOnce(95.7).mockResolvedValueOnce(180);
 
-  await expect(setAppleFoldPose(duo, 'open')).resolves.toEqual({
+  await expect(setAppleFoldPose(duo, { pose: 'open' })).resolves.toEqual({
     pose: 'open',
     hingeAngleDegrees: 180,
     screen: { display: 'LCD-1', coordinateSpace: 'native-panel', widthPt: 669, heightPt: 951 },
@@ -101,7 +101,7 @@ test('reports the closed outer panel in native points, not rotated to a snapshot
     .mockResolvedValueOnce(duoInventory('outer'));
   mockHinge.mockResolvedValue(0);
 
-  await expect(setAppleFoldPose(duo, 'closed')).resolves.toEqual({
+  await expect(setAppleFoldPose(duo, { pose: 'closed' })).resolves.toEqual({
     pose: 'closed',
     hingeAngleDegrees: 0,
     screen: { display: 'LCD', coordinateSpace: 'native-panel', widthPt: 466, heightPt: 678 },
@@ -126,7 +126,7 @@ test("reports native panel points regardless of the display's own currentOrienta
   mockInventory.mockResolvedValueOnce(duoInventory('inner')).mockResolvedValueOnce(rot0Inner);
   mockHinge.mockResolvedValue(180);
 
-  const result = await setAppleFoldPose(duo, 'open');
+  const result = await setAppleFoldPose(duo, { pose: 'open' });
   expect(result.screen).toEqual({
     display: 'LCD-1',
     coordinateSpace: 'native-panel',
@@ -143,7 +143,7 @@ test('omits the screen report when panel selection is ambiguous, never inventing
   mockInventory.mockResolvedValueOnce(bothLit).mockResolvedValueOnce(bothLit);
   mockHinge.mockResolvedValue(180);
 
-  await expect(setAppleFoldPose(duo, 'open')).resolves.toEqual({
+  await expect(setAppleFoldPose(duo, { pose: 'open' })).resolves.toEqual({
     pose: 'open',
     hingeAngleDegrees: 180,
   });
@@ -157,7 +157,7 @@ test('sends half-open and reports it only once the hinge has stopped', async ()
   // one stream after the press. Only the repeated 130° is the preset.
   mockHinge.mockResolvedValueOnce(175.1).mockResolvedValueOnce(130).mockResolvedValueOnce(130);
 
-  await expect(setAppleFoldPose(duo, 'half-open')).resolves.toMatchObject({
+  await expect(setAppleFoldPose(duo, { pose: 'half-open' })).resolves.toMatchObject({
     pose: 'half-open',
     hingeAngleDegrees: 130,
     screen: { display: 'LCD-1', coordinateSpace: 'native-panel', widthPt: 669, heightPt: 951 },
@@ -176,7 +176,9 @@ test('refuses half-open when the hinge was observed there but never came to rest
 
   // Every read classifies as half-open, so the requested category was observed; what is missing is
   // a hinge that stopped.
-  const failure = await setAppleFoldPose(duo, 'half-open').catch((error: unknown) => error);
+  const failure = await setAppleFoldPose(duo, { pose: 'half-open' }).catch(
+    (error: unknown) => error,
+  );
   expect(failure).toMatchObject({
     code: 'COMMAND_FAILED',
     details: expect.objectContaining({
@@ -206,7 +208,7 @@ test('refuses half-open when consecutive readings only straddle the open boundar
     .mockResolvedValueOnce(179)
     .mockResolvedValueOnce(178.8);
 
-  await expect(setAppleFoldPose(duo, 'half-open')).rejects.toMatchObject({
+  await expect(setAppleFoldPose(duo, { pose: 'half-open' })).rejects.toMatchObject({
     code: 'COMMAND_FAILED',
     details: expect.objectContaining({
       reason: 'fold-pose-unsettled',
@@ -228,7 +230,7 @@ test('refuses half-open as unverified when the last reading is another pose', as
     .mockResolvedValueOnce(120)
     .mockResolvedValueOnce(180);
 
-  await expect(setAppleFoldPose(duo, 'half-open')).rejects.toMatchObject({
+  await expect(setAppleFoldPose(duo, { pose: 'half-open' })).rejects.toMatchObject({
     code: 'COMMAND_FAILED',
     details: expect.objectContaining({
       reason: 'fold-pose-unverified',
@@ -244,7 +246,7 @@ test('refuses the pose when the hinge never reaches it, naming what CoreDevice s
   mockInventory.mockResolvedValueOnce(duoInventory('inner'));
   mockHinge.mockResolvedValue(180);
 
-  await expect(setAppleFoldPose(duo, 'closed')).rejects.toMatchObject({
+  await expect(setAppleFoldPose(duo, { pose: 'closed' })).rejects.toMatchObject({
     code: 'COMMAND_FAILED',
     details: expect.objectContaining({
       reason: 'fold-pose-unverified',
@@ -264,7 +266,7 @@ test('reports closed on one reading at the end stop, without waiting for a secon
   // confirmation. Routing `closed` through the half-open settle rule would want another read.
   mockHinge.mockResolvedValueOnce(95.7).mockResolvedValueOnce(0.4);
 
-  await expect(setAppleFoldPose(duo, 'closed')).resolves.toMatchObject({
+  await expect(setAppleFoldPose(duo, { pose: 'closed' })).resolves.toMatchObject({
     pose: 'closed',
     hingeAngleDegrees: 0.4,
   });
@@ -277,7 +279,7 @@ test('refuses before reading the hinge at all when the request is already cancel
   mockInventory.mockResolvedValueOnce(duoInventory('inner'));
 
   await expect(
-    setAppleFoldPose(duo, 'half-open', { signal: controller.signal }),
+    setAppleFoldPose(duo, { pose: 'half-open' }, { signal: controller.signal }),
   ).rejects.toMatchObject({ name: 'AbortError' });
   expect(mockHinge).not.toHaveBeenCalled();
 });
@@ -292,7 +294,7 @@ test('propagates a cancellation raised by a hinge read and stops polling', async
   });
 
   await expect(
-    setAppleFoldPose(duo, 'half-open', { signal: controller.signal }),
+    setAppleFoldPose(duo, { pose: 'half-open' }, { signal: controller.signal }),
   ).rejects.toMatchObject({ name: 'AbortError' });
   expect(mockHinge).toHaveBeenCalledTimes(1);
 });
@@ -300,7 +302,9 @@ test('propagates a cancellation raised by a hinge read and stops polling', async
 test('refuses a single-panel simulator before sending anything', async () => {
   mockInventory.mockResolvedValueOnce(buildInventory([panel({})]));
 
-  await expect(setAppleFoldPose({ ...duo, name: 'iPhone 17' }, 'open')).rejects.toMatchObject({
+  await expect(
+    setAppleFoldPose({ ...duo, name: 'iPhone 17' }, { pose: 'open' }),
+  ).rejects.toMatchObject({
     code: 'UNSUPPORTED_OPERATION',
     details: expect.objectContaining({ reason: 'single-panel-device' }),
   });
@@ -309,7 +313,9 @@ test('refuses a single-panel simulator before sending anything', async () => {
 });
 
 test('refuses a physical device and an unreadable display table before sending anything', async () => {
-  await expect(setAppleFoldPose({ ...duo, kind: 'device' }, 'open')).rejects.toMatchObject({
+  await expect(
+    setAppleFoldPose({ ...duo, kind: 'device' }, { pose: 'open' }),
+  ).rejects.toMatchObject({
     code: 'UNSUPPORTED_OPERATION',
   });
   mockInventory.mockResolvedValueOnce({
@@ -318,9 +324,60 @@ test('refuses a physical device and an unreadable display table before sending a
     ambiguous: false,
     unresolved: true,
   });
-  await expect(setAppleFoldPose(duo, 'open')).rejects.toMatchObject({
+  await expect(setAppleFoldPose(duo, { pose: 'open' })).rejects.toMatchObject({
     code: 'COMMAND_FAILED',
     details: expect.objectContaining({ hint: expect.stringContaining('displays') }),
   });
   expect(mockSend).not.toHaveBeenCalled();
 });
+
+test('a stable half-open angle cannot satisfy a different final keyframe angle', async () => {
+  mockInventory.mockResolvedValue(duoInventory('inner'));
+  mockHinge.mockResolvedValue(130);
+  await expect(
+    setAppleFoldPose(duo, {
+      keyframes: [
+        { atMs: 0, angle: 0 },
+        { atMs: 5000, angle: 100 },
+      ],
+    }),
+  ).rejects.toMatchObject({
+    code: 'COMMAND_FAILED',
+    details: { reason: 'fold-angle-unverified', targetAngleDegrees: 100, hingeAngleDegrees: 130 },
+  });
+});
+
+test('reports a custom final angle only after it reaches and holds that angle', async () => {
+  mockInventory.mockResolvedValue(duoInventory('inner'));
+  mockHinge.mockResolvedValueOnce(130).mockResolvedValueOnce(100).mockResolvedValueOnce(100);
+  const keyframes = [
+    { atMs: 0, angle: 0 },
+    { atMs: 5000, angle: 100 },
+  ];
+  await expect(setAppleFoldPose(duo, { keyframes })).resolves.toMatchObject({
+    pose: 'half-open',
+    hingeAngleDegrees: 100,
+  });
+  expect(mockSend).toHaveBeenCalledWith(duo.id, keyframes, undefined);
+});
+
+test.each([
+  [1.3, 0.9, 'closed'],
+  [178.7, 179.1, 'open'],
+  [0.8, 1.2, 'half-open'],
+])(
+  'custom target %s accepts stable readback %s across a category boundary',
+  async (target, observed, pose) => {
+    mockInventory.mockResolvedValue(duoInventory('inner'));
+    mockHinge.mockResolvedValue(Number(observed));
+    await expect(
+      setAppleFoldPose(duo, {
+        keyframes: [
+          { atMs: 0, angle: 100 },
+          { atMs: 100, angle: Number(target) },
+        ],
+      }),
+    ).resolves.toMatchObject({ pose, hingeAngleDegrees: observed });
+    expect(mockHinge).toHaveBeenCalledTimes(2);
+  },
+);
diff --git a/packages/platform-apple/src/foldable/pose.ts b/packages/platform-apple/src/foldable/pose.ts
index e8fdade1f8..03e8afe959 100644
--- a/packages/platform-apple/src/foldable/pose.ts
+++ b/packages/platform-apple/src/foldable/pose.ts
@@ -1,4 +1,8 @@
-import { foldPoseForHingeAngle, type FoldPose } from '@agent-device/contracts/device';
+import {
+  type SetFoldPoseInput,
+  foldPoseForHingeAngle,
+  type FoldPose,
+} from '@agent-device/contracts/device';
 import {
   FOLD_SCREEN_COORDINATE_SPACE,
   type FoldScreenReport,
@@ -30,25 +34,28 @@ const POSE_UNSETTLED_HINT =
 /** Sets a simulator hinge through guest HID and verifies the pose through CoreDevice. */
 export async function setAppleFoldPose(
   device: DeviceInfo,
-  pose: FoldPose,
+  input: SetFoldPoseInput,
   options: { signal?: AbortSignal } = {},
 ): Promise<SetFoldPoseResult> {
   options.signal?.throwIfAborted();
   requireSimulatorDevice(device, 'fold');
+  const intent = input;
+  const targetAngle = intent.keyframes?.at(-1)?.angle;
+  const pose = intent.pose ?? foldPoseForHingeAngle(targetAngle!)!;
   const inventory = await queryAppleDisplayInventory(device, { signal: options.signal });
   requireFoldableInventory(device, inventory);
 
-  await sendSimulatorFoldPose(device.id, pose, options.signal);
+  await sendSimulatorFoldPose(device.id, intent.keyframes ?? pose, options.signal);
   emitDiagnostic({
     level: 'info',
     phase: 'apple_fold_pose_dispatched',
     data: { deviceId: device.id, pose },
   });
 
-  const hingeAngleDegrees = await awaitHingePose(device, pose, options.signal);
+  const hingeAngleDegrees = await awaitHingePose(device, pose, options.signal, targetAngle);
   const litPanel = await readLitPanel(device, options.signal);
   return {
-    pose,
+    pose: foldPoseForHingeAngle(hingeAngleDegrees)!,
     hingeAngleDegrees,
     ...(litPanel ? { screen: screenReport(litPanel) } : {}),
   };
@@ -88,6 +95,7 @@ async function awaitHingePose(
   device: DeviceInfo,
   pose: FoldPose,
   signal: AbortSignal | undefined,
+  targetAngle?: number,
 ): Promise<number> {
   let observed: number | undefined;
   let previous: number | undefined;
@@ -95,16 +103,69 @@ async function awaitHingePose(
     signal?.throwIfAborted();
     previous = observed;
     observed = await readAppleHingeAngle(device, { signal });
-    if (foldPoseForHingeAngle(observed) !== pose) continue;
-    if (pose !== 'half-open') return observed;
-    if (previous !== undefined && isSettledHalfOpenPair(observed, previous)) {
-      return observed;
-    }
+    if (isVerifiedHingePose(observed, previous, pose, targetAngle)) return observed;
+  }
+  throw hingeVerificationError(device, pose, observed, previous, targetAngle);
+}
+
+function isVerifiedHingePose(
+  observed: number,
+  previous: number | undefined,
+  pose: FoldPose,
+  targetAngle: number | undefined,
+): boolean {
+  if (targetAngle !== undefined) return isSettledTargetAngle(observed, previous, targetAngle);
+  if (foldPoseForHingeAngle(observed) !== pose) return false;
+  return (
+    pose !== 'half-open' || (previous !== undefined && isSettledHalfOpenPair(observed, previous))
+  );
+}
+
+function isSettledTargetAngle(
+  observed: number,
+  previous: number | undefined,
+  targetAngle: number,
+): boolean {
+  if (!matchesTargetAngle(observed, targetAngle)) return false;
+  if (targetAngle === 0 || targetAngle === 180) return true;
+  return (
+    previous !== undefined &&
+    matchesTargetAngle(previous, targetAngle) &&
+    Math.abs(observed - previous) <= IOS_FOLD_POSE_STABLE_DEGREES
+  );
+}
+
+function matchesTargetAngle(
+  observed: number | undefined,
+  targetAngle: number | undefined,
+): boolean {
+  return (
+    targetAngle === undefined ||
+    (observed !== undefined && Math.abs(observed - targetAngle) <= IOS_FOLD_POSE_STABLE_DEGREES)
+  );
+}
+
+function hingeVerificationError(
+  device: DeviceInfo,
+  pose: FoldPose,
+  observed: number | undefined,
+  previous: number | undefined,
+  targetAngle: number | undefined,
+): AppError {
+  if (!matchesTargetAngle(observed, targetAngle)) {
+    return new AppError('COMMAND_FAILED', 'The hinge did not reach the final keyframe angle', {
+      reason: 'fold-angle-unverified',
+      targetAngleDegrees: targetAngle,
+      hingeAngleDegrees: observed,
+      deviceId: device.id,
+    });
   }
+  if (targetAngle !== undefined && observed !== undefined)
+    return unsettledPoseError(device, foldPoseForHingeAngle(observed)!, observed, previous);
   if (observed !== undefined && pose === 'half-open' && foldPoseForHingeAngle(observed) === pose) {
-    throw unsettledHalfOpenPoseError(device, observed, previous);
+    return unsettledPoseError(device, pose, observed, previous);
   }
-  throw unverifiedPoseError(device, pose, observed);
+  return unverifiedPoseError(device, pose, observed);
 }
 
 /**
@@ -142,16 +203,17 @@ function unverifiedPoseError(device: DeviceInfo, pose: FoldPose, observed: numbe
 }
 
 /** The hinge was seen `half-open` and never came to rest inside that interval. */
-function unsettledHalfOpenPoseError(
+function unsettledPoseError(
   device: DeviceInfo,
+  pose: FoldPose,
   observed: number,
   previous: number | undefined,
 ) {
   return new AppError(
     'COMMAND_FAILED',
-    `${device.name} was observed half-open at ${observed}° but did not settle: ${IOS_FOLD_POSE_SETTLE_ATTEMPTS} hinge reads never held two consecutive half-open angles within ${IOS_FOLD_POSE_STABLE_DEGREES}° of each other`,
+    `${device.name} was observed ${pose} at ${observed}° but did not settle: ${IOS_FOLD_POSE_SETTLE_ATTEMPTS} hinge reads never held two consecutive angles within ${IOS_FOLD_POSE_STABLE_DEGREES}° of each other`,
     {
-      ...hingePoseDetails(device, 'half-open', observed),
+      ...hingePoseDetails(device, pose, observed),
       reason: 'fold-pose-unsettled',
       ...(previous === undefined ? {} : { previousHingeAngleDegrees: previous }),
       hint: POSE_UNSETTLED_HINT,
diff --git a/packages/platform-apple/src/foldable/runtime.ts b/packages/platform-apple/src/foldable/runtime.ts
index 8067e8c01c..c5310f0b31 100644
--- a/packages/platform-apple/src/foldable/runtime.ts
+++ b/packages/platform-apple/src/foldable/runtime.ts
@@ -1,7 +1,5 @@
-import {
-  foldRuntimeOperationFacts,
-  type SetFoldPoseInput,
-} from '@agent-device/contracts/fold-runtime';
+import type { SetFoldPoseInput } from '@agent-device/contracts/device';
+import { foldRuntimeOperationFacts } from '@agent-device/contracts/fold-runtime';
 import type { RuntimeOperationFact } from '@agent-device/contracts/platform-runtime';
 import { whenAdmitted } from '@agent-device/contracts/platform-runtime';
 import { resolveDeviceAppleOs, type DeviceInfo } from '@agent-device/kernel/device';
@@ -13,7 +11,7 @@ const available = Object.freeze({ available: true } as const);
 const foldKindUnavailable = Object.freeze({
   available: false,
   reason: 'unsupported-device-kind',
-  hint: 'fold is supported on foldable iPhone simulators driven by Xcode Device Hub; a physical device is folded by hand.',
+  hint: 'fold is supported on foldable iPhone simulators controlled through simulator HID; a physical device is folded by hand.',
 } as const);
 const foldOsUnavailable = Object.freeze({
   available: false,
@@ -44,7 +42,7 @@ export function createAppleFoldableOperations(params: { device: DeviceInfo; sign
   return whenAdmitted(appleFoldableFacts(device).setFoldPose, () => ({
     setFoldPose: async (input: SetFoldPoseInput) => {
       signal.throwIfAborted();
-      return await setAppleFoldPose(device, input.pose, { signal });
+      return await setAppleFoldPose(device, input, { signal });
     },
   }));
 }
diff --git a/packages/platform-apple/src/foldable/simulator-hid-native.test.ts b/packages/platform-apple/src/foldable/simulator-hid-native.test.ts
new file mode 100644
index 0000000000..6658a46ce2
--- /dev/null
+++ b/packages/platform-apple/src/foldable/simulator-hid-native.test.ts
@@ -0,0 +1,45 @@
+import path from 'node:path';
+import { beforeAll, describe, expect, test } from 'vitest';
+import { runCmd } from '@agent-device/host-kit/command';
+import { findProjectRoot } from '@agent-device/host-kit/version';
+import { mkdtempForTest } from '../__tests__/tmp-dir.ts';
+
+describe.skipIf(process.platform !== 'darwin')('native keyframes', () => {
+  let binary: string;
+  beforeAll(async () => {
+    const root = findProjectRoot();
+    const directory = await mkdtempForTest('fold-native-');
+    binary = path.join(directory, 'keyframes');
+    const build = await runCmd(
+      'xcrun',
+      [
+        '--sdk',
+        'macosx',
+        'clang',
+        '-fobjc-arc',
+        '-Wall',
+        '-Wextra',
+        '-Werror',
+        '-framework',
+        'Foundation',
+        '-framework',
+        'IOKit',
+        '-I',
+        path.join(root, 'apple/fold-helper'),
+        path.join(import.meta.dirname, 'fixtures/keyframes.m'),
+        '-o',
+        binary,
+      ],
+      { allowFailure: true, timeoutMs: 30_000 },
+    );
+    expect(build.exitCode, build.stderr).toBe(0);
+  }, 40_000);
+  test('validation agrees with the shared golden table', async () => {
+    const checked = await runCmd(
+      binary,
+      [path.join(findProjectRoot(), 'contracts/fixtures/fold-keyframes.json')],
+      { allowFailure: true, timeoutMs: 5_000 },
+    );
+    expect(checked.exitCode, checked.stderr).toBe(0);
+  });
+});
diff --git a/packages/platform-apple/src/foldable/simulator-hid.test.ts b/packages/platform-apple/src/foldable/simulator-hid.test.ts
index db0f60d879..56f5aaafce 100644
--- a/packages/platform-apple/src/foldable/simulator-hid.test.ts
+++ b/packages/platform-apple/src/foldable/simulator-hid.test.ts
@@ -45,3 +45,26 @@ test.each(['success', 'build', 'dispatch', 'cancel'] as const)(
     expect(existsSync(path.dirname(binary))).toBe(false);
   },
 );
+
+test('streams all keyframes in one process with a duration-derived timeout', async () => {
+  const keyframes = [
+    { atMs: 0, angle: 0 },
+    { atMs: 60000, angle: 100 },
+  ];
+  let dispatches = 0;
+  await withAppleToolProvider(
+    createLocalAppleToolProvider({
+      runCommand: async (_command, args, options) => {
+        if (args[0] === 'simctl') {
+          dispatches++;
+          expect(JSON.parse(args.at(-1)!)).toEqual(keyframes);
+          expect(options?.timeoutMs).toBe(70000);
+          expect(options?.kill).toEqual({ signal: 'SIGTERM', graceMs: 1000 });
+        }
+        return { stdout: '', stderr: '', exitCode: 0 };
+      },
+    }),
+    () => sendSimulatorFoldPose('duo', keyframes),
+  );
+  expect(dispatches).toBe(1);
+});
diff --git a/packages/platform-apple/src/foldable/simulator-hid.ts b/packages/platform-apple/src/foldable/simulator-hid.ts
index e79382d60f..ec5e14f179 100644
--- a/packages/platform-apple/src/foldable/simulator-hid.ts
+++ b/packages/platform-apple/src/foldable/simulator-hid.ts
@@ -1,5 +1,5 @@
 import path from 'node:path';
-import type { FoldPose } from '@agent-device/contracts/device';
+import type { FoldKeyframe, FoldPose } from '@agent-device/contracts/device';
 import { AppError } from '@agent-device/kernel/errors';
 import { execFailureDetails } from '@agent-device/host-kit/command';
 import { makeHostTemporaryDirectory, removeHostDirectory } from '@agent-device/host-kit/host-file';
@@ -9,7 +9,7 @@ import { runXcrun } from '../core/tool-provider.ts';
 /** Compiles for the selected Xcode and dispatches inside exactly the requested simulator. */
 export async function sendSimulatorFoldPose(
   udid: string,
-  pose: FoldPose,
+  pose: FoldPose | readonly FoldKeyframe[],
   signal?: AbortSignal,
 ): Promise<void> {
   signal?.throwIfAborted();
@@ -47,9 +47,13 @@ export async function sendSimulatorFoldPose(
       );
     }
     signal?.throwIfAborted();
-    const sent = await runXcrun(['simctl', 'spawn', udid, binary, pose], {
+    const durationMs = typeof pose === 'string' ? 0 : pose.at(-1)!.atMs;
+    const payload = typeof pose === 'string' ? pose : JSON.stringify(pose);
+    const sent = await runXcrun(['simctl', 'spawn', udid, binary, payload], {
       signal,
-      timeoutMs: 10_000,
+      timeoutMs: durationMs + 10_000,
+      // simctl must forward termination to the guest before the host kills it.
+      kill: { signal: 'SIGTERM', graceMs: 1000 },
       allowFailure: true,
     });
     if (sent.exitCode !== 0) {
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index c5b7d73020..5eecf5bf5c 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -252,6 +252,10 @@ importers:
       '@agent-device/kernel':
         specifier: workspace:*
         version: link:../kernel
+    devDependencies:
+      fast-check:
+        specifier: ^4.9.0
+        version: 4.9.0
 
   packages/device-selection:
     dependencies:
diff --git a/scripts/integration-progress-model.ts b/scripts/integration-progress-model.ts
index 4e262b174c..bd6d44992f 100644
--- a/scripts/integration-progress-model.ts
+++ b/scripts/integration-progress-model.ts
@@ -156,6 +156,7 @@ function summarizeProviderScenarioFlagCoverage(files) {
     ['intervalMs', 'repeated press interval'],
     ['delayMs', 'typing/fill delay'],
     ['recordAs', 'parameterized fill publication for recorded scripts'],
+    ['keyframes', 'timed fold trajectory'],
     ['durationMs', 'scroll, gesture, and TV remote duration'],
     ['holdMs', 'press hold duration'],
     ['jitterPx', 'press jitter'],
diff --git a/src/__tests__/command-descriptor-timeout-policy.test.ts b/src/__tests__/command-descriptor-timeout-policy.test.ts
index bafd275314..89888805d6 100644
--- a/src/__tests__/command-descriptor-timeout-policy.test.ts
+++ b/src/__tests__/command-descriptor-timeout-policy.test.ts
@@ -145,7 +145,7 @@ test('request envelopes deviating from the default are bounded, reviewed sets',
     longpress: 210_000,
     // fold: one macOS helper press (30s) plus up to four bounded CoreDevice hinge reads (20s
     // each on a wedged host) can pass the default envelope; the policy covers that worst case.
-    fold: 150_000,
+    fold: 210_000,
     // #1774: base allocation budget (300s) + client/daemon race margin (30s).
     lease_allocate: 330_000,
     test: 'unbounded',
diff --git a/src/commands/command-contract.ts b/src/commands/command-contract.ts
index 45054fc612..f01c8f2612 100644
--- a/src/commands/command-contract.ts
+++ b/src/commands/command-contract.ts
@@ -7,6 +7,8 @@ export type JsonSchema = {
   required?: readonly string[];
   additionalProperties?: boolean | JsonSchema;
   items?: JsonSchema;
+  minItems?: number;
+  maxItems?: number;
   prefixItems?: readonly JsonSchema[];
   oneOf?: readonly JsonSchema[];
   not?: JsonSchema;
diff --git a/src/commands/schema/cli-help.ts b/src/commands/schema/cli-help.ts
index 8c4674efd8..9afafa45dd 100644
--- a/src/commands/schema/cli-help.ts
+++ b/src/commands/schema/cli-help.ts
@@ -750,6 +750,8 @@ Changing the pose:
   agent-device fold closed | half-open | open
   fold sends a private HID hinge event inside the selected simulator and then reads the hinge angle back from CoreDevice until it agrees: closed is 0 degrees, open is 180, and half-open is any angle between them (requested at 130 degrees). An angle in that interval only proves the category, so half-open is reported once two consecutive readings both fall inside it and agree within 0.5 degrees. The response reports the verified pose, the hinge angle, and the panel the device now lights with its native panel point size, marked coordinateSpace "native-panel". That point size is the panel's own geometry, not the next snapshot's viewport, so it cannot place a tap: the active app window can differ (a 669x951 inner panel hosts a 951x669 window). A hinge whose last reading is some other pose fails with COMMAND_FAILED and reason fold-pose-unverified, naming the angle CoreDevice still reports; a hinge seen half-open but never at rest fails with reason fold-pose-unsettled, naming the observed and previous angles. A single-panel simulator fails with UNSUPPORTED_OPERATION.
   Expect a fold to take 10-16 seconds: each hinge read is a five-second devicectl stream, and half-open waits for the hinge to stop moving. Re-snapshot after every fold; refs and coordinates from before it are stale, and the command's message says so.
+  Timed motion: fold --keyframes '[{"atMs":0,"angle":0},{"atMs":5000,"angle":180}]'. Use 2–64 frames starting at 0ms, increasing integer timestamps up to 60000ms, and angles from 0 to 180. The last timestamp sets motion duration, excluding setup and verification. Equal angles hold; cancellation stops motion. See the fold examples in the command and Node API documentation for trajectories.
+
   Requirements: an iOS simulator session on a foldable device and an Xcode toolchain with the iOS simulator SDK and foldable HID support (verified on Xcode 27.1). Device Hub and host Accessibility permission are not required. The command builds a small temporary helper with the selected Xcode and runs it through simctl spawn for the session UDID; build or dispatch failures are reported without a UI fallback. The app under test reads the resulting pose as UIHinge.status.
   If a task asserts behavior for more than one pose, fold to each pose and re-snapshot, and report which poses the run covered.`,
   },
diff --git a/src/commands/system/index.test.ts b/src/commands/system/index.test.ts
index 408c7690a9..deb81e3c11 100644
--- a/src/commands/system/index.test.ts
+++ b/src/commands/system/index.test.ts
@@ -181,7 +181,7 @@ describe('system command interface', () => {
   test('fold reader and writer reject a missing or unknown pose', () => {
     expectInvalidArgs(() => foldCliReader([], flags()), 'fold requires a pose');
     expectInvalidArgs(() => foldCliReader(['sideways'], flags()), 'Invalid fold pose');
-    expectInvalidArgs(() => foldDaemonWriter({}), 'fold requires pose');
+    expectInvalidArgs(() => foldDaemonWriter({}), 'fold requires a pose');
   });
 
   test('keyboard reader maps aliases and validates arguments', () => {
@@ -270,3 +270,18 @@ describe('system command interface', () => {
     expectInvalidArgs(() => tvRemoteCliReader(['blue'], flags()), 'button must be one of');
   });
 });
+
+test('fold keyframes survive CLI and daemon projection without a preset', () => {
+  const keyframes = [
+    { atMs: 0, angle: 0 },
+    { atMs: 5000, angle: 180 },
+  ];
+  const input = foldCliReader([], flags({ keyframes: JSON.stringify(keyframes) }));
+  expect(input).toMatchObject({ keyframes });
+  expect(foldDaemonWriter(input)).toMatchObject({
+    command: 'fold',
+    positionals: [],
+    options: { keyframes: JSON.stringify(keyframes) },
+  });
+  expect(() => foldCliReader(['open'], flags({ keyframes: JSON.stringify(keyframes) }))).toThrow();
+});
diff --git a/src/commands/system/index.ts b/src/commands/system/index.ts
index 9626f13210..448d3b51c0 100644
--- a/src/commands/system/index.ts
+++ b/src/commands/system/index.ts
@@ -1,10 +1,15 @@
+import { FOLD_FLAGS } from '@agent-device/command-registry/flag-groups';
 import type { ClipboardCommandOptions } from '@agent-device/contracts/client';
 import {
+  type FoldKeyframe,
+  MAX_FOLD_DURATION_MS,
+  MAX_FOLD_KEYFRAMES,
+  parseFoldInput,
+  parseFoldKeyframesJson,
   DEVICE_ROTATIONS,
   FOLD_POSES,
   FOLD_POSE_USAGE,
   parseDeviceRotation,
-  parseFoldPose,
 } from '@agent-device/contracts/device';
 import { type BackMode, BACK_MODES } from '@agent-device/contracts/back-mode';
 import {
@@ -23,7 +28,14 @@ import {
   requiredDaemonString,
 } from '../cli-grammar/common.ts';
 import type { CliReader, DaemonWriter } from '../cli-grammar/types.ts';
-import { enumField, integerField, requiredField, stringField } from '../command-input.ts';
+import {
+  enumField,
+  integerField,
+  requiredField,
+  stringField,
+  jsonSchemaField,
+  readFieldInput,
+} from '../command-input.ts';
 import { compactRecord } from '../input-readers.ts';
 import {
   defineCommandFacet,
@@ -60,7 +72,7 @@ const homeCommandDescription =
   'Send the selected device to its home screen. This leaves the app session open but moves the foreground away from the app.';
 const orientationCommandDescription = 'Set device orientation on iOS and Android';
 const foldCommandDescription =
-  'Fold or unfold a foldable iPhone simulator (iPhone Duo) into the closed, half-open, or open pose by sending a simulator HID hinge event, then read the hinge angle back from CoreDevice to confirm it. A pose change moves the app to a different panel with a different point size, so every ref and coordinate from before it is stale: re-snapshot after this command. Taps, long presses, and scrolling target the app window on its current panel in closed, half-open, and open poses. Simulator-only; requires the iOS simulator SDK; Device Hub and host Accessibility permission are not required.';
+  'Fold or unfold a foldable iPhone simulator (iPhone Duo) into the closed, half-open, or open pose, or follow timestamped angle keyframes, by sending a simulator HID hinge event, then read the hinge angle back from CoreDevice to confirm it. A pose change moves the app to a different panel with a different point size, so every ref and coordinate from before it is stale: re-snapshot after this command. Taps, long presses, and scrolling target the app window on its current panel in closed, half-open, and open poses. Simulator-only; requires the iOS simulator SDK; Device Hub and host Accessibility permission are not required.';
 const appSwitcherCommandDescription =
   'Open the device app switcher to inspect or change foreground apps. This changes the visible system UI and may move focus away from the current app.';
 const keyboardCommandDescription =
@@ -85,14 +97,48 @@ const orientationCommandMetadata = defineFieldCommandMetadata(
   },
 );
 
-const foldCommandMetadata = defineFieldCommandMetadata(FOLD_COMMAND_NAME, foldCommandDescription, {
-  pose: requiredField(
-    enumField(
-      FOLD_POSES,
-      'The hinge pose to reach: closed lights the outer panel; half-open (130 degrees) and open light the inner panel.',
-    ),
-  ),
-});
+const foldFields = {
+  pose: enumField(FOLD_POSES, 'Instant preset; mutually exclusive with keyframes.'),
+  keyframes: jsonSchemaField<readonly FoldKeyframe[]>({
+    type: 'array',
+    minItems: 2,
+    maxItems: MAX_FOLD_KEYFRAMES,
+    description:
+      'Piecewise-linear hinge motion. Start at 0ms; strictly increasing timestamps, up to 60000ms. Repeated angles create holds. Mutually exclusive with pose.',
+    items: {
+      type: 'object',
+      required: ['atMs', 'angle'],
+      additionalProperties: false,
+      properties: {
+        atMs: { type: 'integer', minimum: 0, maximum: MAX_FOLD_DURATION_MS },
+        angle: { type: 'number', minimum: 0, maximum: 180 },
+      },
+    },
+  }),
+};
+const foldFieldMetadata = defineFieldCommandMetadata(
+  FOLD_COMMAND_NAME,
+  foldCommandDescription,
+  foldFields,
+  {
+    readInput: (input) => {
+      const fields = readFieldInput(input, foldFields);
+      const { pose, keyframes, ...common } = fields;
+      return { ...common, ...parseFoldInput({ pose, keyframes }) };
+    },
+  },
+);
+
+const foldCommandMetadata = {
+  ...foldFieldMetadata,
+  inputSchema: {
+    ...foldFieldMetadata.inputSchema,
+    oneOf: [
+      { required: ['pose'], not: { required: ['keyframes'] } },
+      { required: ['keyframes'], not: { required: ['pose'] } },
+    ],
+  },
+};
 
 const keyboardCommandMetadata = defineFieldCommandMetadata(
   KEYBOARD_COMMAND_NAME,
@@ -139,8 +185,9 @@ const orientationCliSchema = {
 } as const satisfies CommandSchemaOverride;
 
 const foldCliSchema = {
-  usageOverride: `fold <${FOLD_POSE_USAGE}>`,
-  positionalArgs: ['pose'],
+  usageOverride: `fold [${FOLD_POSE_USAGE}]`,
+  positionalArgs: ['pose?'],
+  allowedFlags: FOLD_FLAGS,
 } as const satisfies CommandSchemaOverride;
 
 const keyboardCliSchema = {
@@ -174,7 +221,10 @@ export const orientationCliReader: CliReader = (positionals, flags) => ({
 
 export const foldCliReader: CliReader = (positionals, flags) => ({
   ...commonInputFromFlags(flags),
-  pose: parseFoldPose(positionals[0]),
+  ...parseFoldInput({
+    pose: positionals[0],
+    keyframes: flags.keyframes === undefined ? undefined : parseFoldKeyframesJson(flags.keyframes),
+  }),
 });
 
 export const keyboardCliReader: CliReader = (positionals, flags) => ({
@@ -202,9 +252,13 @@ export const orientationDaemonWriter: DaemonWriter = direct(ORIENTATION_COMMAND_
   requiredDaemonString(input.orientation, 'orientation requires orientation'),
 ]);
 
-export const foldDaemonWriter: DaemonWriter = direct(FOLD_COMMAND_NAME, (input) => [
-  requiredDaemonString(input.pose, 'fold requires pose'),
-]);
+export const foldDaemonWriter: DaemonWriter = (input) => {
+  const fold = parseFoldInput(input);
+  return request(FOLD_COMMAND_NAME, fold.pose ? [fold.pose] : [], {
+    ...input,
+    keyframes: fold.keyframes ? JSON.stringify(fold.keyframes) : undefined,
+  });
+};
 
 export const keyboardDaemonWriter: DaemonWriter = direct(KEYBOARD_COMMAND_NAME, (input) =>
   optionalString(input.action),
diff --git a/src/daemon/__tests__/fold-runtime.test.ts b/src/daemon/__tests__/fold-runtime.test.ts
index 3cbc78f7ed..ed41d0d900 100644
--- a/src/daemon/__tests__/fold-runtime.test.ts
+++ b/src/daemon/__tests__/fold-runtime.test.ts
@@ -1,3 +1,4 @@
+import { recordActionEntry } from '../session-action-recorder.ts';
 import { expect, test, vi } from 'vitest';
 
 import {
@@ -160,3 +161,40 @@ test('rejects an unavailable exact-owner fact before binding', async () => {
     unavailable,
   });
 });
+
+test('passes the validated timed intent to the admitted fold owner', async () => {
+  const setFoldPose = vi.fn(async (): Promise<SetFoldPoseResult> => ({
+    pose: 'half-open',
+    hingeAngleDegrees: 100,
+  }));
+  const harness = runtimeHarness(available, setFoldPose);
+  const keyframes = [
+    { atMs: 0, angle: 0 },
+    { atMs: 5000, angle: 100 },
+  ];
+  const resolved = await resolveBoundFoldRuntime({
+    device: testDevice,
+    positionals: [],
+    keyframes: JSON.stringify(keyframes),
+    inspectFacts: harness.inspectFacts,
+    bindDevice: harness.bindDevice,
+  });
+  expect(resolved.ok).toBe(true);
+  if (!resolved.ok) return;
+  expect(await resolved.execute(foldExecutionParams([]))).toMatchObject({ hingeAngleDegrees: 100 });
+  expect(setFoldPose).toHaveBeenCalledWith({ keyframes });
+});
+
+test('recording preserves the timeline for replay', () => {
+  const keyframes = JSON.stringify([
+    { atMs: 0, angle: 0 },
+    { atMs: 5000, angle: 180 },
+  ]);
+  const action = recordActionEntry(makeSession('fold-recording'), {
+    command: 'fold',
+    positionals: [],
+    flags: { keyframes },
+    result: { pose: 'open', hingeAngleDegrees: 180 },
+  });
+  expect(action?.flags?.keyframes).toBe(keyframes);
+});
diff --git a/src/daemon/fold-runtime.ts b/src/daemon/fold-runtime.ts
index 179ea15a73..593df43cfe 100644
--- a/src/daemon/fold-runtime.ts
+++ b/src/daemon/fold-runtime.ts
@@ -1,5 +1,10 @@
-import { parseFoldPose, type FoldPose } from '@agent-device/contracts/device';
-import type { SetFoldPoseInput } from '@agent-device/contracts/fold-runtime';
+import {
+  type SetFoldPoseInput,
+  parseFoldPose,
+  parseFoldInput,
+  parseFoldKeyframesJson,
+  type FoldPose,
+} from '@agent-device/contracts/device';
 import { foldRuntimeUse } from '@agent-device/contracts/platform-runtime-operations';
 import type { BoundDeviceRuntime } from '@agent-device/contracts/platform-runtime';
 import type { DeviceInfo } from '@agent-device/kernel/device';
@@ -21,9 +26,16 @@ export async function resolveBoundFoldRuntime(
   params: {
     device: DeviceInfo;
     positionals: readonly string[];
+    keyframes?: string;
   } & RuntimeAdmissionBindings,
 ): Promise<ResolvedGenericExecution> {
-  const pose = readRequestedFoldPose(params.positionals);
+  const input =
+    params.keyframes === undefined
+      ? { pose: readRequestedFoldPose(params.positionals) }
+      : parseFoldInput({
+          pose: params.positionals[0],
+          keyframes: parseFoldKeyframesJson(params.keyframes),
+        });
   return await resolveBoundGenericRuntime(
     {
       command: 'fold',
@@ -32,7 +44,7 @@ export async function resolveBoundFoldRuntime(
       inspectFacts: params.inspectFacts,
       bindDevice: params.bindDevice,
     },
-    (runtime) => executeSetFoldPose(runtime, pose),
+    (runtime) => executeSetFoldPose(runtime, input),
   );
 }
 
@@ -43,9 +55,8 @@ export async function resolveBoundFoldRuntime(
  */
 async function executeSetFoldPose(
   runtime: BoundDeviceRuntime<typeof foldRuntimeUse>,
-  requestedPose: FoldPose,
+  input: SetFoldPoseInput,
 ): Promise<Record<string, unknown>> {
-  const input: SetFoldPoseInput = { pose: requestedPose };
   const result = await runtime.operations.setFoldPose(input);
   const screen = result.screen;
   return {
diff --git a/src/daemon/generic-runtime-execution.ts b/src/daemon/generic-runtime-execution.ts
index 6c4f748332..c0b631b467 100644
--- a/src/daemon/generic-runtime-execution.ts
+++ b/src/daemon/generic-runtime-execution.ts
@@ -80,6 +80,7 @@ export async function resolveGenericRuntimeExecution(
       });
     case 'fold':
       return await resolveBoundFoldRuntime({
+        keyframes: params.req.flags?.keyframes,
         device: params.session.device,
         positionals: params.req.positionals ?? [],
         inspectFacts: params.inspectFacts,
diff --git a/test/integration/provider-scenarios/ios-fold.test.ts b/test/integration/provider-scenarios/ios-fold.test.ts
new file mode 100644
index 0000000000..7ba5beef58
--- /dev/null
+++ b/test/integration/provider-scenarios/ios-fold.test.ts
@@ -0,0 +1,92 @@
+import { formatPortableActionLine, parseReplayScriptDetailed } from '@agent-device/ad-script';
+import { recordActionEntry } from '../../../src/daemon/session-action-recorder.ts';
+import { assertRpcOk } from './assertions.ts';
+import { makeIosAppSession } from '../../../src/__tests__/test-utils/session-factories.ts';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import { test } from 'vitest';
+import { createProviderScenarioHarness } from './harness.ts';
+import { createRecordingAppleToolProvider } from './providers.ts';
+import { PROVIDER_SCENARIO_IOS_SIMULATOR } from './fixtures.ts';
+
+test('timed fold keyframes reach simulator HID through the public client and daemon', async () => {
+  const trajectory = [
+    { atMs: 0, angle: 0 },
+    { atMs: 5000, angle: 100 },
+  ];
+  const ok = { stdout: '', stderr: '', exitCode: 0 };
+  let angle = 0;
+  const tool = createRecordingAppleToolProvider({
+    simctl: async (args, options) => {
+      assert.equal(args[0], 'spawn');
+      assert.equal(args[1], PROVIDER_SCENARIO_IOS_SIMULATOR.id);
+      assert.deepEqual(JSON.parse(args[3]!), trajectory);
+      assert.equal(options?.timeoutMs, 15000);
+      angle = 100;
+      return ok;
+    },
+    devicectl: async (args) => {
+      if (args.includes('hinge-angle')) return { ...ok, stdout: `Angle: ${angle}°`, exitCode: 1 };
+      assert.ok(args.includes('displays'));
+      const displays = [0, 1].map((displayId) => ({
+        name: `LCD-${displayId}`,
+        displayId,
+        nativeSize: [2007, 2853],
+        pointScale: 3,
+        type: { integrated: {} },
+        active: displayId === 1,
+      }));
+      fs.writeFileSync(
+        args[args.indexOf('--json-output') + 1]!,
+        JSON.stringify({ result: { displays } }),
+      );
+      return ok;
+    },
+  });
+  let builds = 0;
+  const daemon = await createProviderScenarioHarness({
+    deviceInventoryProvider: async () => [PROVIDER_SCENARIO_IOS_SIMULATOR],
+    appleToolProvider: () => ({
+      ...tool.provider,
+      runCommand: async (command, args) => {
+        assert.equal(command, 'xcrun');
+        assert.ok(args.includes('clang'));
+        builds++;
+        return ok;
+      },
+    }),
+  });
+  daemon.setSession(
+    'default',
+    makeIosAppSession('default', { device: PROVIDER_SCENARIO_IOS_SIMULATOR }),
+  );
+  try {
+    const result = await daemon.client().command.fold({
+      platform: 'ios',
+      udid: PROVIDER_SCENARIO_IOS_SIMULATOR.id,
+      keyframes: trajectory,
+    });
+    assert.equal(result.pose, 'half-open');
+    assert.equal(result.hingeAngleDegrees, 100);
+    const recorded = recordActionEntry(daemon.session()!, {
+      command: 'fold',
+      positionals: [],
+      flags: { keyframes: JSON.stringify(trajectory) },
+      result,
+    });
+    assert.ok(recorded);
+    const line = formatPortableActionLine(recorded);
+    assert.match(line, /--keyframes/);
+    const [parsed] = parseReplayScriptDetailed(line).actions;
+    assert.ok(parsed);
+    const replayed = assertRpcOk(
+      await daemon.callCommand(parsed.command, parsed.positionals ?? [], parsed.flags),
+    );
+    assert.equal(replayed.hingeAngleDegrees, 100);
+    assert.equal(builds, 2);
+    assert.equal(tool.calls.filter((call) => call.includes('spawn')).length, 2);
+    assert.equal(tool.calls.filter((call) => call.includes('hinge-angle')).length, 4);
+  } finally {
+    await daemon.close();
+  }
+});
diff --git a/website/docs/docs/client-api.md b/website/docs/docs/client-api.md
index 3e6d226cd6..99da1feebb 100644
--- a/website/docs/docs/client-api.md
+++ b/website/docs/docs/client-api.md
@@ -273,8 +273,18 @@ await client.command.tvRemote({
 await client.command.appSwitcher();
 await client.command.actionButton();
 await client.command.fold({ pose: 'open' });
+await client.command.fold({
+  keyframes: [
+    { atMs: 0, angle: 0 },
+    { atMs: 1667, angle: 160 },
+    { atMs: 3333, angle: 100 },
+    { atMs: 5000, angle: 180 },
+  ],
+});
 ```
 
+`fold` accepts either `pose` or `keyframes`. Keyframes use linear interpolation at roughly 60 updates per second; repeat an angle to hold it. Timestamps must start at zero and increase strictly, with 2–64 frames and a final timestamp no greater than 60,000ms. Angles must be finite and between 0° and 180°. The final timestamp bounds motion, excluding helper preparation and final hinge verification. A custom final angle is verified within 0.5°; interior angles must also settle. Cancellation stops the motion at its current angle. Re-snapshot afterwards, including after interrupted motion.
+
 Vega OS client support is currently VVD-only and covers device discovery, app open/close, `back`, `home`, and `tvRemote`. Physical Fire TV, capture, selector, install, logging, and performance methods report unsupported for Vega targets.
 
 Supported command methods:
diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md
index 3e20fa5767..cb815c2e4e 100644
--- a/website/docs/docs/commands.md
+++ b/website/docs/docs/commands.md
@@ -92,6 +92,7 @@ agent-device fold open
 - `action-button` does not activate or relaunch the session's app, and it takes no `--settle`: pressing a hardware button is not a navigation, so the app stays where it was.
 - `action-button` reports that the press was dispatched, not what the system did with it. Simulators run no Shortcuts and no App Intents, so what a press triggers can only be verified on a physical iPhone; on a Simulator the command proves the press was accepted and that the session app was not brought forward.
 - `fold <closed|half-open|open>` puts a foldable iPhone simulator (iPhone Duo) into a hinge pose. The command sends a private HID hinge event inside the selected simulator (ADR 0025), then reads the hinge angle back with `devicectl device motion hinge-angle` and reports the pose only when that reading agrees: `closed` is 0°, `open` is 180°, and `half-open` is any angle between them (requested at 130°). An angle inside that interval only proves the category, so `half-open` is reported once two consecutive readings both fall inside it and agree within 0.5°. The response names the panel the device now lights and its native panel point size, marked `coordinateSpace: "native-panel"`; that size is the panel's own geometry, not the next snapshot's viewport (a 669x951 inner panel can host a 951x669 app window), so it cannot place a tap. Re-snapshot afterwards, and never carry refs or coordinates across a `fold`. After that snapshot, taps, long presses, and scrolling follow the app window on the active panel in closed, half-open, and open poses.
+- For timed motion, use `fold --keyframes '[{"atMs":0,"angle":0},{"atMs":1667,"angle":160},{"atMs":3333,"angle":100},{"atMs":5000,"angle":180}]'`. This runs the opening/reversal/reopening sequence over five seconds. Supply either a preset or keyframes, never both. Use 2–64 keyframes starting at 0ms with strictly increasing integer timestamps up to 60,000ms and finite angles in 0–180°. Linear interpolation runs at roughly 60Hz; equal consecutive angles hold the hinge. Motion duration excludes preparation and final-angle verification. Cancellation stops at the current angle; re-snapshot even after an interrupted trajectory.
 - `fold` is simulator-only and requires an Xcode toolchain with the iOS simulator SDK and foldable HID support (verified on Xcode 27.1). It compiles a temporary helper and runs it against the session UDID. Device Hub and host Accessibility permission are not required. Build failures report `fold-helper-build-failed`; dispatch failures report `fold-hid-dispatch-failed`. There is no UI fallback. Single-panel simulators and physical devices are refused.
 - `fold` costs one bounded hinge stream per read, and devicectl's smallest stream is five seconds: `closed` and `open` take about ten seconds, `half-open` about sixteen, because the hinge animates and the command waits for it to stop. A hinge whose last reading is some other pose fails with `COMMAND_FAILED` and `reason: fold-pose-unverified`, naming the angle CoreDevice still reports. A hinge seen `half-open` but never at rest fails with `reason: fold-pose-unsettled`, naming the observed and previous angles: the requested category was observed, and what is missing is a pose the hinge holds (#2730).
 - `action-button` is not a cheap command to loop. On an iPhone 17 Pro Simulator the press itself spent about five seconds inside XCUITest, while `home` and `app-switcher` on the same session took under two seconds each.

From 01328de4113749ac33e35ea2390305e6a08c0edd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Tue, 22 Sep 2026 20:56:05 +0200
Subject: [PATCH 027/132] 0.21.12

---
 package.json | 2 +-
 server.json  | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/package.json b/package.json
index 7453a6a4ce..11d3d7b1be 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "agent-device",
-  "version": "0.21.11",
+  "version": "0.21.12",
   "description": "Mobile app automation and verification for AI coding agents. CLI, MCP server, and typed Node.js API for iOS, Android, HarmonyOS, TV, web, macOS, and Linux.",
   "mcpName": "io.github.callstack/agent-device",
   "license": "MIT",
diff --git a/server.json b/server.json
index f23a9b184a..e5b141a9e1 100644
--- a/server.json
+++ b/server.json
@@ -7,12 +7,12 @@
     "url": "https://github.com/callstack/agent-device",
     "source": "github"
   },
-  "version": "0.21.11",
+  "version": "0.21.12",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "agent-device",
-      "version": "0.21.11",
+      "version": "0.21.12",
       "transport": {
         "type": "stdio"
       },

From bd843087a53b4e5a9243d9b4d927b560fb66d813 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Wed, 23 Sep 2026 07:39:03 +0200
Subject: [PATCH 028/132] fix(ios): derive selected from the AX bridge traits
 word (#2768)

When 0.21.0 made the host AX bridge the iOS Simulator snapshot source, the bridge node reader mapped the traits word into enabled but never into selected, so a selected: selector or Maestro selected: qualifier stopped matching the active tab, segment, or checked row. Restore the fact by reading the selected-trait bit of the same word, publishing selected: true only when set and omitting it otherwise to match the XCTest tree. Pin the bit against the guest's real captured words and fold the traits parse into one shared source so a producer encoding change cannot drop it silently.
---
 CHANGELOG.md                                  | 11 +++++
 .../src/snapshot-source/tree.test.ts          | 45 +++++++++++++++++++
 .../src/snapshot-source/tree.ts               | 25 +++++++++--
 3 files changed, 77 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7301f3b3f4..afea45c5a3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+- Fixed (ios): a local Simulator snapshot taken through the host AX bridge once again carries the
+  accessibility `selected` state, so `is selected`, a `selected=true` selector, and a Maestro
+  `selected:` qualifier match the active control. When 0.21.0 made the AX bridge the Simulator's
+  snapshot source, the bridge's node reader mapped the traits word into `enabled` but never into
+  `selected`, so an active bottom tab, chosen segment, or checked row published no `selected` field
+  and every `selected:` match failed on the iOS Simulator — a fact the 0.20.x XCTest tree had always
+  supplied and that `snapshots.md` still promises. The reader now derives `selected` from the
+  selected-trait bit of the same traits word, publishing `selected: true` only when set and omitting
+  it otherwise so the two producers cannot be told apart by a `selected:` selector. The bit is pinned
+  by the guest's real captured words, so a producer encoding change cannot drop the fact silently
+  again.
 - Fixed (ios): an interactive snapshot no longer drops the rows of a list whose row hosts a scroll
   view of its own. Ownership of a scroll indicator is now read from its parent edge — a visible band
   derives only when the indicator's parent is itself a scroll type — instead of walking ancestors for
diff --git a/packages/platform-apple/src/snapshot-source/tree.test.ts b/packages/platform-apple/src/snapshot-source/tree.test.ts
index e98163c42d..749e182ef5 100644
--- a/packages/platform-apple/src/snapshot-source/tree.test.ts
+++ b/packages/platform-apple/src/snapshot-source/tree.test.ts
@@ -190,6 +190,51 @@ test('the bridge tree reads enabled from the NotEnabled trait', () => {
   assert.throws(() => decode(''), traitsInvalid);
 });
 
+test('the bridge tree reads selected from the selected trait, matching the XCTest tree', () => {
+  const tab = (word?: unknown) => ({
+    [automationType]: 9,
+    [label]: 'Albums',
+    [frame]: { X: 20, Y: 700, Width: 120, Height: 48 },
+    ...(word === undefined ? {} : { [traits]: word }),
+    [children]: [],
+  });
+  const decode = (word?: unknown) =>
+    decodeSnapshotBridgeTree(
+      { [application]: 'Application', [children]: [tab(word)] },
+      { truncated: false },
+      limits,
+    ).nodes[1];
+  const selected = (word?: unknown) => decode(word)?.selected;
+  const enabled = (word?: unknown) => decode(word)?.enabled;
+
+  const buttonTrait = 1n;
+  const selectedTrait = 1n << 3n;
+  const privateHighTrait = 1n << 60n;
+  const word = (traits: bigint) => traits.toString();
+  // Real guest captures from a React Navigation bottom tab bar: the active tab differs from the
+  // inactive tabs by exactly bit 3, and the active tab also carries the label. This pins the bit so
+  // a producer change cannot silently drop `selected:` matching the way the 0.21.0 bridge did.
+  const selectedTabTraits = 8858370057n;
+  const inactiveTabTraits = 8858370049n;
+
+  assert.equal(selected(word(buttonTrait | selectedTrait)), true);
+  assert.equal(selected(word(selectedTabTraits)), true, 'active tab reports selected');
+  assert.equal(selected(word(inactiveTabTraits)), undefined, 'inactive tab omits selected');
+  assert.equal(selected(word(buttonTrait)), undefined, 'unselected omits selected');
+  assert.equal(selected(word(0n)), undefined, 'no selected bit omits selected');
+  assert.equal(
+    selected(word(privateHighTrait | selectedTrait)),
+    true,
+    'a word past double precision keeps bit 3',
+  );
+  assert.equal(selected(word(privateHighTrait | 7n)), undefined, 'no carry into bit 3');
+  assert.equal(selected(), undefined, 'no traits word leaves selected unknown');
+  // The two facts are read from one word without interfering: bit 3 is selection, bit 8 is disabled.
+  const disabledSelected = word(selectedTabTraits | (1n << 8n));
+  assert.equal(selected(disabledSelected), true);
+  assert.equal(enabled(disabledSelected), false);
+});
+
 test('the bridge tree rejects unknown fields, invalid frames, and bounded overflows', () => {
   assert.throws(
     () => decodeSnapshotBridgeTree({ [children]: [], unknown: true }, { truncated: false }, limits),
diff --git a/packages/platform-apple/src/snapshot-source/tree.ts b/packages/platform-apple/src/snapshot-source/tree.ts
index 7cc9fcdd03..21265b3252 100644
--- a/packages/platform-apple/src/snapshot-source/tree.ts
+++ b/packages/platform-apple/src/snapshot-source/tree.ts
@@ -118,6 +118,14 @@ const NODE_KEYS = new Set<string>(Object.values(ATTRIBUTE));
  */
 const NOT_ENABLED_TRAIT = 1n << 8n;
 
+/**
+ * The selected-state trait the guest reader reports for a control the app marked selected — the
+ * active tab in a tab bar, a chosen segment, a checked row. The runner path answers
+ * `selected: true` for the same node, so the bridge derives the fact from this bit. A node that is
+ * not selected omits the field, matching the runner, which publishes `selected` only when true.
+ */
+const SELECTED_TRAIT = 1n << 3n;
+
 /**
  * A WebKit page — Safari's, or a `WKWebView`'s — lives in a WebContent process and reaches UIKit's
  * tree as an `AXRemoteElement` under the web view, with its children in that other process. The
@@ -220,7 +228,11 @@ function nodeFacts(
   const baseClass = optionalString(value[ATTRIBUTE.elementBaseType]);
   const automationType = optionalInteger(value[ATTRIBUTE.automationType]);
   const frame = frameFromGuest(value[ATTRIBUTE.frame]);
-  const enabled = enabledFromTraits(value[ATTRIBUTE.traits]);
+  const traits = traitsFromGuest(value[ATTRIBUTE.traits]);
+  const enabled = traits === undefined ? undefined : (traits & NOT_ENABLED_TRAIT) === 0n;
+  // Publishes `selected: true` only when the selected bit is set and omits it otherwise — the same
+  // shape the XCTest tree produces, so a `selected:` selector cannot tell the producers apart.
+  const selected = traits === undefined || (traits & SELECTED_TRAIT) === 0n ? undefined : true;
   return {
     index,
     ...(parentIndex === undefined ? {} : { parentIndex }),
@@ -240,6 +252,7 @@ function nodeFacts(
       : {}),
     ...(frame ? { rect: frame } : {}),
     ...(enabled === undefined ? {} : { enabled }),
+    ...(selected === undefined ? {} : { selected }),
     depth,
   };
 }
@@ -342,13 +355,17 @@ function optionalScalar(value: unknown): string | undefined {
   return undefined;
 }
 
-/** The guest sends the uint64 traits word as a decimal string so no bit is lost to a double. */
-function enabledFromTraits(value: unknown): boolean | undefined {
+/**
+ * The guest sends the uint64 traits word as a decimal string so no bit is lost to a double. One
+ * parse feeds every trait fact the tree publishes — `enabled` and `selected` — so a malformed word
+ * fails the same way no matter which fact is read.
+ */
+function traitsFromGuest(value: unknown): bigint | undefined {
   if (value === undefined || value === null) return undefined;
   if (typeof value !== 'string' || !/^\d{1,20}$/.test(value)) {
     throw snapshotSourceError('malformed-tree', 'traits-invalid');
   }
-  return (BigInt(value) & NOT_ENABLED_TRAIT) === 0n;
+  return BigInt(value);
 }
 
 function optionalInteger(value: unknown): number | undefined {

From c32a09c85a95d502fc112fac280b8ee7b0f06094 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Wed, 23 Sep 2026 07:39:51 +0200
Subject: [PATCH 029/132] fix(ios): pay for one toolchain in the snapshot
 bridge identity read (#2712) (#2765)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(ios): pay for one toolchain in the snapshot bridge identity read

The identity read probed `xcodebuild -version` and then `xcrun --sdk iphonesimulator
--show-sdk-version` — two Xcode-owned binaries, each a tool the host can stall on before
it answers. On CI the `xcrun` probe lost twice at the shared 30 s ceiling and took the
whole iOS smoke job down over a cache-key field (60.9 s of a 120 s budget, job
106068926059).

The Simulator SDK ships inside the selected `Xcode.app`, so the version and build
`xcodebuild -version` already reports pin it: the field left the cache key and the exec
left the identity read. The `xcrun clang` the build runs pays that wait once, under the
build's own ceiling, where a stall of that length fits instead of exhausting the budget.

A probe or compile that cannot answer now says so at the seam that waited: `timeout` with
`toolchain-probe-stalled` or `native-build-stalled`, the command, the budget each attempt
was armed with, and the exec layer's kill kept as the cause. Before, a job got a bare
`xcrun timed out after 30000ms` stack that reads exactly like a device failure.

Cache entries written before this hash to a different key, so they rebuild once instead of
being misread; no schema bump is needed to prove that.

Closes #2712

* test(ios): take the snapshot bridge stall fixtures from the exec layer

Both stall fixtures built the timeout error by hand, so a probe could keep classifying a
kill `exec.ts` no longer reports as one. They now run a command the exec layer really
kills and carry whatever error it raises; the probe assertions still read the shape
through `isCommandTimeoutError` rather than a message.

Review note on #2765.
---
 .../__tests__/exec-timeout-fixture.ts         |  22 +++
 .../src/snapshot-source/adapter.test.ts       |   5 +-
 .../snapshot-source/cache-identity.test.ts    | 164 +++++++++++++-----
 .../src/snapshot-source/cache-identity.ts     |  92 +++++++---
 .../src/snapshot-source/cache.test.ts         |  50 ++++++
 .../src/snapshot-source/cache.ts              |  96 ++++++----
 6 files changed, 325 insertions(+), 104 deletions(-)
 create mode 100644 packages/platform-apple/src/snapshot-source/__tests__/exec-timeout-fixture.ts

diff --git a/packages/platform-apple/src/snapshot-source/__tests__/exec-timeout-fixture.ts b/packages/platform-apple/src/snapshot-source/__tests__/exec-timeout-fixture.ts
new file mode 100644
index 0000000000..98eaaa1ea8
--- /dev/null
+++ b/packages/platform-apple/src/snapshot-source/__tests__/exec-timeout-fixture.ts
@@ -0,0 +1,22 @@
+import { runCmd } from '@agent-device/host-kit/command';
+import type { AppError } from '@agent-device/kernel/errors';
+
+/** Long enough that the kill always lands first, short enough to stay out of the test budget. */
+const STALL_TIMEOUT_MS = 5;
+
+/**
+ * The failure a probe or a compile hits: the real error `exec.ts` raises when it kills a command at
+ * the budget it was handed. Hand-building that shape would let the probes keep classifying a kill
+ * that exec.ts no longer reports as one.
+ */
+export async function execKillTimeoutError(): Promise<AppError> {
+  // `timeoutMs` bounds the sleep well below its own request, so exec kills it rather than waiting.
+  return await runCmd(process.execPath, ['-e', 'setTimeout(() => {}, 30_000)'], {
+    timeoutMs: STALL_TIMEOUT_MS,
+  }).then(
+    () => {
+      throw new Error('the fixture command answered instead of being killed at its timeout');
+    },
+    (error: unknown) => error as AppError,
+  );
+}
diff --git a/packages/platform-apple/src/snapshot-source/adapter.test.ts b/packages/platform-apple/src/snapshot-source/adapter.test.ts
index c6cdab1f88..5c4f9435fa 100644
--- a/packages/platform-apple/src/snapshot-source/adapter.test.ts
+++ b/packages/platform-apple/src/snapshot-source/adapter.test.ts
@@ -51,7 +51,8 @@ test('the Simulator AX source returns raw acquisition facts and discloses unsupp
       hint,
     });
     assert.equal(fixture.builds, 1);
-    assert.equal(fixture.runs, 6);
+    // Four identity probes and one clang build: the identity read execs one Xcode-owned binary.
+    assert.equal(fixture.runs, 5);
     assert.equal(result.stage, 'acquired');
     assert.equal(result.acquisition.producer, 'simulator-ax-bridge');
     assert.equal(result.acquisition.intent, 'full');
@@ -92,7 +93,7 @@ test('the Simulator AX source returns raw acquisition facts and discloses unsupp
     });
     assert.equal(outcome.stage, 'failed');
     if (outcome.stage === 'failed') assert.equal(outcome.failure.kind, 'stale-target');
-    assert.equal(fixture.runs, 6);
+    assert.equal(fixture.runs, 5);
   } finally {
     await source.close();
     await rm(root, { recursive: true, force: true });
diff --git a/packages/platform-apple/src/snapshot-source/cache-identity.test.ts b/packages/platform-apple/src/snapshot-source/cache-identity.test.ts
index fc71799fd0..f1b1a10998 100644
--- a/packages/platform-apple/src/snapshot-source/cache-identity.test.ts
+++ b/packages/platform-apple/src/snapshot-source/cache-identity.test.ts
@@ -5,25 +5,29 @@ import { createSnapshotSourceHost } from './host.ts';
 import { readSnapshotSourceToolchain } from './cache-identity.ts';
 import { createSnapshotSourceDeadline, type SnapshotSourceDeadline } from './deadline.ts';
 import { SnapshotSourceError } from './errors.ts';
-import type { ExecOptions, ExecResult } from '@agent-device/host-kit/command';
+import { execKillTimeoutError } from './__tests__/exec-timeout-fixture.ts';
+import {
+  isCommandTimeoutError,
+  type ExecOptions,
+  type ExecResult,
+} from '@agent-device/host-kit/command';
 import type { SnapshotSourceHost } from './types.ts';
 
-// Apple's syspolicyd signature scan blocks the first xcodebuild/xcrun exec
-// after a fresh macOS host boots for roughly 18 to 19 seconds; the immediate
-// next exec of the same tool is instant (#2422). These cases exercise the
-// resulting one-retry policy, and the deadline that bounds it, without waiting
-// on a real cold-start stall: the fake clock only moves when a probe actually
-// blocks for the timeout it was handed, so a case that claims the budget was
-// spent had to spend it.
+// Apple's syspolicyd signature scan blocks the first exec of an Xcode-owned tool after a fresh
+// macOS host boots for roughly 18 to 19 seconds; the immediate next exec of the same tool is
+// instant (#2422). These cases exercise the resulting one-retry policy, and the deadline that
+// bounds it, without waiting on a real cold-start stall: the fake clock only moves when a probe
+// actually blocks for the timeout it was handed, so a case that claims the budget was spent had to
+// spend it.
 
 test('a cold-start toolchain probe recovers on retry, and the retry gets only what the stall left', async () => {
   const clock = { nowMs: 0 };
   const timeouts: number[] = [];
   let calls = 0;
-  const host = fakeToolchainHost((command, args, options) => {
+  const host = fakeToolchainHost(async (command, args, options) => {
     calls += 1;
     timeouts.push(options.timeoutMs ?? 0);
-    if (calls === 1) throw blockForWholeTimeout(clock, command, options);
+    if (calls === 1) throw await blockForWholeTimeout(clock, options);
     return toolchainAnswer(command, args);
   });
 
@@ -36,28 +40,47 @@ test('a cold-start toolchain probe recovers on retry, and the retry gets only wh
   assert.equal(identity.xcode, 'Xcode 26.2\nBuild version 17C52');
   assert.equal(identity.macosBuild, '24G90');
   assert.equal(identity.architecture, 'arm64');
-  assert.equal(identity.simulatorSdk, '26.2');
+  assert.equal(identity.simulatorRuntime, 'iOS 26.2');
   // The stalled first attempt is capped at the 30 s per-probe ceiling; the
   // retry runs on the 10 s the shared deadline has left, not a second 30 s.
   assert.deepEqual(timeouts.slice(0, 2), [30_000, 10_000]);
   assert.equal(clock.nowMs, 30_000);
-  // 5 baseline probes (xcodebuild, sw_vers x2, uname, xcrun) plus the one
+  // 4 baseline probes (xcodebuild, sw_vers x2, uname) plus the one
   // retry that recovered the first, timed-out call.
-  assert.equal(calls, 6);
+  assert.equal(calls, 5);
 });
 
-test('a toolchain host that never returns still fails at the deadline with the same timeout error', async () => {
+// The identity read is allowed to exec one Xcode-owned binary. The Simulator SDK a second
+// `xcrun` probe used to report ships inside the selected `Xcode.app`, so it cannot move under a
+// `xcodebuild -version` build that already pins it -- and every extra Xcode-owned exec is another
+// toolchain the job can wait on and fail against (#2712).
+test('the toolchain identity execs one Xcode-owned binary, and no xcrun', async () => {
+  const clock = { nowMs: 0 };
+  const probed: string[] = [];
+  const host = fakeToolchainHost((command, args) => {
+    probed.push(command);
+    return toolchainAnswer(command, args);
+  });
+
+  await readSnapshotSourceToolchain(host, 'iOS 26.2', fakeClockDeadline(120_000, clock));
+
+  assert.deepEqual(probed, ['xcodebuild', 'sw_vers', 'sw_vers', 'uname']);
+});
+
+test('a toolchain host that never returns reports the stalled probe after one retry', async () => {
   const clock = { nowMs: 0 };
   const timeouts: number[] = [];
-  const host = fakeToolchainHost((command, _args, options) => {
+  const host = fakeToolchainHost(async (_command, _args, options) => {
     timeouts.push(options.timeoutMs ?? 0);
-    throw blockForWholeTimeout(clock, command, options);
+    throw await blockForWholeTimeout(clock, options);
   });
 
   await assert.rejects(
     readSnapshotSourceToolchain(host, 'iOS 26.2', fakeClockDeadline(120_000, clock)),
-    (error: unknown) =>
-      error instanceof AppError && error.message === 'xcodebuild timed out after 30000ms',
+    (error: unknown) => {
+      assertToolchainProbeStall(error, 'xcodebuild', [30_000, 30_000]);
+      return true;
+    },
   );
   // Exactly one retry, not an unbounded loop, and the retry is charged the
   // remainder rather than a fresh ceiling.
@@ -65,6 +88,29 @@ test('a toolchain host that never returns still fails at the deadline with the s
   assert.equal(clock.nowMs, 60_000);
 });
 
+// The stall names the probe that hit it, not just the first one in the sequence: a host whose
+// `sw_vers` answers late must not read as an Xcode problem.
+test('a later probe that stalls out names that probe and its own attempts', async () => {
+  const clock = { nowMs: 0 };
+  let macosBuildCalls = 0;
+  const host = fakeToolchainHost(async (command, args, options) => {
+    if (command !== 'sw_vers' || !args.includes('-buildVersion')) {
+      return toolchainAnswer(command, args);
+    }
+    macosBuildCalls += 1;
+    throw await blockForWholeTimeout(clock, options);
+  });
+
+  await assert.rejects(
+    readSnapshotSourceToolchain(host, 'iOS 26.2', fakeClockDeadline(120_000, clock)),
+    (error: unknown) => {
+      assertToolchainProbeStall(error, 'sw_vers', [30_000, 30_000]);
+      return true;
+    },
+  );
+  assert.equal(macosBuildCalls, 2);
+});
+
 test('a probe that failed on its own and merely says "timed out" in its message is not retried', async () => {
   const clock = { nowMs: 0 };
   let calls = 0;
@@ -101,7 +147,7 @@ type ToolchainProbeCancellationCase = {
   aborts: 'never' | 'before-the-deadline' | 'while-it-blocks' | 'as-it-unwinds';
   /** The phase deadline. 30 s is spent in full by one stalled probe, leaving no retry. */
   deadlineMs: number;
-  expected: 'cancelled' | 'exec-timeout' | 'command-failure';
+  expected: 'cancelled' | 'probe-stall' | 'command-failure';
   execs: number;
   clockMs: number;
 };
@@ -146,12 +192,12 @@ const CANCELLATION_CASES: ToolchainProbeCancellationCase[] = [
     clockMs: 30_000,
   },
   {
-    // Nothing left to retry on, so the original timeout propagates unchanged.
+    // Nothing left to retry on, so a single stalled attempt already names the probe.
     label: 'never aborted, the first probe spends the whole deadline',
     firstProbe: 'exec-timeout',
     aborts: 'never',
     deadlineMs: 30_000,
-    expected: 'exec-timeout',
+    expected: 'probe-stall',
     execs: 1,
     clockMs: 30_000,
   },
@@ -162,13 +208,13 @@ test.each(CANCELLATION_CASES)('cancellation matrix: $label', async (testCase) =>
   const request = new AbortController();
   if (testCase.aborts === 'before-the-deadline') request.abort();
   let execs = 0;
-  const host = fakeToolchainHost((command, args, options) => {
+  const host = fakeToolchainHost(async (command, args, options) => {
     execs += 1;
     if (execs > 1 || !testCase.firstProbe) return toolchainAnswer(command, args);
     if (testCase.aborts === 'while-it-blocks') request.abort();
     const failure =
       testCase.firstProbe === 'exec-timeout'
-        ? blockForWholeTimeout(clock, command, options)
+        ? await blockForWholeTimeout(clock, options)
         : // No `timeoutMs` detail: the tool failed on its own, so nothing retries it.
           new AppError('COMMAND_FAILED', `${command}: unexpected error`, { cmd: command });
     if (testCase.aborts === 'as-it-unwinds') request.abort();
@@ -204,13 +250,33 @@ function assertExpectedToolchainFailure(
     assert.equal(error.details?.reason, 'request_canceled', testCase.label);
     return;
   }
+  if (testCase.expected === 'probe-stall') {
+    assertToolchainProbeStall(error, 'xcodebuild', [30_000]);
+    return;
+  }
   assert.ok(error instanceof AppError, `${testCase.label}: expected the probe's own failure`);
-  assert.equal(
-    error.message,
-    testCase.expected === 'exec-timeout'
-      ? 'xcodebuild timed out after 30000ms'
-      : 'xcodebuild: unexpected error',
-    testCase.label,
+  assert.equal(error.message, 'xcodebuild: unexpected error', testCase.label);
+}
+
+/**
+ * A probe that stalled out names itself, says what each attempt was armed with, and keeps the exec
+ * layer's own kill as its cause -- so a job can tell "this tool never answered" from a device
+ * failure without reading a stack frame (#2712).
+ */
+function assertToolchainProbeStall(
+  error: unknown,
+  command: string,
+  attemptTimeoutsMs: number[],
+): void {
+  assert.ok(error instanceof SnapshotSourceError, `expected a toolchain probe stall, got ${error}`);
+  assert.equal(error.failureKind, 'timeout');
+  assert.equal(error.failureCode, 'toolchain-probe-stalled');
+  assert.equal(error.details?.command, command);
+  assert.deepEqual(error.details?.attemptTimeoutsMs, attemptTimeoutsMs);
+  assert.match(String(error.details?.hint), new RegExp(`run \`${command}\` by hand`));
+  assert.ok(
+    isCommandTimeoutError(error.cause),
+    'the exec layer kill the probe hit stays the cause',
   );
 }
 
@@ -219,33 +285,35 @@ function fakeClockDeadline(timeoutMs: number, clock: { nowMs: number }): Snapsho
   return createSnapshotSourceDeadline(timeoutMs, undefined, () => clock.nowMs);
 }
 
-/** A probe that blocked for its whole timeout and was then killed, as the exec layer reports it. */
-function blockForWholeTimeout(
+/**
+ * A probe that blocked for its whole timeout and was then killed. The fake clock advances by the
+ * budget the probe was handed, and the failure is the one `exec.ts` really raises for that kill.
+ */
+async function blockForWholeTimeout(
   clock: { nowMs: number },
-  command: string,
   options: ExecOptions,
-): AppError {
-  const timeoutMs = options.timeoutMs ?? 0;
-  clock.nowMs += timeoutMs;
-  return new AppError('COMMAND_FAILED', `${command} timed out after ${timeoutMs}ms`, { timeoutMs });
+): Promise<unknown> {
+  clock.nowMs += options.timeoutMs ?? 0;
+  return await execKillTimeoutError();
 }
 
+/**
+ * What the host answers each probe the identity read is allowed to run. A command outside this list
+ * is a probe the identity read must not open at all (#2712).
+ */
 function toolchainAnswer(command: string, args: string[]): ExecResult {
-  const stdout =
-    command === 'xcodebuild'
-      ? 'Xcode 26.2\nBuild version 17C52'
-      : command === 'sw_vers'
-        ? args.includes('-buildVersion')
-          ? '24G90'
-          : '15.6'
-        : command === 'uname'
-          ? 'arm64'
-          : '26.2';
-  return { stdout, stderr: '', exitCode: 0 };
+  if (command === 'xcodebuild') {
+    return { stdout: 'Xcode 26.2\nBuild version 17C52', stderr: '', exitCode: 0 };
+  }
+  if (command === 'sw_vers') {
+    return { stdout: args.includes('-buildVersion') ? '24G90' : '15.6', stderr: '', exitCode: 0 };
+  }
+  if (command === 'uname') return { stdout: 'arm64', stderr: '', exitCode: 0 };
+  throw new Error(`the identity read execed ${command} ${args.join(' ')}`);
 }
 
 function fakeToolchainHost(
-  run: (command: string, args: string[], options: ExecOptions) => ExecResult,
+  run: (command: string, args: string[], options: ExecOptions) => ExecResult | Promise<ExecResult>,
 ): SnapshotSourceHost {
   const real = createSnapshotSourceHost();
   return {
diff --git a/packages/platform-apple/src/snapshot-source/cache-identity.ts b/packages/platform-apple/src/snapshot-source/cache-identity.ts
index 785b8708ba..5bf7e42a1e 100644
--- a/packages/platform-apple/src/snapshot-source/cache-identity.ts
+++ b/packages/platform-apple/src/snapshot-source/cache-identity.ts
@@ -2,16 +2,22 @@ import { createHash } from 'node:crypto';
 import path from 'node:path';
 import { isCommandTimeoutError, type ExecResult } from '@agent-device/host-kit/command';
 import { COLD_TOOLCHAIN_PROBE_TIMEOUT_MS } from '../runner/apple-runner-platform.ts';
-import { snapshotSourceError } from './errors.ts';
+import { snapshotSourceError, type SnapshotSourceError } from './errors.ts';
 import { remainingSnapshotSourceMs, type SnapshotSourceDeadline } from './deadline.ts';
 import type { SnapshotSourceHost } from './types.ts';
 
+/**
+ * The half of the bridge cache key the host answers for. `xcode` carries the version and the build,
+ * which is what pins the Simulator SDK the bridge compiles against: that SDK ships inside the
+ * selected `Xcode.app`, so it cannot move while `xcodebuild -version` reports the same build. The
+ * identity therefore execs one Xcode-owned binary rather than two, because a toolchain probe that
+ * cannot answer fails the whole job with nothing but a cache key at stake (#2712).
+ */
 export type SnapshotSourceToolchainIdentity = Readonly<{
   xcode: string;
   macosProductVersion: string;
   macosBuild: string;
   architecture: 'arm64' | 'x86_64';
-  simulatorSdk: string;
   simulatorRuntime: string;
 }>;
 
@@ -53,16 +59,11 @@ export async function readSnapshotSourceToolchain(
   simulatorRuntime: string,
   deadline: SnapshotSourceDeadline,
 ): Promise<SnapshotSourceToolchainIdentity> {
+  // The one Xcode-owned binary this read execs: SnapshotSourceToolchainIdentity says why (#2712).
   const xcode = await toolOutput(host, 'xcodebuild', ['-version'], deadline);
   const macosProductVersion = await toolOutput(host, 'sw_vers', ['-productVersion'], deadline);
   const macosBuild = await toolOutput(host, 'sw_vers', ['-buildVersion'], deadline);
   const architecture = await toolOutput(host, 'uname', ['-m'], deadline);
-  const simulatorSdk = await toolOutput(
-    host,
-    'xcrun',
-    ['--sdk', 'iphonesimulator', '--show-sdk-version'],
-    deadline,
-  );
   const runtime = simulatorRuntime.trim();
   if (!runtime) throw snapshotSourceError('unsupported', 'simulator-runtime-missing');
   if (architecture !== 'arm64' && architecture !== 'x86_64') {
@@ -75,7 +76,6 @@ export async function readSnapshotSourceToolchain(
     macosProductVersion,
     macosBuild,
     architecture,
-    simulatorSdk,
     simulatorRuntime: runtime,
   };
 }
@@ -99,10 +99,16 @@ async function toolOutput(
   return output;
 }
 
+/** One exec, plus the single retry a first-exec stall can actually earn. */
+const TOOLCHAIN_PROBE_ATTEMPTS = 2;
+
 /**
- * Retries exactly once, and only the exec layer's structured timeout: the stall
- * {@link COLD_TOOLCHAIN_PROBE_TIMEOUT_MS} names clears on the next exec of the same tool.
- * Both attempts read one deadline, so the retry gets what the stall left.
+ * Retries exactly once, and only the exec layer's structured timeout: a stall that finished while the
+ * probe was being killed leaves an instant next exec of the same tool behind it, which is what
+ * {@link COLD_TOOLCHAIN_PROBE_TIMEOUT_MS} was sized for (#2422). A stall that had not finished does
+ * not clear that way, so the second timeout is reported as the host condition it is instead of
+ * pretending the probe was worth running twice. Both attempts read one deadline, so the retry only
+ * gets what the first stall left.
  */
 async function runToolchainProbe(
   host: SnapshotSourceHost,
@@ -110,28 +116,68 @@ async function runToolchainProbe(
   args: string[],
   deadline: SnapshotSourceDeadline,
 ): Promise<ExecResult> {
-  try {
-    return await execToolchainProbe(host, command, args, deadline);
-  } catch (error) {
-    if (!isCommandTimeoutError(error)) throw error;
-    if (deadline.signal?.aborted) throw snapshotSourceError('cancelled', 'abort-signal');
-    if (deadline.clock.remainingMs(deadline.now()) <= 0) throw error;
-    return await execToolchainProbe(host, command, args, deadline);
+  const attemptTimeoutsMs: number[] = [];
+  let stalledBy: SnapshotSourceError | undefined;
+  for (let attempt = 1; ; attempt += 1) {
+    let timeoutMs: number;
+    try {
+      timeoutMs = Math.min(
+        COLD_TOOLCHAIN_PROBE_TIMEOUT_MS,
+        remainingSnapshotSourceMs(deadline, 'toolchain-probe-deadline'),
+      );
+    } catch (budgetError) {
+      // A budget that closes between an attempt and this line is the stall already observed, and it
+      // still names the probe that stalled rather than the arithmetic that noticed.
+      throw stalledBy ?? budgetError;
+    }
+    attemptTimeoutsMs.push(timeoutMs);
+    try {
+      return await execToolchainProbe(host, command, args, deadline, timeoutMs);
+    } catch (error) {
+      if (!isCommandTimeoutError(error)) throw error;
+      if (deadline.signal?.aborted) throw snapshotSourceError('cancelled', 'abort-signal');
+      stalledBy = toolchainProbeStallError(command, attemptTimeoutsMs, error);
+      if (attempt >= TOOLCHAIN_PROBE_ATTEMPTS) throw stalledBy;
+    }
   }
 }
 
+/**
+ * Says which probe could not answer, how many execs it took to learn that, and what each was armed
+ * with. The exec layer's `<tool> timed out after Nms` alone reaches a job as an unattributed command
+ * failure, which reads exactly like a device failure (#2712).
+ */
+function toolchainProbeStallError(
+  command: string,
+  attemptTimeoutsMs: readonly number[],
+  cause: unknown,
+): SnapshotSourceError {
+  const attempts = attemptTimeoutsMs.length;
+  return snapshotSourceError(
+    'timeout',
+    'toolchain-probe-stalled',
+    {
+      command,
+      attemptTimeoutsMs: [...attemptTimeoutsMs],
+      hint:
+        `${command} did not answer within ${attemptTimeoutsMs[attempts - 1]}ms on ${attempts} ` +
+        `attempt(s). A toolchain probe that cannot answer is a host condition rather than a ` +
+        `toolchain defect: run \`${command}\` by hand until it answers, then retry.`,
+    },
+    cause,
+  );
+}
+
 function execToolchainProbe(
   host: SnapshotSourceHost,
   command: string,
   args: string[],
   deadline: SnapshotSourceDeadline,
+  timeoutMs: number,
 ): Promise<ExecResult> {
   return host.run(command, args, {
     allowFailure: true,
     signal: deadline.signal,
-    timeoutMs: Math.min(
-      COLD_TOOLCHAIN_PROBE_TIMEOUT_MS,
-      remainingSnapshotSourceMs(deadline, 'toolchain-probe-deadline'),
-    ),
+    timeoutMs,
   });
 }
diff --git a/packages/platform-apple/src/snapshot-source/cache.test.ts b/packages/platform-apple/src/snapshot-source/cache.test.ts
index d381c0ef02..bfbb6da496 100644
--- a/packages/platform-apple/src/snapshot-source/cache.test.ts
+++ b/packages/platform-apple/src/snapshot-source/cache.test.ts
@@ -3,12 +3,14 @@ import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
 
 import path from 'node:path';
 import { test } from 'vitest';
+import { isCommandTimeoutError } from '@agent-device/host-kit/command';
 import { createSnapshotSourceHost } from './host.ts';
 import { ensureSnapshotBridgeBinary } from './cache.ts';
 import { SnapshotSourceError } from './errors.ts';
 import { createSnapshotSourceDeadline } from './deadline.ts';
 import { DEFAULT_SNAPSHOT_SOURCE_LIMITS } from './limits.ts';
 import type { SnapshotSourceHost } from './types.ts';
+import { execKillTimeoutError } from './__tests__/exec-timeout-fixture.ts';
 import { mkdtempForTest } from '../__tests__/tmp-dir.ts';
 
 test('snapshot bridge preparation is cold-once, atomic, and invalidates corrupt or stale entries', async () => {
@@ -265,6 +267,54 @@ test('a bridge build that failed is reported over a cache lock that could not be
   }
 });
 
+test('a compile exec killed at its budget reports the bridge build, not the exec layer', async () => {
+  const root = await mkdtempForTest('agent-device-snapshot-source-build-stall-');
+  const sourceRoot = path.join(root, 'source');
+  const cacheRoot = path.join(root, 'cache');
+  await (await import('@agent-device/host-kit/host-file')).ensureHostDirectory(sourceRoot);
+  await writeFile(path.join(sourceRoot, 'SnapshotBridge.m'), 'native source');
+  await writeFile(path.join(sourceRoot, 'SnapshotBridgeRuntime.m'), 'native runtime');
+  await writeFile(path.join(sourceRoot, 'SnapshotBridgeRuntime.h'), 'native header');
+  await writeFile(path.join(sourceRoot, 'SnapshotBridgeCapture.h'), 'native header');
+  await writeFile(path.join(sourceRoot, 'SnapshotBridgeCapture.m'), 'native header');
+  const buildHost = createFakeBuildHost('binary');
+  let compileTimeoutMs = 0;
+  const host: SnapshotSourceHost = {
+    ...buildHost,
+    run: async (command, args, options) => {
+      if (command !== 'xcrun' || !args.includes('clang')) {
+        return await buildHost.run(command, args, options);
+      }
+      compileTimeoutMs = options?.timeoutMs ?? 0;
+      throw await execKillTimeoutError();
+    },
+  };
+
+  try {
+    await assert.rejects(
+      ensureSnapshotBridgeBinary({
+        host,
+        runtime: 'iOS 26.2',
+        limits: DEFAULT_SNAPSHOT_SOURCE_LIMITS,
+        deadline: testDeadline(120_000),
+        sourceRoot,
+        cacheRoot,
+      }),
+      (error: unknown) => {
+        assert.ok(error instanceof SnapshotSourceError);
+        assert.equal(error.failureKind, 'timeout');
+        assert.equal(error.failureCode, 'native-build-stalled');
+        assert.ok(compileTimeoutMs > 0, 'the compile exec ran and was killed at its budget');
+        assert.equal(error.details?.timeoutMs, compileTimeoutMs, 'says the budget the compile hit');
+        assert.ok(isCommandTimeoutError(error.cause), 'keeps the exec layer kill as the cause');
+        return true;
+      },
+    );
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
 async function expectRejectedCancellation(value: Promise<unknown>): Promise<void> {
   await assert.rejects(value, (error: unknown) => {
     return (
diff --git a/packages/platform-apple/src/snapshot-source/cache.ts b/packages/platform-apple/src/snapshot-source/cache.ts
index 73efeed2c4..4d5f4bf088 100644
--- a/packages/platform-apple/src/snapshot-source/cache.ts
+++ b/packages/platform-apple/src/snapshot-source/cache.ts
@@ -1,5 +1,6 @@
 import { createHash } from 'node:crypto';
 import path from 'node:path';
+import { isCommandTimeoutError, type ExecResult } from '@agent-device/host-kit/command';
 import { withProcessLock } from '@agent-device/host-kit/file';
 import { SnapshotSourceError, snapshotSourceError } from './errors.ts';
 import { remainingSnapshotSourceMs, type SnapshotSourceDeadline } from './deadline.ts';
@@ -88,37 +89,12 @@ export async function ensureSnapshotBridgeBinary(
         remainingSnapshotSourceMs(deadline, 'native-build-deadline');
         await input.host.ensureDirectory(temporaryPath);
         const outputPath = path.join(temporaryPath, BRIDGE_FILENAME);
-        const result = await input.host.run(
-          'xcrun',
-          [
-            '--sdk',
-            'iphonesimulator',
-            'clang',
-            '-arch',
-            toolchain.architecture,
-            '-mios-simulator-version-min=15.0',
-            '-fobjc-arc',
-            '-Werror',
-            '-Wall',
-            '-Wextra',
-            '-framework',
-            'Foundation',
-            '-framework',
-            'CoreGraphics',
-            ...SNAPSHOT_BRIDGE_COMPILE_FILENAMES.map((sourceFile) =>
-              path.join(sourceRoot, sourceFile),
-            ),
-            '-o',
-            outputPath,
-          ],
-          {
-            signal: deadline.signal,
-            timeoutMs: Math.min(
-              BUILD_TIMEOUT_MS,
-              remainingSnapshotSourceMs(deadline, 'native-build-deadline'),
-            ),
-            allowFailure: true,
-          },
+        const result = await compileSnapshotBridge(
+          input.host,
+          deadline,
+          toolchain.architecture,
+          sourceRoot,
+          outputPath,
         );
         if (result.exitCode !== 0 || !input.host.exists(outputPath)) {
           throw snapshotSourceError('unsupported', 'native-build-failed', {
@@ -159,6 +135,64 @@ export async function ensureSnapshotBridgeBinary(
   });
 }
 
+/**
+ * One clang invocation for the bridge sources. A compile exec this module asked to be killed is
+ * reported with the budget it hit: after the identity read stopped opening `xcrun` of its own
+ * (#2712), this is the process's first `xcrun` exec, and the exec layer's bare
+ * `xcrun timed out after Nms` would land on a job as an unattributed command failure again.
+ */
+async function compileSnapshotBridge(
+  host: SnapshotSourceHost,
+  deadline: SnapshotSourceDeadline,
+  architecture: SnapshotSourceToolchainIdentity['architecture'],
+  sourceRoot: string,
+  outputPath: string,
+): Promise<ExecResult> {
+  const timeoutMs = Math.min(
+    BUILD_TIMEOUT_MS,
+    remainingSnapshotSourceMs(deadline, 'native-build-deadline'),
+  );
+  try {
+    return await host.run(
+      'xcrun',
+      [
+        '--sdk',
+        'iphonesimulator',
+        'clang',
+        '-arch',
+        architecture,
+        '-mios-simulator-version-min=15.0',
+        '-fobjc-arc',
+        '-Werror',
+        '-Wall',
+        '-Wextra',
+        '-framework',
+        'Foundation',
+        '-framework',
+        'CoreGraphics',
+        ...SNAPSHOT_BRIDGE_COMPILE_FILENAMES.map((sourceFile) => path.join(sourceRoot, sourceFile)),
+        '-o',
+        outputPath,
+      ],
+      { signal: deadline.signal, timeoutMs, allowFailure: true },
+    );
+  } catch (error) {
+    if (!isCommandTimeoutError(error)) throw error;
+    throw snapshotSourceError(
+      'timeout',
+      'native-build-stalled',
+      {
+        timeoutMs,
+        hint:
+          `The Simulator SDK toolchain did not answer within ${timeoutMs}ms, which stopped the bridge ` +
+          `build before clang reported anything. Run \`xcrun --sdk iphonesimulator clang --version\` ` +
+          `by hand until it answers, then retry.`,
+      },
+      error,
+    );
+  }
+}
+
 function resolveSnapshotBridgeSourceRoot(host: SnapshotSourceHost): string {
   const projectRoot = host.projectRoot();
   const checkoutRoot = path.join(projectRoot, 'apple', 'snapshot-bridge');

From b38b1f9c8c7d114f31424e56818af36c13722e74 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Wed, 23 Sep 2026 10:09:31 +0200
Subject: [PATCH 030/132] refactor(replay): bootstrap packages/replay-port with
 the builtin-vars leaf (#2663) (#2769)

* refactor(replay): move the builtin-vars leaf into a new packages/replay-port

Bootstraps the daemon-side replay port at the destination decided in #2663.
The self-contained builtin-vars module (type-only contracts/ad-script deps, no
inbound daemon coupling) moves out; the two staying importers take the owning
subpath directly. No compatibility re-export: src/daemon/replay keeps its
facade for everything not yet moved.

Part of #2663

* chore(gates): register packages/replay-port in the layering model, ownership table, and build

Ranked spine rank 1 (with the engines it composes), a replay-port ownership
policy forbidding src/daemon|providers|compat, the workspace dep + typecheck
build entry, and the regenerated lockfile.

Part of #2663
---
 package.json                                   |  3 ++-
 packages/replay-port/package.json              | 18 ++++++++++++++++++
 .../session-replay-builtin-vars.test.ts        |  0
 .../replay-port/src}/session-replay-vars.ts    |  0
 packages/replay-port/tsconfig.json             | 12 ++++++++++++
 pnpm-lock.yaml                                 | 12 ++++++++++++
 scripts/layering/architecture-ownership.ts     |  5 +++++
 scripts/layering/model.ts                      |  1 +
 .../internal/session-replay-maestro-runtime.ts |  2 +-
 .../internal/session-replay-runtime-plan.ts    |  2 +-
 10 files changed, 52 insertions(+), 3 deletions(-)
 create mode 100644 packages/replay-port/package.json
 rename {src/daemon/replay/internal => packages/replay-port/src}/__tests__/session-replay-builtin-vars.test.ts (100%)
 rename {src/daemon/replay/internal => packages/replay-port/src}/session-replay-vars.ts (100%)
 create mode 100644 packages/replay-port/tsconfig.json

diff --git a/package.json b/package.json
index 11d3d7b1be..252d486080 100644
--- a/package.json
+++ b/package.json
@@ -171,7 +171,7 @@
     "check:unit": "pnpm test:unit && pnpm check:tmpdir-leaks && pnpm test:smoke",
     "check": "pnpm check:tooling && pnpm check:fallow && pnpm check:unit",
     "prepack": "pnpm check:mcp-metadata && pnpm package:npm",
-    "typecheck": "tsc -b packages/xml packages/kernel packages/contracts packages/device-selection packages/host-kit packages/capture-kit packages/managed-allocation packages/provision-kit packages/platform-apple packages/platform-android packages/platform-harmonyos packages/platform-vega packages/platform-linux packages/platform-web packages/ad-script packages/selectors packages/command-registry packages/session-journal packages/ad-replay packages/maestro packages/replay-test packages/provider-webdriver packages/provider-limrun && tsc -p tsconfig.json && tsc -p examples/sdk/tsconfig.json",
+    "typecheck": "tsc -b packages/xml packages/kernel packages/contracts packages/device-selection packages/host-kit packages/capture-kit packages/managed-allocation packages/provision-kit packages/platform-apple packages/platform-android packages/platform-harmonyos packages/platform-vega packages/platform-linux packages/platform-web packages/ad-script packages/selectors packages/command-registry packages/session-journal packages/ad-replay packages/maestro packages/replay-port packages/replay-test packages/provider-webdriver packages/provider-limrun && tsc -p tsconfig.json && tsc -p examples/sdk/tsconfig.json",
     "test-app:install": "pnpm install --dir examples/test-app",
     "test-app:start": "pnpm --dir examples/test-app start",
     "test-app:ios": "pnpm --dir examples/test-app ios",
@@ -298,6 +298,7 @@
     "@agent-device/provider-limrun": "workspace:*",
     "@agent-device/provider-webdriver": "workspace:*",
     "@agent-device/provision-kit": "workspace:*",
+    "@agent-device/replay-port": "workspace:*",
     "@agent-device/replay-test": "workspace:*",
     "@agent-device/selectors": "workspace:*",
     "@agent-device/session-journal": "workspace:*",
diff --git a/packages/replay-port/package.json b/packages/replay-port/package.json
new file mode 100644
index 0000000000..8d438f07cd
--- /dev/null
+++ b/packages/replay-port/package.json
@@ -0,0 +1,18 @@
+{
+  "name": "@agent-device/replay-port",
+  "version": "0.0.0",
+  "private": true,
+  "sideEffects": false,
+  "type": "module",
+  "description": "Daemon-side replay port: the adapter over the ad-replay, ad-script and replay-test engines.",
+  "dependencies": {
+    "@agent-device/ad-script": "workspace:*",
+    "@agent-device/contracts": "workspace:*"
+  },
+  "exports": {
+    "./session-replay-vars": {
+      "types": "./src/session-replay-vars.ts",
+      "default": "./src/session-replay-vars.ts"
+    }
+  }
+}
diff --git a/src/daemon/replay/internal/__tests__/session-replay-builtin-vars.test.ts b/packages/replay-port/src/__tests__/session-replay-builtin-vars.test.ts
similarity index 100%
rename from src/daemon/replay/internal/__tests__/session-replay-builtin-vars.test.ts
rename to packages/replay-port/src/__tests__/session-replay-builtin-vars.test.ts
diff --git a/src/daemon/replay/internal/session-replay-vars.ts b/packages/replay-port/src/session-replay-vars.ts
similarity index 100%
rename from src/daemon/replay/internal/session-replay-vars.ts
rename to packages/replay-port/src/session-replay-vars.ts
diff --git a/packages/replay-port/tsconfig.json b/packages/replay-port/tsconfig.json
new file mode 100644
index 0000000000..935c871a4d
--- /dev/null
+++ b/packages/replay-port/tsconfig.json
@@ -0,0 +1,12 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "composite": true,
+    "noEmit": false,
+    "emitDeclarationOnly": true,
+    "declaration": true,
+    "declarationDir": "./dist-types",
+    "rootDir": "./src"
+  },
+  "include": ["src"]
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 5eecf5bf5c..7989d46b82 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -74,6 +74,9 @@ importers:
       '@agent-device/provision-kit':
         specifier: workspace:*
         version: link:packages/provision-kit
+      '@agent-device/replay-port':
+        specifier: workspace:*
+        version: link:packages/replay-port
       '@agent-device/replay-test':
         specifier: workspace:*
         version: link:packages/replay-test
@@ -501,6 +504,15 @@ importers:
         specifier: 7.29.0
         version: 7.29.0
 
+  packages/replay-port:
+    dependencies:
+      '@agent-device/ad-script':
+        specifier: workspace:*
+        version: link:../ad-script
+      '@agent-device/contracts':
+        specifier: workspace:*
+        version: link:../contracts
+
   packages/replay-test:
     dependencies:
       '@agent-device/contracts':
diff --git a/scripts/layering/architecture-ownership.ts b/scripts/layering/architecture-ownership.ts
index b1b269d331..86e3927f27 100644
--- a/scripts/layering/architecture-ownership.ts
+++ b/scripts/layering/architecture-ownership.ts
@@ -142,6 +142,11 @@ export const LOGICAL_MODULE_POLICIES = [
       'packages/ad-replay/',
     ],
   },
+  {
+    name: 'replay-port',
+    roots: ['packages/replay-port/src/'],
+    forbiddenTargetRoots: ['src/daemon/', 'src/providers/', 'src/compat/'],
+  },
   {
     name: 'daemon-replay',
     roots: ['src/daemon/replay/'],
diff --git a/scripts/layering/model.ts b/scripts/layering/model.ts
index 7818a6bf56..741c9188ca 100644
--- a/scripts/layering/model.ts
+++ b/scripts/layering/model.ts
@@ -50,6 +50,7 @@ const TARGET_DAG_RANK = new Map([
   ['contracts', 1],
   ['device-selection', 1],
   ['maestro', 1],
+  ['replay-port', 1],
   ['replay-test', 1],
   ['screenshot-diff', 1],
   ['selectors', 1],
diff --git a/src/daemon/replay/internal/session-replay-maestro-runtime.ts b/src/daemon/replay/internal/session-replay-maestro-runtime.ts
index 67804c353b..1e9a960197 100644
--- a/src/daemon/replay/internal/session-replay-maestro-runtime.ts
+++ b/src/daemon/replay/internal/session-replay-maestro-runtime.ts
@@ -17,7 +17,7 @@ import {
 } from '@agent-device/ad-script';
 import { createDaemonMaestroRuntimePort } from '@agent-device/maestro/daemon-runtime-port';
 import type { DeviceInfo } from '@agent-device/kernel/device';
-import { buildReplayBuiltinVars } from './session-replay-vars.ts';
+import { buildReplayBuiltinVars } from '@agent-device/replay-port/session-replay-vars';
 import { createMaestroReplayObserver } from './session-replay-maestro-observer.ts';
 import { maestroOperationDispatchRequest } from './session-replay-maestro-request.ts';
 import {
diff --git a/src/daemon/replay/internal/session-replay-runtime-plan.ts b/src/daemon/replay/internal/session-replay-runtime-plan.ts
index 9c9a7db3dc..605ca42827 100644
--- a/src/daemon/replay/internal/session-replay-runtime-plan.ts
+++ b/src/daemon/replay/internal/session-replay-runtime-plan.ts
@@ -22,7 +22,7 @@ import {
   resolveReplayFormat,
   type ReplayScriptMetadata,
 } from '@agent-device/ad-script';
-import { buildReplayBuiltinVars } from './session-replay-vars.ts';
+import { buildReplayBuiltinVars } from '@agent-device/replay-port/session-replay-vars';
 import { runTypedMaestroReplay } from './session-replay-maestro-runtime.ts';
 import { errorResponse, type DaemonResponse } from '@agent-device/kernel/contracts';
 

From 15ae636f20fb78bc7ff101747e65f7e9fe8681b9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Wed, 23 Sep 2026 12:00:54 +0200
Subject: [PATCH 031/132] fix(recording): export touch overlay at capture size,
 never black (#2707) (#2767)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The overlay burn-in re-encoded through AVAssetExportPresetMediumQuality, a
fixed-canvas preset that caps the long edge at 480px, collapsing any touch
recording to ~220x480 (480x220 landscape) and going all-black on long clips,
always with exit 0. --hide-touches and an empty gesture list copy the raw
capture through, so only the composited path was affected.

Both quality tiers now export through the one geometry-preserving preset
(HighestQuality); the hardware encoder makes the full-resolution re-encode
cheap. The compositor now verifies its own output against the raw before the
caller adopts it — resolved track size must match, and a uniformly black track
whose raw had visible content is rejected — and throws on failure so the
overlay is dropped, the raw kept, and the choice reported as overlayWarning
rather than a broken file. Adds an mp4 transform-aware track-size reader and a
device-lane assertion that a touched export equals its --hide-touches control.

Co-authored-by: dev <dev@example.com>
---
 .../RecordingScripts/recording-overlay.swift  | 170 +++++++++++++++---
 docs/adr/0025-foldable-apple-panels.md        |  68 +++++--
 docs/agents/device-verification.md            |  15 +-
 .../src/flag-definitions-action.ts            |   2 +-
 ...me-screen-recording-finalizer-host.test.ts |  74 +++++++-
 test/integration/recording-overlay.test.ts    | 101 +++++++++++
 .../support/recording-inspect.swift           |   4 +
 test/integration/test-helpers.ts              |   2 +
 website/docs/docs/commands.md                 |   2 +-
 9 files changed, 388 insertions(+), 50 deletions(-)

diff --git a/apple/runner/AgentDeviceRunner/RecordingScripts/recording-overlay.swift b/apple/runner/AgentDeviceRunner/RecordingScripts/recording-overlay.swift
index 60f036921f..9c8077fb09 100644
--- a/apple/runner/AgentDeviceRunner/RecordingScripts/recording-overlay.swift
+++ b/apple/runner/AgentDeviceRunner/RecordingScripts/recording-overlay.swift
@@ -11,6 +11,13 @@ let minimumPinchVisibility: CFTimeInterval = 0.5
 let swipeVisibilityTail: CFTimeInterval = 0.16
 let trailOpacityKeyTimes: [NSNumber] = [0.0, 0.08, 0.62, 1.0]
 
+// A compositor that cannot render frames still completes with an empty track, so a whole frame at
+// or below this mean luma counts as black.
+let compositedBlackFrameLuma: Double = 1.0
+// Above this mean luma the raw capture is taken to hold visible content worth preserving. Below it
+// the recording itself is dark, so a dark composite is the content and not a compositor failure.
+let sourceVisibleFrameLuma: Double = 2.0
+
 struct GestureEnvelope: Decodable {
   let events: [GestureEvent]
 }
@@ -126,10 +133,10 @@ func run() throws {
     in: parentLayer
   )
 
-  // Overlay burn-in forces a full re-encode; medium quality keeps simulator videos readable
-  // while avoiding very slow highest-quality exports. Pass --quality high to opt into
-  // the slower highest-quality export.
-  let presetName = exportPresetName(for: parsedArgs.exportQuality, compatibleWith: composition)
+  // Overlay burn-in forces a full re-encode. The export has to keep the captured track's own
+  // dimensions, so it uses the one preset that preserves arbitrary capture geometry; the hardware
+  // encoder makes the full-resolution re-encode cheap (measured ~1-2s for a 90s 1206x2622 clip).
+  let presetName = try exportPresetName(compatibleWith: composition)
   let exporter = try makeRecordingExporter(
     composition,
     presetName: presetName,
@@ -141,17 +148,19 @@ func run() throws {
     timeoutMessage: "Touch overlay export timed out.",
     failureMessage: "Touch overlay export failed."
   )
+  try verifyCompositedOverlay(
+    input: inputURL,
+    output: outputURL,
+    expectedRenderSize: renderSize
+  )
 }
 
 func parseArguments(
   _ arguments: [String]
-) throws -> (inputPath: String, outputPath: String, eventsPath: String, exportQuality: ExportQuality) {
+) throws -> (inputPath: String, outputPath: String, eventsPath: String) {
   var inputPath: String?
   var outputPath: String?
   var eventsPath: String?
-  // Export quality defaults to medium so existing callers keep the fast, simulator-friendly
-  // export. Pass --quality high to opt into a slower highest-quality export.
-  var exportQuality: ExportQuality = .medium
   var index = 0
 
   while index < arguments.count {
@@ -168,11 +177,13 @@ func parseArguments(
       eventsPath = try recordingOptionValue(arguments, nextIndex, "--events")
       index += 2
     case "--quality":
+      // Accepted for CLI parity with the other backends and still validated, but the composited
+      // export always preserves the captured geometry (see `exportPresetName`), so the tier never
+      // picks a resolution-capping preset and is not retained.
       let rawValue = try recordingOptionValue(arguments, nextIndex, "--quality")
-      guard let parsed = ExportQuality(rawValue: rawValue) else {
+      guard ExportQuality(rawValue: rawValue) != nil else {
         throw RecordingScriptError.invalidArgs("--quality must be one of: medium, high")
       }
-      exportQuality = parsed
       index += 2
     default:
       throw RecordingScriptError.invalidArgs("Unknown argument: \(argument)")
@@ -184,24 +195,22 @@ func parseArguments(
       "Usage: recording-overlay.swift --input <video> --output <video> --events <json> [--quality <medium|high>]"
     )
   }
-  return (inputPath, outputPath, eventsPath, exportQuality)
+  return (inputPath, outputPath, eventsPath)
 }
 
-func exportPresetName(
-  for exportQuality: ExportQuality,
-  compatibleWith asset: AVAsset
-) -> String {
-  switch exportQuality {
-  case .high:
-    return AVAssetExportPresetHighestQuality
-  case .medium:
-    // Prefer the faster medium preset, falling back to highest quality only when medium is
-    // not available for this composition.
-    let compatible = AVAssetExportSession.exportPresets(compatibleWith: asset)
-    return compatible.contains(AVAssetExportPresetMediumQuality)
-      ? AVAssetExportPresetMediumQuality
-      : AVAssetExportPresetHighestQuality
+/// The composited overlay must keep the captured track's dimensions, so it can only use a preset
+/// that preserves source geometry. The fixed-canvas presets rescale the long edge —
+/// `AVAssetExportPresetMediumQuality` caps it at 480px, which is exactly what collapsed every
+/// touch-bearing recording to ~220x480 (#2707). Only `HighestQuality` preserves the capture, and it
+/// is the export for every quality tier, so `--quality` never trades capture resolution away. If a
+/// composition offers no geometry-preserving preset the export refuses rather than rescaling.
+func exportPresetName(compatibleWith asset: AVAsset) throws -> String {
+  guard AVAssetExportSession.exportPresets(compatibleWith: asset).contains(AVAssetExportPresetHighestQuality) else {
+    throw RecordingScriptError.exportFailed(
+      "No geometry-preserving export preset is available; refusing to rescale the capture."
+    )
   }
+  return AVAssetExportPresetHighestQuality
 }
 
 func resolvedRenderSize(for track: AVAssetTrack) -> CGSize {
@@ -209,6 +218,117 @@ func resolvedRenderSize(for track: AVAssetTrack) -> CGSize {
   return CGSize(width: abs(transformed.width), height: abs(transformed.height))
 }
 
+/// Guards the compositor's own contract before the caller adopts its output: the burn-in must keep
+/// the captured track's dimensions, must produce frames, and must not silently become an all-black
+/// track. Any failure throws, dropping the overlay and keeping the raw capture rather than
+/// publishing a broken file with a success exit.
+func verifyCompositedOverlay(input: URL, output: URL, expectedRenderSize: CGSize) throws {
+  let composited = AVURLAsset(url: output)
+  guard let track = composited.tracks(withMediaType: .video).first else {
+    throw RecordingScriptError.exportFailed("Touch overlay export produced no video track.")
+  }
+
+  let producedSize = resolvedRenderSize(for: track)
+  if !renderSizeMatches(producedSize, expectedRenderSize) {
+    throw RecordingScriptError.exportFailed(
+      "Touch overlay export changed the track geometry: \(Int(producedSize.width))x\(Int(producedSize.height)) instead of \(Int(expectedRenderSize.width))x\(Int(expectedRenderSize.height))."
+    )
+  }
+
+  // A compositor that produced no decodable frames is a failure, not an absence of evidence.
+  guard let compositedLuma = meanFrameLuma(of: composited) else {
+    throw RecordingScriptError.exportFailed("Touch overlay export produced no decodable frames.")
+  }
+
+  let source = AVURLAsset(url: input)
+  let sourceDuration = CMTimeGetSeconds(source.duration)
+  let producedDuration = CMTimeGetSeconds(composited.duration)
+  if sourceDuration.isFinite, sourceDuration > 1, producedDuration.isFinite,
+    producedDuration < sourceDuration * 0.5
+  {
+    throw RecordingScriptError.exportFailed(
+      "Touch overlay export truncated the track to \(Int(producedDuration))s of \(Int(sourceDuration))s."
+    )
+  }
+
+  if compositedLuma <= compositedBlackFrameLuma,
+    let sourceLuma = meanFrameLuma(of: source),
+    sourceLuma > sourceVisibleFrameLuma
+  {
+    throw RecordingScriptError.exportFailed(
+      "Touch overlay export produced an all-black track while the raw capture had visible content."
+    )
+  }
+}
+
+func renderSizeMatches(_ produced: CGSize, _ expected: CGSize) -> Bool {
+  // The encoder rounds the stored frame to its coding-block grid, so an honest match tolerates a
+  // few pixels regardless of size. A geometry collapse (the #2707 failure) misses by hundreds.
+  let tolerance: CGFloat = 32
+  return abs(produced.width - expected.width) <= tolerance
+    && abs(produced.height - expected.height) <= tolerance
+}
+
+func meanFrameLuma(of asset: AVURLAsset, sampleCount: Int = 5) -> Double? {
+  let duration = CMTimeGetSeconds(asset.duration)
+  guard duration.isFinite, duration > 0 else { return nil }
+  let generator = AVAssetImageGenerator(asset: asset)
+  generator.appliesPreferredTrackTransform = true
+  generator.requestedTimeToleranceBefore = .positiveInfinity
+  generator.requestedTimeToleranceAfter = .positiveInfinity
+  // Only the mean brightness is wanted, so decode a thumbnail rather than the full frame.
+  generator.maximumSize = CGSize(width: 64, height: 64)
+
+  var total = 0.0
+  var sampled = 0
+  for index in 0..<sampleCount {
+    let fraction = (Double(index) + 0.5) / Double(sampleCount)
+    let time = CMTime(seconds: fraction * duration, preferredTimescale: 600)
+    guard let image = try? generator.copyCGImage(at: time, actualTime: nil),
+      let luma = frameMeanLuma(image)
+    else { continue }
+    total += luma
+    sampled += 1
+  }
+  guard sampled > 0 else { return nil }
+  return total / Double(sampled)
+}
+
+func frameMeanLuma(_ image: CGImage) -> Double? {
+  let width = image.width
+  let height = image.height
+  guard width > 0, height > 0 else { return nil }
+  let bytesPerRow = width * 4
+  var pixels = [UInt8](repeating: 0, count: bytesPerRow * height)
+  let drawn = pixels.withUnsafeMutableBytes { raw -> Bool in
+    guard
+      let context = CGContext(
+        data: raw.baseAddress,
+        width: width,
+        height: height,
+        bitsPerComponent: 8,
+        bytesPerRow: bytesPerRow,
+        space: CGColorSpaceCreateDeviceRGB(),
+        bitmapInfo: CGImageAlphaInfo.premultipliedLast.rawValue
+      )
+    else { return false }
+    context.draw(image, in: CGRect(x: 0, y: 0, width: width, height: height))
+    return true
+  }
+  guard drawn else { return nil }
+
+  var total = 0.0
+  var count = 0
+  for offset in stride(from: 0, to: bytesPerRow * height, by: 4) {
+    total += 0.299 * Double(pixels[offset])
+      + 0.587 * Double(pixels[offset + 1])
+      + 0.114 * Double(pixels[offset + 2])
+    count += 1
+  }
+  guard count > 0 else { return nil }
+  return total / Double(count)
+}
+
 func resolvedFrameDuration(for track: AVAssetTrack) -> CMTime {
   let minFrameDuration = track.minFrameDuration
   if minFrameDuration.isValid && !minFrameDuration.isIndefinite && minFrameDuration.seconds > 0 {
diff --git a/docs/adr/0025-foldable-apple-panels.md b/docs/adr/0025-foldable-apple-panels.md
index f25ace6c96..acc21d64ee 100644
--- a/docs/adr/0025-foldable-apple-panels.md
+++ b/docs/adr/0025-foldable-apple-panels.md
@@ -2,9 +2,9 @@
 
 ## Status
 
-Accepted (2026-09-20; the pose-settle rule amended 2026-09-21 under #2730). Covers iPhone Duo
-(iOS 27.1, `iPhone19,4`) and any Apple device that reports more than one integrated CoreDevice
-display.
+Accepted (2026-09-20; the pose-settle rule amended 2026-09-21 under #2730; the touch-overlay
+export diagnosis corrected 2026-09-22 under #2707). Covers iPhone Duo (iOS 27.1, `iPhone19,4`) and
+any Apple device that reports more than one integrated CoreDevice display.
 
 An iPhone Duo carries two integrated panels — Apple's **outer display** and **inner display** —
 and lights one of them at a time. Which one is lit is the device pose. Two independent facts
@@ -307,18 +307,56 @@ and honors it per panel; sampled mean luma over the whole frame:
 | no `--display` | 2006x2852 | 241.42 |
 
 `record start`/`record stop` exit 0 in both poses, and with `--hide-touches` the export keeps the
-captured geometry (`2006x2852`, mean luma 241.42). Without it the touch-overlay exporter loses the
-track geometry, and on a long clip the frames too.
-
-The trigger is the overlay drawing touch events, not panel rotation. Measured on an iPhone 17
-(iOS 27.0), which has no rotated panel: four seconds with no interaction exports `1206x2622`
-intact, ten seconds containing two taps exports `220x480`, and the same two taps under
-`--hide-touches` export `1206x2622` with the screen content changing across frames. A 97-second
-recording with touches exported `480x220` at mean luma 0.00 throughout. An earlier draft of this
-section blamed the inner panel's `rot90` track, which was wrong: every failing sample then available
-had merely been captured on that panel, and the one non-rotated sample that looked intact had
-contained no touches to draw. Feeding an untouched raw `simctl` capture straight into
-`recording-overlay.swift` reproduces a `0x0` zero-duration output. Tracked in #2707.
+captured geometry (`2006x2852`, mean luma 241.42). Without it, and before #2707 was fixed, the
+touch-overlay exporter lost the track geometry, and on a long clip the frames too.
+
+### The touch-overlay export lost geometry for any capture, not a rotated one (#2707)
+
+The trigger was the overlay drawing touch events, not panel rotation. The #2707 report measured this
+on an iPhone 17 simulator (iOS 27.0, non-rot90 panel), Xcode 27.1 beta: four seconds with no
+interaction exported `1206x2622` intact, ten seconds containing two taps exported `220x480`, and the
+same two taps under `--hide-touches` exported `1206x2622` with the screen content changing across
+frames. A 97-second recording with touches exported `480x220` at mean luma 0.00 throughout.
+
+An earlier draft of this section blamed the inner panel's `rot90` track. That was wrong and predated
+this matrix: every failing sample then available had merely been captured on that panel, and the one
+non-rotated sample that looked intact had contained no touches to draw. Feeding an untouched raw
+`simctl` capture straight into `recording-overlay.swift` just copies it through, which is why
+`--hide-touches` and an empty gesture list kept the capture intact — the collapse lived in the
+overlay export path, not the panel.
+
+The cause was the export preset, measured against a synthetic capture on this host: the burn-in is a
+full re-encode through `AVAssetExportSession`, and the default `medium` tier selected
+`AVAssetExportPresetMediumQuality`, a fixed-canvas preset that rescales the long edge to 480px — a
+`1206x2622` capture lands on `220x480`, a landscape capture on `480x220`. Only
+`AVAssetExportPresetHighestQuality` preserves arbitrary capture geometry, and the hardware encoder
+makes the full-resolution re-encode cheap: 90s at `1206x2622` re-encoded in ~1–2s, so `high` was
+never actually slower.
+
+`recording-overlay.swift` now always exports through the geometry-preserving preset at both quality
+tiers, so `--quality` no longer trades capture resolution away. It also verifies its own output
+before the caller adopts it — the composited track's resolved size must match the capture, and a
+track that went uniformly black while the raw had visible content is rejected — and on either failure
+it throws instead of publishing a broken file, so the overlay is dropped, the raw capture is kept,
+and the choice is reported on the `record stop` response as `overlayWarning`. Feeding the fixed tool
+the same synthetic captures re-measures the failing rows as matching `--hide-touches`:
+
+| Overlay | Interactions | Exported size (before → after) | Black? |
+| --- | --- | --- | --- |
+| default | two taps, 1206x2622 source | `220x480` → `1206x2622` | no |
+| default | taps + scroll, landscape source | `480x220` → source size | no |
+| `--hide-touches` | two taps | `1206x2622` → `1206x2622` | no |
+
+The `after` column is this host's offline synthetic harness, which reproduces the collapse and
+confirms the fix preserves geometry. The completion condition's on-device re-measure of these rows on
+a non-rot90 target and on the Duo inner panel is carried by `test/integration/recording-overlay.test.ts`,
+a device-lane case gated behind `AGENT_DEVICE_RECORDING_E2E` that compares a touched export to a
+`--hide-touches` control, asserts the same track size, and asserts the overlay actually drew.
+
+The device-lane test reads each export's transform-applied size back through AVFoundation —
+`test/integration/support/recording-inspect.swift` reports `renderWidth`/`renderHeight` from the same
+`resolvedRenderSize` the overlay tool uses — so a `rot90` panel is compared upright rather than on its
+sideways coding grid, and no second MP4 geometry parser is added to the shipped packages.
 
 ## Verified on a booted Duo
 
diff --git a/docs/agents/device-verification.md b/docs/agents/device-verification.md
index 247dee1152..a17c9d9750 100644
--- a/docs/agents/device-verification.md
+++ b/docs/agents/device-verification.md
@@ -81,12 +81,15 @@ toolchain per command:
   three poses, active panel capture, and an app interaction. Duo coverage remains local until GHA
   supports the runtime. To inspect the angle independently:
   `xcrun devicectl device motion hinge-angle --device <udid> --session-timeout 1 --timeout 5`.
-- When a recording must show touches, assume it cannot. The touch-overlay exporter loses the track
-  geometry whenever it has touch events to draw — `220x480` on a plain iPhone 17 as well as on the
-  inner panel — and returns all-black frames on long clips, always with exit 0. Record with
-  `record start --hide-touches` and make the interaction legible through its on-screen effect
-  (typed text, navigation, a counter) instead of a cursor. The raw `simctl` capture behind it is
-  correct. See ADR 0025 and #2707.
+- Touch overlays export at the captured track size again (#2707). The burn-in used to re-encode
+  through a fixed 480px preset, so a recording with touches collapsed to `220x480` (landscape
+  `480x220`) on any panel — not just the `rot90` inner one — and went all-black on long clips,
+  always with exit 0. That preset is gone: both quality tiers export through the one
+  geometry-preserving preset, and the compositor now checks its own output (size and non-black)
+  against the raw before publishing it — on failure it drops the overlay, keeps the raw capture, and
+  reports it as `overlayWarning` on `record stop` rather than returning a broken file. Only reach
+  for `record start --hide-touches` when you want the fastest raw capture, not to dodge the defect.
+  See ADR 0025 and #2707.
 - An app must adopt the UIScene lifecycle to launch on iOS 27.1 at all: a legacy
   `UIApplicationDelegate` app traps at launch inside
   `___UIApplicationEvaluateRuntimeIssueForNoSceneLifecycleAdoption`, which reads like a broken
diff --git a/packages/command-registry/src/flag-definitions-action.ts b/packages/command-registry/src/flag-definitions-action.ts
index 7eed5127ff..cd697ca8c3 100644
--- a/packages/command-registry/src/flag-definitions-action.ts
+++ b/packages/command-registry/src/flag-definitions-action.ts
@@ -52,7 +52,7 @@ export const ACTION_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
     type: 'string',
     usageLabel: '--quality <medium|high>',
     usageDescription:
-      'Record: output quality preset; Android maps this to screenrecord bitrate, Apple targets use it for export/encoding, Limrun sessions map medium to recorder quality 5 and high to 8. Legacy numeric values 5-7 map to medium; 8-10 map to high',
+      'Record: output quality preset; Android maps this to screenrecord bitrate, Limrun sessions map medium to recorder quality 5 and high to 8; Apple export always preserves the captured resolution, so it has no effect there. Legacy numeric values 5-7 map to medium; 8-10 map to high',
     projectConfig: true,
     recorded: true,
   },
diff --git a/src/platform-runtime-screen-recording-finalizer-host.test.ts b/src/platform-runtime-screen-recording-finalizer-host.test.ts
index ff10ef3705..44a9f12573 100644
--- a/src/platform-runtime-screen-recording-finalizer-host.test.ts
+++ b/src/platform-runtime-screen-recording-finalizer-host.test.ts
@@ -1,4 +1,4 @@
-import { expect, test, vi } from 'vitest';
+import { beforeEach, expect, test, vi } from 'vitest';
 import { createScreenRecordingFinalizer } from './platform-runtime-screen-recording-finalizer-host.ts';
 
 const video = vi.hoisted(() => ({
@@ -8,6 +8,7 @@ const video = vi.hoisted(() => ({
   container: vi.fn(async () => true),
 }));
 const telemetry = vi.hoisted(() => vi.fn(() => '/tmp/capture.telemetry.json'));
+const overlay = vi.hoisted(() => vi.fn(async () => {}));
 vi.mock('@agent-device/capture-kit/recording-video', () => ({
   waitForStableFile: video.stable,
   waitForPlayableVideo: video.playable,
@@ -19,9 +20,20 @@ vi.mock('@agent-device/capture-kit/recording-telemetry', () => ({
 }));
 vi.mock('@agent-device/capture-kit/recording-overlay', () => ({
   getRecordingOverlaySupportWarning: () => undefined,
-  overlayRecordingTouches: vi.fn(async () => {}),
+  overlayRecordingTouches: overlay,
 }));
 
+// The mocks are module-level, so a leaked call count or queued once-value from one case would make
+// the next pass for the wrong reason. Restore the hoisted defaults and clear history per test; the
+// per-test mockRejectedValueOnce/mockResolvedValueOnce overrides run after this and still win.
+beforeEach(() => {
+  overlay.mockReset().mockResolvedValue(undefined);
+  video.stable.mockReset().mockResolvedValue(undefined);
+  video.playable.mockReset().mockResolvedValue(undefined);
+  video.isPlayable.mockReset().mockResolvedValue(true);
+  video.container.mockReset().mockResolvedValue(true);
+});
+
 test('requires stable playable media before publishing finalization telemetry', async () => {
   const result = await createScreenRecordingFinalizer().complete({
     outputPath: '/tmp/capture.mp4',
@@ -56,6 +68,64 @@ test('names the retry and the escape for a recording that never became playable'
   });
 });
 
+test('burns touches into a playable recording without a warning', async () => {
+  const result = await createScreenRecordingFinalizer().complete({
+    outputPath: '/tmp/capture.mp4',
+    showTouches: true,
+    gestureEvents: [{ kind: 'tap', tMs: 500, x: 10, y: 20 }],
+    targetLabel: 'test recording',
+  });
+
+  expect(overlay).toHaveBeenCalledTimes(1);
+  expect(result).toEqual({ telemetryPath: '/tmp/capture.telemetry.json' });
+});
+
+test('#2707 reports a dropped overlay and keeps the raw when compositing throws', async () => {
+  // overlay.ts verifies the composite and only renames it over the raw on success, so a compositor
+  // that fails its own #2707 checks throws before any rename: the raw file survives and the caller
+  // learns of the drop from the response, not from a black or shrunken file. This locks the
+  // finalizer's drop-and-report contract; the preset/black checks themselves are proven by the
+  // AGENT_DEVICE_RECORDING_E2E device lane, which is red against the old 480px preset.
+  overlay.mockRejectedValueOnce(
+    new Error(
+      'Touch overlay export produced an all-black track while the raw capture had visible content.',
+    ),
+  );
+
+  const result = await createScreenRecordingFinalizer().complete({
+    outputPath: '/tmp/capture.mp4',
+    showTouches: true,
+    gestureEvents: [{ kind: 'tap', tMs: 500, x: 10, y: 20 }],
+    targetLabel: 'test recording',
+  });
+
+  expect(result).toMatchObject({
+    telemetryPath: '/tmp/capture.telemetry.json',
+    overlayWarning: expect.stringContaining('failed to overlay recording touches'),
+  });
+});
+
+test('#2707 reports a warning when a composited recording turns unplayable after burn-in', async () => {
+  // Narrower than it looks: overlay.ts confirms the composite playable before renaming, so this only
+  // models the post-rename TOCTOU where the file the raw was replaced with goes unplayable. The raw
+  // is already overwritten here, so the finalizer can report but not restore — it must not exit 0
+  // silently, which the pre-rename probe and the Swift check already prevent for ordinary failures.
+  overlay.mockImplementationOnce(async () => {
+    video.isPlayable.mockResolvedValueOnce(false);
+  });
+
+  const result = await createScreenRecordingFinalizer().complete({
+    outputPath: '/tmp/capture.mp4',
+    showTouches: true,
+    gestureEvents: [{ kind: 'tap', tMs: 500, x: 10, y: 20 }],
+    targetLabel: 'test recording',
+  });
+
+  expect(result).toMatchObject({
+    overlayWarning: expect.stringContaining('failed to overlay recording touches'),
+  });
+});
+
 test('sniffs a collected copy without spawning the validator, and refuses one with no container', async () => {
   const validatorCalls = video.isPlayable.mock.calls.length + video.playable.mock.calls.length;
   await expect(
diff --git a/test/integration/recording-overlay.test.ts b/test/integration/recording-overlay.test.ts
index bc74de3a34..c3eebff313 100644
--- a/test/integration/recording-overlay.test.ts
+++ b/test/integration/recording-overlay.test.ts
@@ -12,6 +12,107 @@ import {
 
 const recordingE2EEnabled = isTruthy(process.env.AGENT_DEVICE_RECORDING_E2E);
 
+test(
+  'recording tap overlay keeps the raw track size on iOS simulator',
+  {
+    skip: shouldSkipIosRecordingE2E(),
+  },
+  () => {
+    // #2707: the composited overlay used to be re-encoded through a fixed 480px preset, collapsing a
+    // touch recording to ~220x480 while `--hide-touches` kept the capture. "File exists and is
+    // non-zero bytes" passed every broken export, so this compares the touched export to a control
+    // that skipped the overlay and asserts the same track size for the same scripted tap.
+    const integration = createRecordingIntegrationContext('ios', 'recording-ios-tap-size');
+    const session = ['--session', 'recording-ios-tap-size'];
+    const controlPath = path.join(integration.artifactDir(), 'ios-tap-raw.mp4');
+    const touchesPath = path.join(integration.artifactDir(), 'ios-tap-overlay.mp4');
+    let recordingStarted = false;
+    let recordingStopped = false;
+    try {
+      integration.runStep('open settings', [
+        'open',
+        'com.apple.Preferences',
+        '--platform',
+        'ios',
+        '--relaunch',
+        '--json',
+        ...session,
+      ]);
+      // AVFoundation owns the track geometry the same way the overlay tool does: read each export's
+      // transform-applied render size back through the inspect tool, no second MP4 parser.
+      const control = recordTap(
+        integration,
+        session,
+        controlPath,
+        ['--hide-touches'],
+        'ios-tap-raw',
+      );
+      const touches = recordTap(integration, session, touchesPath, [], 'ios-tap-overlay');
+      recordingStarted = true;
+      recordingStopped = true;
+      const controlSize = {
+        width: control.manifest.renderWidth,
+        height: control.manifest.renderHeight,
+      };
+      const touchesSize = {
+        width: touches.manifest.renderWidth,
+        height: touches.manifest.renderHeight,
+      };
+      assert.deepEqual(
+        touchesSize,
+        controlSize,
+        'a touched recording must export at the raw capture size (#2707)',
+      );
+      assert.ok(
+        touchesSize.width > 480 && touchesSize.height > 480,
+        `expected the overlay export above the 480px collapse (#2707), saw ${touchesSize.width}x${touchesSize.height}`,
+      );
+      // Matching size alone is not enough: a dropped overlay would keep the raw capture and match too.
+      // Prove the compositor kept its overlay (no warning) and that the touch actually drew.
+      assert.equal(
+        touches.stop.json?.data?.overlayWarning,
+        undefined,
+        'the compositor must not drop the overlay for a black or wrong-size export (#2707)',
+      );
+      assertOverlayForKind(touches.manifest, 'tap', { minPixelCount: 180, maxCenterDistance: 80 });
+    } finally {
+      cleanupRecordingSession(integration, session, recordingStarted, recordingStopped);
+    }
+  },
+);
+
+type TapRecording = {
+  stop: ReturnType<typeof runCliJson>;
+  manifest: RecordingInspectionManifest;
+};
+
+function recordTap(
+  integration: ReturnType<typeof createRecordingIntegrationContext>,
+  session: string[],
+  outPath: string,
+  startFlags: string[],
+  inspectPrefix: string,
+): TapRecording {
+  integration.runStep('record start', [
+    'record',
+    'start',
+    outPath,
+    '--json',
+    ...startFlags,
+    ...session,
+  ]);
+  integration.runStep('tap general', ['click', 'role=cell', 'label=General', '--json', ...session]);
+  const stop = integration.runStep('record stop', ['record', 'stop', '--json', ...session]);
+  assertRecordingArtifacts(stop, outPath);
+  const manifest = inspectRecording(
+    outPath,
+    String(stop.json?.data?.telemetryPath),
+    integration.artifactDir(),
+    inspectPrefix,
+  );
+  return { stop, manifest };
+}
+
 test('recording tap overlay on iOS simulator', { skip: shouldSkipIosRecordingE2E() }, () => {
   runRecordingOverlayCase({
     platform: 'ios',
diff --git a/test/integration/support/recording-inspect.swift b/test/integration/support/recording-inspect.swift
index 58658cec28..0bfcd00415 100644
--- a/test/integration/support/recording-inspect.swift
+++ b/test/integration/support/recording-inspect.swift
@@ -33,6 +33,8 @@ struct InspectionManifest: Encodable {
 
   let generatedAt: String
   let inputPath: String
+  let renderWidth: Int
+  let renderHeight: Int
   let items: [Item]
 }
 
@@ -131,6 +133,8 @@ func run() throws {
   let manifest = InspectionManifest(
     generatedAt: ISO8601DateFormatter().string(from: Date()),
     inputPath: inputURL.path,
+    renderWidth: Int(renderSize.width.rounded()),
+    renderHeight: Int(renderSize.height.rounded()),
     items: manifestItems
   )
   let manifestURL = outputDirURL.appendingPathComponent("manifest.json")
diff --git a/test/integration/test-helpers.ts b/test/integration/test-helpers.ts
index 4dd657cca8..7bf5e763f0 100644
--- a/test/integration/test-helpers.ts
+++ b/test/integration/test-helpers.ts
@@ -40,6 +40,8 @@ type AssertResultOptions = {
 export type RecordingInspectionManifest = {
   generatedAt: string;
   inputPath: string;
+  renderWidth: number;
+  renderHeight: number;
   items: Array<{
     index: number;
     kind: string;
diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md
index cb815c2e4e..f398d74278 100644
--- a/website/docs/docs/commands.md
+++ b/website/docs/docs/commands.md
@@ -1135,7 +1135,7 @@ tail -50 ~/.agent-device/sessions/default/app.log
 - Physical iOS device capture is best-effort: dropped frames are expected and true 60 FPS is not guaranteed even with `--fps 60`.
 - Physical-device capture defaults to 15 FPS.
 - `--fps <n>` (1-120) applies to physical iOS device recording as an explicit FPS cap.
-- `--quality <medium|high>` controls recording output quality. Android maps it to `adb shell screenrecord --bit-rate`; Apple targets use it for export/encoding; Limrun sessions map it to the provider recorder's quality (`medium` to 5, `high` to 8). `medium` is the default; pass `high` for evidence, release notes, or debugging visual artifacts. Legacy numeric values are still accepted for compatibility: `5`-`7` map to `medium`, and `8`-`10` map to `high`.
+- `--quality <medium|high>` controls recording output quality. Android maps it to `adb shell screenrecord --bit-rate`; Limrun sessions map it to the provider recorder's quality (`medium` to 5, `high` to 8). Apple export always preserves the captured resolution, so `--quality` has no effect on Apple output size. `medium` is the default; pass `high` for evidence, release notes, or debugging visual artifacts. Legacy numeric values are still accepted for compatibility: `5`-`7` map to `medium`, and `8`-`10` map to `high`.
 
 ## Tracing
 

From a55b88a495858a76b13f8b5aa915543a72868cf1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Wed, 23 Sep 2026 14:13:11 +0200
Subject: [PATCH 032/132] refactor(contracts): move unconfirmed fill evidence
 into a leaf module (#2778)

* refactor(contracts): give unconfirmed fill evidence its own leaf module

FillUnconfirmedVerification and FillVerificationTarget lived in interactor-types.ts,
so interaction.ts had to read that file for the fill response shape while
interactor-types.ts reads scroll-command.ts, which reads interaction.ts back: a
three-file type-only cycle. Declare the two shapes in a leaf and let both
consumers read them from there.

* chore(gates): name the contracts fill-evidence subpath and refresh its export snapshot

@agent-device/contracts uses an explicit export map, so the new leaf needs its own
entry before platform-android and the daemon can read it. Regenerate
contracts-exports.snapshot.json, which package-boundaries.test.ts diffs against the
live manifest, in the same commit.
---
 packages/contracts/package.json               |  4 +++
 packages/contracts/src/fill-evidence.ts       | 30 +++++++++++++++++++
 packages/contracts/src/interaction.ts         |  2 +-
 packages/contracts/src/interactor-types.ts    | 16 +---------
 .../platform-android/src/fill-verification.ts |  2 +-
 packages/platform-android/src/text-input.ts   |  2 +-
 .../layering/contracts-exports.snapshot.json  |  1 +
 src/daemon/fill-backend-result.ts             |  2 +-
 8 files changed, 40 insertions(+), 19 deletions(-)
 create mode 100644 packages/contracts/src/fill-evidence.ts

diff --git a/packages/contracts/package.json b/packages/contracts/package.json
index 8a1000fb98..d7cfadd309 100644
--- a/packages/contracts/package.json
+++ b/packages/contracts/package.json
@@ -188,6 +188,10 @@
       "types": "./src/element-text-runtime.ts",
       "default": "./src/element-text-runtime.ts"
     },
+    "./fill-evidence": {
+      "types": "./src/fill-evidence.ts",
+      "default": "./src/fill-evidence.ts"
+    },
     "./fold-runtime": {
       "types": "./src/fold-runtime.ts",
       "default": "./src/fold-runtime.ts"
diff --git a/packages/contracts/src/fill-evidence.ts b/packages/contracts/src/fill-evidence.ts
new file mode 100644
index 0000000000..4e9969d89f
--- /dev/null
+++ b/packages/contracts/src/fill-evidence.ts
@@ -0,0 +1,30 @@
+import type { Rect } from '@agent-device/kernel/snapshot';
+
+/**
+ * The evidence a `fill` carries when it changed a field but could not confirm the text it sent.
+ * Both the fill response and `Interactor.fill`'s return need these shapes, so they sit below both
+ * of those modules rather than in either. This is the cross-language shape, not Android's probing:
+ * `packages/platform-android/src/fill-verification.ts` builds Android's copy of it.
+ */
+
+/** The field a fill aimed at, as the platform that performed it names it. */
+export type FillVerificationTarget = {
+  resourceId: string | null;
+  className: string | null;
+  packageName: string | null;
+  rect: Rect;
+};
+
+/**
+ * Target-bound evidence that a fill moved a field's content from `before` to `after` without raw
+ * equality with `requested` being reachable, because app-owned formatting prevents it. Bound to the
+ * {@link FillVerificationTarget} it was collected against so another field, or the same field after
+ * it re-laid out, cannot borrow this evidence.
+ */
+export type FillUnconfirmedVerification = {
+  verification: 'unconfirmed';
+  requested: string;
+  before: string | null;
+  after: string | null;
+  target: FillVerificationTarget;
+};
diff --git a/packages/contracts/src/interaction.ts b/packages/contracts/src/interaction.ts
index 07f276fe5c..09698d2fd3 100644
--- a/packages/contracts/src/interaction.ts
+++ b/packages/contracts/src/interaction.ts
@@ -1,7 +1,7 @@
 import type { Point, SnapshotKeyboardBandFact, SnapshotNode } from '@agent-device/kernel/snapshot';
 import type { ResponseCost } from '@agent-device/kernel/contracts';
 import type { ClickButton } from './click-button.ts';
-import type { FillUnconfirmedVerification } from './interactor-types.ts';
+import type { FillUnconfirmedVerification } from './fill-evidence.ts';
 
 export type SelectorTarget = {
   kind: 'selector';
diff --git a/packages/contracts/src/interactor-types.ts b/packages/contracts/src/interactor-types.ts
index 77f3982c58..96cc751563 100644
--- a/packages/contracts/src/interactor-types.ts
+++ b/packages/contracts/src/interactor-types.ts
@@ -1,6 +1,7 @@
 import type { BackMode } from './back-mode.ts';
 import type { IosSystemSurfaceProvenance } from './ios-system-surface.ts';
 import type { DeviceRotation } from './device-rotation.ts';
+import type { FillUnconfirmedVerification } from './fill-evidence.ts';
 import type { ScrollDirection } from './scroll-gesture.ts';
 import type { ScrollExecutionOptions } from './scroll-command.ts';
 import type { TvRemoteButton } from './tv-remote.ts';
@@ -151,21 +152,6 @@ export const CLOUD_TEXT_ENTRY_READINESS = ['focused-element', 'keyboard-shown']
 
 export type CloudTextEntryReadiness = (typeof CLOUD_TEXT_ENTRY_READINESS)[number];
 
-export type FillVerificationTarget = {
-  resourceId: string | null;
-  className: string | null;
-  packageName: string | null;
-  rect: Rect;
-};
-
-export type FillUnconfirmedVerification = {
-  verification: 'unconfirmed';
-  requested: string;
-  before: string | null;
-  after: string | null;
-  target: FillVerificationTarget;
-};
-
 /**
  * What `Interactor.fill` reports back about the entry it performed. The cloud
  * interactors (WebDriver and the Limrun iOS session) populate
diff --git a/packages/platform-android/src/fill-verification.ts b/packages/platform-android/src/fill-verification.ts
index fca1d9480f..7570a5d7d3 100644
--- a/packages/platform-android/src/fill-verification.ts
+++ b/packages/platform-android/src/fill-verification.ts
@@ -18,7 +18,7 @@ import { androidUiNodes, type AndroidUiNodeMetadata } from './ui-hierarchy.ts';
 import type {
   FillUnconfirmedVerification,
   FillVerificationTarget,
-} from '@agent-device/contracts/interactor-types';
+} from '@agent-device/contracts/fill-evidence';
 
 export type { AndroidFillVerification } from './fill-diagnostics.ts';
 
diff --git a/packages/platform-android/src/text-input.ts b/packages/platform-android/src/text-input.ts
index 59a42d6da0..01e7bec648 100644
--- a/packages/platform-android/src/text-input.ts
+++ b/packages/platform-android/src/text-input.ts
@@ -4,7 +4,7 @@
  * Pointer, key, and gesture actions stay in `input-actions.ts`; what the field ended up holding is
  * `fill-verification.ts`.
  */
-import type { FillUnconfirmedVerification } from '@agent-device/contracts/interactor-types';
+import type { FillUnconfirmedVerification } from '@agent-device/contracts/fill-evidence';
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import { AppError } from '@agent-device/kernel/errors';
 import { emitDiagnostic } from '@agent-device/host-kit/diagnostics';
diff --git a/scripts/layering/contracts-exports.snapshot.json b/scripts/layering/contracts-exports.snapshot.json
index f1e855b964..db1201fb26 100644
--- a/scripts/layering/contracts-exports.snapshot.json
+++ b/scripts/layering/contracts-exports.snapshot.json
@@ -44,6 +44,7 @@
   "@agent-device/contracts/durable-resource",
   "@agent-device/contracts/durable-resource-envelope",
   "@agent-device/contracts/element-text-runtime",
+  "@agent-device/contracts/fill-evidence",
   "@agent-device/contracts/focus-runtime",
   "@agent-device/contracts/fold-runtime",
   "@agent-device/contracts/gesture-admission",
diff --git a/src/daemon/fill-backend-result.ts b/src/daemon/fill-backend-result.ts
index 5182010742..40a2035522 100644
--- a/src/daemon/fill-backend-result.ts
+++ b/src/daemon/fill-backend-result.ts
@@ -2,8 +2,8 @@ import {
   CLOUD_TEXT_ENTRY_READINESS,
   type CloudTextEntryReadiness,
   type FillBackendResult,
-  type FillVerificationTarget,
 } from '@agent-device/contracts/interactor-types';
+import type { FillVerificationTarget } from '@agent-device/contracts/fill-evidence';
 
 type RawUnconfirmedVerification = Record<string, unknown> & {
   requested: string;

From ca2970b3caf97c92a2c5a25283b7de8ad70d8258 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Wed, 23 Sep 2026 14:13:29 +0200
Subject: [PATCH 033/132] fix(ios): derive hittable from geometric
 actionability on the AX bridge (#2775)

The snapshot capability table has declared `hittable = geometric-actionability` for
every iOS backend (#1933), and the XCTest runner has always stamped it. When 0.21.0
made the host AX bridge the Simulator's snapshot source, the bridge reader mapped the
traits word into `enabled` and `selected` but handed over no hit result and disclosed
`hittability` as unavailable on every capture (#2638). A `hittable:` selector therefore
matched nothing on the bridge that the runner would match.

The reader now stamps `hittable` on its raw nodes from the node's own frame and the
reported viewport, using a shared `isGeometricallyActionable` that is the TypeScript twin
of the runner's Swift `SnapshotGeometry.isGeometricallyActionable`, `CGRect.contains`
half-open edges included. It discloses `hittability` as unavailable only when no viewport
is reported, keeping the residue owner the fact owner (#2199). Stamping the raw source
rather than the fold makes `snapshot --raw` match too.

This restores `hittable` parity between the two producers. It does not resolve the two
native-stack Maestro flows that motivated the investigation: those are a separate
behind-modal occlusion capture divergence, tracked apart.

Co-authored-by: Apex <noreply@callstack.com>
---
 CHANGELOG.md                                  | 13 ++++
 .../src/ios-snapshot-acquisition.ts           | 11 ++--
 .../ios-snapshot-engine/geometry-policy.ts    | 14 +----
 .../src/ios-snapshot-engine/geometry.ts       |  2 +-
 packages/contracts/src/ios-snapshot.ts        |  8 ++-
 packages/kernel/src/rect.test.ts              | 59 ++++++++++++++++++-
 packages/kernel/src/rect.ts                   | 26 ++++++++
 .../src/snapshot-source/adapter.test.ts       | 28 ++++++++-
 .../src/snapshot-source/adapter.ts            | 10 +++-
 .../src/snapshot-source/tree.test.ts          | 56 ++++++++++++++++++
 .../src/snapshot-source/tree.ts               | 29 ++++++++-
 11 files changed, 230 insertions(+), 26 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index afea45c5a3..1014a6774f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,19 @@
 
 ## Unreleased
 
+- Fixed (ios): a local Simulator snapshot taken through the host AX bridge once again publishes the
+  geometric `hittable` fact, so `is hittable` and a `hittable:` selector resolve the same controls on
+  the bridge and the XCTest runner. The snapshot capability table has declared `hittable =
+  geometric-actionability` for every backend (#1933), and the runner has always stamped it; when 0.21.0
+  made the AX bridge the Simulator's snapshot source, the bridge reader mapped the traits word into
+  `enabled` and `selected` but handed over no hit result and disclosed `hittability` as unavailable on
+  every capture, so a `hittable:` selector matched nothing on the bridge that the runner would match.
+  The reader now derives `hittable` on its raw nodes from the same rule the runner's Swift uses — the
+  shared `isGeometricallyActionable`, `CGRect.contains` half-open edges and all — applied to the node's
+  own frame and the reported viewport, and discloses `hittability` as unavailable only when no viewport
+  is reported. Because it stamps the raw source rather than the fold, `snapshot --raw` matches too, and
+  the residue owner stays the fact owner (#2199). Closes the hittable-absence half of the AX-bridge
+  capture divergence (#2638).
 - Fixed (ios): a local Simulator snapshot taken through the host AX bridge once again carries the
   accessibility `selected` state, so `is selected`, a `selected=true` selector, and a Maestro
   `selected:` qualifier match the active control. When 0.21.0 made the AX bridge the Simulator's
diff --git a/packages/capture-kit/src/ios-snapshot-acquisition.ts b/packages/capture-kit/src/ios-snapshot-acquisition.ts
index 75821130f7..106c5a0b4f 100644
--- a/packages/capture-kit/src/ios-snapshot-acquisition.ts
+++ b/packages/capture-kit/src/ios-snapshot-acquisition.ts
@@ -17,11 +17,12 @@ import type { RawSnapshotNode, Rect } from '@agent-device/kernel/snapshot';
  * this module derives.
  *
  * `apple-runner` and `simulator-ax-bridge` are absent by construction, not by omission: each
- * builds its own residue at the source (the bridge adapter emits `unavailable-fact: hittability`
- * on every capture; the runner presents and reports its own facts), so a row here would be a
- * declaration with no reader — which is how the table came to claim the bridge had hittability
- * evidence while every bridge-served `snapshot -i` printed the opposite (#2199). Keying the
- * record on {@link IosProviderAcquisitionProducer} makes that claim not compile.
+ * builds its own residue at the source (the bridge reader derives geometric `hittable` onto its
+ * nodes and emits `unavailable-fact: hittability` only when the viewport is missing; the runner
+ * presents and reports its own facts), so a row here would be a declaration with no reader — which
+ * is how the table once came to claim the bridge had hittability evidence while every bridge-served
+ * `snapshot -i` printed the opposite (#2199). Keying the record on
+ * {@link IosProviderAcquisitionProducer} makes that claim not compile.
  */
 const IOS_PROVIDER_ACQUISITION_CAPABILITY_VALUES = {
   'appium-source': {
diff --git a/packages/capture-kit/src/ios-snapshot-engine/geometry-policy.ts b/packages/capture-kit/src/ios-snapshot-engine/geometry-policy.ts
index 0dde0c6f3c..7f0108a68e 100644
--- a/packages/capture-kit/src/ios-snapshot-engine/geometry-policy.ts
+++ b/packages/capture-kit/src/ios-snapshot-engine/geometry-policy.ts
@@ -1,5 +1,5 @@
 import type { Rect, RawSnapshotNode } from '@agent-device/kernel/snapshot';
-import { containsPoint, isPositiveFiniteRect } from '@agent-device/kernel/rect';
+import { isPositiveFiniteRect } from '@agent-device/kernel/rect';
 import { normalizeType } from '@agent-device/contracts/snapshot';
 import type { IosSnapshotFoldPolicy } from './types.ts';
 
@@ -27,18 +27,6 @@ export type GeometryDecision = Readonly<{
   establishesScrollAnchor: boolean;
 }>;
 
-export function isGeometricallyActionable(
-  enabled: boolean,
-  rect: Rect | undefined,
-  viewport: Rect,
-): boolean {
-  return Boolean(
-    enabled &&
-    isPositiveFiniteRect(rect) &&
-    containsPoint(viewport, rect.x + rect.width / 2, rect.y + rect.height / 2),
-  );
-}
-
 export function rootTraversal(): TraversalState {
   return { projectedOut: false };
 }
diff --git a/packages/capture-kit/src/ios-snapshot-engine/geometry.ts b/packages/capture-kit/src/ios-snapshot-engine/geometry.ts
index fd8bf27f6b..61b6345cea 100644
--- a/packages/capture-kit/src/ios-snapshot-engine/geometry.ts
+++ b/packages/capture-kit/src/ios-snapshot-engine/geometry.ts
@@ -1,7 +1,7 @@
 import type { Rect, RawSnapshotNode } from '@agent-device/kernel/snapshot';
+import { isGeometricallyActionable } from '@agent-device/kernel/rect';
 import { validateIosSnapshotGraph } from './graph.ts';
 import {
-  isGeometricallyActionable,
   rootTraversal,
   traversalDecision,
   type BranchState,
diff --git a/packages/contracts/src/ios-snapshot.ts b/packages/contracts/src/ios-snapshot.ts
index 992388edf1..5f84381f26 100644
--- a/packages/contracts/src/ios-snapshot.ts
+++ b/packages/contracts/src/ios-snapshot.ts
@@ -84,9 +84,11 @@ export type IosSnapshotFact =
  * element tree — and deliberately not every {@link IosSnapshotProducer}. `apple-runner` and
  * `simulator-ax-bridge` build their own residue at the source, so a capability declared for
  * them here would be a claim nothing consults: exactly the shape that let the table say the
- * Simulator bridge had hittability evidence while the bridge adapter emitted
- * `unavailable-fact: hittability` on every capture (#2199). Narrowing the producer makes that
- * claim unrepresentable rather than merely wrong.
+ * Simulator bridge had hittability evidence while the bridge adapter published none and emitted
+ * `unavailable-fact: hittability` on every capture (#2199). The bridge now derives geometric
+ * `hittable` at the source and drops that residue when its inputs are established, so a table row
+ * for it would still have no reader. Narrowing the producer makes that claim unrepresentable
+ * rather than merely wrong.
  *
  * Truncation is not a field here: it is the one fact the runner and the bridge also need
  * answered, so it has a single owner over all four producers instead
diff --git a/packages/kernel/src/rect.test.ts b/packages/kernel/src/rect.test.ts
index f4cf34e843..e3c31814d1 100644
--- a/packages/kernel/src/rect.test.ts
+++ b/packages/kernel/src/rect.test.ts
@@ -1,7 +1,12 @@
 import assert from 'node:assert/strict';
 import { test } from 'vitest';
 import type { Rect } from './snapshot.ts';
-import { containsPoint, isRectVisibleInViewport, pickLargestRect } from './rect.ts';
+import {
+  containsPoint,
+  isGeometricallyActionable,
+  isRectVisibleInViewport,
+  pickLargestRect,
+} from './rect.ts';
 
 const VIEWPORT: Rect = { x: 0, y: 0, width: 300, height: 500 };
 
@@ -23,3 +28,55 @@ test('pickLargestRect selects by area and returns null for an empty list', () =>
   assert.deepEqual(pickLargestRect([{ x: 0, y: 0, width: 2, height: 2 }, VIEWPORT]), VIEWPORT);
   assert.equal(pickLargestRect([]), null);
 });
+
+// These rows are the TypeScript twin of the runner's Swift `SnapshotGeometry.isGeometricallyActionable`
+// (asserted over randomized rects by the snapshot differential and over authored rects by
+// CoordinateSpaceTests.swift). They pin it so the host AX bridge cannot drift from the XCTest runner.
+test('isGeometricallyActionable matches the Swift runner predicate', () => {
+  assert.equal(
+    isGeometricallyActionable(true, { x: 10, y: 10, width: 40, height: 40 }, VIEWPORT),
+    true,
+  );
+  // Enabled but centered off-screen, or zero/negative/absent, is never actionable.
+  assert.equal(
+    isGeometricallyActionable(true, { x: 320, y: 10, width: 40, height: 40 }, VIEWPORT),
+    false,
+  );
+  assert.equal(
+    isGeometricallyActionable(true, { x: 10, y: 600, width: 40, height: 40 }, VIEWPORT),
+    false,
+  );
+  assert.equal(
+    isGeometricallyActionable(true, { x: 10, y: 10, width: 0, height: 40 }, VIEWPORT),
+    false,
+  );
+  assert.equal(isGeometricallyActionable(true, undefined, VIEWPORT), false);
+  // A disabled node with a centred frame is not actionable.
+  assert.equal(
+    isGeometricallyActionable(false, { x: 10, y: 10, width: 40, height: 40 }, VIEWPORT),
+    false,
+  );
+  // CGRect.contains is half-open: the top/left edge counts, the right/bottom edge does not — the
+  // divergence the shared `containsPoint` (inclusive) would otherwise hide from a `hittable:` selector.
+  const topCentered: Rect = { x: 0, y: 0, width: 2, height: 2 };
+  assert.equal(
+    isGeometricallyActionable(true, topCentered, VIEWPORT),
+    true,
+    'center at the origin counts',
+  );
+  assert.equal(
+    containsPoint(VIEWPORT, 300, 250),
+    true,
+    'containsPoint stays inclusive on the right edge',
+  );
+  assert.equal(
+    isGeometricallyActionable(true, { x: 299, y: 249, width: 2, height: 2 }, VIEWPORT),
+    false,
+    'a center on the right edge is not hittable',
+  );
+  assert.equal(
+    isGeometricallyActionable(true, { x: 149, y: 499, width: 2, height: 2 }, VIEWPORT),
+    false,
+    'a center on the bottom edge is not hittable',
+  );
+});
diff --git a/packages/kernel/src/rect.ts b/packages/kernel/src/rect.ts
index 932f370d50..fe25acfe7d 100644
--- a/packages/kernel/src/rect.ts
+++ b/packages/kernel/src/rect.ts
@@ -27,6 +27,32 @@ export function containsPoint(rect: Rect, x: number, y: number): boolean {
   return x >= rect.x && x <= rect.x + rect.width && y >= rect.y && y <= rect.y + rect.height;
 }
 
+/**
+ * The shared `hittable` predicate every iOS snapshot producer publishes (#1933): an enabled node
+ * with a positive frame whose center falls inside the viewport. It is the TypeScript twin of the
+ * runner's Swift `SnapshotGeometry.isGeometricallyActionable`, including `CGRect.contains`'s
+ * half-open right/bottom edges — a center landing exactly on the viewport's right or bottom edge is
+ * not hittable on either producer. The host AX bridge derives the source bit from the node's own
+ * frame and the fold intersects it with the clipped frame, so a `hittable:` selector cannot tell the
+ * two producers apart. Kept here so both packages read one definition rather than each re-encoding
+ * the rule.
+ */
+export function isGeometricallyActionable(
+  enabled: boolean,
+  rect: Rect | undefined,
+  viewport: Rect,
+): boolean {
+  if (!enabled || !isPositiveFiniteRect(rect)) return false;
+  const centerX = rect.x + rect.width / 2;
+  const centerY = rect.y + rect.height / 2;
+  return (
+    centerX >= viewport.x &&
+    centerX < viewport.x + viewport.width &&
+    centerY >= viewport.y &&
+    centerY < viewport.y + viewport.height
+  );
+}
+
 export function pickLargestRect(rects: readonly Rect[]): Rect | null {
   let best: Rect | null = null;
   let bestArea = -1;
diff --git a/packages/platform-apple/src/snapshot-source/adapter.test.ts b/packages/platform-apple/src/snapshot-source/adapter.test.ts
index 5c4f9435fa..5b9a6fed68 100644
--- a/packages/platform-apple/src/snapshot-source/adapter.test.ts
+++ b/packages/platform-apple/src/snapshot-source/adapter.test.ts
@@ -66,9 +66,27 @@ test('the Simulator AX source returns raw acquisition facts and discloses unsupp
       targetId: 'target-1',
       generation: 'generation-1',
     });
+    // With the viewport reported the reader owns `hittable` and stamps it on every node, so hittability
+    // is not disclosed as unavailable; only the interactive-query facet it cannot honour is.
     assert.deepEqual(result.acquisition.residue, [
+      { kind: 'unavailable-fact', fact: 'interactive-query' },
+    ]);
+    assert.equal(result.acquisition.nodes[0]?.hittable, false, 'the stamped root is not hittable');
+
+    // The complement (#2199: the residue owner is the fact owner): strip the viewport and the reader
+    // publishes no `hittable` claim and discloses hittability as unavailable again.
+    fixture.omitViewport = true;
+    const viewportless = await source.acquire({
+      target: { ...sourceTarget, targetId: 'target-1' },
+      hint,
+    });
+    fixture.omitViewport = false;
+    assert.equal(viewportless.stage, 'acquired');
+    assert.equal(viewportless.acquisition.nodes[0]?.hittable, undefined);
+    assert.deepEqual(viewportless.acquisition.residue, [
       { kind: 'unavailable-fact', fact: 'hittability' },
       { kind: 'unavailable-fact', fact: 'interactive-query' },
+      { kind: 'missing-viewport', reason: 'not-provided' },
     ]);
 
     const regularDepthOne = await source.acquire({
@@ -443,6 +461,8 @@ type AdapterFixture = {
   remoteContent: boolean;
   /** Whether the fake guest's tree holds a window reporting the app box quarter-turned (#2612). */
   turnedWindow: boolean;
+  /** Whether the fake guest's root omits its frame, leaving the capture without a viewport. */
+  omitViewport: boolean;
   omitRecovery: boolean;
   diagnostics: Record<string, unknown>[];
 };
@@ -469,6 +489,7 @@ function createAdapterHost(buildDelayMs = 0): AdapterFixture {
     malformedTree: false,
     remoteContent: false,
     turnedWindow: false,
+    omitViewport: false,
     omitRecovery: false,
     diagnostics: [],
   };
@@ -542,6 +563,11 @@ class AdapterSocket extends EventEmitter implements SnapshotSourceSocket {
     this.fixture = fixture;
   }
 
+  /** The guest root's frame, or undefined when the fixture reports a viewportless tree. */
+  private rootFrame(): Record<string, number> | undefined {
+    return this.fixture.omitViewport ? undefined : { X: 0, Y: 0, Width: 390, Height: 844 };
+  }
+
   write(frame: Buffer): boolean {
     const bodyLength = frame.readUInt32BE(0);
     const request = JSON.parse(frame.subarray(4, bodyLength + 4).toString('utf8')) as {
@@ -610,7 +636,7 @@ class AdapterSocket extends EventEmitter implements SnapshotSourceSocket {
               ? null
               : {
                   XC_kAXXCAttributeElementType: 'Application',
-                  XC_kAXXCAttributeFrame: { X: 0, Y: 0, Width: 390, Height: 844 },
+                  XC_kAXXCAttributeFrame: this.rootFrame(),
                   XC_kAXXCAttributeChildren:
                     request.maxDepth === 1
                       ? [{ XC_kAXXCAttributeElementType: 'Button', XC_kAXXCAttributeChildren: [] }]
diff --git a/packages/platform-apple/src/snapshot-source/adapter.ts b/packages/platform-apple/src/snapshot-source/adapter.ts
index f6dfbebec7..f82c771124 100644
--- a/packages/platform-apple/src/snapshot-source/adapter.ts
+++ b/packages/platform-apple/src/snapshot-source/adapter.ts
@@ -261,8 +261,16 @@ function createAcquisitionResidue(
   truncated: boolean,
   viewport: IosViewportEvidence,
 ) {
+  // With a reported viewport the bridge reader has already stamped geometric `hittable` onto every
+  // node (it owns that fact and the residue), so it is not declared unavailable. Only when the
+  // viewport is missing does the reader withhold `hittable` and disclose it as an unavailable fact —
+  // the same "the residue owner is the fact owner" rule that keeps geometry from minting the claim.
+  const hittabilityResidue =
+    viewport.kind === 'reported'
+      ? []
+      : ([{ kind: 'unavailable-fact', fact: 'hittability' }] as const);
   return Object.freeze([
-    { kind: 'unavailable-fact', fact: 'hittability' } as const,
+    ...hittabilityResidue,
     ...(hint.interactiveOnly
       ? ([{ kind: 'unavailable-fact', fact: 'interactive-query' }] as const)
       : []),
diff --git a/packages/platform-apple/src/snapshot-source/tree.test.ts b/packages/platform-apple/src/snapshot-source/tree.test.ts
index 749e182ef5..23853eddc0 100644
--- a/packages/platform-apple/src/snapshot-source/tree.test.ts
+++ b/packages/platform-apple/src/snapshot-source/tree.test.ts
@@ -52,6 +52,7 @@ test('the bridge tree becomes one depth-first raw snapshot with viewport evidenc
       role: 'Application',
       rect: { x: 0, y: 0, width: 390, height: 844 },
       depth: 0,
+      hittable: false,
     },
     {
       index: 1,
@@ -61,6 +62,7 @@ test('the bridge tree becomes one depth-first raw snapshot with viewport evidenc
       subrole: 'UIWindow',
       rect: { x: 0, y: 0, width: 390, height: 844 },
       depth: 1,
+      hittable: true,
     },
     {
       index: 2,
@@ -69,6 +71,7 @@ test('the bridge tree becomes one depth-first raw snapshot with viewport evidenc
       label: 'Continue',
       rect: { x: 20, y: 700, width: 120, height: 48 },
       depth: 2,
+      hittable: true,
     },
   ]);
   assert.deepEqual(result.viewport, {
@@ -79,6 +82,59 @@ test('the bridge tree becomes one depth-first raw snapshot with viewport evidenc
   assert.equal(result.opaqueRemoteElements, 0);
 });
 
+test('the bridge reader stamps geometric hittable onto every raw node, matching the runner', () => {
+  const traitsWord = (bits: bigint) => bits.toString();
+  const button = (text: string, rect: Record<string, number>, traitBits = 1n) => ({
+    [automationType]: 9,
+    [label]: text,
+    [frame]: rect,
+    [traits]: traitsWord(traitBits),
+    [children]: [],
+  });
+  const decode = (kids: unknown[]) =>
+    decodeSnapshotBridgeTree(
+      {
+        [application]: 'Application',
+        [frame]: { X: 0, Y: 0, Width: 390, Height: 844 },
+        [children]: kids,
+      },
+      { truncated: false },
+      limits,
+    ).nodes;
+  const hittableOf = (kids: unknown[]) => decode(kids).map((node) => node.hittable);
+  const notEnabled = 1n << 8n;
+
+  // A root has no parent to hit through, so it is published not-hittable exactly as the runner does.
+  assert.deepEqual(hittableOf([]), [false], 'root is not hittable');
+  // On-screen enabled is hittable; the same frame disabled is not; a frame centred below the
+  // fold is not, even while enabled. These are the Swift `normalized()` cases pinned in
+  // CoordinateSpaceTests.swift, replayed against the bridge reader.
+  assert.deepEqual(
+    hittableOf([
+      button('Continue', { X: 20, Y: 700, Width: 120, Height: 48 }),
+      button('Place order', { X: 20, Y: 600, Width: 120, Height: 48 }, 1n | notEnabled),
+      button('Offscreen', { X: 20, Y: 2000, Width: 120, Height: 48 }),
+    ]),
+    [false, true, false, false],
+  );
+
+  // Without a reported viewport the reader has no rule input, so it publishes no hittable claim at
+  // all rather than guessing — the fold keeps hittability withheld until the runner serves the frame.
+  const noViewport = decodeSnapshotBridgeTree(
+    {
+      [application]: 'Application',
+      [children]: [button('Continue', { X: 20, Y: 700, Width: 120, Height: 48 })],
+    },
+    { truncated: false },
+    limits,
+  ).nodes;
+  assert.deepEqual(
+    noViewport.map((node) => node.hittable),
+    [undefined, undefined],
+    'a missing viewport publishes no hittable claim',
+  );
+});
+
 test('the bridge tree counts web-hosted remote leaves that reach the viewport', () => {
   const viewport = { X: 0, Y: 0, Width: 390, Height: 844 };
   const remoteLeaf = (rect?: Record<string, number>) => ({
diff --git a/packages/platform-apple/src/snapshot-source/tree.ts b/packages/platform-apple/src/snapshot-source/tree.ts
index 21265b3252..dd8322f78f 100644
--- a/packages/platform-apple/src/snapshot-source/tree.ts
+++ b/packages/platform-apple/src/snapshot-source/tree.ts
@@ -1,4 +1,8 @@
-import { isPositiveFiniteRect, isRectVisibleInViewport } from '@agent-device/kernel/rect';
+import {
+  isGeometricallyActionable,
+  isPositiveFiniteRect,
+  isRectVisibleInViewport,
+} from '@agent-device/kernel/rect';
 import type { RawSnapshotNode, Rect } from '@agent-device/kernel/snapshot';
 import type { IosViewportEvidence } from '@agent-device/contracts/ios-snapshot';
 import { snapshotSourceError } from './errors.ts';
@@ -173,6 +177,14 @@ export function decodeSnapshotBridgeTree(
   }
   const windowRoots = nodes.filter(isWindowRoot);
   const viewport = viewportFromRoot(windowRoots[0]);
+  // The runner publishes `hittable` for every node as geometric actionability; the guest hands over no
+  // hit-test result, so derive the same fact here from enabled + the node's own frame + the reported
+  // viewport. Publishing it on the raw nodes (rather than in the fold) is what lets `snapshot --raw`
+  // match the runner too, and it is only claimed once every input the rule needs is established — the
+  // reported viewport, with unresolved coordinate-space windows already refused above.
+  if (viewport.kind === 'reported') {
+    publishDerivedHittability(nodes, viewport.rect);
+  }
   return {
     nodes,
     maxTraversalDepth,
@@ -309,6 +321,21 @@ function isWindowRoot(node: RawSnapshotNode): boolean {
   return node.type === 'Application' || node.type === 'Window';
 }
 
+/**
+ * Stamp geometric actionability onto every decoded node, mirroring the XCTest runner's Swift rule
+ * (`parentIndex != nil && isGeometricallyActionable(enabled, frame, viewport)`). A root, a disabled
+ * node, or one whose frame center falls outside the viewport is published `hittable: false`; the
+ * fold's `available` branch then intersects this with the clipped-frame test exactly as it does for
+ * the runner, so the two producers cannot be told apart.
+ */
+function publishDerivedHittability(nodes: RawSnapshotNode[], viewport: Rect): void {
+  for (const node of nodes) {
+    node.hittable =
+      node.parentIndex !== undefined &&
+      isGeometricallyActionable(node.enabled !== false, node.rect, viewport);
+  }
+}
+
 /**
  * Surface hosts reporting their subtree in a space this capture cannot name.
  *

From 485221fa05f3645c4815d72e1e966eb7c8af170e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Wed, 23 Sep 2026 14:48:16 +0200
Subject: [PATCH 034/132] docs(command-registry): state what the descriptor
 root actually guarantees (#2779)

`commandDescriptors` claimed to be "proven byte-equal to the live hand tables by
`__tests__/parity.test.ts`". Neither operand survives the ADR 0008 migration. The
test is now `src/__tests__/command-descriptor-parity.test.ts` (moved by 2ec4e91b11
#2348); the tables it compared were deleted by the PRs that inverted them
(47abc8c416 #907 daemon routes, 96bc7b190c #908 capability matrix, retired by
ea1d6b8c55 #2089, 607883d66c #909 batch allowlist, 8ef4e73408 #1137 MCP
exposure); and TIMEOUT_POLICY_BY_COMMAND, DEVICE_CLAIM_POLICY_BY_COMMAND and
COMMAND_DESCRIPTOR_BY_NAME are folds over this array, so byte-equality has no
second operand.

Record the invariant that does hold and name the check that carries each part, so
a future split of this file preserves them. Established by mutation, not by
reading: duplicating a descriptor fails owner-files.test.ts,
command-descriptor-parity.test.ts and device-claim-policy.test.ts, while renaming
one lands on the literal pins (targetIdentityVerification, the timeout and
device-claim deviating sets). No new completeness test was owed here, and the
compile-time totality guard already covers required traits.

Same repair for the `frameworkTier` and `targetIdentityVerification` "the parity
test" pointers, the two `@internal Introspection helper used by parity tests`
docblocks (whose real consumers are command-descriptor-parity.test.ts and
command-surface-metadata.test.ts), the "additive single source" banner that still
listed the retired capability facet, and the CommandDescriptor intro, which
described the deleted tables as "today" and cited `app-switcher` as unrouted
after ADR 0014 gave it a daemon facet.
---
 packages/command-registry/src/registry.ts | 71 ++++++++++++++++++-----
 packages/command-registry/src/types.ts    | 31 +++++-----
 2 files changed, 75 insertions(+), 27 deletions(-)

diff --git a/packages/command-registry/src/registry.ts b/packages/command-registry/src/registry.ts
index db08824ec7..9807ca1294 100644
--- a/packages/command-registry/src/registry.ts
+++ b/packages/command-registry/src/registry.ts
@@ -438,10 +438,10 @@ function postActionObservation(command: string): PostActionObservationSupport {
 }
 
 // ---------------------------------------------------------------------------
-// The additive single source. Each entry carries the command identity facets
-// plus whichever daemon, capability, batch, MCP, timeout, observation, and
+// The command declaration root (ADR 0008). Each entry carries the command identity
+// facets plus whichever daemon, batch, MCP, timeout, observation, and
 // platform-dispatch traits that command owns. Public catalog identity and the
-// non-public dispatch aliases now live here too; leaf views derive from this
+// non-public dispatch aliases live here too; every view derives from this
 // array rather than recreating command-name sets.
 // ---------------------------------------------------------------------------
 
@@ -1781,12 +1781,40 @@ const CLI_COMMAND_NAMES = new Set<string>(
 );
 
 /**
- * The additive single source of truth (ADR-0008, Phase 1 step 1). Proven
- * byte-equal to the live hand tables by `__tests__/parity.test.ts`.
+ * {@link RAW_COMMAND_DESCRIPTORS} normalized: `mcpExposed` and `platformExecution`
+ * resolved, `ownerFiles` kept out of the runtime shape. The raw array is the root every
+ * projection folds over, directly or through this normalized copy — `CLI_COMMAND_NAMES`
+ * and the MCP exposure list here, `COMMAND_OWNER_FILES` in `owner-files.ts`, the catalog
+ * records, the daemon registry and batch allowlist in their own modules, and the
+ * {@link COMMAND_DESCRIPTOR_BY_NAME}, {@link TIMEOUT_POLICY_BY_COMMAND},
+ * {@link DEVICE_CLAIM_POLICY_BY_COMMAND} and {@link RESPONSE_DATA_TRANSFORM_BY_COMMAND}
+ * maps below. Those four are keyed by `name`, so a duplicated entry collapses into one
+ * rather than conflicting.
  *
- * The `as const` on {@link RAW_COMMAND_DESCRIPTORS} flows through this `.map`,
- * so each entry keeps its literal `name`. That is what makes the {@link Command}
- * union below a precise set of command-name literals rather than `string`.
+ * None of those has an independent table left to be byte-equal against: each consumer
+ * list became a projection of this array and its hand-authored source went away with it —
+ * `47abc8c416` (#907) daemon routes, `96bc7b190c` (#908) capability matrix (retired
+ * outright by `ea1d6b8c55` #2089), `607883d66c` (#909) batch allowlist, `8ef4e73408`
+ * (#1137) MCP exposure. The test that proved those equivalences is now an invariants-only
+ * guard at `src/__tests__/command-descriptor-parity.test.ts` (`2ec4e91b11` #2348).
+ *
+ * Two kinds of check replace that gate. Required traits are typed: `as const satisfies
+ * readonly RawCommandDescriptor[]` on the raw array, `satisfies readonly
+ * CommandDescriptor[]` here, and {@link CommandOwnerFileClaimsAreComplete} for owner
+ * claims. Classifications are pinned as literal command-name lists, so reclassifying or
+ * renaming a command they name means editing that list in the same diff: the device-claim
+ * deviating set in
+ * `packages/command-registry/src/__tests__/device-claim-policy.test.ts`; the timeout
+ * envelopes and budgets in `src/__tests__/command-descriptor-timeout-policy.test.ts` (a
+ * declared trait since `b25ef7b024` #1084); and the `targetIdentityVerification` and
+ * `'core'` tier sets, plus the tier-iff-public rule, in
+ * `src/__tests__/command-descriptor-parity.test.ts`. A duplicated entry is caught by the
+ * list comparisons in `packages/command-registry/src/__tests__/owner-files.test.ts` and
+ * that parity test.
+ *
+ * The `as const` on {@link RAW_COMMAND_DESCRIPTORS} flows through this `.map`, so each
+ * entry keeps its literal `name`. That is what makes the {@link Command} union below a
+ * precise set of command-name literals rather than `string`.
  */
 export const commandDescriptors = RAW_COMMAND_DESCRIPTORS.map((descriptor) => {
   const platformExecution = readDeclaredPlatformExecution(descriptor);
@@ -1811,7 +1839,14 @@ export const commandDescriptors = RAW_COMMAND_DESCRIPTORS.map((descriptor) => {
 export type Command = (typeof commandDescriptors)[number]['name'];
 
 /**
- * @internal Introspection helper used by parity tests.
+ * @internal Command names for one catalog group, sorted.
+ *
+ * Consumed only by `src/__tests__/command-descriptor-parity.test.ts`, which compares
+ * these names against the `PUBLIC_COMMANDS` / `INTERNAL_COMMANDS` records `catalog.ts`
+ * builds from {@link listDescriptorCatalogEntries}: a duplicated descriptor or a
+ * colliding `catalog.key` drops a name from one side of that comparison. Production code
+ * reads those records; this flat list is the second side the test checks them against,
+ * which is why the helper stays exported.
  */
 export function listDescriptorCatalogCommandNames<Group extends CommandCatalogGroup>(
   group: Group,
@@ -1961,10 +1996,13 @@ export function resolveCommandRecordsSessionAction(command: string | undefined):
 
 /**
  * The declared {@link CommandFrameworkTier} for a public command, or
- * `undefined` for a command that never declares one (every non-public
- * command, by construction — see the parity test). Framework adapters
- * (`agent-device/ai-sdk`, `@agent-device/eve`) read this to build their
- * default tool set instead of hand-listing tool names.
+ * `undefined` for a command that never declares one. A tier is declared iff
+ * `catalog.group === 'public'`; that rule is a runtime pin, not a type rule —
+ * `src/__tests__/command-descriptor-parity.test.ts` asserts it and the exact
+ * `'core'` tool set, so a new public command cannot join a framework adapter's
+ * default set silently. Framework adapters (`agent-device/ai-sdk`,
+ * `@agent-device/eve`) read this to build their default tool set instead of
+ * hand-listing tool names.
  */
 export function resolveCommandFrameworkTier(
   command: string | undefined,
@@ -1994,7 +2032,12 @@ export function resolveCommandRecordingEffect(req: DispatchedCommand): Recording
 }
 
 /**
- * @internal Introspection helper used by parity tests.
+ * @internal The commands that declare a {@link CommandResponseDataTransform}, with it.
+ *
+ * Consumed only by `src/commands/__tests__/command-surface-metadata.test.ts`, which
+ * checks every transform field against that command's declared input schema. The
+ * production projection of the same map is
+ * {@link listCommandResponseDataTransformFieldNames}.
  */
 export function listCommandResponseDataTransforms(): Array<{
   command: string;
diff --git a/packages/command-registry/src/types.ts b/packages/command-registry/src/types.ts
index 8e348986cb..5b926a7d26 100644
--- a/packages/command-registry/src/types.ts
+++ b/packages/command-registry/src/types.ts
@@ -156,26 +156,31 @@ export type CommandRecordingEffect =
  * dispatch (touch/fill/get/is expect their target present). `post-resolution`
  * — the command's own resolution verifies (wait's polling loop, whose
  * landmark may legitimately be absent at step start); only decision 3 path 1
- * runs up front. Declared on every evidence-carrying command and pinned by
- * the parity test, so a new one must choose a phase explicitly.
+ * runs up front. Declared on every evidence-carrying command and pinned as a literal
+ * set by `src/__tests__/command-descriptor-parity.test.ts`, so a new one must choose a
+ * phase explicitly.
  */
 export type TargetIdentityVerification = 'pre-dispatch' | 'post-resolution';
 
 /**
- * The single additive command-descriptor shape (ADR-0008, Phase 1 step 1).
+ * The single command-descriptor shape (ADR 0008).
  *
- * Per command this carries, side-by-side, the facts that today live in three
- * separate hand-authored tables:
- *  - `daemon`     — the daemon route + request-policy traits
- *                   (from DAEMON_COMMAND_DESCRIPTORS). Absent for commands that
- *                   have no daemon route (e.g. `app-switcher`, `install-from-source`).
- *  - `batchable`  — whether the command is exposed through `batch`
- *                   (from STRUCTURED_BATCH_COMMAND_NAMES).
- *  - `mcpExposed` — whether the command is surfaced over MCP.
- *  - `timeoutPolicy` — the request-envelope budget source + on-timeout daemon
- *                   policy. REQUIRED on every entry — most commands share the
+ * Per command this carries, side-by-side, the facts its consumer projections are built
+ * from. Four of them replaced a hand-authored list outright:
+ *  - `daemon`     — the daemon route + request-policy traits, projected into
+ *                   DAEMON_COMMAND_DESCRIPTORS (#907). Absent for commands with no
+ *                   daemon route: the local-cli commands, and `install-from-source`,
+ *                   which reaches the daemon through the `install_source` internal command.
+ *  - `batchable`  — whether the command is exposed through `batch`, projected into
+ *                   STRUCTURED_BATCH_COMMAND_NAMES (#909).
+ *  - `mcpExposed` — whether the command is surfaced over MCP, in place of the
+ *                   hand-maintained exclusion list (`8ef4e73408` #1137).
+ *  - `timeoutPolicy` — the request-envelope budget source + on-timeout daemon policy,
+ *                   in place of the daemon client's timeout lists (`b25ef7b024` #1084).
+ *                   REQUIRED on every entry — most commands share the
  *                   explicit `DEFAULT_TIMEOUT_POLICY` constant, but a new
  *                   command must say so rather than inherit silently.
+ * The remaining facets are plain declarations their consumers derive from:
  *  - `postActionObservation` — optional interaction observation trait for
  *                   commands that support `--settle`/`--verify`; consumed by
  *                   command surfaces and timeout policy instead of repeated

From 12d3f5af9974186f133a0b6900ca74f9961b7a87 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Wed, 23 Sep 2026 14:48:16 +0200
Subject: [PATCH 035/132] refactor(move): guard the descriptor root's literal
 unions beside the union (#2805)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`Command` and `DescriptorCliCommandName` are literal unions only while
`RAW_COMMAND_DESCRIPTORS` keeps its `as const`, and every downstream use of
them is a place that stops complaining rather than failing when that is lost:
`COMMAND_DEFAULTS` and the `Record<DescriptorCliCommandName, …>` in
`src/cli/injected-daemon-dispatch.ts` stop rejecting an unknown key, and the
`command: Command` parameters in `src/cli/command-explain.ts` and
`owner-files.ts` stop excluding a name no descriptor declares.
`CommandUnionStaysLiteral` and `CliCommandUnionStaysLiteral` assert the
literalness where the unions are declared, joining the
`CommandOwnerFileClaimsAreComplete` guard `.fallowrc.json` already keys for
this shape of exported-only-so-`noUnusedLocals`-keeps-it-alive assertion.

Two comment corrections in the same region. `ownerFilesEnabled` sat between the
root banner and the array it describes and carried no explanation of what it
switches, so it moved above the banner and documents the `__OWNER_FILES__`
fold that `pnpm check:bundle-owner-files` proves over `dist/`. The block header
claiming "capability/batch-only commands (no daemon route)" preceded
`app-switcher`, which declares `daemon: { route: 'generic' }` under ADR 0014,
and `action-button`, which gets the same facet from
`GENERIC_MUTATING_COMMAND_TRAITS`; it now names what those three commands
actually share.

No module is added or removed, so every measured eager closure is unchanged.
---
 .fallowrc.json                            |  2 ++
 packages/command-registry/src/registry.ts | 29 ++++++++++++++++++++---
 2 files changed, 28 insertions(+), 3 deletions(-)

diff --git a/.fallowrc.json b/.fallowrc.json
index ebe7cf1436..691ae633e6 100644
--- a/.fallowrc.json
+++ b/.fallowrc.json
@@ -258,6 +258,8 @@
       "file": "{packages/command-registry/src/registry.ts,src/core/interactors/register-builtins.ts,src/core/platform-descriptor/registry.ts,src/daemon/request-platform-providers.ts}",
       "exports": [
         "CommandOwnerFileClaimsAreComplete",
+        "CommandUnionStaysLiteral",
+        "CliCommandUnionStaysLiteral",
         "BuiltinPluginsCoverAllPlatforms",
         "PlatformDescriptorsAreTotal",
         "GatedKeysAreResolverKeys"
diff --git a/packages/command-registry/src/registry.ts b/packages/command-registry/src/registry.ts
index 9807ca1294..43ebe1a20c 100644
--- a/packages/command-registry/src/registry.ts
+++ b/packages/command-registry/src/registry.ts
@@ -437,6 +437,14 @@ function postActionObservation(command: string): PostActionObservationSupport {
   return support;
 }
 
+/**
+ * Whether this build carries the descriptors' `ownerFiles` claims. Production defines
+ * `__OWNER_FILES__` as `false`, so every `ownerFilesEnabled ? { ownerFiles: [...] } : {}` spread
+ * in the root below folds to nothing and the navigation paths never reach a bundle — which
+ * `pnpm check:bundle-owner-files` proves over `dist/`.
+ */
+const ownerFilesEnabled = typeof __OWNER_FILES__ === 'undefined' || __OWNER_FILES__;
+
 // ---------------------------------------------------------------------------
 // The command declaration root (ADR 0008). Each entry carries the command identity
 // facets plus whichever daemon, batch, MCP, timeout, observation, and
@@ -445,8 +453,6 @@ function postActionObservation(command: string): PostActionObservationSupport {
 // array rather than recreating command-name sets.
 // ---------------------------------------------------------------------------
 
-const ownerFilesEnabled = typeof __OWNER_FILES__ === 'undefined' || __OWNER_FILES__;
-
 const DEPLOY_APP_COMMAND_DESCRIPTOR = {
   deviceClaimPolicy: 'transient-exclusive',
   ...(ownerFilesEnabled ? { ownerFiles: ['src/commands/management/install.ts'] as const } : {}),
@@ -1534,7 +1540,7 @@ export const RAW_COMMAND_DESCRIPTORS = [
     batchable: false,
     platformExecution: { kind: 'device-runtime', uses: [viewportRuntimeUse] },
   },
-  // -- capability/batch-only commands (no daemon route) --
+  // -- public extended-tier commands: the generic route, or no daemon facet declared --
   {
     name: 'app-switcher',
     deviceClaimPolicy: 'require-owner',
@@ -1838,6 +1844,23 @@ export const commandDescriptors = RAW_COMMAND_DESCRIPTORS.map((descriptor) => {
 /** The literal union of every registered command name. */
 export type Command = (typeof commandDescriptors)[number]['name'];
 
+type Equal<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false;
+
+/**
+ * Compile-time literalness of {@link Command}. The `as const` on {@link RAW_COMMAND_DESCRIPTORS}
+ * keeps each descriptor's literal `name` through the composition and the `.map` above; an array
+ * that lost it would widen this union to `string`, and nothing downstream would say so:
+ * `COMMAND_DEFAULTS` below and `Record<DescriptorCliCommandName, …>` in
+ * `src/cli/injected-daemon-dispatch.ts` stop rejecting an unknown key, and the `command: Command`
+ * parameters in `src/cli/command-explain.ts` and `owner-files.ts` would stop excluding a name no
+ * descriptor declares. That silence is why this is a type guard and not a value comparison.
+ */
+export type CommandUnionStaysLiteral = AssertTrue<Equal<Equal<Command, string>, false>>;
+/** The CLI view is narrowed from the same literals, so it cannot hide a widened root union. */
+export type CliCommandUnionStaysLiteral = AssertTrue<
+  Equal<Equal<DescriptorCliCommandName, string>, false>
+>;
+
 /**
  * @internal Command names for one catalog group, sorted.
  *

From efd210815a4331a2919fc9951e55cce13652946c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Wed, 23 Sep 2026 14:48:57 +0200
Subject: [PATCH 036/132] docs(adr): retire the parity-gate claim, state
 press-shape refusal, record the descriptor-root block (#2808)

* docs(adr): retire the parity-gate claim, state press-shape refusal, record the descriptor-root block

ADR 0008 still promises a class of check that no longer exists. The parity test its
migration rule required lost its second operand as each hand table was inverted out
(#907, #908, #909, #1084, #1137); the retirement is recorded in Status and the
present-tense claims are corrected, while the migration rule itself is left intact
because it was followed.

ADR 0019 gains the rule that a shape of an operation is not an operation and gets no
fact cell, which is what a per-shape refusal on the owning leaf mechanic rests on.

ADR 0027 records, without deciding, the conflict that makes the descriptor root
unshippably splitable: ADR 0008's synchronous hub and the ADR-0019 eager-closure
module-count budget have no shared approval path. Measured: any decomposition of the
root, even the smallest, grows eleven entry surfaces.

* docs(adr): propose one runtime source for the capability-family cell vocabulary

Adding an operation family edits the cell key twice in one file: once as a property of
UnavailablePlatformRuntimeFacts and again as a value in UNAVAILABLE_CELLS, which cannot
be derived from the type. satisfies makes drift a compile error, so this is a
maintenance tax rather than a soundness hole -- but it is why a file with fan-in 6
churned 9 times in 200 commits, and why one capability still fans out across eight
packages.

Proposes the inversion the repo already proved on the binding axis
(INTERACTOR_OPERATIONS) for the facts axis, and states what it deliberately does not
grant: no default-deny baseline, because ADR 0019 requires exhaustive per-shape facts
and forbids cross-family defaults in a platform package. Gated on a measurement and on
eager-closure neutrality, with withdrawal as an acceptable outcome.

* docs(adr): point ADR 0027 at the pushed, recoverable descriptor split
---
 docs/adr/0008-command-descriptor-registry.md  |  13 ++-
 .../0019-request-bound-platform-runtime.md    |  15 +++
 ...descriptor-root-vs-eager-closure-budget.md | 103 ++++++++++++++++++
 .../0028-capability-family-cell-vocabulary.md |  79 ++++++++++++++
 docs/adr/README.md                            |   2 +
 5 files changed, 210 insertions(+), 2 deletions(-)
 create mode 100644 docs/adr/0027-descriptor-root-vs-eager-closure-budget.md
 create mode 100644 docs/adr/0028-capability-family-cell-vocabulary.md

diff --git a/docs/adr/0008-command-descriptor-registry.md b/docs/adr/0008-command-descriptor-registry.md
index 543357e2ae..241cca57f9 100644
--- a/docs/adr/0008-command-descriptor-registry.md
+++ b/docs/adr/0008-command-descriptor-registry.md
@@ -9,6 +9,15 @@ Accepted
 > preferred runtime use joined with leaf/device/provider-specific runtime facts; inventory commands
 > declare inventory use instead of fabricating a device binding. The descriptor's other derived
 > projections remain accepted.
+>
+> **Parity gate retired (2026-09).** The migration rule below — assert each derived table
+> byte-for-byte against its hand-authored table before deleting the hand table — was followed, and
+> completing it removed the gate's second operand. Each hand table went away as its projection was
+> inverted out: #907 daemon routes, #908 capability matrix, #909 batch allowlist, #1084
+> daemon-client timeout lists, #1137 MCP exposure list. No parity test exists. Do not add one or
+> look for one; the totality invariants are now carried by compile-time guards
+> (`CommandOwnerFileClaimsAreComplete`) and by literal pin-set tests that compare a name set rather
+> than two tables.
 
 ## Context
 
@@ -32,7 +41,7 @@ model must preserve. This ADR is that model.
 ## Decision
 
 Introduce one `CommandDescriptor` per command that **composes facets owned by their domains** and from which
-every consumer table is **derived** by pure, parity-tested projection:
+every consumer table is **derived** by pure projection:
 
 - The descriptor composes catalog identity, command-family surface projection hooks
   (`src/commands/**` remains the owner of CLI schema/reader and executable surface metadata), a
@@ -95,4 +104,4 @@ modules must move those contracts before their client methods can stop returning
 `CommandRequestResult`.
 
 This ADR owns the decision and its constraints; the roadmap that prototyped it has been retired, with
-the delivered end-state enforced by the descriptor projections and parity gates below.
+the delivered end-state enforced by the descriptor projections below.
diff --git a/docs/adr/0019-request-bound-platform-runtime.md b/docs/adr/0019-request-bound-platform-runtime.md
index 561864f135..7ff3ae3f7a 100644
--- a/docs/adr/0019-request-bound-platform-runtime.md
+++ b/docs/adr/0019-request-bound-platform-runtime.md
@@ -12,6 +12,12 @@ a narrow neutral typed service, not diagnostics alone. Host diagnostics, daemon-
 cleanup, and managed host tooling share the execution category because none binds a request-scoped
 device runtime; their domain services remain separate rather than forming a generic host grab bag.
 
+Amendment proposed 2026-09-23 alongside the web press-shape refusal: it states in section 3 that a
+modifier on an admitted operation is not a second operation and therefore has no fact cell, which is
+what a per-shape refusal on the owning leaf mechanic rests on. Without that sentence the next
+contributor reasonably reaches for a per-shape fact key, which the operation-facts mapped type cannot
+express.
+
 Amendment proposed 2026-09-14 by [ADR 0024](./0024-screen-recording-provable-signal.md) for the
 `screen-recording` kind only; see the note at the head of section 5. It takes effect when ADR 0024
 is accepted.
@@ -268,6 +274,15 @@ stubs that throw `unsupported` after binding. Runtime-use keys identify individu
 operations, not whole facet namespaces, so selecting one operation does not expose undeclared sibling
 operations from the same facet.
 
+**A shape of an operation is not an operation and gets no fact cell.** Runtime facts speak per
+semantic operation; a modifier applied to an admitted operation — a press that is double, held, or
+repeated — is not a second operation and must not be given a fact key, because the facts map is a
+mapped type over operation names and a phantom operation satisfies neither the required nor the
+preferred runtime-use shape. Such a shape is refused by the owning leaf mechanic being absent, with a
+typed reason and a hint, at the point the shape is requested. Absence of a whole admitted
+operation's member remains an ownership bug and fails closed with its own typed reason; it is never
+the mechanism that expresses an unsupported shape.
+
 `RequestExecutionScope.bindDevice(device, use)` is the trust choke point. It:
 
 1. resolves the exact local or provider runtime owner;
diff --git a/docs/adr/0027-descriptor-root-vs-eager-closure-budget.md b/docs/adr/0027-descriptor-root-vs-eager-closure-budget.md
new file mode 100644
index 0000000000..53d17f99a3
--- /dev/null
+++ b/docs/adr/0027-descriptor-root-vs-eager-closure-budget.md
@@ -0,0 +1,103 @@
+# ADR 0027: Descriptor Root Size vs Eager-Closure Budget (Proposed)
+
+## Status
+
+Proposed (2026-09-23). This ADR **decides nothing**. It records a conflict between two invariants
+that are both enforced and both correct, and states the one question a repo owner must answer before
+either invariant can be relied on for module placement. Until then, follow both: do not split the
+descriptor root, and do not add an approval path to the budget gate to let the split through.
+
+## The conflict
+
+[ADR 0008](0008-command-descriptor-registry.md) makes `packages/command-registry/src/registry.ts`
+the single **synchronous** descriptor root. `RAW_COMMAND_DESCRIPTORS` and every derived view — the
+`Command` literal union, the catalog name sets, the `name`-keyed policy maps, batch policy — are
+module-scope values, and consumers reach them through **value** imports.
+
+`AGENTS.md` states that files past 1,000 lines are architecture debt and must be split before adding
+behavior. The descriptor root is past that line.
+
+`scripts/__tests__/eager-closure-budgets.ts` (the ADR 0019 loading-shape probe) measures each
+published entry surface's eager **module count** against the committed merge-base and forbids any
+increase. It has no approval path for growth by design; `APPROVED_OVER_CEILING` applies only to
+first-introduced entries against `NEW_ENTRY_CEILINGS`.
+
+Splitting a hub module necessarily adds static value edges beneath it, so every entry surface that
+reaches it grows by the number of new modules. The two rules have no shared approval path: one says
+the file must be divided, the other says the division must not be visible to any importer.
+
+## Rules at a glance, while unresolved
+
+- Do not split `registry.ts`. The budget gate is the binding constraint and has no waiver.
+- Do not add an approved-growth row, a baseline entry, or a suppression to pass it. That is the
+  allowlist `AGENTS.md` forbids.
+- Do not make registry construction asynchronous to dodge the walker. ADR 0008's synchronous root is
+  load-bearing for compile-time totality.
+- Closure-neutral edits inside the descriptor root are still welcome: relocating guards beside the
+  union they constrain, correcting stale claims, and moving non-eager content out are fine so long as
+  every measured entry surface is unchanged.
+
+## Measured
+
+Splitting `RAW_COMMAND_DESCRIPTORS` into eleven family modules plus a shared trait module, byte-faithful
+(80 descriptors, 79 byte-identical including comments), grew **every** entry surface reaching the root
+by exactly **+11** modules. Route for all rows:
+`… → catalog.ts → registry.ts → descriptor-traits.ts + descriptors/*.ts`.
+
+| entry surface | merge-base | split |
+| --- | --- | --- |
+| `src/cli.ts` | 295 | 306 |
+| `packages/session-journal/src/session-event-log.ts` | 92 | 103 |
+| `packages/session-journal/src/session-event-action.ts` | 87 | 98 |
+| `packages/session-journal/src/session-event-action-presentation.ts` | 83 | 94 |
+| `packages/command-registry/src/batch.ts` | 80 | 91 |
+| `packages/session-journal/src/session-event-request.ts` | 75 | 86 |
+| `packages/command-registry/src/batch-policy.ts` | 74 | 85 |
+| `packages/command-registry/src/planned-operations.ts` | 74 | 85 |
+| `packages/command-registry/src/catalog.ts` | 73 | 84 |
+| `packages/command-registry/src/owner-files.ts` | 73 | 84 |
+| `packages/command-registry/src/registry.ts` | 72 | 83 |
+
+Two facts make this unavoidable rather than incidental:
+
+- Extracting only the shared trait module — the smallest possible decomposition — costs **+1** on the
+  same eleven surfaces. There is no decomposition of this hub that passes.
+- The walker erases type-only edges, so narrowing consumer imports cannot absorb the cost. These
+  consumers need the derived values, not the types.
+
+The cost is genuinely a *count*, not weight: the same bytes are evaluated either way. That is what
+makes the conflict worth deciding rather than absorbing silently, because the gate's proxy and the
+debt rule's proxy disagree at exactly this shape.
+
+## Decision required
+
+May a byte-neutral re-homing of a hub module's contents into new modules raise the eager module count
+of the entry surfaces that reach it — or must a hub module's contents stay inside the file its
+consumers already evaluate?
+
+Answering "the count may rise" needs a bounded, auditable growth allowance on an invariant that
+currently refuses one. Answering "contents stay put" needs `AGENTS.md`'s 1,000-line rule to name the
+exception for a hub whose consumers evaluate it as one unit, so the size is treated as accepted and
+measured rather than as unaddressed debt. Either answer is fine; leaving it unstated means the next
+agent at this file discovers the conflict from a red gate and picks one silently.
+
+## Alternatives considered and refuted
+
+- **Approved-growth row mirroring `APPROVED_OVER_CEILING` (issue, reason, owner):** refuted pending the
+  decision above. It would be auditable, but it is an allowlist on the one invariant deliberately
+  given no approval path, and `AGENTS.md` forbids adding one to obtain a pass.
+- **Leave the array in place:** the status quo, not a resolution — it leaves the size debt unowned and
+  the conflict undocumented.
+- **Function-scoped `await import` per family:** passes the gate by making registry construction
+  asynchronous, which removes the compile-time totality and literal-union guarantees ADR 0008 depends
+  on. Trading a measured proxy cost for a lost correctness guarantee is the wrong direction.
+- **Reduce descriptor verbosity instead of splitting the file:** legitimate and unexplored, but it
+  changes the declaration vocabulary for all ~80 commands, which is a larger change than the split
+  and needs its own decision.
+
+## Recovery
+
+A complete, byte-faithful split of the descriptor array exists on
+`refactor/collocation-registry-family-split` (`40bf719a8b`, split commit `ad3aaa520e`) and is pushed.
+It is kept rather than deleted so that answering the question above does not require redoing the
+mechanical work; 80 descriptors, 79 byte-identical including comments.
diff --git a/docs/adr/0028-capability-family-cell-vocabulary.md b/docs/adr/0028-capability-family-cell-vocabulary.md
new file mode 100644
index 0000000000..b65dd49862
--- /dev/null
+++ b/docs/adr/0028-capability-family-cell-vocabulary.md
@@ -0,0 +1,79 @@
+# ADR 0028: Capability-Family Cell Vocabulary — One Runtime Source (Proposed)
+
+## Status
+
+Proposed (2026-09-23). Proposes inverting one vocabulary so adding a capability family is a single
+declaration instead of a coordinated edit across a type, a table, and every runtime owner. It decides
+**no** defaulting behavior, and it does not weaken any ADR 0019 rule. Ship only after the measurement
+below shows the fan-out actually shrinks.
+
+## Why now, and what the numbers said
+
+Over the last 200 commits, 8 commits touched eight or more packages, across only five distinct
+package combinations — and one of those combinations recurred four times. Each was one capability
+(`action-button`, `fold`, preferred text size) propagating through every runtime owner. Within
+`@agent-device/contracts`, `platform-runtime-unavailable.ts` churned 9 times with fan-in of only 6:
+the most-changed file in the repo that almost nothing imports. That signature is a declaration site
+paying a coordination tax, not a behavioral hotspot.
+
+## What is actually duplicated
+
+Not the behavior — the **cell vocabulary**. Adding one operation family currently means editing, in
+`@agent-device/contracts`:
+
+1. the family's own `xxx-runtime.ts` fact builder,
+2. `UnavailablePlatformRuntimeFacts` (`platform-runtime-unavailable.ts`) — a type property,
+3. `UNAVAILABLE_CELLS` in the same file — a `{ cell: true } satisfies Record<UnavailableCellKey, true>`
+   value listing the same keys again, because a type's key set cannot be enumerated at runtime,
+4. `PlatformRuntimeOperations`,
+5. `runtime-operation-names.ts`,
+6. one row in `INTERACTOR_OPERATIONS`.
+
+(2) and (3) are the same list written twice. `satisfies` makes drift a compile error, so this is **not**
+a soundness hole — it is a maintenance tax paid on every family. A runtime row table would make the
+value authoritative and the type derived from it.
+
+The repo has already done exactly this inversion once, and should copy it rather than invent:
+`interactor-operation-catalog.ts` replaced "three parallel declarations — a name tuple, a local binder
+map, and a provider binder map" with `INTERACTOR_OPERATIONS`, one row per operation. The binding axis
+is single-sourced. The **facts** axis is not.
+
+## Rules at a glance
+
+- One runtime row per capability family is the authority for its cell key; the cell-key type is
+  derived from that table, not maintained beside it.
+- A runtime owner still reports **exhaustive** facts for its exact device shape
+  ([ADR 0019](0019-request-bound-platform-runtime.md), section 3). Deriving the *list of cells* is
+  allowed; deriving an owner's *answer* for a cell is not.
+- No cross-family default denial set. An owner that does not state a cell is a bug, not an
+  unsupported result.
+- Lifecycle keeps its own authority. `platform-runtime-unavailable.ts` exists "for provider ownership
+  gaps" and never assigns lifecycle semantics; that stays out of the table.
+
+## Explicitly not proposed
+
+- **A default-deny baseline owners inherit.** ADR 0019 requires exhaustive per-shape facts and forbids
+  cross-family defaults in a platform package, so the current ~35-cell enumeration in an owner such as
+  `packages/platform-linux/src/runtime.ts` is intentional. Removing it needs an ADR that supersedes
+  those two rules on the merits, not a table that quietly reimplements them.
+- **Moving the vocabulary out of `@agent-device/contracts`.** It already lives at the lowest ranked
+  zone; the `depgraph` README's 42→48 lesson applies — moving a vocabulary file down made the gate
+  worse because the vocabulary itself imports upward.
+- **A new generator.** The catalog precedent is a hand-written row array with derived views.
+
+## Measurement required before acceptance
+
+This ADR exists to stop an eight-package fan-out. Before landing any inversion, measure on a real
+family rather than arguing from the shape:
+
+1. Pick the next capability family. Land only the single-source cell vocabulary (steps 2-3 above).
+2. Report the change in files-touched for that family against the recorded baseline of the four
+   recurring eight-package commits.
+3. Report eager-closure deltas per entry surface. `scripts/__tests__/eager-closure-budgets.ts` has no
+   growth-approval path, and [ADR 0027](0027-descriptor-root-vs-eager-closure-budget.md) shows a
+   byte-neutral re-home can be unshippable here. A row table is a **new eager value**; if it costs
+   closure slots, it is blocked on the same ground and this ADR should be withdrawn rather than
+   granted an exception.
+
+If the fan-out does not visibly shrink, close this as rejected and leave the two authored lists in
+place — a compile-checked duplicate is a legitimate resting state.
diff --git a/docs/adr/README.md b/docs/adr/README.md
index 809f5aa11c..51e2a8af42 100644
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@ -28,6 +28,8 @@
 | [0024 Screen Recording — One Coordinator, Two Facts (Proposed)](0024-screen-recording-provable-signal.md) | `record start`/`stop` lifecycle, the export-exists / recorder-stopped split, backend stop-and-collect contract, recovery through the coordinator, the ADR 0019 §5 amendment and the failed-finish cleanup fix |
 | [0025 Foldable Apple Panels — Capture the Lit Panel](0025-foldable-apple-panels.md) | iPhone Duo outer/inner panels, CoreDevice display info as the only screen authority, why `simctl`'s implicit display default captures a black panel, derived (never asserted) pose, and why no pose-control command exists |
 | [0026 Scroll Clip Authority — Ownership Is the Parent Edge (Proposed)](0026-scroll-clip-authority.md) | iOS scroll indicators and the visible band, why ownership is read from the parent edge instead of an ancestor walk, what may remove a node from an interactive snapshot, and ejection dispositions |
+| [0027 Descriptor Root Size vs Eager-Closure Budget (Proposed)](0027-descriptor-root-vs-eager-closure-budget.md) | splitting `packages/command-registry/src/registry.ts`, the ADR-0019 eager-closure module-count budget, and why a byte-neutral hub split is currently unshippable |
+| [0028 Capability-Family Cell Vocabulary — One Runtime Source (Proposed)](0028-capability-family-cell-vocabulary.md) | adding a capability operation family, `UnavailablePlatformRuntimeFacts` / `UNAVAILABLE_CELLS`, `INTERACTOR_OPERATIONS`, and why an eight-package fan-out recurs |
 
 ADRs record *why*; the registries and gates they describe are the living source of truth — when
 prose and a registry disagree, the registry wins and the ADR needs a follow-up.

From 181a0f98ad85c3c2fabe8ea6222bc1dfe7f03e4b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Wed, 23 Sep 2026 15:03:58 +0200
Subject: [PATCH 037/132] refactor(ios): declare runner screen-capture facts at
 the owning contract (#2813)

* refactor(ios): declare runner screen-capture facts at the owning contract

#2728 asked for the runner's display facts at the owning cross-language contract,
not by per-consumer casts. The wire key was a TypeScript literal and the shape a
Swift struct pinned only by two hand-written Swift encode tests, so every consumer
restated a shape it did not own.

Move the read to packages/contracts/src/screen-capture-contract.ts and record the
wire key plus two measured Duo poses in the golden table
contracts/fixtures/screen-capture-metadata.json. The table names no field of its
own: this module's reader and ScreenshotMetadataPayload stay the only two
declarations of the shape, and each language decodes the table through its own, so
a renamed or dropped fact fails both lanes. The vitest twin asserts the host reads
exactly the facts a capture recorded and refuses anything that cannot describe one.

Negative control on a booted iPhone Duo: renaming pixelsPerPoint in the table alone
turns both lanes red, Swift with DecodingError.keyNotFound at
captures[0].metadata and vitest by refusing the payload.

* docs(adr-0025): record what the shipped capture encoder owes

The capture-surface section still said a normalization "owes a rotation and a
crop". The redraw that landed pays the rotation at the image's own logical size
and scale and deliberately takes no crop, so the one-pixel difference between a
runner capture and a simctl export stays rather than being stretched away.

Narrow the sampling-path evidence gap to what was never exercised: keyboard
settling and the navigation fallback each have a recorded lit-panel observation
from #2741, so only a pose change under the sampler, and screen recording at all,
remain open.

Drop the Device Hub and host Accessibility requirement from the Duo fixture docs.
`fold` drives the hinge through simulator HID, and device-hub-window-missing is
named by no production code any more.

* chore(gates): put the screen-capture contract on the per-PR lane

Declare the new contracts subpath in the exports map and regenerate the R11
contracts-exports snapshot from it. Add the golden-table encode test and its
no-facts sibling to the ios.yml -only-testing list, so cross-language drift on
this key fails a pull request instead of waiting for nightly; the PR list now
selects 101 methods with no dark tests.
---
 .github/workflows/ios.yml                     |  2 +
 .../RunnerTests+AppScreenCaptureTests.swift   | 78 +++++++++++++-----
 .../fixtures/screen-capture-metadata.json     | 24 ++++++
 docs/adr/0025-foldable-apple-panels.md        | 30 +++++--
 examples/test-app/README.md                   |  6 +-
 .../test-app/foldable/duo-pose-semantic.mjs   |  7 +-
 packages/contracts/package.json               |  4 +
 .../src/screen-capture-contract.test.ts       | 82 +++++++++++++++++++
 .../contracts/src/screen-capture-contract.ts  | 66 +++++++++++++++
 .../src/core/__tests__/screenshot.test.ts     | 73 ++++-------------
 .../platform-apple/src/core/screenshot.ts     | 56 +------------
 .../layering/contracts-exports.snapshot.json  |  1 +
 12 files changed, 283 insertions(+), 146 deletions(-)
 create mode 100644 contracts/fixtures/screen-capture-metadata.json
 create mode 100644 packages/contracts/src/screen-capture-contract.test.ts
 create mode 100644 packages/contracts/src/screen-capture-contract.ts

diff --git a/.github/workflows/ios.yml b/.github/workflows/ios.yml
index ecb5fc3b54..daaa784677 100644
--- a/.github/workflows/ios.yml
+++ b/.github/workflows/ios.yml
@@ -181,6 +181,8 @@ jobs:
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testApplicationStateRawValuesMatchTheActivationDecoder \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testMissingBundleCommandInvalidatesCompleteCachedTargetState \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testCachedTargetInvalidationClearsProcessBoundState \
+            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testScreenshotDisplayFactsReEncodeEveryGoldenTableRowUnderTheTablesKey \
+            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testScreenshotResultCarriesNoDisplayFactsWhenNothingResolved \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testAlertResolutionCannotBypassRequestedDeadline \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testAlertAcceptTreatsOpenAsAffirmative \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testAlertAcceptDoesNotActivateAReplacementWithASharedButton \
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+AppScreenCaptureTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+AppScreenCaptureTests.swift
index 6c9730d0f1..74b65986a2 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+AppScreenCaptureTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+AppScreenCaptureTests.swift
@@ -1,6 +1,37 @@
 import XCTest
 
 #if AGENT_DEVICE_RUNNER_UNIT_TESTS
+/// One read of contracts/fixtures/screen-capture-metadata.json. The capture decodes through the
+/// production `ScreenshotMetadataPayload`, so the table cannot describe a shape this encoder does
+/// not write, and this file's re-encode cannot write a shape the table does not describe. The table
+/// names no field of its own: this struct and the host's reader in
+/// `packages/contracts/src/screen-capture-contract.ts` are the only declarations of the shape, and
+/// `packages/contracts/src/screen-capture-contract.test.ts` is the vitest twin (#2728).
+private struct ScreenCaptureMetadataTable: Decodable {
+  struct Capture: Decodable {
+    let name: String
+    let metadata: ScreenshotMetadataPayload
+  }
+
+  let key: String
+  let captures: [Capture]
+}
+
+private func loadScreenCaptureMetadataTable() throws -> ScreenCaptureMetadataTable {
+  let fixtureURL = URL(fileURLWithPath: #filePath)
+    .deletingLastPathComponent() // UnitTests
+    .deletingLastPathComponent() // AgentDeviceRunnerUITests
+    .deletingLastPathComponent() // AgentDeviceRunner
+    .deletingLastPathComponent() // runner
+    .deletingLastPathComponent() // apple
+    .deletingLastPathComponent() // repo root
+    .appendingPathComponent("contracts/fixtures/screen-capture-metadata.json")
+  return try JSONDecoder().decode(
+    ScreenCaptureMetadataTable.self,
+    from: Data(contentsOf: fixtureURL)
+  )
+}
+
 extension RunnerTests {
   func testScreenCaptureFailureCarriesTheBridgeReasonAsItsOwnCode() {
     XCTAssertEqual(
@@ -26,34 +57,39 @@ extension RunnerTests {
     )
   }
 
-  func testScreenshotResultEncodesDisplayFactsUnderTheKeyTheHostReads() throws {
-    // The measured open-Duo inner panel: 2852x2006 at scale 3 on display 3. The host reads these to
-    // rescale an image it did not measure, so the key and the shape are a cross-language contract.
-    let payload = DataPayload(
-      message: "tmp/screenshot-1.png",
-      screenshotMetadata: ScreenshotMetadataPayload(
-        displayID: 3,
-        pixelWidth: 2852,
-        pixelHeight: 2006,
-        pixelsPerPoint: 3
+  func testScreenshotDisplayFactsReEncodeEveryGoldenTableRowUnderTheTablesKey() throws {
+    let table = try loadScreenCaptureMetadataTable()
+    XCTAssertFalse(table.captures.isEmpty, "the table must record at least one measured capture")
+    for capture in table.captures {
+      let payload = DataPayload(
+        message: "tmp/screenshot-1.png",
+        screenshotMetadata: capture.metadata
       )
-    )
-    let encoded = try JSONSerialization.jsonObject(
-      with: JSONEncoder().encode(payload)
-    ) as? [String: Any]
-    XCTAssertEqual(encoded?["message"] as? String, "tmp/screenshot-1.png")
-    let metadata = encoded?["screenshotMetadata"] as? [String: Any]
-    XCTAssertEqual(metadata?["displayID"] as? UInt, 3)
-    XCTAssertEqual(metadata?["pixelWidth"] as? Int, 2852)
-    XCTAssertEqual(metadata?["pixelHeight"] as? Int, 2006)
-    XCTAssertEqual(metadata?["pixelsPerPoint"] as? Double, 3)
+      let encoded = try JSONSerialization.jsonObject(
+        with: JSONEncoder().encode(payload)
+      ) as? [String: Any]
+      XCTAssertEqual(encoded?["message"] as? String, "tmp/screenshot-1.png", capture.name)
+      // The host reads these facts under the key the table spells, which neither language restates.
+      guard let metadata = encoded?[table.key] as? [String: Any] else {
+        return XCTFail("\(capture.name): no display facts under the table's key '\(table.key)'")
+      }
+      XCTAssertEqual(metadata["displayID"] as? UInt, capture.metadata.displayID, capture.name)
+      XCTAssertEqual(metadata["pixelWidth"] as? Int, capture.metadata.pixelWidth, capture.name)
+      XCTAssertEqual(metadata["pixelHeight"] as? Int, capture.metadata.pixelHeight, capture.name)
+      XCTAssertEqual(
+        metadata["pixelsPerPoint"] as? Double,
+        capture.metadata.pixelsPerPoint,
+        capture.name
+      )
+    }
   }
 
   func testScreenshotResultCarriesNoDisplayFactsWhenNothingResolved() throws {
+    let key = try loadScreenCaptureMetadataTable().key
     let encoded = try JSONSerialization.jsonObject(
       with: JSONEncoder().encode(DataPayload(message: "tmp/screenshot-1.png"))
     ) as? [String: Any]
-    XCTAssertNil(encoded?["screenshotMetadata"])
+    XCTAssertNil(encoded?[key], "a capture that resolved nothing owes no facts either")
   }
 }
 #endif
diff --git a/contracts/fixtures/screen-capture-metadata.json b/contracts/fixtures/screen-capture-metadata.json
new file mode 100644
index 0000000000..67227ad784
--- /dev/null
+++ b/contracts/fixtures/screen-capture-metadata.json
@@ -0,0 +1,24 @@
+{
+  "comment": "Cross-language golden table for the display facts one Apple runner capture reports about the image it encoded (#2728). The vitest twin is packages/contracts/src/screen-capture-contract.test.ts and the Swift twin is UnitTests/RunnerTests+AppScreenCaptureTests.swift, which decodes and re-encodes every capture through the production ScreenshotMetadataPayload — so a renamed or dropped fact fails both lanes. This table deliberately records no field list: the Swift struct and the TypeScript reader are the only declarations of the shape. Add a measured capture here, never to one suite.",
+  "key": "screenshotMetadata",
+  "captures": [
+    {
+      "name": "Open Duo, resolved inner panel LCD-1: the window is 951x669 pt on display 3 and the upright encoding is one pixel per axis under the 2853x2007 CoreDevice calls the panel",
+      "metadata": {
+        "displayID": 3,
+        "pixelWidth": 2852,
+        "pixelHeight": 2006,
+        "pixelsPerPoint": 3
+      }
+    },
+    {
+      "name": "Closed Duo, outer panel LCD: the same command following the app onto the other panel, reported by the window that moved with it",
+      "metadata": {
+        "displayID": 1,
+        "pixelWidth": 1398,
+        "pixelHeight": 2034,
+        "pixelsPerPoint": 3
+      }
+    }
+  ]
+}
diff --git a/docs/adr/0025-foldable-apple-panels.md b/docs/adr/0025-foldable-apple-panels.md
index acc21d64ee..3d0e7c9705 100644
--- a/docs/adr/0025-foldable-apple-panels.md
+++ b/docs/adr/0025-foldable-apple-panels.md
@@ -99,7 +99,12 @@ the system presents turned has its buffer sideways.
 The capture reports the display ID it used, the pixel size it encoded, and the pixels-per-point of
 that image, so density normalization reads the source it captured instead of applying a scale the
 host inferred. A runner that reports nothing measured nothing, and normalization keeps the pre-panel
-answer rather than borrowing a scale from a panel nobody captured.
+answer rather than borrowing a scale from a panel nobody captured. That payload is a cross-language
+contract, not a per-consumer cast: `packages/contracts/src/screen-capture-contract.ts` owns the read,
+the Swift struct owns the write, and those two types are the only declarations of the shape. The
+golden table `contracts/fixtures/screen-capture-metadata.json` carries the wire key and two measured
+poses for the vitest twin and the runner unit-test lane to decode through, so drift fails CI on both
+sides at once.
 
 A capture asks the target app's window first and the system surface's window second. The home screen
 is SpringBoard's window, so a capture with no session app — or with one that is not running — still
@@ -432,11 +437,14 @@ Four facts the capture path cannot read off the image:
   whose display size transposes the panel, where `simctl` exports the same panel `2853x2007`
   upright. The runner's production encoder and `XCUIScreenshot`'s produce 0 differing pixels for
   one capture from `358,402` and `328,181` encoded bytes, so the turn belongs to the capture and
-  not to an encoder. Rotating is not enough to compare the two: the runner's canvas is `2006x2852`
-  and `simctl`'s `2853x2007`, a pixel apart on each axis, so #2729's normalization owes a rotation
-  and a crop. - **Overlays.** A screen capture and a window capture are both display captures — the
-  second cropped to the window — so the software keyboard, a SpringBoard-hosted permission alert,
-  and the status bar all appear in either. It cuts the other way as well: that alert's own window
+  not to an encoder. Rotating is not enough to compare the two: the raw canvas is `2006x2852` and
+  `simctl`'s `2853x2007`, a pixel apart on each axis. The shipped encoder draws the capture upright
+  at that image's own logical size and scale, which pays the rotation and takes no crop: the one-pixel
+  difference stays, because stretching it to CoreDevice's nominal panel box would invent pixels the
+  capture never held (#2741). - **Overlays.** A screen capture and a window capture are both display
+  captures — the second cropped to the window — so the software keyboard, a SpringBoard-hosted
+  permission alert, and the status bar all appear in either. It cuts the other way as well: that
+  alert's own window
   resolved to `displayID` `3`, the dark panel in the closed pose, and capturing it yielded a black
   `668x950` crop indistinguishable from any capture of a dark panel. Whether a system window on the
   *lit* panel captures was not measured, so a system surface is verified on the app's panel, not
@@ -483,9 +491,13 @@ incorrect viewport, not an inner-panel delivery prohibition.
   physical foldable was never exercised.
 - **Runner observation paths that sample a frame.** Keyboard settling, screen recording, and the
   navigation fallback now take their frame from the display owning a window and each states in
-  `runner.log` what it looked at, but none was watched on a device that changes panel under it. A
-  pose change mid-recording still changes the captured display under a writer sized from the first
-  frame, and that mismatch was never exercised.
+  `runner.log` what it looked at. Keyboard settling and the navigation fallback were each watched
+  once while serving a lit panel — `AGENT_DEVICE_RUNNER_KEYBOARD_STABILITY samples=3 captured=3
+  settled=yes` behind a `returnKeyType="done"` field, and
+  `AGENT_DEVICE_RUNNER_IN_APP_BACK_VISUAL_VERIFICATION ... changed=no` as the no-change control
+  (#2741) — and neither was watched while the pose changed underneath it. Screen recording was never
+  watched: a pose change mid-recording still changes the captured display under a writer sized from
+  the first frame, and that mismatch was never exercised.
 - **Desktop capture paths.** The two `#if os(macOS)` siblings of the `screenshot` capture in
   `RunnerTests+CommandExecution.swift` keep capturing the desktop screen, which also reaches the
   screen through Screen Capture Kit in `AgentDeviceMacOSHelper`; only the iOS branches changed
diff --git a/examples/test-app/README.md b/examples/test-app/README.md
index 088f145011..825b51ace9 100644
--- a/examples/test-app/README.md
+++ b/examples/test-app/README.md
@@ -313,9 +313,9 @@ gate and does not change the ordinary iPhone lane.
 
 Requirements: `DEVELOPER_DIR` pinned to a Duo-capable Xcode (iOS 27.1 ships only with Xcode 27.1+);
 exactly one booted iPhone Duo not shared with a concurrent run (concurrent runs rebuild the shared
-Apple runner and race capture/pose state); Xcode Device Hub reachable with Accessibility permission
-(`fold` presses its pose control — a Device Hub window on a secondary display makes the control
-unreachable and reports `device-hub-window-missing`; move it to the main display); the Agent Device
+Apple runner and race capture/pose state); nothing else for pose control, because `fold` drives the
+hinge through simulator HID — a helper compiled and dispatched inside the simulator with `simctl
+spawn`, so no Device Hub window and no host Accessibility permission is involved; the Agent Device
 Tester app installed on that simulator.
 
 ```bash
diff --git a/examples/test-app/foldable/duo-pose-semantic.mjs b/examples/test-app/foldable/duo-pose-semantic.mjs
index 33881e063e..77f2d8953a 100644
--- a/examples/test-app/foldable/duo-pose-semantic.mjs
+++ b/examples/test-app/foldable/duo-pose-semantic.mjs
@@ -20,9 +20,10 @@
 //   * DEVELOPER_DIR pinned to a Duo-capable Xcode (the iOS 27.1 runtime ships only with Xcode 27.1+).
 //   * An iPhone Duo simulator already booted on that toolchain, not shared with a concurrent run
 //     (concurrent runs rebuild the shared Apple runner and race the pose/capture state).
-//   * Xcode Device Hub reachable with Accessibility permission, because `fold` presses the Device
-//     Hub pose control. If Device Hub's window is on a secondary display, pose control is
-//     unreachable and `fold` reports `device-hub-window-missing`; move it to the main display.
+//   * Nothing else for pose control: `fold` drives the hinge through simulator HID, compiling a
+//     helper and dispatching it inside the simulator with `simctl spawn`, so no Device Hub window
+//     and no host Accessibility permission is involved. It refuses a single-panel simulator as
+//     `single-panel-device` and a pose the hinge read-back does not confirm as `fold-pose-unverified`.
 //   * The Agent Device Tester fixture app installed on that simulator.
 //
 // Usage (from the repository root):
diff --git a/packages/contracts/package.json b/packages/contracts/package.json
index d7cfadd309..47dbeded3d 100644
--- a/packages/contracts/package.json
+++ b/packages/contracts/package.json
@@ -396,6 +396,10 @@
       "types": "./src/runner-lease-context.ts",
       "default": "./src/runner-lease-context.ts"
     },
+    "./screen-capture-contract": {
+      "types": "./src/screen-capture-contract.ts",
+      "default": "./src/screen-capture-contract.ts"
+    },
     "./screen-recording-runtime": {
       "types": "./src/screen-recording-runtime.ts",
       "default": "./src/screen-recording-runtime.ts"
diff --git a/packages/contracts/src/screen-capture-contract.test.ts b/packages/contracts/src/screen-capture-contract.test.ts
new file mode 100644
index 0000000000..29f67bbfb9
--- /dev/null
+++ b/packages/contracts/src/screen-capture-contract.test.ts
@@ -0,0 +1,82 @@
+import { test } from 'vitest';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  readRunnerScreenCaptureMetadata,
+  type RunnerScreenCaptureMetadata,
+} from './screen-capture-contract.ts';
+
+// Cross-language golden table: the display facts a runner capture reports about its own image are
+// written by the Swift encoder (`ScreenshotMetadataPayload`) and read here. Every capture in
+// contracts/fixtures/screen-capture-metadata.json is asserted by this file AND by
+// `UnitTests/RunnerTests+AppScreenCaptureTests.swift`, which decodes and re-encodes each one through
+// the production struct, so a renamed or dropped fact turns both suites red without a simulator. The
+// table names no field of its own: the two production types are the only declarations of the shape.
+type ScreenCaptureMetadataTable = {
+  key: string;
+  captures: Array<{ name: string; metadata: RunnerScreenCaptureMetadata }>;
+};
+
+const TABLE = JSON.parse(
+  fs.readFileSync(
+    path.resolve(
+      import.meta.dirname,
+      '..',
+      '..',
+      '..',
+      'contracts',
+      'fixtures',
+      'screen-capture-metadata.json',
+    ),
+    'utf8',
+  ),
+) as ScreenCaptureMetadataTable;
+
+const [MEASURED] = TABLE.captures;
+assert(MEASURED, 'the golden table must record at least one measured capture');
+
+/** A runner `data` payload, as the native side answers a file-path screenshot. */
+function runnerPayload(metadata: unknown): Record<string, unknown> {
+  return { message: 'tmp/screenshot-1.png', [TABLE.key]: metadata };
+}
+
+test('reads every measured capture the golden table records', () => {
+  for (const capture of TABLE.captures) {
+    // deepEqual pins the key set as well as the values, so a reader that gained or renamed a fact
+    // stops matching the capture the encoder produced.
+    assert.deepEqual(
+      readRunnerScreenCaptureMetadata(runnerPayload(capture.metadata)),
+      capture.metadata,
+      capture.name,
+    );
+  }
+});
+
+test('refuses a payload missing any fact the golden table records', () => {
+  for (const field of Object.keys(MEASURED.metadata)) {
+    const partial: Record<string, number> = { ...MEASURED.metadata };
+    delete partial[field];
+    assert.equal(
+      readRunnerScreenCaptureMetadata(runnerPayload(partial)),
+      undefined,
+      `missing ${field}`,
+    );
+  }
+});
+
+test('reports no source fact when the runner carried no metadata', () => {
+  assert.equal(readRunnerScreenCaptureMetadata({ message: 'tmp/screenshot-1.png' }), undefined);
+});
+
+test.each([
+  ['a non-object payload', 'not-an-object'],
+  ['an array payload', [MEASURED.metadata]],
+  ['the pre-panel scale probe leaking in as zero', { ...MEASURED.metadata, displayID: 0 }],
+  ['a zero-scale image', { ...MEASURED.metadata, pixelsPerPoint: 0 }],
+  ['a non-integer pixel box', { ...MEASURED.metadata, pixelWidth: 2852.5 }],
+  ['a negative scale', { ...MEASURED.metadata, pixelsPerPoint: -3 }],
+  ['a non-numeric scale', { ...MEASURED.metadata, pixelsPerPoint: '3' }],
+])('refuses %s rather than guessing a capture', (_case, metadata) => {
+  assert.equal(readRunnerScreenCaptureMetadata(runnerPayload(metadata)), undefined);
+});
diff --git a/packages/contracts/src/screen-capture-contract.ts b/packages/contracts/src/screen-capture-contract.ts
new file mode 100644
index 0000000000..3df2ea3960
--- /dev/null
+++ b/packages/contracts/src/screen-capture-contract.ts
@@ -0,0 +1,66 @@
+/**
+ * The display facts an Apple runner capture reports about the image it encoded (#2728).
+ *
+ * A foldable lights one panel at a time and the dark panel still answers with a valid all-black PNG
+ * at exit zero, so a capture has to carry its own proof of what it looked at: the display it
+ * captured, the box it encoded, and how many pixels make one point. Swift owns the encoder
+ * (`ScreenshotMetadataPayload` in `RunnerTests+Models.swift`) and this module owns the reader; those
+ * two types are the only declarations of the shape. The golden table
+ * `contracts/fixtures/screen-capture-metadata.json` carries the wire key and two real measured
+ * captures, and each language decodes it through its own production type — this file's test and
+ * `UnitTests/RunnerTests+AppScreenCaptureTests.swift` — so a renamed or dropped fact turns both
+ * lanes red without a simulator. A consumer may not restate this shape as a local literal or read it
+ * through an unchecked cast.
+ */
+
+/** The `data` key a runner screenshot result carries its display facts under. */
+const RUNNER_SCREEN_CAPTURE_METADATA_KEY = 'screenshotMetadata';
+
+/**
+ * What one runner capture measured about itself. `pixelsPerPoint` is the scale of the image the
+ * runner encoded, `pixelWidth`/`pixelHeight` are that encoded image's own box after the runner drew
+ * it upright, and `displayID` is the screen the window reported — never a screen chosen by number
+ * or by position in a screen list.
+ */
+export type RunnerScreenCaptureMetadata = Readonly<{
+  displayID: number;
+  pixelWidth: number;
+  pixelHeight: number;
+  pixelsPerPoint: number;
+}>;
+
+/**
+ * Reads the display facts out of a runner `data` payload. Returns undefined when the payload carries
+ * none or carries a value that cannot describe a real capture, which leaves the consumer with no
+ * source fact — the honest pre-panel state — rather than a number invented from a panel nobody
+ * measured. The Swift encoder refuses to report a scale that is not finite and positive, so these
+ * refusals are the host's defence against a payload that did not come from that encoder.
+ */
+export function readRunnerScreenCaptureMetadata(
+  data: Record<string, unknown>,
+): RunnerScreenCaptureMetadata | undefined {
+  const raw = data[RUNNER_SCREEN_CAPTURE_METADATA_KEY];
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return undefined;
+  const payload = raw as Record<string, unknown>;
+  const displayID = readPositiveInteger(payload.displayID);
+  const pixelWidth = readPositiveInteger(payload.pixelWidth);
+  const pixelHeight = readPositiveInteger(payload.pixelHeight);
+  const pixelsPerPoint = readPositiveFinite(payload.pixelsPerPoint);
+  if (
+    displayID === undefined ||
+    pixelWidth === undefined ||
+    pixelHeight === undefined ||
+    pixelsPerPoint === undefined
+  ) {
+    return undefined;
+  }
+  return Object.freeze({ displayID, pixelWidth, pixelHeight, pixelsPerPoint });
+}
+
+function readPositiveInteger(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isInteger(value) && value > 0 ? value : undefined;
+}
+
+function readPositiveFinite(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : undefined;
+}
diff --git a/packages/platform-apple/src/core/__tests__/screenshot.test.ts b/packages/platform-apple/src/core/__tests__/screenshot.test.ts
index 971e2cc881..01651f6763 100644
--- a/packages/platform-apple/src/core/__tests__/screenshot.test.ts
+++ b/packages/platform-apple/src/core/__tests__/screenshot.test.ts
@@ -1,7 +1,8 @@
 import { beforeEach, test, vi } from 'vitest';
 import assert from 'node:assert/strict';
-import { promises as fs } from 'node:fs';
+import { promises as fs, readFileSync } from 'node:fs';
 import path from 'node:path';
+import type { RunnerScreenCaptureMetadata } from '@agent-device/contracts/screen-capture-contract';
 import { mkdtempForTest } from '../../__tests__/tmp-dir.ts';
 
 vi.mock('@agent-device/host-kit/command', async (importOriginal) => {
@@ -49,7 +50,6 @@ import {
   captureSimulatorScreenshotWithFallback,
   captureSimulatorScreenshotWithRetry,
   captureScreenshotViaRunner,
-  readRunnerScreenCaptureMetadata,
   resolveSimulatorRunnerScreenshotCandidatePaths,
   shouldRetryIosSimulatorScreenshot,
 } from '../screenshot.ts';
@@ -70,6 +70,17 @@ const mockEnsureBootedSimulator = vi.mocked(ensureBootedSimulator);
 const mockOpenIosSimulatorApp = vi.mocked(openIosSimulatorApp);
 const mockPrepareStatusBarForScreenshot = vi.mocked(prepareSimulatorStatusBarForScreenshot);
 
+// The wire key and a real measured capture come from the cross-language golden table, so this
+// consumer suite cannot spell a shape the Swift encoder disagrees with (#2728).
+const SCREEN_CAPTURE_TABLE = JSON.parse(
+  readFileSync(
+    new URL('../../../../../contracts/fixtures/screen-capture-metadata.json', import.meta.url),
+    'utf8',
+  ),
+) as { key: string; captures: Array<{ metadata: RunnerScreenCaptureMetadata }> };
+const [MEASURED_CAPTURE] = SCREEN_CAPTURE_TABLE.captures;
+assert(MEASURED_CAPTURE, 'the golden table must record at least one measured capture');
+
 beforeEach(() => {
   vi.resetAllMocks();
   mockRunCmd.mockImplementation(execActual.runCmd);
@@ -505,7 +516,7 @@ test('captureScreenshotViaRunner reports the display facts a runner capture meas
   await fs.writeFile(runnerImage, 'runner-image', 'utf8');
   mockRunAppleRunnerCommand.mockResolvedValue({
     message: 'tmp/duo.png',
-    screenshotMetadata: { displayID: 3, pixelWidth: 2852, pixelHeight: 2006, pixelsPerPoint: 3 },
+    [SCREEN_CAPTURE_TABLE.key]: MEASURED_CAPTURE.metadata,
   });
   mockRunCmd.mockImplementation(async (_cmd, args) => {
     if (args.includes('get_app_container')) {
@@ -517,12 +528,7 @@ test('captureScreenshotViaRunner reports the display facts a runner capture meas
   try {
     const outPath = path.join(tmpDir, 'out.png');
     const metadata = await captureScreenshotViaRunner(device, outPath);
-    assert.deepEqual(metadata, {
-      displayID: 3,
-      pixelWidth: 2852,
-      pixelHeight: 2006,
-      pixelsPerPoint: 3,
-    });
+    assert.deepEqual(metadata, MEASURED_CAPTURE.metadata);
     assert.equal(await fs.readFile(outPath, 'utf8'), 'runner-image');
   } finally {
     await fs.rm(tmpDir, { recursive: true, force: true });
@@ -568,52 +574,3 @@ test('captureScreenshotViaRunner copies macOS runner screenshots from the host',
     await fs.rm(tmpDir, { recursive: true, force: true });
   }
 });
-
-// The open-Duo row of the #2727 measurement: a resolved inner panel reports 2852x2006 at scale 3,
-// one pixel per axis smaller than the size CoreDevice calls the panel.
-const OPEN_DUO_CAPTURE = {
-  displayID: 3,
-  pixelWidth: 2852,
-  pixelHeight: 2006,
-  pixelsPerPoint: 3,
-};
-
-// The wire key is spelled as a literal because the Swift encoder, not this module, owns it (#2728).
-function runnerCapturePayload(metadata: unknown): Record<string, unknown> {
-  return { message: 'tmp/screenshot-1.png', screenshotMetadata: metadata };
-}
-
-test('reads the display facts a resolved runner capture reported', () => {
-  assert.deepEqual(
-    readRunnerScreenCaptureMetadata(runnerCapturePayload(OPEN_DUO_CAPTURE)),
-    OPEN_DUO_CAPTURE,
-  );
-  assert.deepEqual(
-    readRunnerScreenCaptureMetadata(
-      runnerCapturePayload({
-        displayID: 1,
-        pixelWidth: 1398,
-        pixelHeight: 2034,
-        pixelsPerPoint: 3,
-      }),
-    ),
-    { displayID: 1, pixelWidth: 1398, pixelHeight: 2034, pixelsPerPoint: 3 },
-  );
-});
-
-test('reports no source fact when the runner carried no metadata', () => {
-  assert.equal(readRunnerScreenCaptureMetadata({ message: 'tmp/screenshot-1.png' }), undefined);
-});
-
-test.each([
-  ['a non-object payload', 'not-an-object'],
-  ['an array payload', [OPEN_DUO_CAPTURE]],
-  ['the pre-panel scale probe value leaking in as zero', { ...OPEN_DUO_CAPTURE, displayID: 0 }],
-  ['a zero-scale image', { ...OPEN_DUO_CAPTURE, pixelsPerPoint: 0 }],
-  ['a non-integer pixel box', { ...OPEN_DUO_CAPTURE, pixelWidth: 2852.5 }],
-  ['a missing side', { displayID: 3, pixelWidth: 2852, pixelsPerPoint: 3 }],
-  ['a negative scale', { ...OPEN_DUO_CAPTURE, pixelsPerPoint: -3 }],
-  ['a non-numeric scale', { ...OPEN_DUO_CAPTURE, pixelsPerPoint: '3' }],
-])('refuses %s rather than guessing a capture scale', (_case, metadata) => {
-  assert.equal(readRunnerScreenCaptureMetadata(runnerCapturePayload(metadata)), undefined);
-});
diff --git a/packages/platform-apple/src/core/screenshot.ts b/packages/platform-apple/src/core/screenshot.ts
index 1879149d2a..a4d00c1a73 100644
--- a/packages/platform-apple/src/core/screenshot.ts
+++ b/packages/platform-apple/src/core/screenshot.ts
@@ -5,6 +5,10 @@ import { emitDiagnostic } from '@agent-device/host-kit/diagnostics';
 import { copyHostFile } from '@agent-device/host-kit/host-file';
 import { Deadline, retryWithPolicy } from '@agent-device/host-kit/retry';
 import { AppError } from '@agent-device/kernel/errors';
+import {
+  readRunnerScreenCaptureMetadata,
+  type RunnerScreenCaptureMetadata,
+} from '@agent-device/contracts/screen-capture-contract';
 
 import { resizePngFile } from '@agent-device/capture-kit/png-resize';
 import { readPngSize } from '@agent-device/capture-kit/png-size';
@@ -33,58 +37,6 @@ import { runSimctlForDevice } from './simctl.ts';
 import { appleToolFailureText, extractAppleToolErrorMeta } from './tool-diagnostics.ts';
 import { resolveIosPhysicalDeviceControl } from './physical-device-control.ts';
 
-/** The `data` key a runner screenshot result carries its display facts under. */
-const RUNNER_SCREEN_CAPTURE_METADATA_KEY = 'screenshotMetadata';
-
-/**
- * What one runner capture measured about itself. `pixelsPerPoint` is the scale of the image the
- * runner encoded, `pixelWidth`/`pixelHeight` are that encoded image's own box after the runner drew
- * it upright, and `displayID` is the screen the window reported — never a screen chosen by number
- * or by position in a screen list. The runner owns this vocabulary; the literals are pinned against
- * the Swift encoder in the screenshot tests.
- */
-export type RunnerScreenCaptureMetadata = Readonly<{
-  displayID: number;
-  pixelWidth: number;
-  pixelHeight: number;
-  pixelsPerPoint: number;
-}>;
-
-/**
- * Reads the display facts out of a runner `data` payload. Returns undefined when the payload carries
- * none or carries a value that cannot describe a real capture, which leaves the consumer with no
- * source fact — the honest pre-panel state — rather than a number invented from a panel nobody
- * measured.
- */
-export function readRunnerScreenCaptureMetadata(
-  data: Record<string, unknown>,
-): RunnerScreenCaptureMetadata | undefined {
-  const raw = data[RUNNER_SCREEN_CAPTURE_METADATA_KEY];
-  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return undefined;
-  const payload = raw as Record<string, unknown>;
-  const displayID = readPositiveInteger(payload.displayID);
-  const pixelWidth = readPositiveInteger(payload.pixelWidth);
-  const pixelHeight = readPositiveInteger(payload.pixelHeight);
-  const pixelsPerPoint = readPositiveFinite(payload.pixelsPerPoint);
-  if (
-    displayID === undefined ||
-    pixelWidth === undefined ||
-    pixelHeight === undefined ||
-    pixelsPerPoint === undefined
-  ) {
-    return undefined;
-  }
-  return Object.freeze({ displayID, pixelWidth, pixelHeight, pixelsPerPoint });
-}
-
-function readPositiveInteger(value: unknown): number | undefined {
-  return typeof value === 'number' && Number.isInteger(value) && value > 0 ? value : undefined;
-}
-
-function readPositiveFinite(value: unknown): number | undefined {
-  return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : undefined;
-}
-
 function runSimctl(device: DeviceInfo, args: string[], options?: ExecOptions) {
   return runSimctlForDevice(device, args, options);
 }
diff --git a/scripts/layering/contracts-exports.snapshot.json b/scripts/layering/contracts-exports.snapshot.json
index db1201fb26..419ebc6e98 100644
--- a/scripts/layering/contracts-exports.snapshot.json
+++ b/scripts/layering/contracts-exports.snapshot.json
@@ -96,6 +96,7 @@
   "@agent-device/contracts/replay",
   "@agent-device/contracts/runner-lease-context",
   "@agent-device/contracts/runtime-operation-names",
+  "@agent-device/contracts/screen-capture-contract",
   "@agent-device/contracts/screen-recording-runtime",
   "@agent-device/contracts/screen-recording-runtime-host",
   "@agent-device/contracts/screen-recording-runtime-plan",

From 210f958d8540610be9dd4fd2244c0cc33d95db26 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Wed, 23 Sep 2026 15:04:16 +0200
Subject: [PATCH 038/132] refactor(move): split runner failure classification
 out of the wire contract (#2809)

* refactor(move): split runner failure classification out of the wire contract

runner-contract.ts is 1,055 lines and answers two questions: what the XCTest
runner's request/response wire looks like, and what a runner failure means for
what we do next. Move the second one out.

- runner-error-classification.ts: the startup-failure reason vocabulary, the
  RUNNER_ERROR_RULES table (moved byte-for-byte), its matcher, every recovery
  predicate, and the startup classifier plus the device-state enrichment.
- runner-startup-failure.ts: how the runner that never served a command is
  reported - the early-exit hint and the connect/early-exit error builders.
- runner-contract.ts keeps the wire half: command shape, command id, request
  signal and active assertion, the runner codes that stay off the wire code,
  and response decoding. It no longer imports runner-session-types or
  provision-kit/boot-diagnostics, and reaches host.ts for two request
  functions instead of five symbols.

* refactor(move): merge two runner modules back into their only consumers

The eager-closure budget (ADR 0019, scripts/__tests__/eager-closure-budgets.test.ts)
holds three Apple facades at their merge-base module count, and a file split inside
their eager closure pays one evaluated module per new file. Two merges pay that tax
without an allowlist, each because the merged pair answers one question:

- runner-startup-failure.ts (98 lines) folds into runner-startup-transport.ts, the
  module whose connect loop and early-exit path are the only producers of those
  failures. It already imported both RunnerSession and the classification module, so
  this adds no import edge at all. Folding into the classification module instead
  would have made runner-error-classification import runner-session-types while
  runner-session-types imports IosRunnerDeviceStates from it: the same type cycle
  this PR exists to remove, plus a longer one through runner-xctestrun.
- runner-command-manifest.ts (47 lines) collapses into runner-command-traits.ts,
  its only production consumer. The manifest is a `satisfies`-checked declaration
  table that exists to build that module's traits map, the same shape as
  packages/contracts/src/interactor-operation-catalog.ts. The table is read only
  inside readRunnerCommandTraits, and it stays declared above that function, so no
  evaluation order moves; RUNNER_COMMAND_TRAIT_MANIFEST is unchanged, including its
  `as const satisfies Record<RunnerCommand['command'], RunnerCommandTraitClass>`.

Exported names are unchanged; consumers move by import path only. The three facades
land back at 120/101/100 evaluated modules.

* docs(apple-runner): point the runner routing line at the modules that own each question

Connection errors are built in runner-startup-transport.ts and retry policy is the
rule table in runner-error-classification.ts; only command typing stays in
runner-contract.ts.

* refactor(test): carry the early-exit hint cases with the module that builds that hint

resolveRunnerEarlyExitHint now lives in runner-startup-transport.ts, so its two
cases move from runner-client.test.ts to that module's own mirror test, verbatim.
The legacy runner-client.test.ts also may not grow: the 1,000-line test-size
ratchet pins it at its merge-base length of 1,082 lines, and re-pointing three
import specifiers would have pushed it to 1,083. It is now 1,063.

* refactor(apple-runner): keep the runner connect-error builder private to its module

buildRunnerConnectError was exported from the wire contract only because the
startup transport consumed it. Now that they share a module, the export has no
consumer and fallow reports it as dead code.
---
 docs/agents/device-verification.md            |   3 +-
 .../runner/__tests__/runner-client.test.ts    |  31 +-
 .../__tests__/runner-command-traits.test.ts   |   2 +-
 .../__tests__/runner-device-readiness.test.ts |   2 +-
 .../runner-early-exit-diagnosis.test.ts       |   2 +-
 .../runner-error-classification.test.ts       |   6 +-
 .../__tests__/runner-session-response.test.ts |   2 +-
 .../runner-startup-failure-fixtures.ts        |   4 +-
 .../runner-startup-failure-reasons.test.ts    |   2 +-
 .../runner-startup-transport.test.ts          |  21 +-
 .../src/runner/runner-artifact.ts             |   2 +-
 .../src/runner/runner-client.ts               |   2 +-
 .../src/runner/runner-command-manifest.ts     |  47 --
 .../src/runner/runner-command-traits.ts       |  47 +-
 .../src/runner/runner-contract.ts             | 777 +-----------------
 .../src/runner/runner-dev-tools-security.ts   |   2 +-
 .../src/runner/runner-device-readiness.ts     |   2 +-
 .../src/runner/runner-error-classification.ts | 676 +++++++++++++++
 .../src/runner/runner-lifecycle.ts            |  10 +-
 .../src/runner/runner-session-types.ts        |   2 +-
 .../src/runner/runner-session.ts              |   4 +-
 .../src/runner/runner-startup-transport.ts    |  99 ++-
 .../src/runner/runner-transport.ts            |   3 +-
 23 files changed, 876 insertions(+), 872 deletions(-)
 delete mode 100644 packages/platform-apple/src/runner/runner-command-manifest.ts
 create mode 100644 packages/platform-apple/src/runner/runner-error-classification.ts

diff --git a/docs/agents/device-verification.md b/docs/agents/device-verification.md
index a17c9d9750..29391a4f26 100644
--- a/docs/agents/device-verification.md
+++ b/docs/agents/device-verification.md
@@ -45,7 +45,8 @@ verification looks exactly like that to the next `open` — until the owner reop
 boot it is now running on and makes the claim live again.
 
 The OS-neutral Apple runner lives under `packages/platform-apple/src/runner/`. For connection errors,
-retry policy, or command typing, start at `runner-contract.ts`; transport stays below session/client
+start at `runner-startup-transport.ts`; for retry policy, at `runner-error-classification.ts`; for
+command typing, at `runner-contract.ts`. Transport stays below session/client
 behavior, and xctestrun build/cache logic stays outside request execution.
 
 ## Session hygiene
diff --git a/packages/platform-apple/src/runner/__tests__/runner-client.test.ts b/packages/platform-apple/src/runner/__tests__/runner-client.test.ts
index 48df249118..4ea4ae064a 100644
--- a/packages/platform-apple/src/runner/__tests__/runner-client.test.ts
+++ b/packages/platform-apple/src/runner/__tests__/runner-client.test.ts
@@ -3,7 +3,6 @@ import {
   isRequestCanceledError,
   AppError,
 } from '@agent-device/kernel/errors';
-import { RUNNER_COMMAND_TRAIT_MANIFEST } from '../runner-command-manifest.ts';
 import type { RequestProgressEvent } from '@agent-device/contracts/progress';
 import { beforeEach, test, onTestFinished, vi } from 'vitest';
 import assert from 'node:assert/strict';
@@ -30,14 +29,15 @@ vi.mock('../runner-macos-products.ts', async () => {
 });
 
 import type { DeviceInfo } from '@agent-device/kernel/device';
-import { isReadOnlyRunnerCommand } from '../runner-command-traits.ts';
+import {
+  RUNNER_COMMAND_TRAIT_MANIFEST,
+  isReadOnlyRunnerCommand,
+} from '../runner-command-traits.ts';
 import {
   isRetryableRunnerError,
-  resolveRunnerEarlyExitHint,
   shouldRetryRunnerConnectError,
-  withRunnerCommandId,
-  type RunnerCommand,
-} from '../runner-contract.ts';
+} from '../runner-error-classification.ts';
+import { withRunnerCommandId, type RunnerCommand } from '../runner-contract.ts';
 import {
   resolveRunnerBuildDestination,
   resolveRunnerDestination,
@@ -415,25 +415,6 @@ test('assertSafeDerivedCleanup allows cleaning override path under project .tmp'
   });
 });
 
-test('resolveRunnerEarlyExitHint surfaces busy-connecting guidance', () => {
-  const hint = resolveRunnerEarlyExitHint(
-    'Runner did not accept connection (xcodebuild exited early)',
-    'Ineligible destinations for the "AgentDeviceRunner" scheme:\n{ error:Device is busy (Connecting to iPhone) }',
-    '',
-  );
-  assert.match(hint, /still connecting/i);
-});
-
-test('resolveRunnerEarlyExitHint falls back to runner connect timeout hint', () => {
-  const hint = resolveRunnerEarlyExitHint(
-    'Runner did not accept connection (xcodebuild exited early)',
-    '',
-    'xcodebuild failed unexpectedly',
-  );
-  assert.match(hint, /retry runner startup/i);
-  assert.match(hint, /pnpm clean:xcuitest/i);
-});
-
 test('shouldRetryRunnerConnectError does not retry xcodebuild early-exit errors', () => {
   const err = new AppError(
     'COMMAND_FAILED',
diff --git a/packages/platform-apple/src/runner/__tests__/runner-command-traits.test.ts b/packages/platform-apple/src/runner/__tests__/runner-command-traits.test.ts
index 2ea8cc13bb..5d83d569ac 100644
--- a/packages/platform-apple/src/runner/__tests__/runner-command-traits.test.ts
+++ b/packages/platform-apple/src/runner/__tests__/runner-command-traits.test.ts
@@ -8,9 +8,9 @@ import {
   isRunnerReadinessPreflightExempt,
   isRunnerReadinessProbeCommand,
   readRunnerCommandTraits,
+  RUNNER_COMMAND_TRAIT_MANIFEST,
   type RunnerCommandTraits,
 } from '../runner-command-traits.ts';
-import { RUNNER_COMMAND_TRAIT_MANIFEST } from '../runner-command-manifest.ts';
 
 const EXPECTED_RUNNER_COMMAND_TRAITS = Object.fromEntries(
   Object.entries(RUNNER_COMMAND_TRAIT_MANIFEST).map(([command, traitClass]) => [
diff --git a/packages/platform-apple/src/runner/__tests__/runner-device-readiness.test.ts b/packages/platform-apple/src/runner/__tests__/runner-device-readiness.test.ts
index 1c00f2edd0..d1338cd0a4 100644
--- a/packages/platform-apple/src/runner/__tests__/runner-device-readiness.test.ts
+++ b/packages/platform-apple/src/runner/__tests__/runner-device-readiness.test.ts
@@ -6,7 +6,7 @@ import { appleRunnerTestHost } from '../test-host.ts';
 import type { IosPhysicalDeviceRunnerControl } from '../../core/physical-device-routing.ts';
 import type { IosDeviceReadiness } from '../host.ts';
 import { preflightIosRunnerDeviceReadiness } from '../runner-device-readiness.ts';
-import { RUNNER_DEVICE_READINESS_FAILURE_REASONS } from '../runner-contract.ts';
+import { RUNNER_DEVICE_READINESS_FAILURE_REASONS } from '../runner-error-classification.ts';
 import { IOS_DEVICE, IOS_SIMULATOR, MACOS_DEVICE } from './device-fixtures.ts';
 import {
   deviceReadinessFixtures,
diff --git a/packages/platform-apple/src/runner/__tests__/runner-early-exit-diagnosis.test.ts b/packages/platform-apple/src/runner/__tests__/runner-early-exit-diagnosis.test.ts
index 4afff5b787..54bb0da57c 100644
--- a/packages/platform-apple/src/runner/__tests__/runner-early-exit-diagnosis.test.ts
+++ b/packages/platform-apple/src/runner/__tests__/runner-early-exit-diagnosis.test.ts
@@ -4,7 +4,7 @@ import path from 'node:path';
 import { test } from 'vitest';
 import type { AppError } from '@agent-device/kernel/errors';
 import type { ExecBackgroundResult } from '@agent-device/host-kit/command';
-import { buildRunnerEarlyExitError } from '../runner-contract.ts';
+import { buildRunnerEarlyExitError } from '../runner-startup-transport.ts';
 import { readRunnerLogTail } from '../runner-io.ts';
 import type { RunnerSession } from '../runner-session-types.ts';
 import { mkdtempForTestSync } from './tmp-dir.ts';
diff --git a/packages/platform-apple/src/runner/__tests__/runner-error-classification.test.ts b/packages/platform-apple/src/runner/__tests__/runner-error-classification.test.ts
index 1cd6c6fa1a..2ff3beb550 100644
--- a/packages/platform-apple/src/runner/__tests__/runner-error-classification.test.ts
+++ b/packages/platform-apple/src/runner/__tests__/runner-error-classification.test.ts
@@ -2,16 +2,18 @@ import assert from 'node:assert/strict';
 import { test } from 'vitest';
 import { AppError, createRequestCanceledError } from '@agent-device/kernel/errors';
 import {
+  RUNNER_SCREEN_CAPTURE_REFUSAL_RUNNER_CODES,
   classifyRunnerReportedError,
+} from '../runner-contract.ts';
+import {
   RUNNER_ERROR_RULES,
-  RUNNER_SCREEN_CAPTURE_REFUSAL_RUNNER_CODES,
   isRetryableRunnerError,
   resolveRunnerFatalErrorReason,
   shouldRebuildCachedRunnerArtifact,
   shouldRestartRunnerAfterReadinessPreflight,
   shouldRestartRunnerBeforeCommandSend,
   shouldRetryRunnerConnectError,
-} from '../runner-contract.ts';
+} from '../runner-error-classification.ts';
 
 function commandFailed(message: string, details?: Record<string, unknown>): AppError {
   return new AppError('COMMAND_FAILED', message, details);
diff --git a/packages/platform-apple/src/runner/__tests__/runner-session-response.test.ts b/packages/platform-apple/src/runner/__tests__/runner-session-response.test.ts
index d1ad163287..91de8d0c57 100644
--- a/packages/platform-apple/src/runner/__tests__/runner-session-response.test.ts
+++ b/packages/platform-apple/src/runner/__tests__/runner-session-response.test.ts
@@ -6,7 +6,7 @@ import path from 'node:path';
 import type { DiagnosticEventInput } from '@agent-device/host-kit/diagnostics';
 import { mkdtempForTestSync } from './tmp-dir.ts';
 import { appleRunnerTestHost } from '../test-host.ts';
-import { isRetryableRunnerError } from '../runner-contract.ts';
+import { isRetryableRunnerError } from '../runner-error-classification.ts';
 import type { RunnerLogAttempt } from '../runner-failure-diagnostics.ts';
 import { parseRunnerResponse } from '../runner-session.ts';
 
diff --git a/packages/platform-apple/src/runner/__tests__/runner-startup-failure-fixtures.ts b/packages/platform-apple/src/runner/__tests__/runner-startup-failure-fixtures.ts
index b351184b7f..c38b2b1dd7 100644
--- a/packages/platform-apple/src/runner/__tests__/runner-startup-failure-fixtures.ts
+++ b/packages/platform-apple/src/runner/__tests__/runner-startup-failure-fixtures.ts
@@ -2,8 +2,8 @@ import { AppError } from '@agent-device/kernel/errors';
 import type {
   RunnerDeviceReadinessFailureReason,
   RunnerStartupFailureReason,
-} from '../runner-contract.ts';
-import { RUNNER_DEVICE_READINESS_FAILURE_REASONS } from '../runner-contract.ts';
+} from '../runner-error-classification.ts';
+import { RUNNER_DEVICE_READINESS_FAILURE_REASONS } from '../runner-error-classification.ts';
 import type { IosPhysicalDeviceRunnerControl } from '../../core/physical-device-routing.ts';
 
 /**
diff --git a/packages/platform-apple/src/runner/__tests__/runner-startup-failure-reasons.test.ts b/packages/platform-apple/src/runner/__tests__/runner-startup-failure-reasons.test.ts
index e5f3cff58b..94a26223e6 100644
--- a/packages/platform-apple/src/runner/__tests__/runner-startup-failure-reasons.test.ts
+++ b/packages/platform-apple/src/runner/__tests__/runner-startup-failure-reasons.test.ts
@@ -19,7 +19,7 @@ import {
   RUNNER_STARTUP_FAILURE_REASONS,
   RUNNER_STARTUP_FAILURE_UNCLASSIFIED_REASON,
   type RunnerStartupFailureReason,
-} from '../runner-contract.ts';
+} from '../runner-error-classification.ts';
 import { assertDevToolsSecurityForIosRunner } from '../runner-dev-tools-security.ts';
 import { appleToolchainProbeResult } from './apple-toolchain-fixtures.ts';
 import { IOS_DEVICE } from './device-fixtures.ts';
diff --git a/packages/platform-apple/src/runner/__tests__/runner-startup-transport.test.ts b/packages/platform-apple/src/runner/__tests__/runner-startup-transport.test.ts
index 07d9128185..38ae2a55f2 100644
--- a/packages/platform-apple/src/runner/__tests__/runner-startup-transport.test.ts
+++ b/packages/platform-apple/src/runner/__tests__/runner-startup-transport.test.ts
@@ -31,7 +31,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { clearDeviceTunnelIpCache } from '../runner-command-route.ts';
 import { readRunnerLogTail } from '../runner-io.ts';
-import { waitForRunner } from '../runner-startup-transport.ts';
+import { resolveRunnerEarlyExitHint, waitForRunner } from '../runner-startup-transport.ts';
 import { mkdtempForTestSync } from './tmp-dir.ts';
 
 beforeEach(() => {
@@ -365,3 +365,22 @@ function makeReadyRunnerSession(): RunnerSession {
     hasAbandonedCommands: false,
   };
 }
+
+test('resolveRunnerEarlyExitHint surfaces busy-connecting guidance', () => {
+  const hint = resolveRunnerEarlyExitHint(
+    'Runner did not accept connection (xcodebuild exited early)',
+    'Ineligible destinations for the "AgentDeviceRunner" scheme:\n{ error:Device is busy (Connecting to iPhone) }',
+    '',
+  );
+  assert.match(hint, /still connecting/i);
+});
+
+test('resolveRunnerEarlyExitHint falls back to runner connect timeout hint', () => {
+  const hint = resolveRunnerEarlyExitHint(
+    'Runner did not accept connection (xcodebuild exited early)',
+    '',
+    'xcodebuild failed unexpectedly',
+  );
+  assert.match(hint, /retry runner startup/i);
+  assert.match(hint, /pnpm clean:xcuitest/i);
+});
diff --git a/packages/platform-apple/src/runner/runner-artifact.ts b/packages/platform-apple/src/runner/runner-artifact.ts
index 8f332b69fd..ba7cff5734 100644
--- a/packages/platform-apple/src/runner/runner-artifact.ts
+++ b/packages/platform-apple/src/runner/runner-artifact.ts
@@ -13,7 +13,7 @@ import {
 } from './host.ts';
 import type { ExecBackgroundResult } from '@agent-device/host-kit/command';
 import type { DeviceInfo } from '@agent-device/kernel/device';
-import { classifyRunnerStartupFailure } from './runner-contract.ts';
+import { classifyRunnerStartupFailure } from './runner-error-classification.ts';
 import { logChunk } from './runner-io.ts';
 import { withXcodebuildSimulatorSetRedirect } from './runner-device-set.ts';
 import {
diff --git a/packages/platform-apple/src/runner/runner-client.ts b/packages/platform-apple/src/runner/runner-client.ts
index 7056c5f971..4706959011 100644
--- a/packages/platform-apple/src/runner/runner-client.ts
+++ b/packages/platform-apple/src/runner/runner-client.ts
@@ -9,10 +9,10 @@ import {
 } from './runner-session.ts';
 import {
   assertRunnerRequestActive,
-  isRetryableRunnerError,
   withRunnerCommandId,
   type RunnerCommand,
 } from './runner-contract.ts';
+import { isRetryableRunnerError } from './runner-error-classification.ts';
 import { isReadOnlyRunnerCommand } from './runner-command-traits.ts';
 import {
   createLocalAppleRunnerProvider,
diff --git a/packages/platform-apple/src/runner/runner-command-manifest.ts b/packages/platform-apple/src/runner/runner-command-manifest.ts
deleted file mode 100644
index 7974928ef2..0000000000
--- a/packages/platform-apple/src/runner/runner-command-manifest.ts
+++ /dev/null
@@ -1,47 +0,0 @@
-import type { RunnerCommand } from './runner-contract.ts';
-
-export type RunnerCommandTraitClass =
-  | 'default'
-  | 'readinessPreflightExemptMutation'
-  | 'readOnly'
-  | 'alertAction'
-  | 'readOnlyReadinessProbe'
-  | 'preflightSkippableTouchMutation';
-
-export const RUNNER_COMMAND_TRAIT_MANIFEST = {
-  tap: 'preflightSkippableTouchMutation',
-  mouseClick: 'default',
-  longPress: 'preflightSkippableTouchMutation',
-  drag: 'preflightSkippableTouchMutation',
-  remotePress: 'default',
-  type: 'default',
-  swipe: 'preflightSkippableTouchMutation',
-  scroll: 'preflightSkippableTouchMutation',
-  desktopScroll: 'preflightSkippableTouchMutation',
-  findText: 'readOnly',
-  querySelector: 'readOnly',
-  readText: 'readOnly',
-  snapshot: 'readOnly',
-  screenshot: 'readOnly',
-  back: 'default',
-  backInApp: 'default',
-  backSystem: 'default',
-  home: 'default',
-  rotate: 'default',
-  gesture: 'preflightSkippableTouchMutation',
-  gestureViewport: 'readOnly',
-  appSwitcher: 'default',
-  actionButton: 'default',
-  keyboardDismiss: 'default',
-  keyboardReturn: 'default',
-  alert: 'alertAction',
-  sequence: 'preflightSkippableTouchMutation',
-  recordStart: 'default',
-  recordStop: 'default',
-  status: 'readOnlyReadinessProbe',
-  uptime: 'readOnlyReadinessProbe',
-  activate: 'readinessPreflightExemptMutation',
-  terminate: 'readinessPreflightExemptMutation',
-  targetReset: 'readinessPreflightExemptMutation',
-  shutdown: 'default',
-} as const satisfies Record<RunnerCommand['command'], RunnerCommandTraitClass>;
diff --git a/packages/platform-apple/src/runner/runner-command-traits.ts b/packages/platform-apple/src/runner/runner-command-traits.ts
index f0e5686d5f..cdb6be10d2 100644
--- a/packages/platform-apple/src/runner/runner-command-traits.ts
+++ b/packages/platform-apple/src/runner/runner-command-traits.ts
@@ -1,5 +1,50 @@
 import type { RunnerCommand } from './runner-contract.ts';
-import { RUNNER_COMMAND_TRAIT_MANIFEST } from './runner-command-manifest.ts';
+
+export type RunnerCommandTraitClass =
+  | 'default'
+  | 'readinessPreflightExemptMutation'
+  | 'readOnly'
+  | 'alertAction'
+  | 'readOnlyReadinessProbe'
+  | 'preflightSkippableTouchMutation';
+
+export const RUNNER_COMMAND_TRAIT_MANIFEST = {
+  tap: 'preflightSkippableTouchMutation',
+  mouseClick: 'default',
+  longPress: 'preflightSkippableTouchMutation',
+  drag: 'preflightSkippableTouchMutation',
+  remotePress: 'default',
+  type: 'default',
+  swipe: 'preflightSkippableTouchMutation',
+  scroll: 'preflightSkippableTouchMutation',
+  desktopScroll: 'preflightSkippableTouchMutation',
+  findText: 'readOnly',
+  querySelector: 'readOnly',
+  readText: 'readOnly',
+  snapshot: 'readOnly',
+  screenshot: 'readOnly',
+  back: 'default',
+  backInApp: 'default',
+  backSystem: 'default',
+  home: 'default',
+  rotate: 'default',
+  gesture: 'preflightSkippableTouchMutation',
+  gestureViewport: 'readOnly',
+  appSwitcher: 'default',
+  actionButton: 'default',
+  keyboardDismiss: 'default',
+  keyboardReturn: 'default',
+  alert: 'alertAction',
+  sequence: 'preflightSkippableTouchMutation',
+  recordStart: 'default',
+  recordStop: 'default',
+  status: 'readOnlyReadinessProbe',
+  uptime: 'readOnlyReadinessProbe',
+  activate: 'readinessPreflightExemptMutation',
+  terminate: 'readinessPreflightExemptMutation',
+  targetReset: 'readinessPreflightExemptMutation',
+  shutdown: 'default',
+} as const satisfies Record<RunnerCommand['command'], RunnerCommandTraitClass>;
 
 export type RunnerCommandTraits = Readonly<{
   readOnly: boolean;
diff --git a/packages/platform-apple/src/runner/runner-contract.ts b/packages/platform-apple/src/runner/runner-contract.ts
index aabcd91638..c4f143f648 100644
--- a/packages/platform-apple/src/runner/runner-contract.ts
+++ b/packages/platform-apple/src/runner/runner-contract.ts
@@ -1,11 +1,4 @@
-import {
-  AppError,
-  createRequestCanceledError,
-  isRequestCanceledDetails,
-  toAppErrorCode,
-  type AppErrorCode,
-  type AppErrorDetails,
-} from '@agent-device/kernel/errors';
+import { AppError, createRequestCanceledError, toAppErrorCode } from '@agent-device/kernel/errors';
 import crypto from 'node:crypto';
 import { ALERT_NOT_FOUND_RUNNER_CODE } from '@agent-device/contracts/alert-contract';
 import type { DeviceRotation } from '@agent-device/contracts/device';
@@ -14,21 +7,8 @@ import type { ClickButton } from '@agent-device/contracts/click-button';
 import type { ElementSelectorKey } from '@agent-device/contracts/interactor-types';
 import type { GesturePlan } from '@agent-device/contracts/gesture-plan-types';
 import type { ScrollDirection } from '@agent-device/contracts/scroll-gesture';
-import type { IosDeveloperDiskImageState, IosDeveloperModeState } from './host.ts';
 import type { ScrollReleaseBehavior } from '@agent-device/contracts/scroll-command';
-import {
-  getRequestSignal,
-  isRequestCanceled,
-  isCommandTimeoutError,
-  bootFailureHint,
-  classifyBootFailure,
-} from './host.ts';
-import type { BootFailureReason } from '@agent-device/provision-kit/boot-diagnostics';
-import type { RunnerSession } from './runner-session-types.ts';
-
-// What an early-exit error quotes of the runner's own log: enough for the boot-failure anchors
-// (signing, tunneld, device busy), bounded so a wedged xcodebuild cannot ship a megabyte in details.
-const RUNNER_EARLY_EXIT_LOG_TAIL_BYTES = 64 * 1024;
+import { getRequestSignal, isRequestCanceled } from './host.ts';
 
 /**
  * The runner's own code for "an earlier command exceeded the execution watchdog and its abandoned
@@ -36,7 +16,7 @@ const RUNNER_EARLY_EXIT_LOG_TAIL_BYTES = 64 * 1024;
  * threshold the runner escalates to `RUNNER_WEDGED` instead — so every host path must publish it
  * as retriable.
  */
-const RUNNER_BUSY_RUNNER_CODE = 'RUNNER_BUSY';
+export const RUNNER_BUSY_RUNNER_CODE = 'RUNNER_BUSY';
 
 /**
  * The runner's own code for the command that just tripped the execution watchdog: its main-thread
@@ -45,10 +25,7 @@ const RUNNER_BUSY_RUNNER_CODE = 'RUNNER_BUSY';
  * typed signal available before any refusal happens. Not retriable: the wait already elapsed and an
  * immediate retry would only meet `RUNNER_BUSY`.
  */
-const MAIN_THREAD_TIMEOUT_RUNNER_CODE = 'MAIN_THREAD_TIMEOUT';
-
-const RUNNER_CACHE_RECOVERY_HINT =
-  'If runner build products look stale or corrupted, run `pnpm clean:xcuitest` in a local checkout, or remove ~/.agent-device/apple-runner/derived, then retry.';
+export const MAIN_THREAD_TIMEOUT_RUNNER_CODE = 'MAIN_THREAD_TIMEOUT';
 
 export type RunnerCommand = {
   command:
@@ -166,527 +143,6 @@ export function resolveRunnerRequestSignal(options: {
   return AbortSignal.any([registeredSignal, options.signal]);
 }
 
-/**
- * Details evidence a rule requires beyond code and message. A predicate rather than a
- * fixed vocabulary because the useful evidence is a shape: a recorded deadline, a
- * preflight marker, a retriable flag. Every predicate below names one.
- */
-type RunnerErrorDetailsMatch = (details: AppErrorDetails) => boolean;
-
-type RunnerErrorMatch = {
-  /** Required `AppError.code`; absent = any AppError. */
-  code?: AppErrorCode;
-  /** Every entry must appear in the lowercased message. */
-  messageIncludesAll?: readonly string[];
-  /**
-   * Every entry must appear in the lowercased {@link runnerToolText}: our message plus the tool's
-   * own `stdout`/`stderr`. Nothing else in `details` is read, so the argv we were asked to run and
-   * the verdict this classifier already published can never carry a rule (#2680).
-   */
-  toolTextIncludesAll?: readonly string[];
-  /**
-   * Every entry must appear in the SAME line of the lowercased {@link runnerToolText} (#2688 review).
-   * {@link RunnerErrorMatch.toolTextIncludesAll} proves only that two phrases exist somewhere in a
-   * captured log, which is a weaker claim than one phrase qualifying the other: a note about the
-   * profile the build used, three lines above an unrelated expired-certificate warning, says nothing
-   * about the profile. A row whose evidence is a noun and its complaint asks for both on one line.
-   */
-  toolTextLineIncludesAll?: readonly string[];
-  /** Required details evidence beyond code/message. */
-  details?: RunnerErrorDetailsMatch;
-};
-
-const hasRetriableFlag: RunnerErrorDetailsMatch = (details) => details.retriable === true;
-/**
- * The host's own `DevToolsSecurity -status` read, published as typed details by the probe that
- * takes it. The build-failure rule below keys on this field and never on the probe's message, so
- * an error that merely says developer mode is disabled cannot be read as a host refusal (#2680).
- */
-const hasDevToolsSecurityStatus: RunnerErrorDetailsMatch = (details) =>
-  typeof details.devToolsSecurityStatus === 'string';
-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 && !isRequestCanceledDetails(details);
-
-type RunnerErrorVerdicts = {
-  /** isRetryableRunnerError: transport error worth a same-session resend. */
-  retryable?: boolean;
-  /** shouldRetryRunnerConnectError: connect loop may keep waiting for the runner. */
-  connectRetry?: boolean;
-  /** Session-fatal classification: invalidate the cached runner session with this reason. */
-  sessionFatalReason?: string;
-  /** Connect-shaped failure before the command was sent: restart the session and replay. */
-  restartBeforeSend?: boolean;
-  /** Readiness preflight gave up before the command was written: restart the session and replay. */
-  restartAfterReadinessPreflight?: boolean;
-  /** The runner never accepted a connection, so the restored artifact itself is suspect. */
-  artifactSuspect?: boolean;
-};
-
-/**
- * The two device-readiness members (#2683): what the iPhone itself reports through
- * `devicectl device info details`, not what another tool's output implies about it. They are listed
- * apart because they are the members {@link classifyRunnerStartupFailure} does NOT produce — no
- * xcodebuild or host-tool text establishes them, and the code that reads the device publishes them
- * with the hint beside it. The two reach the caller at different moments, which is the whole
- * asymmetry of #2683: a disabled Developer Mode toggle refuses the run up front, while an unavailable
- * developer disk image is published onto a build that named no cause of its own, because iOS 17+
- * mounts that image on demand during build and launch. A connect-stage failure always claims a cause
- * of its own (`IOS_RUNNER_CONNECT_TIMEOUT` unless a provisioning row matches first), so there the
- * image state travels only as `details.developerDiskImage`, and
- * `device_developer_disk_image_unavailable` is published only from the startup build catch.
- */
-export const RUNNER_DEVICE_READINESS_FAILURE_REASONS = [
-  'device_developer_mode_disabled',
-  'device_developer_disk_image_unavailable',
-] as const;
-
-/**
- * Why the Apple runner could not reach the point of serving a command (#2680). Published in
- * `details.reason` on the `COMMAND_FAILED` every one of these paths throws, so a caller branches
- * on the reason instead of matching prose; the hint that answers it travels with it in
- * {@link RUNNER_ERROR_RULES}.
- *
- * This is the vocabulary #2683 adds the device-readiness members to (Developer Mode and developer
- * disk image state read from the device itself), which is why it is keyed on startup rather than on
- * `xcodebuild`: an iPhone that refuses the runner for reasons other than signing stops the runner
- * before a build is ever the question.
- *
- * Placement: here beside the rules that produce it, not in `@agent-device/contracts`. Every member
- * names a verdict an Apple runner path reaches, while `contracts` carries shapes several surfaces
- * answer with (`InfrastructureBootFailureReason`, which both simulator and device boot use).
- * Nothing outside this package publishes or consumes this enum, and one declaration is the only way
- * a row and its reason cannot disagree.
- */
-export const RUNNER_STARTUP_FAILURE_REASONS = [
-  'bundle_identifier_already_registered',
-  'signing_no_development_team',
-  'signing_provisioning_profile_missing',
-  'signing_unspecified',
-  'devtools_security_developer_mode_disabled',
-  ...RUNNER_DEVICE_READINESS_FAILURE_REASONS,
-  'build_failed_unclassified',
-] as const;
-
-export type RunnerStartupFailureReason = (typeof RUNNER_STARTUP_FAILURE_REASONS)[number];
-
-/** The device-readiness subset, typed from the one list above. */
-export type RunnerDeviceReadinessFailureReason =
-  (typeof RUNNER_DEVICE_READINESS_FAILURE_REASONS)[number];
-
-/**
- * The reason a startup failure carries when no rule proves a cause. Its hint is deliberately the
- * cache-recovery advice rather than anything about signing: an unclassified build is not evidence of
- * a signing problem.
- */
-export const RUNNER_STARTUP_FAILURE_UNCLASSIFIED_REASON: RunnerStartupFailureReason =
-  'build_failed_unclassified';
-
-type RunnerErrorRule = {
-  /** Stable rule name for tests and diagnostics. */
-  reason: string;
-  match: RunnerErrorMatch;
-  verdicts: RunnerErrorVerdicts;
-  /**
-   * Set on the rules that also classify why the runner could not start (#2680). Rules like these
-   * define no recovery verdicts for a runner that never came up — there is no session to invalidate
-   * and nothing was sent to resend — so the axes stay empty and the row carries only reason plus
-   * hint. Several rows may name one reason (bundle-identifier registration fails in two shapes),
-   * and the classifier takes the first match, which is why specific rows precede generic ones.
-   */
-  buildFailure?: {
-    reason: RunnerStartupFailureReason;
-    hint: string;
-  };
-};
-
-/**
- * The advice the provisioning-profile rows share (#2688). Named once so the three rows that require a
- * different complaint cannot drift into three different fixes for one lever.
- */
-const PROFILE_UNUSABLE: RunnerErrorRule['buildFailure'] = {
-  reason: 'signing_provisioning_profile_missing',
-  hint: 'Install/select a valid iOS provisioning profile, or set AGENT_DEVICE_IOS_PROVISIONING_PROFILE.',
-};
-
-/**
- * The one declaration of runner error classes (#1631), mirroring
- * RUNNER_COMMAND_TRAIT_MANIFEST's role for commands: every recovery predicate
- * below derives from this table instead of keeping its own substring chain,
- * and since #2680 so does the one classification of startup failures — a row
- * carries recovery verdicts, a `buildFailure` reason and hint, or both.
- * Per axis, the FIRST matching rule that defines the axis wins — which is why
- * `flagged_retriable` precedes the denials (an explicitly retriable error
- * stays retriable whatever its message says), and `usbmux_device_unattached`
- * sits first (retrying cannot attach a cable, and its typed verdict carries
- * the recovery hint a generic connect failure would replace).
- */
-export const RUNNER_ERROR_RULES: readonly RunnerErrorRule[] = [
-  {
-    reason: 'usbmux_device_unattached',
-    match: { code: 'DEVICE_NOT_FOUND', details: hasUsbmuxDeviceUnattached },
-    verdicts: { connectRetry: false },
-  },
-  {
-    reason: 'flagged_retriable',
-    match: { code: 'COMMAND_FAILED', details: hasRetriableFlag },
-    verdicts: { retryable: true, connectRetry: true },
-  },
-  {
-    // Says `artifactSuspect: false` on purpose: its message also reads as a refused
-    // connection, and a boot that cannot compile is not cured by wiping derived data.
-    reason: 'xcodebuild_exited_early',
-    match: { code: 'COMMAND_FAILED', messageIncludesAll: ['xcodebuild exited early'] },
-    verdicts: { retryable: false, connectRetry: false, artifactSuspect: false },
-  },
-  {
-    // A device still mid-attachment is not a runner we can talk to yet, and waiting on
-    // it inside this request is what the caller's own retry is for.
-    reason: 'device_busy_connecting',
-    match: { code: 'COMMAND_FAILED', messageIncludesAll: ['device is busy', 'connecting'] },
-    verdicts: { retryable: false, connectRetry: false },
-  },
-  {
-    // The marker is the whole fact: the preflight gave up before the command was written, so
-    // replaying it cannot duplicate anything. It is asked for alone because the preflight fails in
-    // whatever shape the connect loop ended with — a refusal, an exhausted probe, a killed
-    // fallback — and a rule that also required a recorded budget would fire on only some of them.
-    reason: 'runner_readiness_preflight_failed',
-    match: { code: 'COMMAND_FAILED', details: hasReadinessPreflightFailure },
-    verdicts: { restartAfterReadinessPreflight: true },
-  },
-  {
-    reason: 'runner_connect_refused',
-    match: { code: 'COMMAND_FAILED', messageIncludesAll: ['runner did not accept connection'] },
-    verdicts: {
-      retryable: true,
-      connectRetry: true,
-      restartBeforeSend: true,
-      artifactSuspect: true,
-    },
-  },
-  {
-    // Every endpoint answered and none of them had a runner: with a restored artifact
-    // in hand, that artifact is the common cause.
-    reason: 'runner_endpoint_probe_exhausted',
-    match: { code: 'COMMAND_FAILED', messageIncludesAll: ['runner endpoint probe failed'] },
-    verdicts: { artifactSuspect: true },
-  },
-  {
-    reason: 'fetch_failed',
-    match: { code: 'COMMAND_FAILED', messageIncludesAll: ['fetch failed'] },
-    verdicts: { retryable: true, connectRetry: true },
-  },
-  {
-    reason: 'econnrefused',
-    match: { code: 'COMMAND_FAILED', messageIncludesAll: ['econnrefused'] },
-    verdicts: { retryable: true, connectRetry: true },
-  },
-  {
-    reason: 'socket_hang_up',
-    match: { code: 'COMMAND_FAILED', messageIncludesAll: ['socket hang up'] },
-    verdicts: { retryable: true, connectRetry: true },
-  },
-  {
-    reason: 'ax_snapshot_failure',
-    match: { code: 'IOS_AX_SNAPSHOT_FAILED' },
-    verdicts: { sessionFatalReason: 'ax_snapshot_failure' },
-  },
-  {
-    reason: 'xctest_recorded_failure',
-    match: { code: 'XCTEST_RECORDED_FAILURE' },
-    verdicts: { sessionFatalReason: 'xctest_recorded_failure' },
-  },
-  {
-    // The runner reported its main thread stuck in abandoned work past the wedge
-    // threshold (#1105): only a restart cures it. The per-request recycle budget
-    // still bounds how many boots one request pays for.
-    reason: 'runner_main_thread_wedged',
-    match: { code: 'RUNNER_WEDGED' },
-    verdicts: { sessionFatalReason: 'runner_main_thread_wedged' },
-  },
-  // ── Startup classification (#2680) ───────────────────────────────────────────────────────────
-  // These rows answer "why could the runner not get here at all": `xcodebuild build-for-testing`
-  // refusing, and the host preflight that runs before it. They carry a reason and a hint for the
-  // caller and no recovery verdicts, because there is no session to invalidate and nothing was sent
-  // to resend. Specific rows precede generic ones: the classifier takes the first match.
-  //
-  // Why these rows are text matchers while the rows above key on a code or a typed field:
-  // `runnerToolText` reads xcodebuild's own prose because that prose is the only publication these
-  // failures have — there is no code and no typed field to key on. Its haystack is deliberately
-  // narrow: our message plus the tool's stdout/stderr, never the whole details bag, which also
-  // holds the argv we were asked to run (so a caller's own PROVISIONING_PROFILE_SPECIFIER=… would
-  // otherwise name a signing cause for an unrelated compile error) and the reason and hint this
-  // classifier just published (so a re-wrapped failure would match itself). The DevToolsSecurity
-  // row is the other half: where a probe of ours publishes a typed fact, the row keys on that fact
-  // alone. `resolveRunnerEarlyExitHint` stays outside this table for the same reason it stays a hint
-  // builder — it classifies a runner that DID build and then exited early, whose reason axis is the
-  // `BootFailureReason` `classifyBootFailure` already returns, and a build that never produced a
-  // binary has no boot to classify.
-  {
-    reason: 'bundle_identifier_registration_failed',
-    match: { toolTextIncludesAll: ['failed registering bundle identifier'] },
-    verdicts: {},
-    buildFailure: {
-      reason: 'bundle_identifier_already_registered',
-      hint: 'Set AGENT_DEVICE_IOS_BUNDLE_ID to a unique reverse-DNS value (for example, com.yourname.agentdevice.runner), then retry.',
-    },
-  },
-  {
-    // The identifier and its availability have to meet in one line: `App Identifier` and `not
-    // available` are two phrases a captured log can carry for reasons that have nothing to do with
-    // each other, which is the same hazard the profile rows just gave up (#2688 review).
-    reason: 'bundle_identifier_unavailable',
-    match: { toolTextLineIncludesAll: ['app identifier', 'not available'] },
-    verdicts: {},
-    buildFailure: {
-      reason: 'bundle_identifier_already_registered',
-      hint: 'Set AGENT_DEVICE_IOS_BUNDLE_ID to a unique reverse-DNS value (for example, com.yourname.agentdevice.runner), then retry.',
-    },
-  },
-  {
-    reason: 'signing_requires_development_team',
-    match: { toolTextIncludesAll: ['requires a development team'] },
-    verdicts: {},
-    buildFailure: {
-      reason: 'signing_no_development_team',
-      hint: 'Configure signing in Xcode or set AGENT_DEVICE_IOS_TEAM_ID for physical-device runs.',
-    },
-  },
-  {
-    // "conflicting provisioning settings" names a profile while saying the automatic and manual
-    // settings disagree, so without this row the profile row below would send the reader to install
-    // a profile for a problem that is a settings mismatch. No reason is claimed for it: nothing has
-    // captured this failure or proved which lever clears it, and advice the reader cannot follow is
-    // worse than the cache-recovery advice the unclassified path already gives (#2680).
-    reason: 'conflicting_provisioning_settings_unproven',
-    match: { toolTextIncludesAll: ['conflicting provisioning settings'] },
-    verdicts: {},
-    buildFailure: {
-      reason: RUNNER_STARTUP_FAILURE_UNCLASSIFIED_REASON,
-      hint: RUNNER_CACHE_RECOVERY_HINT,
-    },
-  },
-  {
-    // "No profiles for 'com.example' were found" names the bundle id and the absence in one sentence,
-    // so the phrase alone is the complaint and needs no second phrase to qualify it.
-    reason: 'signing_no_profiles_for_bundle_id',
-    match: { toolTextIncludesAll: ['no profiles for'] },
-    verdicts: {},
-    buildFailure: PROFILE_UNUSABLE,
-  },
-  // A profile named in the tool's output is only evidence when the output also says what is wrong with
-  // that profile, in the same line (#2688 review). One bare `provisioning profile` substring was the
-  // shipped sniffer's trigger, and it is a phrase a failing build can print while talking about
-  // something else: the codesign command line, a build-settings dump, a note about the profile that was
-  // used. Requiring a second phrase somewhere in the same log is no better — a note about the profile
-  // used above an unrelated `has expired` certificate warning would then name the profile. Each row
-  // below therefore asks for the profile and Xcode's complaint about it on one line, and a failure that
-  // merely mentions a profile stays unclassified rather than being sent to install one it already has.
-  {
-    // Xcode's own signing-error domain beside the profile it rejected: the machine-readable half of its
-    // `IDEProvisioningErrorDomain` diagnostics, which accompanies the prose rather than replacing it.
-    reason: 'signing_provisioning_profile_xcode_error',
-    match: { toolTextLineIncludesAll: ['provisioning profile', 'ideprovisioningerrordomain'] },
-    verdicts: {},
-    buildFailure: PROFILE_UNUSABLE,
-  },
-  {
-    // "Provisioning profile \"X\" doesn't include application identifier ..." — the profile that is
-    // installed but does not cover this app or capability.
-    reason: 'signing_provisioning_profile_does_not_cover',
-    match: { toolTextLineIncludesAll: ['provisioning profile', "doesn't include"] },
-    verdicts: {},
-    buildFailure: PROFILE_UNUSABLE,
-  },
-  {
-    // "Provisioning profile \"X\" has expired" — installing it again is not the fix; replacing it is,
-    // which is what the hint's "valid" is for. The full phrase, on the profile's own line: `expired`
-    // alone is what an expired certificate, a stale session, or a revoked key writes (#2688 review).
-    reason: 'signing_provisioning_profile_expired',
-    match: { toolTextLineIncludesAll: ['provisioning profile', 'has expired'] },
-    verdicts: {},
-    buildFailure: PROFILE_UNUSABLE,
-  },
-  {
-    // Signing is involved but nothing above names how: the reason says signing and the hint stays
-    // the generic one it has always carried, rather than naming a misconfiguration no rule proved.
-    reason: 'signing_unspecified',
-    match: { toolTextIncludesAll: ['code signing'] },
-    verdicts: {},
-    buildFailure: {
-      reason: 'signing_unspecified',
-      hint: 'Enable Automatic Signing in Xcode or provide AGENT_DEVICE_IOS_TEAM_ID and optional AGENT_DEVICE_IOS_SIGNING_IDENTITY.',
-    },
-  },
-  {
-    reason: 'devtools_security_refused',
-    match: { code: 'COMMAND_FAILED', details: hasDevToolsSecurityStatus },
-    verdicts: {},
-    buildFailure: {
-      reason: 'devtools_security_developer_mode_disabled',
-      hint: 'Run `sudo DevToolsSecurity -enable`, then retry the iOS runner. UI test runners start suspended until Xcode/testmanagerd can attach.',
-    },
-  },
-];
-
-function matchesRunnerErrorRule(error: AppError, match: RunnerErrorMatch): boolean {
-  if (match.code !== undefined && error.code !== match.code) return false;
-  if (!matchesRunnerErrorDetails(error, match.details)) return false;
-  if (!matchesRunnerToolText(error, match.toolTextIncludesAll)) return false;
-  if (!matchesRunnerToolTextLine(error, match.toolTextLineIncludesAll)) return false;
-  return matchesRunnerErrorMessage(error, match.messageIncludesAll);
-}
-
-function matchesRunnerErrorDetails(error: AppError, details: RunnerErrorMatch['details']): boolean {
-  if (details === undefined) return true;
-  return details((error.details ?? {}) as AppErrorDetails);
-}
-
-function matchesRunnerErrorMessage(error: AppError, parts: readonly string[] | undefined): boolean {
-  if (!parts) return true;
-  const message = `${error.message ?? ''}`.toLowerCase();
-  return parts.every((part) => message.includes(part));
-}
-
-/**
- * The only text a startup rule may read: our message plus the tool's own `stdout` and `stderr`
- * (#2680). The rest of `details` is deliberately out of reach — `cmd`/`args` describe what we were
- * asked to run, and `reason`/`hint` are this classifier's own output, which a re-wrapped failure
- * would otherwise find and match again.
- */
-function runnerToolText(error: AppError): string {
-  const details = error.details ?? {};
-  return [error.message, details.stdout, details.stderr]
-    .filter((part): part is string => typeof part === 'string')
-    .join('\n')
-    .toLowerCase();
-}
-
-function matchesRunnerToolText(error: AppError, parts: readonly string[] | undefined): boolean {
-  if (!parts) return true;
-  const text = runnerToolText(error);
-  return parts.every((part) => text.includes(part));
-}
-
-/**
- * The same haystack read one line at a time, so a row can require its phrases to be in one sentence
- * rather than merely in one file (#2688 review). A captured build log is thousands of lines long, and
- * two unrelated lines can hold any pair of words.
- */
-function matchesRunnerToolTextLine(error: AppError, parts: readonly string[] | undefined): boolean {
-  if (!parts) return true;
-  return runnerToolText(error)
-    .split('\n')
-    .some((line) => parts.every((part) => line.includes(part)));
-}
-
-function runnerErrorVerdict<Axis extends keyof RunnerErrorVerdicts>(
-  error: unknown,
-  axis: Axis,
-): RunnerErrorVerdicts[Axis] | undefined {
-  if (!(error instanceof AppError)) return undefined;
-  for (const rule of RUNNER_ERROR_RULES) {
-    if (rule.verdicts[axis] === undefined) continue;
-    if (matchesRunnerErrorRule(error, rule.match)) return rule.verdicts[axis];
-  }
-  return undefined;
-}
-
-export function isRetryableRunnerError(err: unknown): boolean {
-  if (!(err instanceof AppError)) return false;
-  if (err.code !== 'COMMAND_FAILED') return false;
-  return runnerErrorVerdict(err, 'retryable') ?? false;
-}
-
-/**
- * True when the runner reported its main thread occupied by watchdog-abandoned XCTest work, either
- * as a fast refusal of this command (`RUNNER_BUSY`) or as the timeout the stalling command itself
- * returns (`MAIN_THREAD_TIMEOUT`) (#2552). Both are diagnostic-only on the wire (`COMMAND_FAILED` +
- * `details.runnerErrorCode`), so family policy reads the typed detail rather than the message.
- */
-export function isRunnerMainThreadOccupiedError(error: unknown): boolean {
-  if (!(error instanceof AppError)) return false;
-  const runnerErrorCode = error.details?.runnerErrorCode;
-  return (
-    runnerErrorCode === RUNNER_BUSY_RUNNER_CODE ||
-    runnerErrorCode === MAIN_THREAD_TIMEOUT_RUNNER_CODE
-  );
-}
-
-/**
- * True when usbmuxd answered and the device is simply not attached by cable.
- * A CoreDevice-backed device falls back to its network tunnel; an XCTest-backed
- * device has no second route, so this verdict is terminal rather than retryable.
- *
- * Lives here rather than beside the usbmux transport because the retry policy
- * below needs it, and that transport already depends on this module.
- */
-export function isUsbmuxDeviceUnattachedError(error: unknown): boolean {
-  if (!(error instanceof AppError) || error.code !== 'DEVICE_NOT_FOUND') return false;
-  return hasUsbmuxDeviceUnattached((error.details ?? {}) as AppErrorDetails);
-}
-
-/**
- * Default is true and not false: the common failure while the runner boots is an error
- * no rule describes, and giving up on it would fail a command that the connect loop was
- * about to succeed. A rule says false only when waiting cannot help.
- */
-export function shouldRetryRunnerConnectError(error: unknown): boolean {
-  return runnerErrorVerdict(error, 'connectRetry') ?? true;
-}
-
-/**
- * The readiness preflight gave up, so the runner never saw the command: restarting the session and
- * replaying is both safe and the only way out. The marker carries the rule; the message does not.
- */
-export function shouldRestartRunnerAfterReadinessPreflight(error: unknown): boolean {
-  return runnerErrorVerdict(error, 'restartAfterReadinessPreflight') ?? false;
-}
-
-/**
- * The runner refused or never answered on every route, which is what a restored artifact
- * that cannot boot looks like. Deliberately narrow: the recovery it authorises is a clean
- * `xcodebuild` rebuild, so a slow boot, a busy device or a transport failure partway
- * through a command must not pay that price.
- */
-export function shouldRebuildCachedRunnerArtifact(error: unknown): boolean {
-  return runnerErrorVerdict(error, 'artifactSuspect') ?? false;
-}
-
-/**
- * Session-fatal classification for a runner response error: when defined, the
- * cached runner session must be invalidated with this reason instead of being
- * reused (see ADR 0005 and docs/agents/selector-capture.md's
- * runnerFatal rule).
- */
-export function resolveRunnerFatalErrorReason(error: unknown): string | undefined {
-  return runnerErrorVerdict(error, 'sessionFatalReason');
-}
-
-/**
- * A connect-shaped failure that surfaced before the command was sent: restart
- * the runner session and replay the command, rather than probing a runner
- * that never accepted the connection. Composed with the connect-retry axis so
- * a terminal connect verdict (cable unattached, xcodebuild exited early)
- * still refuses the restart. Matching is table-driven and therefore
- * case-insensitive, unlike the raw-message check it replaced; the message is
- * our own transport literal, so no real error changes class.
- */
-export function shouldRestartRunnerBeforeCommandSend(error: unknown): boolean {
-  return (
-    (runnerErrorVerdict(error, 'restartBeforeSend') ?? false) &&
-    shouldRetryRunnerConnectError(error)
-  );
-}
-
 /**
  * The code the XCTest runner answers with when it declines to place a scroll gesture under the
  * on-screen keyboard (#2500). It is the runner's own vocabulary, so it is declared here beside the
@@ -813,231 +269,6 @@ function readRunnerErrorCode(rawCode: unknown): string | undefined {
   return typeof rawCode === 'string' && rawCode.trim().length > 0 ? rawCode.trim() : undefined;
 }
 
-export function resolveRunnerEarlyExitHint(
-  message: string,
-  stdout: string,
-  stderr: string,
-  reason?: BootFailureReason,
-): string {
-  const haystack = `${message}\n${stdout}\n${stderr}`.toLowerCase();
-  if (haystack.includes('device is busy') && haystack.includes('connecting')) {
-    return 'Target iOS device is still connecting. Keep it unlocked, wait for device trust/connection to settle, then retry.';
-  }
-  const classified = reason ?? 'IOS_RUNNER_CONNECT_TIMEOUT';
-  // Clearing cached build products cannot put a device into a provisioning
-  // profile, so that recovery advice is withheld where it would only add noise
-  // to an already actionable instruction.
-  if (classified === 'IOS_RUNNER_DEVICE_NOT_PROVISIONED') return bootFailureHint(classified);
-  return `${bootFailureHint(classified)} ${RUNNER_CACHE_RECOVERY_HINT}`;
-}
-
-export function buildRunnerConnectError(params: {
-  port: number;
-  endpoints: string[];
-  logPath?: string;
-  lastError: unknown;
-  deviceStates?: IosRunnerDeviceStates;
-}): AppError {
-  const { port, endpoints, logPath, lastError, deviceStates } = params;
-  const message = 'Runner did not accept connection';
-  const error = new AppError('COMMAND_FAILED', message, {
-    port,
-    endpoints,
-    logPath,
-    lastError: lastError ? String(lastError) : undefined,
-    reason: classifyBootFailure({
-      error: lastError,
-      message,
-      context: { platform: 'ios', phase: 'connect' },
-    }),
-    hint: bootFailureHint('IOS_RUNNER_CONNECT_TIMEOUT'),
-  });
-  // The other way the connect stage gives up: `xcodebuild` is still alive at the deadline. It gets
-  // the same enrichment as the early exit below (#2683).
-  return enrichRunnerStartupFailureWithDeviceStates(error, deviceStates) as AppError;
-}
-
-export async function buildRunnerEarlyExitError(params: {
-  session: RunnerSession;
-  port: number;
-  logPath?: string;
-}): Promise<AppError> {
-  const { session, port, logPath } = params;
-  const result = await session.testPromise;
-  const message = 'Runner did not accept connection (xcodebuild exited early)';
-  // The runner writes its own output file, so the exec result holds nothing for a file-backed
-  // child; that file is what an early exit can quote (#2681).
-  const output = session.readLogTail?.(RUNNER_EARLY_EXIT_LOG_TAIL_BYTES) ?? '';
-  const reason = classifyBootFailure({
-    message,
-    stdout: output,
-    stderr: output,
-    context: { platform: 'ios', phase: 'connect' },
-  });
-  // exec-guard-allow: xcodebuild can exit 0 and still count as an early exit;
-  // the trio is nested tool context under `xcodebuild`, classified into
-  // `reason`/`hint` above — not a process-exit wrap.
-  const error = new AppError('COMMAND_FAILED', message, {
-    port,
-    // The quote always comes from the runner's own file, so that is the file the error has to name;
-    // pointing at the request's log would advertise a file that does not contain what is quoted (#2681).
-    logPath: session.runnerLogPath ?? logPath,
-    xcodebuild: {
-      exitCode: result.exitCode,
-      // One merged file since #2681: the tail is reported under `stderr`, which is where readers
-      // already look, next to the file it came from.
-      stderr: output,
-    },
-    reason,
-    hint: resolveRunnerEarlyExitHint(message, output, output, reason),
-  });
-  // The build catch is not the only way a runner stops before serving a command. A locked phone lets
-  // the build finish and kills `xcodebuild test-without-building` instead, so nothing reaches that
-  // catch and the disk-image state read before the build would be dropped. Same enrichment, applied
-  // to the failure this path actually produces (#2683).
-  return enrichRunnerStartupFailureWithDeviceStates(error, session.startupDeviceStates) as AppError;
-}
-
-/**
- * The one classifier for "the runner did not reach the point of serving a command" (#2680). Every
- * path that stops the runner before it answers a request routes its failure through here, so the
- * reason a caller sees is produced by the same rows that produce the hint beside it — a reason is
- * never inferred from a hint's wording, and an unproven cause is never claimed.
- *
- * Callers publish the pair as `details.reason` plus the top-level hint on a `COMMAND_FAILED`; the
- * code is `COMMAND_FAILED` for every reason, so the reason is the assertion.
- */
-export function classifyRunnerStartupFailure(error: unknown): RunnerStartupClassification {
-  if (error instanceof AppError) {
-    for (const rule of RUNNER_ERROR_RULES) {
-      const buildFailure = rule.buildFailure;
-      if (!buildFailure) continue;
-      if (matchesRunnerErrorRule(error, rule.match)) {
-        return { reason: buildFailure.reason, hint: buildFailure.hint, matched: true };
-      }
-    }
-  }
-  return {
-    reason: RUNNER_STARTUP_FAILURE_UNCLASSIFIED_REASON,
-    hint: RUNNER_CACHE_RECOVERY_HINT,
-    matched: false,
-  };
-}
-
-/**
- * The verdict, the advice beside it, and whether a row reached either (#2690 review). `matched` is
- * half the answer rather than an implementation detail: {@link RUNNER_STARTUP_FAILURE_UNCLASSIFIED_REASON}
- * is also what a row that deliberately claims no cause publishes, so reading the reason alone cannot
- * tell "nothing spoke" from "a row spoke and declined to name a cause".
- */
-export type RunnerStartupClassification = Readonly<{
-  reason: RunnerStartupFailureReason;
-  hint: string;
-  /**
-   * False only when no rule row matched at all. The catch that publishes this verdict carries it on
-   * `details.startupRuleMatched`, which is the half a caller cannot recover from the reason alone.
-   */
-  matched: boolean;
-}>;
-
-/**
- * What the startup carries forward from the device so a later failure can say what the phone said
- * (#2683). The one thing that stops a run up front is a disabled Developer Mode toggle, which no
- * later step can change; everything else the device reports is only worth publishing beside the
- * failure it explains.
- */
-export type IosRunnerDeviceStates = Readonly<{
-  developerMode: IosDeveloperModeState;
-  developerDiskImage: IosDeveloperDiskImageState;
-  /** The remedy for an unavailable image, worded by `core/devicectl.ts` and read, not rewritten. */
-  developerDiskImageHint: string;
-}>;
-
-/**
- * The device's turn on a startup failure (#2683, #2690 review), applied by the session's startup
- * catch so it reaches every path that stops a runner before it serves a command: a cold build, a warm
- * derived cache that fails at install, or an external xctestrun that never launches. The phone's own
- * state rides along as `details.developerDiskImage` on all of them, because it is a fact whoever is
- * reading this failure wants.
- *
- * It becomes the *reason* only when the failure carries no reason of its own and no rule row matched.
- * `devicectl` reports the image only while the tunnel is up and the phone is booted, so an
- * unavailable reading that reached here is a fact about the device rather than a snapshot of a sleeping
- * phone — but a failure that already named a cause, or that a row looked at and declined to name one
- * for, outranks a state that may have been cleared before the failure was written down. And a command
- * the host killed at its own deadline says nothing about the device either: the build that never
- * finished cannot have been refused for want of developer support, so a timeout outranks a state too.
- * An error that is not an `AppError` comes back untouched: a cancellation and a foreign failure keep
- * their identity.
- */
-export function enrichRunnerStartupFailureWithDeviceStates(
-  error: unknown,
-  states: IosRunnerDeviceStates | undefined,
-): unknown {
-  if (!states || !(error instanceof AppError)) return error;
-  const speaks =
-    claimedStartupFailureReason(error) === undefined &&
-    states.developerDiskImage === 'unavailable' &&
-    !startupFailureRuleMatched(error) &&
-    !startupFailureHostDeadlineHit(error);
-  return new AppError(
-    error.code,
-    error.message,
-    {
-      ...(error.details ?? {}),
-      ...(speaks
-        ? {
-            reason: 'device_developer_disk_image_unavailable',
-            hint: states.developerDiskImageHint,
-          }
-        : {}),
-      developerDiskImage: states.developerDiskImage,
-    },
-    error.cause,
-  );
-}
-
-/**
- * The reason a startup failure already carries, discounting the placeholder the classifier publishes
- * when nothing proved a cause. Without this discount the build catch's own
- * `build_failed_unclassified` would read as a claimed cause and silence the device everywhere.
- */
-function claimedStartupFailureReason(error: AppError): RunnerStartupFailureReason | undefined {
-  const reason = error.details?.reason;
-  if (typeof reason !== 'string' || reason === RUNNER_STARTUP_FAILURE_UNCLASSIFIED_REASON) {
-    return undefined;
-  }
-  return reason as RunnerStartupFailureReason;
-}
-
-/**
- * Whether the host's own execution deadline ended the command behind this failure. A build the host
- * killed at `buildTimeoutMs` reaches the startup catch as `build_failed_unclassified` with nothing
- * matched, and an unavailable image sitting on the device would then be named as the cause of a build
- * that was simply too slow (#2690 review). A catch that published a classification carries the answer
- * in `details.startupHostDeadlineHit` for the same reason it carries `startupRuleMatched`: its wrapper
- * buries the tool error a level too deep to inspect. A failure that never passed through such a catch
- * is read here, where the exec's own `timeoutMs` detail is still in reach.
- */
-function startupFailureHostDeadlineHit(error: AppError): boolean {
-  const published = error.details?.startupHostDeadlineHit;
-  if (typeof published === 'boolean') return published;
-  return isCommandTimeoutError(error);
-}
-
-/**
- * Whether a rule row already reached this failure. A catch that published a classification carries its
- * own answer in `details.startupRuleMatched`, because its wrapper keeps the tool's text one level too
- * deep for the rows to read again — re-classifying the wrapper would report "nothing matched" for a
- * failure whose cause a row had just declined to name (#2690 review). A failure that never passed
- * through such a catch is classified here, which is the same answer its own publisher would have given.
- */
-function startupFailureRuleMatched(error: AppError): boolean {
-  const published = error.details?.startupRuleMatched;
-  if (typeof published === 'boolean') return published;
-  return classifyRunnerStartupFailure(error).matched;
-}
-
 export function withRunnerCommandId(command: RunnerCommand): RunnerCommand {
   if (command.command === 'status') return command;
   if (command.commandId?.trim()) return command;
diff --git a/packages/platform-apple/src/runner/runner-dev-tools-security.ts b/packages/platform-apple/src/runner/runner-dev-tools-security.ts
index f3ce67e73b..1ba3167559 100644
--- a/packages/platform-apple/src/runner/runner-dev-tools-security.ts
+++ b/packages/platform-apple/src/runner/runner-dev-tools-security.ts
@@ -1,7 +1,7 @@
 import { AppError } from '@agent-device/kernel/errors';
 import { isIosFamily, type DeviceInfo } from '@agent-device/kernel/device';
 import { runAppleToolCommand } from './host.ts';
-import { classifyRunnerStartupFailure } from './runner-contract.ts';
+import { classifyRunnerStartupFailure } from './runner-error-classification.ts';
 
 const DEV_TOOLS_SECURITY_TIMEOUT_MS = 2_000;
 
diff --git a/packages/platform-apple/src/runner/runner-device-readiness.ts b/packages/platform-apple/src/runner/runner-device-readiness.ts
index b887d243f6..e38e02eef7 100644
--- a/packages/platform-apple/src/runner/runner-device-readiness.ts
+++ b/packages/platform-apple/src/runner/runner-device-readiness.ts
@@ -4,7 +4,7 @@ import { resolveIosPhysicalDeviceControl, type IosDeviceReadiness } from './host
 import {
   type IosRunnerDeviceStates,
   type RunnerDeviceReadinessFailureReason,
-} from './runner-contract.ts';
+} from './runner-error-classification.ts';
 
 const DEVICE_MODE_OFF_MESSAGE = 'The iOS device reports that Developer Mode is turned off';
 
diff --git a/packages/platform-apple/src/runner/runner-error-classification.ts b/packages/platform-apple/src/runner/runner-error-classification.ts
new file mode 100644
index 0000000000..bbc97a3f7e
--- /dev/null
+++ b/packages/platform-apple/src/runner/runner-error-classification.ts
@@ -0,0 +1,676 @@
+import {
+  AppError,
+  isRequestCanceledDetails,
+  type AppErrorCode,
+  type AppErrorDetails,
+} from '@agent-device/kernel/errors';
+import {
+  isCommandTimeoutError,
+  type IosDeveloperDiskImageState,
+  type IosDeveloperModeState,
+} from './host.ts';
+import { MAIN_THREAD_TIMEOUT_RUNNER_CODE, RUNNER_BUSY_RUNNER_CODE } from './runner-contract.ts';
+
+export const RUNNER_CACHE_RECOVERY_HINT =
+  'If runner build products look stale or corrupted, run `pnpm clean:xcuitest` in a local checkout, or remove ~/.agent-device/apple-runner/derived, then retry.';
+
+/**
+ * Details evidence a rule requires beyond code and message. A predicate rather than a
+ * fixed vocabulary because the useful evidence is a shape: a recorded deadline, a
+ * preflight marker, a retriable flag. Every predicate below names one.
+ */
+type RunnerErrorDetailsMatch = (details: AppErrorDetails) => boolean;
+
+type RunnerErrorMatch = {
+  /** Required `AppError.code`; absent = any AppError. */
+  code?: AppErrorCode;
+  /** Every entry must appear in the lowercased message. */
+  messageIncludesAll?: readonly string[];
+  /**
+   * Every entry must appear in the lowercased {@link runnerToolText}: our message plus the tool's
+   * own `stdout`/`stderr`. Nothing else in `details` is read, so the argv we were asked to run and
+   * the verdict this classifier already published can never carry a rule (#2680).
+   */
+  toolTextIncludesAll?: readonly string[];
+  /**
+   * Every entry must appear in the SAME line of the lowercased {@link runnerToolText} (#2688 review).
+   * {@link RunnerErrorMatch.toolTextIncludesAll} proves only that two phrases exist somewhere in a
+   * captured log, which is a weaker claim than one phrase qualifying the other: a note about the
+   * profile the build used, three lines above an unrelated expired-certificate warning, says nothing
+   * about the profile. A row whose evidence is a noun and its complaint asks for both on one line.
+   */
+  toolTextLineIncludesAll?: readonly string[];
+  /** Required details evidence beyond code/message. */
+  details?: RunnerErrorDetailsMatch;
+};
+
+const hasRetriableFlag: RunnerErrorDetailsMatch = (details) => details.retriable === true;
+/**
+ * The host's own `DevToolsSecurity -status` read, published as typed details by the probe that
+ * takes it. The build-failure rule below keys on this field and never on the probe's message, so
+ * an error that merely says developer mode is disabled cannot be read as a host refusal (#2680).
+ */
+const hasDevToolsSecurityStatus: RunnerErrorDetailsMatch = (details) =>
+  typeof details.devToolsSecurityStatus === 'string';
+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 && !isRequestCanceledDetails(details);
+
+type RunnerErrorVerdicts = {
+  /** isRetryableRunnerError: transport error worth a same-session resend. */
+  retryable?: boolean;
+  /** shouldRetryRunnerConnectError: connect loop may keep waiting for the runner. */
+  connectRetry?: boolean;
+  /** Session-fatal classification: invalidate the cached runner session with this reason. */
+  sessionFatalReason?: string;
+  /** Connect-shaped failure before the command was sent: restart the session and replay. */
+  restartBeforeSend?: boolean;
+  /** Readiness preflight gave up before the command was written: restart the session and replay. */
+  restartAfterReadinessPreflight?: boolean;
+  /** The runner never accepted a connection, so the restored artifact itself is suspect. */
+  artifactSuspect?: boolean;
+};
+
+/**
+ * The two device-readiness members (#2683): what the iPhone itself reports through
+ * `devicectl device info details`, not what another tool's output implies about it. They are listed
+ * apart because they are the members {@link classifyRunnerStartupFailure} does NOT produce — no
+ * xcodebuild or host-tool text establishes them, and the code that reads the device publishes them
+ * with the hint beside it. The two reach the caller at different moments, which is the whole
+ * asymmetry of #2683: a disabled Developer Mode toggle refuses the run up front, while an unavailable
+ * developer disk image is published onto a build that named no cause of its own, because iOS 17+
+ * mounts that image on demand during build and launch. A connect-stage failure always claims a cause
+ * of its own (`IOS_RUNNER_CONNECT_TIMEOUT` unless a provisioning row matches first), so there the
+ * image state travels only as `details.developerDiskImage`, and
+ * `device_developer_disk_image_unavailable` is published only from the startup build catch.
+ */
+export const RUNNER_DEVICE_READINESS_FAILURE_REASONS = [
+  'device_developer_mode_disabled',
+  'device_developer_disk_image_unavailable',
+] as const;
+
+/**
+ * Why the Apple runner could not reach the point of serving a command (#2680). Published in
+ * `details.reason` on the `COMMAND_FAILED` every one of these paths throws, so a caller branches
+ * on the reason instead of matching prose; the hint that answers it travels with it in
+ * {@link RUNNER_ERROR_RULES}.
+ *
+ * This is the vocabulary #2683 adds the device-readiness members to (Developer Mode and developer
+ * disk image state read from the device itself), which is why it is keyed on startup rather than on
+ * `xcodebuild`: an iPhone that refuses the runner for reasons other than signing stops the runner
+ * before a build is ever the question.
+ *
+ * Placement: here beside the rules that produce it, not in `@agent-device/contracts`. Every member
+ * names a verdict an Apple runner path reaches, while `contracts` carries shapes several surfaces
+ * answer with (`InfrastructureBootFailureReason`, which both simulator and device boot use).
+ * Nothing outside this package publishes or consumes this enum, and one declaration is the only way
+ * a row and its reason cannot disagree.
+ */
+export const RUNNER_STARTUP_FAILURE_REASONS = [
+  'bundle_identifier_already_registered',
+  'signing_no_development_team',
+  'signing_provisioning_profile_missing',
+  'signing_unspecified',
+  'devtools_security_developer_mode_disabled',
+  ...RUNNER_DEVICE_READINESS_FAILURE_REASONS,
+  'build_failed_unclassified',
+] as const;
+
+export type RunnerStartupFailureReason = (typeof RUNNER_STARTUP_FAILURE_REASONS)[number];
+
+/** The device-readiness subset, typed from the one list above. */
+export type RunnerDeviceReadinessFailureReason =
+  (typeof RUNNER_DEVICE_READINESS_FAILURE_REASONS)[number];
+
+/**
+ * The reason a startup failure carries when no rule proves a cause. Its hint is deliberately the
+ * cache-recovery advice rather than anything about signing: an unclassified build is not evidence of
+ * a signing problem.
+ */
+export const RUNNER_STARTUP_FAILURE_UNCLASSIFIED_REASON: RunnerStartupFailureReason =
+  'build_failed_unclassified';
+
+type RunnerErrorRule = {
+  /** Stable rule name for tests and diagnostics. */
+  reason: string;
+  match: RunnerErrorMatch;
+  verdicts: RunnerErrorVerdicts;
+  /**
+   * Set on the rules that also classify why the runner could not start (#2680). Rules like these
+   * define no recovery verdicts for a runner that never came up — there is no session to invalidate
+   * and nothing was sent to resend — so the axes stay empty and the row carries only reason plus
+   * hint. Several rows may name one reason (bundle-identifier registration fails in two shapes),
+   * and the classifier takes the first match, which is why specific rows precede generic ones.
+   */
+  buildFailure?: {
+    reason: RunnerStartupFailureReason;
+    hint: string;
+  };
+};
+
+/**
+ * The advice the provisioning-profile rows share (#2688). Named once so the three rows that require a
+ * different complaint cannot drift into three different fixes for one lever.
+ */
+const PROFILE_UNUSABLE: RunnerErrorRule['buildFailure'] = {
+  reason: 'signing_provisioning_profile_missing',
+  hint: 'Install/select a valid iOS provisioning profile, or set AGENT_DEVICE_IOS_PROVISIONING_PROFILE.',
+};
+
+/**
+ * The one declaration of runner error classes (#1631), mirroring
+ * RUNNER_COMMAND_TRAIT_MANIFEST's role for commands: every recovery predicate
+ * below derives from this table instead of keeping its own substring chain,
+ * and since #2680 so does the one classification of startup failures — a row
+ * carries recovery verdicts, a `buildFailure` reason and hint, or both.
+ * Per axis, the FIRST matching rule that defines the axis wins — which is why
+ * `flagged_retriable` precedes the denials (an explicitly retriable error
+ * stays retriable whatever its message says), and `usbmux_device_unattached`
+ * sits first (retrying cannot attach a cable, and its typed verdict carries
+ * the recovery hint a generic connect failure would replace).
+ */
+export const RUNNER_ERROR_RULES: readonly RunnerErrorRule[] = [
+  {
+    reason: 'usbmux_device_unattached',
+    match: { code: 'DEVICE_NOT_FOUND', details: hasUsbmuxDeviceUnattached },
+    verdicts: { connectRetry: false },
+  },
+  {
+    reason: 'flagged_retriable',
+    match: { code: 'COMMAND_FAILED', details: hasRetriableFlag },
+    verdicts: { retryable: true, connectRetry: true },
+  },
+  {
+    // Says `artifactSuspect: false` on purpose: its message also reads as a refused
+    // connection, and a boot that cannot compile is not cured by wiping derived data.
+    reason: 'xcodebuild_exited_early',
+    match: { code: 'COMMAND_FAILED', messageIncludesAll: ['xcodebuild exited early'] },
+    verdicts: { retryable: false, connectRetry: false, artifactSuspect: false },
+  },
+  {
+    // A device still mid-attachment is not a runner we can talk to yet, and waiting on
+    // it inside this request is what the caller's own retry is for.
+    reason: 'device_busy_connecting',
+    match: { code: 'COMMAND_FAILED', messageIncludesAll: ['device is busy', 'connecting'] },
+    verdicts: { retryable: false, connectRetry: false },
+  },
+  {
+    // The marker is the whole fact: the preflight gave up before the command was written, so
+    // replaying it cannot duplicate anything. It is asked for alone because the preflight fails in
+    // whatever shape the connect loop ended with — a refusal, an exhausted probe, a killed
+    // fallback — and a rule that also required a recorded budget would fire on only some of them.
+    reason: 'runner_readiness_preflight_failed',
+    match: { code: 'COMMAND_FAILED', details: hasReadinessPreflightFailure },
+    verdicts: { restartAfterReadinessPreflight: true },
+  },
+  {
+    reason: 'runner_connect_refused',
+    match: { code: 'COMMAND_FAILED', messageIncludesAll: ['runner did not accept connection'] },
+    verdicts: {
+      retryable: true,
+      connectRetry: true,
+      restartBeforeSend: true,
+      artifactSuspect: true,
+    },
+  },
+  {
+    // Every endpoint answered and none of them had a runner: with a restored artifact
+    // in hand, that artifact is the common cause.
+    reason: 'runner_endpoint_probe_exhausted',
+    match: { code: 'COMMAND_FAILED', messageIncludesAll: ['runner endpoint probe failed'] },
+    verdicts: { artifactSuspect: true },
+  },
+  {
+    reason: 'fetch_failed',
+    match: { code: 'COMMAND_FAILED', messageIncludesAll: ['fetch failed'] },
+    verdicts: { retryable: true, connectRetry: true },
+  },
+  {
+    reason: 'econnrefused',
+    match: { code: 'COMMAND_FAILED', messageIncludesAll: ['econnrefused'] },
+    verdicts: { retryable: true, connectRetry: true },
+  },
+  {
+    reason: 'socket_hang_up',
+    match: { code: 'COMMAND_FAILED', messageIncludesAll: ['socket hang up'] },
+    verdicts: { retryable: true, connectRetry: true },
+  },
+  {
+    reason: 'ax_snapshot_failure',
+    match: { code: 'IOS_AX_SNAPSHOT_FAILED' },
+    verdicts: { sessionFatalReason: 'ax_snapshot_failure' },
+  },
+  {
+    reason: 'xctest_recorded_failure',
+    match: { code: 'XCTEST_RECORDED_FAILURE' },
+    verdicts: { sessionFatalReason: 'xctest_recorded_failure' },
+  },
+  {
+    // The runner reported its main thread stuck in abandoned work past the wedge
+    // threshold (#1105): only a restart cures it. The per-request recycle budget
+    // still bounds how many boots one request pays for.
+    reason: 'runner_main_thread_wedged',
+    match: { code: 'RUNNER_WEDGED' },
+    verdicts: { sessionFatalReason: 'runner_main_thread_wedged' },
+  },
+  // ── Startup classification (#2680) ───────────────────────────────────────────────────────────
+  // These rows answer "why could the runner not get here at all": `xcodebuild build-for-testing`
+  // refusing, and the host preflight that runs before it. They carry a reason and a hint for the
+  // caller and no recovery verdicts, because there is no session to invalidate and nothing was sent
+  // to resend. Specific rows precede generic ones: the classifier takes the first match.
+  //
+  // Why these rows are text matchers while the rows above key on a code or a typed field:
+  // `runnerToolText` reads xcodebuild's own prose because that prose is the only publication these
+  // failures have — there is no code and no typed field to key on. Its haystack is deliberately
+  // narrow: our message plus the tool's stdout/stderr, never the whole details bag, which also
+  // holds the argv we were asked to run (so a caller's own PROVISIONING_PROFILE_SPECIFIER=… would
+  // otherwise name a signing cause for an unrelated compile error) and the reason and hint this
+  // classifier just published (so a re-wrapped failure would match itself). The DevToolsSecurity
+  // row is the other half: where a probe of ours publishes a typed fact, the row keys on that fact
+  // alone. `resolveRunnerEarlyExitHint` stays outside this table for the same reason it stays a hint
+  // builder — it classifies a runner that DID build and then exited early, whose reason axis is the
+  // `BootFailureReason` `classifyBootFailure` already returns, and a build that never produced a
+  // binary has no boot to classify.
+  {
+    reason: 'bundle_identifier_registration_failed',
+    match: { toolTextIncludesAll: ['failed registering bundle identifier'] },
+    verdicts: {},
+    buildFailure: {
+      reason: 'bundle_identifier_already_registered',
+      hint: 'Set AGENT_DEVICE_IOS_BUNDLE_ID to a unique reverse-DNS value (for example, com.yourname.agentdevice.runner), then retry.',
+    },
+  },
+  {
+    // The identifier and its availability have to meet in one line: `App Identifier` and `not
+    // available` are two phrases a captured log can carry for reasons that have nothing to do with
+    // each other, which is the same hazard the profile rows just gave up (#2688 review).
+    reason: 'bundle_identifier_unavailable',
+    match: { toolTextLineIncludesAll: ['app identifier', 'not available'] },
+    verdicts: {},
+    buildFailure: {
+      reason: 'bundle_identifier_already_registered',
+      hint: 'Set AGENT_DEVICE_IOS_BUNDLE_ID to a unique reverse-DNS value (for example, com.yourname.agentdevice.runner), then retry.',
+    },
+  },
+  {
+    reason: 'signing_requires_development_team',
+    match: { toolTextIncludesAll: ['requires a development team'] },
+    verdicts: {},
+    buildFailure: {
+      reason: 'signing_no_development_team',
+      hint: 'Configure signing in Xcode or set AGENT_DEVICE_IOS_TEAM_ID for physical-device runs.',
+    },
+  },
+  {
+    // "conflicting provisioning settings" names a profile while saying the automatic and manual
+    // settings disagree, so without this row the profile row below would send the reader to install
+    // a profile for a problem that is a settings mismatch. No reason is claimed for it: nothing has
+    // captured this failure or proved which lever clears it, and advice the reader cannot follow is
+    // worse than the cache-recovery advice the unclassified path already gives (#2680).
+    reason: 'conflicting_provisioning_settings_unproven',
+    match: { toolTextIncludesAll: ['conflicting provisioning settings'] },
+    verdicts: {},
+    buildFailure: {
+      reason: RUNNER_STARTUP_FAILURE_UNCLASSIFIED_REASON,
+      hint: RUNNER_CACHE_RECOVERY_HINT,
+    },
+  },
+  {
+    // "No profiles for 'com.example' were found" names the bundle id and the absence in one sentence,
+    // so the phrase alone is the complaint and needs no second phrase to qualify it.
+    reason: 'signing_no_profiles_for_bundle_id',
+    match: { toolTextIncludesAll: ['no profiles for'] },
+    verdicts: {},
+    buildFailure: PROFILE_UNUSABLE,
+  },
+  // A profile named in the tool's output is only evidence when the output also says what is wrong with
+  // that profile, in the same line (#2688 review). One bare `provisioning profile` substring was the
+  // shipped sniffer's trigger, and it is a phrase a failing build can print while talking about
+  // something else: the codesign command line, a build-settings dump, a note about the profile that was
+  // used. Requiring a second phrase somewhere in the same log is no better — a note about the profile
+  // used above an unrelated `has expired` certificate warning would then name the profile. Each row
+  // below therefore asks for the profile and Xcode's complaint about it on one line, and a failure that
+  // merely mentions a profile stays unclassified rather than being sent to install one it already has.
+  {
+    // Xcode's own signing-error domain beside the profile it rejected: the machine-readable half of its
+    // `IDEProvisioningErrorDomain` diagnostics, which accompanies the prose rather than replacing it.
+    reason: 'signing_provisioning_profile_xcode_error',
+    match: { toolTextLineIncludesAll: ['provisioning profile', 'ideprovisioningerrordomain'] },
+    verdicts: {},
+    buildFailure: PROFILE_UNUSABLE,
+  },
+  {
+    // "Provisioning profile \"X\" doesn't include application identifier ..." — the profile that is
+    // installed but does not cover this app or capability.
+    reason: 'signing_provisioning_profile_does_not_cover',
+    match: { toolTextLineIncludesAll: ['provisioning profile', "doesn't include"] },
+    verdicts: {},
+    buildFailure: PROFILE_UNUSABLE,
+  },
+  {
+    // "Provisioning profile \"X\" has expired" — installing it again is not the fix; replacing it is,
+    // which is what the hint's "valid" is for. The full phrase, on the profile's own line: `expired`
+    // alone is what an expired certificate, a stale session, or a revoked key writes (#2688 review).
+    reason: 'signing_provisioning_profile_expired',
+    match: { toolTextLineIncludesAll: ['provisioning profile', 'has expired'] },
+    verdicts: {},
+    buildFailure: PROFILE_UNUSABLE,
+  },
+  {
+    // Signing is involved but nothing above names how: the reason says signing and the hint stays
+    // the generic one it has always carried, rather than naming a misconfiguration no rule proved.
+    reason: 'signing_unspecified',
+    match: { toolTextIncludesAll: ['code signing'] },
+    verdicts: {},
+    buildFailure: {
+      reason: 'signing_unspecified',
+      hint: 'Enable Automatic Signing in Xcode or provide AGENT_DEVICE_IOS_TEAM_ID and optional AGENT_DEVICE_IOS_SIGNING_IDENTITY.',
+    },
+  },
+  {
+    reason: 'devtools_security_refused',
+    match: { code: 'COMMAND_FAILED', details: hasDevToolsSecurityStatus },
+    verdicts: {},
+    buildFailure: {
+      reason: 'devtools_security_developer_mode_disabled',
+      hint: 'Run `sudo DevToolsSecurity -enable`, then retry the iOS runner. UI test runners start suspended until Xcode/testmanagerd can attach.',
+    },
+  },
+];
+
+function matchesRunnerErrorRule(error: AppError, match: RunnerErrorMatch): boolean {
+  if (match.code !== undefined && error.code !== match.code) return false;
+  if (!matchesRunnerErrorDetails(error, match.details)) return false;
+  if (!matchesRunnerToolText(error, match.toolTextIncludesAll)) return false;
+  if (!matchesRunnerToolTextLine(error, match.toolTextLineIncludesAll)) return false;
+  return matchesRunnerErrorMessage(error, match.messageIncludesAll);
+}
+
+function matchesRunnerErrorDetails(error: AppError, details: RunnerErrorMatch['details']): boolean {
+  if (details === undefined) return true;
+  return details((error.details ?? {}) as AppErrorDetails);
+}
+
+function matchesRunnerErrorMessage(error: AppError, parts: readonly string[] | undefined): boolean {
+  if (!parts) return true;
+  const message = `${error.message ?? ''}`.toLowerCase();
+  return parts.every((part) => message.includes(part));
+}
+
+/**
+ * The only text a startup rule may read: our message plus the tool's own `stdout` and `stderr`
+ * (#2680). The rest of `details` is deliberately out of reach — `cmd`/`args` describe what we were
+ * asked to run, and `reason`/`hint` are this classifier's own output, which a re-wrapped failure
+ * would otherwise find and match again.
+ */
+function runnerToolText(error: AppError): string {
+  const details = error.details ?? {};
+  return [error.message, details.stdout, details.stderr]
+    .filter((part): part is string => typeof part === 'string')
+    .join('\n')
+    .toLowerCase();
+}
+
+function matchesRunnerToolText(error: AppError, parts: readonly string[] | undefined): boolean {
+  if (!parts) return true;
+  const text = runnerToolText(error);
+  return parts.every((part) => text.includes(part));
+}
+
+/**
+ * The same haystack read one line at a time, so a row can require its phrases to be in one sentence
+ * rather than merely in one file (#2688 review). A captured build log is thousands of lines long, and
+ * two unrelated lines can hold any pair of words.
+ */
+function matchesRunnerToolTextLine(error: AppError, parts: readonly string[] | undefined): boolean {
+  if (!parts) return true;
+  return runnerToolText(error)
+    .split('\n')
+    .some((line) => parts.every((part) => line.includes(part)));
+}
+
+function runnerErrorVerdict<Axis extends keyof RunnerErrorVerdicts>(
+  error: unknown,
+  axis: Axis,
+): RunnerErrorVerdicts[Axis] | undefined {
+  if (!(error instanceof AppError)) return undefined;
+  for (const rule of RUNNER_ERROR_RULES) {
+    if (rule.verdicts[axis] === undefined) continue;
+    if (matchesRunnerErrorRule(error, rule.match)) return rule.verdicts[axis];
+  }
+  return undefined;
+}
+
+export function isRetryableRunnerError(err: unknown): boolean {
+  if (!(err instanceof AppError)) return false;
+  if (err.code !== 'COMMAND_FAILED') return false;
+  return runnerErrorVerdict(err, 'retryable') ?? false;
+}
+
+/**
+ * True when the runner reported its main thread occupied by watchdog-abandoned XCTest work, either
+ * as a fast refusal of this command (`RUNNER_BUSY`) or as the timeout the stalling command itself
+ * returns (`MAIN_THREAD_TIMEOUT`) (#2552). Both are diagnostic-only on the wire (`COMMAND_FAILED` +
+ * `details.runnerErrorCode`), so family policy reads the typed detail rather than the message.
+ */
+export function isRunnerMainThreadOccupiedError(error: unknown): boolean {
+  if (!(error instanceof AppError)) return false;
+  const runnerErrorCode = error.details?.runnerErrorCode;
+  return (
+    runnerErrorCode === RUNNER_BUSY_RUNNER_CODE ||
+    runnerErrorCode === MAIN_THREAD_TIMEOUT_RUNNER_CODE
+  );
+}
+
+/**
+ * True when usbmuxd answered and the device is simply not attached by cable.
+ * A CoreDevice-backed device falls back to its network tunnel; an XCTest-backed
+ * device has no second route, so this verdict is terminal rather than retryable.
+ *
+ * Lives here rather than beside the usbmux transport because the retry policy
+ * below needs it, and that transport already depends on this module.
+ */
+export function isUsbmuxDeviceUnattachedError(error: unknown): boolean {
+  if (!(error instanceof AppError) || error.code !== 'DEVICE_NOT_FOUND') return false;
+  return hasUsbmuxDeviceUnattached((error.details ?? {}) as AppErrorDetails);
+}
+
+/**
+ * Default is true and not false: the common failure while the runner boots is an error
+ * no rule describes, and giving up on it would fail a command that the connect loop was
+ * about to succeed. A rule says false only when waiting cannot help.
+ */
+export function shouldRetryRunnerConnectError(error: unknown): boolean {
+  return runnerErrorVerdict(error, 'connectRetry') ?? true;
+}
+
+/**
+ * The readiness preflight gave up, so the runner never saw the command: restarting the session and
+ * replaying is both safe and the only way out. The marker carries the rule; the message does not.
+ */
+export function shouldRestartRunnerAfterReadinessPreflight(error: unknown): boolean {
+  return runnerErrorVerdict(error, 'restartAfterReadinessPreflight') ?? false;
+}
+
+/**
+ * The runner refused or never answered on every route, which is what a restored artifact
+ * that cannot boot looks like. Deliberately narrow: the recovery it authorises is a clean
+ * `xcodebuild` rebuild, so a slow boot, a busy device or a transport failure partway
+ * through a command must not pay that price.
+ */
+export function shouldRebuildCachedRunnerArtifact(error: unknown): boolean {
+  return runnerErrorVerdict(error, 'artifactSuspect') ?? false;
+}
+
+/**
+ * Session-fatal classification for a runner response error: when defined, the
+ * cached runner session must be invalidated with this reason instead of being
+ * reused (see ADR 0005 and docs/agents/selector-capture.md's
+ * runnerFatal rule).
+ */
+export function resolveRunnerFatalErrorReason(error: unknown): string | undefined {
+  return runnerErrorVerdict(error, 'sessionFatalReason');
+}
+
+/**
+ * A connect-shaped failure that surfaced before the command was sent: restart
+ * the runner session and replay the command, rather than probing a runner
+ * that never accepted the connection. Composed with the connect-retry axis so
+ * a terminal connect verdict (cable unattached, xcodebuild exited early)
+ * still refuses the restart. Matching is table-driven and therefore
+ * case-insensitive, unlike the raw-message check it replaced; the message is
+ * our own transport literal, so no real error changes class.
+ */
+export function shouldRestartRunnerBeforeCommandSend(error: unknown): boolean {
+  return (
+    (runnerErrorVerdict(error, 'restartBeforeSend') ?? false) &&
+    shouldRetryRunnerConnectError(error)
+  );
+}
+
+/**
+ * The one classifier for "the runner did not reach the point of serving a command" (#2680). Every
+ * path that stops the runner before it answers a request routes its failure through here, so the
+ * reason a caller sees is produced by the same rows that produce the hint beside it — a reason is
+ * never inferred from a hint's wording, and an unproven cause is never claimed.
+ *
+ * Callers publish the pair as `details.reason` plus the top-level hint on a `COMMAND_FAILED`; the
+ * code is `COMMAND_FAILED` for every reason, so the reason is the assertion.
+ */
+export function classifyRunnerStartupFailure(error: unknown): RunnerStartupClassification {
+  if (error instanceof AppError) {
+    for (const rule of RUNNER_ERROR_RULES) {
+      const buildFailure = rule.buildFailure;
+      if (!buildFailure) continue;
+      if (matchesRunnerErrorRule(error, rule.match)) {
+        return { reason: buildFailure.reason, hint: buildFailure.hint, matched: true };
+      }
+    }
+  }
+  return {
+    reason: RUNNER_STARTUP_FAILURE_UNCLASSIFIED_REASON,
+    hint: RUNNER_CACHE_RECOVERY_HINT,
+    matched: false,
+  };
+}
+
+/**
+ * The verdict, the advice beside it, and whether a row reached either (#2690 review). `matched` is
+ * half the answer rather than an implementation detail: {@link RUNNER_STARTUP_FAILURE_UNCLASSIFIED_REASON}
+ * is also what a row that deliberately claims no cause publishes, so reading the reason alone cannot
+ * tell "nothing spoke" from "a row spoke and declined to name a cause".
+ */
+export type RunnerStartupClassification = Readonly<{
+  reason: RunnerStartupFailureReason;
+  hint: string;
+  /**
+   * False only when no rule row matched at all. The catch that publishes this verdict carries it on
+   * `details.startupRuleMatched`, which is the half a caller cannot recover from the reason alone.
+   */
+  matched: boolean;
+}>;
+
+/**
+ * What the startup carries forward from the device so a later failure can say what the phone said
+ * (#2683). The one thing that stops a run up front is a disabled Developer Mode toggle, which no
+ * later step can change; everything else the device reports is only worth publishing beside the
+ * failure it explains.
+ */
+export type IosRunnerDeviceStates = Readonly<{
+  developerMode: IosDeveloperModeState;
+  developerDiskImage: IosDeveloperDiskImageState;
+  /** The remedy for an unavailable image, worded by `core/devicectl.ts` and read, not rewritten. */
+  developerDiskImageHint: string;
+}>;
+
+/**
+ * The device's turn on a startup failure (#2683, #2690 review), applied by the session's startup
+ * catch so it reaches every path that stops a runner before it serves a command: a cold build, a warm
+ * derived cache that fails at install, or an external xctestrun that never launches. The phone's own
+ * state rides along as `details.developerDiskImage` on all of them, because it is a fact whoever is
+ * reading this failure wants.
+ *
+ * It becomes the *reason* only when the failure carries no reason of its own and no rule row matched.
+ * `devicectl` reports the image only while the tunnel is up and the phone is booted, so an
+ * unavailable reading that reached here is a fact about the device rather than a snapshot of a sleeping
+ * phone — but a failure that already named a cause, or that a row looked at and declined to name one
+ * for, outranks a state that may have been cleared before the failure was written down. And a command
+ * the host killed at its own deadline says nothing about the device either: the build that never
+ * finished cannot have been refused for want of developer support, so a timeout outranks a state too.
+ * An error that is not an `AppError` comes back untouched: a cancellation and a foreign failure keep
+ * their identity.
+ */
+export function enrichRunnerStartupFailureWithDeviceStates(
+  error: unknown,
+  states: IosRunnerDeviceStates | undefined,
+): unknown {
+  if (!states || !(error instanceof AppError)) return error;
+  const speaks =
+    claimedStartupFailureReason(error) === undefined &&
+    states.developerDiskImage === 'unavailable' &&
+    !startupFailureRuleMatched(error) &&
+    !startupFailureHostDeadlineHit(error);
+  return new AppError(
+    error.code,
+    error.message,
+    {
+      ...(error.details ?? {}),
+      ...(speaks
+        ? {
+            reason: 'device_developer_disk_image_unavailable',
+            hint: states.developerDiskImageHint,
+          }
+        : {}),
+      developerDiskImage: states.developerDiskImage,
+    },
+    error.cause,
+  );
+}
+
+/**
+ * The reason a startup failure already carries, discounting the placeholder the classifier publishes
+ * when nothing proved a cause. Without this discount the build catch's own
+ * `build_failed_unclassified` would read as a claimed cause and silence the device everywhere.
+ */
+function claimedStartupFailureReason(error: AppError): RunnerStartupFailureReason | undefined {
+  const reason = error.details?.reason;
+  if (typeof reason !== 'string' || reason === RUNNER_STARTUP_FAILURE_UNCLASSIFIED_REASON) {
+    return undefined;
+  }
+  return reason as RunnerStartupFailureReason;
+}
+
+/**
+ * Whether the host's own execution deadline ended the command behind this failure. A build the host
+ * killed at `buildTimeoutMs` reaches the startup catch as `build_failed_unclassified` with nothing
+ * matched, and an unavailable image sitting on the device would then be named as the cause of a build
+ * that was simply too slow (#2690 review). A catch that published a classification carries the answer
+ * in `details.startupHostDeadlineHit` for the same reason it carries `startupRuleMatched`: its wrapper
+ * buries the tool error a level too deep to inspect. A failure that never passed through such a catch
+ * is read here, where the exec's own `timeoutMs` detail is still in reach.
+ */
+function startupFailureHostDeadlineHit(error: AppError): boolean {
+  const published = error.details?.startupHostDeadlineHit;
+  if (typeof published === 'boolean') return published;
+  return isCommandTimeoutError(error);
+}
+
+/**
+ * Whether a rule row already reached this failure. A catch that published a classification carries its
+ * own answer in `details.startupRuleMatched`, because its wrapper keeps the tool's text one level too
+ * deep for the rows to read again — re-classifying the wrapper would report "nothing matched" for a
+ * failure whose cause a row had just declined to name (#2690 review). A failure that never passed
+ * through such a catch is classified here, which is the same answer its own publisher would have given.
+ */
+function startupFailureRuleMatched(error: AppError): boolean {
+  const published = error.details?.startupRuleMatched;
+  if (typeof published === 'boolean') return published;
+  return classifyRunnerStartupFailure(error).matched;
+}
diff --git a/packages/platform-apple/src/runner/runner-lifecycle.ts b/packages/platform-apple/src/runner/runner-lifecycle.ts
index a99316d767..aa06dcd967 100644
--- a/packages/platform-apple/src/runner/runner-lifecycle.ts
+++ b/packages/platform-apple/src/runner/runner-lifecycle.ts
@@ -15,15 +15,17 @@ import {
 } from './runner-session.ts';
 import {
   assertRunnerRequestActive,
-  isRetryableRunnerError,
   resolveRunnerRequestSignal,
+  withRunnerCommandId,
+  type RunnerCommand,
+} from './runner-contract.ts';
+import {
+  isRetryableRunnerError,
   shouldRebuildCachedRunnerArtifact,
   shouldRestartRunnerAfterReadinessPreflight,
   shouldRestartRunnerBeforeCommandSend,
   shouldRetryRunnerConnectError,
-  withRunnerCommandId,
-  type RunnerCommand,
-} from './runner-contract.ts';
+} from './runner-error-classification.ts';
 import type {
   AppleRunnerCommandOptions,
   AppleRunnerPrepareOptions,
diff --git a/packages/platform-apple/src/runner/runner-session-types.ts b/packages/platform-apple/src/runner/runner-session-types.ts
index f599eea468..71c8c4c73b 100644
--- a/packages/platform-apple/src/runner/runner-session-types.ts
+++ b/packages/platform-apple/src/runner/runner-session-types.ts
@@ -4,7 +4,7 @@ import type { DeviceInfo } from '@agent-device/kernel/device';
 import type { RunnerXctestrunArtifact } from './runner-xctestrun.ts';
 import type { RunnerLease } from './runner-lease.ts';
 import type { XcodebuildSimulatorSetRedirectHandle } from './runner-device-set.ts';
-import type { IosRunnerDeviceStates } from './runner-contract.ts';
+import type { IosRunnerDeviceStates } from './runner-error-classification.ts';
 
 /**
  * Where one runner process stands in the lifecycle of the session that owns it (#2662). The state
diff --git a/packages/platform-apple/src/runner/runner-session.ts b/packages/platform-apple/src/runner/runner-session.ts
index 7c0e124cad..e27b692034 100644
--- a/packages/platform-apple/src/runner/runner-session.ts
+++ b/packages/platform-apple/src/runner/runner-session.ts
@@ -39,10 +39,12 @@ import {
   resolveRunnerRequestSignal,
   withRunnerCommandId,
   type RunnerCommand,
+} from './runner-contract.ts';
+import {
   resolveRunnerFatalErrorReason,
   isRunnerMainThreadOccupiedError,
   enrichRunnerStartupFailureWithDeviceStates,
-} from './runner-contract.ts';
+} from './runner-error-classification.ts';
 import {
   canSkipRunnerReadinessPreflightAfterHealthyMutation,
   isReadOnlyRunnerCommand,
diff --git a/packages/platform-apple/src/runner/runner-startup-transport.ts b/packages/platform-apple/src/runner/runner-startup-transport.ts
index 403b6cdcac..df48f0863b 100644
--- a/packages/platform-apple/src/runner/runner-startup-transport.ts
+++ b/packages/platform-apple/src/runner/runner-startup-transport.ts
@@ -13,18 +13,20 @@ import {
   runXcrun,
 } from './host.ts';
 import type { DeviceInfo } from '@agent-device/kernel/device';
+import type { BootFailureReason } from '@agent-device/provision-kit/boot-diagnostics';
 import {
   createRunnerCommandRouteResolver,
   invalidateDeviceTunnelIpCache,
   type RunnerCommandRoute,
 } from './runner-command-route.ts';
 import {
-  buildRunnerConnectError,
-  buildRunnerEarlyExitError,
+  enrichRunnerStartupFailureWithDeviceStates,
   isUsbmuxDeviceUnattachedError,
+  RUNNER_CACHE_RECOVERY_HINT,
   shouldRetryRunnerConnectError,
-  type RunnerCommand,
-} from './runner-contract.ts';
+  type IosRunnerDeviceStates,
+} from './runner-error-classification.ts';
+import type { RunnerCommand } from './runner-contract.ts';
 import type { RunnerSession } from './runner-session-types.ts';
 import {
   canFallBackFromUsbmux,
@@ -455,3 +457,92 @@ async function postCommandViaSimulator(
   const body = result.stdout as string;
   return { status: 200, body };
 }
+
+// What an early-exit error quotes of the runner's own log: enough for the boot-failure anchors
+// (signing, tunneld, device busy), bounded so a wedged xcodebuild cannot ship a megabyte in details.
+const RUNNER_EARLY_EXIT_LOG_TAIL_BYTES = 64 * 1024;
+
+export function resolveRunnerEarlyExitHint(
+  message: string,
+  stdout: string,
+  stderr: string,
+  reason?: BootFailureReason,
+): string {
+  const haystack = `${message}\n${stdout}\n${stderr}`.toLowerCase();
+  if (haystack.includes('device is busy') && haystack.includes('connecting')) {
+    return 'Target iOS device is still connecting. Keep it unlocked, wait for device trust/connection to settle, then retry.';
+  }
+  const classified = reason ?? 'IOS_RUNNER_CONNECT_TIMEOUT';
+  // Clearing cached build products cannot put a device into a provisioning
+  // profile, so that recovery advice is withheld where it would only add noise
+  // to an already actionable instruction.
+  if (classified === 'IOS_RUNNER_DEVICE_NOT_PROVISIONED') return bootFailureHint(classified);
+  return `${bootFailureHint(classified)} ${RUNNER_CACHE_RECOVERY_HINT}`;
+}
+
+function buildRunnerConnectError(params: {
+  port: number;
+  endpoints: string[];
+  logPath?: string;
+  lastError: unknown;
+  deviceStates?: IosRunnerDeviceStates;
+}): AppError {
+  const { port, endpoints, logPath, lastError, deviceStates } = params;
+  const message = 'Runner did not accept connection';
+  const error = new AppError('COMMAND_FAILED', message, {
+    port,
+    endpoints,
+    logPath,
+    lastError: lastError ? String(lastError) : undefined,
+    reason: classifyBootFailure({
+      error: lastError,
+      message,
+      context: { platform: 'ios', phase: 'connect' },
+    }),
+    hint: bootFailureHint('IOS_RUNNER_CONNECT_TIMEOUT'),
+  });
+  // The other way the connect stage gives up: `xcodebuild` is still alive at the deadline. It gets
+  // the same enrichment as the early exit below (#2683).
+  return enrichRunnerStartupFailureWithDeviceStates(error, deviceStates) as AppError;
+}
+
+export async function buildRunnerEarlyExitError(params: {
+  session: RunnerSession;
+  port: number;
+  logPath?: string;
+}): Promise<AppError> {
+  const { session, port, logPath } = params;
+  const result = await session.testPromise;
+  const message = 'Runner did not accept connection (xcodebuild exited early)';
+  // The runner writes its own output file, so the exec result holds nothing for a file-backed
+  // child; that file is what an early exit can quote (#2681).
+  const output = session.readLogTail?.(RUNNER_EARLY_EXIT_LOG_TAIL_BYTES) ?? '';
+  const reason = classifyBootFailure({
+    message,
+    stdout: output,
+    stderr: output,
+    context: { platform: 'ios', phase: 'connect' },
+  });
+  // exec-guard-allow: xcodebuild can exit 0 and still count as an early exit;
+  // the trio is nested tool context under `xcodebuild`, classified into
+  // `reason`/`hint` above — not a process-exit wrap.
+  const error = new AppError('COMMAND_FAILED', message, {
+    port,
+    // The quote always comes from the runner's own file, so that is the file the error has to name;
+    // pointing at the request's log would advertise a file that does not contain what is quoted (#2681).
+    logPath: session.runnerLogPath ?? logPath,
+    xcodebuild: {
+      exitCode: result.exitCode,
+      // One merged file since #2681: the tail is reported under `stderr`, which is where readers
+      // already look, next to the file it came from.
+      stderr: output,
+    },
+    reason,
+    hint: resolveRunnerEarlyExitHint(message, output, output, reason),
+  });
+  // The build catch is not the only way a runner stops before serving a command. A locked phone lets
+  // the build finish and kills `xcodebuild test-without-building` instead, so nothing reaches that
+  // catch and the disk-image state read before the build would be dropped. Same enrichment, applied
+  // to the failure this path actually produces (#2683).
+  return enrichRunnerStartupFailureWithDeviceStates(error, session.startupDeviceStates) as AppError;
+}
diff --git a/packages/platform-apple/src/runner/runner-transport.ts b/packages/platform-apple/src/runner/runner-transport.ts
index efb89a6c26..754df7ef74 100644
--- a/packages/platform-apple/src/runner/runner-transport.ts
+++ b/packages/platform-apple/src/runner/runner-transport.ts
@@ -2,7 +2,8 @@ import { createRequestCanceledError, AppError } from '@agent-device/kernel/error
 import { Deadline, resolveIosPhysicalDeviceControl } from './host.ts';
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import { createRunnerCommandRouteResolver } from './runner-command-route.ts';
-import { isUsbmuxDeviceUnattachedError, type RunnerCommand } from './runner-contract.ts';
+import { isUsbmuxDeviceUnattachedError } from './runner-error-classification.ts';
+import type { RunnerCommand } from './runner-contract.ts';
 import { usbmuxRunnerTransport } from './runner-usbmux.ts';
 
 export const RUNNER_COMMAND_TIMEOUT_MS = 45_000;

From 9918e721a0b54cfb8911f6aa6efad3d88619b904 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Wed, 23 Sep 2026 15:15:18 +0200
Subject: [PATCH 039/132] refactor(move): collocate the daemon device family
 under src/daemon/device (#2780)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* refactor(move): collocate the daemon device family under src/daemon/device

Move the 17 loose src/daemon/device-*.ts production modules and their 13 tests
into src/daemon/device/ (+ __tests__/), matching the managed-device-allocation,
replay and session-lifecycle layout. Rename-only: every edge involved already
lives in the daemon-server zone, so no layering rule, rank, or import cost
changes. The justification is naming and discoverability — src/daemon holds 177
loose files against 6 directories, and the device-claim family is one owner.
Only relative import specifiers changed.

* chore(gates): repoint the path-keyed tables at src/daemon/device

The move is rename-only, but four tables key on the exact old paths:
- scripts/layering/daemon-platform-runtime-inventory.ts (R76): the two
  composition-essential edges from device-claim-owner-recovery.ts and
  device-ready.ts, whose old entries are stale and whose new paths are
  unclassified — observed red (4 violations) before this edit, green after.
- scripts/layering/daemon-platform-runtime-inventory.test.ts: the device-ready
  fixtures now plant the importer at its new path with its new specifier depth.
- fallow-baselines/health.json: move the device-ready.ts complexity_high +
  crap_high entry by hand to the new path; nothing else regenerated.
- .fallowrc.json: the #1642 host-process-mock exemption names its consumers by
  path; two of the three moved.
Plus two stale path comments in the help-conformance sample producer and the
nightly claim-registry model. LOGICAL_MODULE_POLICIES gains no entry: the device
family has no forbidden target roots and no facade, and a facade-less entry with
empty forbiddenTargetRoots is a no-op declaration (cf. the undeclared
src/daemon/managed-device-allocation/).
---
 .fallowrc.json                                |  2 +-
 fallow-baselines/health.json                  |  2 +-
 .../help-conformance-sample-producers.ts      |  2 +-
 scripts/help-conformance-sample-outputs.mjs   |  2 +-
 .../daemon-platform-runtime-inventory.test.ts | 24 +++++++++----------
 .../daemon-platform-runtime-inventory.ts      |  4 ++--
 .../test-utils/device-claim-store.ts          |  2 +-
 src/cli/commands/device-release.ts            |  6 ++---
 src/cli/commands/device.ts                    |  4 ++--
 .../atomic-publish-ownership.test.ts          |  2 +-
 .../__tests__/capture-disclosure.test.ts      |  2 +-
 .../filesystem-boundary-faults.test.ts        |  4 ++--
 .../__tests__/request-router-cost.test.ts     |  2 +-
 .../request-router-lock-policy.test.ts        |  2 +-
 .../request-router-open-claim.test.ts         |  6 ++---
 .../__tests__/request-router-open-harness.ts  |  2 +-
 .../__tests__/request-router-open.test.ts     |  6 ++---
 ...request-router-record-runtime-lock.test.ts |  2 +-
 .../request-router-repair-expired.test.ts     |  2 +-
 .../request-router-replay-scope.test.ts       |  4 ++--
 .../request-router-response-level.test.ts     |  2 +-
 .../request-router-session-address.test.ts    |  4 ++--
 .../request-router-typed-error.test.ts        |  2 +-
 .../__tests__/request-runtime-binding.test.ts |  4 ++--
 .../session-device-resolution.test.ts         |  4 ++--
 .../snapshot-runtime-binding.test.ts          |  4 ++--
 src/daemon/app-event-runtime.ts               |  2 +-
 .../__tests__/device-claim-admission.test.ts  | 12 +++++-----
 .../__tests__/device-claim-allocator.test.ts  |  6 ++---
 .../__tests__/device-claim-conflict.test.ts   |  0
 .../device-claim-owner-recovery.test.ts       |  0
 .../__tests__/device-claim-prune.test.ts      |  8 +++----
 .../__tests__/device-claim-reboot.test.ts     |  0
 .../device-claim-reconciliation.test.ts       |  8 +++----
 .../__tests__/device-claim-record.test.ts     |  0
 .../__tests__/device-claim-rule.test.ts       |  0
 .../__tests__/device-claim-settlement.test.ts |  6 ++---
 .../__tests__/device-claims.test.ts           |  6 ++---
 .../__tests__/device-mutation-drain.test.ts   |  2 +-
 .../__tests__/device-ready.test.ts            |  2 +-
 .../{ => device}/device-claim-admission.ts    |  0
 .../{ => device}/device-claim-allocator.ts    |  0
 .../{ => device}/device-claim-conflict.ts     |  2 +-
 .../{ => device}/device-claim-inspection.ts   |  2 +-
 .../device-claim-owner-recovery.ts            |  6 ++---
 src/daemon/{ => device}/device-claim-paths.ts |  0
 .../{ => device}/device-claim-reboot.ts       |  0
 .../device-claim-reconciliation.ts            |  6 ++---
 .../{ => device}/device-claim-record.ts       |  0
 src/daemon/{ => device}/device-claim-rule.ts  |  0
 .../{ => device}/device-claim-settlement.ts   |  0
 src/daemon/{ => device}/device-claim-store.ts |  0
 src/daemon/{ => device}/device-claims.ts      |  0
 .../{ => device}/device-mutation-drain.ts     |  0
 src/daemon/{ => device}/device-ready.ts       |  4 ++--
 .../{ => device}/device-selector-intent.ts    |  0
 src/daemon/{ => device}/device-targets.ts     |  0
 ...ession-boot-shutdown-device-claims.test.ts |  4 ++--
 .../__tests__/session-device-claims.test.ts   |  8 +++----
 .../__tests__/session-relaunch-close.test.ts  |  4 ++--
 .../__tests__/session-test-harness.ts         |  4 ++--
 .../__tests__/wait-landmark-recording.test.ts |  2 +-
 src/daemon/handlers/session-command-input.ts  |  2 +-
 .../handlers/session-selector-dispatch.ts     |  2 +-
 src/daemon/keyboard-runtime.ts                |  2 +-
 src/daemon/lease-lifecycle.ts                 |  2 +-
 src/daemon/lease-registry.ts                  |  2 +-
 .../session-test-infrastructure.test.ts       |  2 +-
 src/daemon/request-binding.ts                 |  2 +-
 src/daemon/request-execution-scope.ts         |  7 ++++--
 src/daemon/request-handler-chain.ts           |  2 +-
 src/daemon/request-lock-policy.ts             |  2 +-
 .../request-platform-provider-context.ts      |  5 +++-
 src/daemon/request-router.ts                  |  2 +-
 src/daemon/request-runtime-binding.ts         |  2 +-
 src/daemon/runtime-admission.ts               |  2 +-
 src/daemon/server/daemon-runtime.ts           |  4 ++--
 .../server/daemon-shutdown-claims.test.ts     |  6 ++---
 src/daemon/server/daemon-shutdown-claims.ts   |  2 +-
 src/daemon/session-device-resolution.ts       |  5 +++-
 .../session-close-shutdown.fixtures.ts        |  4 ++--
 .../session-open-execution-runtime.test.ts    |  2 +-
 .../__tests__/session-open-runtime.test.ts    |  2 +-
 .../session-open-url-prewarm.test.ts          |  2 +-
 .../session-lifecycle/internal/inventory.ts   |  6 ++---
 .../internal/session-close.ts                 |  2 +-
 .../internal/session-open-execution.ts        | 10 ++++----
 .../internal/session-open.ts                  |  2 +-
 src/daemon/session-runtime.ts                 |  2 +-
 src/daemon/snapshot-runtime-binding.ts        |  2 +-
 .../concurrency-torture/claim-registry.ts     |  2 +-
 .../managed-request-admission.fixtures.ts     |  4 ++--
 92 files changed, 149 insertions(+), 140 deletions(-)
 rename src/daemon/{ => device}/__tests__/device-claim-admission.test.ts (97%)
 rename src/daemon/{ => device}/__tests__/device-claim-allocator.test.ts (97%)
 rename src/daemon/{ => device}/__tests__/device-claim-conflict.test.ts (100%)
 rename src/daemon/{ => device}/__tests__/device-claim-owner-recovery.test.ts (100%)
 rename src/daemon/{ => device}/__tests__/device-claim-prune.test.ts (96%)
 rename src/daemon/{ => device}/__tests__/device-claim-reboot.test.ts (100%)
 rename src/daemon/{ => device}/__tests__/device-claim-reconciliation.test.ts (95%)
 rename src/daemon/{ => device}/__tests__/device-claim-record.test.ts (100%)
 rename src/daemon/{ => device}/__tests__/device-claim-rule.test.ts (100%)
 rename src/daemon/{ => device}/__tests__/device-claim-settlement.test.ts (98%)
 rename src/daemon/{ => device}/__tests__/device-claims.test.ts (99%)
 rename src/daemon/{ => device}/__tests__/device-mutation-drain.test.ts (96%)
 rename src/daemon/{ => device}/__tests__/device-ready.test.ts (98%)
 rename src/daemon/{ => device}/device-claim-admission.ts (100%)
 rename src/daemon/{ => device}/device-claim-allocator.ts (100%)
 rename src/daemon/{ => device}/device-claim-conflict.ts (99%)
 rename src/daemon/{ => device}/device-claim-inspection.ts (99%)
 rename src/daemon/{ => device}/device-claim-owner-recovery.ts (93%)
 rename src/daemon/{ => device}/device-claim-paths.ts (100%)
 rename src/daemon/{ => device}/device-claim-reboot.ts (100%)
 rename src/daemon/{ => device}/device-claim-reconciliation.ts (96%)
 rename src/daemon/{ => device}/device-claim-record.ts (100%)
 rename src/daemon/{ => device}/device-claim-rule.ts (100%)
 rename src/daemon/{ => device}/device-claim-settlement.ts (100%)
 rename src/daemon/{ => device}/device-claim-store.ts (100%)
 rename src/daemon/{ => device}/device-claims.ts (100%)
 rename src/daemon/{ => device}/device-mutation-drain.ts (100%)
 rename src/daemon/{ => device}/device-ready.ts (89%)
 rename src/daemon/{ => device}/device-selector-intent.ts (100%)
 rename src/daemon/{ => device}/device-targets.ts (100%)

diff --git a/.fallowrc.json b/.fallowrc.json
index 691ae633e6..2e78ae33ae 100644
--- a/.fallowrc.json
+++ b/.fallowrc.json
@@ -244,7 +244,7 @@
       "exports": ["*"]
     },
     {
-      "comment": "#1642: its three consumers (src/__tests__/cli-device-status.test.ts, src/daemon/__tests__/device-claims.test.ts, src/daemon/__tests__/device-claim-prune.test.ts) all reach it the only way a Vitest module mock can — `vi.mock(path, async (importOriginal) => (await import('...host-process-mock.ts')).pinOwnProcessStartTime(importOriginal))`. Dependency analysis cannot follow that dynamic import to a consumer, the same limitation the daemon route-handler entry above records.",
+      "comment": "#1642: its three consumers (src/__tests__/cli-device-status.test.ts, src/daemon/device/__tests__/device-claims.test.ts, src/daemon/device/__tests__/device-claim-prune.test.ts) all reach it the only way a Vitest module mock can — `vi.mock(path, async (importOriginal) => (await import('...host-process-mock.ts')).pinOwnProcessStartTime(importOriginal))`. Dependency analysis cannot follow that dynamic import to a consumer, the same limitation the daemon route-handler entry above records.",
       "file": "src/__tests__/test-utils/host-process-mock.ts",
       "exports": ["pinOwnProcessStartTime"]
     },
diff --git a/fallow-baselines/health.json b/fallow-baselines/health.json
index 9076fc5fb6..4869c16c7c 100644
--- a/fallow-baselines/health.json
+++ b/fallow-baselines/health.json
@@ -130,7 +130,7 @@
         "count": 1
       }
     },
-    "src/daemon/device-ready.ts": {
+    "src/daemon/device/device-ready.ts": {
       "complexity_high": {
         "count": 1
       },
diff --git a/scripts/__tests__/help-conformance-sample-producers.ts b/scripts/__tests__/help-conformance-sample-producers.ts
index cfceef7429..2bc1fe0bdf 100644
--- a/scripts/__tests__/help-conformance-sample-producers.ts
+++ b/scripts/__tests__/help-conformance-sample-producers.ts
@@ -22,7 +22,7 @@ import { NEVER_SETTLED_HINT } from '../../src/commands/interaction/runtime/settl
 import { buildAmbiguousMatchError } from '../../src/daemon/selector-match-errors.ts';
 import { refMutationAdmissionResponse } from '../../src/daemon/interaction/index.ts';
 import { buildDeviceInUseBySessionError } from '../../src/daemon/session-recovery-hints.ts';
-import { buildDeviceClaimConflictError } from '../../src/daemon/device-claim-conflict.ts';
+import { buildDeviceClaimConflictError } from '../../src/daemon/device/device-claim-conflict.ts';
 import { activateCompleteRefFrame, readRefMutationFrame } from '../../src/daemon/ref-frame.ts';
 import { resolveRefStalenessWarning } from '../../src/daemon/session-snapshot.ts';
 import type { SessionState } from '../../src/daemon/session-state.ts';
diff --git a/scripts/help-conformance-sample-outputs.mjs b/scripts/help-conformance-sample-outputs.mjs
index f56ce9f36b..db109ec6de 100644
--- a/scripts/help-conformance-sample-outputs.mjs
+++ b/scripts/help-conformance-sample-outputs.mjs
@@ -91,7 +91,7 @@ Hint: Run agent-device session list to inspect active sessions. To reuse this de
 };
 
 // Enforced cross-daemon device claim conflict from
-// src/daemon/device-claim-conflict.ts. This path is deliberately non-retriable:
+// src/daemon/device/device-claim-conflict.ts. This path is deliberately non-retriable:
 // the exact status command is the only safe next step while ownership is live.
 export const DEVICE_CLAIM_IN_USE_SAMPLE = {
   command: 'agent-device open Demo --platform android --serial emulator-5554',
diff --git a/scripts/layering/daemon-platform-runtime-inventory.test.ts b/scripts/layering/daemon-platform-runtime-inventory.test.ts
index a3ec6175a8..2bd73cd8f0 100644
--- a/scripts/layering/daemon-platform-runtime-inventory.test.ts
+++ b/scripts/layering/daemon-platform-runtime-inventory.test.ts
@@ -23,11 +23,11 @@ function edgeViolations(sources: Record<string, string>, file: string): Layering
 test('R76 accepts a classified edge with the exact recorded symbols', () => {
   const sources = {
     [DEVICE_READY_TARGET]: DEVICE_READY_STUB,
-    'src/daemon/device-ready.ts':
-      "import { ensureLocalPlatformDeviceReady } from '../platform-runtime-device-ready.ts';\n" +
+    'src/daemon/device/device-ready.ts':
+      "import { ensureLocalPlatformDeviceReady } from '../../platform-runtime-device-ready.ts';\n" +
       'void ensureLocalPlatformDeviceReady;\n',
   };
-  assert.deepEqual(edgeViolations(sources, 'src/daemon/device-ready.ts'), []);
+  assert.deepEqual(edgeViolations(sources, 'src/daemon/device/device-ready.ts'), []);
 });
 
 for (const [file, target, symbol] of [
@@ -51,8 +51,8 @@ for (const [file, target, symbol] of [
 test('R76 reports every classified edge missing from the tree as stale, not the other way around', () => {
   const sources = {
     [DEVICE_READY_TARGET]: DEVICE_READY_STUB,
-    'src/daemon/device-ready.ts':
-      "import { ensureLocalPlatformDeviceReady } from '../platform-runtime-device-ready.ts';\n" +
+    'src/daemon/device/device-ready.ts':
+      "import { ensureLocalPlatformDeviceReady } from '../../platform-runtime-device-ready.ts';\n" +
       'void ensureLocalPlatformDeviceReady;\n',
   };
   const stale = violations(sources).filter(
@@ -87,11 +87,11 @@ test('R76 rejects an unclassified edge with the pair and its line', () => {
 test('R76 rejects new symbols on a classified edge', () => {
   const sources = {
     [DEVICE_READY_TARGET]: DEVICE_READY_STUB + 'export function extraReadiness() {}\n',
-    'src/daemon/device-ready.ts':
-      "import { ensureLocalPlatformDeviceReady, extraReadiness } from '../platform-runtime-device-ready.ts';\n" +
+    'src/daemon/device/device-ready.ts':
+      "import { ensureLocalPlatformDeviceReady, extraReadiness } from '../../platform-runtime-device-ready.ts';\n" +
       'void [ensureLocalPlatformDeviceReady, extraReadiness];\n',
   };
-  const found = edgeViolations(sources, 'src/daemon/device-ready.ts');
+  const found = edgeViolations(sources, 'src/daemon/device/device-ready.ts');
   assert.equal(found.length, 1);
   assert.equal(found[0]!.rule, DAEMON_PLATFORM_RUNTIME_RULE);
   assert.match(found[0]!.message, /classified symbols drifted/);
@@ -212,12 +212,12 @@ test('R76 rejects a namespace import alongside the recorded named binding on the
 test('R76 treats the import and re-export of one classified pair as one entry', () => {
   const sources = {
     [DEVICE_READY_TARGET]: DEVICE_READY_STUB,
-    'src/daemon/device-ready.ts':
-      "import { ensureLocalPlatformDeviceReady } from '../platform-runtime-device-ready.ts';\n" +
-      "export { ensureLocalPlatformDeviceReady } from '../platform-runtime-device-ready.ts';\n" +
+    'src/daemon/device/device-ready.ts':
+      "import { ensureLocalPlatformDeviceReady } from '../../platform-runtime-device-ready.ts';\n" +
+      "export { ensureLocalPlatformDeviceReady } from '../../platform-runtime-device-ready.ts';\n" +
       'void ensureLocalPlatformDeviceReady;\n',
   };
-  assert.deepEqual(edgeViolations(sources, 'src/daemon/device-ready.ts'), []);
+  assert.deepEqual(edgeViolations(sources, 'src/daemon/device/device-ready.ts'), []);
 });
 
 test('R76 ignores test-shaped and non-daemon importers', () => {
diff --git a/scripts/layering/daemon-platform-runtime-inventory.ts b/scripts/layering/daemon-platform-runtime-inventory.ts
index 78cfee21cb..e50087480a 100644
--- a/scripts/layering/daemon-platform-runtime-inventory.ts
+++ b/scripts/layering/daemon-platform-runtime-inventory.ts
@@ -130,7 +130,7 @@ export const DAEMON_PLATFORM_RUNTIME_EDGES: readonly DaemonPlatformRuntimeEdge[]
       'orphan cleanups, and legacy app-log marker recovery.',
   },
   {
-    file: 'src/daemon/device-claim-owner-recovery.ts',
+    file: 'src/daemon/device/device-claim-owner-recovery.ts',
     target: 'src/platform-runtime.ts',
     symbols: ['createPlatformRuntimeGateway'],
     classification: 'composition-essential',
@@ -140,7 +140,7 @@ export const DAEMON_PLATFORM_RUNTIME_EDGES: readonly DaemonPlatformRuntimeEdge[]
       "composition belongs to the recovery policy's own module.",
   },
   {
-    file: 'src/daemon/device-ready.ts',
+    file: 'src/daemon/device/device-ready.ts',
     target: 'src/platform-runtime-device-ready.ts',
     symbols: ['ensureLocalPlatformDeviceReady'],
     classification: 'composition-essential',
diff --git a/src/__tests__/test-utils/device-claim-store.ts b/src/__tests__/test-utils/device-claim-store.ts
index f1acf204cb..7777f80a48 100644
--- a/src/__tests__/test-utils/device-claim-store.ts
+++ b/src/__tests__/test-utils/device-claim-store.ts
@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { afterEach } from 'vitest';
 import { mkdtempForTestSync } from './tmp-dir.ts';
-import type { DeviceClaimReconciler } from '../../daemon/device-claims.ts';
+import type { DeviceClaimReconciler } from '../../daemon/device/device-claims.ts';
 import { type OwnerIdentity } from '@agent-device/host-kit/process';
 
 export type IsolatedDeviceClaimStore = {
diff --git a/src/cli/commands/device-release.ts b/src/cli/commands/device-release.ts
index 5405ba2d58..1b2ad82c5b 100644
--- a/src/cli/commands/device-release.ts
+++ b/src/cli/commands/device-release.ts
@@ -1,13 +1,13 @@
 import {
   createOwnerScopedDeviceClaimReconciler,
   type OwnerScopedClaimRecoveryComposer,
-} from '../../daemon/device-claim-owner-recovery.ts';
+} from '../../daemon/device/device-claim-owner-recovery.ts';
 import { createDaemonRecoveryPlatformScope } from '../../daemon/platform-request-scope.ts';
 import {
   releaseProvenStaleDeviceClaims,
   type DeviceClaimStaleReleaseOutcome,
-} from '../../daemon/device-claims.ts';
-import type { DeviceClaimSelectors } from '../../daemon/device-claim-inspection.ts';
+} from '../../daemon/device/device-claims.ts';
+import type { DeviceClaimSelectors } from '../../daemon/device/device-claim-inspection.ts';
 
 /**
  * Daemonless `device release --stale`: settles each provably dead owner
diff --git a/src/cli/commands/device.ts b/src/cli/commands/device.ts
index bf277a7dcf..ec1e141983 100644
--- a/src/cli/commands/device.ts
+++ b/src/cli/commands/device.ts
@@ -5,8 +5,8 @@ import {
   deviceClaimRequiresStaleInspection,
   inspectDeviceClaims,
   type InspectedDeviceClaim,
-} from '../../daemon/device-claim-inspection.ts';
-import type { DeviceClaimStaleReleaseOutcome } from '../../daemon/device-claims.ts';
+} from '../../daemon/device/device-claim-inspection.ts';
+import type { DeviceClaimStaleReleaseOutcome } from '../../daemon/device/device-claims.ts';
 import { shellQuoteIfNeeded } from '@agent-device/kernel/device-shell';
 import { writeCommandOutput } from './shared.ts';
 import type { CliFlags } from '@agent-device/contracts/command';
diff --git a/src/daemon/__tests__/atomic-publish-ownership.test.ts b/src/daemon/__tests__/atomic-publish-ownership.test.ts
index 219e548b5e..4dca5b498c 100644
--- a/src/daemon/__tests__/atomic-publish-ownership.test.ts
+++ b/src/daemon/__tests__/atomic-publish-ownership.test.ts
@@ -5,7 +5,7 @@ import { test } from 'vitest';
 const SIMPLE_PUBLISHERS = [
   // device-claims.ts delegates every write to device-claim-store.ts's writeDeviceClaim, the
   // single writer shared by the process-owned and allocator-held claim kinds.
-  new URL('../device-claim-store.ts', import.meta.url),
+  new URL('../device/device-claim-store.ts', import.meta.url),
   new URL('../daemon-shutdown-report.ts', import.meta.url),
   new URL('../provider-lease-expiry.ts', import.meta.url),
   new URL('../session-script-writer.ts', import.meta.url),
diff --git a/src/daemon/__tests__/capture-disclosure.test.ts b/src/daemon/__tests__/capture-disclosure.test.ts
index b6ac2c3a67..a7a52de12f 100644
--- a/src/daemon/__tests__/capture-disclosure.test.ts
+++ b/src/daemon/__tests__/capture-disclosure.test.ts
@@ -29,7 +29,7 @@ vi.mock('../snapshot-interactor-capture.ts', async () => {
   return { captureSnapshotWithInteractor: fixture.captureSnapshotThroughLegacyDispatchFixture };
 });
 
-vi.mock('../device-ready.ts', () => ({
+vi.mock('../device/device-ready.ts', () => ({
   ensureDeviceReady: vi.fn(async () => {}),
 }));
 
diff --git a/src/daemon/__tests__/filesystem-boundary-faults.test.ts b/src/daemon/__tests__/filesystem-boundary-faults.test.ts
index cfb4fb20f4..b6e31da3c4 100644
--- a/src/daemon/__tests__/filesystem-boundary-faults.test.ts
+++ b/src/daemon/__tests__/filesystem-boundary-faults.test.ts
@@ -5,8 +5,8 @@ import { afterEach, vi } from 'vitest';
 import { localRuntimeOwner } from '@agent-device/contracts/platform-runtime';
 import { createDurableResourceEnvelope } from '@agent-device/capture-kit';
 import type { DeviceInfo } from '@agent-device/kernel/device';
-import { acquireDeviceClaim } from '../device-claims.ts';
-import { canonicalLocalDeviceKey } from '../device-claim-paths.ts';
+import { acquireDeviceClaim } from '../device/device-claims.ts';
+import { canonicalLocalDeviceKey } from '../device/device-claim-paths.ts';
 import { createDurableCaptureResourceStore } from '@agent-device/capture-kit/durable-capture';
 import { writeDaemonShutdownReport } from '../daemon-shutdown-report.ts';
 import { SessionScriptWriter, type SessionScriptWriteResult } from '../session-script-writer.ts';
diff --git a/src/daemon/__tests__/request-router-cost.test.ts b/src/daemon/__tests__/request-router-cost.test.ts
index 340c32a589..8eeb772cf2 100644
--- a/src/daemon/__tests__/request-router-cost.test.ts
+++ b/src/daemon/__tests__/request-router-cost.test.ts
@@ -9,7 +9,7 @@ vi.mock('@agent-device/platform-apple/runner/operations', async (importOriginal)
   return { ...actual, stopIosRunnerSession: vi.fn(async () => {}) };
 });
 
-vi.mock('../device-ready.ts', () => ({ ensureDeviceReady: vi.fn(async () => {}) }));
+vi.mock('../device/device-ready.ts', () => ({ ensureDeviceReady: vi.fn(async () => {}) }));
 
 import {
   createRequestHandler,
diff --git a/src/daemon/__tests__/request-router-lock-policy.test.ts b/src/daemon/__tests__/request-router-lock-policy.test.ts
index 4a1479e81f..45da103c58 100644
--- a/src/daemon/__tests__/request-router-lock-policy.test.ts
+++ b/src/daemon/__tests__/request-router-lock-policy.test.ts
@@ -12,7 +12,7 @@ vi.mock('@agent-device/platform-apple/runner/operations', async (importOriginal)
   return { ...actual, stopIosRunnerSession: vi.fn(async () => {}) };
 });
 
-vi.mock('../device-ready.ts', () => ({ ensureDeviceReady: vi.fn(async () => {}) }));
+vi.mock('../device/device-ready.ts', () => ({ ensureDeviceReady: vi.fn(async () => {}) }));
 
 import {
   createRequestHandler,
diff --git a/src/daemon/__tests__/request-router-open-claim.test.ts b/src/daemon/__tests__/request-router-open-claim.test.ts
index 516c7e1725..eabd859560 100644
--- a/src/daemon/__tests__/request-router-open-claim.test.ts
+++ b/src/daemon/__tests__/request-router-open-claim.test.ts
@@ -6,7 +6,7 @@ import path from 'node:path';
 import crypto from 'node:crypto';
 import { getResolveTargetDeviceMock } from './request-router-dispatch-mocks.ts';
 
-vi.mock('../device-ready.ts', () => ({ ensureDeviceReady: vi.fn(async () => {}) }));
+vi.mock('../device/device-ready.ts', () => ({ ensureDeviceReady: vi.fn(async () => {}) }));
 vi.mock('@agent-device/host-kit/process', async (importOriginal) => {
   const actual = await importOriginal<typeof import('@agent-device/host-kit/process')>();
   return { ...actual, readProcessStartTime: vi.fn(() => 'test-process-start') };
@@ -64,11 +64,11 @@ import {
   awaitFixtureReadiness,
   discoverReadyAndroidEmulators,
 } from './application-lifecycle-runtime-fixture.ts';
-import { ensureDeviceReady } from '../device-ready.ts';
+import { ensureDeviceReady } from '../device/device-ready.ts';
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import type { DeviceBootObservation } from '@agent-device/contracts/device-boot';
 import { makeSessionStore } from '../../__tests__/test-utils/store-factory.ts';
-import { inspectDeviceClaims } from '../device-claim-inspection.ts';
+import { inspectDeviceClaims } from '../device/device-claim-inspection.ts';
 import { makeIosDevice, openRequest, storedClaimUpdatedAt } from './request-router-open-harness.ts';
 import { mkdtempForTestSync } from '../../__tests__/test-utils/tmp-dir.ts';
 
diff --git a/src/daemon/__tests__/request-router-open-harness.ts b/src/daemon/__tests__/request-router-open-harness.ts
index 6d44517a67..950ee12ce3 100644
--- a/src/daemon/__tests__/request-router-open-harness.ts
+++ b/src/daemon/__tests__/request-router-open-harness.ts
@@ -1,4 +1,4 @@
-import { inspectDeviceClaims } from '../device-claim-inspection.ts';
+import { inspectDeviceClaims } from '../device/device-claim-inspection.ts';
 import type { DeviceInfo } from '@agent-device/kernel/device';
 
 /**
diff --git a/src/daemon/__tests__/request-router-open.test.ts b/src/daemon/__tests__/request-router-open.test.ts
index 7f874b492e..344f7ba6b1 100644
--- a/src/daemon/__tests__/request-router-open.test.ts
+++ b/src/daemon/__tests__/request-router-open.test.ts
@@ -8,7 +8,7 @@ import { getResolveTargetDeviceMock } from './request-router-dispatch-mocks.ts';
 
 import { replayScriptSourceBundleFor } from '../../__tests__/test-utils/replay-script-source.ts';
 
-vi.mock('../device-ready.ts', () => ({ ensureDeviceReady: vi.fn(async () => {}) }));
+vi.mock('../device/device-ready.ts', () => ({ ensureDeviceReady: vi.fn(async () => {}) }));
 vi.mock('@agent-device/host-kit/process', async (importOriginal) => {
   const actual = await importOriginal<typeof import('@agent-device/host-kit/process')>();
   const startTime = 'test-process-start';
@@ -74,7 +74,7 @@ import {
 import { createRequestHandler as createProductionRequestHandler } from '../request-router.ts';
 import { resolveRequestExecutionLockPlan } from '../request-binding.ts';
 import { LeaseRegistry } from '../lease-registry.ts';
-import { ensureDeviceReady } from '../device-ready.ts';
+import { ensureDeviceReady } from '../device/device-ready.ts';
 import {
   awaitFixtureReadiness,
   discoverReadyAndroidEmulators,
@@ -83,7 +83,7 @@ import type { DeviceInfo } from '@agent-device/kernel/device';
 import type { DeviceBootObservation } from '@agent-device/contracts/device-boot';
 import { AppError } from '@agent-device/kernel/errors';
 import { makeSessionStore } from '../../__tests__/test-utils/store-factory.ts';
-import { inspectDeviceClaims } from '../device-claim-inspection.ts';
+import { inspectDeviceClaims } from '../device/device-claim-inspection.ts';
 import { spawn } from 'node:child_process';
 import crypto from 'node:crypto';
 import {
diff --git a/src/daemon/__tests__/request-router-record-runtime-lock.test.ts b/src/daemon/__tests__/request-router-record-runtime-lock.test.ts
index b0c0f24064..3355a9594d 100644
--- a/src/daemon/__tests__/request-router-record-runtime-lock.test.ts
+++ b/src/daemon/__tests__/request-router-record-runtime-lock.test.ts
@@ -31,7 +31,7 @@ vi.mock('@agent-device/device-selection/dispatch-resolve', async (importOriginal
   return { ...actual, resolveTargetDevice: vi.fn(async () => DEVICE) };
 });
 
-vi.mock('../device-ready.ts', () => ({ ensureDeviceReady: vi.fn(async () => {}) }));
+vi.mock('../device/device-ready.ts', () => ({ ensureDeviceReady: vi.fn(async () => {}) }));
 
 test('fresh default-device recording starts serialize before durable admission', async () => {
   let releaseFirstStart: () => void = () => {};
diff --git a/src/daemon/__tests__/request-router-repair-expired.test.ts b/src/daemon/__tests__/request-router-repair-expired.test.ts
index b3d0ad2666..0e9947be33 100644
--- a/src/daemon/__tests__/request-router-repair-expired.test.ts
+++ b/src/daemon/__tests__/request-router-repair-expired.test.ts
@@ -12,7 +12,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { getResolveTargetDeviceMock } from './request-router-dispatch-mocks.ts';
 
-vi.mock('../device-ready.ts', () => ({ ensureDeviceReady: vi.fn(async () => {}) }));
+vi.mock('../device/device-ready.ts', () => ({ ensureDeviceReady: vi.fn(async () => {}) }));
 
 import { createRequestHandler } from './test-device-runtime-gateway.ts';
 import type { DaemonRequest } from '../daemon-request.ts';
diff --git a/src/daemon/__tests__/request-router-replay-scope.test.ts b/src/daemon/__tests__/request-router-replay-scope.test.ts
index e9850fe882..5413f916f7 100644
--- a/src/daemon/__tests__/request-router-replay-scope.test.ts
+++ b/src/daemon/__tests__/request-router-replay-scope.test.ts
@@ -6,7 +6,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { getResolveTargetDeviceMock } from './request-router-dispatch-mocks.ts';
 
-vi.mock('../device-ready.ts', () => ({ ensureDeviceReady: vi.fn(async () => {}) }));
+vi.mock('../device/device-ready.ts', () => ({ ensureDeviceReady: vi.fn(async () => {}) }));
 
 vi.mock('../../platform-runtime-runtime-hints.ts', async (importOriginal) => {
   const actual = await importOriginal<typeof import('../../platform-runtime-runtime-hints.ts')>();
@@ -39,7 +39,7 @@ import {
   lifecycleDeviceRuntimeGateway,
   systemRuntimeSpies,
 } from './test-device-runtime-gateway.ts';
-import { ensureDeviceReady } from '../device-ready.ts';
+import { ensureDeviceReady } from '../device/device-ready.ts';
 // Readiness is package-owned; hold the open at the fixture's platform-neutral readiness gate.
 import { awaitFixtureReadiness } from './application-lifecycle-runtime-fixture.ts';
 import { createRequestPlatformProviders } from '../../platform-runtime.ts';
diff --git a/src/daemon/__tests__/request-router-response-level.test.ts b/src/daemon/__tests__/request-router-response-level.test.ts
index 17a3cc5a72..c7fcbffb55 100644
--- a/src/daemon/__tests__/request-router-response-level.test.ts
+++ b/src/daemon/__tests__/request-router-response-level.test.ts
@@ -9,7 +9,7 @@ vi.mock('@agent-device/platform-apple/runner/operations', async (importOriginal)
   return { ...actual, stopIosRunnerSession: vi.fn(async () => {}) };
 });
 
-vi.mock('../device-ready.ts', () => ({ ensureDeviceReady: vi.fn(async () => {}) }));
+vi.mock('../device/device-ready.ts', () => ({ ensureDeviceReady: vi.fn(async () => {}) }));
 
 // Register a test view on a command whose payload this file controls end to end, so the router
 // graft mechanics can be exercised without the real snapshot handler (the actual snapshot view is
diff --git a/src/daemon/__tests__/request-router-session-address.test.ts b/src/daemon/__tests__/request-router-session-address.test.ts
index 16bbece3f1..4dfdffa237 100644
--- a/src/daemon/__tests__/request-router-session-address.test.ts
+++ b/src/daemon/__tests__/request-router-session-address.test.ts
@@ -5,7 +5,7 @@ import { test, expect, vi, beforeEach } from 'vitest';
 import path from 'node:path';
 import { getResolveTargetDeviceMock } from './request-router-dispatch-mocks.ts';
 
-vi.mock('../device-ready.ts', () => ({ ensureDeviceReady: vi.fn(async () => {}) }));
+vi.mock('../device/device-ready.ts', () => ({ ensureDeviceReady: vi.fn(async () => {}) }));
 vi.mock('@agent-device/host-kit/process', async (importOriginal) => {
   const actual = await importOriginal<typeof import('@agent-device/host-kit/process')>();
   return { ...actual, readProcessStartTime: vi.fn(() => 'test-process-start') };
@@ -26,7 +26,7 @@ import {
   lifecycleDeviceRuntimeGateway,
 } from './test-device-runtime-gateway.ts';
 import { LeaseRegistry } from '../lease-registry.ts';
-import { ensureDeviceReady } from '../device-ready.ts';
+import { ensureDeviceReady } from '../device/device-ready.ts';
 import { awaitFixtureReadiness } from './application-lifecycle-runtime-fixture.ts';
 import { makeSessionStore } from '../../__tests__/test-utils/store-factory.ts';
 import type { DeviceInfo } from '@agent-device/kernel/device';
diff --git a/src/daemon/__tests__/request-router-typed-error.test.ts b/src/daemon/__tests__/request-router-typed-error.test.ts
index 2c048f282b..bd54eb4d2b 100644
--- a/src/daemon/__tests__/request-router-typed-error.test.ts
+++ b/src/daemon/__tests__/request-router-typed-error.test.ts
@@ -11,7 +11,7 @@ vi.mock('@agent-device/platform-apple/runner/operations', async (importOriginal)
   return { ...actual, stopIosRunnerSession: vi.fn(async () => {}) };
 });
 
-vi.mock('../device-ready.ts', () => ({ ensureDeviceReady: vi.fn(async () => {}) }));
+vi.mock('../device/device-ready.ts', () => ({ ensureDeviceReady: vi.fn(async () => {}) }));
 
 import { dispatchApplicationLifecycleEffect } from './application-lifecycle-runtime-fixture.ts';
 import {
diff --git a/src/daemon/__tests__/request-runtime-binding.test.ts b/src/daemon/__tests__/request-runtime-binding.test.ts
index 6bd831fcce..a2ee437240 100644
--- a/src/daemon/__tests__/request-runtime-binding.test.ts
+++ b/src/daemon/__tests__/request-runtime-binding.test.ts
@@ -24,10 +24,10 @@ import {
   createRequestRuntimeBindings,
   ensureBoundDeviceReady,
 } from '../request-runtime-binding.ts';
-import { ensureDeviceReady } from '../device-ready.ts';
+import { ensureDeviceReady } from '../device/device-ready.ts';
 import { admitRuntimeUse } from '../runtime-admission.ts';
 
-vi.mock('../device-ready.ts', () => ({ ensureDeviceReady: vi.fn(async () => {}) }));
+vi.mock('../device/device-ready.ts', () => ({ ensureDeviceReady: vi.fn(async () => {}) }));
 
 const inspectPlan = resolveLogsRuntimePlan({ action: 'path' });
 const doctorPlan = resolveLogsRuntimePlan({ action: 'doctor' });
diff --git a/src/daemon/__tests__/session-device-resolution.test.ts b/src/daemon/__tests__/session-device-resolution.test.ts
index 45c5c37234..91c25796b3 100644
--- a/src/daemon/__tests__/session-device-resolution.test.ts
+++ b/src/daemon/__tests__/session-device-resolution.test.ts
@@ -9,7 +9,7 @@ import {
 import { appleSessionObservation } from '../../platform-runtime-apple-resources.ts';
 import { resolveTargetDevice } from '@agent-device/device-selection/dispatch-resolve';
 import { isActiveProviderDevice } from '../provider-device-admission.ts';
-import { ensureDeviceReady } from '../device-ready.ts';
+import { ensureDeviceReady } from '../device/device-ready.ts';
 
 vi.mock('../../platform-runtime-apple-resources.ts', async (importOriginal) => ({
   ...(await importOriginal<typeof import('../../platform-runtime-apple-resources.ts')>()),
@@ -21,7 +21,7 @@ vi.mock('@agent-device/device-selection/dispatch-resolve', () => ({
 vi.mock('../provider-device-admission.ts', () => ({
   isActiveProviderDevice: vi.fn(() => false),
 }));
-vi.mock('../device-ready.ts', () => ({
+vi.mock('../device/device-ready.ts', () => ({
   ensureDeviceReady: vi.fn(async () => {}),
 }));
 
diff --git a/src/daemon/__tests__/snapshot-runtime-binding.test.ts b/src/daemon/__tests__/snapshot-runtime-binding.test.ts
index e22112e463..e6f050cf43 100644
--- a/src/daemon/__tests__/snapshot-runtime-binding.test.ts
+++ b/src/daemon/__tests__/snapshot-runtime-binding.test.ts
@@ -11,9 +11,9 @@ import {
 } from '../snapshot-runtime-binding.ts';
 import type { DaemonRequest } from '../daemon-request.ts';
 import { snapshotRuntimeFixture } from './snapshot-runtime-fixture.ts';
-import { ensureDeviceReady } from '../device-ready.ts';
+import { ensureDeviceReady } from '../device/device-ready.ts';
 
-vi.mock('../device-ready.ts', () => ({ ensureDeviceReady: vi.fn(async () => {}) }));
+vi.mock('../device/device-ready.ts', () => ({ ensureDeviceReady: vi.fn(async () => {}) }));
 
 const mockEnsureDeviceReady = vi.mocked(ensureDeviceReady);
 
diff --git a/src/daemon/app-event-runtime.ts b/src/daemon/app-event-runtime.ts
index c72499faa9..0e0d83e68b 100644
--- a/src/daemon/app-event-runtime.ts
+++ b/src/daemon/app-event-runtime.ts
@@ -7,7 +7,7 @@ import { successText } from '@agent-device/kernel/success-text';
 import type { DaemonCommandContext } from './context.ts';
 import { admitRuntimeUse, type RuntimeAdmissionBindings } from './runtime-admission.ts';
 import { runtimeExecutionFromContext } from './snapshot-runtime-capture-input.ts';
-import type { DeviceReadyOptions } from './device-ready.ts';
+import type { DeviceReadyOptions } from './device/device-ready.ts';
 import type { DaemonFailureResponse } from '@agent-device/kernel/contracts';
 
 /**
diff --git a/src/daemon/__tests__/device-claim-admission.test.ts b/src/daemon/device/__tests__/device-claim-admission.test.ts
similarity index 97%
rename from src/daemon/__tests__/device-claim-admission.test.ts
rename to src/daemon/device/__tests__/device-claim-admission.test.ts
index 7829dde7bd..ae540a68db 100644
--- a/src/daemon/__tests__/device-claim-admission.test.ts
+++ b/src/daemon/device/__tests__/device-claim-admission.test.ts
@@ -9,20 +9,20 @@ import {
   type DeviceBindingIntent,
 } from '@agent-device/contracts/platform-runtime';
 import { asAppError } from '@agent-device/kernel/errors';
-import { ANDROID_EMULATOR } from '../../__tests__/test-utils/device-fixtures.ts';
+import { ANDROID_EMULATOR } from '../../../__tests__/test-utils/device-fixtures.ts';
 import {
   isolatedDeviceClaimStores,
   retainOrphanedDeviceClaims,
-} from '../../__tests__/test-utils/device-claim-store.ts';
+} from '../../../__tests__/test-utils/device-claim-store.ts';
 import { createDeviceClaimAdmission } from '../device-claim-admission.ts';
 import { acquireAllocatorHeldDeviceClaim } from '../device-claim-allocator.ts';
 import { abandonDeviceClaim, acquireDeviceClaim } from '../device-claims.ts';
 import { inspectDeviceClaims } from '../device-claim-inspection.ts';
 import { canonicalLocalDeviceKey, resolveDeviceClaimPath } from '../device-claim-paths.ts';
-import { createRequestExecutionScope } from '../request-execution-scope.ts';
-import { LeaseRegistry } from '../lease-registry.ts';
-import { SessionStore } from '../session-store.ts';
-import { unavailableDeviceRuntimeGateway } from './test-device-runtime-gateway.ts';
+import { createRequestExecutionScope } from '../../request-execution-scope.ts';
+import { LeaseRegistry } from '../../lease-registry.ts';
+import { SessionStore } from '../../session-store.ts';
+import { unavailableDeviceRuntimeGateway } from '../../__tests__/test-device-runtime-gateway.ts';
 import type { DeviceClaimPolicy } from '@agent-device/command-registry/types';
 
 const setup = isolatedDeviceClaimStores('agent-device-claim-admission-');
diff --git a/src/daemon/__tests__/device-claim-allocator.test.ts b/src/daemon/device/__tests__/device-claim-allocator.test.ts
similarity index 97%
rename from src/daemon/__tests__/device-claim-allocator.test.ts
rename to src/daemon/device/__tests__/device-claim-allocator.test.ts
index 500c9f7e6c..80bdc142fa 100644
--- a/src/daemon/__tests__/device-claim-allocator.test.ts
+++ b/src/daemon/device/__tests__/device-claim-allocator.test.ts
@@ -7,11 +7,11 @@ import {
   managedLocalRuntimeOwner,
   type DeviceBindingIntent,
 } from '@agent-device/contracts/platform-runtime';
-import { ANDROID_EMULATOR } from '../../__tests__/test-utils/device-fixtures.ts';
+import { ANDROID_EMULATOR } from '../../../__tests__/test-utils/device-fixtures.ts';
 import {
   isolatedDeviceClaimStores,
   retainOrphanedDeviceClaims,
-} from '../../__tests__/test-utils/device-claim-store.ts';
+} from '../../../__tests__/test-utils/device-claim-store.ts';
 import {
   acquireAllocatorHeldDeviceClaim,
   inspectAllocatorHeldDeviceClaim,
@@ -27,7 +27,7 @@ import { canonicalLocalDeviceKey, resolveDeviceClaimPath } from '../device-claim
 import { acquireDeviceClaim, deviceClaimIdentity } from '../device-claims.ts';
 
 vi.mock('@agent-device/host-kit/process', async (importOriginal) =>
-  (await import('../../__tests__/test-utils/host-process-mock.ts')).pinOwnProcessStartTime(
+  (await import('../../../__tests__/test-utils/host-process-mock.ts')).pinOwnProcessStartTime(
     importOriginal,
   ),
 );
diff --git a/src/daemon/__tests__/device-claim-conflict.test.ts b/src/daemon/device/__tests__/device-claim-conflict.test.ts
similarity index 100%
rename from src/daemon/__tests__/device-claim-conflict.test.ts
rename to src/daemon/device/__tests__/device-claim-conflict.test.ts
diff --git a/src/daemon/__tests__/device-claim-owner-recovery.test.ts b/src/daemon/device/__tests__/device-claim-owner-recovery.test.ts
similarity index 100%
rename from src/daemon/__tests__/device-claim-owner-recovery.test.ts
rename to src/daemon/device/__tests__/device-claim-owner-recovery.test.ts
diff --git a/src/daemon/__tests__/device-claim-prune.test.ts b/src/daemon/device/__tests__/device-claim-prune.test.ts
similarity index 96%
rename from src/daemon/__tests__/device-claim-prune.test.ts
rename to src/daemon/device/__tests__/device-claim-prune.test.ts
index 6c9569cb2b..681ca01179 100644
--- a/src/daemon/__tests__/device-claim-prune.test.ts
+++ b/src/daemon/device/__tests__/device-claim-prune.test.ts
@@ -8,13 +8,13 @@ import { acquireAllocatorHeldDeviceClaim } from '../device-claim-allocator.ts';
 import { canonicalLocalDeviceKey, resolveDeviceClaimPath } from '../device-claim-paths.ts';
 import { acquireProcessLock } from '@agent-device/host-kit/file';
 import { readCurrentOwnerIdentity } from '@agent-device/host-kit/process';
-import { ANDROID_EMULATOR } from '../../__tests__/test-utils/device-fixtures.ts';
-import { publishDaemonRegistration } from '../../__tests__/test-utils/device-claim-store.ts';
+import { ANDROID_EMULATOR } from '../../../__tests__/test-utils/device-fixtures.ts';
+import { publishDaemonRegistration } from '../../../__tests__/test-utils/device-claim-store.ts';
 
-import { mkdtempForTestSync } from '../../__tests__/test-utils/tmp-dir.ts';
+import { mkdtempForTestSync } from '../../../__tests__/test-utils/tmp-dir.ts';
 
 vi.mock('@agent-device/host-kit/process', async (importOriginal) =>
-  (await import('../../__tests__/test-utils/host-process-mock.ts')).pinOwnProcessStartTime(
+  (await import('../../../__tests__/test-utils/host-process-mock.ts')).pinOwnProcessStartTime(
     importOriginal,
   ),
 );
diff --git a/src/daemon/__tests__/device-claim-reboot.test.ts b/src/daemon/device/__tests__/device-claim-reboot.test.ts
similarity index 100%
rename from src/daemon/__tests__/device-claim-reboot.test.ts
rename to src/daemon/device/__tests__/device-claim-reboot.test.ts
diff --git a/src/daemon/__tests__/device-claim-reconciliation.test.ts b/src/daemon/device/__tests__/device-claim-reconciliation.test.ts
similarity index 95%
rename from src/daemon/__tests__/device-claim-reconciliation.test.ts
rename to src/daemon/device/__tests__/device-claim-reconciliation.test.ts
index e8531a5dce..f9a9052b1f 100644
--- a/src/daemon/__tests__/device-claim-reconciliation.test.ts
+++ b/src/daemon/device/__tests__/device-claim-reconciliation.test.ts
@@ -8,13 +8,13 @@ import {
   localRuntimeOwner,
 } from '@agent-device/contracts/platform-runtime';
 import type { PlatformRuntimeOperations } from '@agent-device/contracts/platform-runtime-operations';
-import { createTestAppLogLiveHandle } from '../../__tests__/test-utils/app-log-live-handle.ts';
-import { unavailableDeploymentSnapshotAndShutdownOperationFacts } from '../../__tests__/test-utils/runtime-operation-facts.ts';
-import { mkdtempForTestSync } from '../../__tests__/test-utils/tmp-dir.ts';
+import { createTestAppLogLiveHandle } from '../../../__tests__/test-utils/app-log-live-handle.ts';
+import { unavailableDeploymentSnapshotAndShutdownOperationFacts } from '../../../__tests__/test-utils/runtime-operation-facts.ts';
+import { mkdtempForTestSync } from '../../../__tests__/test-utils/tmp-dir.ts';
 import { createDeviceClaimReconciler } from '../device-claim-reconciliation.ts';
 import type { AllocatorHeldDeviceClaim, DeviceClaim } from '../device-claim-record.ts';
 import type { DeviceClaimReconciler } from '../device-claims.ts';
-import { appLogResourceStore } from '../app-log-resource-store.ts';
+import { appLogResourceStore } from '../../app-log-resource-store.ts';
 
 const scope = {
   signal: new AbortController().signal,
diff --git a/src/daemon/__tests__/device-claim-record.test.ts b/src/daemon/device/__tests__/device-claim-record.test.ts
similarity index 100%
rename from src/daemon/__tests__/device-claim-record.test.ts
rename to src/daemon/device/__tests__/device-claim-record.test.ts
diff --git a/src/daemon/__tests__/device-claim-rule.test.ts b/src/daemon/device/__tests__/device-claim-rule.test.ts
similarity index 100%
rename from src/daemon/__tests__/device-claim-rule.test.ts
rename to src/daemon/device/__tests__/device-claim-rule.test.ts
diff --git a/src/daemon/__tests__/device-claim-settlement.test.ts b/src/daemon/device/__tests__/device-claim-settlement.test.ts
similarity index 98%
rename from src/daemon/__tests__/device-claim-settlement.test.ts
rename to src/daemon/device/__tests__/device-claim-settlement.test.ts
index cf3af9e79b..a8c89e3cc4 100644
--- a/src/daemon/__tests__/device-claim-settlement.test.ts
+++ b/src/daemon/device/__tests__/device-claim-settlement.test.ts
@@ -8,10 +8,10 @@ import { canonicalLocalDeviceKey } from '../device-claim-paths.ts';
 import { inspectDeviceClaims } from '../device-claim-inspection.ts';
 import type { DeviceBootObservationService } from '@agent-device/contracts/device-boot';
 import type { DeviceInfo } from '@agent-device/kernel/device';
-import { mkdtempForTestSync } from '../../__tests__/test-utils/tmp-dir.ts';
-import { publishDaemonRegistration } from '../../__tests__/test-utils/device-claim-store.ts';
+import { mkdtempForTestSync } from '../../../__tests__/test-utils/tmp-dir.ts';
+import { publishDaemonRegistration } from '../../../__tests__/test-utils/device-claim-store.ts';
 vi.mock('@agent-device/host-kit/process', async (importOriginal) =>
-  (await import('../../__tests__/test-utils/host-process-mock.ts')).pinOwnProcessStartTime(
+  (await import('../../../__tests__/test-utils/host-process-mock.ts')).pinOwnProcessStartTime(
     importOriginal,
   ),
 );
diff --git a/src/daemon/__tests__/device-claims.test.ts b/src/daemon/device/__tests__/device-claims.test.ts
similarity index 99%
rename from src/daemon/__tests__/device-claims.test.ts
rename to src/daemon/device/__tests__/device-claims.test.ts
index a3d66d4f6f..e14b03a99a 100644
--- a/src/daemon/__tests__/device-claims.test.ts
+++ b/src/daemon/device/__tests__/device-claims.test.ts
@@ -14,13 +14,13 @@ import { acquireAllocatorHeldDeviceClaim } from '../device-claim-allocator.ts';
 import { canonicalLocalDeviceKey } from '../device-claim-paths.ts';
 import { inspectDeviceClaims } from '../device-claim-inspection.ts';
 import type { DeviceInfo } from '@agent-device/kernel/device';
-import { mkdtempForTestSync } from '../../__tests__/test-utils/tmp-dir.ts';
-import { publishDaemonRegistration } from '../../__tests__/test-utils/device-claim-store.ts';
+import { mkdtempForTestSync } from '../../../__tests__/test-utils/tmp-dir.ts';
+import { publishDaemonRegistration } from '../../../__tests__/test-utils/device-claim-store.ts';
 import { readCurrentOwnerIdentity } from '@agent-device/host-kit/process';
 import { acquireProcessLock } from '@agent-device/host-kit/file';
 
 vi.mock('@agent-device/host-kit/process', async (importOriginal) =>
-  (await import('../../__tests__/test-utils/host-process-mock.ts')).pinOwnProcessStartTime(
+  (await import('../../../__tests__/test-utils/host-process-mock.ts')).pinOwnProcessStartTime(
     importOriginal,
   ),
 );
diff --git a/src/daemon/__tests__/device-mutation-drain.test.ts b/src/daemon/device/__tests__/device-mutation-drain.test.ts
similarity index 96%
rename from src/daemon/__tests__/device-mutation-drain.test.ts
rename to src/daemon/device/__tests__/device-mutation-drain.test.ts
index 6c5a76cde6..48ccb69020 100644
--- a/src/daemon/__tests__/device-mutation-drain.test.ts
+++ b/src/daemon/device/__tests__/device-mutation-drain.test.ts
@@ -1,4 +1,4 @@
-import { createControlLatch } from './human-control-fixtures.ts';
+import { createControlLatch } from '../../__tests__/human-control-fixtures.ts';
 import assert from 'node:assert/strict';
 import { test } from 'vitest';
 import { DeviceMutationDrain } from '../device-mutation-drain.ts';
diff --git a/src/daemon/__tests__/device-ready.test.ts b/src/daemon/device/__tests__/device-ready.test.ts
similarity index 98%
rename from src/daemon/__tests__/device-ready.test.ts
rename to src/daemon/device/__tests__/device-ready.test.ts
index a85abf427f..2008db70b3 100644
--- a/src/daemon/__tests__/device-ready.test.ts
+++ b/src/daemon/device/__tests__/device-ready.test.ts
@@ -26,7 +26,7 @@ import {
   ANDROID_EMULATOR,
   IOS_DEVICE,
   IOS_SIMULATOR,
-} from '../../__tests__/test-utils/device-fixtures.ts';
+} from '../../../__tests__/test-utils/device-fixtures.ts';
 import { DEVICE_READY_CACHE_TTL_MS, ensureDeviceReady } from '../device-ready.ts';
 
 const mockRunCmd = vi.mocked(runCmd);
diff --git a/src/daemon/device-claim-admission.ts b/src/daemon/device/device-claim-admission.ts
similarity index 100%
rename from src/daemon/device-claim-admission.ts
rename to src/daemon/device/device-claim-admission.ts
diff --git a/src/daemon/device-claim-allocator.ts b/src/daemon/device/device-claim-allocator.ts
similarity index 100%
rename from src/daemon/device-claim-allocator.ts
rename to src/daemon/device/device-claim-allocator.ts
diff --git a/src/daemon/device-claim-conflict.ts b/src/daemon/device/device-claim-conflict.ts
similarity index 99%
rename from src/daemon/device-claim-conflict.ts
rename to src/daemon/device/device-claim-conflict.ts
index c628e04e59..b003ca2bb3 100644
--- a/src/daemon/device-claim-conflict.ts
+++ b/src/daemon/device/device-claim-conflict.ts
@@ -15,7 +15,7 @@ import {
   type DeviceClaimClassification,
   type InspectedDeviceClaim,
 } from './device-claim-inspection.ts';
-import type { DaemonResponse } from './daemon-request.ts';
+import type { DaemonResponse } from '../daemon-request.ts';
 import { errorResponse } from '@agent-device/kernel/contracts';
 import type { DeviceClaimConflictReason } from '@agent-device/contracts/device';
 
diff --git a/src/daemon/device-claim-inspection.ts b/src/daemon/device/device-claim-inspection.ts
similarity index 99%
rename from src/daemon/device-claim-inspection.ts
rename to src/daemon/device/device-claim-inspection.ts
index 042ddd0875..616ffe4bb4 100644
--- a/src/daemon/device-claim-inspection.ts
+++ b/src/daemon/device/device-claim-inspection.ts
@@ -7,7 +7,7 @@ import {
   readHostProcessIdentityObservations,
 } from '@agent-device/host-kit/process';
 
-import { isSupersededDaemonOwner } from './daemon-registration.ts';
+import { isSupersededDaemonOwner } from '../daemon-registration.ts';
 import { resolveDeviceClaimRoot } from './device-claim-paths.ts';
 import {
   decodeStoredDeviceClaim,
diff --git a/src/daemon/device-claim-owner-recovery.ts b/src/daemon/device/device-claim-owner-recovery.ts
similarity index 93%
rename from src/daemon/device-claim-owner-recovery.ts
rename to src/daemon/device/device-claim-owner-recovery.ts
index 7c16c759b5..c8b60069ee 100644
--- a/src/daemon/device-claim-owner-recovery.ts
+++ b/src/daemon/device/device-claim-owner-recovery.ts
@@ -1,10 +1,10 @@
 import type { PlatformRequestScope } from '@agent-device/contracts/platform-runtime-host';
 import { createOwnedProcessRecordStore } from '@agent-device/host-kit/process';
-import { createPlatformRuntimeGateway } from '../platform-runtime.ts';
-import { resolveDaemonPaths } from '../daemon-resolution.ts';
+import { createPlatformRuntimeGateway } from '../../platform-runtime.ts';
+import { resolveDaemonPaths } from '../../daemon-resolution.ts';
 import { createDeviceClaimReconciler } from './device-claim-reconciliation.ts';
 import type { DeviceClaimReconciler } from './device-claims.ts';
-import { SessionStore } from './session-store.ts';
+import { SessionStore } from '../session-store.ts';
 
 export type OwnerScopedClaimRecovery = {
   reconcile: DeviceClaimReconciler;
diff --git a/src/daemon/device-claim-paths.ts b/src/daemon/device/device-claim-paths.ts
similarity index 100%
rename from src/daemon/device-claim-paths.ts
rename to src/daemon/device/device-claim-paths.ts
diff --git a/src/daemon/device-claim-reboot.ts b/src/daemon/device/device-claim-reboot.ts
similarity index 100%
rename from src/daemon/device-claim-reboot.ts
rename to src/daemon/device/device-claim-reboot.ts
diff --git a/src/daemon/device-claim-reconciliation.ts b/src/daemon/device/device-claim-reconciliation.ts
similarity index 96%
rename from src/daemon/device-claim-reconciliation.ts
rename to src/daemon/device/device-claim-reconciliation.ts
index fb9f9189f7..fa45f94174 100644
--- a/src/daemon/device-claim-reconciliation.ts
+++ b/src/daemon/device/device-claim-reconciliation.ts
@@ -4,9 +4,9 @@ import type { PlatformRequestScope } from '@agent-device/contracts/platform-runt
 import type { PlatformRuntimeOperations } from '@agent-device/contracts/platform-runtime-operations';
 import { sameDeviceIdentity } from '@agent-device/kernel/device';
 import { emitDiagnostic } from '@agent-device/host-kit/diagnostics';
-import { resolveDaemonPaths } from '../daemon-resolution.ts';
-import { appLogDurableResource } from './app-log-session-resource.ts';
-import { recoverAppLogResourceAfterDaemonLock } from './app-log-resource-recovery.ts';
+import { resolveDaemonPaths } from '../../daemon-resolution.ts';
+import { appLogDurableResource } from '../app-log-session-resource.ts';
+import { recoverAppLogResourceAfterDaemonLock } from '../app-log-resource-recovery.ts';
 import type { DeviceClaim } from './device-claim-record.ts';
 import type { DeviceClaimReconciler } from './device-claims.ts';
 import type { DurableCaptureRecoveryOutcome } from '@agent-device/capture-kit/durable-capture';
diff --git a/src/daemon/device-claim-record.ts b/src/daemon/device/device-claim-record.ts
similarity index 100%
rename from src/daemon/device-claim-record.ts
rename to src/daemon/device/device-claim-record.ts
diff --git a/src/daemon/device-claim-rule.ts b/src/daemon/device/device-claim-rule.ts
similarity index 100%
rename from src/daemon/device-claim-rule.ts
rename to src/daemon/device/device-claim-rule.ts
diff --git a/src/daemon/device-claim-settlement.ts b/src/daemon/device/device-claim-settlement.ts
similarity index 100%
rename from src/daemon/device-claim-settlement.ts
rename to src/daemon/device/device-claim-settlement.ts
diff --git a/src/daemon/device-claim-store.ts b/src/daemon/device/device-claim-store.ts
similarity index 100%
rename from src/daemon/device-claim-store.ts
rename to src/daemon/device/device-claim-store.ts
diff --git a/src/daemon/device-claims.ts b/src/daemon/device/device-claims.ts
similarity index 100%
rename from src/daemon/device-claims.ts
rename to src/daemon/device/device-claims.ts
diff --git a/src/daemon/device-mutation-drain.ts b/src/daemon/device/device-mutation-drain.ts
similarity index 100%
rename from src/daemon/device-mutation-drain.ts
rename to src/daemon/device/device-mutation-drain.ts
diff --git a/src/daemon/device-ready.ts b/src/daemon/device/device-ready.ts
similarity index 89%
rename from src/daemon/device-ready.ts
rename to src/daemon/device/device-ready.ts
index 0592781b6f..bbe1b0c880 100644
--- a/src/daemon/device-ready.ts
+++ b/src/daemon/device/device-ready.ts
@@ -1,6 +1,6 @@
 import type { DeviceInfo } from '@agent-device/kernel/device';
-import { ensureLocalPlatformDeviceReady } from '../platform-runtime-device-ready.ts';
-import { isActiveProviderDevice } from './provider-device-admission.ts';
+import { ensureLocalPlatformDeviceReady } from '../../platform-runtime-device-ready.ts';
+import { isActiveProviderDevice } from '../provider-device-admission.ts';
 import { createTtlMemo } from '@agent-device/kernel/ttl-memo';
 
 // Exported so unit tests can assert TTL behavior without duplicating the value.
diff --git a/src/daemon/device-selector-intent.ts b/src/daemon/device/device-selector-intent.ts
similarity index 100%
rename from src/daemon/device-selector-intent.ts
rename to src/daemon/device/device-selector-intent.ts
diff --git a/src/daemon/device-targets.ts b/src/daemon/device/device-targets.ts
similarity index 100%
rename from src/daemon/device-targets.ts
rename to src/daemon/device/device-targets.ts
diff --git a/src/daemon/handlers/__tests__/session-boot-shutdown-device-claims.test.ts b/src/daemon/handlers/__tests__/session-boot-shutdown-device-claims.test.ts
index eefdd47d34..8c1b619c22 100644
--- a/src/daemon/handlers/__tests__/session-boot-shutdown-device-claims.test.ts
+++ b/src/daemon/handlers/__tests__/session-boot-shutdown-device-claims.test.ts
@@ -15,8 +15,8 @@ import {
 } from '../../../__tests__/test-utils/device-claim-store.ts';
 import { SessionStore } from '../../session-store.ts';
 import { LeaseRegistry } from '../../lease-registry.ts';
-import { acquireDeviceClaim } from '../../device-claims.ts';
-import { inspectDeviceClaims } from '../../device-claim-inspection.ts';
+import { acquireDeviceClaim } from '../../device/device-claims.ts';
+import { inspectDeviceClaims } from '../../device/device-claim-inspection.ts';
 import { createRequestExecutionScope } from '../../request-execution-scope.ts';
 import { handleSessionStateCommands } from '../session-state.ts';
 import type { DaemonRequest, DaemonResponse } from '../../daemon-request.ts';
diff --git a/src/daemon/handlers/__tests__/session-device-claims.test.ts b/src/daemon/handlers/__tests__/session-device-claims.test.ts
index 8b4e583526..d45941b2c1 100644
--- a/src/daemon/handlers/__tests__/session-device-claims.test.ts
+++ b/src/daemon/handlers/__tests__/session-device-claims.test.ts
@@ -16,7 +16,7 @@ vi.mock('@agent-device/device-selection/dispatch-resolve', async (importOriginal
     resolveTargetDeviceSelection: vi.fn(selectionFromResolveTargetDevice(resolveTargetDevice)),
   };
 });
-vi.mock('../../device-ready.ts', () => ({ ensureDeviceReady: vi.fn(async () => {}) }));
+vi.mock('../../device/device-ready.ts', () => ({ ensureDeviceReady: vi.fn(async () => {}) }));
 vi.mock('../../../platform-runtime-runtime-hints.ts', async (importOriginal) => {
   const actual =
     await importOriginal<typeof import('../../../platform-runtime-runtime-hints.ts')>();
@@ -38,7 +38,7 @@ vi.mock('@agent-device/host-kit/process', async (importOriginal) =>
 );
 
 import { resolveTargetDevice } from '@agent-device/device-selection/dispatch-resolve';
-import { ensureDeviceReady } from '../../device-ready.ts';
+import { ensureDeviceReady } from '../../device/device-ready.ts';
 import { applyRuntimeHintValues } from '../../../platform-runtime-runtime-hints.ts';
 import {
   activateAndroidTestIme,
@@ -49,8 +49,8 @@ import {
   dispatchApplicationLifecycleEffect,
 } from '../../__tests__/application-lifecycle-runtime-fixture.ts';
 import { clearRequestCanceled, markRequestCanceled } from '@agent-device/host-kit/request';
-import { acquireDeviceClaim as acquireProductionDeviceClaim } from '../../device-claims.ts';
-import { inspectDeviceClaims } from '../../device-claim-inspection.ts';
+import { acquireDeviceClaim as acquireProductionDeviceClaim } from '../../device/device-claims.ts';
+import { inspectDeviceClaims } from '../../device/device-claim-inspection.ts';
 import { LeaseRegistry } from '../../lease-registry.ts';
 import { SessionStore } from '../../session-store.ts';
 import {
diff --git a/src/daemon/handlers/__tests__/session-relaunch-close.test.ts b/src/daemon/handlers/__tests__/session-relaunch-close.test.ts
index 573ed6f3cf..2b71e6c3f9 100644
--- a/src/daemon/handlers/__tests__/session-relaunch-close.test.ts
+++ b/src/daemon/handlers/__tests__/session-relaunch-close.test.ts
@@ -20,7 +20,7 @@ vi.mock('node:timers/promises', async (importOriginal) => {
   const actual = await importOriginal<typeof import('node:timers/promises')>();
   return { ...actual, setTimeout: vi.fn(async () => undefined) };
 });
-vi.mock('../../device-ready.ts', () => ({ ensureDeviceReady: vi.fn(async () => {}) }));
+vi.mock('../../device/device-ready.ts', () => ({ ensureDeviceReady: vi.fn(async () => {}) }));
 vi.mock('@agent-device/platform-apple/runner/operations', async (importOriginal) => {
   const actual =
     await importOriginal<typeof import('@agent-device/platform-apple/runner/operations')>();
@@ -67,7 +67,7 @@ import {
   awaitFixtureReadiness,
   discoverReadyAndroidEmulators,
 } from '../../__tests__/application-lifecycle-runtime-fixture.ts';
-import { ensureDeviceReady } from '../../device-ready.ts';
+import { ensureDeviceReady } from '../../device/device-ready.ts';
 import {
   prewarmIosRunnerSession,
   notifyIosRunnerAppRelaunched,
diff --git a/src/daemon/handlers/__tests__/session-test-harness.ts b/src/daemon/handlers/__tests__/session-test-harness.ts
index 6288852025..be74fce5ec 100644
--- a/src/daemon/handlers/__tests__/session-test-harness.ts
+++ b/src/daemon/handlers/__tests__/session-test-harness.ts
@@ -25,7 +25,7 @@ vi.mock('@agent-device/device-selection/dispatch-resolve', async (importOriginal
     resolveTargetDeviceSelection: vi.fn(selectionFromResolveTargetDevice(resolveTargetDevice)),
   };
 });
-vi.mock('../../device-ready.ts', () => ({ ensureDeviceReady: vi.fn(async () => {}) }));
+vi.mock('../../device/device-ready.ts', () => ({ ensureDeviceReady: vi.fn(async () => {}) }));
 vi.mock('../../../platform-runtime-runtime-hints.ts', async (importOriginal) => {
   const actual =
     await importOriginal<typeof import('../../../platform-runtime-runtime-hints.ts')>();
@@ -92,7 +92,7 @@ import { SessionStore } from '../../session-store.ts';
 import type { DaemonRequest, DaemonResponse } from '../../daemon-request.ts';
 import type { SessionState } from '../../session-state.ts';
 import { resolveTargetDevice } from '@agent-device/device-selection/dispatch-resolve';
-import { ensureDeviceReady } from '../../device-ready.ts';
+import { ensureDeviceReady } from '../../device/device-ready.ts';
 import {
   applyRuntimeHintValues,
   clearRuntimeHintValues,
diff --git a/src/daemon/handlers/__tests__/wait-landmark-recording.test.ts b/src/daemon/handlers/__tests__/wait-landmark-recording.test.ts
index 6b9e9a6a4a..fca72e152e 100644
--- a/src/daemon/handlers/__tests__/wait-landmark-recording.test.ts
+++ b/src/daemon/handlers/__tests__/wait-landmark-recording.test.ts
@@ -38,7 +38,7 @@ vi.mock('../../snapshot-interactor-capture.ts', async () => {
   return { captureSnapshotWithInteractor: fixture.captureSnapshotThroughLegacyDispatchFixture };
 });
 
-vi.mock('../../device-ready.ts', () => ({
+vi.mock('../../device/device-ready.ts', () => ({
   ensureDeviceReady: vi.fn(async () => {}),
 }));
 
diff --git a/src/daemon/handlers/session-command-input.ts b/src/daemon/handlers/session-command-input.ts
index d3e4902b80..4daf14fb47 100644
--- a/src/daemon/handlers/session-command-input.ts
+++ b/src/daemon/handlers/session-command-input.ts
@@ -7,7 +7,7 @@ import type { AppLogAdmissionLedger } from '../app-log-admission-ledger.ts';
 import { type AudioProbeAdmissionLedger } from '@agent-device/capture-kit/audio-probe-admission-ledger';
 import { type PerfCaptureAdmissionLedger } from '@agent-device/capture-kit/perf-capture-admission-ledger';
 import { type ScreenRecordingAdmissionLedger } from '@agent-device/capture-kit/screen-recording-admission-ledger';
-import type { DeviceClaimReconciler } from '../device-claims.ts';
+import type { DeviceClaimReconciler } from '../device/device-claims.ts';
 import type { LeaseRegistry } from '../lease-registry.ts';
 import type {
   BindDeviceRuntime,
diff --git a/src/daemon/handlers/session-selector-dispatch.ts b/src/daemon/handlers/session-selector-dispatch.ts
index 62a5217786..eba1058808 100644
--- a/src/daemon/handlers/session-selector-dispatch.ts
+++ b/src/daemon/handlers/session-selector-dispatch.ts
@@ -16,7 +16,7 @@ import { expireRefFrame } from '../ref-frame.ts';
 import { resolveSessionAppBundleIdForTarget } from '../../platform-runtime-open-target.ts';
 import type { BindDeviceRuntime, InspectDeviceRuntimeFacts } from '../request-runtime-binding.ts';
 import type { DaemonCommandContext } from '../context.ts';
-import type { DeviceReadyOptions } from '../device-ready.ts';
+import type { DeviceReadyOptions } from '../device/device-ready.ts';
 import { errorResponse } from '@agent-device/kernel/contracts';
 
 /**
diff --git a/src/daemon/keyboard-runtime.ts b/src/daemon/keyboard-runtime.ts
index 9dbb2da3b7..69b12aeee1 100644
--- a/src/daemon/keyboard-runtime.ts
+++ b/src/daemon/keyboard-runtime.ts
@@ -29,7 +29,7 @@ import {
   type RuntimeAdmissionRequest,
 } from './runtime-admission.ts';
 import { runtimeExecutionFromContext } from './snapshot-runtime-capture-input.ts';
-import type { DeviceReadyOptions } from './device-ready.ts';
+import type { DeviceReadyOptions } from './device/device-ready.ts';
 import type { DaemonFailureResponse } from '@agent-device/kernel/contracts';
 
 type KeyboardRuntimeAction = 'status' | 'dismiss' | 'enter';
diff --git a/src/daemon/lease-lifecycle.ts b/src/daemon/lease-lifecycle.ts
index 1a77a4f626..cc70befb02 100644
--- a/src/daemon/lease-lifecycle.ts
+++ b/src/daemon/lease-lifecycle.ts
@@ -1,6 +1,6 @@
 import { emitDiagnostic } from '@agent-device/host-kit/diagnostics';
 import { leaseScopeToReleaseRequest } from '@agent-device/contracts/lease-scope';
-import { clearDeviceClaim } from './device-claims.ts';
+import { clearDeviceClaim } from './device/device-claims.ts';
 import type { LeaseRegistry } from './lease-registry.ts';
 import type {
   DeviceLease,
diff --git a/src/daemon/lease-registry.ts b/src/daemon/lease-registry.ts
index b8c722b854..af8683d417 100644
--- a/src/daemon/lease-registry.ts
+++ b/src/daemon/lease-registry.ts
@@ -25,7 +25,7 @@ import {
   leaseDeviceBindingKey,
   leaseRunBindingKey,
 } from './lease-registry-scope.ts';
-import { DeviceMutationDrain } from './device-mutation-drain.ts';
+import { DeviceMutationDrain } from './device/device-mutation-drain.ts';
 import {
   type LeaseWorkPass,
   type LeaseWorkWanted,
diff --git a/src/daemon/replay/internal/__tests__/session-test-infrastructure.test.ts b/src/daemon/replay/internal/__tests__/session-test-infrastructure.test.ts
index 771c0c3c5e..3649ce82a5 100644
--- a/src/daemon/replay/internal/__tests__/session-test-infrastructure.test.ts
+++ b/src/daemon/replay/internal/__tests__/session-test-infrastructure.test.ts
@@ -1,7 +1,7 @@
 import { test } from 'vitest';
 import assert from 'node:assert/strict';
 import { isReplayInfrastructureFailure } from '../session-test-infrastructure.ts';
-import { ALLOCATOR_CLAIM_MISSING } from '../../../device-claim-conflict.ts';
+import { ALLOCATOR_CLAIM_MISSING } from '../../../device/device-claim-conflict.ts';
 import type { DaemonResponse } from '../../../daemon-request.ts';
 import type { ReplaySuiteTestResult } from '@agent-device/contracts/replay';
 
diff --git a/src/daemon/request-binding.ts b/src/daemon/request-binding.ts
index cff557a635..488d7514b4 100644
--- a/src/daemon/request-binding.ts
+++ b/src/daemon/request-binding.ts
@@ -1,5 +1,5 @@
 import { resolveTargetDevice } from '@agent-device/device-selection/dispatch-resolve';
-import { hasDeviceSelectionInput } from './device-selector-intent.ts';
+import { hasDeviceSelectionInput } from './device/device-selector-intent.ts';
 import { applyRequestLockPolicy } from './request-lock-policy.ts';
 import { buildOpenTargetDeviceResolutionOptions } from '@agent-device/device-selection/open-target';
 import { buildReplayTargetDeviceResolution } from './replay-device-selection.ts';
diff --git a/src/daemon/request-execution-scope.ts b/src/daemon/request-execution-scope.ts
index c4a65011a0..193b2eaaa7 100644
--- a/src/daemon/request-execution-scope.ts
+++ b/src/daemon/request-execution-scope.ts
@@ -59,8 +59,11 @@ import {
   type InspectDeviceRuntimeFacts,
   type RequestRuntimeBindings,
 } from './request-runtime-binding.ts';
-import { createDeviceClaimAdmission, type DeviceClaimAdmission } from './device-claim-admission.ts';
-import { createOwnerScopedDeviceClaimReconciler } from './device-claim-owner-recovery.ts';
+import {
+  createDeviceClaimAdmission,
+  type DeviceClaimAdmission,
+} from './device/device-claim-admission.ts';
+import { createOwnerScopedDeviceClaimReconciler } from './device/device-claim-owner-recovery.ts';
 import {
   applyCommandDefaults,
   resolveCommandDeviceClaimPolicy,
diff --git a/src/daemon/request-handler-chain.ts b/src/daemon/request-handler-chain.ts
index 15af5b35d5..8884506f2a 100644
--- a/src/daemon/request-handler-chain.ts
+++ b/src/daemon/request-handler-chain.ts
@@ -14,7 +14,7 @@ import type {
   BindExactDeviceRuntime,
   InspectDeviceRuntimeFacts,
 } from './request-runtime-binding.ts';
-import type { DeviceClaimReconciler } from './device-claims.ts';
+import type { DeviceClaimReconciler } from './device/device-claims.ts';
 import type { AppLogAdmissionLedger } from './app-log-admission-ledger.ts';
 import { type AudioProbeAdmissionLedger } from '@agent-device/capture-kit/audio-probe-admission-ledger';
 import { type PerfCaptureAdmissionLedger } from '@agent-device/capture-kit/perf-capture-admission-ledger';
diff --git a/src/daemon/request-lock-policy.ts b/src/daemon/request-lock-policy.ts
index 8f635c9508..105233cda0 100644
--- a/src/daemon/request-lock-policy.ts
+++ b/src/daemon/request-lock-policy.ts
@@ -15,7 +15,7 @@ import {
 } from '@agent-device/kernel/device';
 import { buildSessionRecoveryHint, describeSessionDevice } from './session-recovery-hints.ts';
 import { shellQuoteIfNeeded } from '@agent-device/kernel/device-shell';
-import { hasLockableDeviceSelector, hasSelectorValue } from './device-selector-intent.ts';
+import { hasLockableDeviceSelector, hasSelectorValue } from './device/device-selector-intent.ts';
 import { canOverrideLockPolicySelector } from './daemon-command-registry.ts';
 
 type LockPlatform = NonNullable<DaemonRequest['meta']>['lockPlatform'];
diff --git a/src/daemon/request-platform-provider-context.ts b/src/daemon/request-platform-provider-context.ts
index 8e2b824894..08f19d3cf3 100644
--- a/src/daemon/request-platform-provider-context.ts
+++ b/src/daemon/request-platform-provider-context.ts
@@ -1,6 +1,9 @@
 import type { PlatformProviderRequestContext } from '@agent-device/contracts/platform-providers';
 import { resolveTargetDevice } from '@agent-device/device-selection/dispatch-resolve';
-import { hasDeviceSelectionInput, hasExplicitDeviceSelector } from './device-selector-intent.ts';
+import {
+  hasDeviceSelectionInput,
+  hasExplicitDeviceSelector,
+} from './device/device-selector-intent.ts';
 import { buildOpenTargetDeviceResolutionOptions } from '@agent-device/device-selection/open-target';
 import { resolveProviderDeviceResolutionIntent } from './daemon-command-registry.ts';
 import type { DaemonRequest } from './daemon-request.ts';
diff --git a/src/daemon/request-router.ts b/src/daemon/request-router.ts
index a4c5ca31c4..5ccf01d9e0 100644
--- a/src/daemon/request-router.ts
+++ b/src/daemon/request-router.ts
@@ -56,7 +56,7 @@ import { canRunReplayScopedAction } from './daemon-command-registry.ts';
 import { isWebSession } from './web-session-names.ts';
 import { inferFillText } from '@agent-device/ad-script';
 import { createPlatformRequestScope } from './platform-request-scope.ts';
-import { createOwnerScopedDeviceClaimReconciler } from './device-claim-owner-recovery.ts';
+import { createOwnerScopedDeviceClaimReconciler } from './device/device-claim-owner-recovery.ts';
 import {
   createAppLogAdmissionLedger,
   type AppLogAdmissionLedger,
diff --git a/src/daemon/request-runtime-binding.ts b/src/daemon/request-runtime-binding.ts
index acb486dea9..b756188de2 100644
--- a/src/daemon/request-runtime-binding.ts
+++ b/src/daemon/request-runtime-binding.ts
@@ -15,7 +15,7 @@ import {
 } from '@agent-device/contracts/platform-runtime';
 import type { PlatformRequestScope } from '@agent-device/contracts/platform-runtime-host';
 import type { PlatformRuntimeOperations } from '@agent-device/contracts/platform-runtime-operations';
-import { ensureDeviceReady, type DeviceReadyOptions } from './device-ready.ts';
+import { ensureDeviceReady, type DeviceReadyOptions } from './device/device-ready.ts';
 import type {
   ManagedRequestAdmission,
   ResolveManagedRequestLease,
diff --git a/src/daemon/runtime-admission.ts b/src/daemon/runtime-admission.ts
index b91d83f601..b976c7d913 100644
--- a/src/daemon/runtime-admission.ts
+++ b/src/daemon/runtime-admission.ts
@@ -13,7 +13,7 @@ import type {
   RuntimeAdmissionBindings,
 } from './request-runtime-binding.ts';
 import { ensureBoundDeviceReady } from './request-runtime-binding.ts';
-import type { DeviceReadyOptions } from './device-ready.ts';
+import type { DeviceReadyOptions } from './device/device-ready.ts';
 import type { DaemonCommandContext } from './context.ts';
 import type { ResolvedGenericExecution } from './request-generic-dispatch.ts';
 import { type DaemonFailureResponse, errorResponse } from '@agent-device/kernel/contracts';
diff --git a/src/daemon/server/daemon-runtime.ts b/src/daemon/server/daemon-runtime.ts
index 72b7a4d50d..c5edcb3e32 100644
--- a/src/daemon/server/daemon-runtime.ts
+++ b/src/daemon/server/daemon-runtime.ts
@@ -40,8 +40,8 @@ import {
   processOwnsActiveDeviceClaim,
   reconcileOrphanedDeviceClaims,
   type DeviceClaimReconciler,
-} from '../device-claims.ts';
-import { createOwnerScopedDeviceClaimReconciler } from '../device-claim-owner-recovery.ts';
+} from '../device/device-claims.ts';
+import { createOwnerScopedDeviceClaimReconciler } from '../device/device-claim-owner-recovery.ts';
 import { createDaemonShutdownClaimLedger } from './daemon-shutdown-claims.ts';
 import { createAudioProbeAdmissionLedger } from '@agent-device/capture-kit/audio-probe-admission-ledger';
 import { createPerfCaptureAdmissionLedger } from '@agent-device/capture-kit/perf-capture-admission-ledger';
diff --git a/src/daemon/server/daemon-shutdown-claims.test.ts b/src/daemon/server/daemon-shutdown-claims.test.ts
index 46a7a9219a..e679e65a84 100644
--- a/src/daemon/server/daemon-shutdown-claims.test.ts
+++ b/src/daemon/server/daemon-shutdown-claims.test.ts
@@ -5,9 +5,9 @@ import {
   retainOrphanedDeviceClaims,
 } from '../../__tests__/test-utils/device-claim-store.ts';
 import fs from 'node:fs';
-import { acquireDeviceClaim } from '../device-claims.ts';
-import { resolveDeviceClaimPath } from '../device-claim-paths.ts';
-import { inspectDeviceClaims } from '../device-claim-inspection.ts';
+import { acquireDeviceClaim } from '../device/device-claims.ts';
+import { resolveDeviceClaimPath } from '../device/device-claim-paths.ts';
+import { inspectDeviceClaims } from '../device/device-claim-inspection.ts';
 import { createDaemonShutdownClaimLedger } from './daemon-shutdown-claims.ts';
 import type { SessionState } from '../session-state.ts';
 
diff --git a/src/daemon/server/daemon-shutdown-claims.ts b/src/daemon/server/daemon-shutdown-claims.ts
index 274f3ac314..7452838ca2 100644
--- a/src/daemon/server/daemon-shutdown-claims.ts
+++ b/src/daemon/server/daemon-shutdown-claims.ts
@@ -1,6 +1,6 @@
 import { publicPlatformString } from '@agent-device/kernel/device';
 import { emitDiagnostic } from '@agent-device/host-kit/diagnostics';
-import { clearDeviceClaim, type DeviceClaimClearOutcome } from '../device-claims.ts';
+import { clearDeviceClaim, type DeviceClaimClearOutcome } from '../device/device-claims.ts';
 import type { DeviceClaimRecord } from '../daemon-shutdown-report.ts';
 import type { SessionState } from '../session-state.ts';
 
diff --git a/src/daemon/session-device-resolution.ts b/src/daemon/session-device-resolution.ts
index fae0ac7afd..19312c0949 100644
--- a/src/daemon/session-device-resolution.ts
+++ b/src/daemon/session-device-resolution.ts
@@ -5,7 +5,10 @@ import { appleSessionObservation } from '../platform-runtime-apple-resources.ts'
 import { resolveTargetDevice } from '@agent-device/device-selection/dispatch-resolve';
 import type { DaemonRequest, DaemonResponse } from './daemon-request.ts';
 import type { SessionState } from './session-state.ts';
-import { hasDeviceSelectionInput, hasExplicitDeviceSelector } from './device-selector-intent.ts';
+import {
+  hasDeviceSelectionInput,
+  hasExplicitDeviceSelector,
+} from './device/device-selector-intent.ts';
 import { listSessionSelectorConflicts } from './session-selector.ts';
 import { errorResponse } from '@agent-device/kernel/contracts';
 
diff --git a/src/daemon/session-lifecycle/internal/__tests__/session-close-shutdown.fixtures.ts b/src/daemon/session-lifecycle/internal/__tests__/session-close-shutdown.fixtures.ts
index d3c9e99918..03953f6adc 100644
--- a/src/daemon/session-lifecycle/internal/__tests__/session-close-shutdown.fixtures.ts
+++ b/src/daemon/session-lifecycle/internal/__tests__/session-close-shutdown.fixtures.ts
@@ -69,8 +69,8 @@ import {
 } from '@agent-device/platform-apple/runner/operations';
 import { cleanupAppleXctracePerfCapture } from '@agent-device/platform-apple/perf';
 import { WEB_DESKTOP_DEVICE } from '../../../../__tests__/test-utils/device-fixtures.ts';
-import { acquireDeviceClaim } from '../../../device-claims.ts';
-import { inspectDeviceClaims } from '../../../device-claim-inspection.ts';
+import { acquireDeviceClaim } from '../../../device/device-claims.ts';
+import { inspectDeviceClaims } from '../../../device/device-claim-inspection.ts';
 
 import {
   type DeviceBinding,
diff --git a/src/daemon/session-lifecycle/internal/__tests__/session-open-execution-runtime.test.ts b/src/daemon/session-lifecycle/internal/__tests__/session-open-execution-runtime.test.ts
index babda0afb4..06c344a5a4 100644
--- a/src/daemon/session-lifecycle/internal/__tests__/session-open-execution-runtime.test.ts
+++ b/src/daemon/session-lifecycle/internal/__tests__/session-open-execution-runtime.test.ts
@@ -17,7 +17,7 @@ vi.mock('@agent-device/device-selection/dispatch-resolve', async (importOriginal
     resolveTargetDeviceSelection: vi.fn(selectionFromResolveTargetDevice(mockResolveTargetDevice)),
   };
 });
-vi.mock('../../../device-ready.ts', () => ({ ensureDeviceReady: vi.fn(async () => {}) }));
+vi.mock('../../../device/device-ready.ts', () => ({ ensureDeviceReady: vi.fn(async () => {}) }));
 vi.mock('../../../../platform-runtime-runtime-hints.ts', async (importOriginal) => {
   const actual =
     await importOriginal<typeof import('../../../../platform-runtime-runtime-hints.ts')>();
diff --git a/src/daemon/session-lifecycle/internal/__tests__/session-open-runtime.test.ts b/src/daemon/session-lifecycle/internal/__tests__/session-open-runtime.test.ts
index a6d1ffa997..7f61090b65 100644
--- a/src/daemon/session-lifecycle/internal/__tests__/session-open-runtime.test.ts
+++ b/src/daemon/session-lifecycle/internal/__tests__/session-open-runtime.test.ts
@@ -15,7 +15,7 @@ vi.mock('@agent-device/device-selection/dispatch-resolve', async (importOriginal
     resolveTargetDeviceSelection: vi.fn(selectionFromResolveTargetDevice(mockResolveTargetDevice)),
   };
 });
-vi.mock('../../../device-ready.ts', () => ({ ensureDeviceReady: vi.fn(async () => {}) }));
+vi.mock('../../../device/device-ready.ts', () => ({ ensureDeviceReady: vi.fn(async () => {}) }));
 vi.mock('../../../../platform-runtime-apple-application-tools.ts', async (importOriginal) => {
   const actual =
     await importOriginal<
diff --git a/src/daemon/session-lifecycle/internal/__tests__/session-open-url-prewarm.test.ts b/src/daemon/session-lifecycle/internal/__tests__/session-open-url-prewarm.test.ts
index aae46b5573..96010f58fb 100644
--- a/src/daemon/session-lifecycle/internal/__tests__/session-open-url-prewarm.test.ts
+++ b/src/daemon/session-lifecycle/internal/__tests__/session-open-url-prewarm.test.ts
@@ -6,7 +6,7 @@ vi.mock('node:timers/promises', async (importOriginal) => {
   const actual = await importOriginal<typeof import('node:timers/promises')>();
   return { ...actual, setTimeout: vi.fn(async () => undefined) };
 });
-vi.mock('../../../device-ready.ts', () => ({ ensureDeviceReady: vi.fn(async () => {}) }));
+vi.mock('../../../device/device-ready.ts', () => ({ ensureDeviceReady: vi.fn(async () => {}) }));
 vi.mock('@agent-device/platform-apple/runner/operations', async (importOriginal) => {
   const actual =
     await importOriginal<typeof import('@agent-device/platform-apple/runner/operations')>();
diff --git a/src/daemon/session-lifecycle/internal/inventory.ts b/src/daemon/session-lifecycle/internal/inventory.ts
index 4090515829..24725b83f6 100644
--- a/src/daemon/session-lifecycle/internal/inventory.ts
+++ b/src/daemon/session-lifecycle/internal/inventory.ts
@@ -22,9 +22,9 @@ import {
 import {
   deviceClaimOwnerCannotRelease,
   inspectDeviceClaims,
-} from '../../device-claim-inspection.ts';
-import { canonicalLocalDeviceKey } from '../../device-claim-paths.ts';
-import { deviceClaimIdentity } from '../../device-claims.ts';
+} from '../../device/device-claim-inspection.ts';
+import { canonicalLocalDeviceKey } from '../../device/device-claim-paths.ts';
+import { deviceClaimIdentity } from '../../device/device-claims.ts';
 import type { DaemonRequest, DaemonResponse } from '../../daemon-request.ts';
 import type { SessionRef } from '../../session-state.ts';
 import { SessionStore } from '../../session-store.ts';
diff --git a/src/daemon/session-lifecycle/internal/session-close.ts b/src/daemon/session-lifecycle/internal/session-close.ts
index da1bd016e5..889cc5016b 100644
--- a/src/daemon/session-lifecycle/internal/session-close.ts
+++ b/src/daemon/session-lifecycle/internal/session-close.ts
@@ -17,7 +17,7 @@ import {
 import { isAuthoringArmedSession } from '../../session-script-publication-capability.ts';
 import type { SessionCleanupFailure } from '../../session-teardown.ts';
 import { isWebSession } from '../../web-session-names.ts';
-import { clearDeviceClaim } from '../../device-claims.ts';
+import { clearDeviceClaim } from '../../device/device-claims.ts';
 import { applicationLifecycleExecutionFromRequest } from '../../application-lifecycle-execution.ts';
 import { hasRuntimeTransportHints } from '../../session-runtime.ts';
 import type {
diff --git a/src/daemon/session-lifecycle/internal/session-open-execution.ts b/src/daemon/session-lifecycle/internal/session-open-execution.ts
index 1be19c529e..b43578d3ac 100644
--- a/src/daemon/session-lifecycle/internal/session-open-execution.ts
+++ b/src/daemon/session-lifecycle/internal/session-open-execution.ts
@@ -57,16 +57,16 @@ import {
   type DeviceClaimAcquireResult,
   type DeviceClaimSessionOwnership,
   type DeviceClaimReconciler,
-} from '../../device-claims.ts';
-import type { TakenOverDeviceClaim } from '../../device-claim-reboot.ts';
+} from '../../device/device-claims.ts';
+import type { TakenOverDeviceClaim } from '../../device/device-claim-reboot.ts';
 import { deviceBootObservation } from '../../../platform-runtime-device-boot.ts';
 import { appendResponseWarning } from './session-open-warnings.ts';
 import {
   buildAllocatorHeldRefusal,
   buildDeviceClaimConflictError,
-} from '../../device-claim-conflict.ts';
-import { requireAllocatorHeldDeviceClaim } from '../../device-claim-allocator.ts';
-import { deviceClaimRuleForOwner } from '../../device-claim-rule.ts';
+} from '../../device/device-claim-conflict.ts';
+import { requireAllocatorHeldDeviceClaim } from '../../device/device-claim-allocator.ts';
+import { deviceClaimRuleForOwner } from '../../device/device-claim-rule.ts';
 import { errorResponse, type DaemonFailureResponse } from '@agent-device/kernel/contracts';
 
 type OpenTiming = {
diff --git a/src/daemon/session-lifecycle/internal/session-open.ts b/src/daemon/session-lifecycle/internal/session-open.ts
index badb991d29..098cb7f46d 100644
--- a/src/daemon/session-lifecycle/internal/session-open.ts
+++ b/src/daemon/session-lifecycle/internal/session-open.ts
@@ -27,7 +27,7 @@ import {
   resolveForegroundOpenRequest,
 } from './session-open-foreground.ts';
 import { expireRefFrame } from '../../ref-frame.ts';
-import type { DeviceClaimReconciler } from '../../device-claims.ts';
+import type { DeviceClaimReconciler } from '../../device/device-claims.ts';
 import type {
   BindDeviceRuntime,
   InspectDeviceRuntimeFacts,
diff --git a/src/daemon/session-runtime.ts b/src/daemon/session-runtime.ts
index 52fb6669df..2cc69922f2 100644
--- a/src/daemon/session-runtime.ts
+++ b/src/daemon/session-runtime.ts
@@ -13,7 +13,7 @@ import { publicPlatformString, type DeviceInfo } from '@agent-device/kernel/devi
 import type { SessionRuntimeHints, SessionState } from './session-state.ts';
 import { SessionStore } from './session-store.ts';
 import { trimRuntimeValue } from '@agent-device/host-kit/runtime-transport-hints';
-import { isAndroidEmulator, isIosSimulator } from './device-targets.ts';
+import { isAndroidEmulator, isIosSimulator } from './device/device-targets.ts';
 
 type SessionRuntimeHintsStore = Readonly<{
   getRuntimeHints: SessionStore['getRuntimeHints'];
diff --git a/src/daemon/snapshot-runtime-binding.ts b/src/daemon/snapshot-runtime-binding.ts
index e4d3650560..a47f3a398a 100644
--- a/src/daemon/snapshot-runtime-binding.ts
+++ b/src/daemon/snapshot-runtime-binding.ts
@@ -16,7 +16,7 @@ import {
   type BindDeviceRuntime,
   type InspectDeviceRuntimeFacts,
 } from './request-runtime-binding.ts';
-import type { DeviceReadyOptions } from './device-ready.ts';
+import type { DeviceReadyOptions } from './device/device-ready.ts';
 import type { PlatformResourceCleanup } from './platform-resource-cleanup.ts';
 import { SessionStore } from './session-store.ts';
 import type { DaemonRequest, DaemonResponse } from './daemon-request.ts';
diff --git a/test/integration/nightly/concurrency-torture/claim-registry.ts b/test/integration/nightly/concurrency-torture/claim-registry.ts
index d2f05b9c1b..001db632f7 100644
--- a/test/integration/nightly/concurrency-torture/claim-registry.ts
+++ b/test/integration/nightly/concurrency-torture/claim-registry.ts
@@ -1,4 +1,4 @@
-// In-memory model of the enforced host-global device claim (`src/daemon/device-claims.ts`).
+// In-memory model of the enforced host-global device claim (`src/daemon/device/device-claims.ts`).
 //
 // The production claim is a filesystem lock file guarded by a process lock, keyed
 // by `canonicalLocalDeviceKey`. That is real I/O and a real OS lock — neither is
diff --git a/test/integration/provider-scenarios/managed-request-admission.fixtures.ts b/test/integration/provider-scenarios/managed-request-admission.fixtures.ts
index 2b5f02cf55..98d97ee4e2 100644
--- a/test/integration/provider-scenarios/managed-request-admission.fixtures.ts
+++ b/test/integration/provider-scenarios/managed-request-admission.fixtures.ts
@@ -13,8 +13,8 @@ import {
   isolatedDeviceClaimStores,
   retainOrphanedDeviceClaims,
 } from '../../../src/__tests__/test-utils/device-claim-store.ts';
-import { createDeviceClaimAdmission } from '../../../src/daemon/device-claim-admission.ts';
-import { acquireAllocatorHeldDeviceClaim } from '../../../src/daemon/device-claim-allocator.ts';
+import { createDeviceClaimAdmission } from '../../../src/daemon/device/device-claim-admission.ts';
+import { acquireAllocatorHeldDeviceClaim } from '../../../src/daemon/device/device-claim-allocator.ts';
 import { createRequestRuntimeBindings } from '../../../src/daemon/request-runtime-binding.ts';
 import { managedCommandHorizon } from '../../../src/daemon/managed-device-allocation/command-horizon.ts';
 import type { ManagedLeaseAdmission } from '../../../src/daemon/managed-device-allocation/lease-admission.ts';

From 19cb1fddd9c0753d341e01c55e28164cf3d4b1ca Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Wed, 23 Sep 2026 15:15:40 +0200
Subject: [PATCH 040/132] fix(ios): report capture refusals as typed reasons in
 back-fallback and recording (#2766)

* fix(ios): report capture refusals as typed reasons in back-fallback and recording

#2741 routed screenshots through the resolved app display but left two
failure contracts papered over (#2728):

- The in-app `back` coordinate fallback read a nil screenshot sample as "no
  visual change" and sampled SpringBoard when the app resolved no window, so
  a two-home-screen comparison reported "in-app back control is not
  available" after a real leading tap had already run. The check now observes
  only the app's own resolved window and reports the display refusal as an
  unverified outcome; an observable no-change still reads as unavailable.
- `record start` collapsed every no-frame bootstrap into an untyped NSError.
  It now surfaces the shared APP_SCREEN_* reason, so a runtime with no
  resolvable window fails closed with a typed code.

Refuse a zero-pixel capture at the capture type so a required consumer cannot
mistake it for a usable frame. macOS/tvOS keep their host-display capture and
generic bootstrap error. Focused runner unit tests pin the observation split,
the refusal-selection, and the typed-vs-generic error mapping.

* test(ios): pin the capture-refusal contracts behind the code that produces them

- testRecordStartThrowsTheCaptureRefusalItReceived drives ScreenRecorder.start
  with an always-refusing capture and maps the actual thrown error through
  recordingStartErrorPayload, so the bootstrap forwarding is covered (iOS PR lane).
- navigationFallbackSample(resolvingApp:systemSurface:encoding:) now holds the
  back fallback's app-only decision; the test hands it a system surface that fails
  if consulted, so a revert to SpringBoard sampling turns it red.
- navigationVisualSample + inAppBackOutcome keep the refusal->code mapping and the
  unknown-outcome decision testable on the macOS host lane.
---
 .github/workflows/ios.yml                     |   1 +
 .../RunnerAppScreenCapture.swift              |  34 +-
 .../RunnerTests+CommandExecution.swift        |  18 +-
 .../RunnerTests+Lifecycle.swift               |  50 ++-
 .../RunnerTests+Navigation.swift              | 312 +++++++++++++++---
 .../RunnerTests+ScreenRecorder.swift          |  62 +++-
 .../RunnerTests+RecordingTests.swift          |  71 ++++
 docs/adr/0025-foldable-apple-panels.md        |  15 +
 .../src/runner/runner-contract.ts             |  14 +-
 9 files changed, 486 insertions(+), 91 deletions(-)

diff --git a/.github/workflows/ios.yml b/.github/workflows/ios.yml
index daaa784677..dc1cda0ec1 100644
--- a/.github/workflows/ios.yml
+++ b/.github/workflows/ios.yml
@@ -154,6 +154,7 @@ jobs:
             -xctestrun "$XCTESTRUN_PATH" \
             -destination "platform=iOS Simulator,id=${{ steps.ios-simulator.outputs.simulator-udid }}" \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testSinglePointerFlingFallsBackToXCTestCoordinateDragWhenPrivateSynthesisFails \
+            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testRecordStartThrowsTheCaptureRefusalItReceived \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testAlertDispatchResolvesItsOwnModalWithoutCoordinateTapRoutingProbe \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testAlertResolutionCannotBypassRequestedDeadline \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testTypeWithoutResolvedInputReturnsTypedFailureBeforeDispatchingText \
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerAppScreenCapture.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerAppScreenCapture.swift
index 9429ad3e0a..e44934777f 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerAppScreenCapture.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerAppScreenCapture.swift
@@ -54,6 +54,21 @@ enum RunnerAppScreenCaptureFailure: String, Error {
   }
 }
 
+extension RunnerTests {
+  /// The target rule, kept apart from the two queries so the rule itself is testable: an unresolved
+  /// window asks the system surface, and nothing else does.
+  func selectObservedScreenCapture(
+    resolving: () -> Result<CapturedAppScreen, RunnerAppScreenCaptureFailure>,
+    fallingBack: () -> Result<CapturedAppScreen, RunnerAppScreenCaptureFailure>
+  ) -> Result<CapturedAppScreen, RunnerAppScreenCaptureFailure> {
+    let outcome = resolving()
+    if case .failure(.unresolvedWindow) = outcome {
+      return fallingBack()
+    }
+    return outcome
+  }
+}
+
 #if canImport(UIKit) && os(iOS)
 extension RunnerTests {
   /// Captures the display hosting `app` instead of `XCUIScreen.main`.
@@ -103,19 +118,6 @@ extension RunnerTests {
     )
   }
 
-  /// The target rule, kept apart from the two queries so the rule itself is testable: an unresolved
-  /// window asks the system surface, and nothing else does.
-  func selectObservedScreenCapture(
-    resolving: () -> Result<CapturedAppScreen, RunnerAppScreenCaptureFailure>,
-    fallingBack: () -> Result<CapturedAppScreen, RunnerAppScreenCaptureFailure>
-  ) -> Result<CapturedAppScreen, RunnerAppScreenCaptureFailure> {
-    let outcome = resolving()
-    if case .failure(.unresolvedWindow) = outcome {
-      return fallingBack()
-    }
-    return outcome
-  }
-
   private static func resolveCapturedAppScreen(
     app: XCUIApplication
   ) -> Result<CapturedAppScreen, RunnerAppScreenCaptureFailure> {
@@ -140,6 +142,12 @@ extension RunnerTests {
     guard let cgImage = runnerCGImage(from: upright) else {
       return .failure(.unrenderableImage)
     }
+    // A zero-pixel image is a capture that did not happen, not a tiny one. Refusing it here — at the
+    // type that owns the fact — keeps a required consumer (a recording sizing its writer from this
+    // frame) from mistaking it for a usable frame and falling back to an untyped error (#2728).
+    guard cgImage.width > 0, cgImage.height > 0 else {
+      return .failure(.unrenderableImage)
+    }
     return .success(
       CapturedAppScreen(
         image: upright,
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
index e23dd7952f..e731ad4e2c 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
@@ -1466,13 +1466,14 @@ extension RunnerTests {
           fps: command.fps.map { Int32($0) }
         )
         try recorder.start { [weak self] in
-          return self?.captureRunnerFrame(app: activeApp)
+          guard let self else { return .failure(.unresolvedScreen) }
+          return self.captureRunnerFrameResult(app: activeApp)
         }
         activeRecording = recorder
         return Response(ok: true, data: DataPayload(message: "recording started"))
       } catch {
         activeRecording = nil
-        return Response(ok: false, error: ErrorPayload(message: "failed to start recording: \(error.localizedDescription)"))
+        return Response(ok: false, error: Self.recordingStartErrorPayload(for: error))
       }
     case .recordStop:
       guard let recorder = activeRecording else {
@@ -2120,11 +2121,20 @@ extension RunnerTests {
       )
 #endif
     case .back, .backInApp:
-      if tapInAppBackControl(app: activeApp) {
+      switch tapInAppBackControl(app: activeApp) {
+      case .performed:
         let message = command.command == .back ? "back" : "backInApp"
         return Response(ok: true, data: DataPayload(message: message))
+      case .unavailable:
+        return Response(
+          ok: false,
+          error: ErrorPayload(message: "in-app back control is not available")
+        )
+      case .unverified(let error):
+        // The fallback gesture ran but the display refused to be sampled. Reporting the typed refusal
+        // keeps an unknown outcome from being laundered into a definitive "no back control" (#2728).
+        return Response(ok: false, error: error)
       }
-      return Response(ok: false, error: ErrorPayload(message: "in-app back control is not available"))
     case .backSystem:
       if performSystemBackAction(app: activeApp) {
         return Response(ok: true, data: DataPayload(message: "backSystem"))
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Lifecycle.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Lifecycle.swift
index 67c689cb1c..a74851b5ef 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Lifecycle.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Lifecycle.swift
@@ -42,31 +42,59 @@ enum RunnerInteractionIdleWaits {
 extension RunnerTests {
   // MARK: - Recording
 
-  /// One frame for the recording pump and the keyboard settle sample.
+  /// One frame for a caller that tolerates a dropped one — keyboard settling, which skips a sample it
+  /// cannot take and keeps polling. A frame that must exist goes through `captureRunnerFrameResult`,
+  /// which says why it refused.
   ///
   /// On iOS the frame comes from the display owning a window, because a foldable's
   /// `XCUIScreen.main` can be the dark outer panel while the app runs on the inner one — a stream of
-  /// identical black frames would then read as a settled screen and as a finished recording (#2728).
-  /// An observation with no session window falls to the system surface's window, which is what the
-  /// home screen is. macOS keeps recording the host display the way it always has.
+  /// identical black frames would then read as a settled screen (#2728). An observation with no
+  /// session window falls to the system surface's window, which is what the home screen is. macOS
+  /// keeps the host display it always recorded.
   func captureRunnerFrame(app: XCUIApplication) -> RunnerImage? {
-#if os(iOS)
-    guard case .success(let captured) = captureObservedScreen(app: app) else {
+    switch captureRunnerFrameResult(app: app) {
+    case .success(let captured):
+      return captured.image
+    case .failure:
       return nil
     }
-    return captured.image
+  }
+
+  /// The same frame as `captureRunnerFrame`, but carrying the reason it refused, so a required first
+  /// frame — a recording's bootstrap, which sizes the whole writer from it — fails closed with a
+  /// typed code rather than a message. The ongoing pump reads the same result and ignores a refusal
+  /// the way it ignored the `nil` it used to get; only a frame that must exist owes a reason (#2728).
+  func captureRunnerFrameResult(
+    app: XCUIApplication
+  ) -> Result<CapturedAppScreen, RunnerAppScreenCaptureFailure> {
+#if os(iOS)
+    return captureObservedScreen(app: app)
 #else
-    var image: RunnerImage?
+    var outcome: Result<CapturedAppScreen, RunnerAppScreenCaptureFailure> = .failure(
+      .unrenderableImage
+    )
     let capture = {
-      let screenshot = XCUIScreen.main.screenshot()
-      image = screenshot.image
+      let image = XCUIScreen.main.screenshot().image
+      if let cgImage = runnerCGImage(from: image) {
+        // The host display has no resolved-panel facts to report; the recorder reads only the image
+        // and its pixel size, so these two are inert placeholders, not measurements the host scales by.
+        outcome = .success(
+          CapturedAppScreen(
+            image: image,
+            displayID: 0,
+            pixelWidth: cgImage.width,
+            pixelHeight: cgImage.height,
+            pixelsPerPoint: 1
+          )
+        )
+      }
     }
     if Thread.isMainThread {
       capture()
     } else {
       DispatchQueue.main.sync(execute: capture)
     }
-    return image
+    return outcome
 #endif
   }
 
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Navigation.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Navigation.swift
index 98b41d3bb5..650d7559bb 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Navigation.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Navigation.swift
@@ -4,27 +4,66 @@ extension RunnerTests {
   static let navigationBackKeywords = ["back", "close", "cancel"]
   static let navigationFallbackVerificationDelay: TimeInterval = 0.25
 
-  func tapInAppBackControl(app: XCUIApplication) -> Bool {
+  /// What one in-app `back` attempt concluded. `.unverified` carries the typed capture failure the
+  /// display refused with, so an optional visual check that could not run reports an unknown instead
+  /// of the false "no back control exists" that a `nil` sample would otherwise become (#2728).
+  enum InAppBackOutcome {
+    case performed
+    case unavailable
+    case unverified(ErrorPayload)
+  }
+
+  /// The three answers a before/after visual comparison can give. `unobserved` is not evidence of
+  /// "no change": a display that refuses to be sampled proves nothing either way (#2728).
+  enum NavigationVisualObservation: Equatable {
+    case changed
+    case unchanged
+    case unobserved
+
+    var logToken: String {
+      switch self {
+      case .changed: return "yes"
+      case .unchanged: return "no"
+      case .unobserved: return "unknown"
+      }
+    }
+  }
+
+  /// One navigation-fallback capture: the encoded frame when the display answered, and the typed
+  /// reason it refused otherwise. Only iOS produces a refusal; other platforms capture nothing here.
+  struct NavigationVisualSample {
+    let data: Data?
+    let refusalCode: String?
+    let refusalHint: String?
+
+    init(data: Data?, refusalCode: String? = nil, refusalHint: String? = nil) {
+      self.data = data
+      self.refusalCode = refusalCode
+      self.refusalHint = refusalHint
+    }
+  }
+
+  func tapInAppBackControl(app: XCUIApplication) -> InAppBackOutcome {
 #if os(macOS)
     if let back = macOSNavigationBackElement(app: app) {
       tapElementCenter(app: app, element: back)
-      return true
+      return .performed
     }
-    return false
+    return .unavailable
 #elseif os(tvOS)
     _ = pressTvRemote(.menu)
-    return true
+    return .performed
 #else
     let buttons = app.navigationBars.buttons.allElementsBoundByIndex
     if let back = buttons.first(where: { $0.isHittable }) {
       back.tap()
-      return true
+      return .performed
     }
     if isSnapshotXCTestChannelPenalized(bundleId: currentBundleId) {
       NSLog("AGENT_DEVICE_RUNNER_IN_APP_BACK_SKIPPED_XCTEST_ENUMERATION bundle=%@", currentBundleId ?? "")
     } else if let back = topNavigationBackElement(app: app) {
       tapElementCenter(app: app, element: back)
-      return true
+      return .performed
     }
     return tapTopLeadingNavigationFallback(app: app)
 #endif
@@ -109,11 +148,11 @@ extension RunnerTests {
     return CGPoint(x: frame.minX + xOffset, y: frame.minY + yOffset)
   }
 
-  private func tapTopLeadingNavigationFallback(app: XCUIApplication) -> Bool {
+  private func tapTopLeadingNavigationFallback(app: XCUIApplication) -> InAppBackOutcome {
 #if os(iOS)
     let frame = onScreenWindowFrame(app: app)
     guard let point = Self.topLeadingNavigationFallbackPoint(in: frame) else {
-      return false
+      return .unavailable
     }
     let before = captureNavigationFallbackVisualState(app: app)
     let context = synthesizedCoordinateContext(
@@ -124,54 +163,135 @@ extension RunnerTests {
       synthesizedTapAt(app: app, x: point.x, y: point.y, context: context)
     }
     if case .performed = synthesized.outcome {
-      return didNavigationFallbackChangeVisualState(app: app, before: before)
+      return verifyNavigationFallbackOutcome(app: app, before: before)
     }
     let fallback = performGesture(app) {
       tapAt(app: app, x: point.x, y: point.y)
     }
     if case .performed = fallback.outcome {
-      return didNavigationFallbackChangeVisualState(app: app, before: before)
+      return verifyNavigationFallbackOutcome(app: app, before: before)
     }
 #endif
-    return false
+    return .unavailable
   }
 
-  private func captureNavigationFallbackVisualState(app: XCUIApplication) -> Data? {
+  private func captureNavigationFallbackVisualState(app: XCUIApplication) -> NavigationVisualSample {
 #if os(iOS)
-    // A visual check is optional evidence: a display that owns no window reports unknown by returning
-    // no sample, which the comparison below already reads as "nothing proved". It never reaches for
-    // a screen nobody is on, whose stable black would then be read as evidence that the tap did
-    // nothing (#2728).
-    guard case .success(let captured) = captureObservedScreen(app: app) else {
-      return nil
-    }
-    return runnerPngData(for: captured.image)
+    return Self.navigationFallbackSample(
+      resolvingApp: { self.captureResolvedAppScreen(app: app) },
+      systemSurface: { self.captureResolvedAppScreen(app: self.springboard) },
+      encoding: { runnerPngData(for: $0.image) }
+    )
 #else
-    return nil
+    return NavigationVisualSample(data: nil)
 #endif
   }
 
-  private func didNavigationFallbackChangeVisualState(
+  /// The decision the in-app `back` fallback makes about WHAT to sample, kept apart from the live app
+  /// so the decision itself is testable. It samples only the app's own resolved screen: consulting the
+  /// system surface for an app that resolved no window would capture SpringBoard's home screen, which
+  /// reads as "unchanged" across a before/after pair and launders a wrong-process frame into a false
+  /// "no back control" — the opposite of the unknown-outcome answer the fallback owes (#2728). The
+  /// system surface is still threaded in, so sampling it is the tested contract: a caller that started
+  /// to consult it fails the fallback's test. `navigationVisualSample` then names the refusal.
+  static func navigationFallbackSample(
+    resolvingApp: () -> Result<CapturedAppScreen, RunnerAppScreenCaptureFailure>,
+    systemSurface: () -> Result<CapturedAppScreen, RunnerAppScreenCaptureFailure>,
+    encoding: (CapturedAppScreen) -> Data?
+  ) -> NavigationVisualSample {
+    _ = systemSurface
+    return navigationVisualSample(from: resolvingApp(), encoding: encoding)
+  }
+
+  /// Turns a capture answer into a navigation sample: the encoded frame when the display answered,
+  /// and the typed reason it refused otherwise. A resolved display whose image would not encode is
+  /// named as the capture failure it is, not as an unnamed no-sample that would default to "no
+  /// display resolved" (#2728). Kept apart from the query so the mapping itself is testable.
+  static func navigationVisualSample(
+    from outcome: Result<CapturedAppScreen, RunnerAppScreenCaptureFailure>,
+    encoding: (CapturedAppScreen) -> Data?
+  ) -> NavigationVisualSample {
+    switch outcome {
+    case .success(let captured):
+      guard let png = encoding(captured) else {
+        let refusal = RunnerAppScreenCaptureFailure.unrenderableImage
+        return NavigationVisualSample(
+          data: nil,
+          refusalCode: refusal.rawValue,
+          refusalHint: refusal.hint
+        )
+      }
+      return NavigationVisualSample(data: png)
+    case .failure(let failure):
+      return NavigationVisualSample(
+        data: nil,
+        refusalCode: failure.rawValue,
+        refusalHint: failure.hint
+      )
+    }
+  }
+
+  private func verifyNavigationFallbackOutcome(
     app: XCUIApplication,
-    before: Data?
-  ) -> Bool {
+    before: NavigationVisualSample
+  ) -> InAppBackOutcome {
     sleepFor(Self.navigationFallbackVerificationDelay)
     let after = captureNavigationFallbackVisualState(app: app)
-    let changed = Self.didNavigationFallbackChangeVisualState(before: before, after: after)
-    // The sample sizes are what tells a refused capture apart from an unchanged screen, and the
-    // fallback is rare enough that saying so every time costs nothing (#2728).
+    let observation = Self.navigationVisualObservation(before: before.data, after: after.data)
+    // The sample sizes and the observation name together tell a refused capture apart from an
+    // unchanged screen, and the fallback is rare enough that saying so every time costs nothing.
     NSLog(
       "AGENT_DEVICE_RUNNER_IN_APP_BACK_VISUAL_VERIFICATION beforeBytes=%ld afterBytes=%ld changed=%@",
-      before?.count ?? -1,
-      after?.count ?? -1,
-      changed ? "yes" : "no"
+      before.data?.count ?? -1,
+      after.data?.count ?? -1,
+      observation.logToken
     )
-    return changed
+    return Self.inAppBackOutcome(observation: observation, before: before, after: after)
+  }
+
+  /// What an observation of the fallback's before/after samples concludes. Kept apart from the sleep
+  /// and the capture so the three-way decision is testable without a running app.
+  static func inAppBackOutcome(
+    observation: NavigationVisualObservation,
+    before: NavigationVisualSample,
+    after: NavigationVisualSample
+  ) -> InAppBackOutcome {
+    switch observation {
+    case .changed:
+      return .performed
+    case .unchanged:
+      return .unavailable
+    case .unobserved:
+      // No sample is not evidence of no navigation change: the fallback ran, so report the display
+      // refusal it hit rather than laundering an unobservable result into "back is not available".
+      return .unverified(Self.navigationFallbackErrorPayload(after: after, before: before))
+    }
   }
 
-  static func didNavigationFallbackChangeVisualState(before: Data?, after: Data?) -> Bool {
-    guard let before, let after else { return false }
-    return before != after
+  static func navigationVisualObservation(
+    before: Data?,
+    after: Data?
+  ) -> NavigationVisualObservation {
+    guard let before, let after else { return .unobserved }
+    return before != after ? .changed : .unchanged
+  }
+
+  /// The refusal the fallback most recently hit wins, so the code names the last thing it looked at
+  /// before giving up. A missing reason on both sides is unreachable on iOS (every nil sample carries
+  /// one) and defaults to the plain display-unresolved code.
+  static func navigationFallbackErrorPayload(
+    after: NavigationVisualSample,
+    before: NavigationVisualSample
+  ) -> ErrorPayload {
+    ErrorPayload(
+      code:
+        after.refusalCode
+        ?? before.refusalCode
+        ?? RunnerAppScreenCaptureFailure.unresolvedScreen.rawValue,
+      message:
+        "The in-app back fallback was dispatched, but no display could be sampled to confirm the result. This is an unknown outcome, not evidence that a back control is absent.",
+      hint: after.refusalHint ?? before.refusalHint
+    )
   }
 
   private func macOSNavigationBackElement(app: XCUIApplication) -> XCUIElement? {
@@ -234,21 +354,119 @@ extension RunnerTests {
     XCTAssertFalse(Self.isTopNavigationControlFrame(.infinite, in: window))
   }
 
-  func testNavigationFallbackRequiresObservedVisualChange() {
-    XCTAssertTrue(
-      Self.didNavigationFallbackChangeVisualState(
-        before: Data([1, 2, 3]),
-        after: Data([1, 2, 4])
-      )
+  func testNavigationVisualVerificationSeparatesNoChangeFromNoSample() {
+    XCTAssertEqual(
+      Self.navigationVisualObservation(before: Data([1, 2, 3]), after: Data([1, 2, 4])),
+      .changed
     )
-    XCTAssertFalse(
-      Self.didNavigationFallbackChangeVisualState(
-        before: Data([1, 2, 3]),
-        after: Data([1, 2, 3])
-      )
+    XCTAssertEqual(
+      Self.navigationVisualObservation(before: Data([1, 2, 3]), after: Data([1, 2, 3])),
+      .unchanged
+    )
+    // A missing sample is neither a change nor a no-change; treating it as "unchanged" would let a
+    // capture that refused become the reason the `back` command claims no control exists (#2728).
+    XCTAssertEqual(Self.navigationVisualObservation(before: nil, after: Data([1])), .unobserved)
+    XCTAssertEqual(Self.navigationVisualObservation(before: Data([1]), after: nil), .unobserved)
+    XCTAssertEqual(Self.navigationVisualObservation(before: nil, after: nil), .unobserved)
+  }
+
+  func testNavigationFallbackReportsTheRefusalItHitNotADefaultCode() {
+    // The refusal from the most recent sample wins, so the code names what the fallback last looked at
+    // before giving up; an earlier refusal is reported only when the later sample carried none (#2728).
+    let after = NavigationVisualSample(
+      data: nil,
+      refusalCode: "APP_SCREEN_WINDOW_UNRESOLVED",
+      refusalHint: "after hint"
+    )
+    let before = NavigationVisualSample(
+      data: nil,
+      refusalCode: "APP_SCREEN_UNRESOLVED",
+      refusalHint: "before hint"
+    )
+    let laterWins = Self.navigationFallbackErrorPayload(after: after, before: before)
+    XCTAssertEqual(laterWins.code, "APP_SCREEN_WINDOW_UNRESOLVED")
+    XCTAssertEqual(laterWins.hint, "after hint")
+
+    let onlyBefore = Self.navigationFallbackErrorPayload(
+      after: NavigationVisualSample(data: nil),
+      before: before
+    )
+    XCTAssertEqual(onlyBefore.code, "APP_SCREEN_UNRESOLVED")
+    XCTAssertEqual(onlyBefore.hint, "before hint")
+
+    // Neither side named a reason (unreachable on iOS): a real capture code, never a bare failure.
+    let unnamed = Self.navigationFallbackErrorPayload(
+      after: NavigationVisualSample(data: nil),
+      before: NavigationVisualSample(data: nil)
+    )
+    XCTAssertEqual(unnamed.code, "APP_SCREEN_UNRESOLVED")
+    XCTAssertTrue(unnamed.message.contains("unknown outcome"))
+  }
+
+  func testVerifyNavigationFallbackOutcomeReportsUnresolvedWindowWithoutSystemSurface() {
+    // The in-app `back` fallback ran its tap but the app resolved no window. It must name that refusal
+    // as an unknown outcome AND must not have sampled the system surface: capturing SpringBoard's home
+    // screen twice reads as "unchanged" and launders a wrong-process frame into "no back control
+    // exists" (#2728). This drives the SAME `navigationFallbackSample` production calls, handing it a
+    // system surface that fails the test if consulted — so reverting the fallback to sample SpringBoard
+    // (or dropping the refusal code) turns this red, which an inline `.never` re-creation could not.
+    var askedSystemSurface = false
+    let sample = Self.navigationFallbackSample(
+      resolvingApp: { .failure(.unresolvedWindow) },
+      systemSurface: {
+        askedSystemSurface = true
+        return .failure(.unresolvedWindow)
+      },
+      encoding: { _ in Data([1, 2, 3]) }
+    )
+    XCTAssertFalse(askedSystemSurface, "the in-app fallback samples the app only, never SpringBoard")
+
+    XCTAssertNil(sample.data)
+    XCTAssertEqual(sample.refusalCode, "APP_SCREEN_WINDOW_UNRESOLVED")
+
+    let observation = Self.navigationVisualObservation(before: sample.data, after: sample.data)
+    XCTAssertEqual(observation, .unobserved)
+
+    switch Self.inAppBackOutcome(observation: observation, before: sample, after: sample) {
+    case .unverified(let payload):
+      XCTAssertEqual(payload.code, "APP_SCREEN_WINDOW_UNRESOLVED")
+    case .performed, .unavailable:
+      XCTFail("a refused capture must report an unknown outcome, not 'no back control'")
+    }
+  }
+
+  func testNavigationVisualSampleDistinguishesEncodedFrameFromRefusal() {
+    // The same capture entry point yields three different samples, and only the refusal ones may carry
+    // a code: an encoded frame is evidence, a resolved-but-unencodable image and a refusal are not
+    // (#2728). Reverting the mapping to a plain no-sample loses the reason a host keys on.
+    let captured = CapturedAppScreen(
+      image: RunnerImage(),
+      displayID: 3,
+      pixelWidth: 12,
+      pixelHeight: 24,
+      pixelsPerPoint: 3
+    )
+
+    let encoded = Self.navigationVisualSample(
+      from: .success(captured),
+      encoding: { _ in Data([7, 7]) }
+    )
+    XCTAssertEqual(encoded.data, Data([7, 7]))
+    XCTAssertNil(encoded.refusalCode)
+
+    let unencodable = Self.navigationVisualSample(
+      from: .success(captured),
+      encoding: { _ in nil }
+    )
+    XCTAssertNil(unencodable.data)
+    XCTAssertEqual(unencodable.refusalCode, "APP_SCREEN_CAPTURE_UNRENDERABLE")
+
+    let refused = Self.navigationVisualSample(
+      from: .failure(.unresolvedScreen),
+      encoding: { _ in Data([7, 7]) }
     )
-    XCTAssertFalse(Self.didNavigationFallbackChangeVisualState(before: nil, after: Data([1])))
-    XCTAssertFalse(Self.didNavigationFallbackChangeVisualState(before: Data([1]), after: nil))
+    XCTAssertNil(refused.data)
+    XCTAssertEqual(refused.refusalCode, "APP_SCREEN_UNRESOLVED")
   }
 #endif
 }
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+ScreenRecorder.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+ScreenRecorder.swift
index 6f55379c24..a7e13154fe 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+ScreenRecorder.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+ScreenRecorder.swift
@@ -30,7 +30,9 @@ extension RunnerTests {
       self.fps = fps
     }
 
-    func start(captureFrame: @escaping () -> RunnerImage?) throws {
+    func start(
+      capture: @escaping () -> Result<CapturedAppScreen, RunnerAppScreenCaptureFailure>
+    ) throws {
       let url = URL(fileURLWithPath: outputPath)
       let directory = url.deletingLastPathComponent()
       try FileManager.default.createDirectory(
@@ -44,21 +46,34 @@ extension RunnerTests {
 
       var dimensions: CGSize = .zero
       var bootstrapImage: RunnerImage?
+      var lastFailure: RunnerAppScreenCaptureFailure?
       let bootstrapDeadline = Date().addingTimeInterval(2.0)
       while Date() < bootstrapDeadline {
-        if let image = captureFrame(), let cgImage = runnerCGImage(from: image) {
-          bootstrapImage = image
-          dimensions = CGSize(width: cgImage.width, height: cgImage.height)
+        switch capture() {
+        case .success(let captured):
+          bootstrapImage = captured.image
+          dimensions = CGSize(width: captured.pixelWidth, height: captured.pixelHeight)
+        case .failure(let failure):
+          lastFailure = failure
+        }
+        if dimensions.width > 0, dimensions.height > 0 {
           break
         }
         Thread.sleep(forTimeInterval: 0.05)
       }
       guard dimensions.width > 0, dimensions.height > 0 else {
-        throw NSError(
-          domain: "AgentDeviceRunner.Record",
-          code: 1,
-          userInfo: [NSLocalizedDescriptionKey: "failed to capture initial frame"]
-        )
+        // The bootstrap frame is required: the writer is sized from it. A capture that refused names
+        // why (no window, no display, unencodable image) so the host sees a typed reason rather than
+        // the generic "no frame" it used to collapse every refusal into (#2728). macOS keeps its
+        // host-display behavior and its original error, because nothing here is a panel question.
+        #if os(iOS)
+        throw RunnerTests.recordingBootstrapError(from: lastFailure)
+        #else
+        // macOS/tvOS preserve their original untyped record error regardless of why the host capture
+        // refused; the reason is read here only so the shared bootstrap loop carries no dead write.
+        _ = lastFailure
+        throw RunnerTests.recordingBootstrapError(from: nil)
+        #endif
       }
 
       let writer = try AVAssetWriter(outputURL: url, fileType: .mp4)
@@ -114,8 +129,8 @@ extension RunnerTests {
       timer.setEventHandler { [weak self] in
         guard let self else { return }
         if self.shouldStop() { return }
-        guard let image = captureFrame() else { return }
-        self.append(image: image)
+        guard case .success(let captured) = capture() else { return }
+        self.append(image: captured.image)
       }
       self.timer = timer
       timer.resume()
@@ -269,6 +284,31 @@ extension RunnerTests {
   }
 }
 
+extension RunnerTests {
+  /// The error a `record start` bootstrap raises when no initial frame arrived. On iOS the last capture
+  /// refusal (if any) is the honest reason and travels as its own typed code; only when nothing
+  /// refused — a macOS host capture, or a deadline that elapsed before any answer — does it fall back
+  /// to the original untyped record error, which keeps pre-panel behavior intact (#2728).
+  static func recordingBootstrapError(from lastFailure: RunnerAppScreenCaptureFailure?) -> Error {
+    lastFailure
+      ?? NSError(
+        domain: "AgentDeviceRunner.Record",
+        code: 1,
+        userInfo: [NSLocalizedDescriptionKey: "failed to capture initial frame"]
+      )
+  }
+
+  /// Maps a `record start` failure to the wire payload. A capture that refused carries a typed
+  /// `APP_SCREEN_*` reason, so a no-window bootstrap reaches the host as that code rather than the
+  /// generic record error it used to collapse into; a genuine writer failure keeps its message.
+  static func recordingStartErrorPayload(for error: Error) -> ErrorPayload {
+    if let failure = error as? RunnerAppScreenCaptureFailure {
+      return ErrorPayload(code: failure.rawValue, message: failure.message, hint: failure.hint)
+    }
+    return ErrorPayload(message: "failed to start recording: \(error.localizedDescription)")
+  }
+}
+
 #if AGENT_DEVICE_RUNNER_UNIT_TESTS
 extension RunnerTests.ScreenRecorder {
   @discardableResult
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+RecordingTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+RecordingTests.swift
index 8875716a6e..ce8bd2c2c5 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+RecordingTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+RecordingTests.swift
@@ -23,5 +23,76 @@ extension RunnerTests {
     // The helper records each returned value as an accepted frame.
     XCTAssertEqual(recorder.allocateTimestampForTesting(0), 101)
   }
+
+  func testRecordingBootstrapErrorKeepsTheTypedRefusalAndFallsBackGenerically() {
+    // A capture that refused is the honest bootstrap error; nothing refusing keeps the pre-panel
+    // untyped record error, so the iOS typed path and the macOS generic path are both pinned (#2728).
+    let typed = RunnerTests.recordingBootstrapError(from: .unresolvedWindow)
+    XCTAssertEqual(
+      (typed as? RunnerAppScreenCaptureFailure)?.rawValue,
+      "APP_SCREEN_WINDOW_UNRESOLVED"
+    )
+
+    let generic = RunnerTests.recordingBootstrapError(from: nil)
+    XCTAssertNil(generic as? RunnerAppScreenCaptureFailure)
+    XCTAssertEqual((generic as NSError).code, 1)
+  }
+
+  func testRecordingStartSurfacesACaptureRefusalAsATypedCode() {
+    // The bootstrap frame is required, so a no-window refusal must travel as its own code rather than
+    // the generic record error it used to collapse into; a real writer failure keeps its message (#2728).
+    let refusal = RunnerTests.recordingStartErrorPayload(
+      for: RunnerAppScreenCaptureFailure.unresolvedWindow
+    )
+    XCTAssertEqual(refusal.code, "APP_SCREEN_WINDOW_UNRESOLVED")
+    XCTAssertNotNil(refusal.hint)
+
+    let writerFailure = NSError(
+      domain: "AgentDeviceRunner.Record",
+      code: 5,
+      userInfo: [NSLocalizedDescriptionKey: "failed to append frame"]
+    )
+    let generic = RunnerTests.recordingStartErrorPayload(for: writerFailure)
+    XCTAssertNil(generic.code)
+    XCTAssertTrue(generic.message.contains("failed to start recording"))
+    XCTAssertTrue(generic.message.contains("failed to append frame"))
+  }
 #endif
 }
+
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS && os(iOS)
+extension RunnerTests {
+  func testRecordStartThrowsTheCaptureRefusalItReceived() throws {
+    // The bootstrap frame is required, so `record start` must surface the exact refusal its capture
+    // saw rather than the generic "failed to capture initial frame" every refusal used to collapse
+    // into, and that refusal must reach the host as its own code. Driving `start` with an always-
+    // refusing capture and mapping the ACTUAL thrown error — not a re-typed literal — proves the
+    // bootstrap forwards its last refusal end to end; the pure mapping tests cannot catch that wiring.
+    let outputPath = (NSTemporaryDirectory() as NSString).appendingPathComponent(
+      "record-refusal-\(UUID().uuidString).mp4"
+    )
+    let recorder = ScreenRecorder(outputPath: outputPath, fps: 30)
+
+    var captureCalls = 0
+    var thrown: Error?
+    XCTAssertThrowsError(
+      try recorder.start(capture: {
+        captureCalls += 1
+        return .failure(.unresolvedWindow)
+      })
+    ) { error in
+      thrown = error
+      XCTAssertEqual(
+        (error as? RunnerAppScreenCaptureFailure)?.rawValue,
+        "APP_SCREEN_WINDOW_UNRESOLVED",
+        "the thrown bootstrap error is the refusal the capture returned"
+      )
+    }
+    XCTAssertGreaterThan(captureCalls, 0, "the bootstrap must poll the injected capture")
+
+    // The refusal the bootstrap actually threw maps to its own host code, not the generic record error.
+    let payload = RunnerTests.recordingStartErrorPayload(for: try XCTUnwrap(thrown))
+    XCTAssertEqual(payload.code, "APP_SCREEN_WINDOW_UNRESOLVED")
+  }
+}
+#endif
diff --git a/docs/adr/0025-foldable-apple-panels.md b/docs/adr/0025-foldable-apple-panels.md
index 3d0e7c9705..7735c2601b 100644
--- a/docs/adr/0025-foldable-apple-panels.md
+++ b/docs/adr/0025-foldable-apple-panels.md
@@ -115,6 +115,21 @@ resolves a window. An app with no window is refused on the query's own `exists`
 its frame: a windowless app answers `frame` with `(0,0 0x0)` without raising, so geometry alone
 cannot say "no window".
 
+A visual *check* on an app's own transition is a different question, and the system surface's second
+answer would fabricate it. The `back` fallback's before/after comparison asks whether THIS app's
+screen changed under a leading tap the app itself received; two SpringBoard captures of the home
+screen are byte-identical no matter what the app did, so a system-surface sample would report
+"unchanged" for exactly the failure it is meant to catch. The check therefore observes the app's own
+resolved window and nothing else: an app that resolves no window reports the typed refusal as an
+unknown outcome, not as the false no-change a second process would produce (#2728).
+
+Required and optional consumers of the same helper split on the frame they are owed. `screenshot` and
+`record start`'s bootstrap frame are required — the recording sizes its whole writer from that first
+image — and each names why the capture did not happen with the shared `APP_SCREEN_*` reason, so a
+no-window runtime is a typed failure and never a generic one. The keyboard stability pump and the
+recording pump keep a nil-tolerant frame, because a dropped frame between polls is normal and says
+nothing about which display a window is on (#2728).
+
 Both answers are measured rather than assumed. A session with no app, and one whose app was terminated while still bound, answer the window query with `resolved=no`, and the capture that follows names the lit panel — on an unfolded Duo that is `LCD-1`, and the resulting home-screen image contains no black pixel. An app suspended by `home` keeps answering with a usable window, so it takes the first branch and still captures the panel it is on.
 
 `screenshot` is a runner-lifecycle command and skips the app-activation preflight, which left its
diff --git a/packages/platform-apple/src/runner/runner-contract.ts b/packages/platform-apple/src/runner/runner-contract.ts
index c4f143f648..2dd42692b7 100644
--- a/packages/platform-apple/src/runner/runner-contract.ts
+++ b/packages/platform-apple/src/runner/runner-contract.ts
@@ -152,11 +152,15 @@ export function resolveRunnerRequestSignal(options: {
 export const SCROLL_KEYBOARD_OCCLUDES_SURFACE_RUNNER_CODE = 'SCROLL_KEYBOARD_OCCLUDES_SURFACE';
 
 /**
- * The codes the XCTest runner answers with when a screenshot did not happen (#2728): no window
- * resolved so no display could be named, the resolved window named no display, or the resolved
- * display handed back an image it could not encode upright. They are the runner's own vocabulary, so
- * they are declared here beside the set that keeps them off the wire, and a required capture fails
- * closed on them rather than falling back to a screen nobody is on.
+ * The codes the XCTest runner answers with when a resolved-display capture it was asked to make did
+ * not happen (#2728): no window resolved so no display could be named, the resolved window named no
+ * display, or the resolved display handed back an image it could not encode upright. The runner emits
+ * them from every consumer of that helper — the `screenshot` command's fallback, `record start`'s
+ * required first frame, and an optional visual check such as the `back` fallback's before/after
+ * sample. They are the runner's own vocabulary, so they are declared here beside the set that keeps
+ * them off the wire; a required capture fails closed on them rather than falling back to a screen
+ * nobody is on, and an optional one reports the refusal as an unknown. Only the `screenshot` route
+ * consumes the set for its own simctl-to-runner decision, but the set names the whole family.
  */
 const RUNNER_SCREEN_WINDOW_UNRESOLVED_RUNNER_CODE = 'APP_SCREEN_WINDOW_UNRESOLVED';
 const RUNNER_SCREEN_UNRESOLVED_RUNNER_CODE = 'APP_SCREEN_UNRESOLVED';

From 746e9b3f63d8250d13fbce497e6dc733716c2a80 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Wed, 23 Sep 2026 16:10:16 +0200
Subject: [PATCH 041/132] fix(web): refuse the press shapes a browser click
 cannot drive (#2806)

An admitted `tapPoint` cell promised the whole point-press series, so `press --double`
and `press --hold` on a web session resolved the shared interactor's bare denials. The
browser backend drives one immediate pointer press per call: it repeats single taps for
`--count`, and carries no click count to fuse a double-click and no hold duration.

A hold is a capability an owner states, so `press --hold` is now refused by the same
`longPressPoint` cell that already refuses `longpress`, carrying the owner's reason and
hint. A fused double-click is a mechanic an interactor either has or leaves undefined, so
it joins the other optional owner mechanics and the shared series refuses the shape with
`details.reason: "owner-capability-missing"` before pressing anything.
---
 CHANGELOG.md                                  |  13 ++
 packages/contracts/src/interactor-types.ts    |   8 +-
 packages/contracts/src/touch-runtime.test.ts  | 190 +++++++++++++++++-
 packages/contracts/src/touch-runtime.ts       |  34 +++-
 .../interactor-runner-provider.test.ts        |   2 +-
 .../src/__tests__/interactor.test.ts          |   1 -
 .../__tests__/unsupported-interactor.test.ts  |   1 -
 .../src/unsupported-interactor.ts             |   1 -
 packages/platform-web/src/runtime.test.ts     |  67 +++++-
 packages/platform-web/src/runtime.ts          |  14 +-
 .../src/ios-interactor-double-tap.test.ts     |   4 +-
 src/core/__tests__/web-interactor.test.ts     |  10 +
 .../__tests__/unsupported-interactor.test.ts  |   6 +
 .../interactors/unsupported-interactor.ts     |   1 -
 .../command-coverage/declarations.ts          |   4 +-
 15 files changed, 341 insertions(+), 15 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1014a6774f..091d3c82af 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -15,6 +15,19 @@
   is reported. Because it stamps the raw source rather than the fold, `snapshot --raw` matches too, and
   the residue owner stays the fact owner (#2199). Closes the hittable-absence half of the AX-bridge
   capture divergence (#2638).
+- Fixed (web): `press --double` and `press --hold` on a web session now answer with a typed reason
+  instead of an unclassified `UNSUPPORTED_OPERATION` naming an interactor member. The browser owner's
+  `tapPoint` cell admitted the whole press series, but the web click affordance is one immediate
+  pointer press per call: `--count` repeats it, and this owner composes neither a fused double-click
+  nor a timed hold. A hold is refused by the `longPressPoint` cell that already refuses `longpress`,
+  so both commands now carry the hint "A web click is one immediate pointer press; the browser backend
+  has no timed hold." and `press --hold` adds `details.reason: "unsupported-platform-leaf"`. A
+  double-click is refused by the fused mechanic the web interactor no longer carries, reporting
+  `details.reason: "owner-capability-missing"`; both refusals arrive when the press runs, after any
+  target selector was resolved. A repeated single-tap press (`--count 3`) keeps working on the same
+  session, and every owner that double-tapped or held before this change still does: Android, iOS,
+  Linux, HarmonyOS, Cloud WebDriver and Limrun keep their own mechanics, and an owner with a fused
+  point press keeps answering `--double` through it.
 - Fixed (ios): a local Simulator snapshot taken through the host AX bridge once again carries the
   accessibility `selected` state, so `is selected`, a `selected=true` selector, and a Maestro
   `selected:` qualifier match the active control. When 0.21.0 made the AX bridge the Simulator's
diff --git a/packages/contracts/src/interactor-types.ts b/packages/contracts/src/interactor-types.ts
index 96cc751563..f71089193d 100644
--- a/packages/contracts/src/interactor-types.ts
+++ b/packages/contracts/src/interactor-types.ts
@@ -295,7 +295,13 @@ export type Interactor = {
   /** Owner-native ref routes; currently the managed web runtime is their only local owner. */
   tapRef?(ref: string): Promise<Record<string, unknown> | void>;
   tapElementSelector?(selector: ElementSelectorTapOptions): Promise<Record<string, unknown> | void>;
-  doubleTap(x: number, y: number): Promise<Record<string, unknown> | void>;
+  /**
+   * Fused double-click for owners that have one. The shared `--count` series cannot stand in for it —
+   * it spaces and jitters independent presses rather than firing one pair the target reads as a
+   * double — so an owner with no such mechanic leaves this undefined and `press --double` reports the
+   * gap instead of resolving a denial.
+   */
+  doubleTap?(x: number, y: number): Promise<Record<string, unknown> | void>;
   longPress(x: number, y: number, durationMs?: number): Promise<Record<string, unknown> | void>;
   /**
    * Move the pointer to a point without pressing. Only pointer-driven
diff --git a/packages/contracts/src/touch-runtime.test.ts b/packages/contracts/src/touch-runtime.test.ts
index 736a279cae..339de10d84 100644
--- a/packages/contracts/src/touch-runtime.test.ts
+++ b/packages/contracts/src/touch-runtime.test.ts
@@ -1,5 +1,6 @@
 import { expect, test, vi } from 'vitest';
-import type { Interactor } from './interactor-types.ts';
+import { AppError } from '@agent-device/kernel/errors';
+import type { Interactor, PressPointOptions } from './interactor-types.ts';
 import {
   bindLocalTouchInteractor,
   HOVER_UNAVAILABLE_HINT,
@@ -143,3 +144,190 @@ test('the shared primary series preserves jitter, interval, and every press', as
   ]);
   expect(pause.mock.calls).toEqual([[40], [40]]);
 });
+
+// A point press is one operation whose options carry several shapes, and two of them ask for more
+// than the shared series can compose. A timed hold is a capability an owner states with its
+// `longPressPoint` cell; a fused double-click is a mechanic its interactor either has or leaves
+// undefined. Either way the shape is refused with a typed reason instead of resolving a member that
+// only knows how to throw.
+const holdRefused = (hint?: string) =>
+  touchRuntimeOperationFacts({
+    unsupported: unavailable,
+    tap: available,
+    longPress:
+      hint === undefined
+        ? unavailable
+        : { available: false, reason: 'unsupported-platform-leaf', hint },
+    fill: available,
+  });
+
+const pressOptions = {
+  button: 'primary',
+  count: 1,
+  intervalMs: 0,
+  holdMs: 0,
+  jitterPx: 0,
+  doubleTap: false,
+} as const;
+
+function bindSharedSeries(
+  seriesFacts: ReturnType<typeof touchRuntimeOperationFacts>,
+  mechanics: Partial<
+    Record<'tap' | 'doubleTap' | 'longPress' | 'pressPoint', ReturnType<typeof vi.fn>>
+  >,
+) {
+  return bindLocalTouchInteractor({
+    device,
+    signal: new AbortController().signal,
+    resolveInteractor: async () => mechanics as unknown as Interactor,
+    facts: seriesFacts,
+    pause: async () => {},
+  });
+}
+
+const refusedBy =
+  (reason: string) =>
+  (error: unknown): boolean =>
+    error instanceof AppError &&
+    error.code === 'UNSUPPORTED_OPERATION' &&
+    error.details?.['reason'] === reason;
+
+const press = (
+  operations: ReturnType<typeof bindSharedSeries>,
+  options: Partial<PressPointOptions> = {},
+) =>
+  operations.tapPoint!({
+    point: { x: 20, y: 30 },
+    options: { ...pressOptions, ...options },
+  });
+
+test('a hold the owner refuses is refused by its fact, over an interactor that can hold', async () => {
+  const longPress = vi.fn(async () => undefined);
+  const operations = bindSharedSeries(holdRefused('Use a native gesture instead.'), {
+    tap: vi.fn(async () => undefined),
+    longPress,
+  });
+
+  await expect(press(operations, { holdMs: 600 })).rejects.toSatisfy(
+    refusedBy('unsupported-platform-leaf'),
+  );
+  await expect(press(operations, { holdMs: 600 })).rejects.toMatchObject({
+    details: { reason: 'unsupported-platform-leaf', hint: 'Use a native gesture instead.' },
+  });
+
+  expect(longPress).not.toHaveBeenCalled();
+});
+
+test('an owner with no double-click mechanic refuses --double before pressing anything', async () => {
+  const tap = vi.fn(async () => undefined);
+  const operations = bindSharedSeries(holdRefused(), { tap });
+
+  await expect(press(operations, { doubleTap: true })).rejects.toSatisfy(
+    refusedBy('owner-capability-missing'),
+  );
+
+  expect(tap).not.toHaveBeenCalled();
+});
+
+test('the same hold refusal wording carries whatever reason the owner states', async () => {
+  const refusals = await Promise.all(
+    [
+      touchRuntimeOperationFacts({
+        unsupported: unavailable,
+        tap: available,
+        longPress: unavailable,
+        fill: available,
+      }),
+      touchRuntimeOperationFacts({
+        unsupported: unavailable,
+        tap: available,
+        longPress: { available: false, reason: 'unsupported-device-kind' },
+        fill: available,
+      }),
+    ].map(
+      async (seriesFacts) =>
+        await bindSharedSeries(seriesFacts, { longPress: vi.fn() }).tapPoint!({
+          point: { x: 1, y: 1 },
+          options: { ...pressOptions, holdMs: 600 },
+        })
+          .then(() => undefined)
+          .catch((error: unknown) => error),
+    ),
+  );
+
+  const [leaf, deviceKind] = refusals as [AppError, AppError];
+  // Identical wording and code, so nothing reading the message can tell the two owners apart…
+  expect(deviceKind.message).toEqual(leaf.message);
+  expect(deviceKind.code).toEqual(leaf.code);
+  // …and the typed reason is the only thing that can.
+  expect(leaf).toSatisfy(refusedBy('unsupported-platform-leaf'));
+  expect(deviceKind).toSatisfy(refusedBy('unsupported-device-kind'));
+});
+
+// The three tests below pin behavior this change must not disturb, so they are green before it too.
+test('an owner that states each shape reaches its own mechanic', async () => {
+  const mechanics = {
+    tap: vi.fn(async () => undefined),
+    doubleTap: vi.fn(async () => ({ double: true })),
+    longPress: vi.fn(async () => ({ held: true })),
+  };
+  const operations = bindSharedSeries(facts, mechanics);
+
+  await expect(press(operations, { doubleTap: true })).resolves.toEqual({ double: true });
+  await expect(press(operations, { holdMs: 600 })).resolves.toEqual({ held: true });
+
+  expect(mechanics.doubleTap).toHaveBeenCalledWith(20, 30);
+  expect(mechanics.longPress).toHaveBeenCalledWith(20, 30, 600);
+});
+
+test('an owner with a fused point press keeps its own --double route without a double-click member', async () => {
+  const pressPoint = vi.fn(async () => ({ fused: true }));
+  const operations = bindSharedSeries(facts, { pressPoint });
+
+  await expect(
+    operations.tapPoint!({
+      point: { x: 20, y: 30 },
+      options: { ...pressOptions, doubleTap: true },
+    }),
+  ).resolves.toEqual({ fused: true });
+
+  expect(pressPoint).toHaveBeenCalledWith(
+    { x: 20, y: 30 },
+    expect.objectContaining({ doubleTap: true }),
+  );
+});
+
+test('a repeated single tap keeps running where the owner refuses a hold and has no double-click', async () => {
+  const tap = vi.fn(async () => undefined);
+  const operations = bindSharedSeries(holdRefused(), { tap });
+
+  await expect(press(operations, { count: 2, jitterPx: 1 })).resolves.toBeUndefined();
+
+  expect(tap.mock.calls).toEqual([
+    [20, 30],
+    [21, 30],
+  ]);
+});
+
+// The mechanic is read off the interactor, so an owner written as a class has to keep its own
+// receiver: both provider interactors are classes that reach their session through `this`.
+test('the fused double-click keeps the interactor as its receiver', async () => {
+  class PointerOwner {
+    readonly pressed: Array<[number, number]> = [];
+    async doubleTap(x: number, y: number): Promise<void> {
+      this.pressed.push([x, y]);
+    }
+  }
+  const owner = new PointerOwner();
+  const operations = bindLocalTouchInteractor({
+    device,
+    signal: new AbortController().signal,
+    resolveInteractor: async () => owner as unknown as Interactor,
+    facts,
+    pause: async () => {},
+  });
+
+  await press(operations, { doubleTap: true });
+
+  expect(owner.pressed).toEqual([[20, 30]]);
+});
diff --git a/packages/contracts/src/touch-runtime.ts b/packages/contracts/src/touch-runtime.ts
index 04a360ace1..600dcaf281 100644
--- a/packages/contracts/src/touch-runtime.ts
+++ b/packages/contracts/src/touch-runtime.ts
@@ -136,6 +136,8 @@ function bindTouch(
     return await resolveInteractor(runnerContext(input, signal));
   };
   const tapPoint = async (input: TapPointInput) => {
+    signal.throwIfAborted();
+    requireAdmittedHold(input.options, facts.longPressPoint);
     const interactor = await interactorFor(input);
     if (input.options.button !== 'primary' && interactor.alternateClick) {
       return await interactor.alternateClick(input.point, input.options.button);
@@ -221,6 +223,33 @@ function missingAdvertisedOperation(name: string): never {
   );
 }
 
+/**
+ * Two shapes of a point press ask for more than the shared series can compose. A hold is a capability
+ * an owner states with its `longPressPoint` cell, so `press --hold` is refused by the same fact that
+ * refuses `longpress`, carrying the owner's reason and hint.
+ */
+function requireAdmittedHold(options: PressPointOptions, fact: RuntimeOperationFact): void {
+  if (options.holdMs <= 0 || fact.available) return;
+  throw new AppError('UNSUPPORTED_OPERATION', 'press-and-hold is not supported by this runtime.', {
+    reason: fact.reason,
+    ...(fact.hint === undefined ? {} : { hint: fact.hint }),
+  });
+}
+
+/**
+ * A fused double-click is the one press shape no fact can state: facts speak per operation, and no
+ * command names a double-tap operation. The interactor member is the owner's only claim, so an absent
+ * one is a capability it declines — where an absent alert member is an ownership bug, because the
+ * alert leg's operation was admitted and this shape never was.
+ */
+function requireDoubleTapMechanic(interactor: Interactor): NonNullable<Interactor['doubleTap']> {
+  if (interactor.doubleTap) return interactor.doubleTap;
+  throw new AppError('UNSUPPORTED_OPERATION', 'double-tap is not supported by this runtime.', {
+    reason: 'owner-capability-missing',
+    hint: 'This runtime drives single presses; use --count to repeat them.',
+  });
+}
+
 async function executeGenericPress(
   interactor: Interactor,
   point: Point,
@@ -233,11 +262,12 @@ async function executeGenericPress(
       `Bound runtime does not implement ${options.button} click.`,
     );
   }
+  const doubleTap = options.doubleTap ? requireDoubleTapMechanic(interactor) : undefined;
   let first: Record<string, unknown> | void = undefined;
   for (let index = 0; index < options.count; index += 1) {
     const [dx, dy] = pressJitter(index, options.jitterPx);
-    const result = options.doubleTap
-      ? await interactor.doubleTap(point.x + dx, point.y + dy)
+    const result = doubleTap
+      ? await doubleTap.call(interactor, point.x + dx, point.y + dy)
       : options.holdMs > 0
         ? await interactor.longPress(point.x + dx, point.y + dy, options.holdMs)
         : await interactor.tap(point.x + dx, point.y + dy);
diff --git a/packages/platform-apple/src/__tests__/interactor-runner-provider.test.ts b/packages/platform-apple/src/__tests__/interactor-runner-provider.test.ts
index 3c558b90db..e9b1aea8da 100644
--- a/packages/platform-apple/src/__tests__/interactor-runner-provider.test.ts
+++ b/packages/platform-apple/src/__tests__/interactor-runner-provider.test.ts
@@ -51,7 +51,7 @@ const RUNNER_TRANSPORT_METHODS: Record<
     invoke: (i) => i.tapElementSelector!({ key: 'label', value: 'Go' }),
     runnerCommand: 'tap',
   },
-  doubleTap: { invoke: (i) => i.doubleTap(10, 20), runnerCommand: 'sequence' },
+  doubleTap: { invoke: (i) => i.doubleTap!(10, 20), runnerCommand: 'sequence' },
   longPress: { invoke: (i) => i.longPress(10, 20, 600), runnerCommand: 'longPress' },
   focus: { invoke: (i) => i.focus(10, 20), runnerCommand: 'tap' },
   type: { invoke: (i) => i.type('hi'), runnerCommand: 'type' },
diff --git a/packages/platform-vega/src/__tests__/interactor.test.ts b/packages/platform-vega/src/__tests__/interactor.test.ts
index 3e00b91a2c..38a7766033 100644
--- a/packages/platform-vega/src/__tests__/interactor.test.ts
+++ b/packages/platform-vega/src/__tests__/interactor.test.ts
@@ -121,7 +121,6 @@ test('required unproven Vega operations share typed unsupported behavior', async
   const interactor = createVegaInteractor(VEGA_VVD, {});
   const unsupportedCalls: ReadonlyArray<readonly [string, () => Promise<unknown>]> = [
     ['tap', () => interactor.tap(10, 20)],
-    ['doubleTap', () => interactor.doubleTap(10, 20)],
     ['longPress', () => interactor.longPress(10, 20, 500)],
     ['focus', () => interactor.focus(10, 20)],
     ['type', () => interactor.type('text')],
diff --git a/packages/platform-vega/src/__tests__/unsupported-interactor.test.ts b/packages/platform-vega/src/__tests__/unsupported-interactor.test.ts
index 02ee9ef151..ac3f486aa7 100644
--- a/packages/platform-vega/src/__tests__/unsupported-interactor.test.ts
+++ b/packages/platform-vega/src/__tests__/unsupported-interactor.test.ts
@@ -8,7 +8,6 @@ const OPERATIONS = [
   'openDevice',
   'close',
   'tap',
-  'doubleTap',
   'longPress',
   'focus',
   'type',
diff --git a/packages/platform-vega/src/unsupported-interactor.ts b/packages/platform-vega/src/unsupported-interactor.ts
index f96e878cc3..d96f3b7715 100644
--- a/packages/platform-vega/src/unsupported-interactor.ts
+++ b/packages/platform-vega/src/unsupported-interactor.ts
@@ -15,7 +15,6 @@ export function createUnsupportedInteractor(platformLabel: string): Interactor {
     openDevice: () => unsupported('openDevice'),
     close: () => unsupported('close'),
     tap: () => unsupported('tap'),
-    doubleTap: () => unsupported('doubleTap'),
     longPress: () => unsupported('longPress'),
     focus: () => unsupported('focus'),
     type: () => unsupported('type'),
diff --git a/packages/platform-web/src/runtime.test.ts b/packages/platform-web/src/runtime.test.ts
index 52ac3d8d8f..f25bccc885 100644
--- a/packages/platform-web/src/runtime.test.ts
+++ b/packages/platform-web/src/runtime.test.ts
@@ -6,8 +6,9 @@ import type {
   PlatformRuntimeHost,
   PlatformRuntimeOperations,
 } from '@agent-device/contracts/platform-runtime-operations';
-import type { Interactor } from '@agent-device/contracts/interactor-types';
+import type { Interactor, PressPointOptions } from '@agent-device/contracts/interactor-types';
 import type { DeviceInfo } from '@agent-device/kernel/device';
+import { AppError } from '@agent-device/kernel/errors';
 import { createWebPlatformRuntime } from './runtime.ts';
 
 const device: DeviceInfo = {
@@ -604,3 +605,67 @@ test('press shares the admitted tapPoint fact that live click, press and react-n
   expect(binding.facts.operations.tapPoint).toEqual({ available: true });
   expect(binding.operations.tapPoint).toBeTypeOf('function');
 });
+
+/**
+ * A browser click is one immediate pointer press, which is all a repeated `--count` series needs. The
+ * two shapes that ask for more used to ride the admitted `tapPoint` fact into the interactor's bare
+ * denial — a hold into its `longPress` stub, a double-click into a member the web factory no longer
+ * supplies. Each now answers from its own authority: this module's fact for a hold, the absent
+ * mechanic for a fused double-click.
+ */
+test('a browser press repeats single taps and refuses the hold and double-tap shapes it has no mechanic for', async () => {
+  const clicked: Array<[number, number]> = [];
+  const denied: string[] = [];
+  const interactor = {
+    tap: async (x: number, y: number) => {
+      clicked.push([x, y]);
+    },
+    longPress: async () => {
+      denied.push('longPress');
+      throw new AppError('UNSUPPORTED_OPERATION', 'longPress is not supported on web');
+    },
+  } as unknown as Interactor;
+  const binding = await createWebPlatformRuntime(
+    host({ mode: 'local' }, undefined, interactor),
+  ).bind({ device, intent: { kind: 'ordinary' }, scope: scope() });
+
+  expect(binding.facts.operations.tapPoint).toEqual({ available: true });
+  expect(binding.facts.operations.longPressPoint).toMatchObject({
+    available: false,
+    reason: 'unsupported-platform-leaf',
+    hint: 'A web click is one immediate pointer press; the browser backend has no timed hold.',
+  });
+
+  const press = (options: Partial<PressPointOptions>) =>
+    binding.operations.tapPoint!({
+      point: { x: 10, y: 20 },
+      options: {
+        button: 'primary',
+        count: 1,
+        intervalMs: 0,
+        holdMs: 0,
+        jitterPx: 0,
+        doubleTap: false,
+        ...options,
+      },
+    });
+
+  await expect(press({ count: 2, jitterPx: 1 })).resolves.toBeUndefined();
+  expect(clicked).toEqual([
+    [10, 20],
+    [11, 20],
+  ]);
+
+  await expect(press({ holdMs: 600 })).rejects.toMatchObject({
+    code: 'UNSUPPORTED_OPERATION',
+    details: {
+      reason: 'unsupported-platform-leaf',
+      hint: 'A web click is one immediate pointer press; the browser backend has no timed hold.',
+    },
+  });
+  await expect(press({ doubleTap: true })).rejects.toMatchObject({
+    code: 'UNSUPPORTED_OPERATION',
+    details: { reason: 'owner-capability-missing' },
+  });
+  expect(denied).toEqual([]);
+});
diff --git a/packages/platform-web/src/runtime.ts b/packages/platform-web/src/runtime.ts
index ebb2cf131d..883ac73069 100644
--- a/packages/platform-web/src/runtime.ts
+++ b/packages/platform-web/src/runtime.ts
@@ -114,6 +114,18 @@ const nativeRefUnavailable = Object.freeze({
   available: false,
   reason: 'owner-capability-missing',
 } as const);
+/**
+ * The web click affordance is one immediate pointer press, which is everything `press` needs for a
+ * repeated `--count` series. Timed actions are a policy this owner declines rather than a missing
+ * primitive: the browser could compose a raw pointer down/up pair around a wait and does not, so the
+ * cell denies the hold rather than borrowing the tap cell that admits the series. The fused
+ * double-click is declined one level down, by the interactor member the browser never supplies.
+ */
+const holdUnavailable = Object.freeze({
+  available: false,
+  reason: 'unsupported-platform-leaf',
+  hint: 'A web click is one immediate pointer press; the browser backend has no timed hold.',
+} as const);
 const audioCaptureUnavailable = Object.freeze({
   available: false,
   reason: 'unsupported-platform-leaf',
@@ -386,7 +398,7 @@ function webRuntimeFacts(
         unsupported: readinessUnavailable,
         tap: browserDevice,
         tapRef: webOptionalOperationFact(interactor?.tapRef, browserDevice),
-        longPress: readinessUnavailable,
+        longPress: holdUnavailable,
         hover: webOptionalOperationFact(interactor?.hover, browserDevice),
         hoverRef: webOptionalOperationFact(interactor?.hoverRef, browserDevice),
         fill: browserDevice,
diff --git a/packages/provider-limrun/src/ios-interactor-double-tap.test.ts b/packages/provider-limrun/src/ios-interactor-double-tap.test.ts
index 3d33e65642..cf6dfcb251 100644
--- a/packages/provider-limrun/src/ios-interactor-double-tap.test.ts
+++ b/packages/provider-limrun/src/ios-interactor-double-tap.test.ts
@@ -17,7 +17,7 @@ function sessionWithClient() {
 test('double tap sends both taps in one batch with the pause enforced on the device', async () => {
   const { interactor, client } = sessionWithClient();
 
-  await interactor.doubleTap(120, 340);
+  await interactor.doubleTap!(120, 340);
 
   expect(client.performActions).toHaveBeenCalledTimes(1);
   expect(client.performActions).toHaveBeenCalledWith([
@@ -32,5 +32,5 @@ test('a batch the device rejects surfaces as the double tap failure', async () =
   const { interactor, client } = sessionWithClient();
   client.performActions.mockRejectedValueOnce(new Error('tap: no foreground application'));
 
-  await expect(interactor.doubleTap(120, 340)).rejects.toThrow('tap: no foreground application');
+  await expect(interactor.doubleTap!(120, 340)).rejects.toThrow('tap: no foreground application');
 });
diff --git a/src/core/__tests__/web-interactor.test.ts b/src/core/__tests__/web-interactor.test.ts
index 867fd0dca0..82c35feaeb 100644
--- a/src/core/__tests__/web-interactor.test.ts
+++ b/src/core/__tests__/web-interactor.test.ts
@@ -89,6 +89,16 @@ test('web interactor reports hover unsupported when the provider lacks it', asyn
   });
 });
 
+// `press --double` refuses through the absent mechanic, so the interactor the daemon composes for a
+// web session must carry no fused double-click of its own.
+test('web interactor carries no fused double-click mechanic', async () => {
+  await withWebProvider(makeWebProvider(), async () => {
+    const interactor = await createWebInteractor();
+
+    assert.equal(interactor.doubleTap, undefined);
+  });
+});
+
 test('web interactor reports unsupported operations explicitly', async () => {
   const interactor = await createWebInteractor();
 
diff --git a/src/core/interactors/__tests__/unsupported-interactor.test.ts b/src/core/interactors/__tests__/unsupported-interactor.test.ts
index 0c474fd0fa..9f8e001058 100644
--- a/src/core/interactors/__tests__/unsupported-interactor.test.ts
+++ b/src/core/interactors/__tests__/unsupported-interactor.test.ts
@@ -28,6 +28,12 @@ test('every operation on the factory rejects, naming itself and the platform', a
   assert.deepEqual(failures.filter(Boolean), []);
 });
 
+test('a fused double-click is left undefined, not denied, so a shared series reports the gap', () => {
+  const interactor = createUnsupportedInteractor('web');
+
+  assert.equal(interactor.doubleTap, undefined);
+});
+
 test('a rejection carries no partial result the caller could mistake for success', async () => {
   const interactor = createUnsupportedInteractor('Linux desktop');
 
diff --git a/src/core/interactors/unsupported-interactor.ts b/src/core/interactors/unsupported-interactor.ts
index ab1c89ef7b..70aae68a18 100644
--- a/src/core/interactors/unsupported-interactor.ts
+++ b/src/core/interactors/unsupported-interactor.ts
@@ -14,7 +14,6 @@ export function createUnsupportedInteractor(platformLabel: string): Interactor {
     openDevice: () => unsupported('openDevice'),
     close: () => unsupported('close'),
     tap: () => unsupported('tap'),
-    doubleTap: () => unsupported('doubleTap'),
     longPress: () => unsupported('longPress'),
     focus: () => unsupported('focus'),
     type: () => unsupported('type'),
diff --git a/test/integration/command-coverage/declarations.ts b/test/integration/command-coverage/declarations.ts
index 17168c0c5a..7495497e7a 100644
--- a/test/integration/command-coverage/declarations.ts
+++ b/test/integration/command-coverage/declarations.ts
@@ -886,8 +886,8 @@ const COMMAND_COVERAGE_DECLARATIONS = {
     tvos: tvos.gap('No tvOS-specific long-press command evidence exists yet'),
     web: web.contract(
       'packages/platform-web/src/runtime.ts',
-      'longPress: readinessUnavailable',
-      'the web runtime fact rejects touch long-press input',
+      'longPress: holdUnavailable',
+      'the web runtime fact declines the timed hold as a platform leaf',
     ),
     linux: linux.contract(
       LINUX_PROVIDER_EVIDENCE.path,

From d9887684db4c9a0e7782f3174ca79fce192980be Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Wed, 23 Sep 2026 16:10:17 +0200
Subject: [PATCH 042/132] refactor(contracts): make the alert legs optional
 members and drop their denials (#2807)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* refactor(contracts): make the alert legs optional members and drop their denials

ADR 0019 keeps a stub that throws `unsupported` out of the interactor: an owner with no
alert surface says so with its facts, and the facts are what the binding consults. Every
alert leg was reachable only through `bindAlertLeg`, which the catalog calls for exactly
the legs a binding's facts admitted — and web, Linux, HarmonyOS, Vega, Cloud WebDriver and
the Limrun iOS direct session all refuse all four cells unconditionally. Their interactor
denials were therefore unreachable code pretending to be an implementation.

All four members become optional, so `bindAlertLeg` now fails closed through
`requireInteractorMethod` when a fact admits a leg its interactor cannot serve, naming the
leg with the label the catalog already used. Apple and Android keep their real mechanics.

* docs(provider-webdriver): state the alert cell's absence, not a deleted denial

The cell's docblock described alert legs that this PR removes. It also sat stacked on top of the
settings docblock, which had been orphaned off `settingsUnavailable` on main; the pair now reads
one doc per const.
---
 packages/contracts/src/alert-runtime.test.ts  | 20 +++++++++++++++++++
 packages/contracts/src/alert-runtime.ts       | 14 ++++++++++++-
 .../src/interactor-operation-catalog.ts       | 10 +++++-----
 packages/contracts/src/interactor-types.ts    | 12 +++++++----
 .../interactor-runner-provider.test.ts        |  8 ++++----
 .../__tests__/unsupported-interactor.test.ts  |  6 +-----
 .../src/unsupported-interactor.ts             |  4 ----
 packages/provider-limrun/src/ios.ts           | 20 -------------------
 .../src/platform-runtime.ts                   | 17 ++++++++--------
 .../src/webdriver-interactor.ts               | 18 -----------------
 src/core/interactors/harmonyos.ts             |  6 ------
 src/core/interactors/linux.ts                 |  9 ---------
 .../interactors/unsupported-interactor.ts     |  4 ----
 .../__tests__/snapshot-runtime-fixture.ts     |  8 ++++----
 .../snapshot-alert-android-occlusion.test.ts  | 12 +++++------
 .../ios-alert-settings.test.ts                |  8 ++++----
 16 files changed, 73 insertions(+), 103 deletions(-)

diff --git a/packages/contracts/src/alert-runtime.test.ts b/packages/contracts/src/alert-runtime.test.ts
index 94d1f7cd5a..d0a5dab34d 100644
--- a/packages/contracts/src/alert-runtime.test.ts
+++ b/packages/contracts/src/alert-runtime.test.ts
@@ -1,4 +1,5 @@
 import { expect, test, vi } from 'vitest';
+import { AppError } from '@agent-device/kernel/errors';
 import { alertRuntimeOperationFacts, bindAlertLeg } from './alert-runtime.ts';
 import { localInteractorSource } from './interactor-operation-binding.ts';
 import type { AlertInteractorOptions, Interactor } from './interactor-types.ts';
@@ -82,3 +83,22 @@ test('an absent target field never reaches the owner as an explicit undefined',
   expect(readAlert).toHaveBeenCalledWith({ surface: 'frontmost-app' });
   expect(Object.keys(readAlert.mock.calls[0]?.[0] ?? {})).toEqual(['surface']);
 });
+
+// Facts admitted the leg, so an interactor without it is an ownership bug the caller must see
+// rather than a refusal to degrade around. The label is the one the command already used.
+test('a leg whose fact admitted but whose interactor cannot serve it fails closed', async () => {
+  const served = { acceptAlert: vi.fn(async () => ({ accepted: true })) } as unknown as Interactor;
+  const source = localInteractorSource({
+    device,
+    resolveInteractor: async () => ({ ...served, acceptAlert: undefined }),
+  });
+  const operations = bindAlertLeg('acceptAlert', new AbortController().signal, source);
+
+  await expect(operations.acceptAlert({})).rejects.toSatisfy(
+    (error: unknown) =>
+      error instanceof AppError &&
+      error.code === 'COMMAND_FAILED' &&
+      error.details?.['reason'] === 'interactor-method-missing' &&
+      error.message.includes('alert accept'),
+  );
+});
diff --git a/packages/contracts/src/alert-runtime.ts b/packages/contracts/src/alert-runtime.ts
index 59773a58e8..b3879cd205 100644
--- a/packages/contracts/src/alert-runtime.ts
+++ b/packages/contracts/src/alert-runtime.ts
@@ -104,6 +104,14 @@ function alertInteractorOptions(input: AlertRuntimeInput): AlertInteractorOption
 
 type AlertLeg = 'readAlert' | 'awaitAlert' | 'acceptAlert' | 'dismissAlert';
 
+/** How a fail-closed refusal names each leg to the caller, matching the command that asked for it. */
+export const ALERT_LEG_LABELS = {
+  readAlert: 'alert get',
+  awaitAlert: 'alert wait',
+  acceptAlert: 'alert accept',
+  dismissAlert: 'alert dismiss',
+} as const satisfies Record<AlertLeg, string>;
+
 export function bindAlertLeg<Leg extends AlertLeg>(
   leg: Leg,
   signal: AbortSignal,
@@ -112,7 +120,11 @@ export function bindAlertLeg<Leg extends AlertLeg>(
   return Object.freeze({
     [leg]: async (input: AlertRuntimeInput) => {
       const interactor = await resolveAlertInteractor(signal, resolveInteractor, input);
-      return await interactor[leg](alertInteractorOptions(input));
+      // Loaded on the call rather than at module evaluation because this module's eager closure is
+      // held at its merge-base size (`eager-closure-budgets`); a static edge would grow it.
+      const { requireInteractorMethod } = await import('./interactor-operation-binding.ts');
+      const method = requireInteractorMethod(interactor[leg], ALERT_LEG_LABELS[leg]);
+      return await method.call(interactor, alertInteractorOptions(input));
     },
   }) as Readonly<Record<Leg, (input: AlertRuntimeInput) => Promise<Record<string, unknown>>>>;
 }
diff --git a/packages/contracts/src/interactor-operation-catalog.ts b/packages/contracts/src/interactor-operation-catalog.ts
index 49d292b3fc..15c16494fe 100644
--- a/packages/contracts/src/interactor-operation-catalog.ts
+++ b/packages/contracts/src/interactor-operation-catalog.ts
@@ -1,5 +1,5 @@
 import type { DeviceInfo } from '@agent-device/kernel/device';
-import { bindAlertLeg } from './alert-runtime.ts';
+import { ALERT_LEG_LABELS, bindAlertLeg } from './alert-runtime.ts';
 import { bindAppEvent } from './app-event-runtime.ts';
 import { bindBack } from './back-runtime.ts';
 import { bindClipboardRead, bindClipboardWrite } from './clipboard-runtime.ts';
@@ -91,22 +91,22 @@ export const INTERACTOR_OPERATIONS = [
   { operation: 'readSetting', label: 'settings read', bind: bindReadSetting },
   {
     operation: 'readAlert',
-    label: 'alert get',
+    label: ALERT_LEG_LABELS.readAlert,
     bind: (signal, resolve) => bindAlertLeg('readAlert', signal, resolve),
   },
   {
     operation: 'awaitAlert',
-    label: 'alert wait',
+    label: ALERT_LEG_LABELS.awaitAlert,
     bind: (signal, resolve) => bindAlertLeg('awaitAlert', signal, resolve),
   },
   {
     operation: 'acceptAlert',
-    label: 'alert accept',
+    label: ALERT_LEG_LABELS.acceptAlert,
     bind: (signal, resolve) => bindAlertLeg('acceptAlert', signal, resolve),
   },
   {
     operation: 'dismissAlert',
-    label: 'alert dismiss',
+    label: ALERT_LEG_LABELS.dismissAlert,
     bind: (signal, resolve) => bindAlertLeg('dismissAlert', signal, resolve),
   },
 ] as const satisfies readonly InteractorOperationDefinition[];
diff --git a/packages/contracts/src/interactor-types.ts b/packages/contracts/src/interactor-types.ts
index f71089193d..fc178c4ad0 100644
--- a/packages/contracts/src/interactor-types.ts
+++ b/packages/contracts/src/interactor-types.ts
@@ -395,11 +395,15 @@ export type Interactor = {
    * poll: an alert is a transient device surface, and how long to look for it — and how to press
    * its buttons — is family mechanics, not something a caller can supply. `timeoutMs` is the
    * whole window the caller allows; the owner spends it however its backend requires.
+   *
+   * Optional: an owner with no alert surface leaves all four undefined. Its facts refuse every leg
+   * before binding, so the absent members are never resolved, and a fact that admitted a leg the
+   * interactor cannot serve fails closed instead of answering empty.
    */
-  readAlert(options?: AlertInteractorOptions): Promise<Record<string, unknown>>;
-  awaitAlert(options?: AlertInteractorOptions): Promise<Record<string, unknown>>;
-  acceptAlert(options?: AlertInteractorOptions): Promise<Record<string, unknown>>;
-  dismissAlert(options?: AlertInteractorOptions): Promise<Record<string, unknown>>;
+  readAlert?(options?: AlertInteractorOptions): Promise<Record<string, unknown>>;
+  awaitAlert?(options?: AlertInteractorOptions): Promise<Record<string, unknown>>;
+  acceptAlert?(options?: AlertInteractorOptions): Promise<Record<string, unknown>>;
+  dismissAlert?(options?: AlertInteractorOptions): Promise<Record<string, unknown>>;
 };
 
 /**
diff --git a/packages/platform-apple/src/__tests__/interactor-runner-provider.test.ts b/packages/platform-apple/src/__tests__/interactor-runner-provider.test.ts
index e9b1aea8da..eeea455a2c 100644
--- a/packages/platform-apple/src/__tests__/interactor-runner-provider.test.ts
+++ b/packages/platform-apple/src/__tests__/interactor-runner-provider.test.ts
@@ -81,10 +81,10 @@ const RUNNER_TRANSPORT_METHODS: Record<
   // R59: same reading as `readTextAtPoint` — the macOS-helper branch is reachable only for a
   // local desktop surface, which a provider-owned mobile device never carries, so every
   // provider-backed alert leg rides the runner. Each spends one runner call when it succeeds.
-  readAlert: { invoke: (i) => i.readAlert(), runnerCommand: 'alert' },
-  awaitAlert: { invoke: (i) => i.awaitAlert(), runnerCommand: 'alert' },
-  acceptAlert: { invoke: (i) => i.acceptAlert(), runnerCommand: 'alert' },
-  dismissAlert: { invoke: (i) => i.dismissAlert(), runnerCommand: 'alert' },
+  readAlert: { invoke: (i) => i.readAlert!(), runnerCommand: 'alert' },
+  awaitAlert: { invoke: (i) => i.awaitAlert!(), runnerCommand: 'alert' },
+  acceptAlert: { invoke: (i) => i.acceptAlert!(), runnerCommand: 'alert' },
+  dismissAlert: { invoke: (i) => i.dismissAlert!(), runnerCommand: 'alert' },
 };
 
 const LOCAL_TOOL_METHODS: Record<string, (interactor: Interactor) => Promise<unknown>> = {
diff --git a/packages/platform-vega/src/__tests__/unsupported-interactor.test.ts b/packages/platform-vega/src/__tests__/unsupported-interactor.test.ts
index ac3f486aa7..ddfdc2410a 100644
--- a/packages/platform-vega/src/__tests__/unsupported-interactor.test.ts
+++ b/packages/platform-vega/src/__tests__/unsupported-interactor.test.ts
@@ -23,10 +23,6 @@ const OPERATIONS = [
   'readClipboard',
   'writeClipboard',
   'setSetting',
-  'readAlert',
-  'awaitAlert',
-  'acceptAlert',
-  'dismissAlert',
 ] as const;
 
 test('every operation rejects as unsupported and names the platform', async () => {
@@ -46,7 +42,7 @@ test('the label is per-instance, so two platforms reject with their own wording'
   await expectUnsupported(vega, 'home', 'Vega OS');
 });
 
-test('the factory covers the whole interactor surface', () => {
+test('the factory covers the whole required interactor surface', () => {
   const interactor = createUnsupportedInteractor('Vega OS');
 
   assert.deepEqual(Object.keys(interactor).sort(), [...OPERATIONS].sort());
diff --git a/packages/platform-vega/src/unsupported-interactor.ts b/packages/platform-vega/src/unsupported-interactor.ts
index d96f3b7715..127ba1bf3e 100644
--- a/packages/platform-vega/src/unsupported-interactor.ts
+++ b/packages/platform-vega/src/unsupported-interactor.ts
@@ -30,9 +30,5 @@ export function createUnsupportedInteractor(platformLabel: string): Interactor {
     readClipboard: () => unsupported('readClipboard'),
     writeClipboard: () => unsupported('writeClipboard'),
     setSetting: () => unsupported('setSetting'),
-    readAlert: () => unsupported('readAlert'),
-    awaitAlert: () => unsupported('awaitAlert'),
-    acceptAlert: () => unsupported('acceptAlert'),
-    dismissAlert: () => unsupported('dismissAlert'),
   };
 }
diff --git a/packages/provider-limrun/src/ios.ts b/packages/provider-limrun/src/ios.ts
index ac0dd01719..4ad0c18331 100644
--- a/packages/provider-limrun/src/ios.ts
+++ b/packages/provider-limrun/src/ios.ts
@@ -351,22 +351,6 @@ class LimrunIosInteractor implements Interactor {
     throw unsupported('tv-remote', 'Limrun iOS direct sessions do not expose tv remote control.');
   }
 
-  async readAlert(): Promise<never> {
-    throw unsupported('alert', LIMRUN_IOS_ALERT_UNSUPPORTED);
-  }
-
-  async awaitAlert(): Promise<never> {
-    throw unsupported('alert', LIMRUN_IOS_ALERT_UNSUPPORTED);
-  }
-
-  async acceptAlert(): Promise<never> {
-    throw unsupported('alert', LIMRUN_IOS_ALERT_UNSUPPORTED);
-  }
-
-  async dismissAlert(): Promise<never> {
-    throw unsupported('alert', LIMRUN_IOS_ALERT_UNSUPPORTED);
-  }
-
   async readClipboard(): Promise<never> {
     throw unsupported('clipboard', 'Limrun iOS direct sessions do not expose clipboard read yet.');
   }
@@ -471,10 +455,6 @@ export function isUserInstalledIosApp(app: LimrunIosApp): boolean {
   );
 }
 
-/** One sentence for all four alert legs: this session has no XCUITest runner to read a sheet. */
-const LIMRUN_IOS_ALERT_UNSUPPORTED =
-  'Limrun iOS direct sessions do not expose alert inspection yet.';
-
 function unsupported(command: string, message: string): never {
   throw new AppError('UNSUPPORTED_OPERATION', message, { command });
 }
diff --git a/packages/provider-webdriver/src/platform-runtime.ts b/packages/provider-webdriver/src/platform-runtime.ts
index ede8da3fbe..5302e3d955 100644
--- a/packages/provider-webdriver/src/platform-runtime.ts
+++ b/packages/provider-webdriver/src/platform-runtime.ts
@@ -249,14 +249,10 @@ const foldUnavailable = Object.freeze({
 } as const);
 
 /**
- * The WebDriver interactor's own `setSetting` always throws unsupported (its capability map
- * declares `settings: unsupported`), so this cell is unavailable unconditionally rather than
- * gated by interactor reachability — the same shape `tvRemote` takes.
- */
-/**
- * Same shape as `settings`: the WebDriver interactor's own alert legs always throw unsupported
- * (its capability map declares `alert: unsupported`), so this cell is unavailable unconditionally
- * rather than gated by interactor reachability.
+ * The WebDriver interactor supplies no alert members at all: ADR 0019 keeps a stub that throws
+ * `unsupported` out of an interactor, and the provider's capability map declares
+ * `alert: unsupported`, so this cell is unavailable unconditionally rather than gated by
+ * interactor reachability.
  */
 const alertUnavailable = Object.freeze({
   available: false,
@@ -264,6 +260,11 @@ const alertUnavailable = Object.freeze({
   hint: 'WebDriver provider runtimes do not expose native alert handling.',
 } as const);
 
+/**
+ * The WebDriver interactor's own `setSetting` always throws unsupported (its capability map
+ * declares `settings: unsupported`), so this cell is unavailable unconditionally rather than
+ * gated by interactor reachability — the same shape `tvRemote` takes.
+ */
 const settingsUnavailable = Object.freeze({
   available: false,
   reason: 'unsupported-provider-mode',
diff --git a/packages/provider-webdriver/src/webdriver-interactor.ts b/packages/provider-webdriver/src/webdriver-interactor.ts
index 239839c3be..6b677904c9 100644
--- a/packages/provider-webdriver/src/webdriver-interactor.ts
+++ b/packages/provider-webdriver/src/webdriver-interactor.ts
@@ -381,24 +381,6 @@ class WebDriverInteractor implements Interactor {
     this.unsupported('settings');
   }
 
-  // The four alert legs share one declared capability: a driver that cannot read a native alert
-  // cannot press its buttons either, and no provider in this family declares either half.
-  async readAlert(): Promise<Record<string, unknown>> {
-    this.unsupported('alert');
-  }
-
-  async awaitAlert(): Promise<Record<string, unknown>> {
-    this.unsupported('alert');
-  }
-
-  async acceptAlert(): Promise<Record<string, unknown>> {
-    this.unsupported('alert');
-  }
-
-  async dismissAlert(): Promise<Record<string, unknown>> {
-    this.unsupported('alert');
-  }
-
   /**
    * The cloud twin of the local Apple runner's focus -> readiness -> type
    * pipeline (RunnerTests+TextEntry.swift). A WebView input does not take first
diff --git a/src/core/interactors/harmonyos.ts b/src/core/interactors/harmonyos.ts
index 2dc993086d..1c163ab313 100644
--- a/src/core/interactors/harmonyos.ts
+++ b/src/core/interactors/harmonyos.ts
@@ -65,11 +65,5 @@ export function createHarmonyInteractor(device: DeviceInfo, _runner?: RunnerCont
     readClipboard: unsupported('clipboard'),
     writeClipboard: unsupported('clipboard'),
     setSetting: (setting, state, appId) => setHarmonySetting(device, setting, state, appId),
-    // R59: the retired `alert` descriptor declared no HarmonyOS leaf, and hdc exposes no dialog
-    // surface to read one from.
-    readAlert: unsupported('alert'),
-    awaitAlert: unsupported('alert'),
-    acceptAlert: unsupported('alert'),
-    dismissAlert: unsupported('alert'),
   };
 }
diff --git a/src/core/interactors/linux.ts b/src/core/interactors/linux.ts
index 8ed8850286..e541ab9352 100644
--- a/src/core/interactors/linux.ts
+++ b/src/core/interactors/linux.ts
@@ -24,10 +24,6 @@ import {
 import { singlePointerPlanEndpoints } from '@agent-device/contracts/gesture-plan';
 import type { Interactor } from '@agent-device/contracts/interactor-types';
 
-function unsupportedLinuxAlert(): Promise<never> {
-  throw new AppError('UNSUPPORTED_OPERATION', 'alert not supported on Linux');
-}
-
 export function createLinuxInteractor(): Interactor {
   return {
     open: (app) => openLinuxApp(app),
@@ -83,10 +79,5 @@ export function createLinuxInteractor(): Interactor {
     setSetting: () => {
       throw new AppError('UNSUPPORTED_OPERATION', 'setSetting not supported on Linux');
     },
-    // R59: the retired `alert` descriptor declared `linux: {}`, so no Linux cell was admitted.
-    readAlert: unsupportedLinuxAlert,
-    awaitAlert: unsupportedLinuxAlert,
-    acceptAlert: unsupportedLinuxAlert,
-    dismissAlert: unsupportedLinuxAlert,
   };
 }
diff --git a/src/core/interactors/unsupported-interactor.ts b/src/core/interactors/unsupported-interactor.ts
index 70aae68a18..9c3d623eaa 100644
--- a/src/core/interactors/unsupported-interactor.ts
+++ b/src/core/interactors/unsupported-interactor.ts
@@ -29,9 +29,5 @@ export function createUnsupportedInteractor(platformLabel: string): Interactor {
     readClipboard: () => unsupported('readClipboard'),
     writeClipboard: () => unsupported('writeClipboard'),
     setSetting: () => unsupported('setSetting'),
-    readAlert: () => unsupported('readAlert'),
-    awaitAlert: () => unsupported('awaitAlert'),
-    acceptAlert: () => unsupported('acceptAlert'),
-    dismissAlert: () => unsupported('dismissAlert'),
   };
 }
diff --git a/src/daemon/__tests__/snapshot-runtime-fixture.ts b/src/daemon/__tests__/snapshot-runtime-fixture.ts
index 5ae600982e..71e633d61a 100644
--- a/src/daemon/__tests__/snapshot-runtime-fixture.ts
+++ b/src/daemon/__tests__/snapshot-runtime-fixture.ts
@@ -130,13 +130,13 @@ export function snapshotRuntimeFixture(requestId?: string): Readonly<{
           ...(appleInteractor
             ? {
                 readAlert: async (input: AlertRuntimeInput) =>
-                  await appleInteractor.readAlert(alertOptions(input)),
+                  await appleInteractor.readAlert!(alertOptions(input)),
                 awaitAlert: async (input: AlertRuntimeInput) =>
-                  await appleInteractor.awaitAlert(alertOptions(input)),
+                  await appleInteractor.awaitAlert!(alertOptions(input)),
                 acceptAlert: async (input: AlertRuntimeInput) =>
-                  await appleInteractor.acceptAlert(alertOptions(input)),
+                  await appleInteractor.acceptAlert!(alertOptions(input)),
                 dismissAlert: async (input: AlertRuntimeInput) =>
-                  await appleInteractor.dismissAlert(alertOptions(input)),
+                  await appleInteractor.dismissAlert!(alertOptions(input)),
               }
             : {}),
         },
diff --git a/src/daemon/handlers/__tests__/snapshot-alert-android-occlusion.test.ts b/src/daemon/handlers/__tests__/snapshot-alert-android-occlusion.test.ts
index 42775c2916..a9817fd3ce 100644
--- a/src/daemon/handlers/__tests__/snapshot-alert-android-occlusion.test.ts
+++ b/src/daemon/handlers/__tests__/snapshot-alert-android-occlusion.test.ts
@@ -30,7 +30,7 @@ afterEach(() => {
 test('Android alert get does not choose an exactly covered candidate', async () => {
   vi.mocked(snapshotAndroid).mockResolvedValue(coveredAlertCapture() as never);
 
-  const result = await alertLegs().readAlert();
+  const result = await alertLegs().readAlert!();
 
   expect(result).toMatchObject({ action: 'get', alert: null });
   expect(pressAndroid).not.toHaveBeenCalled();
@@ -40,12 +40,10 @@ test('Android alert accept does not tap an exactly covered candidate', async ()
   vi.useFakeTimers();
   vi.mocked(snapshotAndroid).mockResolvedValue(coveredAlertCapture() as never);
 
-  const outcome = alertLegs()
-    .acceptAlert()
-    .then(
-      () => undefined,
-      (error: unknown) => error,
-    );
+  const outcome = alertLegs().acceptAlert!().then(
+    () => undefined,
+    (error: unknown) => error,
+  );
   await vi.advanceTimersByTimeAsync(3_500);
   const error = await outcome;
   expect(error).toBeInstanceOf(Error);
diff --git a/test/integration/provider-scenarios/ios-alert-settings.test.ts b/test/integration/provider-scenarios/ios-alert-settings.test.ts
index 8ccf5e1fae..847635c179 100644
--- a/test/integration/provider-scenarios/ios-alert-settings.test.ts
+++ b/test/integration/provider-scenarios/ios-alert-settings.test.ts
@@ -284,10 +284,10 @@ function createRecordingPlatformRuntimeGateway(params: {
           // R59 does the same for `alert`: the scenario's gateway states and serves the four
           // legs, reusing the Apple family's own module so the runner transcript this scenario
           // scripts — including its retry and poll windows — is what actually runs.
-          readAlert: async (input) => await interactor.readAlert(alertOptions(input)),
-          awaitAlert: async (input) => await interactor.awaitAlert(alertOptions(input)),
-          acceptAlert: async (input) => await interactor.acceptAlert(alertOptions(input)),
-          dismissAlert: async (input) => await interactor.dismissAlert(alertOptions(input)),
+          readAlert: async (input) => await interactor.readAlert!(alertOptions(input)),
+          awaitAlert: async (input) => await interactor.awaitAlert!(alertOptions(input)),
+          acceptAlert: async (input) => await interactor.acceptAlert!(alertOptions(input)),
+          dismissAlert: async (input) => await interactor.dismissAlert!(alertOptions(input)),
           appLogReattach: async () => ({ status: 'missing' }),
           appLogCleanup: async () => ({ status: 'already-missing' }),
           resolveOpenTarget: async (input) => ({

From fa4109d7b9381eca07444248f8328a139d8575bd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Wed, 23 Sep 2026 16:10:17 +0200
Subject: [PATCH 043/132] refactor(contracts): drop the Limrun iOS denials its
 facts already make (#2815)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* refactor(contracts): make the springboard buttons optional members and drop the Limrun denials

ADR 0019 keeps a stub that throws `unsupported` out of an interactor: an owner with no
control says so with its facts, and the facts are what the binding consults. `home` and
`appSwitcher` reached the Limrun iOS direct session's interactor only through
`bindSystemButton`, which the catalog calls for exactly the buttons a binding's facts
admitted — and `limrunSystemButtonOperationFacts` refuses both cells on that leg
(`homeUnavailableIos`/`appSwitcherUnavailableIos`, or `liveSessionUnavailable` when no
session is live). The interactor denials were therefore unreachable code pretending to be
an implementation, and the fact hints already carried the identical wording.

Both members become optional, following #2715's `actionButton` shape: the system-button
binder already fails closed through `requireInteractorMethod`, so a fact that admits a
button its interactor cannot serve names the missing button instead of answering a silent
no-op. Apple, Android, HarmonyOS and the Vega TV leg keep their real mechanics.

* refactor(contracts): make the clipboard halves optional members and drop the Limrun denials

The Limrun iOS direct session's clipboard legs were unreachable code pretending to be an
implementation. `bindClipboardRead`/`bindClipboardWrite` are reached only through the
catalog, which binds a half exactly when the owner's fact admits it, and
`limrunClipboardOperationFacts` refuses both halves on that leg
(`clipboardUnavailableIos`, or `liveSessionUnavailable` with no live session). The
Android leg stays honest: it rides the same `createAndroidInteractor` the local family
binds, and its cells stay available.

Both members become optional and the binders now fail closed through
`requireInteractorMethod`, naming the half with the labels `CLIPBOARD_LEG_LABELS`
introduces and the catalog adopts — a fact that admits a half its interactor cannot
serve reports the missing method instead of resolving an absent member as a TypeError.
Apple, Android, Linux and the WebDriver clipboard extension keep their real mechanics.

* refactor(contracts): make the TV remote an optional member and drop the Limrun denial

The Limrun iOS direct session's remote leg was unreachable code pretending to be an
implementation. `bindTvRemote` is reached only through the catalog, which binds the press
exactly when the owner's fact admits it, and `limrunNavigationOperationFacts` refuses the
cell on that leg (`tvRemoteUnavailableIos`, or `liveSessionUnavailable` with no live
session) — a phone/tablet direct session has no remote receiver. The Android leg stays
honest: its cells gate on `device.target === 'tv'` and ride the real Android interactor.

The member becomes optional and the binder now fails closed through
`requireInteractorMethod`, naming the press with the label the catalog already used — a
fact that admits a press its interactor cannot serve reports the missing method instead
of resolving an absent member as a TypeError. Apple tvOS, the Android TV leaf, and Vega
keep their real mechanics.

* refactor(provider-limrun): drop the Limrun iOS gesture denial the facts already make

The iOS direct session refused every gesture tier through
`limrunGestureFacts` (`iosGestureUnavailable` on live sessions, the liveness cell
otherwise), and `bindGestureOperations` binds a tier only when its cell is available —
so the interactor's throwing `performGesture` could never run. The member is already
optional on `Interactor`, and the binder already escalates an advertised tier with no
executor to `invalidRuntimeContract` rather than a refusal (ADR 0019 §2), a path pinned
by `gesture-runtime.test.ts`. What remained was unreachable code pretending to be an
implementation; the fact cell is now the single source of the agent-facing wording.

* test(interactors): narrow the optional members at pinned implementation call sites

The Vega, Apple-runner-provider, and core interactor tests drive interactors that really
do carry home/appSwitcher/tvRemote/readClipboard/writeClipboard, but the factory hands
them an Interactor, and those members are optional now. Same `!` narrowing #2715 and
#2807 applied at their own pinned call sites: the assertion still runs the real method,
and an owner that ever stopped carrying it would fail in the factory's own test rather
than silently skipping the press.
---
 .../contracts/src/clipboard-runtime.test.ts   | 29 +++++++++++++++
 packages/contracts/src/clipboard-runtime.ts   | 25 ++++++++++++-
 .../src/interactor-operation-catalog.ts       | 22 ++++++++---
 packages/contracts/src/interactor-types.ts    | 37 ++++++++++++++++---
 .../contracts/src/tv-remote-runtime.test.ts   | 19 ++++++++++
 packages/contracts/src/tv-remote-runtime.ts   |  9 ++++-
 .../interactor-runner-provider.test.ts        | 10 ++---
 .../src/__tests__/interactor.test.ts          | 10 ++---
 .../src/interaction-operations.ts             | 14 +++----
 packages/provider-limrun/src/ios.ts           | 27 --------------
 src/core/__tests__/interactors.test.ts        |  2 +-
 11 files changed, 146 insertions(+), 58 deletions(-)

diff --git a/packages/contracts/src/clipboard-runtime.test.ts b/packages/contracts/src/clipboard-runtime.test.ts
index eee72ae1c9..d3829d169b 100644
--- a/packages/contracts/src/clipboard-runtime.test.ts
+++ b/packages/contracts/src/clipboard-runtime.test.ts
@@ -1,4 +1,5 @@
 import { expect, test, vi } from 'vitest';
+import { AppError } from '@agent-device/kernel/errors';
 import {
   bindClipboardRead,
   bindClipboardWrite,
@@ -96,3 +97,31 @@ test('a local write binding hands the interactor the already-joined text', async
 
   expect(writeClipboard).toHaveBeenCalledWith('hello world');
 });
+
+// Facts admitted the half, so an interactor without it is an ownership bug the caller must see
+// rather than a refusal to degrade around. The label is the one the command already used.
+test('a clipboard half whose fact admitted but whose interactor cannot serve it fails closed', async () => {
+  const served = { readClipboard: vi.fn(async () => 'copied text') } as unknown as Interactor;
+  const signal = new AbortController().signal;
+  const missingWrite = local(async () => ({ ...served, writeClipboard: undefined }));
+  const missingRead = local(
+    async () => ({ writeClipboard: vi.fn(async () => undefined) }) as unknown as Interactor,
+  );
+
+  await expect(
+    bindClipboardWrite(signal, missingWrite).writeClipboard({ text: 'hello' }),
+  ).rejects.toSatisfy(
+    (error: unknown) =>
+      error instanceof AppError &&
+      error.code === 'COMMAND_FAILED' &&
+      error.details?.['reason'] === 'interactor-method-missing' &&
+      error.message.includes('clipboard write'),
+  );
+  await expect(bindClipboardRead(signal, missingRead).readClipboard({})).rejects.toSatisfy(
+    (error: unknown) =>
+      error instanceof AppError &&
+      error.code === 'COMMAND_FAILED' &&
+      error.details?.['reason'] === 'interactor-method-missing' &&
+      error.message.includes('clipboard read'),
+  );
+});
diff --git a/packages/contracts/src/clipboard-runtime.ts b/packages/contracts/src/clipboard-runtime.ts
index bb60e8021e..2b73e37834 100644
--- a/packages/contracts/src/clipboard-runtime.ts
+++ b/packages/contracts/src/clipboard-runtime.ts
@@ -69,6 +69,12 @@ export function clipboardRuntimeOperationFacts(
   });
 }
 
+/** How a fail-closed refusal names each clipboard half to the caller. */
+export const CLIPBOARD_LEG_LABELS = {
+  readClipboard: 'clipboard read',
+  writeClipboard: 'clipboard write',
+} as const;
+
 /**
  * Captures one selected owner's interactor authority for the lifetime of a request binding. The
  * owner is already chosen by the time a binder is called, so each entry point supplies its own
@@ -87,6 +93,19 @@ async function resolveClipboardInteractor(
   });
 }
 
+/**
+ * Resolves one clipboard half's member through the shared optional-member guard. Loaded on the
+ * call rather than at module evaluation because this facade's eager closure is held at its
+ * merge-base size (`eager-closure-budgets`); a static edge would grow it.
+ */
+async function requireClipboardMethod<Leg extends keyof typeof CLIPBOARD_LEG_LABELS>(
+  interactor: Interactor,
+  leg: Leg,
+): Promise<NonNullable<Interactor[Leg]>> {
+  const { requireInteractorMethod } = await import('./interactor-operation-binding.ts');
+  return requireInteractorMethod(interactor[leg], CLIPBOARD_LEG_LABELS[leg]);
+}
+
 export function bindClipboardRead(
   signal: AbortSignal,
   resolveInteractor: (runner: RunnerContext) => Promise<Interactor>,
@@ -94,7 +113,8 @@ export function bindClipboardRead(
   return Object.freeze({
     readClipboard: async (input: ClipboardReadInput) => {
       const interactor = await resolveClipboardInteractor(signal, resolveInteractor, input);
-      return await interactor.readClipboard();
+      const readClipboard = await requireClipboardMethod(interactor, 'readClipboard');
+      return await readClipboard.call(interactor);
     },
   });
 }
@@ -106,7 +126,8 @@ export function bindClipboardWrite(
   return Object.freeze({
     writeClipboard: async (input: ClipboardWriteInput) => {
       const interactor = await resolveClipboardInteractor(signal, resolveInteractor, input);
-      await interactor.writeClipboard(input.text);
+      const writeClipboard = await requireClipboardMethod(interactor, 'writeClipboard');
+      await writeClipboard.call(interactor, input.text);
     },
   });
 }
diff --git a/packages/contracts/src/interactor-operation-catalog.ts b/packages/contracts/src/interactor-operation-catalog.ts
index 15c16494fe..80be944e06 100644
--- a/packages/contracts/src/interactor-operation-catalog.ts
+++ b/packages/contracts/src/interactor-operation-catalog.ts
@@ -2,11 +2,15 @@ import type { DeviceInfo } from '@agent-device/kernel/device';
 import { ALERT_LEG_LABELS, bindAlertLeg } from './alert-runtime.ts';
 import { bindAppEvent } from './app-event-runtime.ts';
 import { bindBack } from './back-runtime.ts';
-import { bindClipboardRead, bindClipboardWrite } from './clipboard-runtime.ts';
+import {
+  CLIPBOARD_LEG_LABELS,
+  bindClipboardRead,
+  bindClipboardWrite,
+} from './clipboard-runtime.ts';
 import { KEYBOARD_ACTION_LABELS, bindKeyboardAction } from './keyboard-runtime.ts';
 import { bindOrientation } from './orientation-runtime.ts';
 import { bindReadSetting, bindSetSetting } from './settings-runtime.ts';
-import { bindTvRemote } from './tv-remote-runtime.ts';
+import { TV_REMOTE_LABEL, bindTvRemote } from './tv-remote-runtime.ts';
 import {
   localInteractorSource,
   providerInteractorSource,
@@ -58,7 +62,7 @@ export const INTERACTOR_OPERATIONS = [
     bind: (signal, resolve) => bindSystemButton('home', signal, resolve),
   },
   { operation: 'setOrientation', label: 'orientation', bind: bindOrientation },
-  { operation: 'tvRemote', label: 'tv-remote', bind: bindTvRemote },
+  { operation: 'tvRemote', label: TV_REMOTE_LABEL, bind: bindTvRemote },
   {
     operation: 'keyboardStatus',
     label: KEYBOARD_ACTION_LABELS.keyboardStatus,
@@ -74,8 +78,16 @@ export const INTERACTOR_OPERATIONS = [
     label: KEYBOARD_ACTION_LABELS.keyboardEnter,
     bind: (signal, resolve) => bindKeyboardAction('keyboardEnter', signal, resolve),
   },
-  { operation: 'readClipboard', label: 'clipboard read', bind: bindClipboardRead },
-  { operation: 'writeClipboard', label: 'clipboard write', bind: bindClipboardWrite },
+  {
+    operation: 'readClipboard',
+    label: CLIPBOARD_LEG_LABELS.readClipboard,
+    bind: bindClipboardRead,
+  },
+  {
+    operation: 'writeClipboard',
+    label: CLIPBOARD_LEG_LABELS.writeClipboard,
+    bind: bindClipboardWrite,
+  },
   {
     operation: 'appSwitcher',
     label: SYSTEM_BUTTON_LABELS.appSwitcher,
diff --git a/packages/contracts/src/interactor-types.ts b/packages/contracts/src/interactor-types.ts
index fc178c4ad0..d6905eee8f 100644
--- a/packages/contracts/src/interactor-types.ts
+++ b/packages/contracts/src/interactor-types.ts
@@ -356,11 +356,29 @@ export type Interactor = {
   }>;
   gestureViewport?(): Promise<Rect>;
   back(mode?: BackMode): Promise<void>;
-  home(): Promise<void>;
+  /**
+   * Optional (parity with `actionButton`): opens the springboard, a control not every owner
+   * carries. An owner without it leaves it undefined; its fact refuses the press before binding,
+   * and the system-button binder fails closed rather than resolving an absent member as a
+   * successful no-op.
+   */
+  home?(): Promise<void>;
   setOrientation(orientation: DeviceRotation): Promise<{ orientation?: DeviceRotation } | void>;
   performGesture?(plan: GesturePlan): Promise<Record<string, unknown> | void>;
-  appSwitcher(): Promise<void>;
-  tvRemote(button: TvRemoteButton, durationMs?: number): Promise<void>;
+  /**
+   * Optional (parity with `home`): opens the recents surface, a control not every owner carries.
+   * An owner without it leaves it undefined; its fact refuses the press before binding, and the
+   * system-button binder fails closed rather than resolving an absent member as a successful
+   * no-op.
+   */
+  appSwitcher?(): Promise<void>;
+  /**
+   * Optional (parity with `home`): presses one TV remote key, a control only TV-capable owners
+   * carry. An owner without it leaves it undefined; its fact refuses the press before binding,
+   * and the TV remote binder fails closed rather than resolving an absent member as a silent
+   * no-op.
+   */
+  tvRemote?(button: TvRemoteButton, durationMs?: number): Promise<void>;
   /**
    * Optional (parity with `keyboardDismiss`): presses the iPhone/iPad Action Button, hardware only
    * the Apple owner carries. An owner without the button leaves it undefined; its fact refuses the
@@ -374,8 +392,17 @@ export type Interactor = {
   keyboardDismiss?(): Promise<KeyboardDismissResult>;
   /** Optional: platforms with no keyboard-return concept leave it undefined. */
   keyboardEnter?(): Promise<KeyboardEnterResult>;
-  readClipboard(): Promise<string>;
-  writeClipboard(text: string): Promise<void>;
+  /**
+   * Optional (parity with `readSetting`): the owner's pasteboard read. An owner with no clipboard
+   * surface leaves both halves undefined; its fact refuses the half before binding, and the
+   * clipboard binder fails closed rather than resolving an absent member as an empty answer.
+   */
+  readClipboard?(): Promise<string>;
+  /**
+   * Optional (parity with `readClipboard`): the owner's pasteboard write, with the same
+   * fact-then-guard contract as the read.
+   */
+  writeClipboard?(text: string): Promise<void>;
   setSetting(
     setting: string,
     state: string,
diff --git a/packages/contracts/src/tv-remote-runtime.test.ts b/packages/contracts/src/tv-remote-runtime.test.ts
index a29dd1e7bb..3ba0d3f342 100644
--- a/packages/contracts/src/tv-remote-runtime.test.ts
+++ b/packages/contracts/src/tv-remote-runtime.test.ts
@@ -1,4 +1,5 @@
 import { expect, test, vi } from 'vitest';
+import { AppError } from '@agent-device/kernel/errors';
 import { bindTvRemote, tvRemoteRuntimeOperationFacts } from './tv-remote-runtime.ts';
 import type { Interactor } from './interactor-types.ts';
 import { localInteractorSource } from './interactor-operation-binding.ts';
@@ -39,3 +40,21 @@ test('a local binding drives the interactor with the button and duration', async
   // durationMs is the one transposition a point-shaped assertion would not catch.
   expect(tvRemote).toHaveBeenCalledWith('down', 250);
 });
+
+// Facts admitted the press, so an interactor without the member is an ownership bug the caller
+// must see rather than a refusal to degrade around. The label is the one the command used.
+test('a press whose fact admitted but whose interactor cannot serve it fails closed', async () => {
+  const resolveInteractor = vi.fn(async () => ({}) as unknown as Interactor);
+
+  const operations = bindTvRemote(
+    new AbortController().signal,
+    localInteractorSource({ device, resolveInteractor }),
+  );
+  await expect(operations.tvRemote({ button: 'up' })).rejects.toSatisfy(
+    (error: unknown) =>
+      error instanceof AppError &&
+      error.code === 'COMMAND_FAILED' &&
+      error.details?.['reason'] === 'interactor-method-missing' &&
+      error.message.includes('tv-remote'),
+  );
+});
diff --git a/packages/contracts/src/tv-remote-runtime.ts b/packages/contracts/src/tv-remote-runtime.ts
index b5801525e7..88922013bf 100644
--- a/packages/contracts/src/tv-remote-runtime.ts
+++ b/packages/contracts/src/tv-remote-runtime.ts
@@ -35,6 +35,9 @@ export function tvRemoteRuntimeOperationFacts(
   return Object.freeze({ tvRemote: input.tvRemote });
 }
 
+/** How a fail-closed refusal names the TV remote to the caller, matching the command. */
+export const TV_REMOTE_LABEL = 'tv-remote';
+
 /**
  * Captures one selected owner's interactor authority for the lifetime of a request binding. The
  * owner is already chosen by the time a binder is called, so each entry point supplies its own
@@ -52,7 +55,11 @@ export function bindTvRemote(
         appBundleId: input.options?.appBundleId,
         signal,
       });
-      await interactor.tvRemote(input.button, input.durationMs);
+      // Loaded on the call rather than at module evaluation because this facade's eager closure
+      // is held at its merge-base size (`eager-closure-budgets`); a static edge would grow it.
+      const { requireInteractorMethod } = await import('./interactor-operation-binding.ts');
+      const tvRemote = requireInteractorMethod(interactor.tvRemote, TV_REMOTE_LABEL);
+      await tvRemote.call(interactor, input.button, input.durationMs);
     },
   });
 }
diff --git a/packages/platform-apple/src/__tests__/interactor-runner-provider.test.ts b/packages/platform-apple/src/__tests__/interactor-runner-provider.test.ts
index eeea455a2c..d55f0a4c0a 100644
--- a/packages/platform-apple/src/__tests__/interactor-runner-provider.test.ts
+++ b/packages/platform-apple/src/__tests__/interactor-runner-provider.test.ts
@@ -71,11 +71,11 @@ const RUNNER_TRANSPORT_METHODS: Record<
   },
   findText: { invoke: (i) => i.findText!('Ready'), runnerCommand: 'findText' },
   back: { invoke: (i) => i.back(), runnerCommand: 'backInApp' },
-  home: { invoke: (i) => i.home(), runnerCommand: 'home' },
+  home: { invoke: (i) => i.home!(), runnerCommand: 'home' },
   setOrientation: { invoke: (i) => i.setOrientation('portrait'), runnerCommand: 'rotate' },
-  appSwitcher: { invoke: (i) => i.appSwitcher(), runnerCommand: 'appSwitcher' },
+  appSwitcher: { invoke: (i) => i.appSwitcher!(), runnerCommand: 'appSwitcher' },
   actionButton: { invoke: (i) => i.actionButton!(), runnerCommand: 'actionButton' },
-  tvRemote: { invoke: (i) => i.tvRemote('select'), runnerCommand: 'remotePress' },
+  tvRemote: { invoke: (i) => i.tvRemote!('select'), runnerCommand: 'remotePress' },
   keyboardDismiss: { invoke: (i) => i.keyboardDismiss!(), runnerCommand: 'keyboardDismiss' },
   keyboardEnter: { invoke: (i) => i.keyboardEnter!(), runnerCommand: 'keyboardReturn' },
   // R59: same reading as `readTextAtPoint` — the macOS-helper branch is reachable only for a
@@ -92,8 +92,8 @@ const LOCAL_TOOL_METHODS: Record<string, (interactor: Interactor) => Promise<unk
   openDevice: (i) => i.openDevice(),
   close: (i) => i.close('com.example.app'),
   screenshot: (i) => i.screenshot('/dev/null'),
-  readClipboard: (i) => i.readClipboard(),
-  writeClipboard: (i) => i.writeClipboard('hi'),
+  readClipboard: (i) => i.readClipboard!(),
+  writeClipboard: (i) => i.writeClipboard!('hi'),
   setSetting: (i) => i.setSetting('wifi', 'on'),
   // `simctl ui ... content_size` is local Apple tooling like the write leg beside it, so a provider-owned
   // device has no way to answer a text-size read.
diff --git a/packages/platform-vega/src/__tests__/interactor.test.ts b/packages/platform-vega/src/__tests__/interactor.test.ts
index 38a7766033..4ea99f9745 100644
--- a/packages/platform-vega/src/__tests__/interactor.test.ts
+++ b/packages/platform-vega/src/__tests__/interactor.test.ts
@@ -42,9 +42,9 @@ beforeEach(() => {
 test('tvRemote, back, and home share the Vega remote primitive', async () => {
   const interactor = createVegaInteractor(VEGA_VVD, {});
 
-  await interactor.tvRemote('left', 250);
+  await interactor.tvRemote!('left', 250);
   await interactor.back('system');
-  await interactor.home();
+  await interactor.home!();
 
   assert.deepEqual(mockPressVegaTvRemote.mock.calls, [
     [VEGA_VVD, 'left', 250],
@@ -129,9 +129,9 @@ test('required unproven Vega operations share typed unsupported behavior', async
     ['screenshot', () => interactor.screenshot('/tmp/vega.png')],
     ['snapshot', () => interactor.snapshot()],
     ['setOrientation', () => interactor.setOrientation('portrait')],
-    ['appSwitcher', () => interactor.appSwitcher()],
-    ['readClipboard', () => interactor.readClipboard()],
-    ['writeClipboard', () => interactor.writeClipboard('text')],
+    ['appSwitcher', () => interactor.appSwitcher!()],
+    ['readClipboard', () => interactor.readClipboard!()],
+    ['writeClipboard', () => interactor.writeClipboard!('text')],
     ['setSetting', () => interactor.setSetting('wifi', 'on')],
   ];
 
diff --git a/packages/provider-limrun/src/interaction-operations.ts b/packages/provider-limrun/src/interaction-operations.ts
index 1337d452a4..1c5796bc30 100644
--- a/packages/provider-limrun/src/interaction-operations.ts
+++ b/packages/provider-limrun/src/interaction-operations.ts
@@ -44,9 +44,9 @@ import { setTimeout as sleep } from 'node:timers/promises';
 
 const available = Object.freeze({ available: true } as const);
 /**
- * Limrun's iOS direct session drives text and touch but exposes no portable gesture execution —
- * its interactor's own `performGesture` refuses with this wording. Stating it as a fact refuses at
- * admission instead of mid-execution (ADR 0019 §6), keeping the agent-facing hint identical.
+ * Limrun's iOS direct session drives text and touch but exposes no portable gesture execution.
+ * Stating it as a fact refuses at admission instead of mid-execution (ADR 0019 §6), and it is
+ * the only refusal the caller sees: the leg's interactor carries no gesture member at all.
  */
 const iosGestureUnavailable = Object.freeze({
   available: false,
@@ -228,8 +228,9 @@ export function bindLimrunInteractionOperations(
  * `back`/`orientation`/`tvRemote` differ by direct-session platform, unlike focus/type:
  * the Android leg rides `session.dependencies.android.createInteractor` (`android.ts`) — the
  * SAME factory the local Android family binds, so it carries the identical cell table (parity
- * with the local owner, including the `device.target === 'tv'` gate for `tvRemote`). The iOS leg
- * (`ios.ts`) implements `back`/`setOrientation` but explicitly refuses `tvRemote`.
+ * with the local owner, including the `device.target === 'tv'` gate for `tvRemote`). The iOS
+ * direct session is a phone/tablet surface with no remote receiver, so its fact refuses
+ * `tvRemote` and its interactor carries no such member.
  */
 export function limrunNavigationOperationFacts(
   device: DeviceInfo,
@@ -267,8 +268,7 @@ export function limrunNavigationOperationFacts(
  * `clipboard` shares the split its siblings have: the Android leg rides
  * `session.dependencies.android.createInteractor` — the SAME factory the local Android family
  * binds, so `cmd clipboard get/set text` reaches the device exactly as it does locally — while
- * the iOS leg's own `readClipboard`/`writeClipboard` throw, so both cells stay unavailable there
- * and carry the interactor's wording.
+ * the iOS direct session has no pasteboard transport, so both cells stay unavailable there.
  */
 export function limrunClipboardOperationFacts(
   device: DeviceInfo,
diff --git a/packages/provider-limrun/src/ios.ts b/packages/provider-limrun/src/ios.ts
index 4ad0c18331..6a76aa9d20 100644
--- a/packages/provider-limrun/src/ios.ts
+++ b/packages/provider-limrun/src/ios.ts
@@ -322,10 +322,6 @@ class LimrunIosInteractor implements Interactor {
     await this.session.client.pressKey('escape');
   }
 
-  async home(): Promise<never> {
-    throw unsupported('home', 'Limrun iOS direct sessions do not expose home yet.');
-  }
-
   async setOrientation(orientation: DeviceRotation): Promise<void> {
     if (orientation === 'portrait-upside-down') {
       throw unsupported(
@@ -336,29 +332,6 @@ class LimrunIosInteractor implements Interactor {
     await this.session.client.setOrientation(orientation === 'portrait' ? 'Portrait' : 'Landscape');
   }
 
-  async performGesture(): Promise<never> {
-    throw unsupported(
-      'gesture',
-      'Limrun iOS direct sessions do not expose portable gesture execution yet.',
-    );
-  }
-
-  async appSwitcher(): Promise<never> {
-    throw unsupported('app-switcher', 'Limrun iOS direct sessions do not expose app switcher yet.');
-  }
-
-  async tvRemote(): Promise<never> {
-    throw unsupported('tv-remote', 'Limrun iOS direct sessions do not expose tv remote control.');
-  }
-
-  async readClipboard(): Promise<never> {
-    throw unsupported('clipboard', 'Limrun iOS direct sessions do not expose clipboard read yet.');
-  }
-
-  async writeClipboard(): Promise<never> {
-    throw unsupported('clipboard', 'Limrun iOS direct sessions do not expose clipboard write yet.');
-  }
-
   async setSetting(): Promise<never> {
     throw unsupported('settings', 'Limrun iOS direct sessions do not expose settings changes yet.');
   }
diff --git a/src/core/__tests__/interactors.test.ts b/src/core/__tests__/interactors.test.ts
index 895b13a294..e259dcf246 100644
--- a/src/core/__tests__/interactors.test.ts
+++ b/src/core/__tests__/interactors.test.ts
@@ -217,7 +217,7 @@ test('tvOS home navigates focus via the remote Home button', async () => {
   });
   const interactor = await getInteractor(tvOsSimulator, { appBundleId: 'com.example.app' });
 
-  await withRunner(() => interactor.home(), tvOsSimulator);
+  await withRunner(() => interactor.home!(), tvOsSimulator);
 
   assert.deepEqual(commands, [
     { command: 'remotePress', remoteButton: 'home', appBundleId: 'com.example.app' },

From 661229d5c2740ea8a8857b957cfc53fecd2ab017 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Wed, 23 Sep 2026 16:10:18 +0200
Subject: [PATCH 044/132] refactor(interactors): stop handing web and Vega a
 full wall of refusals (#2816)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* refactor(interactors): drop the inherited home and app-switcher denials

ADR 0019 says an owner with no control states that with its facts, and waves #2715/#2807/
#2815 gave the two base interactors the optional members and the fail-closed
requireInteractorMethod guards this needs. The inherited home/appSwitcher throws were
unreachable on both platforms: web runtime facts refuse every system button
(navigationUnavailable — runtime.test.ts pins fact unavailable AND no bound operation),
Vega refuses the app switcher ("System buttons other than home are not supported on Vega
OS.") and its VVD-accepted home press binds through the interactor override to
pressVegaTvRemote, never the base leg. If a fact ever admits a button its interactor
lacks, the system-button binder names it with the SYSTEM_BUTTON_LABELS label instead of
resolving an absent member.

Both factories lose both legs; the factory tests shrink with them, the per-instance label
assertion re-anchors to a required member, and the moved coverage lands where the refusal
now lives: the absence assertions in the factory/interactor tests, the fact-cell pins in
the platform runtime tests, the binder guard in contracts. User-visible refusals are
unchanged: same admission-time UNSUPPORTED_OPERATION with the platforms fact hint.

* refactor(interactors): drop the inherited clipboard denials

Both clipboard halves are optional members with a fail-closed binder (Wave A gave
bindClipboardRead/bindClipboardWrite the CLIPBOARD_LEG_LABELS guard), and neither base
platform can reach its inherited throw: the web runtime carries no clipboard bucket at
all ("clipboard, the app switcher, app events, settings and alerts carry no web bucket"
pins fact unavailable AND no bound operation), and the Vega facts refuse both halves with
"clipboard is not supported on Vega OS." before binding. The factories keep only the
members the interface still requires; the moved coverage is the absence assertions in
the factory and Vega interactor tests beside the unchanged fact-cell pins in the runtime
tests. User-visible refusals unchanged: admission already answered with the platforms
fact wording, never the leg text.

* refactor(interactors): drop the inherited TV remote denial

Web never carried a tv-remote bucket — runtime.test.ts pins the fact unavailable and the
operation unbound — and the only platform whose facts admit a remote press is Vega on a
VVD, where the press is the interactor override riding pressVegaTvRemote (pinned by
"tvRemote, back, and home share the Vega remote primitive"), never this leg. The member
is optional and bindTvRemote fails closed through the TV_REMOTE_LABEL guard Wave A added,
so a fact that admits a remote its interactor lacks names it instead of answering a
TypeError. The base factories now carry only required members plus setOrientation (a
required member with a per-platform refusal), and the absence assertions in both factory
tests pin the shape. No user-facing refusal changed on either platform.
---
 .../src/__tests__/interactor.test.ts          |  8 +++---
 .../__tests__/unsupported-interactor.test.ts  | 27 ++++++++++++-------
 .../src/unsupported-interactor.ts             |  5 ----
 .../__tests__/unsupported-interactor.test.ts  | 10 ++++++-
 .../interactors/unsupported-interactor.ts     |  5 ----
 5 files changed, 32 insertions(+), 23 deletions(-)

diff --git a/packages/platform-vega/src/__tests__/interactor.test.ts b/packages/platform-vega/src/__tests__/interactor.test.ts
index 4ea99f9745..185acf471a 100644
--- a/packages/platform-vega/src/__tests__/interactor.test.ts
+++ b/packages/platform-vega/src/__tests__/interactor.test.ts
@@ -129,9 +129,6 @@ test('required unproven Vega operations share typed unsupported behavior', async
     ['screenshot', () => interactor.screenshot('/tmp/vega.png')],
     ['snapshot', () => interactor.snapshot()],
     ['setOrientation', () => interactor.setOrientation('portrait')],
-    ['appSwitcher', () => interactor.appSwitcher!()],
-    ['readClipboard', () => interactor.readClipboard!()],
-    ['writeClipboard', () => interactor.writeClipboard!('text')],
     ['setSetting', () => interactor.setSetting('wifi', 'on')],
   ];
 
@@ -155,6 +152,11 @@ test('optional Vega operations stay absent so shared dispatch keeps its fallback
     'setViewport',
     'gestureViewport',
     'performGesture',
+    // The factory no longer fakes a recents button or a pasteboard Vega OS never carried;
+    // the runtime facts refuse those operations before an absent member could be resolved.
+    'appSwitcher',
+    'readClipboard',
+    'writeClipboard',
   ];
 
   for (const operation of optionalOperations) {
diff --git a/packages/platform-vega/src/__tests__/unsupported-interactor.test.ts b/packages/platform-vega/src/__tests__/unsupported-interactor.test.ts
index ddfdc2410a..736555e711 100644
--- a/packages/platform-vega/src/__tests__/unsupported-interactor.test.ts
+++ b/packages/platform-vega/src/__tests__/unsupported-interactor.test.ts
@@ -16,12 +16,7 @@ const OPERATIONS = [
   'screenshot',
   'snapshot',
   'back',
-  'home',
   'setOrientation',
-  'appSwitcher',
-  'tvRemote',
-  'readClipboard',
-  'writeClipboard',
   'setSetting',
 ] as const;
 
@@ -35,11 +30,25 @@ test('every operation rejects as unsupported and names the platform', async () =
 });
 
 test('the label is per-instance, so two platforms reject with their own wording', async () => {
-  const web = createUnsupportedInteractor('web').home as () => Promise<unknown>;
-  const vega = createUnsupportedInteractor('Vega OS').home as () => Promise<unknown>;
+  const web = createUnsupportedInteractor('web').setSetting as () => Promise<unknown>;
+  const vega = createUnsupportedInteractor('Vega OS').setSetting as () => Promise<unknown>;
 
-  await expectUnsupported(web, 'home', 'web');
-  await expectUnsupported(vega, 'home', 'Vega OS');
+  await expectUnsupported(web, 'setSetting', 'web');
+  await expectUnsupported(vega, 'setSetting', 'Vega OS');
+});
+
+// The system buttons, the clipboard, and the TV remote ride fact-gated binders: web's cell
+// refuses all five, Vega's refuses the app switcher and both clipboard halves (its real
+// remote mechanics arrive through the Vega interactor override, not this factory), and each
+// binder fails closed if a fact ever admits an operation its interactor lacks.
+test('operations with no shared fallback are left undefined, not denied', () => {
+  const interactor = createUnsupportedInteractor('Vega OS');
+
+  assert.equal(interactor.home, undefined);
+  assert.equal(interactor.appSwitcher, undefined);
+  assert.equal(interactor.readClipboard, undefined);
+  assert.equal(interactor.writeClipboard, undefined);
+  assert.equal(interactor.tvRemote, undefined);
 });
 
 test('the factory covers the whole required interactor surface', () => {
diff --git a/packages/platform-vega/src/unsupported-interactor.ts b/packages/platform-vega/src/unsupported-interactor.ts
index 127ba1bf3e..73487a6fd6 100644
--- a/packages/platform-vega/src/unsupported-interactor.ts
+++ b/packages/platform-vega/src/unsupported-interactor.ts
@@ -23,12 +23,7 @@ export function createUnsupportedInteractor(platformLabel: string): Interactor {
     screenshot: () => unsupported('screenshot'),
     snapshot: () => unsupported('snapshot'),
     back: () => unsupported('back'),
-    home: () => unsupported('home'),
     setOrientation: () => unsupported('setOrientation'),
-    appSwitcher: () => unsupported('appSwitcher'),
-    tvRemote: () => unsupported('tvRemote'),
-    readClipboard: () => unsupported('readClipboard'),
-    writeClipboard: () => unsupported('writeClipboard'),
     setSetting: () => unsupported('setSetting'),
   };
 }
diff --git a/src/core/interactors/__tests__/unsupported-interactor.test.ts b/src/core/interactors/__tests__/unsupported-interactor.test.ts
index 9f8e001058..5430ad0d8b 100644
--- a/src/core/interactors/__tests__/unsupported-interactor.test.ts
+++ b/src/core/interactors/__tests__/unsupported-interactor.test.ts
@@ -28,10 +28,18 @@ test('every operation on the factory rejects, naming itself and the platform', a
   assert.deepEqual(failures.filter(Boolean), []);
 });
 
-test('a fused double-click is left undefined, not denied, so a shared series reports the gap', () => {
+test('optional operations are left undefined, not denied, so shared dispatch keeps its fallback semantics', () => {
   const interactor = createUnsupportedInteractor('web');
 
+  // A fused double-click has no shared-series stand-in, the system buttons ride fact-gated
+  // binders, and neither the clipboard nor a TV remote has a shared fallback either: an absent
+  // member is the owner's absence, a throw would fake one.
   assert.equal(interactor.doubleTap, undefined);
+  assert.equal(interactor.home, undefined);
+  assert.equal(interactor.appSwitcher, undefined);
+  assert.equal(interactor.readClipboard, undefined);
+  assert.equal(interactor.writeClipboard, undefined);
+  assert.equal(interactor.tvRemote, undefined);
 });
 
 test('a rejection carries no partial result the caller could mistake for success', async () => {
diff --git a/src/core/interactors/unsupported-interactor.ts b/src/core/interactors/unsupported-interactor.ts
index 9c3d623eaa..27a36c12d3 100644
--- a/src/core/interactors/unsupported-interactor.ts
+++ b/src/core/interactors/unsupported-interactor.ts
@@ -22,12 +22,7 @@ export function createUnsupportedInteractor(platformLabel: string): Interactor {
     screenshot: () => unsupported('screenshot'),
     snapshot: () => unsupported('snapshot'),
     back: () => unsupported('back'),
-    home: () => unsupported('home'),
     setOrientation: () => unsupported('setOrientation'),
-    appSwitcher: () => unsupported('appSwitcher'),
-    tvRemote: () => unsupported('tvRemote'),
-    readClipboard: () => unsupported('readClipboard'),
-    writeClipboard: () => unsupported('writeClipboard'),
     setSetting: () => unsupported('setSetting'),
   };
 }

From dd59b437c234c2971a11a82f22c06eaa20af7575 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Wed, 23 Sep 2026 16:19:13 +0200
Subject: [PATCH 045/132] fix(scroll): name what a scroll observed and read an
 edge off one tree (#2770)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two pieces the directional-scroll answer needs, with no behavior change on its own.

`movement` is the vocabulary a scroll uses to say what happened to the surface: `moved`,
`at-edge`, `unchanged` when the visible content did not change, and `unobserved` when the
command could not compare anything. It is absent when the runtime cannot read a screen at
all, so a caller never has to guess whether a missing claim means "did not move".

`readScrollEdgeState` is the one pure door into the edge analyzer — the question
`canScrollFurtherAtEdge` and `scrollSurfaceFingerprint` already ask, exposed with the frame
of the container that answer was taken on. Without `containerRect`, `canScroll: false`
cannot distinguish content that ends here from a tree that named no container, and a caller
checking whether its gesture landed inside the list has nothing to check against.
---
 ...roll-edge-state-pass-orchestration.test.ts | 57 +++++++++++++
 .../__tests__/scroll-edge-state-read.test.ts  | 79 +++++++++++++++++
 .../src/snapshot/scroll-edge-state.ts         | 85 +++++++++++++++++--
 .../snapshot/scroll-edge-state/selection.ts   |  3 +
 packages/contracts/src/scroll-command.test.ts | 20 ++++-
 packages/contracts/src/scroll-command.ts      | 49 +++++++++++
 src/daemon/scroll-until.ts                    | 16 +---
 7 files changed, 288 insertions(+), 21 deletions(-)
 create mode 100644 packages/capture-kit/src/snapshot/__tests__/scroll-edge-state-read.test.ts

diff --git a/packages/capture-kit/src/snapshot/__tests__/scroll-edge-state-pass-orchestration.test.ts b/packages/capture-kit/src/snapshot/__tests__/scroll-edge-state-pass-orchestration.test.ts
index 112da4a2a4..712c3dac8d 100644
--- a/packages/capture-kit/src/snapshot/__tests__/scroll-edge-state-pass-orchestration.test.ts
+++ b/packages/capture-kit/src/snapshot/__tests__/scroll-edge-state-pass-orchestration.test.ts
@@ -77,6 +77,63 @@ test('an amount-based message names the honored travel when the planner reports
   );
 });
 
+/**
+ * #2714. A travel figure describes the swipe that was dispatched, not content that moved, so an
+ * observation of no change outranks it. `unobserved` is the pair to these: the disclosure travels in
+ * the `movement` field, and the prose keeps the number the caller asked for.
+ */
+test('formatScrollEdgeMessage: an observed edge answers without a distance', () => {
+  assert.equal(
+    formatScrollEdgeMessage({ direction: 'down', passes: 1, amount: 0.75, movement: 'at-edge' }),
+    'Scrolled down and no hidden content below was detected',
+  );
+  assert.equal(
+    formatScrollEdgeMessage({ direction: 'up', passes: 1, amount: 0.75, movement: 'at-edge' }),
+    'Scrolled up and no hidden content above was detected',
+  );
+});
+
+test('formatScrollEdgeMessage: a horizontal scroll never claims a vertical edge', () => {
+  assert.equal(
+    formatScrollEdgeMessage({ direction: 'left', passes: 1, amount: 0.75, movement: 'at-edge' }),
+    'Scrolled left by 0.75',
+  );
+});
+
+test('formatScrollEdgeMessage: an unchanged surface reports the measurement, not the request', () => {
+  assert.equal(
+    formatScrollEdgeMessage({ direction: 'left', passes: 1, pixels: 500, movement: 'unchanged' }),
+    'Scrolled left and the visible content did not change',
+  );
+});
+
+test('formatScrollEdgeMessage: an observation outranks the distance it disagrees with', () => {
+  assert.equal(
+    formatScrollEdgeMessage({
+      direction: 'down',
+      passes: 1,
+      amount: 3,
+      pixels: 5000,
+      honoredPixels: 640,
+      movement: 'at-edge',
+    }),
+    'Scrolled down and no hidden content below was detected',
+  );
+});
+
+test('formatScrollEdgeMessage: an unobserved movement keeps the distance the caller asked for', () => {
+  assert.equal(
+    formatScrollEdgeMessage({
+      direction: 'down',
+      passes: 1,
+      amount: 0.75,
+      honoredPixels: 656,
+      movement: 'unobserved',
+    }),
+    'Scrolled down by 0.75 of the viewport (656px)',
+  );
+});
+
 // ---------------------------------------------------------------------------
 // captureScrollEdgeState: retry-without-scope on an empty scoped capture
 // ---------------------------------------------------------------------------
diff --git a/packages/capture-kit/src/snapshot/__tests__/scroll-edge-state-read.test.ts b/packages/capture-kit/src/snapshot/__tests__/scroll-edge-state-read.test.ts
new file mode 100644
index 0000000000..e51a39a01d
--- /dev/null
+++ b/packages/capture-kit/src/snapshot/__tests__/scroll-edge-state-read.test.ts
@@ -0,0 +1,79 @@
+import { test } from 'vitest';
+import assert from 'node:assert/strict';
+import { captureScrollEdgeState, readScrollEdgeState } from '../scroll-edge-state.ts';
+import { scrollNode, windowRoot } from './scroll-edge-state-fixtures.ts';
+
+/**
+ * The pure door into the edge analyzer. `scroll <dir>` reads an edge decision off a tree it already
+ * holds to say what its gesture did (#2714), which makes `containerRect` part of the answer: the
+ * caller has to be able to tell "this content ends here" from "the tree named no container", and
+ * `canScroll: false` alone cannot tell them apart.
+ */
+
+const CONTAINER = { x: 18, y: 178, width: 366, height: 662 };
+
+test('readScrollEdgeState: a resolved container reports the frame the decision was taken on', async () => {
+  const nodes = [
+    windowRoot(),
+    scrollNode(1, { hiddenContentBelow: true, rect: CONTAINER }),
+    {
+      ref: 'e3',
+      index: 2,
+      parentIndex: 1,
+      type: 'StaticText',
+      label: 'Row',
+      rect: { x: 24, y: 700, width: 300, height: 40 },
+    },
+  ];
+
+  const state = await readScrollEdgeState(nodes, 'bottom');
+
+  assert.equal(state.canScroll, true);
+  assert.deepEqual(state.containerRect, CONTAINER);
+});
+
+test('readScrollEdgeState: a tree with no scroll container reports no frame to check a gesture against', async () => {
+  const nodes = [
+    windowRoot(),
+    {
+      ref: 'e2',
+      index: 1,
+      parentIndex: 0,
+      type: 'Button',
+      label: 'Tap me',
+      rect: { x: 20, y: 40, width: 100, height: 40 },
+    },
+  ];
+
+  const state = await readScrollEdgeState(nodes, 'bottom');
+
+  assert.equal(state.canScroll, false);
+  assert.equal(state.containerRect, undefined);
+});
+
+test('readScrollEdgeState: a zero-area scrollable resolves to no container and therefore no frame', async () => {
+  const state = await readScrollEdgeState(
+    [windowRoot(), scrollNode(1, { hiddenContentBelow: true, rect: { ...CONTAINER, height: 0 } })],
+    'bottom',
+  );
+
+  assert.equal(state.containerRect, undefined);
+});
+
+/**
+ * The reader must not become a second source of truth: the captured and pure doors disagreeing about
+ * one tree would mean an edge loop and a movement claim reading different rules.
+ */
+test('readScrollEdgeState answers what captureScrollEdgeState answers for the same tree', async () => {
+  const nodes = [windowRoot(), scrollNode(1, { hiddenContentBelow: true, rect: CONTAINER })];
+
+  const captured = await captureScrollEdgeState({
+    edge: 'bottom',
+    captureNodes: async () => nodes,
+  });
+  const read = await readScrollEdgeState(nodes, 'bottom');
+
+  assert.equal(read.canScroll, captured.canScroll);
+  assert.deepEqual(read.containerRect, captured.containerRect);
+  assert.equal(read.fingerprint, captured.fingerprint);
+});
diff --git a/packages/capture-kit/src/snapshot/scroll-edge-state.ts b/packages/capture-kit/src/snapshot/scroll-edge-state.ts
index d9690ad011..7359b2348d 100644
--- a/packages/capture-kit/src/snapshot/scroll-edge-state.ts
+++ b/packages/capture-kit/src/snapshot/scroll-edge-state.ts
@@ -1,13 +1,31 @@
 import { AppError } from '@agent-device/kernel/errors';
+import type { ScrollMovementObservation } from '@agent-device/contracts/scroll-command';
 import type { ScrollDirection } from '@agent-device/contracts/scroll-gesture';
-import type { Point, RawSnapshotNode, SnapshotNode } from '@agent-device/kernel/snapshot';
+import type { Point, RawSnapshotNode, Rect, SnapshotNode } from '@agent-device/kernel/snapshot';
 
 export type ScrollEdge = 'top' | 'bottom';
 
+/**
+ * The end-of-content analyzer reads vertical edges only, so a horizontal scroll has no end signal
+ * and is bounded by whatever pass or observation budget its caller owns.
+ */
+export function verticalEdgeFor(direction: ScrollDirection): ScrollEdge | undefined {
+  if (direction === 'down') return 'bottom';
+  if (direction === 'up') return 'top';
+  return undefined;
+}
+
 export type ScrollEdgeState = {
   canScroll: boolean;
   emptySnapshot: boolean;
   scope?: string;
+  /**
+   * The frame of the container every other field on this record describes, absent when the tree
+   * named no usable scroll container at all. Without it `canScroll: false` cannot be read as
+   * "already at this edge": a tree that names no scroller and a scroller with nothing left to
+   * reveal answer the same way, and only one of them is the end of the content (#2714).
+   */
+  containerRect?: Rect;
   /**
    * A cheap signature of what is on screen right now. Two consecutive captures with the same
    * fingerprint but `canScroll` still true mean the scroll did not move the container — the actuator
@@ -55,6 +73,19 @@ export async function captureScrollEdgeState(params: {
   }
 }
 
+/**
+ * Everything one tree can answer about this edge — hidden content left, the container that answer
+ * was taken on, and the surface signature — with no capture. The one pure door into the analyzer,
+ * so every reader of an edge decision goes through the same selection rules.
+ */
+export async function readScrollEdgeState(
+  nodes: readonly (RawSnapshotNode | SnapshotNode)[],
+  edge: ScrollEdge,
+): Promise<ScrollEdgeState> {
+  const { analyzeScrollEdgeState } = await import('./scroll-edge-state/selection.ts');
+  return analyzeScrollEdgeState(nodes, edge);
+}
+
 /**
  * Is there hidden content left at this edge? The same question `runScrollEdgePasses` loops on,
  * exposed for callers with their own stop condition (`scroll --until`) so both read one signal.
@@ -63,8 +94,7 @@ export async function canScrollFurtherAtEdge(
   nodes: readonly (RawSnapshotNode | SnapshotNode)[],
   edge: ScrollEdge,
 ): Promise<boolean> {
-  const { analyzeScrollEdgeState } = await import('./scroll-edge-state/selection.ts');
-  return analyzeScrollEdgeState(nodes, edge).canScroll;
+  return (await readScrollEdgeState(nodes, edge)).canScroll;
 }
 
 /**
@@ -167,6 +197,10 @@ export async function runScrollEdgePasses<TResult>(params: {
  * travel that was asked for: one gesture cannot cross more than the viewport axis minus its edge
  * padding, so a large `amount` saturates. Naming the honored distance is what keeps
  * `scroll down 3` from reporting a three-viewport scroll it never performed.
+ *
+ * `movement` is what the owner measured after the gesture (#2714), and it outranks the requested
+ * distance: a directional scroll that observed no change cannot answer with a travel figure, since
+ * that number describes the swipe that was dispatched, not content that moved.
  */
 export function formatScrollEdgeMessage(params: {
   direction: ScrollDirection;
@@ -175,12 +209,25 @@ export function formatScrollEdgeMessage(params: {
   amount?: number | undefined;
   pixels?: number | undefined;
   honoredPixels?: number | undefined;
+  movement?: ScrollMovementObservation | undefined;
 }): string {
-  const { direction, edge, passes, amount, pixels, honoredPixels } = params;
+  const { direction, edge, passes, amount, pixels, honoredPixels, movement } = params;
   if (edge && passes === 0) {
     return `Already at ${edge}; no hidden content ${edge === 'bottom' ? 'below' : 'above'} detected`;
   }
   if (edge) return `Scrolled to ${edge} with ${passes} ${direction} passes`;
+  const verticalEdge = verticalEdgeFor(direction);
+  if (movement === 'at-edge' && verticalEdge) {
+    // The same honesty the zero-pass branch above holds: the analyzer reports no hidden content
+    // DETECTED, which is not a claim that the content provably ends here. A horizontal scroll has
+    // no edge signal to report, so it falls through to the distance it was asked for.
+    return `Scrolled ${direction} and no hidden content ${
+      verticalEdge === 'bottom' ? 'below' : 'above'
+    } was detected`;
+  }
+  if (movement === 'unchanged') {
+    return `Scrolled ${direction} and the visible content did not change`;
+  }
   if (pixels !== undefined) return `Scrolled ${direction} by ${honoredPixels ?? pixels}px`;
   if (amount !== undefined) {
     return honoredPixels === undefined
@@ -199,13 +246,37 @@ function buildScrollEdgeNoProgressError(edge: ScrollEdge, passes: number): AppEr
       reason: 'scroll_edge_no_progress',
       edge,
       passes,
-      hint:
-        `The scroll is not reaching this container. If a field is focused, dismiss the keyboard first; if it is nested inside another scroller, target it directly with scroll <dir> --until <selector>. ` +
-        `Some lists ignore synthesized scrolls — a raw drag moves them: swipe x1 y1 x2 y2 started inside the list.`,
+      hint: scrollNoProgressHint({ targetDirectly: 'with scroll <dir> --until <selector>' }),
     },
   );
 }
 
+/**
+ * What a caller does next when a scroll moved nothing while the container still had content to
+ * reveal: one hint, because every loop that notices has the same recovery.
+ *
+ * `targetDirectly` names the form the failing command has for reaching an inner scroller — `scroll
+ * --until` already IS that form, so it says only "target it directly". The raw-drag sentence belongs
+ * only where the command can say where a swipe would land: a tvOS scroll is a remote keypress with no
+ * coordinates to name, and advice nobody can follow is noise.
+ */
+export function scrollNoProgressHint(
+  params: Readonly<{ targetDirectly?: string; rawDrag?: boolean }> = {},
+): string {
+  const target =
+    params.targetDirectly === undefined
+      ? 'target it directly'
+      : `target it directly ${params.targetDirectly}`;
+  const reached =
+    `The scroll is not reaching this container. If a field is focused, dismiss the keyboard first; ` +
+    `if it is nested inside another scroller, ${target}.`;
+  if (params.rawDrag === false) return reached;
+  return (
+    reached +
+    ` Some lists ignore synthesized scrolls — a raw drag moves them: swipe x1 y1 x2 y2 started inside the list.`
+  );
+}
+
 function buildScrollEdgeVerificationError(
   edge: ScrollEdge,
   scope: string | undefined,
diff --git a/packages/capture-kit/src/snapshot/scroll-edge-state/selection.ts b/packages/capture-kit/src/snapshot/scroll-edge-state/selection.ts
index a2f50658c8..48c9a2571d 100644
--- a/packages/capture-kit/src/snapshot/scroll-edge-state/selection.ts
+++ b/packages/capture-kit/src/snapshot/scroll-edge-state/selection.ts
@@ -38,6 +38,9 @@ export function analyzeScrollEdgeState(
   return {
     canScroll,
     emptySnapshot: false,
+    // Every selection path admits only `isUsableRect` containers, so a resolved container always
+    // has a frame to report and its absence always means no container was resolved.
+    ...(container.rect ? { containerRect: container.rect } : {}),
     scope: buildScrollContainerScope(container, nodes),
     fingerprint: buildSurfaceFingerprint(container, nodes),
   };
diff --git a/packages/contracts/src/scroll-command.test.ts b/packages/contracts/src/scroll-command.test.ts
index ecd96072bc..12e701602e 100644
--- a/packages/contracts/src/scroll-command.test.ts
+++ b/packages/contracts/src/scroll-command.test.ts
@@ -1,6 +1,6 @@
 import assert from 'node:assert/strict';
 import { test } from 'vitest';
-import { resolveScrollExecutionOptions } from './scroll-command.ts';
+import { honoredScrollSwipeMidpoint, resolveScrollExecutionOptions } from './scroll-command.ts';
 
 test('resolveScrollExecutionOptions keeps ordinary scrolls controlled', () => {
   assert.deepEqual(resolveScrollExecutionOptions({ amount: 0.5 }), {
@@ -18,3 +18,21 @@ test('resolveScrollExecutionOptions marks edge scrolls inertial without changing
     releaseBehavior: 'inertial',
   });
 });
+
+/**
+ * The swipe midpoint is what lets a scroll ask whether its own gesture landed inside the container it
+ * blamed for a no-op, so the pair that pins it is a leaf that reported coordinates and one that did
+ * not: a tvOS scroll is a remote keypress, and guessing a midpoint there would invent evidence.
+ */
+test('honoredScrollSwipeMidpoint reports the middle of a swipe the leaf ran', () => {
+  assert.deepEqual(honoredScrollSwipeMidpoint({ x1: 201, y1: 665, x2: 201, y2: 209 }), {
+    x: 201,
+    y: 437,
+  });
+});
+
+test('honoredScrollSwipeMidpoint declines to guess where the owner reported no gesture', () => {
+  assert.equal(honoredScrollSwipeMidpoint({ button: 'down' }), undefined);
+  assert.equal(honoredScrollSwipeMidpoint({ x1: 201, y1: 665, x2: 201 }), undefined);
+  assert.equal(honoredScrollSwipeMidpoint({ x1: 201, y1: 665, x2: 201, y2: 'none' }), undefined);
+});
diff --git a/packages/contracts/src/scroll-command.ts b/packages/contracts/src/scroll-command.ts
index 59b2146b1a..39de1e80cf 100644
--- a/packages/contracts/src/scroll-command.ts
+++ b/packages/contracts/src/scroll-command.ts
@@ -9,6 +9,24 @@ export const DEFAULT_IOS_SCROLL_AMOUNT = 0.65;
 
 export type ScrollReleaseBehavior = 'controlled' | 'inertial';
 
+/**
+ * What a directional scroll actually SAW after its gesture, which is the only evidence that can
+ * back the distance the same response reports (#2714).
+ *
+ * - `'moved'`: the post-gesture surface differs from the pre-gesture one, so content did move.
+ * - `'at-edge'`: the surface is identical and the resolved container names no hidden content in
+ *   that direction — the scroll was a legitimate no-op at the end of the content.
+ * - `'unchanged'`: the surface is identical and the direction has no end-of-content signal to read
+ *   (a horizontal scroll: the hidden-content analyzer only covers the vertical axis), so the
+ *   response says what it measured without guessing which of the two it was.
+ * - `'unobserved'`: nothing comparable was available, so the distance rests on the gesture plan
+ *   alone. Callers that need the effect confirmed ask for a capture or a `--settle` observation.
+ *
+ * A directional scroll that measures an unchanged surface WITH hidden content still in that
+ * direction does not answer at all: it fails with `scroll_no_progress`.
+ */
+export type ScrollMovementObservation = 'moved' | 'at-edge' | 'unchanged' | 'unobserved';
+
 export type ScrollDistanceOptions = {
   amount?: number;
   pixels?: number;
@@ -95,6 +113,29 @@ export function honoredScrollDurationMs(
   return typeof result?.durationMs === 'number' ? result.durationMs : undefined;
 }
 
+/**
+ * Where the leaf's swipe ran, as the midpoint of the coordinates it reported — the same absolute space
+ * its snapshots use, which is what lets a container rect say whether the gesture landed inside it.
+ * An owner that reports no coordinates is answered `undefined` rather than guessed at: a tvOS scroll
+ * is a remote keypress, so there is no midpoint to name.
+ */
+export function honoredScrollSwipeMidpoint(
+  result: Record<string, unknown> | undefined,
+): { x: number; y: number } | undefined {
+  const x1 = readReportedCoordinate(result?.x1);
+  const y1 = readReportedCoordinate(result?.y1);
+  const x2 = readReportedCoordinate(result?.x2);
+  const y2 = readReportedCoordinate(result?.y2);
+  if (x1 === undefined || y1 === undefined || x2 === undefined || y2 === undefined) {
+    return undefined;
+  }
+  return { x: (x1 + x2) / 2, y: (y1 + y2) / 2 };
+}
+
+function readReportedCoordinate(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
 /**
  * `scroll` — the generic-route result built by `buildDispatchedScrollResult`
  * (src/core/dispatch-scroll.ts): the resolved direction, the edge-pass
@@ -118,6 +159,14 @@ export type ScrollCommandResult = {
   durationMs?: number;
   message?: string;
   settle?: SettleObservation;
+  /**
+   * The observation that gated this response's distance claim. See
+   * {@link ScrollMovementObservation}: `scroll` answers with what it measured after the gesture,
+   * and only `'moved'` and `'at-edge'` confirm the surface's fate. Absent on the tiers that verify
+   * per pass instead of per gesture (`scroll top`/`bottom` and `--until`), and on platforms whose
+   * scroll owner never dispatches a swipe (the Linux wheel).
+   */
+  movement?: ScrollMovementObservation;
   /**
    * Set only when an on-screen keyboard made the owner clip the swipe into the band above it
    * (#2500). Absent means the swipe was not clipped, which is not the same claim as `false`: a
diff --git a/src/daemon/scroll-until.ts b/src/daemon/scroll-until.ts
index 8b123826b6..300ed28fe7 100644
--- a/src/daemon/scroll-until.ts
+++ b/src/daemon/scroll-until.ts
@@ -11,8 +11,10 @@ import { SELECTOR_PIPELINE_POLICIES } from '@agent-device/selectors/selector-pip
 import {
   canScrollFurtherAtEdge,
   pushScrollSurfaceSignature,
+  scrollNoProgressHint,
   scrollSurfaceFingerprint,
   scrollSurfaceIsStuck,
+  verticalEdgeFor,
   type ScrollEdge,
 } from '@agent-device/capture-kit/scroll-edge-state';
 
@@ -252,9 +254,7 @@ function scrollUntilNoProgressError(
       selector,
       direction,
       passes,
-      hint:
-        `The scroll is not reaching this container. If a field is focused, dismiss the keyboard first; if it is nested inside another scroller, target it directly. ` +
-        `Some lists ignore synthesized scrolls — a raw drag moves them: swipe x1 y1 x2 y2 started inside the list.`,
+      hint: scrollNoProgressHint(),
     },
   );
 }
@@ -279,13 +279,3 @@ function scrollUntilCaptureError(
     },
   );
 }
-
-/**
- * The end-of-content analyzer only reads vertical edges, so a horizontal `--until` is bounded by its
- * pass budget alone rather than by a signal that would always report "no room".
- */
-function verticalEdgeFor(direction: ScrollDirection): ScrollEdge | undefined {
-  if (direction === 'down') return 'bottom';
-  if (direction === 'up') return 'top';
-  return undefined;
-}

From 61b0a56430e102db1862a04d7041289d79876cda Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Wed, 23 Sep 2026 16:19:13 +0200
Subject: [PATCH 046/132] fix(scroll): observe the movement a directional
 scroll can claim (#2776)

---
 .../interaction-outcome-policy.test.ts        |  56 ++
 src/daemon/__tests__/scroll-movement.test.ts  | 501 +++++++++++++++
 src/daemon/deferred-interaction-outcome.ts    |  15 +-
 src/daemon/interaction-outcome-policy.ts      |  54 +-
 src/daemon/scroll-movement.ts                 | 591 ++++++++++++++++++
 5 files changed, 1204 insertions(+), 13 deletions(-)
 create mode 100644 src/daemon/__tests__/scroll-movement.test.ts
 create mode 100644 src/daemon/scroll-movement.ts

diff --git a/src/daemon/__tests__/interaction-outcome-policy.test.ts b/src/daemon/__tests__/interaction-outcome-policy.test.ts
index 7dfbcef361..9cd0d34c5a 100644
--- a/src/daemon/__tests__/interaction-outcome-policy.test.ts
+++ b/src/daemon/__tests__/interaction-outcome-policy.test.ts
@@ -5,6 +5,7 @@ import {
   buildInteractionSurfaceSignature,
   classifyBaselineSurfaceEvidence,
   classifyInteractionSurfaceChange,
+  discriminatingSurfaceChangedWithinRect,
   markPendingInteractionOutcome,
   stripInternalInteractionFlags,
 } from '../interaction-outcome-policy.ts';
@@ -411,3 +412,58 @@ function makeSnapshotWithExtraText(label: string, y = 100): SnapshotState {
     ],
   };
 }
+
+// ---------------------------------------------------------------------------
+// discriminatingSurfaceChangedWithinRect (#2714 review): a whole-surface
+// difference that lives outside the region a command acted on is not that
+// command's doing. Measured on the Android tester, the status bar changed on
+// its own over a list that never moved. The strict key-matched view stays
+// owned here; this only narrows the region it is asked about.
+// ---------------------------------------------------------------------------
+
+const LIST_RECT = { x: 0, y: 150, width: 390, height: 600 };
+
+function rowAt(index: number, y: number) {
+  return {
+    type: 'StaticText',
+    identifier: `row-${index}`,
+    label: `Row ${index}`,
+    rect: { x: 12, y, width: 300, height: 24 },
+  } as SnapshotState['nodes'][number];
+}
+
+function surfaceWithClock(clock: string, secondRowY: number) {
+  return [
+    {
+      type: 'Image',
+      identifier: 'status-clock',
+      label: clock,
+      rect: { x: 12, y: 12, width: 40, height: 18 },
+    } as SnapshotState['nodes'][number],
+    rowAt(1, 200),
+    rowAt(2, secondRowY),
+  ];
+}
+
+test('discriminatingSurfaceChangedWithinRect reads a movement inside the region', () => {
+  const before = buildInteractionSurfaceSignature(surfaceWithClock('2:40', 300));
+  const after = buildInteractionSurfaceSignature(surfaceWithClock('2:40', 420));
+
+  assert.equal(discriminatingSurfaceChangedWithinRect(before, after, LIST_RECT), true);
+});
+
+test('discriminatingSurfaceChangedWithinRect does not read a movement outside the region', () => {
+  const before = buildInteractionSurfaceSignature(surfaceWithClock('2:40', 300));
+  const after = buildInteractionSurfaceSignature(surfaceWithClock('2:41', 300));
+
+  // The whole surface did change — that is the trap this reader exists to refuse.
+  assert.equal(classifyBaselineSurfaceEvidence(before, after), 'changed');
+  assert.equal(discriminatingSurfaceChangedWithinRect(before, after, LIST_RECT), false);
+});
+
+test('discriminatingSurfaceChangedWithinRect counts content appearing inside the region', () => {
+  const before = buildInteractionSurfaceSignature(surfaceWithClock('2:40', 300));
+  const after = buildInteractionSurfaceSignature([...surfaceWithClock('2:40', 300), rowAt(3, 640)]);
+
+  assert.equal(discriminatingSurfaceChangedWithinRect(before, after, LIST_RECT), true);
+});
diff --git a/src/daemon/__tests__/scroll-movement.test.ts b/src/daemon/__tests__/scroll-movement.test.ts
new file mode 100644
index 0000000000..bf46f3cbdc
--- /dev/null
+++ b/src/daemon/__tests__/scroll-movement.test.ts
@@ -0,0 +1,501 @@
+import assert from 'node:assert/strict';
+import { test, vi } from 'vitest';
+import type { SnapshotResult } from '@agent-device/contracts/interactor-types';
+import { buildSnapshotState } from '@agent-device/capture-kit/snapshot-state';
+import { AppError } from '@agent-device/kernel/errors';
+import type { CommandFlags } from '@agent-device/contracts/command';
+import type { Rect, SnapshotNode } from '@agent-device/kernel/snapshot';
+import { emitDiagnostic } from '@agent-device/host-kit/diagnostics';
+import { IOS_SIMULATOR, MACOS_DEVICE } from '../../__tests__/test-utils/device-fixtures.ts';
+import { makeSession } from '../../__tests__/test-utils/session-factories.ts';
+import { expireRefFrame } from '../ref-frame.ts';
+import {
+  observeScrollMovement,
+  planScrollMovement,
+  readScrollSurfaceBaseline,
+  reportScrollMovementNotApplicable,
+  reportScrollMovementUnobserved,
+  type ScrollMovementPlan,
+  type ScrollSurfaceBaseline,
+} from '../scroll-movement.ts';
+
+// The reason a scroll withholds its claim lives in the daemon log, so the cases below pin it there
+// rather than trusting a bare `unobserved`.
+vi.mock('@agent-device/host-kit/diagnostics', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@agent-device/host-kit/diagnostics')>();
+  return { ...actual, emitDiagnostic: vi.fn() };
+});
+
+const loggedDiagnostics = vi.mocked(emitDiagnostic);
+
+function movementDiagnostic(): { phase: string; level: string; data: Record<string, unknown> } {
+  const call = [...loggedDiagnostics.mock.calls]
+    .reverse()
+    .find(([event]) => String(event.phase).startsWith('scroll_movement_'));
+  if (!call) throw new Error('the movement module logged no diagnostic');
+  return {
+    phase: call[0].phase,
+    level: call[0].level ?? 'info',
+    data: (call[0].data ?? {}) as Record<string, unknown>,
+  };
+}
+
+function assertWithheld(reason: string): void {
+  const entry = movementDiagnostic();
+  assert.equal(entry.phase, 'scroll_movement_unobserved');
+  assert.equal(entry.data.reason, reason);
+}
+
+function assertPlanKind<K extends ScrollMovementPlan['kind']>(
+  plan: ScrollMovementPlan,
+  kind: K,
+): asserts plan is Extract<ScrollMovementPlan, { kind: K }> {
+  if (plan.kind !== kind) throw new Error(`expected a "${kind}" plan, got "${plan.kind}"`);
+}
+
+/**
+ * The observation that gates a directional scroll's distance claim (#2714). Node shapes follow the
+ * live pair `interaction-surface-baseline-evidence.test.ts` transcribed: a scroller holding labelled
+ * rows, plus fixed chrome that never moves.
+ *
+ * Every verdict here is paired with the closest input that must NOT produce it, because the whole
+ * risk of this rule is failing a scroll that was fine: a no-op and a scroll at the end of its list
+ * differ by one hidden-content hint, a no-op and a scroll over a busy screen differ by whether the
+ * surface will hold still, and a no-op and a scroll whose content was replaced differ by the strict
+ * no-effect bar rather than by the distance it names.
+ */
+
+const CONTAINER: Rect = { x: 18, y: 178, width: 366, height: 662 };
+const SWIPE_MIDPOINT = { x: 201, y: 437 };
+const REQUESTED_PIXELS = 656;
+
+/** The trees one case feeds the observer: a fixed list of them, or one that never repeats. */
+type SnapshotFrames = SnapshotNode[][] | ((attempt: number) => SnapshotNode[] | Error);
+
+function screen(rowOffset: number, hiddenBelow = true): SnapshotNode[] {
+  return [
+    {
+      type: 'ScrollView',
+      identifier: 'lab-list',
+      rect: CONTAINER,
+      ...(hiddenBelow ? { hiddenContentBelow: true } : {}),
+    },
+    {
+      type: 'StaticText',
+      label: 'Row one',
+      rect: { x: 24, y: 200 + rowOffset, width: 300, height: 20 },
+    },
+    {
+      type: 'StaticText',
+      label: 'Row two',
+      rect: { x: 24, y: 260 + rowOffset, width: 300, height: 20 },
+    },
+    {
+      type: 'Button',
+      identifier: 'automation-press',
+      label: 'Press canary',
+      rect: { x: 24, y: 780, width: 200, height: 44 },
+    },
+  ] as SnapshotNode[];
+}
+
+function state(nodes: SnapshotNode[], flags?: Partial<CommandFlags>) {
+  return buildSnapshotState({ nodes, backend: 'xctest', producer: 'apple-runner' }, flags);
+}
+
+function baselineOf(nodes: SnapshotNode[], flags?: Partial<CommandFlags>): ScrollSurfaceBaseline {
+  const baseline = readScrollSurfaceBaseline(state(nodes, flags));
+  if (!baseline) throw new Error('the fixture produced no comparable surface');
+  return baseline;
+}
+
+/**
+ * The captures the observation is allowed to take. A case that under-provides frames fails loudly:
+ * reusing the last frame would let a quiet pair form by accident, turning a budget case into a
+ * no-op case that passes for the wrong reason.
+ */
+function captures(screens: SnapshotFrames): {
+  calls: () => number;
+  capture: () => Promise<SnapshotResult>;
+} {
+  const next: (attempt: number) => SnapshotNode[] | Error =
+    typeof screens === 'function' ? screens : queueReader(screens);
+  let calls = 0;
+  return {
+    calls: () => calls,
+    capture: async (): Promise<SnapshotResult> => {
+      const frame = next(calls);
+      calls += 1;
+      if (frame instanceof Error) throw frame;
+      return { nodes: frame, backend: 'xctest', producer: 'apple-runner' };
+    },
+  };
+}
+
+function queueReader(frames: SnapshotNode[][]) {
+  return (attempt: number): SnapshotNode[] => {
+    const frame = frames[attempt];
+    if (frame === undefined) {
+      throw new Error('the observation captured more times than the case supplied frames for');
+    }
+    return frame;
+  };
+}
+
+function observe(params: {
+  direction?: 'up' | 'down' | 'left' | 'right';
+  baseline: ScrollSurfaceBaseline;
+  screens: SnapshotFrames;
+  midpoint?: { x: number; y: number };
+  pixels?: number;
+  budgetMs?: number;
+}) {
+  const spy = captures(params.screens);
+  loggedDiagnostics.mockClear();
+  const observation = observeScrollMovement({
+    direction: params.direction ?? 'down',
+    baseline: params.baseline,
+    swipe: {
+      midpoint: params.midpoint ?? SWIPE_MIDPOINT,
+      pixels: params.pixels ?? REQUESTED_PIXELS,
+    },
+    capture: spy.capture,
+    pollMs: 1,
+    budgetMs: params.budgetMs ?? 5_000,
+  });
+  return { observation, spy };
+}
+
+test('a surface that no longer holds the pre-gesture content answers moved on the first capture', async () => {
+  const { observation, spy } = observe({
+    baseline: baselineOf(screen(0)),
+    screens: [screen(-300)],
+  });
+
+  assert.equal(await observation, 'moved');
+  // The cost claim of the whole feature: a scroll that worked is confirmed by one capture.
+  assert.equal(spy.calls(), 1);
+});
+
+test('a surface that never shifted while the container still hides content refuses with a typed reason', async () => {
+  const { observation, spy } = observe({
+    baseline: baselineOf(screen(0)),
+    screens: [screen(0), screen(0)],
+  });
+
+  await assert.rejects(
+    () => observation,
+    (error: unknown) =>
+      error instanceof AppError &&
+      error.code === 'COMMAND_FAILED' &&
+      error.details?.reason === 'scroll_no_progress' &&
+      error.details.direction === 'down' &&
+      error.details.hiddenContentAt === 'bottom' &&
+      error.details.requestedPixels === REQUESTED_PIXELS &&
+      typeof error.details.hint === 'string' &&
+      /swipe x1 y1 x2 y2/.test(error.details.hint),
+  );
+  // Refusing needs the surface at rest, which needs the second read.
+  assert.equal(spy.calls(), 2);
+});
+
+/**
+ * The refusal above names a raw drag because it knows where the swipe ran. An owner that reports no
+ * coordinates (a tvOS scroll is a remote keypress) must not be told to swipe where it cannot.
+ */
+test('a refusal without gesture coordinates does not recommend a swipe', async () => {
+  const spy = captures([screen(0), screen(0)]);
+
+  await assert.rejects(
+    () =>
+      observeScrollMovement({
+        direction: 'down',
+        baseline: baselineOf(screen(0)),
+        swipe: {},
+        capture: spy.capture,
+        pollMs: 1,
+        budgetMs: 5_000,
+      }),
+    (error: unknown) =>
+      error instanceof AppError && !/swipe x1 y1 x2 y2/.test(String(error.details?.hint)),
+  );
+});
+
+test('a surface that never shifted with nothing left to reveal answers at-edge, not a refusal', async () => {
+  const { observation } = observe({
+    baseline: baselineOf(screen(0)),
+    screens: [screen(0, false), screen(0, false)],
+  });
+
+  assert.equal(await observation, 'at-edge');
+});
+
+test('a tree that names no scroll container is not read as the end of the content', async () => {
+  const rowsOnly = screen(0).filter((node) => node.type !== 'ScrollView');
+  const { observation } = observe({
+    baseline: baselineOf(rowsOnly),
+    screens: [rowsOnly, rowsOnly],
+  });
+
+  assert.equal(await observation, 'unobserved');
+  assertWithheld('no-scroll-container');
+});
+
+test('a container the gesture never ran inside is not blamed for the no-op', async () => {
+  const { observation } = observe({
+    baseline: baselineOf(screen(0)),
+    screens: [screen(0), screen(0)],
+    midpoint: { x: 201, y: 40 },
+  });
+
+  assert.equal(await observation, 'unobserved');
+  assertWithheld('container-outside-swipe');
+});
+
+test('a horizontal scroll that moved nothing reports what it measured instead of refusing', async () => {
+  const pager = [
+    { type: 'ScrollView', identifier: 'pager', rect: CONTAINER, hiddenContentBelow: true },
+    { type: 'StaticText', label: 'Page', rect: { x: 24, y: 400, width: 200, height: 20 } },
+  ] as SnapshotNode[];
+  const { observation } = observe({
+    direction: 'left',
+    baseline: baselineOf(pager),
+    screens: [pager, pager],
+  });
+
+  assert.equal(await observation, 'unchanged');
+});
+
+/**
+ * A pair from different capture lineages is not two views of one screen — the XCTest-channel fallback
+ * swaps the producer mid-request (#1569) — so its difference is neither movement nor a no-op. The
+ * frames here genuinely differ: the gate has to hold on the path that would otherwise answer `moved`,
+ * not only on the quiet one.
+ */
+test('a capture lineage that changed mid-request withholds the claim, even as the frames differ', async () => {
+  const baseline = readScrollSurfaceBaseline({
+    ...state(screen(0)),
+    comparisonKey: 'lineage-before',
+  });
+  if (!baseline) throw new Error('the fixture produced no comparable surface');
+  const { observation, spy } = observe({
+    baseline,
+    screens: [screen(-300)],
+  });
+
+  assert.equal(await observation, 'unobserved');
+  assertWithheld('capture-lineage-drift');
+  assert.equal(spy.calls(), 1);
+});
+
+/** The same gate on the other lineage axis: `snapshot -i` stored the baseline, and the broad tree this
+ * command reads shares too little with it to refuse a scroll on — or to credit one. */
+test('a baseline captured interactively-only withholds the claim, even as the frames differ', async () => {
+  const { observation } = observe({
+    baseline: baselineOf(screen(0), { snapshotInteractiveOnly: true }),
+    screens: [screen(-300)],
+  });
+
+  assert.equal(await observation, 'unobserved');
+  assertWithheld('baseline-presentation-drift');
+});
+
+test('content appearing under unchanged chrome is not judged a no-op either', async () => {
+  // A toast over an untouched list: nothing the baseline named disappeared, so the tolerant
+  // classifier says 'unchanged' — and the strict no-effect bar refuses to call it a scroll that did
+  // nothing, in either direction.
+  const toast = {
+    type: 'StaticText',
+    label: 'Saved',
+    rect: { x: 24, y: 60, width: 120, height: 20 },
+  } as SnapshotNode;
+  const { observation } = observe({
+    baseline: baselineOf(screen(0)),
+    screens: [
+      [...screen(0), toast],
+      [...screen(0), toast],
+    ],
+  });
+
+  assert.equal(await observation, 'unobserved');
+  assertWithheld('surface-divergence');
+});
+
+test('a surface still in motion on the first read is a scroll that worked, not a no-op', async () => {
+  const { observation, spy } = observe({
+    baseline: baselineOf(screen(0)),
+    screens: [screen(0), screen(-320)],
+  });
+
+  assert.equal(await observation, 'moved');
+  assert.equal(spy.calls(), 2);
+});
+
+test('a surface that never holds still spends the budget and answers unobserved', async () => {
+  // A spinner that comes and goes keeps every consecutive pair different while every element that
+  // can be identified sits exactly where it was: `unchanged` against the baseline, never at rest.
+  // Refusing here would fail a scroll over a busy screen, so the budget expires instead.
+  const flicker = {
+    type: 'ActivityIndicator',
+    label: 'Loading',
+    rect: { x: 340, y: 20, width: 20, height: 20 },
+  } as SnapshotNode;
+  const { observation, spy } = observe({
+    baseline: baselineOf(screen(0)),
+    screens: (attempt) => (attempt % 2 === 0 ? screen(0) : [...screen(0), flicker]),
+    budgetMs: 40,
+  });
+
+  assert.equal(await observation, 'unobserved');
+  assertWithheld('surface-unsettled');
+  // The budget, not an accidental quiet pair: more than the two reads a verdict needs were taken.
+  assert.ok(spy.calls() > 2);
+});
+
+test('a capture this command cannot read withholds the claim instead of failing the scroll', async () => {
+  const unreadable = new Error('snapshot source unsupported');
+  const { observation } = observe({
+    baseline: baselineOf(screen(0)),
+    screens: () => unreadable,
+    budgetMs: 40,
+  });
+
+  assert.equal(await observation, 'unobserved');
+  assertWithheld('capture-unreadable');
+});
+
+/**
+ * The tree a scroll reads carries system chrome along with the app's content, and on Android that
+ * chrome changes by itself: measured on the tester's `/catalog`, a status-bar icon alone turned the
+ * pair into "changed" over a list that had not moved. Only a difference inside the scroller counts as
+ * the gesture's doing — and the absence of one is not evidence that the gesture failed either.
+ */
+test('a difference outside the scrolled container does not buy the movement claim', async () => {
+  const chrome = {
+    type: 'Image',
+    identifier: 'status-clock',
+    label: '2:40',
+    rect: { x: 20, y: 20, width: 60, height: 20 },
+  } as SnapshotNode;
+  const { observation, spy } = observe({
+    baseline: baselineOf([...screen(0), chrome]),
+    screens: [[...screen(0), { ...chrome, label: '2:41' } as SnapshotNode]],
+  });
+
+  assert.equal(await observation, 'unobserved');
+  assertWithheld('change-outside-container');
+  // The claim is confined by the tree already read: no second capture is spent to ask.
+  assert.equal(spy.calls(), 1);
+});
+
+test('a surface with no container to confine the claim to keeps the whole-surface answer', async () => {
+  const rowsOnly = (offset: number) => screen(offset).filter((node) => node.type !== 'ScrollView');
+  const { observation } = observe({
+    baseline: baselineOf(rowsOnly(0)),
+    screens: [rowsOnly(-300)],
+  });
+
+  assert.equal(await observation, 'moved');
+});
+
+/**
+ * What a scroll owes is decided once, before the gesture dispatches, because every fact the plan reads
+ * — the device family, the caller's flags, the tree the session holds — is about to change under it.
+ */
+test('a platform whose scroll dispatches no swipe is declined the observation', () => {
+  const plan = planScrollMovement({
+    device: MACOS_DEVICE,
+    flags: undefined,
+    session: makeSession('movement-plan-desktop'),
+  });
+  assertPlanKind(plan, 'declined');
+
+  assert.equal(plan.reason, 'non-swipe-platform');
+});
+
+test('a caller that pays for its own observation is declined before the gesture', () => {
+  const plan = planScrollMovement({
+    device: IOS_SIMULATOR,
+    flags: { postGestureStabilization: false },
+    session: makeSession('movement-plan-replay', { snapshot: state(screen(0)) }),
+  });
+  assertPlanKind(plan, 'declined');
+
+  assert.equal(plan.reason, 'caller-declined-observation');
+});
+
+test('a settle observation owns the outcome, so the scroll does not answer twice', () => {
+  const plan = planScrollMovement({
+    device: IOS_SIMULATOR,
+    flags: { settle: true },
+    session: makeSession('movement-plan-settle', { snapshot: state(screen(0)) }),
+  });
+  assertPlanKind(plan, 'declined');
+
+  assert.equal(plan.reason, 'settle-observer-owns-outcome');
+});
+
+test('a session holding no tree cannot back a movement claim, and names why', () => {
+  const plan = planScrollMovement({
+    device: IOS_SIMULATOR,
+    flags: undefined,
+    session: makeSession('movement-plan-empty'),
+  });
+  assertPlanKind(plan, 'unobservable');
+
+  assert.equal(plan.reason, 'stored-surface-unusable');
+});
+
+test('a tree the session no longer stands behind is refused as a baseline', () => {
+  const session = makeSession('movement-plan-stale', { snapshot: state(screen(0)) });
+  expireRefFrame(session);
+  const plan = planScrollMovement({ device: IOS_SIMULATOR, flags: undefined, session });
+  assertPlanKind(plan, 'unobservable');
+
+  assert.equal(plan.reason, 'stored-surface-not-current');
+});
+
+test('a gesture nobody has read yet may still be moving the stored tree', () => {
+  const session = makeSession('movement-plan-pending', { snapshot: state(screen(0)) });
+  session.postGestureStabilization = { action: 'tap', positionals: [], markedAt: Date.now() };
+  const plan = planScrollMovement({ device: IOS_SIMULATOR, flags: undefined, session });
+  assertPlanKind(plan, 'unobservable');
+
+  assert.equal(plan.reason, 'prior-gesture-unsettled');
+});
+
+test('a session standing behind its tree gets the read, at no extra capture cost', () => {
+  const snapshot = state(screen(0));
+  const plan = planScrollMovement({
+    device: IOS_SIMULATOR,
+    flags: undefined,
+    session: makeSession('movement-plan-observe', { snapshot }),
+  });
+  assertPlanKind(plan, 'observe');
+
+  assert.deepEqual(plan.baseline, readScrollSurfaceBaseline(snapshot));
+});
+
+test('the withheld answer carries its reason to the daemon log, not only to the response', () => {
+  loggedDiagnostics.mockClear();
+
+  const answer = reportScrollMovementUnobserved('down', 'stored-surface-not-current', {
+    swipe: { midpoint: SWIPE_MIDPOINT, pixels: REQUESTED_PIXELS },
+  });
+
+  assert.equal(answer, 'unobserved');
+  const entry = movementDiagnostic();
+  assert.equal(entry.phase, 'scroll_movement_unobserved');
+  assert.equal(entry.data.reason, 'stored-surface-not-current');
+  assert.equal(entry.data.requestedPixels, REQUESTED_PIXELS);
+});
+
+test('the command that owes no observation logs which owner owes the read', () => {
+  loggedDiagnostics.mockClear();
+
+  reportScrollMovementNotApplicable('down', 'owner-without-capture');
+
+  const entry = movementDiagnostic();
+  assert.equal(entry.phase, 'scroll_movement_not_applicable');
+  assert.equal(entry.data.reason, 'owner-without-capture');
+});
diff --git a/src/daemon/deferred-interaction-outcome.ts b/src/daemon/deferred-interaction-outcome.ts
index 043c2fe463..79e6cc4d87 100644
--- a/src/daemon/deferred-interaction-outcome.ts
+++ b/src/daemon/deferred-interaction-outcome.ts
@@ -27,6 +27,7 @@ import {
   summarizeDiscriminatingSurfaceDivergence,
   markPendingInteractionOutcome,
   retryPendingInteractionOutcome,
+  snapshotSurfaceComparisonKey,
   type InteractionRetryTap,
 } from './interaction-outcome-policy.ts';
 import { runPostGestureStabilityLoop } from '@agent-device/capture-kit/post-gesture-stability';
@@ -124,7 +125,7 @@ function markPostGestureStabilization(
           baselineSignature,
           // Recorded so the loop can tell a comparable quiet capture from one
           // served by a different backend, which is not comparable at all.
-          baselineBackend: snapshotComparisonKey(session.snapshot),
+          baselineBackend: snapshotSurfaceComparisonKey(session.snapshot),
         }
       : {}),
   };
@@ -350,7 +351,7 @@ export async function capturePostGestureStabilizedResult<T>(params: {
         const snapshot = readSnapshot(value);
         return {
           signature: buildInteractionSurfaceSignature(snapshot.nodes),
-          backend: snapshotComparisonKey(snapshot),
+          backend: snapshotSurfaceComparisonKey(snapshot),
         };
       },
       signaturesStable: areInteractionSurfaceSignaturesStable,
@@ -363,16 +364,6 @@ export async function capturePostGestureStabilizedResult<T>(params: {
   return outcome;
 }
 
-/**
- * What makes two captures comparable at all. The iOS comparison key already carries the whole
- * presentation identity, including the surface the capture described — an in-place system surface (a
- * web sign-in sheet) is captured under its own host lineage (#2438) — so a sheet appearing or
- * dismissing mid-poll reads as incomparable rather than as a stable surface.
- */
-function snapshotComparisonKey(snapshot: SnapshotState | undefined): string | undefined {
-  return snapshot?.comparisonKey ?? snapshot?.snapshotQuality?.backend;
-}
-
 function isPostGestureStabilizingAction(
   action: string,
   positionals: string[],
diff --git a/src/daemon/interaction-outcome-policy.ts b/src/daemon/interaction-outcome-policy.ts
index 3de9938efa..3519a01e83 100644
--- a/src/daemon/interaction-outcome-policy.ts
+++ b/src/daemon/interaction-outcome-policy.ts
@@ -1,6 +1,6 @@
 import type { CommandFlags } from '@agent-device/contracts/command';
 import { isMobilePlatform } from '@agent-device/kernel/device';
-import type { SnapshotNode, SnapshotState } from '@agent-device/kernel/snapshot';
+import type { Rect, SnapshotNode, SnapshotState } from '@agent-device/kernel/snapshot';
 import { collectKeyboardChromeRefs } from '@agent-device/capture-kit/snapshot-chrome';
 import { emitDiagnostic } from '@agent-device/host-kit/diagnostics';
 import { isViewportRootNode } from '@agent-device/contracts/snapshot';
@@ -256,6 +256,17 @@ export function buildInteractionSurfaceSignature(
   return entries;
 }
 
+/**
+ * What makes two captures comparable at all: the iOS comparison key when the capture carries one,
+ * and the capturing backend otherwise. Two trees from different producers are not two views of one
+ * screen — the XCTest-channel fallback swapping mid-request (#1569) is the case this exists for.
+ */
+export function snapshotSurfaceComparisonKey(
+  snapshot: SnapshotState | undefined,
+): string | undefined {
+  return snapshot?.comparisonKey ?? snapshot?.snapshotQuality?.backend;
+}
+
 export function classifyInteractionSurfaceChange(
   before: InteractionSurfaceSignature,
   after: InteractionSurfaceSignature,
@@ -453,6 +464,47 @@ export function summarizeDiscriminatingSurfaceDivergence(
   return { onlyInBaseline, onlyInCurrent: currentByKey.size, rectMismatched, shared };
 }
 
+/**
+ * Whether the DISCRIMINATING entries inside `rect` differ across a gesture, on the same key-matched,
+ * rect-tolerant view `haveIdenticalDiscriminatingSurfaces` uses — restricted to one region.
+ *
+ * A whole-surface difference is not automatically the gesture's doing. A captured tree carries system
+ * chrome with it, and on Android the status bar clocks and icons change on their own while the app's
+ * list sits frozen underneath. A difference that lives entirely outside the region a command acted on
+ * therefore proves nothing in either direction: it cannot credit the gesture, and it cannot convict it.
+ */
+export function discriminatingSurfaceChangedWithinRect(
+  before: InteractionSurfaceSignature,
+  after: InteractionSurfaceSignature,
+  rect: Rect,
+): boolean {
+  const beforeInRect = discriminatingEntriesWithinRect(before, rect);
+  const afterByKey = new Map(
+    discriminatingEntriesWithinRect(after, rect).map((entry) => [entry.key, entry]),
+  );
+  for (const entry of beforeInRect) {
+    const other = afterByKey.get(entry.key);
+    if (!other) return true;
+    if (!rectsWithinTolerance(entry, other)) return true;
+    afterByKey.delete(entry.key);
+  }
+  return afterByKey.size > 0;
+}
+
+function discriminatingEntriesWithinRect(
+  signature: InteractionSurfaceSignature,
+  rect: Rect,
+): InteractionSurfaceSignature {
+  return signature.filter(
+    (entry) =>
+      entry.discriminating &&
+      entry.x < rect.x + rect.width &&
+      rect.x < entry.x + entry.width &&
+      entry.y < rect.y + rect.height &&
+      rect.y < entry.y + entry.height,
+  );
+}
+
 function supportsInteractionOutcomePolicy(session: SessionState): boolean {
   return isMobilePlatform(session.device);
 }
diff --git a/src/daemon/scroll-movement.ts b/src/daemon/scroll-movement.ts
new file mode 100644
index 0000000000..e0c878d7bb
--- /dev/null
+++ b/src/daemon/scroll-movement.ts
@@ -0,0 +1,591 @@
+import type { ScrollMovementObservation } from '@agent-device/contracts/scroll-command';
+import type { ScrollDirection } from '@agent-device/contracts/scroll-gesture';
+import type { SnapshotResult } from '@agent-device/contracts/interactor-types';
+import type { CommandFlags } from '@agent-device/contracts/command';
+import { isMobilePlatform, type DeviceInfo } from '@agent-device/kernel/device';
+import { buildSnapshotState } from '@agent-device/capture-kit/snapshot-state';
+import {
+  readScrollEdgeState,
+  scrollNoProgressHint,
+  verticalEdgeFor,
+  type ScrollEdge,
+} from '@agent-device/capture-kit/scroll-edge-state';
+import { containsPoint } from '@agent-device/kernel/rect';
+import { AppError } from '@agent-device/kernel/errors';
+import type { Point, Rect, SnapshotState } from '@agent-device/kernel/snapshot';
+import { emitDiagnostic } from '@agent-device/host-kit/diagnostics';
+import { sleep } from '@agent-device/host-kit/retry';
+import {
+  areInteractionSurfaceSignaturesStable,
+  buildInteractionSurfaceSignature,
+  classifyBaselineSurfaceEvidence,
+  discriminatingSurfaceChangedWithinRect,
+  haveIdenticalDiscriminatingSurfaces,
+  snapshotSurfaceComparisonKey,
+  summarizeDiscriminatingSurfaceDivergence,
+  type InteractionSurfaceChange,
+  type InteractionSurfaceSignature,
+} from './interaction-outcome-policy.ts';
+import { refFrameState } from './ref-frame.ts';
+import { isPostGestureStabilizationPending } from './deferred-interaction-outcome.ts';
+import type { SessionState } from './session-state.ts';
+
+/**
+ * What one directional scroll saw after its gesture, and the only thing that can back the distance
+ * the same response reports (#2714).
+ *
+ * `scroll <direction>` used to answer with the travel its gesture plan had computed. That number
+ * describes the swipe that was dispatched, not the content that moved, so a scroll whose gesture
+ * never reached the container reported success with a distance — repeatedly, on every retry, until a
+ * later assertion failed for a reason no log explained. This module reads the difference the command
+ * can actually observe: the tree the session already held before the gesture, and one tree after it.
+ *
+ * The evidence rules are not a second opinion on that pair. The signature, the subset-tolerant
+ * baseline classifier, and the strict no-effect bar all belong to
+ * `interaction-outcome-policy.ts`, the same comparators the deferred post-gesture stabilization
+ * applies to every other gesture, so "that scroll did nothing" means one thing in this daemon.
+ * What is new here is only WHEN the answer is owed: a directional scroll pays one capture to gate its
+ * own reply instead of leaving the proof to the next command's snapshot.
+ *
+ * The shape of the loop is the mirror image of that stabilization: a surface that differs from the
+ * baseline is answered on the first capture, so a scroll that worked pays nothing extra; only a
+ * surface that looks untouched keeps polling (a mid-flight or stale read is indistinguishable from a
+ * no-op until it either moves or goes quiet), and only an untouched surface at rest is ever reported.
+ *
+ * Nothing is classified before the two trees are established to be two views of one screen, and that
+ * gate runs on every capture rather than only on the quiet path. The deferred loop can adopt a new
+ * producer when a capture lineage changes under it and keep going, because its question is whether the
+ * surface ever settles; this one compares against a pre-gesture tree, so a pair from different
+ * lineages can never answer either way and the claim is withheld rather than re-based.
+ */
+
+/** How long a scroll keeps asking whether an untouched surface is really untouched (#1542's window). */
+const MOVEMENT_VERDICT_BUDGET_MS = 1_500;
+const MOVEMENT_POLL_MS = 200;
+
+/** The pre-gesture surface, already in hand: no capture is spent to produce it. */
+export type ScrollSurfaceBaseline = Readonly<{
+  signature: InteractionSurfaceSignature;
+  presentationKey: string | undefined;
+  comparisonKey: string | undefined;
+}>;
+
+/** Why there is nothing honest to compare this scroll's effect against. */
+export type ScrollSurfaceBaselineAbsence =
+  | 'stored-surface-unusable'
+  | 'stored-surface-not-current'
+  | 'prior-gesture-unsettled';
+
+/** Why this command owes no observation of its own effect. A reason, never text to match. */
+export type ScrollMovementInapplicability =
+  | 'owner-without-capture'
+  | 'non-swipe-platform'
+  | 'caller-declined-observation'
+  | 'settle-observer-owns-outcome';
+
+/**
+ * Everything about this scroll's observation that is knowable before it dispatches, decided once, in
+ * one place: whether the command owes the read at all, and what it gets to compare against.
+ *
+ * The declines are the device's and the caller's — a platform that moves content with a wheel or a JS
+ * step instead of a synthesized swipe, a caller that pays for its own observation (Maestro's replay
+ * loop), and `--settle`, which freezes its own baseline and already answers whether the surface
+ * moved. Whether the bound runtime can read a screen at all is the one fact not knowable here, since
+ * binding happens after this returns; that owner reports its own `owner-without-capture`.
+ */
+export type ScrollMovementPlan =
+  | Readonly<{
+      kind: 'declined';
+      reason: Exclude<ScrollMovementInapplicability, 'owner-without-capture'>;
+    }>
+  | Readonly<{ kind: 'unobservable'; reason: ScrollSurfaceBaselineAbsence }>
+  | Readonly<{ kind: 'observe'; baseline: ScrollSurfaceBaseline }>;
+
+export function planScrollMovement(params: {
+  device: DeviceInfo;
+  flags: CommandFlags | undefined;
+  session: SessionState;
+}): ScrollMovementPlan {
+  if (!isMobilePlatform(params.device)) return { kind: 'declined', reason: 'non-swipe-platform' };
+  if (params.flags?.postGestureStabilization === false) {
+    return { kind: 'declined', reason: 'caller-declined-observation' };
+  }
+  if (params.flags?.settle === true) {
+    return { kind: 'declined', reason: 'settle-observer-owns-outcome' };
+  }
+  return freezeScrollSurfaceBaseline(params.session);
+}
+
+/** Where the swipe ran, so a container elsewhere on the screen cannot be blamed for the no-op. */
+export type ScrollSwipeEvidence = Readonly<{
+  /** Midpoint of the dispatched gesture, in the same space as a snapshot rect. */
+  midpoint?: Point;
+  /** The travel the gesture plan produced, reported on the refusal. */
+  pixels?: number;
+}>;
+
+export function readScrollSurfaceBaseline(
+  snapshot: SnapshotState | undefined,
+): ScrollSurfaceBaseline | undefined {
+  if (!snapshot || snapshot.nodes.length === 0) return undefined;
+  const signature = buildInteractionSurfaceSignature(snapshot.nodes);
+  if (signature.length === 0) return undefined;
+  return {
+    signature,
+    presentationKey: snapshot.presentationKey,
+    comparisonKey: snapshotSurfaceComparisonKey(snapshot),
+  };
+}
+
+/**
+ * Freezes what a directional scroll can compare its own effect against, at the one moment that
+ * answer is available: before the command dispatches.
+ *
+ * The tree the session stores is not automatically the screen as it stands — a mutation may have
+ * happened since it was captured, and its own gesture is about to be another one. ADR 0014 already
+ * encodes exactly that question: the ref frame stays `active` while no device side effect has
+ * crossed since the last publication, which is while the stored tree still is the newest
+ * observation. Anything else and there is nothing honest to compare against, so this names the reason
+ * instead of letting a stale tree back a movement claim (#2714).
+ */
+function freezeScrollSurfaceBaseline(session: SessionState): ScrollMovementPlan {
+  const baseline = readScrollSurfaceBaseline(session.snapshot);
+  if (!baseline) return { kind: 'unobservable', reason: 'stored-surface-unusable' };
+  if (refFrameState(session) !== 'active') {
+    return { kind: 'unobservable', reason: 'stored-surface-not-current' };
+  }
+  if (isPostGestureStabilizationPending(session)) {
+    // A gesture nobody has read yet may still be moving this tree, which would bill its motion to
+    // the scroll being dispatched now.
+    return { kind: 'unobservable', reason: 'prior-gesture-unsettled' };
+  }
+  return { kind: 'observe', baseline };
+}
+
+/**
+ * Observes one directional scroll and returns the movement its response may claim.
+ *
+ * Throws `scroll_no_progress` when it proves the gesture did not land: the surface is byte-for-byte
+ * what it was, the tree still names hidden content in the direction that was scrolled, and the swipe
+ * ran inside that container. Every other untouched surface answers honestly instead — at the edge of
+ * the content, in a direction with no end-of-content signal, or as `unobserved` when the evidence
+ * would not support the claim either way.
+ *
+ * A capture that fails does not fail the scroll: the gesture already happened, so an unreadable tree
+ * answers `unobserved` and leaves the caller's scroll succeeded.
+ */
+export async function observeScrollMovement(params: {
+  direction: ScrollDirection;
+  baseline: ScrollSurfaceBaseline;
+  swipe: ScrollSwipeEvidence;
+  capture: () => Promise<SnapshotResult>;
+  /** The same two overrides `pollForScrollRest` takes: how long to ask, and how often. */
+  budgetMs?: number;
+  pollMs?: number;
+}): Promise<ScrollMovementObservation> {
+  const { direction, baseline, swipe } = params;
+  const verdict = await pollForSurfaceVerdict(baseline, params);
+  switch (verdict.kind) {
+    case 'moved':
+      return await claimMoved({ ...verdict, direction, baseline, swipe });
+    case 'blind':
+      return reportScrollMovementUnobserved(direction, verdict.reason, { swipe });
+    case 'settled':
+      return await decideUnchanged({ ...verdict, direction, baseline, swipe });
+  }
+}
+
+/** What the polling could say about the surface, before any of it is interpreted. */
+type SurfaceVerdict =
+  | Readonly<{
+      kind: 'moved';
+      observed: ObservedSurface;
+      attempts: number;
+      startedAt: number;
+    }>
+  | Readonly<{ kind: 'blind'; reason: SurfaceBlindReason }>
+  | Readonly<{
+      kind: 'settled';
+      observed: ObservedSurface;
+      evidence: InteractionSurfaceChange;
+      attempts: number;
+      startedAt: number;
+    }>;
+
+/** Why this capture cannot be compared against the pre-gesture tree at all, movement included. */
+type SurfaceBlindReason = 'capture-unreadable' | 'surface-unsettled' | ScrollSurfacePairDrift;
+
+/**
+ * Whether two captures describe one screen. Capture backends do not agree on which nodes exist, so a
+ * pair across a lineage change — the XCTest-channel fallback swapping the producer mid-request
+ * (#1569) — or across the interactive-only difference `snapshot -i` stores says nothing about
+ * movement in either direction, however different the two trees look.
+ */
+type ScrollSurfacePairDrift = 'baseline-presentation-drift' | 'capture-lineage-drift';
+
+function surfacePairDrift(
+  baseline: ScrollSurfaceBaseline,
+  observed: ObservedSurface,
+): ScrollSurfacePairDrift | undefined {
+  if (baseline.presentationKey !== observed.presentationKey) return 'baseline-presentation-drift';
+  if (baseline.comparisonKey !== observed.comparisonKey) return 'capture-lineage-drift';
+  return undefined;
+}
+
+/**
+ * Polls until an untouched surface proves itself. A surface that differs from the baseline is a
+ * verdict on the first capture, so a scroll that worked pays for one read. One that looks untouched
+ * needs a quiet pair, because a gesture still in flight and a gesture that did nothing answer a
+ * single read identically. A surface that never holds still expires as `surface-unsettled` rather
+ * than being called a no-op — and that answer is worth a warning the others are not, since it spent
+ * the whole budget confirming nothing.
+ */
+async function pollForSurfaceVerdict(
+  baseline: ScrollSurfaceBaseline,
+  params: {
+    direction: ScrollDirection;
+    capture: () => Promise<SnapshotResult>;
+    budgetMs?: number;
+    pollMs?: number;
+    swipe: ScrollSwipeEvidence;
+  },
+): Promise<SurfaceVerdict> {
+  const startedAt = Date.now();
+  const deadline = startedAt + (params.budgetMs ?? MOVEMENT_VERDICT_BUDGET_MS);
+  let previous: InteractionSurfaceSignature | undefined;
+  let attempts = 0;
+
+  while (true) {
+    const reading = await readOneCapture(baseline, params.capture);
+    attempts += 1;
+    if (reading.kind === 'blind') return { kind: 'blind', reason: reading.reason };
+    if (reading.kind === 'changed')
+      return { kind: 'moved', observed: reading.observed, attempts, startedAt };
+    if (surfaceIsAtRest(previous, reading.observed.signature)) {
+      return {
+        kind: 'settled',
+        observed: reading.observed,
+        evidence: reading.evidence,
+        attempts,
+        startedAt,
+      };
+    }
+    if (Date.now() >= deadline) return budgetExpiredVerdict(params, attempts, startedAt);
+    previous = reading.observed.signature;
+    await sleep(params.pollMs ?? MOVEMENT_POLL_MS);
+  }
+}
+
+/**
+ * What a single capture says, on its own: nothing at all when the tree could not be read or comes from
+ * another lineage, movement when the surface differs from the baseline, and otherwise the untouched
+ * pair the loop has to prove is at rest before it can be reported.
+ */
+type CaptureReading =
+  | Readonly<{ kind: 'blind'; reason: SurfaceBlindReason }>
+  | Readonly<{ kind: 'changed'; observed: ObservedSurface }>
+  | Readonly<{ kind: 'unchanged'; observed: ObservedSurface; evidence: InteractionSurfaceChange }>;
+
+async function readOneCapture(
+  baseline: ScrollSurfaceBaseline,
+  capture: () => Promise<SnapshotResult>,
+): Promise<CaptureReading> {
+  const observed = await captureSurface(capture);
+  if (!observed) return { kind: 'blind', reason: 'capture-unreadable' };
+  const drift = surfacePairDrift(baseline, observed);
+  if (drift) return { kind: 'blind', reason: drift };
+  const evidence = classifyBaselineSurfaceEvidence(baseline.signature, observed.signature);
+  if (evidence === 'changed') return { kind: 'changed', observed };
+  return { kind: 'unchanged', observed, evidence };
+}
+
+/**
+ * The surface never held still, so this command spent its whole budget confirming nothing. That answer
+ * is worth a warning the others are not: it is also the one that cost the caller the most.
+ */
+function budgetExpiredVerdict(
+  params: {
+    direction: ScrollDirection;
+    swipe: ScrollSwipeEvidence;
+  },
+  attempts: number,
+  startedAt: number,
+): SurfaceVerdict {
+  emitDiagnostic({
+    level: 'warn',
+    phase: 'scroll_movement_budget_expired',
+    data: {
+      direction: params.direction,
+      attempts,
+      durationMs: Date.now() - startedAt,
+      ...(params.swipe.pixels === undefined ? {} : { requestedPixels: params.swipe.pixels }),
+    },
+  });
+  return { kind: 'blind', reason: 'surface-unsettled' };
+}
+
+function surfaceIsAtRest(
+  previous: InteractionSurfaceSignature | undefined,
+  next: InteractionSurfaceSignature,
+): boolean {
+  return previous !== undefined && areInteractionSurfaceSignaturesStable(previous, next);
+}
+
+type ObservedSurface = Readonly<{
+  signature: InteractionSurfaceSignature;
+  presentationKey: string | undefined;
+  comparisonKey: string | undefined;
+  /** The tree itself: the edge question is asked of nodes, not of the identity signature. */
+  nodes: SnapshotState['nodes'];
+}>;
+
+async function captureSurface(
+  capture: () => Promise<SnapshotResult>,
+): Promise<ObservedSurface | undefined> {
+  let result: SnapshotResult;
+  try {
+    result = await capture();
+  } catch {
+    // The gesture is already done; a tree this command cannot read withholds the claim, it does not
+    // undo the scroll.
+    return undefined;
+  }
+  const state = buildSnapshotState(result, undefined);
+  return {
+    signature: buildInteractionSurfaceSignature(state.nodes),
+    presentationKey: state.presentationKey,
+    comparisonKey: snapshotSurfaceComparisonKey(state),
+    nodes: state.nodes,
+  };
+}
+
+/**
+ * A changed surface credits the gesture only when the change sits inside the scroller the swipe ran
+ * in. The captured tree carries system chrome along with the app's content, and on Android the status
+ * bar clocks and icons change on their own while a frozen list sits underneath them — measured on the
+ * tester's `/catalog`, a battery icon alone turned the pair into "changed" over a list that never
+ * moved. Without a container to confine the claim to (no scroller resolved, or the horizontal axis the
+ * analyzer does not read) the whole-surface difference is all there is, and stays the answer.
+ */
+async function claimMoved(params: {
+  direction: ScrollDirection;
+  baseline: ScrollSurfaceBaseline;
+  swipe: ScrollSwipeEvidence;
+  observed: ObservedSurface;
+  attempts: number;
+  startedAt: number;
+}): Promise<ScrollMovementObservation> {
+  const { direction, baseline, swipe, observed } = params;
+  const edge = verticalEdgeFor(direction);
+  const containerRect = edge
+    ? (await readScrollEdgeState(observed.nodes, edge)).containerRect
+    : undefined;
+  if (
+    containerRect &&
+    !discriminatingSurfaceChangedWithinRect(baseline.signature, observed.signature, containerRect)
+  ) {
+    return reportScrollMovementUnobserved(direction, 'change-outside-container', {
+      swipe,
+      containerRect,
+    });
+  }
+  return reportObserved(direction, 'moved', swipe, params.attempts, params.startedAt);
+}
+
+async function decideUnchanged(params: {
+  direction: ScrollDirection;
+  baseline: ScrollSurfaceBaseline;
+  swipe: ScrollSwipeEvidence;
+  observed: ObservedSurface;
+  evidence: InteractionSurfaceChange;
+  attempts: number;
+  startedAt: number;
+}): Promise<ScrollMovementObservation> {
+  const { direction, baseline, observed, evidence, swipe } = params;
+  const comparison = settledPairBlindness(baseline, observed, evidence);
+  if (comparison)
+    return reportScrollMovementUnobserved(direction, comparison.reason, {
+      swipe,
+      divergence: comparison.divergence,
+    });
+  return await decideEdgeVerdict(params);
+}
+
+type SurfaceComparison = Readonly<{
+  reason: 'no-comparable-content' | 'surface-divergence';
+  divergence?: Record<string, unknown>;
+}>;
+
+/**
+ * What a pair already known comparable still cannot say about being untouched. The subset-tolerant
+ * classifier is 'unchanged' for a narrower capture of the same screen, so the no-effect claim needs
+ * the strict both-directions bar (#1601 review P1): a scroll that replaced every list cell under
+ * fixed chrome must not be readable as a gesture that did nothing.
+ */
+function settledPairBlindness(
+  baseline: ScrollSurfaceBaseline,
+  observed: ObservedSurface,
+  evidence: InteractionSurfaceChange,
+): SurfaceComparison | undefined {
+  if (evidence === 'ambiguous') return { reason: 'no-comparable-content' };
+  if (!haveIdenticalDiscriminatingSurfaces(baseline.signature, observed.signature)) {
+    return {
+      reason: 'surface-divergence',
+      divergence: summarizeDiscriminatingSurfaceDivergence(baseline.signature, observed.signature),
+    };
+  }
+  return undefined;
+}
+
+/** What an untouched surface is: the end of the content, a direction with no edge to read, or a gesture that never landed. */
+async function decideEdgeVerdict(params: {
+  direction: ScrollDirection;
+  swipe: ScrollSwipeEvidence;
+  observed: ObservedSurface;
+  attempts: number;
+  startedAt: number;
+}): Promise<ScrollMovementObservation> {
+  const { direction, observed, swipe } = params;
+  const edge = verticalEdgeFor(direction);
+  if (!edge) {
+    // The hidden-content analyzer reads the vertical axis only, so a horizontal scroll that moved
+    // nothing cannot tell a pager at its end from a list that ignored the swipe. It reports what it
+    // measured and leaves the two apart, rather than guessing.
+    return reportObserved(direction, 'unchanged', swipe, params.attempts, params.startedAt);
+  }
+
+  const edgeState = await readScrollEdgeState(observed.nodes, edge);
+  const containerRect = edgeState.containerRect;
+  if (!containerRect) {
+    // `canScroll: false` here means the tree named no scroll container at all, which says nothing
+    // about where the content ends.
+    return reportScrollMovementUnobserved(direction, 'no-scroll-container', { swipe });
+  }
+  if (swipe.midpoint && !containerHoldsSwipe(containerRect, swipe.midpoint)) {
+    return reportScrollMovementUnobserved(direction, 'container-outside-swipe', {
+      swipe,
+      containerRect,
+    });
+  }
+  if (edgeState.canScroll) {
+    throw scrollNoProgressError(direction, edge, swipe, containerRect);
+  }
+  return reportObserved(direction, 'at-edge', swipe, params.attempts, params.startedAt);
+}
+
+function containerHoldsSwipe(containerRect: Rect, midpoint: Point): boolean {
+  return containsPoint(containerRect, midpoint.x, midpoint.y);
+}
+
+/**
+ * The gesture did not reach the container: hidden content is still there, and the surface never
+ * moved. Same typed family as `scroll_edge_no_progress` and `scroll_until_no_progress`, and the same
+ * hint, because the caller's next move is the same whichever loop noticed.
+ */
+function scrollNoProgressError(
+  direction: ScrollDirection,
+  edge: ScrollEdge,
+  swipe: ScrollSwipeEvidence,
+  containerRect: Rect,
+): AppError {
+  return new AppError(
+    'COMMAND_FAILED',
+    `scroll ${direction} moved nothing: the container still reports hidden content ${
+      edge === 'bottom' ? 'below' : 'above'
+    } and its contents never shifted`,
+    {
+      reason: 'scroll_no_progress',
+      direction,
+      hiddenContentAt: edge,
+      containerRect,
+      ...(swipe.pixels === undefined ? {} : { requestedPixels: swipe.pixels }),
+      hint: scrollNoProgressHint({
+        targetDirectly: `with scroll ${direction} --until <selector>`,
+        rawDrag: swipe.midpoint !== undefined,
+      }),
+    },
+  );
+}
+
+/**
+ * Why a scroll that owed an observation could not make one: no usable baseline before the gesture, no
+ * readable or settled tree after it, or a pair that turned out not to be comparable. A reason, never
+ * text a caller has to match.
+ */
+export type ScrollMovementUnobservedReason =
+  | ScrollSurfaceBaselineAbsence
+  | SurfaceBlindReason
+  | 'no-comparable-content'
+  | 'surface-divergence'
+  | 'no-scroll-container'
+  | 'container-outside-swipe'
+  | 'change-outside-container';
+
+/** What accompanies the reason in the daemon log, so one line explains the whole verdict. */
+export type ScrollMovementUnobservedEvidence = Readonly<{
+  swipe: ScrollSwipeEvidence;
+  /** What the two surfaces disagreed on, for a `surface-divergence`. */
+  divergence?: Record<string, unknown>;
+  /** The scroll container the edge analyzer resolved, when it resolved one. */
+  containerRect?: Rect;
+}>;
+
+/**
+ * Tells the daemon log that this command owed no observation at all — the owner cannot read a
+ * screen, the device has no swipe to verify, or the caller (or another observer) already declined
+ * or owns that read. The response carries no `movement` field, so the reason has to live somewhere.
+ */
+export function reportScrollMovementNotApplicable(
+  direction: ScrollDirection,
+  reason: ScrollMovementInapplicability,
+): void {
+  emitDiagnostic({
+    level: 'debug',
+    phase: 'scroll_movement_not_applicable',
+    data: { direction, reason },
+  });
+}
+
+/**
+ * Records why a scroll that DID owe an observation could not make one, and answers `unobserved`: the
+ * distance it reports then rests on the gesture plan alone.
+ */
+export function reportScrollMovementUnobserved(
+  direction: ScrollDirection,
+  reason: ScrollMovementUnobservedReason,
+  evidence: ScrollMovementUnobservedEvidence,
+): ScrollMovementObservation {
+  emitDiagnostic({
+    level: 'info',
+    phase: 'scroll_movement_unobserved',
+    data: {
+      direction,
+      reason,
+      ...(evidence.swipe.pixels === undefined ? {} : { requestedPixels: evidence.swipe.pixels }),
+      ...(evidence.divergence ?? {}),
+      ...(evidence.containerRect === undefined ? {} : { containerRect: evidence.containerRect }),
+    },
+  });
+  return 'unobserved';
+}
+
+function reportObserved(
+  direction: ScrollDirection,
+  movement: Exclude<ScrollMovementObservation, 'unobserved'>,
+  swipe: ScrollSwipeEvidence,
+  attempts: number,
+  startedAt: number,
+): ScrollMovementObservation {
+  emitDiagnostic({
+    level: movement === 'moved' ? 'debug' : 'info',
+    phase: 'scroll_movement_observed',
+    data: {
+      direction,
+      movement,
+      attempts,
+      durationMs: Date.now() - startedAt,
+      ...(swipe.pixels === undefined ? {} : { requestedPixels: swipe.pixels }),
+    },
+  });
+  return movement;
+}

From 4bad7844f904cc42521a41dc64bcdbf7de5d5567 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Wed, 23 Sep 2026 16:19:14 +0200
Subject: [PATCH 047/132] fix(scroll): answer with the movement a directional
 scroll observed (#2771)

---
 .../src/platform-runtime-operations.ts        |  18 +-
 src/daemon/__tests__/scroll-runtime.test.ts   | 289 +++++++++++++++++-
 src/daemon/generic-runtime-execution.ts       |   5 +
 src/daemon/scroll-runtime.ts                  | 156 ++++++++--
 4 files changed, 427 insertions(+), 41 deletions(-)

diff --git a/packages/contracts/src/platform-runtime-operations.ts b/packages/contracts/src/platform-runtime-operations.ts
index 8ca18eabcc..3d6981294d 100644
--- a/packages/contracts/src/platform-runtime-operations.ts
+++ b/packages/contracts/src/platform-runtime-operations.ts
@@ -250,8 +250,22 @@ const gestureTargetAuthoredDragUse = defineUse({
  */
 export const gestureViewportRuntimeUse = defineUse({ required: ['gestureViewport'] });
 
-/** `scroll <direction>` executes one pass and needs nothing else. */
-const scrollDirectionUse = defineUse({ required: ['scrollDirection'] });
+/**
+ * `scroll <direction>` executes one pass, and the capture that lets it answer with the movement it
+ * observed (#2714) is CONDITIONAL — not `preferred`, not `required` (ADR 0019 §2). Not preferred:
+ * the observation is what makes the direction tier's answer honest, which is correctness rather
+ * than a faster path, and §2 reserves `preferred` for optimizations that never carry correctness.
+ * Not required: a runtime that cannot read a screen still scrolls, and `movement: 'unobserved'` —
+ * or no movement field at all — is the answer it owes.
+ *
+ * Both sides are complete. An owner that can capture answers with the movement it saw; an owner that
+ * cannot answers exactly the response it answered before, distance and all. `scroll-runtime.test.ts`
+ * pins one case per side of that parity.
+ */
+const scrollDirectionUse = defineUse({
+  required: ['scrollDirection'],
+  conditional: ['captureSnapshot'],
+});
 /**
  * Every scroll that verifies between passes: `scroll top`/`scroll bottom` read hidden content at
  * the edge, and `scroll --until <selector>` re-reads the tree to decide whether the target came
diff --git a/src/daemon/__tests__/scroll-runtime.test.ts b/src/daemon/__tests__/scroll-runtime.test.ts
index be7e1e63c2..121ebcd45e 100644
--- a/src/daemon/__tests__/scroll-runtime.test.ts
+++ b/src/daemon/__tests__/scroll-runtime.test.ts
@@ -1,6 +1,12 @@
 import { expect, expectTypeOf, test } from 'vitest';
 import assert from 'node:assert/strict';
+import { buildSnapshotState } from '@agent-device/capture-kit/snapshot-state';
 import { AppError } from '@agent-device/kernel/errors';
+import type { CommandFlags } from '@agent-device/contracts/command';
+import type { DaemonRequest } from '../daemon-request.ts';
+import type { SessionState } from '../session-state.ts';
+import type { GenericPlatformExecutionParams } from '../request-generic-dispatch.ts';
+import type { SnapshotNode } from '@agent-device/kernel/snapshot';
 import type { BoundDeviceRuntime, RuntimeFacts } from '@agent-device/contracts/platform-runtime';
 import {
   type PlatformRuntimeOperations,
@@ -12,6 +18,8 @@ import { resolveBoundScrollRuntime } from '../scroll-runtime.ts';
 import type { BindDeviceRuntime, InspectDeviceRuntimeFacts } from '../request-runtime-binding.ts';
 import { unavailableDeploymentSnapshotAndShutdownOperationFacts } from '../../__tests__/test-utils/runtime-operation-facts.ts';
 import { IOS_SIMULATOR } from '../../__tests__/test-utils/device-fixtures.ts';
+import { makeIosSession, makeMacOsSession } from '../../__tests__/test-utils/session-factories.ts';
+import { activateCompleteRefFrame, expireRefFrame } from '../ref-frame.ts';
 
 /**
  * The retired `handleScrollCommand` suite, re-pointed at the bound runtime (R43). Every
@@ -25,7 +33,10 @@ type ScrollCall = { direction: string; options: unknown };
 
 function bindings(options: {
   scroll: (direction: string, scrollOptions: unknown) => Promise<Record<string, unknown> | void>;
-  captureSnapshot?: (input: { options?: { scope?: string } }) => Promise<unknown>;
+  captureSnapshot?: (input: {
+    options?: Record<string, unknown>;
+    execution?: unknown;
+  }) => Promise<unknown>;
 }): { inspectFacts: InspectDeviceRuntimeFacts; bindDevice: BindDeviceRuntime } {
   const available = { available: true } as const;
   const facts = {
@@ -54,20 +65,62 @@ async function runScroll(
   positionals: string[],
   context: Partial<DaemonCommandContext>,
   options: Parameters<typeof bindings>[0],
+  dispatch?: {
+    session?: SessionState;
+    flags?: CommandFlags;
+  },
 ): Promise<Record<string, unknown>> {
+  const session = dispatch?.session ?? makeIosSession('scroll-runtime');
+  const request: DaemonRequest =
+    dispatch?.flags === undefined
+      ? { command: 'scroll', session: session.name, token: 'test-token', positionals }
+      : {
+          command: 'scroll',
+          session: session.name,
+          token: 'test-token',
+          positionals,
+          flags: dispatch.flags,
+        };
   const resolved = await resolveBoundScrollRuntime({
-    device: IOS_SIMULATOR,
+    device: session.device,
     positionals,
     context: context as DaemonCommandContext,
+    session,
+    flags: dispatch?.flags,
     ...bindings(options),
   });
   if (!resolved.ok) throw new AppError('UNSUPPORTED_OPERATION', 'admission refused the scroll');
-  const data = await resolved.execute({
+  // The dispatcher expires the ref frame at its side-effect seam between resolution and execution
+  // (ADR 0014). Running the same transition here keeps a test honest about WHICH of the two moments
+  // a scroll's own evidence has to be read at.
+  expireRefFrame(session);
+  const params: GenericPlatformExecutionParams = {
+    session,
+    sessionName: session.name,
+    logPath: '/tmp/agent-device-scroll-runtime-test.log',
+    command: 'scroll',
+    request,
+    positionals,
+    out: undefined,
     dispatchContext: context as DaemonCommandContext,
-  } as Parameters<typeof resolved.execute>[0]);
+  };
+  const data = await resolved.execute(params);
   return (data ?? {}) as Record<string, unknown>;
 }
 
+/** A session whose stored tree IS the newest observation — what a `snapshot` leaves behind. */
+function sessionWithStoredScreen(
+  nodes: SnapshotNode[],
+  overrides?: Partial<SessionState>,
+): SessionState {
+  const session = makeIosSession('scroll-runtime', {
+    snapshot: buildSnapshotState({ nodes, backend: 'xctest', producer: 'apple-runner' }, undefined),
+    ...overrides,
+  });
+  activateCompleteRefFrame(session);
+  return session;
+}
+
 test('bound scroll rejects mixing amount and --pixels', async () => {
   await assert.rejects(
     () =>
@@ -150,8 +203,10 @@ test('bound scroll bottom refuses at admission when the owner declares no captur
   const calls: ScrollCall[] = [];
   const resolved = await resolveBoundScrollRuntime({
     device: IOS_SIMULATOR,
+    session: makeIosSession('scroll-runtime'),
     positionals: ['bottom'],
     context: {} as DaemonCommandContext,
+    flags: undefined,
     ...bindings({
       scroll: async (direction, options) => {
         calls.push({ direction, options });
@@ -306,12 +361,16 @@ function makeScrollSnapshot(options: { hiddenBelow: boolean; message: string })
 
 /**
  * R53 type-level regression. The two scroll plans must project DIFFERENT bindings: an edge scroll
- * proves `captureSnapshot` statically, and an ordinary scroll must not be able to name it at all.
+ * proves `captureSnapshot` statically, and an ordinary scroll may hold one but can never require it.
  *
  * This is the property a runtime `if (!captureSnapshot) throw` guard silently gave up — the guard
  * type-checks against a widened binding, so the compiler stops enforcing what admission proved.
+ * #2714 made the direction plan's capture a declared PREFERENCE rather than a widening: the owner
+ * observes its own effect when the runtime can read the screen, and says `movement: 'unobserved'`
+ * when it cannot. `RequiredKeys` is what keeps that distinction honest — a direction use that ever
+ * grew a required capture stops type-checking here, and the owner would owe a refusal instead.
  */
-test('the edge plan proves its capture statically and the direction plan cannot expose one', () => {
+test('the edge plan proves its capture statically and the direction plan cannot require one', () => {
   const direction = resolveScrollRuntimePlan({});
   const edge = resolveScrollRuntimePlan({ edge: 'bottom' });
 
@@ -319,8 +378,12 @@ test('the edge plan proves its capture statically and the direction plan cannot
   expect(direction.kind).toBe('direction');
   expect(edge).toMatchObject({ kind: 'edge', edge: 'bottom' });
 
-  // Structural: the required sets differ, and only the edge use names the capture.
+  // Structural: the required sets differ, and only the edge use names the capture. The direction
+  // use names it CONDITIONALLY instead — the observation that makes its answer honest is
+  // correctness-bearing, which ADR 0019 §2 keeps out of `preferred`, while an owner with no capture
+  // still answers the way it answered before. Both sides of that parity are pinned below.
   expect([...direction.use.required]).toEqual(['scrollDirection']);
+  expect([...(direction.use.conditional ?? [])]).toEqual(['captureSnapshot']);
   expect([...edge.use.required]).toEqual(['scrollDirection', 'captureSnapshot']);
 
   type DirectionOperations = BoundDeviceRuntime<
@@ -337,8 +400,9 @@ test('the edge plan proves its capture statically and the direction plan cannot
   expectTypeOf<RequiredKeys<EdgeOperations>>().toEqualTypeOf<
     'scrollDirection' | 'captureSnapshot'
   >();
-  // The ordinary binding cannot even name a capture — absent, not merely optional.
-  expectTypeOf<keyof DirectionOperations>().toEqualTypeOf<'scrollDirection'>();
+  // The ordinary binding can name a capture but never promises one: the key is present, and
+  // optional, which is exactly the disclosure the `movement` field reports instead of a refusal.
+  expectTypeOf<keyof DirectionOperations>().toEqualTypeOf<'scrollDirection' | 'captureSnapshot'>();
   expectTypeOf<RequiredKeys<DirectionOperations>>().toEqualTypeOf<'scrollDirection'>();
 });
 
@@ -346,6 +410,7 @@ test('the edge plan proves its capture statically and the direction plan cannot
 function untilNodes(targetY: number, hiddenBelow: boolean) {
   return [
     {
+      ref: 'e1',
       index: 1,
       depth: 0,
       type: 'ScrollView',
@@ -411,9 +476,215 @@ test('bound scroll rejects --until on an edge direction before any device work',
 test('bound scroll --until is refused at admission when the owner declares no capture', async () => {
   const resolved = await resolveBoundScrollRuntime({
     device: IOS_SIMULATOR,
+    session: makeIosSession('scroll-runtime'),
     positionals: ['down'],
     context: { until: 'label=Email' } as DaemonCommandContext,
+    flags: undefined,
     ...bindings({ scroll: async () => ({}) }),
   });
   assert.equal(resolved.ok, false);
 });
+
+/**
+ * #2714: a directional scroll answers with the movement it OBSERVED, and refuses to spend a
+ * distance it did not earn. The observation math lives in `scroll-movement.test.ts`; these cases
+ * prove the claim reaches the command, and that it stays out of every path that was never entitled
+ * to read the screen — a runtime without a capture, a Maestro replay, a `--settle` caller, the macOS
+ * desktop — or that the evidence for it was never there.
+ */
+const SCREEN_CONTAINER = { x: 18, y: 178, width: 366, height: 662 };
+
+function automationScreen(rowOffset: number, hiddenBelow = true): SnapshotNode[] {
+  return [
+    {
+      ref: 'e1',
+      index: 1,
+      depth: 0,
+      type: 'ScrollView',
+      identifier: 'lab-list',
+      rect: SCREEN_CONTAINER,
+      ...(hiddenBelow ? { hiddenContentBelow: true } : {}),
+    },
+    {
+      ref: 'e2',
+      index: 2,
+      parentIndex: 1,
+      depth: 1,
+      type: 'StaticText',
+      label: 'Row one',
+      rect: { x: 24, y: 200 + rowOffset, width: 300, height: 20 },
+    },
+    {
+      ref: 'e3',
+      index: 3,
+      parentIndex: 1,
+      depth: 1,
+      type: 'StaticText',
+      label: 'Row two',
+      rect: { x: 24, y: 260 + rowOffset, width: 300, height: 20 },
+    },
+  ];
+}
+
+/** The swipe the platform reports back, whose midpoint sits inside the container above. */
+const OBSERVED_SWIPE = { x1: 201, y1: 600, x2: 201, y2: 250, pixels: 656, durationMs: 250 };
+
+function frozenCaptures(frames: SnapshotNode[][]) {
+  const queue = [...frames];
+  let calls = 0;
+  return {
+    calls: () => calls,
+    captureSnapshot: async () => {
+      const next = queue.shift();
+      if (next === undefined)
+        throw new Error('scroll observed more captures than the case provided');
+      calls += 1;
+      return { nodes: next, backend: 'xctest', producer: 'apple-runner' };
+    },
+  };
+}
+
+/**
+ * The scroll of a session that just captured this screen and has moved nothing since: the one
+ * situation in which the stored tree really is the pre-gesture surface.
+ */
+function scrollOverStoredScreen(options: {
+  frames: SnapshotNode[][];
+  baseline?: SnapshotNode[];
+  flags?: CommandFlags;
+  session?: SessionState;
+  positionals?: string[];
+}) {
+  const captures = frozenCaptures(options.frames);
+  const scroll = runScroll(
+    options.positionals ?? ['down', '0.75'],
+    {},
+    { ...captures, scroll: async () => ({ ...OBSERVED_SWIPE }) },
+    {
+      session: options.session ?? sessionWithStoredScreen(options.baseline ?? automationScreen(0)),
+      ...(options.flags === undefined ? {} : { flags: options.flags }),
+    },
+  );
+  return { scroll, captures };
+}
+
+test('bound scroll refuses the distance when the screen it read never moved', async () => {
+  const { scroll } = scrollOverStoredScreen({ frames: [automationScreen(0), automationScreen(0)] });
+
+  await assert.rejects(
+    () => scroll,
+    (error: unknown) =>
+      error instanceof AppError &&
+      error.details?.reason === 'scroll_no_progress' &&
+      error.details.direction === 'down' &&
+      error.details.hiddenContentAt === 'bottom',
+  );
+});
+
+test('bound scroll keeps its distance and says the surface moved when it did', async () => {
+  const { scroll, captures } = scrollOverStoredScreen({
+    frames: [automationScreen(-320)],
+  });
+  const result = await scroll;
+
+  assert.equal(result.movement, 'moved');
+  assert.match(String(result.message), /Scrolled down by 0\.75 of the viewport \(656px\)/);
+  assert.equal(captures.calls(), 1);
+});
+
+test('bound scroll stops claiming a movement its runtime cannot read', async () => {
+  const captures = frozenCaptures([automationScreen(0), automationScreen(0)]);
+  const result = await runScroll(
+    ['down', '0.75'],
+    {},
+    // The same case WITHOUT the capture: this runtime cannot read a screen, so the answer carries
+    // no movement claim at all rather than one it could not have made.
+    { scroll: async () => ({ ...OBSERVED_SWIPE }) },
+    { session: sessionWithStoredScreen(automationScreen(0)) },
+  );
+
+  assert.equal('movement' in result, false);
+  assert.equal(captures.calls(), 0);
+});
+
+test('bound scroll reads no screen for a Maestro replay that asked for no stabilization', async () => {
+  const { scroll, captures } = scrollOverStoredScreen({
+    frames: [automationScreen(0), automationScreen(0)],
+    flags: { postGestureStabilization: false },
+  });
+  const result = await scroll;
+
+  assert.equal('movement' in result, false);
+  assert.equal(captures.calls(), 0);
+});
+
+test('bound scroll spends no capture on a movement another observer already owns', async () => {
+  const { scroll, captures } = scrollOverStoredScreen({
+    frames: [automationScreen(0), automationScreen(0)],
+    flags: { settle: true },
+  });
+  const result = await scroll;
+
+  assert.equal('movement' in result, false);
+  assert.equal(captures.calls(), 0);
+});
+
+test('bound scroll on the macOS desktop reads no screen to confirm a scroll', async () => {
+  const captures = frozenCaptures([automationScreen(0), automationScreen(0)]);
+  const session = makeMacOsSession('scroll-desktop');
+  session.snapshot = buildSnapshotState(
+    { nodes: automationScreen(0), backend: 'xctest', producer: 'apple-runner' },
+    undefined,
+  );
+  activateCompleteRefFrame(session);
+
+  const result = await runScroll(
+    ['down', '0.75'],
+    {},
+    { ...captures, scroll: async () => ({ ...OBSERVED_SWIPE }) },
+    { session },
+  );
+
+  assert.equal('movement' in result, false);
+  assert.equal(captures.calls(), 0);
+});
+
+/**
+ * The pair to the refusal above, and the reason the refusal is allowed to exist: a tree that
+ * predates a device side effect says nothing about what THIS gesture did. The session's ref frame
+ * is the existing owner of that answer (ADR 0014), so a scroll after a mutation says it observed
+ * nothing rather than crediting the swipe with whatever the earlier command changed.
+ */
+test('bound scroll will not read movement off a tree that predates the last mutation', async () => {
+  const captures = frozenCaptures([automationScreen(-320)]);
+  const session = sessionWithStoredScreen(automationScreen(0));
+  // Whatever the previous command was, it crossed the side-effect seam before this scroll resolved.
+  expireRefFrame(session);
+
+  const result = await runScroll(
+    ['down', '0.75'],
+    {},
+    { ...captures, scroll: async () => ({ ...OBSERVED_SWIPE }) },
+    { session },
+  );
+
+  assert.equal(result.movement, 'unobserved');
+  assert.equal(captures.calls(), 0);
+});
+
+test('bound scroll will not bill an unread earlier gesture to the scroll it is dispatching', async () => {
+  const captures = frozenCaptures([automationScreen(-320)]);
+  const session = sessionWithStoredScreen(automationScreen(0), {
+    postGestureStabilization: { action: 'press', positionals: [], markedAt: Date.now() },
+  });
+
+  const result = await runScroll(
+    ['down', '0.75'],
+    {},
+    { ...captures, scroll: async () => ({ ...OBSERVED_SWIPE }) },
+    { session },
+  );
+
+  assert.equal(result.movement, 'unobserved');
+  assert.equal(captures.calls(), 0);
+});
diff --git a/src/daemon/generic-runtime-execution.ts b/src/daemon/generic-runtime-execution.ts
index c0b631b467..cdd440102f 100644
--- a/src/daemon/generic-runtime-execution.ts
+++ b/src/daemon/generic-runtime-execution.ts
@@ -55,6 +55,11 @@ export async function resolveGenericRuntimeExecution(
         device: params.session.device,
         positionals: params.req.positionals ?? [],
         context: params.context,
+        // The scroll's own observation is decided here rather than in its execution closure: this is
+        // the last moment the session's stored tree is still the newest observation, before the
+        // dispatcher's ADR 0014 side-effect seam.
+        session: params.session,
+        flags: params.req.flags,
         inspectFacts: params.inspectFacts,
         bindDevice: params.bindDevice,
       });
diff --git a/src/daemon/scroll-runtime.ts b/src/daemon/scroll-runtime.ts
index 601df69497..9645097f73 100644
--- a/src/daemon/scroll-runtime.ts
+++ b/src/daemon/scroll-runtime.ts
@@ -2,11 +2,13 @@ import {
   assertExclusiveScrollDistanceInputs,
   assertScrollUntilCompatible,
   honoredScrollDurationMs,
+  honoredScrollSwipeMidpoint,
   honoredScrollPixels,
   normalizeScrollDurationMs,
   resolveScrollExecutionOptions,
   type ResolvedScrollExecutionOptions,
   type ScrollCommandOptions,
+  type ScrollMovementObservation,
 } from '@agent-device/contracts/scroll-command';
 import { parseScrollDirection, type ScrollDirection } from '@agent-device/contracts/scroll-gesture';
 import {
@@ -28,11 +30,22 @@ import {
 } from '@agent-device/capture-kit/scroll-edge-state';
 import { formatScrollUntilMessage, runScrollUntilVisible } from './scroll-until.ts';
 import { publicPlatformString } from '@agent-device/kernel/device';
+import type { CommandFlags } from '@agent-device/contracts/command';
 import { withSuccessText } from '@agent-device/kernel/success-text';
 import type { DaemonCommandContext } from './context.ts';
+import type { SessionState } from './session-state.ts';
 import type { ResolvedGenericExecution } from './request-generic-dispatch.ts';
 import { resolveBoundGenericRuntime, type RuntimeAdmissionBindings } from './runtime-admission.ts';
+import {
+  observeScrollMovement,
+  planScrollMovement,
+  reportScrollMovementNotApplicable,
+  reportScrollMovementUnobserved,
+  type ScrollMovementPlan,
+  type ScrollSwipeEvidence,
+} from './scroll-movement.ts';
 import { runtimeExecutionFromContext } from './snapshot-runtime-capture-input.ts';
+import type { CaptureSnapshotInput } from '@agent-device/contracts/snapshot-runtime';
 import { errorResponse } from '@agent-device/kernel/contracts';
 
 type ScrollTarget = Readonly<{
@@ -83,6 +96,12 @@ export async function resolveBoundScrollRuntime(
     device: DeviceInfo;
     positionals: readonly string[];
     context: DaemonCommandContext;
+    /**
+     * The live session and the caller's flags, both read before the dispatcher's side-effect seam can
+     * expire the stored tree this command compares its own gesture against.
+     */
+    session: SessionState;
+    flags: CommandFlags | undefined;
   } & RuntimeAdmissionBindings,
 ): Promise<ResolvedGenericExecution> {
   const directionInput = params.positionals[0];
@@ -108,12 +127,21 @@ export async function resolveBoundScrollRuntime(
     bindDevice: params.bindDevice,
   };
   switch (plan.kind) {
-    case 'direction':
+    case 'direction': {
+      // Decided before the gesture, because this command's own scroll is what invalidates the tree it
+      // compares against: the dispatcher expires the session's ref frame at its ADR 0014 side-effect
+      // seam, and resolvers run before that seam. The same pre-effect freeze #1638's settle plan makes.
+      const movementPlan = planScrollMovement({
+        device: params.device,
+        flags: params.flags,
+        session: params.session,
+      });
       return await resolveBoundGenericRuntime(
         { ...admission, use: plan.use },
         async (runtime, dispatchContext) =>
-          await executeDirectionScroll(runtime, target, options, dispatchContext),
+          await executeDirectionScroll(runtime, target, options, dispatchContext, movementPlan),
       );
+    }
     case 'edge': {
       const edge = plan.edge;
       return await resolveBoundGenericRuntime(
@@ -171,19 +199,96 @@ function scrollCaptureUnsupported(subject: string, hint: string | undefined) {
   );
 }
 
-/** One pass. This binding carries no capture, so an edge-style read will not type-check here. */
+/**
+ * One pass, and the observation that decides whether this response may name a distance (#2714).
+ *
+ * The baseline is the tree the session already holds, so a scroll that works costs one capture and
+ * answers on it; only a surface that looks untouched keeps polling. Whether the read is owed at all was
+ * already answered at resolve time by `planScrollMovement`; the one fact left is whether this binding
+ * carries a capture.
+ */
 async function executeDirectionScroll(
   runtime: BoundScrollDirection,
   target: ScrollTarget,
   options: ResolvedScrollExecutionOptions,
   context: DaemonCommandContext,
+  movementPlan: ScrollMovementPlan,
 ): Promise<Record<string, unknown>> {
-  return scrollResult(
-    target,
-    options,
-    1,
-    (await scrollOnce(runtime, target, options, context)) ?? {},
+  const interactionResult = (await scrollOnce(runtime, target, options, context)) ?? {};
+  const movement = await directionalMovementClaim(
+    runtime,
+    target.direction,
+    context,
+    movementPlan,
+    interactionResult,
   );
+  return scrollResult(target, options, 1, interactionResult, movement);
+}
+
+/**
+ * The movement this response may claim, or `undefined` when this command owed no observation of its own
+ * effect at all. An absent `movement` field is a claim of its own, so every skip names a typed reason in
+ * the daemon log; a runtime bound without a capture answers that way rather than `unobserved`, which
+ * keeps its response exactly what it was before this observation existed.
+ */
+async function directionalMovementClaim(
+  runtime: BoundScrollDirection,
+  direction: ScrollDirection,
+  context: DaemonCommandContext,
+  movementPlan: ScrollMovementPlan,
+  interactionResult: Record<string, unknown>,
+): Promise<ScrollMovementObservation | undefined> {
+  if (movementPlan.kind === 'declined') {
+    reportScrollMovementNotApplicable(direction, movementPlan.reason);
+    return undefined;
+  }
+  const capture = runtime.operations.captureSnapshot;
+  if (!capture) {
+    reportScrollMovementNotApplicable(direction, 'owner-without-capture');
+    return undefined;
+  }
+  if (movementPlan.kind === 'unobservable') {
+    // The read was owed and the evidence was not there. The answer says so rather than resting the
+    // distance on a tree that predates something this command cannot see.
+    return reportScrollMovementUnobserved(direction, movementPlan.reason, {
+      swipe: swipeEvidence(interactionResult),
+    });
+  }
+  return await observeScrollMovement({
+    direction,
+    baseline: movementPlan.baseline,
+    swipe: swipeEvidence(interactionResult),
+    capture: async () => await capture(scrollCaptureInput(context)),
+  });
+}
+
+/**
+ * The capture intent every scroll read shares: the session's app and the request's execution metadata,
+ * and deliberately none of the caller's snapshot flags — a stop condition or a movement claim has to be
+ * decided on the tree the platform answers by default, so `snapshot -i` on the same request cannot
+ * change what this command reads.
+ */
+function scrollCaptureInput(
+  context: DaemonCommandContext,
+  scoped?: { scope: string | undefined },
+): CaptureSnapshotInput {
+  return {
+    options: {
+      ...(context.appBundleId === undefined ? {} : { appBundleId: context.appBundleId }),
+      ...scoped,
+    },
+    execution: runtimeExecutionFromContext(context),
+  };
+}
+
+/** What the leaf reported about the gesture it ran: where it ran, and how far it got. */
+function swipeEvidence(result: Record<string, unknown>): ScrollSwipeEvidence {
+  const midpoint = honoredScrollSwipeMidpoint(result);
+  const pixels = honoredScrollPixels(result);
+  return {
+    ...(midpoint === undefined ? {} : { midpoint }),
+    ...(pixels === undefined ? {} : { pixels }),
+  };
 }
 
 /** Repeats the pass while the verified state still moves; the capture needs no guard here. */
@@ -208,15 +313,8 @@ async function executeEdgeScroll(
     settleAfterPass: async () => {
       await pollForScrollRest(
         async () =>
-          (
-            await runtime.operations.captureSnapshot({
-              options: {
-                ...(context.appBundleId === undefined ? {} : { appBundleId: context.appBundleId }),
-                scope,
-              },
-              execution: runtimeExecutionFromContext(context),
-            })
-          ).nodes ?? [],
+          (await runtime.operations.captureSnapshot(scrollCaptureInput(context, { scope })))
+            .nodes ?? [],
         edge,
       );
     },
@@ -237,11 +335,7 @@ async function executeUntilScroll(
     selector,
     direction: target.direction,
     platform: publicPlatformString(device),
-    capture: async () =>
-      await runtime.operations.captureSnapshot({
-        options: context.appBundleId === undefined ? {} : { appBundleId: context.appBundleId },
-        execution: runtimeExecutionFromContext(context),
-      }),
+    capture: async () => await runtime.operations.captureSnapshot(scrollCaptureInput(context)),
     scroll: async () => await scrollOnce(runtime, target, options, context),
   });
   return withSuccessText(
@@ -268,13 +362,9 @@ async function captureEdgeState(
     scope,
     captureNodes: async (snapshotScope) =>
       (
-        await runtime.operations.captureSnapshot({
-          options: {
-            ...(context.appBundleId === undefined ? {} : { appBundleId: context.appBundleId }),
-            scope: snapshotScope,
-          },
-          execution: runtimeExecutionFromContext(context),
-        })
+        await runtime.operations.captureSnapshot(
+          scrollCaptureInput(context, { scope: snapshotScope }),
+        )
       ).nodes ?? [],
   });
 }
@@ -321,8 +411,10 @@ function scrollResult(
   options: ScrollCommandOptions,
   completedPasses: number,
   interactionResult: Record<string, unknown>,
+  movement?: ScrollMovementObservation,
 ): Record<string, unknown> {
   const durationMs = honoredScrollDurationMs(interactionResult);
+  const honoredPixels = honoredScrollPixels(interactionResult);
   return withSuccessText(
     {
       direction: target.direction,
@@ -331,6 +423,9 @@ function scrollResult(
       ...(options.pixels !== undefined ? { pixels: options.pixels } : {}),
       ...(durationMs !== undefined ? { durationMs } : {}),
       ...interactionResult,
+      // The observation is this command's own claim about its effect, so it is the one field the
+      // owner answers with rather than echoes from the platform leaf.
+      ...(movement === undefined ? {} : { movement }),
     },
     formatScrollEdgeMessage({
       direction: target.direction,
@@ -338,7 +433,8 @@ function scrollResult(
       passes: completedPasses,
       amount: options.amount,
       pixels: options.pixels,
-      honoredPixels: honoredScrollPixels(interactionResult),
+      honoredPixels,
+      ...(movement === undefined ? {} : { movement }),
     }),
   );
 }

From 913e2254517c2b499af66a830b8ddc882a11fc73 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Wed, 23 Sep 2026 16:19:14 +0200
Subject: [PATCH 048/132] docs(scroll): tell the caller what a scroll's
 movement field means (#2772)

---
 src/commands/interaction/metadata.ts | 2 +-
 src/mcp/command-output-schemas.ts    | 4 ++++
 website/docs/docs/commands.md        | 1 +
 3 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/src/commands/interaction/metadata.ts b/src/commands/interaction/metadata.ts
index f365052bcd..b497ceb4eb 100644
--- a/src/commands/interaction/metadata.ts
+++ b/src/commands/interaction/metadata.ts
@@ -68,7 +68,7 @@ const interactionCommandDescriptions = {
     'Move input focus to explicit screen coordinates without entering text. Prefer semantic interactions when a snapshot ref or selector is available; use type or fill after focus.',
   type: 'Append text to the currently focused input. Use fill when the existing field value should be replaced, and focus first when no input is active.',
   scroll:
-    'Scroll in a direction, or toward the top/bottom edge of scrollable content. Set until to a selector to reach an off-screen target in one command rather than a scroll-and-check loop. The optional amount is the finger-path fraction of the viewport axis, honored up to 0.8 of it; directional scrolls reduce release momentum, while app scroll physics determine the final content offset. A visible keyboard shortens the swiped band instead of being dismissed; when too little is left, the command refuses with scroll_keyboard_occludes_surface.',
+    'Scroll in a direction, or toward the top/bottom edge of scrollable content. Set until to a selector to reach an off-screen target in one command rather than a scroll-and-check loop. The optional amount is the finger-path fraction of the viewport axis, honored up to 0.8 of it; directional scrolls reduce release momentum, while app scroll physics determine the final content offset. A visible keyboard shortens the swiped band instead of being dismissed; when too little is left, the command refuses with scroll_keyboard_occludes_surface. A directional scroll also reports the movement it observed as movement: moved, at-edge, unchanged, or unobserved when the two reads could not back a claim either way; an unchanged surface inside a container that still hides content in that direction refuses with scroll_no_progress rather than repeating the requested distance. The movement field is absent where a tier verifies per pass (top/bottom, until), where the runtime cannot read a screen, or where a settle observation or a replay already owns that observation.',
   get: 'Read text or accessibility attributes from a snapshot ref or selector without changing the app. Use format text for visible content or attrs for the element attribute map.',
   is: 'Check whether a selector satisfies a UI predicate such as visible, hidden, exists, absent, editable, selected, focused, or text. `absent` passes only when one readable, complete, unscoped, full-depth accessibility capture has zero matches. Use wait when the condition may appear asynchronously.',
   find: 'Find by text/label/value/role/id and run action',
diff --git a/src/mcp/command-output-schemas.ts b/src/mcp/command-output-schemas.ts
index 1f64e203ed..d3b481ebfe 100644
--- a/src/mcp/command-output-schemas.ts
+++ b/src/mcp/command-output-schemas.ts
@@ -589,6 +589,10 @@ const BASE_COMMAND_OUTPUT_SCHEMAS = {
       keyboardMinY: numberSchema(
         'Where the keyboard began, in the same unit as the gesture coordinates. Clipped scrolls only.',
       ),
+      movement: enumSchema(
+        ['moved', 'at-edge', 'unchanged', 'unobserved'],
+        'Directional scrolls only: what the owner observed after its gesture. `moved` means the content inside the scroller the swipe ran in differs from the tree the session stored immediately before the gesture; `at-edge` and `unchanged` mean it did not change, with no hidden content left to reveal and with no end-of-content signal to read, respectively; `unobserved` means the pair could not back a claim in either direction — nothing comparable was available (no stored tree, a capture from another lineage, a surface that never came to rest), or every difference sits outside the scroller that was swiped, which a changing status bar does on Android — so the reported distance rests on the gesture plan alone. The field is absent — which is never a claim that nothing moved — on the tiers that verify per pass (`scroll top`/`bottom`, `--until`), on a runtime bound without a capture, on a platform whose scroll dispatches no swipe (the Linux wheel), and where the caller already owns that observation (`--settle`, or a replay with `postGestureStabilization: false`).',
+      ),
     },
     ['direction'],
   ),
diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md
index f398d74278..e0db3624b1 100644
--- a/website/docs/docs/commands.md
+++ b/website/docs/docs/commands.md
@@ -509,6 +509,7 @@ On iOS simulators it uses private XCTest synthesis for a continuous two-finger p
 On Android, `gesture transform` injects a geometric two-finger path. App recognizers may report non-exact pan, scale, and rotation values, so verify qualitative state such as `pan changed yes`, `pinch changed yes`, and `rotate changed yes` unless the app explicitly promises exact centroid metrics. If exact app-state values matter, prefer isolated `gesture pan`, `gesture pinch`, or `gesture rotate` commands.
 `scroll` accepts either a relative amount (`0.5` means a finger path spanning half of the viewport on that axis) or `--pixels <n>` for a fixed-distance gesture. Directional scrolls decelerate through the drag on Android to reduce release momentum within the requested duration; `scroll top` and `scroll bottom` retain inertial release for edge traversal. Reduced momentum does not guarantee an exact content offset, especially for very short gestures: apps apply pan-recognition thresholds, collapsing headers, bounds, and their own scroll physics. Large distances are clamped to the usable drag band so the gesture stays reliable across Android, iOS, and macOS.
 A directional scroll places its swipe across the middle of the viewport, so a focused field and its keyboard would put the swipe under the keys: the gesture would land on the keyboard, the surface would not move, and the scroll would read as stuck. On iOS and Android the scroll instead keeps the whole swipe in the band above the keyboard, reporting `keyboardAvoided` and `keyboardMinY` alongside a `referenceHeight` and `pixels` measured against that shorter band. It never dismisses the keyboard, because dismissing drops focus and breaks a `fill`/`scroll`/`fill` loop; run `keyboard dismiss` yourself when you want that. When the keyboard leaves too little room to swipe, the command refuses with the `scroll_keyboard_occludes_surface` reason rather than swiping into the keys, so a scroll that cannot work says so instead of appearing stuck.
+A directional scroll also reports what it *saw*, as `movement`, because the reported distance describes the swipe that was dispatched rather than content that moved. `moved` means the content inside the scroller the swipe ran in differs from the tree the session held immediately before the gesture. `at-edge` means it did not change and the resolved container reported no hidden content left in that direction, and `unchanged` is the same measurement in a direction that has no end-of-content signal to read. `unobserved` means the pair could not back a claim in either direction — no stored tree, a stored tree the session no longer stands behind or that was captured differently, a surface that never came to rest, or a difference sitting entirely outside the scroller that was swiped, which a changing Android status bar does — so the distance rests on the gesture plan alone, and it is answered honestly rather than dressed up as a confirmation. When the surface is provably unchanged while the container the gesture ran inside still reports hidden content in that direction, the command refuses with the `scroll_no_progress` reason instead of repeating the requested distance: the gesture never reached that list, and the hint names the three ways it usually goes missing (a focused keyboard, a nested scroller, a list that ignores synthesized scrolls and needs a raw `swipe`). A scroll on a runtime that cannot read a screen carries no `movement` field at all, and a Maestro replay or a `--settle` caller is not charged a second observation of a fact its own flags already own.
 Default snapshot text output is visible-first, so off-screen interactive content is summarized instead of shown as tappable refs.
 When a target only appears in an off-screen summary, use `scroll <direction> --settle`: the response waits for the UI to go quiet and returns the diff against the tree you last observed, with fresh refs on the added lines, so no follow-up `snapshot -i` is needed. `back --settle` does the same for navigation. Both are best-effort and never fail the action. For repeated checks without settle, a small shell loop is enough:
 

From 1f9f2bcfddf74d9d6a565043712c6faf3f515bfb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Wed, 23 Sep 2026 16:46:41 +0200
Subject: [PATCH 049/132] refactor(cli): drop the inert --device-hub option
 (#2821)

* refactor(cli): drop the inert --device-hub option

open --device-hub has had no effect since #1759: the Apple lifecycle never
read it and always surfaced the standalone Simulator app. Remove the flag,
the deviceHub contract fields, and the test-only readiness options
(deviceHub, focusExisting, onIosSimulatorColdBootStart) along with the Device
Hub branches in the simulator helper. With no readiness options left, the
admission requests carry readiness as a boolean.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* docs: remove open --device-hub from docs and ADR notes

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* refactor(daemon): pass readiness as a plain boolean and share simulator options

Address review findings: sessionless capture sites pass readiness: !session
instead of a conditional spread, the simulator helpers share one options
type, and the ADR and changelog say open surfaces Simulator after a cold
boot and name the retired config key.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* docs(test-app): drop the stale Device Hub requirement from the Duo lane note

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md                                  |   4 +
 ...01-provider-first-integration-scenarios.md |   2 +-
 docs/adr/0025-foldable-apple-panels.md        |   3 +-
 examples/test-app/README.md                   |   6 +-
 .../src/flag-definitions-target.ts            |   9 --
 .../src/application-lifecycle-runtime.ts      |   1 -
 packages/contracts/src/cli-flags.ts           |   1 -
 packages/contracts/src/client-app.ts          |   1 -
 packages/contracts/src/client-request.ts      |   1 -
 .../src/core/__tests__/simulator.test.ts      | 107 +-----------------
 packages/platform-apple/src/core/simulator.ts |  43 ++-----
 packages/platform-apple/src/lifecycle.test.ts |   1 -
 scripts/integration-progress-model.ts         |   1 -
 src/__tests__/client.test.ts                  |   2 -
 .../__tests__/args-parse-session.test.ts      |   9 --
 src/commands/command-flags.ts                 |   1 -
 src/commands/management/app.ts                |   3 -
 .../schema/cli-help-command-usage.test.ts     |   2 -
 .../__tests__/request-runtime-binding.test.ts |   7 +-
 .../snapshot-runtime-binding.test.ts          |   2 +-
 src/daemon/app-event-runtime.ts               |   3 +-
 .../device/__tests__/device-ready.test.ts     |  31 +----
 src/daemon/device/device-ready.ts             |  19 +---
 src/daemon/handlers/session-clipboard.ts      |   4 +-
 .../handlers/session-selector-dispatch.ts     |   5 +-
 src/daemon/handlers/snapshot-alert.ts         |   2 +-
 src/daemon/handlers/snapshot-settings.ts      |   4 +-
 src/daemon/keyboard-runtime.ts                |   3 +-
 src/daemon/request-runtime-binding.ts         |   9 +-
 src/daemon/runtime-admission.ts               |   7 +-
 src/daemon/selector-capture-binding.ts        |   2 +-
 .../internal/session-open-prepare.ts          |   1 -
 src/daemon/snapshot-runtime-binding.ts        |   9 +-
 src/platform-runtime-device-ready.ts          |  17 +--
 .../provider-scenarios/providers.ts           |   9 +-
 website/docs/docs/client-api.md               |   3 -
 website/docs/docs/commands.md                 |   1 -
 37 files changed, 55 insertions(+), 280 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 091d3c82af..1e9850d969 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -161,6 +161,10 @@
   as JPEG and the interactor wrote those bytes straight to the `.png` path, so every capture failed
   downstream with "Screenshot file is not a valid PNG". The bytes are now sniffed and a JPEG is
   transcoded to PNG before it is written; a PNG passes through unchanged.
+- Changed (ios): `open --device-hub`, the `deviceHub` option of `client.apps.open()`, and the
+  `deviceHub` config-file key are gone. The option has had no effect since 0.20.9: `open` surfaces
+  the standalone Simulator app after a cold boot either way. Each form is now handled like any
+  other unknown flag, option, or config key; drop it from scripts and `agent-device.json` (#2798).
 - Changed (ios): a regular `snapshot --depth N` on the XCTest runner is a presentation cut over a
   full acquisition, not a bound on the walk. Acquisition publishes the frames the platform reported,
   one normalization pass turns geometry into the app's orientation space and recomputes `hittable`,
diff --git a/docs/adr/0001-provider-first-integration-scenarios.md b/docs/adr/0001-provider-first-integration-scenarios.md
index 1d355df3f4..ab2f58666c 100644
--- a/docs/adr/0001-provider-first-integration-scenarios.md
+++ b/docs/adr/0001-provider-first-integration-scenarios.md
@@ -40,7 +40,7 @@ Request provider scoping is descriptor-driven inside the request router layer. A
 
 Synchronous host-tool calls are intentionally not part of the provider seam. Any remaining sync Apple helper is local-only and must be converted before a remote/cloud provider can own that path.
 
-Remaining generic Apple host-tool calls are intentionally local-only unless a new adapter creates pressure to promote them: perf process discovery/sampling (`mdfind`, `ps`), launch diagnostics (`plutil`, `otool`), local runner product build/signing (`swift`, `codesign`, sync `plutil`), local simulator UI launch (`open -a "Device Hub"` or `open -a Simulator`), plist compatibility fallbacks, and fallback implementations behind semantic macOS providers. Provider-backed integration scenarios should avoid scripting those host commands for user workflows; a user-facing workflow that depends on one of them is naming pressure for a semantic provider method.
+Remaining generic Apple host-tool calls are intentionally local-only unless a new adapter creates pressure to promote them: perf process discovery/sampling (`mdfind`, `ps`), launch diagnostics (`plutil`, `otool`), local runner product build/signing (`swift`, `codesign`, sync `plutil`), local simulator UI launch (`open -a Simulator`), plist compatibility fallbacks, and fallback implementations behind semantic macOS providers. Provider-backed integration scenarios should avoid scripting those host commands for user workflows; a user-facing workflow that depends on one of them is naming pressure for a semantic provider method.
 
 ## Alternatives Considered
 
diff --git a/docs/adr/0025-foldable-apple-panels.md b/docs/adr/0025-foldable-apple-panels.md
index 7735c2601b..8ab29aa07b 100644
--- a/docs/adr/0025-foldable-apple-panels.md
+++ b/docs/adr/0025-foldable-apple-panels.md
@@ -151,7 +151,8 @@ told, and every row is real content where a main-screen capture of the unlit pan
 The guest HID experiment supersedes the Device Hub pose decision and its private-API rejection
 below. UI discovery and sidebar sections, and their outstanding evidence gaps, are historical.
 `fold` now runs a small Objective-C helper through `simctl spawn <udid>` with no Device Hub or
-host Accessibility requirement. The optional `open --device-hub` UI choice remains independent.
+host Accessibility requirement. `open` surfaces the standalone Simulator app after a cold boot and
+has no Device Hub option.
 The helper serializes `{provider: "com.apple.Virtualization.VirtualMachines", source:
 "hinge-slider-control", type: "range", value: angle}` with IOCFSerialize and dispatches a vendor
 HID event (usage page 0xff61, usage 0x5b, version 0) inside the simulator. Requested angles are
diff --git a/examples/test-app/README.md b/examples/test-app/README.md
index 825b51ace9..9a85c2574a 100644
--- a/examples/test-app/README.md
+++ b/examples/test-app/README.md
@@ -341,6 +341,6 @@ across a pose change or mutation (a dropped session re-opens but never replays a
 failure artifacts, closes the session, and restores the starting pose.
 
 **Deferred GitHub Actions enablement (not a completion condition).** Wiring an automatic Duo job
-later requires, all at once: a Duo runtime/device type on the runner image, working Device Hub pose
-controls with Accessibility permission on the runner host, and one actual successful lane run — then
-re-check the runner-image inventories, which are dated, not permanent.
+later requires, all at once: a Duo runtime/device type on the runner image, an Xcode with foldable
+HID support, and one actual successful lane run — then re-check the runner-image inventories, which
+are dated, not permanent.
diff --git a/packages/command-registry/src/flag-definitions-target.ts b/packages/command-registry/src/flag-definitions-target.ts
index 1064317ff6..d84aa1cc0e 100644
--- a/packages/command-registry/src/flag-definitions-target.ts
+++ b/packages/command-registry/src/flag-definitions-target.ts
@@ -308,15 +308,6 @@ export const TARGET_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
     projectConfig: false,
     recorded: false,
   },
-  {
-    key: 'deviceHub',
-    names: ['--device-hub'],
-    type: 'boolean',
-    usageLabel: '--device-hub',
-    usageDescription: 'open: use Xcode Device Hub when surfacing Apple simulators',
-    projectConfig: true,
-    recorded: false,
-  },
   {
     key: 'testIme',
     names: ['--test-ime'],
diff --git a/packages/contracts/src/application-lifecycle-runtime.ts b/packages/contracts/src/application-lifecycle-runtime.ts
index 58304a5235..f13cb2347d 100644
--- a/packages/contracts/src/application-lifecycle-runtime.ts
+++ b/packages/contracts/src/application-lifecycle-runtime.ts
@@ -74,7 +74,6 @@ export type OpenApplicationPreparationInput = Readonly<{
   currentAppBundleId?: string;
   hasExistingSession: boolean;
   surface: SessionSurface;
-  deviceHub: boolean;
   prewarmRunnerOnColdBoot: boolean;
   execution: ApplicationLifecycleExecution;
 }>;
diff --git a/packages/contracts/src/cli-flags.ts b/packages/contracts/src/cli-flags.ts
index ea76cea5ae..8cd4412922 100644
--- a/packages/contracts/src/cli-flags.ts
+++ b/packages/contracts/src/cli-flags.ts
@@ -66,7 +66,6 @@ export type CliFlags = CloudProviderProfileFields &
     iosXctestrunFile?: string;
     iosXctestDerivedDataPath?: string;
     iosXctestEnvDir?: string;
-    deviceHub?: boolean;
     testIme?: boolean;
     androidDeviceAllowlist?: string;
     remote?: boolean;
diff --git a/packages/contracts/src/client-app.ts b/packages/contracts/src/client-app.ts
index c909ed3065..09bd9f698b 100644
--- a/packages/contracts/src/client-app.ts
+++ b/packages/contracts/src/client-app.ts
@@ -90,7 +90,6 @@ export type AppOpenOptions = AgentDeviceRequestOverrides &
     saveScript?: boolean | string;
     /** #1258: overwrite an existing --save-script target instead of refusing. Alias: --overwrite. */
     force?: boolean;
-    deviceHub?: boolean;
     testIme?: boolean;
     noRecord?: boolean;
     runtime?: SessionRuntimeHints;
diff --git a/packages/contracts/src/client-request.ts b/packages/contracts/src/client-request.ts
index 81f8b25321..c9b3f4e83c 100644
--- a/packages/contracts/src/client-request.ts
+++ b/packages/contracts/src/client-request.ts
@@ -73,7 +73,6 @@ export type InternalRequestOptions = AgentDeviceClientConfig &
     saveScript?: boolean | string;
     /** #1258: overwrite an existing --save-script target instead of refusing. Alias: --overwrite. */
     force?: boolean;
-    deviceHub?: boolean;
     testIme?: boolean;
     noRecord?: boolean;
     /** Fill-only script parameter name used to publish `${VAR}` instead of literal text. */
diff --git a/packages/platform-apple/src/core/__tests__/simulator.test.ts b/packages/platform-apple/src/core/__tests__/simulator.test.ts
index ea660f7370..0c0eb0ab90 100644
--- a/packages/platform-apple/src/core/__tests__/simulator.test.ts
+++ b/packages/platform-apple/src/core/__tests__/simulator.test.ts
@@ -57,7 +57,7 @@ beforeEach(() => {
   mockRunCmd.mockImplementation(execActual.runCmd);
 });
 
-test('ensureBootedSimulator opens Simulator after cold boot by default', async () => {
+test('ensureBootedSimulator opens Simulator after cold boot', async () => {
   mockRunCmdResponses({
     'xcrun simctl list devices -j': simulatorStateSequence('Shutdown', 'Booted'),
     'xcrun simctl boot sim-1': OK_RESULT,
@@ -65,7 +65,7 @@ test('ensureBootedSimulator opens Simulator after cold boot by default', async (
     'open -a Simulator': OK_RESULT,
   });
 
-  await ensureBootedSimulator(IOS_TEST_SIMULATOR, { focusExisting: true });
+  await ensureBootedSimulator(IOS_TEST_SIMULATOR);
 
   assert.equal(
     mockRunCmd.mock.calls.some(
@@ -75,25 +75,7 @@ test('ensureBootedSimulator opens Simulator after cold boot by default', async (
   );
 });
 
-test('ensureBootedSimulator runs cold boot callback only before cold boot', async () => {
-  const onColdBootStart = vi.fn();
-  mockRunCmdResponses({
-    'xcrun simctl list devices -j': simulatorStateSequence('Shutdown', 'Booted'),
-    'xcrun simctl boot sim-1': OK_RESULT,
-    'xcrun simctl bootstatus sim-1 -b': OK_RESULT,
-    'open -a Simulator': OK_RESULT,
-  });
-
-  await ensureBootedSimulator(IOS_TEST_SIMULATOR, {
-    focusExisting: true,
-    onColdBootStart,
-  });
-
-  assert.equal(onColdBootStart.mock.calls.length, 1);
-  assert.deepEqual(onColdBootStart.mock.calls[0], [IOS_TEST_SIMULATOR]);
-});
-
-test('openIosSimulatorApp opens Simulator by default', async () => {
+test('openIosSimulatorApp opens Simulator', async () => {
   mockRunCmdResponses({
     'open -a Simulator': OK_RESULT,
   });
@@ -106,93 +88,16 @@ test('openIosSimulatorApp opens Simulator by default', async () => {
   );
 });
 
-test('openIosSimulatorApp uses Device Hub when opted in and falls back to Simulator', async () => {
-  mockRunCmdResponses({
-    'open -a Device Hub': {
-      exitCode: 1,
-      stdout: '',
-      stderr: 'Unable to find application named Device Hub',
-    },
-    'open -a Simulator': OK_RESULT,
-  });
-
-  await openIosSimulatorApp({ deviceHub: true });
-
-  assert.deepEqual(
-    mockRunCmd.mock.calls.map(([cmd, args]) => [cmd, args.join(' ')]),
-    [
-      ['open', '-a Device Hub'],
-      ['open', '-a Simulator'],
-    ],
-  );
-});
-
-test('ensureBootedSimulator opens Simulator when already booted by default', async () => {
+test('ensureBootedSimulator leaves the Simulator app alone when already booted', async () => {
   mockRunCmdResponses({
     'xcrun simctl list devices -j': simulatorListDevicesResult('Booted'),
-    'open -a Simulator': OK_RESULT,
   });
 
-  await ensureBootedSimulator(IOS_TEST_SIMULATOR, { focusExisting: true });
+  await ensureBootedSimulator(IOS_TEST_SIMULATOR);
 
   assert.deepEqual(
     mockRunCmd.mock.calls.map(([cmd, args]) => [cmd, args.join(' ')]),
-    [
-      ['xcrun', 'simctl list devices -j'],
-      ['open', '-a Simulator'],
-    ],
-  );
-});
-
-test('ensureBootedSimulator skips cold boot callback when already booted', async () => {
-  const onColdBootStart = vi.fn();
-  mockRunCmdResponses({
-    'xcrun simctl list devices -j': simulatorListDevicesResult('Booted'),
-    'open -a Simulator': OK_RESULT,
-  });
-
-  await ensureBootedSimulator(IOS_TEST_SIMULATOR, { focusExisting: true, onColdBootStart });
-
-  assert.equal(onColdBootStart.mock.calls.length, 0);
-});
-
-test('ensureBootedSimulator opens Device Hub without activation when already booted and opted in', async () => {
-  mockRunCmdResponses({
-    'xcrun simctl list devices -j': simulatorListDevicesResult('Booted'),
-    'open -g -a Device Hub': OK_RESULT,
-  });
-
-  await ensureBootedSimulator(IOS_TEST_SIMULATOR, { deviceHub: true, focusExisting: true });
-
-  assert.equal(
-    mockRunCmd.mock.calls.some(
-      ([cmd, args]) => cmd === 'open' && args.join(' ') === '-g -a Device Hub',
-    ),
-    true,
-  );
-  assert.equal(
-    mockRunCmd.mock.calls.some(
-      ([cmd, args]) => cmd === 'open' && args.join(' ') === '-g -a Simulator',
-    ),
-    false,
-  );
-});
-
-test('ensureBootedSimulator foregrounds Device Hub after cold boot when opted in', async () => {
-  mockRunCmdResponses({
-    'xcrun simctl list devices -j': simulatorStateSequence('Shutdown', 'Booted'),
-    'xcrun simctl boot sim-1': OK_RESULT,
-    'xcrun simctl bootstatus sim-1 -b': OK_RESULT,
-    'open -a Device Hub': OK_RESULT,
-  });
-
-  await ensureBootedSimulator(IOS_TEST_SIMULATOR, { deviceHub: true, focusExisting: true });
-
-  assert.equal(
-    mockRunCmd.mock.calls.some(
-      ([cmd, args]) => cmd === 'open' && args.join(' ') === '-a Device Hub',
-    ),
-    true,
+    [['xcrun', 'simctl list devices -j']],
   );
 });
 
diff --git a/packages/platform-apple/src/core/simulator.ts b/packages/platform-apple/src/core/simulator.ts
index 106aae9e6b..6ba17b5552 100644
--- a/packages/platform-apple/src/core/simulator.ts
+++ b/packages/platform-apple/src/core/simulator.ts
@@ -15,9 +15,6 @@ import {
 import { buildSimctlArgsForDevice } from './simctl.ts';
 import { runAppleToolCommand, runXcrun } from './tool-provider.ts';
 
-const IOS_SIMULATOR_HOST_APPS = ['Simulator'] as const;
-const IOS_DEVICE_HUB_HOST_APPS = ['Device Hub', 'Simulator'] as const;
-
 const simulatorReadiness = createScopedProvider<
   ((device: DeviceInfo) => Promise<void>) | undefined
 >(undefined);
@@ -29,16 +26,7 @@ export async function withSimulatorReadiness<T>(
   return await simulatorReadiness.run(ensureReady, task);
 }
 
-type OpenIosSimulatorAppOptions = {
-  background?: boolean;
-  deviceHub?: boolean;
-  signal?: AbortSignal;
-};
-
-type EnsureBootedSimulatorOptions = {
-  deviceHub?: boolean;
-  focusExisting?: boolean;
-  onColdBootStart?: (device: DeviceInfo) => void;
+type SimulatorCommandOptions = {
   signal?: AbortSignal;
 };
 
@@ -78,22 +66,17 @@ export function requireSimulatorDevice(device: DeviceInfo, command: string): voi
   }
 }
 
-export async function openIosSimulatorApp(options: OpenIosSimulatorAppOptions = {}): Promise<void> {
-  const appNames = options.deviceHub ? IOS_DEVICE_HUB_HOST_APPS : IOS_SIMULATOR_HOST_APPS;
-  const openArgsPrefix = options.background ? ['-g', '-a'] : ['-a'];
-  for (const appName of appNames) {
-    const result = await runAppleToolCommand('open', [...openArgsPrefix, appName], {
-      allowFailure: true,
-      signal: options.signal,
-      timeoutMs: IOS_SIMULATOR_FOCUS_TIMEOUT_MS,
-    });
-    if (result.exitCode === 0) return;
-  }
+export async function openIosSimulatorApp(options: SimulatorCommandOptions = {}): Promise<void> {
+  await runAppleToolCommand('open', ['-a', 'Simulator'], {
+    allowFailure: true,
+    signal: options.signal,
+    timeoutMs: IOS_SIMULATOR_FOCUS_TIMEOUT_MS,
+  });
 }
 
 export async function ensureBootedSimulator(
   device: DeviceInfo,
-  options: EnsureBootedSimulatorOptions = {},
+  options: SimulatorCommandOptions = {},
 ): Promise<void> {
   if (device.kind !== 'simulator') return;
   options.signal?.throwIfAborted();
@@ -109,16 +92,8 @@ export async function ensureBootedSimulator(
     : await getSimulatorState(device, options.signal);
   if (state === 'Booted') {
     markSimulatorBooted(device);
-    if (options.focusExisting) {
-      await openIosSimulatorApp({
-        background: options.deviceHub,
-        deviceHub: options.deviceHub,
-        signal: options.signal,
-      });
-    }
     return;
   }
-  options.onColdBootStart?.(device);
 
   const deadline = Deadline.fromTimeoutMs(IOS_BOOT_TIMEOUT_MS);
   let bootResult:
@@ -231,7 +206,7 @@ export async function ensureBootedSimulator(
   }
 
   markSimulatorBooted(device);
-  await openIosSimulatorApp({ deviceHub: options.deviceHub, signal: options.signal });
+  await openIosSimulatorApp({ signal: options.signal });
 }
 
 export async function shutdownSimulator(
diff --git a/packages/platform-apple/src/lifecycle.test.ts b/packages/platform-apple/src/lifecycle.test.ts
index 6df184a1d1..17a1c04206 100644
--- a/packages/platform-apple/src/lifecycle.test.ts
+++ b/packages/platform-apple/src/lifecycle.test.ts
@@ -341,7 +341,6 @@ test('open forwards its startup deadline to the Simulator boot wait', async () =
       target: 'com.example.app',
       hasExistingSession: false,
       surface: 'app',
-      deviceHub: false,
       prewarmRunnerOnColdBoot: false,
       execution: { startupDeadlineAtMs: startedAtMs + 45_000 },
     });
diff --git a/scripts/integration-progress-model.ts b/scripts/integration-progress-model.ts
index bd6d44992f..3a1be8a0b8 100644
--- a/scripts/integration-progress-model.ts
+++ b/scripts/integration-progress-model.ts
@@ -300,7 +300,6 @@ function summarizeProviderScenarioFlagExclusions() {
       name: 'Apple launch and perf artifact options',
       owner: 'iOS platform, observability command, and parser tests',
       keys: [
-        'deviceHub',
         'kind',
         'launchArgs',
         'perfTemplate',
diff --git a/src/__tests__/client.test.ts b/src/__tests__/client.test.ts
index 18c7a11fb1..7ae6d47b05 100644
--- a/src/__tests__/client.test.ts
+++ b/src/__tests__/client.test.ts
@@ -213,13 +213,11 @@ test('apps.open resolves session device identifiers from open response', async (
     app: 'Settings',
     platform: 'ios',
     relaunch: true,
-    deviceHub: true,
   });
 
   assert.equal(setup.calls.length, 1);
   assert.equal(setup.calls[0]?.command, 'open');
   assert.deepEqual(setup.calls[0]?.positionals, ['Settings']);
-  assert.equal(setup.calls[0]?.flags?.deviceHub, true);
   assert.equal(result.identifiers.session, 'qa');
   assert.equal(result.identifiers.deviceId, 'SIM-001');
   assert.equal(result.identifiers.udid, 'SIM-001');
diff --git a/src/cli/parser/__tests__/args-parse-session.test.ts b/src/cli/parser/__tests__/args-parse-session.test.ts
index a9976d590c..14c87a98f7 100644
--- a/src/cli/parser/__tests__/args-parse-session.test.ts
+++ b/src/cli/parser/__tests__/args-parse-session.test.ts
@@ -842,15 +842,6 @@ test('parseArgs recognizes explicit config file flag', () => {
   assert.equal(parsed.flags.config, './agent-device.json');
 });
 
-test('parseArgs recognizes open Device Hub opt-in flag', () => {
-  const parsed = parseArgs(['open', 'settings', '--platform', 'ios', '--device-hub'], {
-    strictFlags: true,
-  });
-  assert.equal(parsed.command, 'open');
-  assert.equal(parsed.flags.platform, 'ios');
-  assert.equal(parsed.flags.deviceHub, true);
-});
-
 test('parseArgs recognizes session lock policy flag', () => {
   const parsed = parseArgs(['snapshot', '--session-lock', 'strip'], { strictFlags: true });
   assert.equal(parsed.command, 'snapshot');
diff --git a/src/commands/command-flags.ts b/src/commands/command-flags.ts
index c2af9abf0d..881a6345c1 100644
--- a/src/commands/command-flags.ts
+++ b/src/commands/command-flags.ts
@@ -64,7 +64,6 @@ function buildFlags(options: InternalRequestOptions): CommandFlags {
     relaunch: options.relaunch,
     shutdown: options.shutdown,
     saveScript: options.saveScript,
-    deviceHub: options.deviceHub,
     testIme: options.testIme,
     noRecord: options.noRecord,
     recordAs: options.recordAs,
diff --git a/src/commands/management/app.ts b/src/commands/management/app.ts
index a44948d9c6..0e8e048b53 100644
--- a/src/commands/management/app.ts
+++ b/src/commands/management/app.ts
@@ -61,7 +61,6 @@ const openCommandMetadata = defineFieldCommandMetadata(
     force: booleanField(
       'Overwrite an existing --save-script target instead of refusing (alias: --overwrite).',
     ),
-    deviceHub: booleanField('Use Xcode Device Hub when surfacing Apple simulators.'),
     testIme: booleanField(
       'Activate the headless Android test IME for deterministic Unicode text entry (default on for emulators; opt-in on real devices).',
     ),
@@ -116,7 +115,6 @@ const openCliSchema = {
     'activity',
     'launchConsole',
     'launchArgs',
-    'deviceHub',
     'testIme',
     'saveScript',
     'force',
@@ -155,7 +153,6 @@ const openCliReader: CliReader = (positionals, flags) => ({
   waitMs: flags.waitMs,
   saveScript: flags.saveScript,
   force: flags.force,
-  deviceHub: flags.deviceHub,
   testIme: flags.testIme,
   noRecord: flags.noRecord,
   metroHost: flags.metroHost,
diff --git a/src/commands/schema/cli-help-command-usage.test.ts b/src/commands/schema/cli-help-command-usage.test.ts
index 1d25e03127..1a1fd35766 100644
--- a/src/commands/schema/cli-help-command-usage.test.ts
+++ b/src/commands/schema/cli-help-command-usage.test.ts
@@ -325,8 +325,6 @@ test('open command usage documents surface and console log flags', async () => {
   assert.match(help, /macOS also supports --surface/);
   assert.match(help, /--launch-console <path>/);
   assert.match(help, /iOS simulator launch console/);
-  assert.match(help, /--device-hub/);
-  assert.match(help, /use Xcode Device Hub/);
   assert.match(help, /Use --platform to bind URL\/deep-link opens/);
   assert.match(help, /agent-device open "Expo Go" exp:\/\/127\.0\.0\.1:8081 --platform ios/);
 });
diff --git a/src/daemon/__tests__/request-runtime-binding.test.ts b/src/daemon/__tests__/request-runtime-binding.test.ts
index a2ee437240..2eba8ce399 100644
--- a/src/daemon/__tests__/request-runtime-binding.test.ts
+++ b/src/daemon/__tests__/request-runtime-binding.test.ts
@@ -53,11 +53,10 @@ beforeEach(() => {
 
 test('bound readiness preserves local behavior after the binding fence', async () => {
   const selected = device('ready-after-bind');
-  const options = { focusExisting: true };
 
-  await ensureBoundDeviceReady({ device: selected, owner: localRuntimeOwner('android') }, options);
+  await ensureBoundDeviceReady({ device: selected, owner: localRuntimeOwner('android') });
 
-  expect(mockEnsureDeviceReady).toHaveBeenCalledWith(selected, options);
+  expect(mockEnsureDeviceReady).toHaveBeenCalledWith(selected);
 });
 
 test('bound readiness leaves provider-owned devices alone', async () => {
@@ -103,7 +102,7 @@ test('runtime readiness follows allocator claim admission', async () => {
     use: appLogInspectUse,
     inspectFacts: bindings.inspectFacts,
     bindDevice: bindings.bindDevice,
-    readiness: {},
+    readiness: true,
   });
 
   expect(admission.type).toBe('runtime');
diff --git a/src/daemon/__tests__/snapshot-runtime-binding.test.ts b/src/daemon/__tests__/snapshot-runtime-binding.test.ts
index e6f050cf43..b512636855 100644
--- a/src/daemon/__tests__/snapshot-runtime-binding.test.ts
+++ b/src/daemon/__tests__/snapshot-runtime-binding.test.ts
@@ -75,7 +75,7 @@ test('sessionless capture readiness follows runtime binding', async () => {
     plan: resolveSnapshotRuntimePlan({ customActions: false, hasActiveApp: true }),
     inspectFacts: fixture.inspectFacts,
     bindDevice: recordingBind,
-    readiness: {},
+    readiness: true,
   });
 
   expect(resolved.ok).toBe(true);
diff --git a/src/daemon/app-event-runtime.ts b/src/daemon/app-event-runtime.ts
index 0e0d83e68b..4136d54cf8 100644
--- a/src/daemon/app-event-runtime.ts
+++ b/src/daemon/app-event-runtime.ts
@@ -7,7 +7,6 @@ import { successText } from '@agent-device/kernel/success-text';
 import type { DaemonCommandContext } from './context.ts';
 import { admitRuntimeUse, type RuntimeAdmissionBindings } from './runtime-admission.ts';
 import { runtimeExecutionFromContext } from './snapshot-runtime-capture-input.ts';
-import type { DeviceReadyOptions } from './device/device-ready.ts';
 import type { DaemonFailureResponse } from '@agent-device/kernel/contracts';
 
 /**
@@ -59,7 +58,7 @@ export async function resolveBoundAppEventRuntime(
   params: Readonly<{
     device: DeviceInfo;
     positionals: readonly string[];
-    readiness?: DeviceReadyOptions;
+    readiness?: boolean;
   }> &
     RuntimeAdmissionBindings,
 ): Promise<ResolvedAppEventExecution> {
diff --git a/src/daemon/device/__tests__/device-ready.test.ts b/src/daemon/device/__tests__/device-ready.test.ts
index 2008db70b3..9fbf9012fb 100644
--- a/src/daemon/device/__tests__/device-ready.test.ts
+++ b/src/daemon/device/__tests__/device-ready.test.ts
@@ -54,26 +54,7 @@ test('ensureDeviceReady caches successful simulator readiness checks', async ()
   await ensureDeviceReady({ ...device });
 
   expect(mockEnsureBootedSimulator).toHaveBeenCalledTimes(1);
-  expect(mockEnsureBootedSimulator).toHaveBeenCalledWith(
-    device,
-    expect.objectContaining({
-      deviceHub: undefined,
-      focusExisting: undefined,
-    }),
-  );
-});
-
-test('ensureDeviceReady focuses cached simulator readiness checks when requested', async () => {
-  const device: DeviceInfo = { ...IOS_SIMULATOR, simulatorSetPath: '/tmp/simset-a' };
-
-  await ensureDeviceReady(device);
-  await ensureDeviceReady({ ...device }, { deviceHub: true, focusExisting: true });
-
-  expect(mockEnsureBootedSimulator).toHaveBeenCalledTimes(2);
-  expect(mockEnsureBootedSimulator).toHaveBeenLastCalledWith(
-    { ...device },
-    expect.objectContaining({ deviceHub: true, focusExisting: true }),
-  );
+  expect(mockEnsureBootedSimulator).toHaveBeenCalledWith(device);
 });
 
 test('ensureDeviceReady caches successful iOS physical device readiness checks', async () => {
@@ -105,16 +86,6 @@ test('ensureDeviceReady includes simulator set path in the cache key', async ()
   expect(mockEnsureBootedSimulator).toHaveBeenCalledTimes(2);
 });
 
-test('ensureDeviceReady forwards iOS simulator cold boot callback', async () => {
-  const onColdBootStart = vi.fn();
-  await ensureDeviceReady(IOS_SIMULATOR, { onIosSimulatorColdBootStart: onColdBootStart });
-
-  expect(mockEnsureBootedSimulator).toHaveBeenCalledWith(
-    IOS_SIMULATOR,
-    expect.objectContaining({ onColdBootStart }),
-  );
-});
-
 test('ensureDeviceReady expires cached readiness checks after the ttl', async () => {
   await ensureDeviceReady(ANDROID_EMULATOR);
   vi.setSystemTime(new Date(Date.now() + DEVICE_READY_CACHE_TTL_MS - 1));
diff --git a/src/daemon/device/device-ready.ts b/src/daemon/device/device-ready.ts
index bbe1b0c880..6ee073517e 100644
--- a/src/daemon/device/device-ready.ts
+++ b/src/daemon/device/device-ready.ts
@@ -8,26 +8,13 @@ export const DEVICE_READY_CACHE_TTL_MS = 5_000;
 
 const readyCache = createTtlMemo<string, true>({ ttlMs: DEVICE_READY_CACHE_TTL_MS });
 
-export type DeviceReadyOptions = {
-  deviceHub?: boolean;
-  focusExisting?: boolean;
-  onIosSimulatorColdBootStart?: (device: DeviceInfo) => void;
-};
-
-export async function ensureDeviceReady(
-  device: DeviceInfo,
-  options: DeviceReadyOptions = {},
-): Promise<void> {
+export async function ensureDeviceReady(device: DeviceInfo): Promise<void> {
   if (isActiveProviderDevice(device)) return;
 
   const cacheKey = deviceReadyCacheKey(device);
-  const isCached = readyCache.get(cacheKey) === true;
-  if (isCached) {
-    if (!options.focusExisting) return;
-    readyCache.delete(cacheKey);
-  }
+  if (readyCache.get(cacheKey) === true) return;
 
-  const handled = await ensureLocalPlatformDeviceReady(device, options);
+  const handled = await ensureLocalPlatformDeviceReady(device);
   if (handled) {
     markDeviceReady(cacheKey);
   }
diff --git a/src/daemon/handlers/session-clipboard.ts b/src/daemon/handlers/session-clipboard.ts
index fa74d23284..869e618d62 100644
--- a/src/daemon/handlers/session-clipboard.ts
+++ b/src/daemon/handlers/session-clipboard.ts
@@ -115,7 +115,7 @@ async function resolveBoundClipboardRuntime(
       use: clipboardReadUse,
       inspectFacts,
       bindDevice,
-      readiness: {},
+      readiness: true,
     });
     if (admission.type === 'response') return { ok: false, response: admission.response };
     const runtime = admission.runtime;
@@ -127,7 +127,7 @@ async function resolveBoundClipboardRuntime(
     use: clipboardWriteUse,
     inspectFacts,
     bindDevice,
-    readiness: {},
+    readiness: true,
   });
   if (admission.type === 'response') return { ok: false, response: admission.response };
   const runtime = admission.runtime;
diff --git a/src/daemon/handlers/session-selector-dispatch.ts b/src/daemon/handlers/session-selector-dispatch.ts
index eba1058808..c41e8cbf73 100644
--- a/src/daemon/handlers/session-selector-dispatch.ts
+++ b/src/daemon/handlers/session-selector-dispatch.ts
@@ -16,7 +16,6 @@ import { expireRefFrame } from '../ref-frame.ts';
 import { resolveSessionAppBundleIdForTarget } from '../../platform-runtime-open-target.ts';
 import type { BindDeviceRuntime, InspectDeviceRuntimeFacts } from '../request-runtime-binding.ts';
 import type { DaemonCommandContext } from '../context.ts';
-import type { DeviceReadyOptions } from '../device/device-ready.ts';
 import { errorResponse } from '@agent-device/kernel/contracts';
 
 /**
@@ -136,7 +135,7 @@ type SessionRouteRuntimeResolver = (
   params: Readonly<{
     device: DeviceInfo;
     positionals: string[];
-    readiness?: DeviceReadyOptions;
+    readiness?: boolean;
     inspectFacts?: InspectDeviceRuntimeFacts;
     bindDevice?: BindDeviceRuntime;
   }>,
@@ -181,7 +180,7 @@ async function runBoundSessionRoute(
       const bound = await params.resolveRuntime({
         device,
         positionals,
-        readiness: {},
+        readiness: true,
         inspectFacts,
         bindDevice,
       });
diff --git a/src/daemon/handlers/snapshot-alert.ts b/src/daemon/handlers/snapshot-alert.ts
index 397325545f..14c10d4507 100644
--- a/src/daemon/handlers/snapshot-alert.ts
+++ b/src/daemon/handlers/snapshot-alert.ts
@@ -61,7 +61,7 @@ async function resolveBoundAlertRuntime(
     device,
     inspectFacts,
     bindDevice,
-    ...(params.session ? {} : { readiness: {} }),
+    readiness: !params.session,
   };
   if (action === 'wait') {
     const admission = await admitRuntimeUse({ ...shared, use: alertWaitUse });
diff --git a/src/daemon/handlers/snapshot-settings.ts b/src/daemon/handlers/snapshot-settings.ts
index 5c990b9287..a74a8b6319 100644
--- a/src/daemon/handlers/snapshot-settings.ts
+++ b/src/daemon/handlers/snapshot-settings.ts
@@ -226,7 +226,7 @@ async function executeSettingsRead(
     use: settingReadUse,
     inspectFacts,
     bindDevice,
-    ...(session ? {} : { readiness: {} }),
+    readiness: !session,
   });
   if (admission.type === 'response') return admission.response;
 
@@ -267,7 +267,7 @@ async function executeSettingsWrite(
     use: settingsRuntimeUse,
     inspectFacts,
     bindDevice,
-    ...(session ? {} : { readiness: {} }),
+    readiness: !session,
   });
   const appBundleId = settingsWriteAppId(req, parsed, session);
   if (admission.type === 'response') return admission.response;
diff --git a/src/daemon/keyboard-runtime.ts b/src/daemon/keyboard-runtime.ts
index 69b12aeee1..aeb925d7fa 100644
--- a/src/daemon/keyboard-runtime.ts
+++ b/src/daemon/keyboard-runtime.ts
@@ -29,7 +29,6 @@ import {
   type RuntimeAdmissionRequest,
 } from './runtime-admission.ts';
 import { runtimeExecutionFromContext } from './snapshot-runtime-capture-input.ts';
-import type { DeviceReadyOptions } from './device/device-ready.ts';
 import type { DaemonFailureResponse } from '@agent-device/kernel/contracts';
 
 type KeyboardRuntimeAction = 'status' | 'dismiss' | 'enter';
@@ -222,7 +221,7 @@ async function executeKeyboardEnter(
 export async function resolveBoundKeyboardRuntime(
   params: {
     device: DeviceInfo;
-    readiness?: DeviceReadyOptions;
+    readiness?: boolean;
   } & RuntimeAdmissionBindings & { positionals: readonly string[] },
 ): Promise<ResolvedKeyboardExecution> {
   const action = readKeyboardAction(params.positionals);
diff --git a/src/daemon/request-runtime-binding.ts b/src/daemon/request-runtime-binding.ts
index b756188de2..1d48614c6b 100644
--- a/src/daemon/request-runtime-binding.ts
+++ b/src/daemon/request-runtime-binding.ts
@@ -15,7 +15,7 @@ import {
 } from '@agent-device/contracts/platform-runtime';
 import type { PlatformRequestScope } from '@agent-device/contracts/platform-runtime-host';
 import type { PlatformRuntimeOperations } from '@agent-device/contracts/platform-runtime-operations';
-import { ensureDeviceReady, type DeviceReadyOptions } from './device/device-ready.ts';
+import { ensureDeviceReady } from './device/device-ready.ts';
 import type {
   ManagedRequestAdmission,
   ResolveManagedRequestLease,
@@ -82,10 +82,7 @@ export type BoundDeviceIdentity = Readonly<{
 }>;
 
 /** Confirms managed authority or runs local readiness after binding and claim admission. */
-export async function ensureBoundDeviceReady(
-  bound: BoundDeviceIdentity,
-  options: DeviceReadyOptions = {},
-): Promise<void> {
+export async function ensureBoundDeviceReady(bound: BoundDeviceIdentity): Promise<void> {
   switch (bound.owner.kind) {
     case 'provider-runtime':
       return;
@@ -102,7 +99,7 @@ export async function ensureBoundDeviceReady(
       );
     }
     case 'local-family':
-      await ensureDeviceReady(bound.device, options);
+      await ensureDeviceReady(bound.device);
   }
 }
 
diff --git a/src/daemon/runtime-admission.ts b/src/daemon/runtime-admission.ts
index b976c7d913..8c47cecb4c 100644
--- a/src/daemon/runtime-admission.ts
+++ b/src/daemon/runtime-admission.ts
@@ -13,7 +13,6 @@ import type {
   RuntimeAdmissionBindings,
 } from './request-runtime-binding.ts';
 import { ensureBoundDeviceReady } from './request-runtime-binding.ts';
-import type { DeviceReadyOptions } from './device/device-ready.ts';
 import type { DaemonCommandContext } from './context.ts';
 import type { ResolvedGenericExecution } from './request-generic-dispatch.ts';
 import { type DaemonFailureResponse, errorResponse } from '@agent-device/kernel/contracts';
@@ -38,7 +37,7 @@ export type RuntimeAdmissionRequest = RuntimeAdmissionBindings &
     device: DeviceInfo;
     required: readonly RuntimeOperationKey<PlatformRuntimeOperations>[];
     unavailableResponse?: UnavailableRuntimeResponse;
-    readiness?: DeviceReadyOptions;
+    readiness?: boolean;
   }>;
 
 export type { RuntimeAdmissionBindings };
@@ -95,9 +94,7 @@ export async function admitRuntimeUse<
   const admitted = await admitRuntimeOperations({ ...request, required: request.use.required });
   if (admitted.type === 'response') return admitted;
   const runtime = await admitted.bind(request.device, request.use);
-  if (request.readiness !== undefined) {
-    await ensureBoundDeviceReady(runtime, request.readiness);
-  }
+  if (request.readiness) await ensureBoundDeviceReady(runtime);
   return { type: 'runtime', runtime };
 }
 
diff --git a/src/daemon/selector-capture-binding.ts b/src/daemon/selector-capture-binding.ts
index 0b91499724..22b568c5a4 100644
--- a/src/daemon/selector-capture-binding.ts
+++ b/src/daemon/selector-capture-binding.ts
@@ -60,7 +60,7 @@ export async function resolveBoundSelectorCapture(
       hasActiveApp: params.session?.appBundleId !== undefined,
       intent: selectorCaptureIntent(params.command),
     }),
-    ...(params.session ? {} : { readiness: {} }),
+    readiness: !params.session,
   });
   if (!bound.ok) return bound;
   // The read is present only when the admitted owner advertised it; its absence is not a failure
diff --git a/src/daemon/session-lifecycle/internal/session-open-prepare.ts b/src/daemon/session-lifecycle/internal/session-open-prepare.ts
index df61b13966..27f4e5e5dd 100644
--- a/src/daemon/session-lifecycle/internal/session-open-prepare.ts
+++ b/src/daemon/session-lifecycle/internal/session-open-prepare.ts
@@ -157,7 +157,6 @@ export async function prepareOpenCommandDetails(params: {
     currentAppBundleId: existingSession?.appBundleId,
     hasExistingSession: existingSession !== undefined,
     surface,
-    deviceHub: req.flags?.deviceHub === true,
     prewarmRunnerOnColdBoot:
       surface === 'app' && Boolean(openTarget) && !isDeepLinkTarget(openTarget ?? ''),
     execution: {
diff --git a/src/daemon/snapshot-runtime-binding.ts b/src/daemon/snapshot-runtime-binding.ts
index a47f3a398a..909e4734a4 100644
--- a/src/daemon/snapshot-runtime-binding.ts
+++ b/src/daemon/snapshot-runtime-binding.ts
@@ -16,7 +16,6 @@ import {
   type BindDeviceRuntime,
   type InspectDeviceRuntimeFacts,
 } from './request-runtime-binding.ts';
-import type { DeviceReadyOptions } from './device/device-ready.ts';
 import type { PlatformResourceCleanup } from './platform-resource-cleanup.ts';
 import { SessionStore } from './session-store.ts';
 import type { DaemonRequest, DaemonResponse } from './daemon-request.ts';
@@ -101,7 +100,7 @@ export async function admitAndBindSnapshotCapture(
     plan: SnapshotRuntimePlan | SelectorCaptureRuntimePlan;
     inspectFacts?: InspectDeviceRuntimeFacts;
     bindDevice?: BindDeviceRuntime;
-    readiness?: DeviceReadyOptions;
+    readiness?: boolean;
   }>,
 ): Promise<AdmittedSnapshotCapture> {
   const { command, device, session, plan } = params;
@@ -149,7 +148,7 @@ export async function resolveBoundSnapshotCaptureRuntime(
     }),
     inspectFacts: params.inspectFacts,
     bindDevice: params.bindDevice,
-    ...(session ? {} : { readiness: {} }),
+    readiness: !session,
   });
   if (!bound.ok) return bound;
 
@@ -177,7 +176,7 @@ export async function resolveBoundSnapshotCaptureRuntime(
 async function bindSnapshotCaptureRuntime(
   bindDevice: BindDeviceRuntime | undefined,
   admission: AdmittedRuntimePlan<SnapshotRuntimePlan | SelectorCaptureRuntimePlan>,
-  readiness: DeviceReadyOptions | undefined,
+  readiness: boolean | undefined,
 ): Promise<
   Readonly<{
     captureSnapshot(input: CaptureSnapshotInput): Promise<SnapshotResult>;
@@ -194,7 +193,7 @@ async function bindSnapshotCaptureRuntime(
   const bind = requireRuntimeBinding(bindDevice);
   const bindReady: BindDeviceRuntime = async (device, use) => {
     const runtime = await bind(device, use);
-    if (readiness !== undefined) await ensureBoundDeviceReady(runtime, readiness);
+    if (readiness) await ensureBoundDeviceReady(runtime);
     return runtime;
   };
   const { device, plan } = unwrapAdmittedRuntimePlan(admission);
diff --git a/src/platform-runtime-device-ready.ts b/src/platform-runtime-device-ready.ts
index dd66b0cef2..c0a63cb593 100644
--- a/src/platform-runtime-device-ready.ts
+++ b/src/platform-runtime-device-ready.ts
@@ -1,28 +1,15 @@
 import { isIosFamily, type DeviceInfo } from '@agent-device/kernel/device';
 import { loadAndroidMechanics } from './platform-runtime-android-mechanics.ts';
 
-export type LocalPlatformDeviceReadyOptions = {
-  deviceHub?: boolean;
-  focusExisting?: boolean;
-  onIosSimulatorColdBootStart?: (device: DeviceInfo) => void;
-};
-
 /**
  * Runs concrete local-platform readiness mechanics from the root composition layer.
  * Returns false when the platform has no readiness preparation step.
  */
-export async function ensureLocalPlatformDeviceReady(
-  device: DeviceInfo,
-  options: LocalPlatformDeviceReadyOptions = {},
-): Promise<boolean> {
+export async function ensureLocalPlatformDeviceReady(device: DeviceInfo): Promise<boolean> {
   if (isIosFamily(device)) {
     if (device.kind === 'simulator') {
       const { ensureBootedSimulator } = await import('@agent-device/platform-apple/simulator');
-      await ensureBootedSimulator(device, {
-        deviceHub: options.deviceHub,
-        focusExisting: options.focusExisting,
-        onColdBootStart: options.onIosSimulatorColdBootStart,
-      });
+      await ensureBootedSimulator(device);
       return true;
     }
     if (device.kind === 'device') {
diff --git a/test/integration/provider-scenarios/providers.ts b/test/integration/provider-scenarios/providers.ts
index be12a2c64f..c39a5f56f0 100644
--- a/test/integration/provider-scenarios/providers.ts
+++ b/test/integration/provider-scenarios/providers.ts
@@ -153,15 +153,8 @@ export function createRecordingAppleToolProvider(handlers: RecordingAppleToolHan
   };
 }
 
-const SIMULATOR_HOST_OPEN_COMMANDS = new Set([
-  '-a Device Hub',
-  '-a Simulator',
-  '-g -a Device Hub',
-  '-g -a Simulator',
-]);
-
 function isSimulatorHostOpenCommand(cmd: string, args: readonly string[]): boolean {
-  return cmd === 'open' && SIMULATOR_HOST_OPEN_COMMANDS.has(args.join(' '));
+  return cmd === 'open' && args.join(' ') === '-a Simulator';
 }
 
 function createRecordingMacOsHostProvider(
diff --git a/website/docs/docs/client-api.md b/website/docs/docs/client-api.md
index 99da1feebb..d28f0d4009 100644
--- a/website/docs/docs/client-api.md
+++ b/website/docs/docs/client-api.md
@@ -107,9 +107,6 @@ The canonical client example is embedded below. It is also runnable from [`examp
 For direct iOS simulator app launches, `client.apps.open({ app, platform: 'ios', launchConsole: './artifacts/app.console.log' })` captures launch-time
 stdout/stderr. The option mirrors `open --launch-console` and is not valid for URL opens or non-simulator targets.
 
-When surfacing Apple simulators, `client.apps.open({ deviceHub: true })` mirrors `open --device-hub` and uses Xcode Device Hub instead of the
-standalone Simulator app.
-
 `client.sessions.stateDir()` mirrors `session state-dir` and returns the resolved daemon state directory as a pure local resolution — it never starts
 or contacts the daemon. Pass `{ stateDir }` to resolve an explicit override the same way the CLI resolves `--state-dir`.
 
diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md
index e0db3624b1..5a675ccdc6 100644
--- a/website/docs/docs/commands.md
+++ b/website/docs/docs/commands.md
@@ -79,7 +79,6 @@ agent-device fold open
 - `open <app> <url>` opens a deep link on iOS.
 - `open <app> --launch-console <path>` captures launch-time stdout/stderr for direct iOS simulator app launches. It is not valid for URL opens or
   non-simulator targets.
-- `open --device-hub` uses Xcode Device Hub when surfacing Apple simulators.
 - `open --platform macos --surface app|frontmost-app|desktop|menubar` selects the macOS session surface explicitly. `app` is the default when an app argument is provided.
 - `back` now defaults to app-owned back navigation. On Apple targets that means visible in-app back UI only. On Android this currently maps to the same back keyevent because Android routes in-app back through that platform event.
 - `back --in-app` is an explicit alias for the default app-owned behavior.

From 3f11d51235679fd74c9661650a4ab398ac8428bf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Wed, 23 Sep 2026 17:26:36 +0200
Subject: [PATCH 050/132] refactor(platform-apple): collapse the runner client
 chain and merge the command trait table (#2822)

* refactor(platform-apple): bind the runner host in the composition root and drop the client factory

core/runner-client.ts now binds the host and re-exports the host-bound
operations from their owning runner modules. runner/client.ts, whose
createAppleRunnerClient returned those module functions unchanged, is
deleted along with its never-read runnerLeaseCleanupAdapter field. The
explicit AppleRunnerClient annotations are gone: plain re-exports emit no
inferred type, so dts generation needs no portable name (no TS2883).

resolveAppleRunnerProvider loses its third provider parameter, which its
only caller always passed as undefined.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* refactor(platform-apple): merge the runner command manifest and trait classes into one table

RUNNER_COMMAND_TRAITS maps each runner command straight to its traits;
alert keeps a function of the command because its read-only trait depends
on the action. The class-name indirection (RunnerCommandTraitClass and the
switch that resolved it) is gone. The Swift CommandType.traits table stays
separate: it models different axes.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* test(platform-apple): pin runner command groups through the trait reader

The group test now resolves each fixed-trait command through
readRunnerCommandTraits, so a regression in the reader fails it. The
composition-root doc states the evaluation order precisely, and the
unbound-host error names both binding sites.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* chore(gates): drop the stale getRunnerSessionSnapshot fallow ignore

The export no longer exists on core/runner-client.ts.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .fallowrc.json                                |   1 -
 .../platform-apple/src/core/runner-client.ts  |  85 +++++------
 .../runner/__tests__/runner-client.test.ts    |   9 +-
 .../__tests__/runner-command-traits.test.ts   | 133 +++++++++---------
 .../runner/__tests__/runner-provider.test.ts  |   4 +-
 packages/platform-apple/src/runner/client.ts  |  88 ------------
 packages/platform-apple/src/runner/host.ts    |   8 +-
 packages/platform-apple/src/runner/index.ts   |  13 +-
 .../src/runner/runner-client.ts               |   2 +-
 .../src/runner/runner-command-traits.ts       | 111 +++++++--------
 .../src/runner/runner-error-classification.ts |   2 +-
 .../src/runner/runner-provider.ts             |   2 -
 12 files changed, 167 insertions(+), 291 deletions(-)
 delete mode 100644 packages/platform-apple/src/runner/client.ts

diff --git a/.fallowrc.json b/.fallowrc.json
index 2e78ae33ae..117ad4dcb4 100644
--- a/.fallowrc.json
+++ b/.fallowrc.json
@@ -160,7 +160,6 @@
         "prepareIosRunner",
         "resolveRunnerAppBundleId",
         "detachIosRunnerSessionsForShutdown",
-        "getRunnerSessionSnapshot",
         "stopIosRunnerSession",
         "stopAllIosRunnerSessions",
         "readStaleRunnerLease",
diff --git a/packages/platform-apple/src/core/runner-client.ts b/packages/platform-apple/src/core/runner-client.ts
index e064f817ec..f084648476 100644
--- a/packages/platform-apple/src/core/runner-client.ts
+++ b/packages/platform-apple/src/core/runner-client.ts
@@ -1,55 +1,40 @@
-import { createAppleRunnerClient, type AppleRunnerClient } from '../runner/client.ts';
+import { bindAppleRunnerHost } from '../runner/host.ts';
 import { appleRunnerHost } from './runner-host.ts';
 
 /**
- * Composition root for the Apple runner client (`@agent-device/platform-apple/runner`).
- * This is the only module that constructs the client: it supplies the real
- * host capabilities from `runner-host.ts` and re-exposes the bound operations
- * under their historical names for daemon, platform, and CLI consumers. Types
- * and host-free helpers come from the package façade directly.
- *
- * Each export below carries an explicit `AppleRunnerClient[...]` annotation
- * (rather than a destructuring re-export) because the package's operation
- * types resolve through its private modules; without an annotation naming
- * the public `AppleRunnerClient` type, dts emit cannot print a portable type
- * for the inferred signature (TS2883).
+ * Composition root for the Apple runner operations: the only module that binds
+ * the real host capabilities from `runner-host.ts`, and the module daemon,
+ * platform, and CLI consumers import the host-bound operations from, so every
+ * such consumer evaluates after the binding. Runner modules must not reach the
+ * host while they evaluate: they load before this module binds it. Types and
+ * host-free helpers come from the package façade directly.
  */
-const client: AppleRunnerClient = createAppleRunnerClient(appleRunnerHost);
+bindAppleRunnerHost(appleRunnerHost);
 
-export const runAppleRunnerCommand: AppleRunnerClient['runAppleRunnerCommand'] =
-  client.runAppleRunnerCommand;
-export const notifyIosRunnerAppRelaunched: AppleRunnerClient['notifyIosRunnerAppRelaunched'] =
-  client.notifyIosRunnerAppRelaunched;
-export const hasLiveIosRunnerSession: AppleRunnerClient['hasLiveIosRunnerSession'] =
-  client.hasLiveIosRunnerSession;
-export const releaseSpeculativeIosRunnerSessionFor: AppleRunnerClient['releaseSpeculativeIosRunnerSessionFor'] =
-  client.releaseSpeculativeIosRunnerSessionFor;
-export const prewarmAppleRunnerCache: AppleRunnerClient['prewarmAppleRunnerCache'] =
-  client.prewarmAppleRunnerCache;
-export const prewarmIosRunnerSession: AppleRunnerClient['prewarmIosRunnerSession'] =
-  client.prewarmIosRunnerSession;
-export const prepareIosRunner: AppleRunnerClient['prepareIosRunner'] = client.prepareIosRunner;
-export const resolveRunnerAppBundleId: AppleRunnerClient['resolveRunnerAppBundleId'] =
-  client.resolveRunnerAppBundleId;
-export const hasCachedAppleRunnerArtifact: AppleRunnerClient['hasCachedAppleRunnerArtifact'] =
-  client.hasCachedAppleRunnerArtifact;
-export const detachIosRunnerSessionsForShutdown: AppleRunnerClient['detachIosRunnerSessionsForShutdown'] =
-  client.detachIosRunnerSessionsForShutdown;
-export const readRunnerSessionLiveness: AppleRunnerClient['readRunnerSessionLiveness'] =
-  client.readRunnerSessionLiveness;
-export const releaseIosRunnerOnClose: AppleRunnerClient['releaseIosRunnerOnClose'] =
-  client.releaseIosRunnerOnClose;
-export const stopIosRunnerSession: AppleRunnerClient['stopIosRunnerSession'] =
-  client.stopIosRunnerSession;
-export const stopAllIosRunnerSessions: AppleRunnerClient['stopAllIosRunnerSessions'] =
-  client.stopAllIosRunnerSessions;
-export const runApplePressSeries: AppleRunnerClient['runApplePressSeries'] =
-  client.runApplePressSeries;
-export const cleanupRunnerLeasesForOwner: AppleRunnerClient['cleanupRunnerLeasesForOwner'] =
-  client.cleanupRunnerLeasesForOwner;
-export const readStaleRunnerLease: AppleRunnerClient['readStaleRunnerLease'] =
-  client.readStaleRunnerLease;
-export const verifyLeaseRunnerPidIdentity: AppleRunnerClient['verifyLeaseRunnerPidIdentity'] =
-  client.verifyLeaseRunnerPidIdentity;
-export const applyXctestRunnerAppIconFromDerivedPath: AppleRunnerClient['applyXctestRunnerAppIconFromDerivedPath'] =
-  client.applyXctestRunnerAppIconFromDerivedPath;
+export {
+  hasLiveIosRunnerSession,
+  notifyIosRunnerAppRelaunched,
+  prepareIosRunner,
+  prewarmAppleRunnerCache,
+  prewarmIosRunnerSession,
+  releaseSpeculativeIosRunnerSessionFor,
+  runAppleRunnerCommand,
+} from '../runner/runner-client.ts';
+export { applyXctestRunnerAppIconFromDerivedPath } from '../runner/runner-icon.ts';
+export {
+  cleanupRunnerLeasesForOwner,
+  readStaleRunnerLease,
+  verifyLeaseRunnerPidIdentity,
+} from '../runner/runner-lease.ts';
+export { runApplePressSeries } from '../runner/runner-sequence.ts';
+export {
+  detachIosRunnerSessionsForShutdown,
+  readRunnerSessionLiveness,
+  releaseIosRunnerOnClose,
+  stopAllIosRunnerSessions,
+  stopIosRunnerSession,
+} from '../runner/runner-session.ts';
+export {
+  hasCachedAppleRunnerArtifact,
+  resolveRunnerAppBundleId,
+} from '../runner/runner-xctestrun.ts';
diff --git a/packages/platform-apple/src/runner/__tests__/runner-client.test.ts b/packages/platform-apple/src/runner/__tests__/runner-client.test.ts
index 4ea4ae064a..d351529a3b 100644
--- a/packages/platform-apple/src/runner/__tests__/runner-client.test.ts
+++ b/packages/platform-apple/src/runner/__tests__/runner-client.test.ts
@@ -29,10 +29,7 @@ vi.mock('../runner-macos-products.ts', async () => {
 });
 
 import type { DeviceInfo } from '@agent-device/kernel/device';
-import {
-  RUNNER_COMMAND_TRAIT_MANIFEST,
-  isReadOnlyRunnerCommand,
-} from '../runner-command-traits.ts';
+import { RUNNER_COMMAND_TRAITS, isReadOnlyRunnerCommand } from '../runner-command-traits.ts';
 import {
   isRetryableRunnerError,
   shouldRetryRunnerConnectError,
@@ -310,12 +307,12 @@ test('resolveRunnerDestination uses simulator destination for simulators', () =>
 });
 
 test('runner protocol fixtures cover every runner command with JSON-safe samples', () => {
-  // The trait manifest is the exhaustive runner-command enumeration — it is `satisfies
+  // The trait table is the exhaustive runner-command enumeration — it is `satisfies
   // Record<RunnerCommand['command'], …>` — so the fixture set is checked against that declaration
   // instead of against a second hand-maintained list that a new command has to remember to update.
   assert.deepEqual(
     Object.keys(runnerProtocolCommandFixtures).sort(),
-    Object.keys(RUNNER_COMMAND_TRAIT_MANIFEST).sort(),
+    Object.keys(RUNNER_COMMAND_TRAITS).sort(),
   );
 
   const roundTrip = JSON.parse(JSON.stringify(runnerProtocolCommandFixtures)) as Record<
diff --git a/packages/platform-apple/src/runner/__tests__/runner-command-traits.test.ts b/packages/platform-apple/src/runner/__tests__/runner-command-traits.test.ts
index 5d83d569ac..cf3bbd284e 100644
--- a/packages/platform-apple/src/runner/__tests__/runner-command-traits.test.ts
+++ b/packages/platform-apple/src/runner/__tests__/runner-command-traits.test.ts
@@ -1,5 +1,6 @@
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
+import { isDeepStrictEqual } from 'node:util';
 import { test } from 'vitest';
 import type { RunnerCommand } from '../runner-contract.ts';
 import {
@@ -8,58 +9,67 @@ import {
   isRunnerReadinessPreflightExempt,
   isRunnerReadinessProbeCommand,
   readRunnerCommandTraits,
-  RUNNER_COMMAND_TRAIT_MANIFEST,
+  RUNNER_COMMAND_TRAITS,
   type RunnerCommandTraits,
 } from '../runner-command-traits.ts';
 
-const EXPECTED_RUNNER_COMMAND_TRAITS = Object.fromEntries(
-  Object.entries(RUNNER_COMMAND_TRAIT_MANIFEST).map(([command, traitClass]) => [
-    command,
-    expectedTraitsForClass(traitClass),
-  ]),
-) as Record<RunnerCommand['command'], RunnerCommandTraits>;
+const RUNNER_COMMANDS = Object.keys(RUNNER_COMMAND_TRAITS) as Array<RunnerCommand['command']>;
 
-test('runner command traits are derived from the runner command manifest', () => {
-  for (const [command, expectedTraits] of Object.entries(EXPECTED_RUNNER_COMMAND_TRAITS) as Array<
-    [RunnerCommand['command'], RunnerCommandTraits]
-  >) {
-    assert.deepEqual(readRunnerCommandTraits({ command }), expectedTraits, command);
-  }
-});
-
-test('runner command manifest pins lifecycle-sensitive command groups', () => {
-  assert.deepEqual(commandsForClass('preflightSkippableTouchMutation'), [
-    'desktopScroll',
-    'drag',
-    'gesture',
-    'longPress',
-    'scroll',
-    'sequence',
-    'swipe',
-    'tap',
-  ]);
-  assert.deepEqual(commandsForClass('readOnly'), [
-    'findText',
-    'gestureViewport',
-    'querySelector',
-    'readText',
-    'screenshot',
-    'snapshot',
-  ]);
-  assert.deepEqual(commandsForClass('alertAction'), ['alert']);
-  assert.deepEqual(commandsForClass('readOnlyReadinessProbe'), ['status', 'uptime']);
-  assert.deepEqual(commandsForClass('readinessPreflightExemptMutation'), [
-    'activate',
-    'targetReset',
-    'terminate',
-  ]);
+test('runner command trait table pins lifecycle-sensitive command groups', () => {
+  const groups = {
+    preflightSkippableTouchMutation: commandsWithTraits(hotMutation()),
+    readOnly: commandsWithTraits(readOnly()),
+    payloadDependent: payloadDependentCommands(),
+    readOnlyReadinessProbe: commandsWithTraits(readOnlyReadinessProbe()),
+    readinessPreflightExemptMutation: commandsWithTraits(preflightExemptMutation()),
+    default: commandsWithTraits(defaults()),
+  };
+  assert.deepEqual(groups, {
+    preflightSkippableTouchMutation: [
+      'desktopScroll',
+      'drag',
+      'gesture',
+      'longPress',
+      'scroll',
+      'sequence',
+      'swipe',
+      'tap',
+    ],
+    readOnly: [
+      'findText',
+      'gestureViewport',
+      'querySelector',
+      'readText',
+      'screenshot',
+      'snapshot',
+    ],
+    payloadDependent: ['alert'],
+    readOnlyReadinessProbe: ['status', 'uptime'],
+    readinessPreflightExemptMutation: ['activate', 'targetReset', 'terminate'],
+    default: [
+      'actionButton',
+      'appSwitcher',
+      'back',
+      'backInApp',
+      'backSystem',
+      'home',
+      'keyboardDismiss',
+      'keyboardReturn',
+      'mouseClick',
+      'recordStart',
+      'recordStop',
+      'remotePress',
+      'rotate',
+      'shutdown',
+      'type',
+    ],
+  });
+  assert.deepEqual(Object.values(groups).flat().sort(), [...RUNNER_COMMANDS].sort());
 });
 
 test('runner command trait helpers read from the shared trait table', () => {
-  for (const command of Object.keys(EXPECTED_RUNNER_COMMAND_TRAITS) as Array<
-    RunnerCommand['command']
-  >) {
-    const traits = EXPECTED_RUNNER_COMMAND_TRAITS[command];
+  for (const command of RUNNER_COMMANDS) {
+    const traits = readRunnerCommandTraits({ command });
     assert.equal(isReadOnlyRunnerCommand({ command }), traits.readOnly, command);
     assert.equal(isRunnerReadinessProbeCommand({ command }), traits.readinessProbe, command);
     assert.equal(
@@ -92,31 +102,18 @@ test('alert actions match the native read-only golden table', () => {
   }
 });
 
-function commandsForClass(
-  traitClass: (typeof RUNNER_COMMAND_TRAIT_MANIFEST)[RunnerCommand['command']],
-): RunnerCommand['command'][] {
-  return Object.entries(RUNNER_COMMAND_TRAIT_MANIFEST)
-    .filter((entry) => entry[1] === traitClass)
-    .map((entry) => entry[0] as RunnerCommand['command'])
-    .sort();
+function commandsWithTraits(traits: RunnerCommandTraits): RunnerCommand['command'][] {
+  return RUNNER_COMMANDS.filter(
+    (command) =>
+      typeof RUNNER_COMMAND_TRAITS[command] !== 'function' &&
+      isDeepStrictEqual(readRunnerCommandTraits({ command }), traits),
+  ).sort();
 }
 
-function expectedTraitsForClass(
-  traitClass: (typeof RUNNER_COMMAND_TRAIT_MANIFEST)[RunnerCommand['command']],
-): RunnerCommandTraits {
-  switch (traitClass) {
-    case 'default':
-      return defaults();
-    case 'readinessPreflightExemptMutation':
-      return preflightExemptMutation();
-    case 'readOnly':
-    case 'alertAction':
-      return readOnly();
-    case 'readOnlyReadinessProbe':
-      return readOnlyReadinessProbe();
-    case 'preflightSkippableTouchMutation':
-      return hotMutation();
-  }
+function payloadDependentCommands(): RunnerCommand['command'][] {
+  return RUNNER_COMMANDS.filter(
+    (command) => typeof RUNNER_COMMAND_TRAITS[command] === 'function',
+  ).sort();
 }
 
 function defaults(): RunnerCommandTraits {
diff --git a/packages/platform-apple/src/runner/__tests__/runner-provider.test.ts b/packages/platform-apple/src/runner/__tests__/runner-provider.test.ts
index c242b49c90..58a4594398 100644
--- a/packages/platform-apple/src/runner/__tests__/runner-provider.test.ts
+++ b/packages/platform-apple/src/runner/__tests__/runner-provider.test.ts
@@ -16,7 +16,7 @@ test('scoped Apple runner provider requires matching request id when scoped by r
     scoped,
     { deviceId: IOS_SIMULATOR.id, requestId: 'req-1' },
     async () =>
-      await resolveAppleRunnerProvider(IOS_SIMULATOR, fallback, undefined, {
+      await resolveAppleRunnerProvider(IOS_SIMULATOR, fallback, {
         requestId: 'req-1',
       }).runCommand(IOS_SIMULATOR, { command: 'snapshot' }, { requestId: 'req-1' }),
   );
@@ -38,7 +38,7 @@ test('scoped Apple runner provider requires matching request id when scoped by r
     scoped,
     { deviceId: IOS_SIMULATOR.id, requestId: 'req-1' },
     async () =>
-      await resolveAppleRunnerProvider(IOS_SIMULATOR, fallback, undefined, {
+      await resolveAppleRunnerProvider(IOS_SIMULATOR, fallback, {
         requestId: 'req-2',
       }).runCommand(IOS_SIMULATOR, { command: 'snapshot' }, { requestId: 'req-2' }),
   );
diff --git a/packages/platform-apple/src/runner/client.ts b/packages/platform-apple/src/runner/client.ts
deleted file mode 100644
index d1a7e253b4..0000000000
--- a/packages/platform-apple/src/runner/client.ts
+++ /dev/null
@@ -1,88 +0,0 @@
-import { bindAppleRunnerHost, type AppleRunnerHost } from './host.ts';
-import {
-  hasLiveIosRunnerSession,
-  releaseSpeculativeIosRunnerSessionFor,
-  notifyIosRunnerAppRelaunched,
-  prepareIosRunner,
-  prewarmAppleRunnerCache,
-  prewarmIosRunnerSession,
-  runAppleRunnerCommand,
-} from './runner-client.ts';
-import { applyXctestRunnerAppIconFromDerivedPath } from './runner-icon.ts';
-import {
-  cleanupRunnerLeasesForOwner,
-  readStaleRunnerLease,
-  verifyLeaseRunnerPidIdentity,
-} from './runner-lease.ts';
-import { runnerLeaseCleanupAdapter } from './runner-disposal.ts';
-import { runApplePressSeries } from './runner-sequence.ts';
-import {
-  detachIosRunnerSessionsForShutdown,
-  readRunnerSessionLiveness,
-  releaseIosRunnerOnClose,
-  stopAllIosRunnerSessions,
-  stopIosRunnerSession,
-} from './runner-session.ts';
-import { hasCachedAppleRunnerArtifact, resolveRunnerAppBundleId } from './runner-xctestrun.ts';
-
-/**
- * The host-bound operation surface of the Apple runner client. Everything on
- * this object reaches host capabilities (process execution, diagnostics,
- * locks, Apple tooling) at call time; the package façade deliberately does not
- * export these operations as free functions, so the only way to obtain them is
- * through {@link createAppleRunnerClient} with a concrete host.
- */
-export type AppleRunnerClient = {
-  runAppleRunnerCommand: typeof runAppleRunnerCommand;
-  notifyIosRunnerAppRelaunched: typeof notifyIosRunnerAppRelaunched;
-  hasLiveIosRunnerSession: typeof hasLiveIosRunnerSession;
-  releaseSpeculativeIosRunnerSessionFor: typeof releaseSpeculativeIosRunnerSessionFor;
-  prewarmAppleRunnerCache: typeof prewarmAppleRunnerCache;
-  prewarmIosRunnerSession: typeof prewarmIosRunnerSession;
-  prepareIosRunner: typeof prepareIosRunner;
-  resolveRunnerAppBundleId: typeof resolveRunnerAppBundleId;
-  hasCachedAppleRunnerArtifact: typeof hasCachedAppleRunnerArtifact;
-  detachIosRunnerSessionsForShutdown: typeof detachIosRunnerSessionsForShutdown;
-  readRunnerSessionLiveness: typeof readRunnerSessionLiveness;
-  releaseIosRunnerOnClose: typeof releaseIosRunnerOnClose;
-  stopIosRunnerSession: typeof stopIosRunnerSession;
-  stopAllIosRunnerSessions: typeof stopAllIosRunnerSessions;
-  runApplePressSeries: typeof runApplePressSeries;
-  cleanupRunnerLeasesForOwner: typeof cleanupRunnerLeasesForOwner;
-  readStaleRunnerLease: typeof readStaleRunnerLease;
-  verifyLeaseRunnerPidIdentity: typeof verifyLeaseRunnerPidIdentity;
-  runnerLeaseCleanupAdapter: typeof runnerLeaseCleanupAdapter;
-  applyXctestRunnerAppIconFromDerivedPath: typeof applyXctestRunnerAppIconFromDerivedPath;
-};
-
-/**
- * Binds the host capabilities and returns the runner operation surface. The
- * runner keeps process-wide state (sessions, leases, provider scopes), so one
- * process gets one host: constructing a second client with a different host
- * reference throws.
- */
-export function createAppleRunnerClient(host: AppleRunnerHost): AppleRunnerClient {
-  bindAppleRunnerHost(host);
-  return {
-    runAppleRunnerCommand,
-    notifyIosRunnerAppRelaunched,
-    hasLiveIosRunnerSession,
-    releaseSpeculativeIosRunnerSessionFor,
-    prewarmAppleRunnerCache,
-    prewarmIosRunnerSession,
-    prepareIosRunner,
-    resolveRunnerAppBundleId,
-    hasCachedAppleRunnerArtifact,
-    detachIosRunnerSessionsForShutdown,
-    readRunnerSessionLiveness,
-    releaseIosRunnerOnClose,
-    stopIosRunnerSession,
-    stopAllIosRunnerSessions,
-    runApplePressSeries,
-    cleanupRunnerLeasesForOwner,
-    readStaleRunnerLease,
-    verifyLeaseRunnerPidIdentity,
-    runnerLeaseCleanupAdapter,
-    applyXctestRunnerAppIconFromDerivedPath,
-  };
-}
diff --git a/packages/platform-apple/src/runner/host.ts b/packages/platform-apple/src/runner/host.ts
index ed6ba3fda7..1c5c9bbb60 100644
--- a/packages/platform-apple/src/runner/host.ts
+++ b/packages/platform-apple/src/runner/host.ts
@@ -25,8 +25,8 @@ import type * as AppleToolProvider from '../core/tool-provider.ts';
  * enters through this object: process execution, diagnostics, retry, process
  * probes, locks, Apple foreground tooling, and physical-device control. The
  * package never imports root implementation files; the composition root
- * (`packages/platform-apple/src/core/runner-client.ts`) constructs the client with the
- * real implementations exactly once per process.
+ * (`packages/platform-apple/src/core/runner-client.ts`) binds the real
+ * implementations exactly once per process.
  *
  * The port is DERIVED from the modules it fronts, never re-typed: the `Pick`
  * lists below are the one place that says which symbol of which module the
@@ -119,7 +119,7 @@ export type {
 let boundHost: AppleRunnerHost | undefined;
 
 /**
- * Binds the process-wide host. Called by `createAppleRunnerClient`; binding a
+ * Binds the process-wide host. Called by the composition root; binding a
  * different host after one is bound throws, because the runner keeps
  * process-wide state (sessions, leases, provider scopes) that cannot serve two
  * hosts. Rebinding the same reference is a no-op.
@@ -134,7 +134,7 @@ export function bindAppleRunnerHost(host: AppleRunnerHost): void {
 function requireHost(): AppleRunnerHost {
   if (!boundHost) {
     throw new Error(
-      'Apple runner host is not bound. Construct the client via createAppleRunnerClient() before using runner operations.',
+      'Apple runner host is not bound. Production binds it in core/runner-client.ts; package tests bind it through runner/test-host.ts.',
     );
   }
   return boundHost;
diff --git a/packages/platform-apple/src/runner/index.ts b/packages/platform-apple/src/runner/index.ts
index 03605c11f9..f61f67599e 100644
--- a/packages/platform-apple/src/runner/index.ts
+++ b/packages/platform-apple/src/runner/index.ts
@@ -1,16 +1,13 @@
 /**
  * @agent-device/platform-apple/runner - the Apple XCUITest runner client.
  *
- * The façade exports the host-free surface only: the client factory, provider
- * seam coordination, pure sequence builders, and types. Host-bound operations
- * (command execution, prewarm/prepare, session lifecycle, leases) exist only
- * on the {@link AppleRunnerClient} returned by {@link createAppleRunnerClient},
- * which the root composition module constructs exactly once with the real host
- * capabilities.
+ * The façade exports the host-free surface only: provider seam coordination,
+ * pure sequence builders, and types. Host-bound operations (command execution,
+ * prewarm/prepare, session lifecycle, leases) are reached through the package
+ * composition root, which binds the real host capabilities exactly once, so
+ * façade consumers never evaluate the implementation.
  */
 
-// The client factory lives behind the './client' subpath so façade consumers
-// (types, pure helpers, runner bundle ids) never evaluate the implementation.
 export type { AppleRunnerHost } from './host.ts';
 export type { RunnerCommand } from './runner-contract.ts';
 export {
diff --git a/packages/platform-apple/src/runner/runner-client.ts b/packages/platform-apple/src/runner/runner-client.ts
index 4706959011..a32b352463 100644
--- a/packages/platform-apple/src/runner/runner-client.ts
+++ b/packages/platform-apple/src/runner/runner-client.ts
@@ -178,7 +178,7 @@ function resolveAppleRunnerRuntime(
   device: DeviceInfo,
   options: { requestId?: string },
 ): AppleRunnerProvider {
-  return resolveAppleRunnerProvider(device, LOCAL_APPLE_RUNNER_RUNTIME, undefined, {
+  return resolveAppleRunnerProvider(device, LOCAL_APPLE_RUNNER_RUNTIME, {
     requestId: options.requestId,
   });
 }
diff --git a/packages/platform-apple/src/runner/runner-command-traits.ts b/packages/platform-apple/src/runner/runner-command-traits.ts
index cdb6be10d2..5e3bcce382 100644
--- a/packages/platform-apple/src/runner/runner-command-traits.ts
+++ b/packages/platform-apple/src/runner/runner-command-traits.ts
@@ -1,51 +1,5 @@
 import type { RunnerCommand } from './runner-contract.ts';
 
-export type RunnerCommandTraitClass =
-  | 'default'
-  | 'readinessPreflightExemptMutation'
-  | 'readOnly'
-  | 'alertAction'
-  | 'readOnlyReadinessProbe'
-  | 'preflightSkippableTouchMutation';
-
-export const RUNNER_COMMAND_TRAIT_MANIFEST = {
-  tap: 'preflightSkippableTouchMutation',
-  mouseClick: 'default',
-  longPress: 'preflightSkippableTouchMutation',
-  drag: 'preflightSkippableTouchMutation',
-  remotePress: 'default',
-  type: 'default',
-  swipe: 'preflightSkippableTouchMutation',
-  scroll: 'preflightSkippableTouchMutation',
-  desktopScroll: 'preflightSkippableTouchMutation',
-  findText: 'readOnly',
-  querySelector: 'readOnly',
-  readText: 'readOnly',
-  snapshot: 'readOnly',
-  screenshot: 'readOnly',
-  back: 'default',
-  backInApp: 'default',
-  backSystem: 'default',
-  home: 'default',
-  rotate: 'default',
-  gesture: 'preflightSkippableTouchMutation',
-  gestureViewport: 'readOnly',
-  appSwitcher: 'default',
-  actionButton: 'default',
-  keyboardDismiss: 'default',
-  keyboardReturn: 'default',
-  alert: 'alertAction',
-  sequence: 'preflightSkippableTouchMutation',
-  recordStart: 'default',
-  recordStop: 'default',
-  status: 'readOnlyReadinessProbe',
-  uptime: 'readOnlyReadinessProbe',
-  activate: 'readinessPreflightExemptMutation',
-  terminate: 'readinessPreflightExemptMutation',
-  targetReset: 'readinessPreflightExemptMutation',
-  shutdown: 'default',
-} as const satisfies Record<RunnerCommand['command'], RunnerCommandTraitClass>;
-
 export type RunnerCommandTraits = Readonly<{
   readOnly: boolean;
   readinessProbe: boolean;
@@ -86,6 +40,55 @@ const PREFLIGHT_SKIPPABLE_TOUCH_MUTATION_TRAITS: RunnerCommandTraits = {
   readinessPreflightSkipEligibleAfterHealthyMutation: true,
 };
 
+type RunnerCommandTraitsEntry =
+  | RunnerCommandTraits
+  | ((command: RunnerCommand) => RunnerCommandTraits);
+
+const readAlertActionTraits = (command: RunnerCommand): RunnerCommandTraits =>
+  (command.action ?? 'get').toLowerCase() === 'get' ? READ_ONLY_TRAITS : DEFAULT_TRAITS;
+
+/**
+ * Traits of every runner command the daemon can send. A command whose traits depend on its
+ * payload maps to a function of the command instead of a fixed trait set.
+ */
+export const RUNNER_COMMAND_TRAITS = {
+  tap: PREFLIGHT_SKIPPABLE_TOUCH_MUTATION_TRAITS,
+  mouseClick: DEFAULT_TRAITS,
+  longPress: PREFLIGHT_SKIPPABLE_TOUCH_MUTATION_TRAITS,
+  drag: PREFLIGHT_SKIPPABLE_TOUCH_MUTATION_TRAITS,
+  remotePress: DEFAULT_TRAITS,
+  type: DEFAULT_TRAITS,
+  swipe: PREFLIGHT_SKIPPABLE_TOUCH_MUTATION_TRAITS,
+  scroll: PREFLIGHT_SKIPPABLE_TOUCH_MUTATION_TRAITS,
+  desktopScroll: PREFLIGHT_SKIPPABLE_TOUCH_MUTATION_TRAITS,
+  findText: READ_ONLY_TRAITS,
+  querySelector: READ_ONLY_TRAITS,
+  readText: READ_ONLY_TRAITS,
+  snapshot: READ_ONLY_TRAITS,
+  screenshot: READ_ONLY_TRAITS,
+  back: DEFAULT_TRAITS,
+  backInApp: DEFAULT_TRAITS,
+  backSystem: DEFAULT_TRAITS,
+  home: DEFAULT_TRAITS,
+  rotate: DEFAULT_TRAITS,
+  gesture: PREFLIGHT_SKIPPABLE_TOUCH_MUTATION_TRAITS,
+  gestureViewport: READ_ONLY_TRAITS,
+  appSwitcher: DEFAULT_TRAITS,
+  actionButton: DEFAULT_TRAITS,
+  keyboardDismiss: DEFAULT_TRAITS,
+  keyboardReturn: DEFAULT_TRAITS,
+  alert: readAlertActionTraits,
+  sequence: PREFLIGHT_SKIPPABLE_TOUCH_MUTATION_TRAITS,
+  recordStart: DEFAULT_TRAITS,
+  recordStop: DEFAULT_TRAITS,
+  status: READ_ONLY_READINESS_PROBE_TRAITS,
+  uptime: READ_ONLY_READINESS_PROBE_TRAITS,
+  activate: READINESS_PREFLIGHT_EXEMPT_MUTATION_TRAITS,
+  terminate: READINESS_PREFLIGHT_EXEMPT_MUTATION_TRAITS,
+  targetReset: READINESS_PREFLIGHT_EXEMPT_MUTATION_TRAITS,
+  shutdown: DEFAULT_TRAITS,
+} as const satisfies Record<RunnerCommand['command'], RunnerCommandTraitsEntry>;
+
 export function isReadOnlyRunnerCommand(command: RunnerCommand): boolean {
   return readRunnerCommandTraits(command).readOnly;
 }
@@ -105,18 +108,6 @@ export function canSkipRunnerReadinessPreflightAfterHealthyMutation(
 }
 
 export function readRunnerCommandTraits(command: RunnerCommand): RunnerCommandTraits {
-  switch (RUNNER_COMMAND_TRAIT_MANIFEST[command.command]) {
-    case 'default':
-      return DEFAULT_TRAITS;
-    case 'readinessPreflightExemptMutation':
-      return READINESS_PREFLIGHT_EXEMPT_MUTATION_TRAITS;
-    case 'readOnly':
-      return READ_ONLY_TRAITS;
-    case 'alertAction':
-      return (command.action ?? 'get').toLowerCase() === 'get' ? READ_ONLY_TRAITS : DEFAULT_TRAITS;
-    case 'readOnlyReadinessProbe':
-      return READ_ONLY_READINESS_PROBE_TRAITS;
-    case 'preflightSkippableTouchMutation':
-      return PREFLIGHT_SKIPPABLE_TOUCH_MUTATION_TRAITS;
-  }
+  const traits: RunnerCommandTraitsEntry = RUNNER_COMMAND_TRAITS[command.command];
+  return typeof traits === 'function' ? traits(command) : traits;
 }
diff --git a/packages/platform-apple/src/runner/runner-error-classification.ts b/packages/platform-apple/src/runner/runner-error-classification.ts
index bbc97a3f7e..882dc73eaf 100644
--- a/packages/platform-apple/src/runner/runner-error-classification.ts
+++ b/packages/platform-apple/src/runner/runner-error-classification.ts
@@ -166,7 +166,7 @@ const PROFILE_UNUSABLE: RunnerErrorRule['buildFailure'] = {
 
 /**
  * The one declaration of runner error classes (#1631), mirroring
- * RUNNER_COMMAND_TRAIT_MANIFEST's role for commands: every recovery predicate
+ * RUNNER_COMMAND_TRAITS' role for commands: every recovery predicate
  * below derives from this table instead of keeping its own substring chain,
  * and since #2680 so does the one classification of startup failures — a row
  * carries recovery verdicts, a `buildFailure` reason and hint, or both.
diff --git a/packages/platform-apple/src/runner/runner-provider.ts b/packages/platform-apple/src/runner/runner-provider.ts
index d76bbf3385..77def22778 100644
--- a/packages/platform-apple/src/runner/runner-provider.ts
+++ b/packages/platform-apple/src/runner/runner-provider.ts
@@ -114,10 +114,8 @@ export function createLocalAppleRunnerProvider(
 export function resolveAppleRunnerProvider(
   device: DeviceInfo,
   fallback: AppleRunnerProvider | AppleRunnerCommandExecutor,
-  provider?: AppleRunnerProvider | AppleRunnerCommandExecutor,
   options: { requestId?: string } = {},
 ): AppleRunnerProvider {
-  if (provider) return normalizeAppleRunnerProvider(provider);
   const scoped = resolveScopedAppleRunnerProvider(device, options);
   return scoped
     ? normalizeAppleRunnerProvider(scoped.provider)

From 7e9031aad96fd3318ec5b1b38a6c10da67d94592 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Wed, 23 Sep 2026 17:28:45 +0200
Subject: [PATCH 051/132] refactor(mcp): project command output schemas from
 their owning family (#2810)

* refactor(mcp): project the replay family output schemas from their owning module

record/trace-style hand entries in src/mcp/command-output-schemas.ts are edited three
layers from the command whose result changed. The docblock already named the end state:
selected executable contracts project their colocated schema into the map. Move the
replay family's two entries into src/commands/replay/index.ts, the descriptors' declared
ownerFile for both commands, and project them through the base map's spread. The
object/enum/number/array schema primitives move to src/commands/command-input.ts, which
already exports the string/boolean/loose ones this file consumes, so both surfaces share
one builder per shape.

Every advertised schema is byte-identical (sha256 of JSON.stringify over all 32 entries),
no entry gains additionalProperties: false, and every eager-closure entry surface keeps
its merge-base module count.

* refactor(mcp): order the output-schema projection last and pin its ownership claim

A hand-written entry added after a spread is accepted silently, while one added before it
fails as TS2783. Moving the replay family spread to the end of BASE_COMMAND_OUTPUT_SCHEMAS
therefore makes a re-hand-authored 'replay' entry a type error instead of a quiet override.
State the enforced invariants only, and tie the projection to the registry: the family test
now asserts every key it projects names this module in its ownerFiles claim.

* refactor(mcp): name the projection invariants the types actually enforce

Drop the migration-status sentence from the map's docblock (AGENTS.md keeps migration status
out of code comments), say what an advertised input object uses instead of the non-strict
object builder, and cut a test comment that only repeated its test name.

* test(mcp): guard projected schema families against silent shadowing in the composed map
---
 src/commands/command-input.ts                 |  25 +++-
 src/commands/replay/index.ts                  |  54 ++++++++
 .../command-tools-replay-schemas.test.ts      | 123 ++++++++++++++++++
 src/mcp/command-output-schemas.ts             |  95 ++++----------
 4 files changed, 222 insertions(+), 75 deletions(-)
 create mode 100644 src/mcp/__tests__/command-tools-replay-schemas.test.ts

diff --git a/src/commands/command-input.ts b/src/commands/command-input.ts
index cc542be6a4..77e66e90a7 100644
--- a/src/commands/command-input.ts
+++ b/src/commands/command-input.ts
@@ -70,6 +70,25 @@ function commandInputSchema(
   };
 }
 
+/**
+ * A non-strict object shape, for what a command RETURNS. It deliberately omits
+ * `additionalProperties: false` and never injects the common device-selection fields, so
+ * additive response fields such as `cost` keep validating. An advertised INPUT object is
+ * built by `commandInputSchema` instead, which is strict and carries those fields.
+ */
+export function objectSchema(
+  properties: Record<string, JsonSchema>,
+  required: readonly string[] = [],
+  description?: string,
+): JsonSchema {
+  return {
+    type: 'object',
+    ...(description ? { description } : {}),
+    properties,
+    ...(required.length > 0 ? { required } : {}),
+  };
+}
+
 function pointSchema(description: string): JsonSchema {
   return {
     type: 'object',
@@ -83,7 +102,7 @@ function pointSchema(description: string): JsonSchema {
   };
 }
 
-function enumSchema(values: readonly string[], description?: string): JsonSchema {
+export function enumSchema(values: readonly string[], description?: string): JsonSchema {
   return { type: 'string', enum: values, ...(description ? { description } : {}) };
 }
 
@@ -91,7 +110,7 @@ export function stringSchema(description?: string): JsonSchema {
   return { type: 'string', ...(description ? { description } : {}) };
 }
 
-function numberSchema(
+export function numberSchema(
   description?: string,
   options: { min?: number; max?: number } = {},
 ): JsonSchema {
@@ -111,7 +130,7 @@ export function booleanSchema(description?: string): JsonSchema {
   return { type: 'boolean', ...(description ? { description } : {}) };
 }
 
-function stringArraySchema(description?: string): JsonSchema {
+export function stringArraySchema(description?: string): JsonSchema {
   return {
     type: 'array',
     items: { type: 'string' },
diff --git a/src/commands/replay/index.ts b/src/commands/replay/index.ts
index ce283c3c31..e57dfcad90 100644
--- a/src/commands/replay/index.ts
+++ b/src/commands/replay/index.ts
@@ -1,13 +1,19 @@
 import type { CommandSchemaOverride } from '@agent-device/command-registry/command-schema';
+import type { CommandResultMap } from '@agent-device/command-registry/command-result';
 import { messageOutput } from '../output-common.ts';
 import { defineCommandFacet, defineCommandFamilyFromFacets } from '../family/types.ts';
+import type { JsonSchema } from '../command-contract.ts';
 import {
   booleanField,
   booleanSchema,
   integerField,
   jsonSchemaField,
+  looseObjectSchema,
+  numberSchema,
+  objectSchema,
   requiredField,
   stringArrayField,
+  stringArraySchema,
   stringField,
   stringSchema,
 } from '../command-input.ts';
@@ -95,6 +101,54 @@ export const testCommandMetadata = defineFieldCommandMetadata(
   },
 );
 
+/**
+ * This family's advertised MCP `outputSchema`s — `ReplayCommandResult` and `ReplaySuiteResult`
+ * (`packages/contracts/src/replay.ts`) — keyed by daemon command name and projected into the
+ * command map by `src/mcp/command-output-schemas.ts`. Non-strict like every other entry: no
+ * `additionalProperties: false`, so additive response fields such as `cost` keep validating.
+ */
+export const REPLAY_COMMAND_OUTPUT_SCHEMAS = {
+  replay: objectSchema(
+    {
+      replayed: numberSchema(),
+      healed: numberSchema(),
+      session: stringSchema(),
+      sessionActive: booleanSchema(
+        'True iff the session is still active — the script had no terminal close.',
+      ),
+      artifactPaths: stringArraySchema(),
+      snapshotDiagnostics: looseObjectSchema(),
+      message: stringSchema(),
+    },
+    ['replayed', 'healed', 'session', 'sessionActive', 'artifactPaths', 'message'],
+  ),
+  test: objectSchema(
+    {
+      total: numberSchema(),
+      executed: numberSchema(),
+      passed: numberSchema(),
+      failed: numberSchema(),
+      skipped: numberSchema(),
+      notRun: numberSchema(),
+      durationMs: numberSchema(),
+      failures: { type: 'array', items: looseObjectSchema() },
+      tests: { type: 'array', items: looseObjectSchema() },
+      snapshotDiagnostics: looseObjectSchema(),
+    },
+    [
+      'total',
+      'executed',
+      'passed',
+      'failed',
+      'skipped',
+      'notRun',
+      'durationMs',
+      'failures',
+      'tests',
+    ],
+  ),
+} satisfies Pick<Record<keyof CommandResultMap, JsonSchema>, 'replay' | 'test'>;
+
 const replayCliSchema = {
   usageOverride: 'replay <path> | replay export <file.ad> [--out <path>]',
   usageFlags: [],
diff --git a/src/mcp/__tests__/command-tools-replay-schemas.test.ts b/src/mcp/__tests__/command-tools-replay-schemas.test.ts
new file mode 100644
index 0000000000..1cf320aafd
--- /dev/null
+++ b/src/mcp/__tests__/command-tools-replay-schemas.test.ts
@@ -0,0 +1,123 @@
+import assert from 'node:assert/strict';
+import { test } from 'vitest';
+import type { ReplayCommandResult, ReplaySuiteResult } from '@agent-device/contracts/replay';
+import { ownerFilesForCommand } from '@agent-device/command-registry/owner-files';
+import { REPLAY_COMMAND_OUTPUT_SCHEMAS } from '../../commands/replay/index.ts';
+import { COMMAND_OUTPUT_SCHEMAS } from '../command-output-schemas.ts';
+import { validateAgainstSchema } from './output-schema-validator.ts';
+
+const REPLAY_RESULT = {
+  replayed: 7,
+  healed: 1,
+  session: 'demo',
+  sessionActive: true,
+  artifactPaths: ['/daemon/artifacts/flow.ad'],
+  snapshotDiagnostics: {
+    stats: { count: 3, p50Ms: 12, p95Ms: 40, maxMs: 40, slowThresholdMs: 100 },
+  },
+  message: 'Replayed 7 steps',
+} satisfies ReplayCommandResult;
+
+const SUITE_RESULT = {
+  total: 2,
+  executed: 1,
+  passed: 1,
+  failed: 0,
+  skipped: 1,
+  notRun: 1,
+  durationMs: 1_200,
+  failures: [],
+  tests: [
+    {
+      file: '/repo/flow.ad',
+      session: 'demo-1',
+      status: 'passed',
+      durationMs: 1_200,
+      attempts: 1,
+      replayed: 7,
+      healed: 0,
+    },
+  ],
+  snapshotDiagnostics: {
+    stats: { count: 3, p50Ms: 12, p95Ms: 40, maxMs: 40, slowThresholdMs: 100 },
+  },
+} satisfies ReplaySuiteResult;
+
+test('MCP replay family output schemas are the family module entries, not copies', () => {
+  assert.equal(COMMAND_OUTPUT_SCHEMAS.replay, REPLAY_COMMAND_OUTPUT_SCHEMAS.replay);
+  assert.equal(COMMAND_OUTPUT_SCHEMAS.test, REPLAY_COMMAND_OUTPUT_SCHEMAS.test);
+});
+
+test('the projected family map declares exactly the commands its module owns', () => {
+  const commands = Object.keys(REPLAY_COMMAND_OUTPUT_SCHEMAS) as ['replay', 'test'];
+  assert.deepEqual(commands, ['replay', 'test']);
+  for (const command of commands) {
+    assert.ok(
+      ownerFilesForCommand(command).includes('src/commands/replay/index.ts'),
+      `${command} projects its output schema from this module but does not name it as its owner`,
+    );
+  }
+});
+
+/**
+ * A projected family is spread into the base map, so two families naming one command would resolve
+ * last-wins with nothing to complain about: the composed map still satisfies
+ * `Record<keyof CommandResultMap, JsonSchema>` and publishes whichever schema spread last. Totality
+ * stays the compiler's; this owns the shadowing half. Every family the seam spreads is listed here,
+ * so registering a new family is the migration step.
+ */
+const PROJECTED_FAMILIES = [{ name: 'replay', schemas: REPLAY_COMMAND_OUTPUT_SCHEMAS }] as const;
+
+test('projected output-schema families claim disjoint commands and survive the composition intact', () => {
+  const claimedBy = new Map<string, string>();
+  for (const family of PROJECTED_FAMILIES) {
+    for (const command of Object.keys(family.schemas)) {
+      const previous = claimedBy.get(command);
+      assert.equal(
+        previous,
+        undefined,
+        `${command} is claimed by both ${previous} and ${family.name}; the later spread would win silently`,
+      );
+      claimedBy.set(command, family.name);
+    }
+  }
+  for (const family of PROJECTED_FAMILIES) {
+    for (const [command, schema] of Object.entries(family.schemas)) {
+      assert.equal(
+        COMMAND_OUTPUT_SCHEMAS[command as keyof typeof COMMAND_OUTPUT_SCHEMAS],
+        schema,
+        `${family.name}.${command} is not the schema the map publishes`,
+      );
+    }
+  }
+});
+
+test('MCP replay outputSchema validates a full result and refuses a dropped required count', () => {
+  assert.deepEqual(validateAgainstSchema(REPLAY_RESULT, COMMAND_OUTPUT_SCHEMAS.replay), []);
+
+  const { healed: _dropped, ...withoutHealed } = REPLAY_RESULT;
+  assert.deepEqual(validateAgainstSchema(withoutHealed, COMMAND_OUTPUT_SCHEMAS.replay), [
+    '$.healed: missing required property',
+  ]);
+});
+
+test('MCP test outputSchema validates a full suite result and refuses a dropped required count', () => {
+  assert.deepEqual(validateAgainstSchema(SUITE_RESULT, COMMAND_OUTPUT_SCHEMAS.test), []);
+
+  const { notRun: _dropped, ...withoutNotRun } = SUITE_RESULT;
+  assert.deepEqual(validateAgainstSchema(withoutNotRun, COMMAND_OUTPUT_SCHEMAS.test), [
+    '$.notRun: missing required property',
+  ]);
+});
+
+test('MCP replay family output schemas stay non-strict for additive response fields', () => {
+  assert.equal(COMMAND_OUTPUT_SCHEMAS.replay.additionalProperties, undefined);
+  assert.equal(COMMAND_OUTPUT_SCHEMAS.test.additionalProperties, undefined);
+  assert.deepEqual(
+    validateAgainstSchema(
+      { ...REPLAY_RESULT, warnings: ['stale ref frame'], cost: { wallClockMs: 12 } },
+      COMMAND_OUTPUT_SCHEMAS.replay,
+    ),
+    [],
+  );
+});
diff --git a/src/mcp/command-output-schemas.ts b/src/mcp/command-output-schemas.ts
index d3b481ebfe..13839625f1 100644
--- a/src/mcp/command-output-schemas.ts
+++ b/src/mcp/command-output-schemas.ts
@@ -1,7 +1,16 @@
 import type { JsonSchema } from '../commands/command-contract.ts';
 import type { CommandResultMap } from '@agent-device/command-registry/command-result';
 import { commandSupportsSettleObservation } from '@agent-device/command-registry/registry';
-import { booleanSchema, looseObjectSchema, stringSchema } from '../commands/command-input.ts';
+import {
+  booleanSchema,
+  enumSchema,
+  looseObjectSchema,
+  numberSchema,
+  objectSchema,
+  stringArraySchema,
+  stringSchema,
+} from '../commands/command-input.ts';
+import { REPLAY_COMMAND_OUTPUT_SCHEMAS } from '../commands/replay/index.ts';
 import { BACK_MODES } from '@agent-device/contracts/back-mode';
 import { NATIVE_PATH_DISPOSITION_VALUES } from '@agent-device/contracts/recording-native-path';
 import { RECORDER_OBSERVATION_VALUES } from '@agent-device/contracts/recording-stop-observation';
@@ -23,9 +32,11 @@ import { DEVICE_TARGETS, PUBLIC_PLATFORMS } from '@agent-device/kernel/device';
  * `outputSchema` key), exactly as `CommandResultMap` omits them rather than
  * inventing a shape.
  *
- * There is no type→JSON-Schema generator in this repo. Schemas remain
- * hand-authored from matching contract types; selected executable contracts can
- * project their colocated schema into this map. Two invariants:
+ * There is no type→JSON-Schema generator in this repo. Schemas are hand-authored from
+ * matching contract types, using the shared JSON-Schema primitives in
+ * `src/commands/command-input.ts`. Where a command family is owned by one module (the
+ * descriptors' `ownerFiles`), that module authors its entries and projects them into this
+ * map instead of being hand-listed here. Two invariants:
  *  - NEVER strict: no `additionalProperties: false` anywhere, so the additive
  *    `cost` object (opted in via `--cost` / `includeCost`) and any other additive
  *    fields ride into `structuredContent` and still validate.
@@ -40,14 +51,6 @@ import { DEVICE_TARGETS, PUBLIC_PLATFORMS } from '@agent-device/kernel/device';
 
 export const DEVICE_KINDS = ['simulator', 'emulator', 'device'] as const;
 
-function numberSchema(description?: string): JsonSchema {
-  return { type: 'number', ...(description ? { description } : {}) };
-}
-
-function enumSchema(values: readonly string[], description?: string): JsonSchema {
-  return { type: 'string', enum: values, ...(description ? { description } : {}) };
-}
-
 function constSchema(value: string): JsonSchema {
   return { type: 'string', const: value };
 }
@@ -56,23 +59,6 @@ function nullableStringSchema(description?: string): JsonSchema {
   return { type: ['string', 'null'], ...(description ? { description } : {}) };
 }
 
-function objectSchema(
-  properties: Record<string, JsonSchema>,
-  required: readonly string[] = [],
-  description?: string,
-): JsonSchema {
-  // Intentionally non-strict (no additionalProperties: false) so additive
-  // fields such as `cost` validate.
-  return {
-    type: 'object',
-    ...(description ? { description } : {}),
-    properties,
-    ...(required.length > 0 ? { required } : {}),
-  };
-}
-
-const stringArraySchema: JsonSchema = { type: 'array', items: { type: 'string' } };
-
 const responseCostSchema: JsonSchema = objectSchema(
   {
     wallClockMs: numberSchema('Total wall-clock time for the request in milliseconds.'),
@@ -122,7 +108,7 @@ function interactionResponseDataSchema(extra: InteractionExtra = {}): JsonSchema
       ),
       ref: stringSchema('Snapshot ref without the @ prefix when the target was an @ref.'),
       selector: stringSchema('Selector expression when the target was a selector.'),
-      selectorChain: stringArraySchema,
+      selectorChain: stringArraySchema(),
       refLabel: stringSchema(),
       targetHittable: booleanSchema(),
       hint: stringSchema(),
@@ -802,52 +788,11 @@ const BASE_COMMAND_OUTPUT_SCHEMAS = {
           ['kind', 'text'],
         ),
       },
-      warnings: stringArraySchema,
+      warnings: stringArraySchema(),
     },
     ['mode', 'baselineInitialized', 'summary', 'lines'],
   ),
 
-  // packages/contracts/src/replay.ts
-  replay: objectSchema(
-    {
-      replayed: numberSchema(),
-      healed: numberSchema(),
-      session: stringSchema(),
-      sessionActive: booleanSchema(
-        'True iff the session is still active — the script had no terminal close.',
-      ),
-      artifactPaths: stringArraySchema,
-      snapshotDiagnostics: looseObjectSchema(),
-      message: stringSchema(),
-    },
-    ['replayed', 'healed', 'session', 'sessionActive', 'artifactPaths', 'message'],
-  ),
-  test: objectSchema(
-    {
-      total: numberSchema(),
-      executed: numberSchema(),
-      passed: numberSchema(),
-      failed: numberSchema(),
-      skipped: numberSchema(),
-      notRun: numberSchema(),
-      durationMs: numberSchema(),
-      failures: { type: 'array', items: looseObjectSchema() },
-      tests: { type: 'array', items: looseObjectSchema() },
-      snapshotDiagnostics: looseObjectSchema(),
-    },
-    [
-      'total',
-      'executed',
-      'passed',
-      'failed',
-      'skipped',
-      'notRun',
-      'durationMs',
-      'failures',
-      'tests',
-    ],
-  ),
-
   // packages/contracts/src/recording.ts
   record: {
     type: 'object',
@@ -911,6 +856,12 @@ const BASE_COMMAND_OUTPUT_SCHEMAS = {
       ),
     ],
   },
+
+  // A family that owns its commands authors their advertised response shape beside the
+  // command surface and projects it here. This spread stays last: a hand-written entry for
+  // a projected command then fails as TS2783 instead of quietly overriding the family's,
+  // and this map's `satisfies` still refuses a missing `CommandResultMap` key.
+  ...REPLAY_COMMAND_OUTPUT_SCHEMAS,
 } satisfies Record<keyof CommandResultMap, JsonSchema>;
 
 export const COMMAND_OUTPUT_SCHEMAS = deriveSettleObservationSchemas(BASE_COMMAND_OUTPUT_SCHEMAS);

From 9b76f600e4ed4b895b1fe3ff17eba3637986949f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Wed, 23 Sep 2026 18:11:48 +0200
Subject: [PATCH 052/132] refactor(ios-runner): key TS runner retry rules on
 typed connect-failure reasons (#2820)

* refactor(ios-runner): key runner retry rules on typed connect-failure reasons

The runner connect path now publishes `details.runnerConnectFailureReason`
(`xcodebuild_exited_early`, `runner_connect_refused`,
`runner_endpoint_probe_exhausted`) where it builds each failure, and the
retry table keys those three rules on that field instead of our own
message text. The remaining text rules read only foreign text (Node's
fetch/net/http errors, Xcode's device-busy text) under a renamed
`foreignMessageIncludesAll` field, each naming its tool.

Test doubles that stood in for these failures now carry the typed reason,
and each converted rule has a test that the reason, not the message,
decides the verdicts.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* refactor(ios-runner): drop the restart composition typed reasons made redundant

With the connect-failure reasons exclusive, no error that grants a restart
before send can also carry a terminal connect verdict, so the restart
predicate reads its own axis. Doc comments now say which failures carry a
BootFailureReason and that the rows above the startup block include
foreign-runtime text matchers.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* test(apple-runner): move connect-retry classification tests to their owning file

runner-client.test.ts asserted shouldRetryRunnerConnectError and
isRetryableRunnerError, both exported by runner-error-classification.ts and
already covered there, growing it past the test-file size ratchet. Move the
one uncovered case (runner_endpoint_probe_exhausted keeps the connect loop
retrying) into runner-error-classification.test.ts and drop the rest as
duplicate message-sniff coverage.

Give runnerConnectFailure a reason-keyed default message so the retry
suite's repeated connect-refused/probe-exhausted fixtures fit on one line
again, bringing runner-command-retry.test.ts back to its merge-base length.

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .../runner/__tests__/runner-client.test.ts    |  30 -----
 .../__tests__/runner-command-retry.test.ts    |  26 ++--
 .../runner-error-classification.test.ts       | 127 ++++++++++++++----
 ...nner-lifecycle-readiness-preflight.test.ts |  11 +-
 .../__tests__/runner-session-fixtures.ts      |  24 ++++
 .../runner-startup-transport.test.ts          |  18 +++
 .../src/runner/runner-error-classification.ts |  76 ++++++++---
 .../src/runner/runner-startup-transport.ts    |   5 +
 8 files changed, 222 insertions(+), 95 deletions(-)

diff --git a/packages/platform-apple/src/runner/__tests__/runner-client.test.ts b/packages/platform-apple/src/runner/__tests__/runner-client.test.ts
index d351529a3b..1e2252e5eb 100644
--- a/packages/platform-apple/src/runner/__tests__/runner-client.test.ts
+++ b/packages/platform-apple/src/runner/__tests__/runner-client.test.ts
@@ -30,10 +30,6 @@ vi.mock('../runner-macos-products.ts', async () => {
 
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import { RUNNER_COMMAND_TRAITS, isReadOnlyRunnerCommand } from '../runner-command-traits.ts';
-import {
-  isRetryableRunnerError,
-  shouldRetryRunnerConnectError,
-} from '../runner-error-classification.ts';
 import { withRunnerCommandId, type RunnerCommand } from '../runner-contract.ts';
 import {
   resolveRunnerBuildDestination,
@@ -412,32 +408,6 @@ test('assertSafeDerivedCleanup allows cleaning override path under project .tmp'
   });
 });
 
-test('shouldRetryRunnerConnectError does not retry xcodebuild early-exit errors', () => {
-  const err = new AppError(
-    'COMMAND_FAILED',
-    'Runner did not accept connection (xcodebuild exited early)',
-  );
-  assert.equal(shouldRetryRunnerConnectError(err), false);
-});
-
-test('shouldRetryRunnerConnectError retries transient connect errors', () => {
-  const err = new AppError('COMMAND_FAILED', 'Runner endpoint probe failed');
-  assert.equal(shouldRetryRunnerConnectError(err), true);
-});
-
-test('isRetryableRunnerError does not retry xcodebuild early-exit errors', () => {
-  const err = new AppError(
-    'COMMAND_FAILED',
-    'Runner did not accept connection (xcodebuild exited early)',
-  );
-  assert.equal(isRetryableRunnerError(err), false);
-});
-
-test('isRetryableRunnerError does not retry busy-connecting errors', () => {
-  const err = new AppError('COMMAND_FAILED', 'Device is busy (Connecting to iPhone)');
-  assert.equal(isRetryableRunnerError(err), false);
-});
-
 test('xctestrunReferencesProjectRoot rejects stale worktree artifacts', async () => {
   const tmpDir = await makeTmpDir();
   const xctestrunPath = path.join(tmpDir, 'AgentDeviceRunner.xctestrun');
diff --git a/packages/platform-apple/src/runner/__tests__/runner-command-retry.test.ts b/packages/platform-apple/src/runner/__tests__/runner-command-retry.test.ts
index 56019ce0ea..e1eb003d7e 100644
--- a/packages/platform-apple/src/runner/__tests__/runner-command-retry.test.ts
+++ b/packages/platform-apple/src/runner/__tests__/runner-command-retry.test.ts
@@ -1,7 +1,7 @@
 import { beforeEach, test, vi } from 'vitest';
 import assert from 'node:assert/strict';
 import { IOS_SIMULATOR } from './device-fixtures.ts';
-import { createTestRequestCancellation } from './runner-session-fixtures.ts';
+import { createTestRequestCancellation, runnerConnectFailure } from './runner-session-fixtures.ts';
 import { AppError } from '@agent-device/kernel/errors';
 import { Deadline } from '../host.ts';
 import { appleRunnerTestHost } from '../test-host.ts';
@@ -71,7 +71,7 @@ test('prepareIosRunner marks a bad restored artifact and rebuilds once after hea
     .mockResolvedValueOnce(fixtures.restoredSession)
     .mockResolvedValueOnce(fixtures.rebuiltSession);
   mockExecuteRunnerCommandWithSession
-    .mockRejectedValueOnce(new AppError('COMMAND_FAILED', 'Runner did not accept connection'))
+    .mockRejectedValueOnce(runnerConnectFailure('runner_connect_refused'))
     .mockResolvedValueOnce({ uptimeMs: 42 });
 
   const result = await prepareIosRunner(IOS_SIMULATOR, {
@@ -110,7 +110,7 @@ test('prepareIosRunner invalidates rebuilt sessions when bad-cache recovery heal
     .mockResolvedValueOnce(restoredSession)
     .mockResolvedValueOnce(rebuiltSession);
   mockExecuteRunnerCommandWithSession
-    .mockRejectedValueOnce(new AppError('COMMAND_FAILED', 'Runner endpoint probe failed'))
+    .mockRejectedValueOnce(runnerConnectFailure('runner_endpoint_probe_exhausted'))
     .mockRejectedValueOnce(new AppError('COMMAND_FAILED', 'Runner health timed out'));
 
   await assert.rejects(
@@ -144,7 +144,7 @@ test('prepareIosRunner retries a fresh launch session when the health check cann
     .mockResolvedValueOnce(stuckSession)
     .mockResolvedValueOnce(relaunchedSession);
   mockExecuteRunnerCommandWithSession
-    .mockRejectedValueOnce(new AppError('COMMAND_FAILED', 'Runner did not accept connection'))
+    .mockRejectedValueOnce(runnerConnectFailure('runner_connect_refused'))
     .mockResolvedValueOnce({ uptimeMs: 42 });
 
   const result = await prepareIosRunner(IOS_SIMULATOR, {
@@ -232,8 +232,8 @@ test('prepareIosRunner does not force a rebuild when the relaunched fresh sessio
     .mockResolvedValueOnce(stuckSession)
     .mockResolvedValueOnce(relaunchedSession);
   mockExecuteRunnerCommandWithSession
-    .mockRejectedValueOnce(new AppError('COMMAND_FAILED', 'Runner did not accept connection'))
-    .mockRejectedValueOnce(new AppError('COMMAND_FAILED', 'Runner did not accept connection'));
+    .mockRejectedValueOnce(runnerConnectFailure('runner_connect_refused'))
+    .mockRejectedValueOnce(runnerConnectFailure('runner_connect_refused'));
 
   await assert.rejects(
     () =>
@@ -261,7 +261,7 @@ test('prepareIosRunner does not relaunch after non-retryable runner startup fail
 
   mockEnsureRunnerSession.mockResolvedValueOnce(failedSession);
   mockExecuteRunnerCommandWithSession.mockRejectedValueOnce(
-    new AppError('COMMAND_FAILED', 'xcodebuild exited early'),
+    runnerConnectFailure('xcodebuild_exited_early'),
   );
 
   await assert.rejects(
@@ -281,7 +281,7 @@ test('prepareIosRunner does not relaunch after request cancellation', async () =
   mockEnsureRunnerSession.mockResolvedValueOnce(stuckSession);
   mockExecuteRunnerCommandWithSession.mockImplementationOnce(() => {
     markRequestCanceled(requestId);
-    throw new AppError('COMMAND_FAILED', 'Runner did not accept connection');
+    throw runnerConnectFailure('runner_connect_refused');
   });
 
   try {
@@ -303,7 +303,7 @@ test('mutating commands restart stale ready sessions when the preflight probe ne
 
   mockEnsureRunnerSession.mockResolvedValueOnce(staleSession).mockResolvedValueOnce(freshSession);
   mockExecuteRunnerCommandWithSession
-    .mockRejectedValueOnce(new AppError('COMMAND_FAILED', 'Runner did not accept connection'))
+    .mockRejectedValueOnce(runnerConnectFailure('runner_connect_refused'))
     .mockResolvedValueOnce({ message: 'tapped' });
 
   const result = await runAppleRunnerCommand(IOS_SIMULATOR, { command: 'tap', x: 120, y: 240 });
@@ -326,7 +326,7 @@ test('mutating commands retry startup sessions with stale bundle cleanup', async
 
   mockEnsureRunnerSession.mockResolvedValueOnce(startupSession).mockResolvedValueOnce(freshSession);
   mockExecuteRunnerCommandWithSession
-    .mockRejectedValueOnce(new AppError('COMMAND_FAILED', 'Runner did not accept connection'))
+    .mockRejectedValueOnce(runnerConnectFailure('runner_connect_refused'))
     .mockResolvedValueOnce({ message: 'tapped' });
 
   const result = await runAppleRunnerCommand(IOS_SIMULATOR, { command: 'tap', x: 120, y: 240 });
@@ -811,7 +811,7 @@ test('mutating commands invalidate the retry session without replaying again', a
 
   mockEnsureRunnerSession.mockResolvedValueOnce(staleSession).mockResolvedValueOnce(freshSession);
   mockExecuteRunnerCommandWithSession
-    .mockRejectedValueOnce(new AppError('COMMAND_FAILED', 'Runner did not accept connection'))
+    .mockRejectedValueOnce(runnerConnectFailure('runner_connect_refused'))
     .mockRejectedValueOnce(new AppError('COMMAND_FAILED', 'fetch failed'))
     .mockResolvedValueOnce({ lifecycleState: 'notAccepted' });
 
@@ -1153,7 +1153,7 @@ test('a failed replacement boot does not consume the request recycle budget', as
   const requestId = 'req-recycle-transient-boot-failure';
   mockEnsureRunnerSession
     .mockResolvedValueOnce(makeRunnerSession({ port: 8100, state: 'ready' }))
-    .mockRejectedValueOnce(new AppError('COMMAND_FAILED', 'Runner did not accept connection'))
+    .mockRejectedValueOnce(runnerConnectFailure('runner_connect_refused'))
     .mockResolvedValueOnce(makeRunnerSession({ port: 8101, state: 'ready' }));
   mockExecuteRunnerCommandWithSession
     .mockRejectedValueOnce(new AppError('COMMAND_FAILED', 'fetch failed'))
@@ -1204,7 +1204,7 @@ test('a later command in the same request cannot pay for a second recycle boot',
 
   mockEnsureRunnerSession.mockResolvedValueOnce(staleSession).mockResolvedValueOnce(freshSession);
   mockExecuteRunnerCommandWithSession
-    .mockRejectedValueOnce(new AppError('COMMAND_FAILED', 'Runner did not accept connection'))
+    .mockRejectedValueOnce(runnerConnectFailure('runner_connect_refused'))
     .mockResolvedValueOnce({ message: 'tapped' });
 
   // First command consumes the request's only recycle via restart-and-replay.
diff --git a/packages/platform-apple/src/runner/__tests__/runner-error-classification.test.ts b/packages/platform-apple/src/runner/__tests__/runner-error-classification.test.ts
index 2ff3beb550..f1936ad802 100644
--- a/packages/platform-apple/src/runner/__tests__/runner-error-classification.test.ts
+++ b/packages/platform-apple/src/runner/__tests__/runner-error-classification.test.ts
@@ -14,6 +14,7 @@ import {
   shouldRestartRunnerBeforeCommandSend,
   shouldRetryRunnerConnectError,
 } from '../runner-error-classification.ts';
+import { runnerConnectFailure } from './runner-session-fixtures.ts';
 
 function commandFailed(message: string, details?: Record<string, unknown>): AppError {
   return new AppError('COMMAND_FAILED', message, details);
@@ -27,12 +28,16 @@ test('every rule carries a unique reason', () => {
 // --- retryable axis (isRetryableRunnerError) ---
 
 test('transport-shaped failures are retryable', () => {
-  for (const message of [
-    'Runner did not accept connection on port 8100',
-    'fetch failed',
-    'connect ECONNREFUSED 127.0.0.1:8100',
-    'socket hang up',
-  ]) {
+  assert.equal(
+    isRetryableRunnerError(
+      runnerConnectFailure(
+        'runner_connect_refused',
+        'Runner did not accept connection on port 8100',
+      ),
+    ),
+    true,
+  );
+  for (const message of ['fetch failed', 'connect ECONNREFUSED 127.0.0.1:8100', 'socket hang up']) {
     assert.equal(isRetryableRunnerError(commandFailed(message)), true, message);
   }
 });
@@ -40,7 +45,10 @@ test('transport-shaped failures are retryable', () => {
 test('boot-shaped failures are not retryable', () => {
   assert.equal(
     isRetryableRunnerError(
-      commandFailed('Runner did not accept connection (xcodebuild exited early)'),
+      runnerConnectFailure(
+        'xcodebuild_exited_early',
+        'Runner did not accept connection (xcodebuild exited early)',
+      ),
     ),
     false,
   );
@@ -51,7 +59,9 @@ test('boot-shaped failures are not retryable', () => {
 });
 
 test('an explicitly retriable flag wins over any message denial', () => {
-  const flagged = commandFailed('xcodebuild exited early', { retriable: true });
+  const flagged = runnerConnectFailure('xcodebuild_exited_early', 'xcodebuild exited early', {
+    retriable: true,
+  });
   assert.equal(isRetryableRunnerError(flagged), true);
 });
 
@@ -64,7 +74,9 @@ test('retryable requires an AppError with COMMAND_FAILED', () => {
 
 test('connect loop keeps waiting by default, including for unknown errors', () => {
   assert.equal(
-    shouldRetryRunnerConnectError(commandFailed('Runner did not accept connection')),
+    shouldRetryRunnerConnectError(
+      runnerConnectFailure('runner_connect_refused', 'Runner did not accept connection'),
+    ),
     true,
   );
   assert.equal(shouldRetryRunnerConnectError(new Error('anything')), true);
@@ -72,7 +84,12 @@ test('connect loop keeps waiting by default, including for unknown errors', () =
 });
 
 test('connect loop stops for terminal verdicts', () => {
-  assert.equal(shouldRetryRunnerConnectError(commandFailed('xcodebuild exited early')), false);
+  assert.equal(
+    shouldRetryRunnerConnectError(
+      runnerConnectFailure('xcodebuild_exited_early', 'xcodebuild exited early'),
+    ),
+    false,
+  );
   const unattached = new AppError('DEVICE_NOT_FOUND', 'device not attached', {
     usbmuxDeviceAttached: false,
   });
@@ -140,27 +157,37 @@ test('a deadline on its own earns no recovery verdict', () => {
 
 test('only a runner that never accepted a connection indicts the cached artifact', () => {
   assert.equal(
-    shouldRebuildCachedRunnerArtifact(commandFailed('Runner endpoint probe failed')),
+    shouldRebuildCachedRunnerArtifact(
+      runnerConnectFailure('runner_endpoint_probe_exhausted', 'Runner endpoint probe failed'),
+    ),
     true,
   );
   assert.equal(
-    shouldRebuildCachedRunnerArtifact(commandFailed('Runner did not accept connection')),
+    shouldRebuildCachedRunnerArtifact(
+      runnerConnectFailure('runner_connect_refused', 'Runner did not accept connection'),
+    ),
     true,
   );
   assert.equal(
     shouldRebuildCachedRunnerArtifact(
-      commandFailed('Runner did not accept connection (simctl spawn)', { port: 8100 }),
+      runnerConnectFailure(
+        'runner_connect_refused',
+        'Runner did not accept connection (simctl spawn)',
+        {
+          port: 8100,
+        },
+      ),
     ),
     true,
   );
-  // Wiping derived data cannot fix a boot that refuses to compile, and its message
-  // otherwise reads as a refused connection.
+  // Wiping derived data cannot fix a boot that refuses to compile.
   assert.equal(
     shouldRebuildCachedRunnerArtifact(
-      commandFailed('Runner did not accept connection (xcodebuild exited early)', {
-        port: 8100,
-        logPath: '/tmp/runner.log',
-      }),
+      runnerConnectFailure(
+        'xcodebuild_exited_early',
+        'Runner did not accept connection (xcodebuild exited early)',
+        { port: 8100, logPath: '/tmp/runner.log' },
+      ),
     ),
     false,
   );
@@ -198,23 +225,67 @@ test('ordinary errors are never session-fatal', () => {
 
 // --- restart-before-send axis (shouldRestartRunnerBeforeCommandSend) ---
 
-test('a refused connection before send restarts the session, case-insensitively', () => {
+test('a refused connection before send restarts the session', () => {
   assert.equal(
-    shouldRestartRunnerBeforeCommandSend(commandFailed('Runner did not accept connection')),
-    true,
-  );
-  assert.equal(
-    shouldRestartRunnerBeforeCommandSend(commandFailed('runner did not accept connection')),
+    shouldRestartRunnerBeforeCommandSend(
+      runnerConnectFailure('runner_connect_refused', 'Runner did not accept connection'),
+    ),
     true,
   );
 });
 
-test('a terminal connect verdict refuses the restart even when the message matches', () => {
-  const both = commandFailed('xcodebuild exited early: runner did not accept connection');
-  assert.equal(shouldRestartRunnerBeforeCommandSend(both), false);
+test('an early exit or a foreign transport failure earns no restart before send', () => {
+  const earlyExit = runnerConnectFailure(
+    'xcodebuild_exited_early',
+    'xcodebuild exited early: runner did not accept connection',
+  );
+  assert.equal(shouldRestartRunnerBeforeCommandSend(earlyExit), false);
   assert.equal(shouldRestartRunnerBeforeCommandSend(commandFailed('socket hang up')), false);
 });
 
+// --- typed connect-failure reasons (agent-device's own connect path) ---
+
+test('xcodebuild_exited_early is decided by the typed reason, not the message', () => {
+  for (const message of ['Runner did not accept connection (xcodebuild exited early)', 'boom']) {
+    const error = runnerConnectFailure('xcodebuild_exited_early', message);
+    assert.equal(isRetryableRunnerError(error), false, message);
+    assert.equal(shouldRetryRunnerConnectError(error), false, message);
+    assert.equal(shouldRebuildCachedRunnerArtifact(error), false, message);
+    assert.equal(shouldRestartRunnerBeforeCommandSend(error), false, message);
+  }
+  // The same words without the reason earn no terminal verdict.
+  const untyped = commandFailed('Runner did not accept connection (xcodebuild exited early)');
+  assert.equal(shouldRetryRunnerConnectError(untyped), true);
+});
+
+test('runner_connect_refused is decided by the typed reason, not the message', () => {
+  for (const message of ['Runner did not accept connection', 'boom']) {
+    const error = runnerConnectFailure('runner_connect_refused', message);
+    assert.equal(isRetryableRunnerError(error), true, message);
+    assert.equal(shouldRetryRunnerConnectError(error), true, message);
+    assert.equal(shouldRebuildCachedRunnerArtifact(error), true, message);
+    assert.equal(shouldRestartRunnerBeforeCommandSend(error), true, message);
+  }
+  const untyped = commandFailed('Runner did not accept connection');
+  assert.equal(isRetryableRunnerError(untyped), false);
+  assert.equal(shouldRebuildCachedRunnerArtifact(untyped), false);
+  assert.equal(shouldRestartRunnerBeforeCommandSend(untyped), false);
+});
+
+test('runner_endpoint_probe_exhausted is decided by the typed reason, not the message', () => {
+  for (const message of ['Runner endpoint probe failed', 'boom']) {
+    const error = runnerConnectFailure('runner_endpoint_probe_exhausted', message);
+    assert.equal(shouldRebuildCachedRunnerArtifact(error), true, message);
+    assert.equal(isRetryableRunnerError(error), false, message);
+    assert.equal(shouldRestartRunnerBeforeCommandSend(error), false, message);
+    assert.equal(shouldRetryRunnerConnectError(error), true, message);
+  }
+  assert.equal(
+    shouldRebuildCachedRunnerArtifact(commandFailed('Runner endpoint probe failed')),
+    false,
+  );
+});
+
 // The literals are what the Swift runner encodes, so they are the contract and not the constant
 // names: a rename on one side has to fail here rather than silently split the pair (#2728).
 test('a refused screen capture keeps the runner reason and stays off the wire code', () => {
diff --git a/packages/platform-apple/src/runner/__tests__/runner-lifecycle-readiness-preflight.test.ts b/packages/platform-apple/src/runner/__tests__/runner-lifecycle-readiness-preflight.test.ts
index dd28f4152a..efe279f753 100644
--- a/packages/platform-apple/src/runner/__tests__/runner-lifecycle-readiness-preflight.test.ts
+++ b/packages/platform-apple/src/runner/__tests__/runner-lifecycle-readiness-preflight.test.ts
@@ -8,7 +8,11 @@ import {
 import { appleRunnerTestHost } from '../test-host.ts';
 import type { RunnerXctestrunArtifact } from '../runner-xctestrun.ts';
 import { IOS_SIMULATOR } from './device-fixtures.ts';
-import { createTestRequestCancellation, makeRunnerSession } from './runner-session-fixtures.ts';
+import {
+  createTestRequestCancellation,
+  makeRunnerSession,
+  runnerConnectFailure,
+} from './runner-session-fixtures.ts';
 
 const {
   mockEnsureRunnerSession,
@@ -216,7 +220,10 @@ test('a boot that exited early does not wipe a restored runner artifact', async
 
   mockEnsureRunnerSession.mockResolvedValueOnce(restoredSession);
   mockExecuteRunnerCommandWithSession.mockRejectedValueOnce(
-    new AppError('COMMAND_FAILED', 'Runner did not accept connection (xcodebuild exited early)'),
+    runnerConnectFailure(
+      'xcodebuild_exited_early',
+      'Runner did not accept connection (xcodebuild exited early)',
+    ),
   );
 
   await assert.rejects(
diff --git a/packages/platform-apple/src/runner/__tests__/runner-session-fixtures.ts b/packages/platform-apple/src/runner/__tests__/runner-session-fixtures.ts
index 2fa54f1694..0aa6a8f605 100644
--- a/packages/platform-apple/src/runner/__tests__/runner-session-fixtures.ts
+++ b/packages/platform-apple/src/runner/__tests__/runner-session-fixtures.ts
@@ -2,11 +2,16 @@ import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import { EventEmitter } from 'node:events';
 import { vi } from 'vitest';
+import { AppError } from '@agent-device/kernel/errors';
 import { IOS_SIMULATOR } from './device-fixtures.ts';
 import { appleRunnerTestHost } from '../test-host.ts';
 import { runnerOwnerStartTime, type RunnerLease } from '../runner-lease.ts';
 import type { RunnerSession } from '../runner-session-types.ts';
 import type { XcodebuildSimulatorSetRedirectHandle } from '../runner-device-set.ts';
+import {
+  runnerConnectFailureDetails,
+  type RunnerConnectFailureReason,
+} from '../runner-error-classification.ts';
 
 // Fabricated runner sessions, leases, background children, and transport
 // payloads shared by the runner-session tests. The child pids here are made up
@@ -71,6 +76,25 @@ export function runnerError(error: { code: string; message: string }): Response
   return new Response(JSON.stringify({ ok: false, error }));
 }
 
+/** Each reason's canonical connect-path message, reused as `runnerConnectFailure`'s default. */
+const RUNNER_CONNECT_FAILURE_MESSAGES: Record<RunnerConnectFailureReason, string> = {
+  runner_connect_refused: 'Runner did not accept connection',
+  runner_endpoint_probe_exhausted: 'Runner endpoint probe failed',
+  xcodebuild_exited_early: 'xcodebuild exited early',
+};
+
+/** A failure in the shape the runner connect path throws: its message plus its typed reason. */
+export function runnerConnectFailure(
+  reason: RunnerConnectFailureReason,
+  message: string = RUNNER_CONNECT_FAILURE_MESSAGES[reason],
+  details?: Record<string, unknown>,
+): AppError {
+  return new AppError('COMMAND_FAILED', message, {
+    ...details,
+    ...runnerConnectFailureDetails(reason),
+  });
+}
+
 // Records everything the runner package emits through host.emitDiagnostic /
 // host.withDiagnosticTimer during `callback` and renders it back as the same
 // newline-delimited-JSON shape a flushed diagnostics session file holds, so
diff --git a/packages/platform-apple/src/runner/__tests__/runner-startup-transport.test.ts b/packages/platform-apple/src/runner/__tests__/runner-startup-transport.test.ts
index 38ae2a55f2..a335e95414 100644
--- a/packages/platform-apple/src/runner/__tests__/runner-startup-transport.test.ts
+++ b/packages/platform-apple/src/runner/__tests__/runner-startup-transport.test.ts
@@ -142,6 +142,22 @@ test('waitForRunner uses simulator fallback within the attempt for ready session
   ]);
 });
 
+test('waitForRunner types a failed simulator fallback as a refused connection', async () => {
+  vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('ECONNREFUSED')));
+  mockRunCmd.mockResolvedValue({ exitCode: 7, stdout: '', stderr: 'curl: (7) Failed to connect' });
+
+  await assert.rejects(
+    () => waitForRunner(iosSimulator, 8100, { command: 'uptime' }, undefined, 100),
+    (error: unknown) => {
+      const appError = error as AppError;
+      assert.equal(appError.message, 'Runner did not accept connection (simctl spawn)');
+      assert.equal(appError.details?.runnerConnectFailureReason, 'runner_connect_refused');
+      return true;
+    },
+  );
+  assert.equal(mockRunCmd.mock.calls.length, 1);
+});
+
 test('waitForRunner wakes a simulator startup retry when the listener reports ready', async () => {
   vi.useFakeTimers();
   const readiness = new AbortController();
@@ -249,6 +265,7 @@ test('waitForRunner preserves xcodebuild diagnostics when the runner exits durin
     (error: unknown) => {
       const appError = error as AppError;
       assert.equal(appError.message, 'Runner did not accept connection (xcodebuild exited early)');
+      assert.equal(appError.details?.runnerConnectFailureReason, 'xcodebuild_exited_early');
       assert.equal(
         (appError.details?.xcodebuild as { exitCode?: number } | undefined)?.exitCode,
         65,
@@ -294,6 +311,7 @@ test('waitForRunner carries the disk-image state when the runner is still alive
     (error: unknown) => {
       const appError = error as AppError;
       assert.equal(appError.message, 'Runner did not accept connection');
+      assert.equal(appError.details?.runnerConnectFailureReason, 'runner_connect_refused');
       assert.equal(appError.details?.developerDiskImage, 'unavailable');
       assert.equal(appError.details?.reason, 'IOS_RUNNER_CONNECT_TIMEOUT');
       assert.doesNotMatch(String(appError.details?.hint), /Unlock the iPhone/);
diff --git a/packages/platform-apple/src/runner/runner-error-classification.ts b/packages/platform-apple/src/runner/runner-error-classification.ts
index 882dc73eaf..32514622aa 100644
--- a/packages/platform-apple/src/runner/runner-error-classification.ts
+++ b/packages/platform-apple/src/runner/runner-error-classification.ts
@@ -21,11 +21,32 @@ export const RUNNER_CACHE_RECOVERY_HINT =
  */
 type RunnerErrorDetailsMatch = (details: AppErrorDetails) => boolean;
 
+/**
+ * Why agent-device's own runner connect path gave up, published in
+ * `details.runnerConnectFailureReason` by the error that path throws. It sits beside
+ * `details.reason` rather than in it: on the refused-connection and early-exit failures
+ * `reason` already carries the `BootFailureReason` the caller's hint answers.
+ */
+export type RunnerConnectFailureReason =
+  | 'xcodebuild_exited_early'
+  | 'runner_connect_refused'
+  | 'runner_endpoint_probe_exhausted';
+
+export function runnerConnectFailureDetails(reason: RunnerConnectFailureReason): {
+  runnerConnectFailureReason: RunnerConnectFailureReason;
+} {
+  return { runnerConnectFailureReason: reason };
+}
+
 type RunnerErrorMatch = {
   /** Required `AppError.code`; absent = any AppError. */
   code?: AppErrorCode;
-  /** Every entry must appear in the lowercased message. */
-  messageIncludesAll?: readonly string[];
+  /**
+   * Every entry must appear in the lowercased message. Only for text a foreign runtime or tool
+   * wrote, which `asAppError` copies into the message verbatim; a failure agent-device produces
+   * publishes a typed detail instead, and its rule keys on that.
+   */
+  foreignMessageIncludesAll?: readonly string[];
   /**
    * Every entry must appear in the lowercased {@link runnerToolText}: our message plus the tool's
    * own `stdout`/`stderr`. Nothing else in `details` is read, so the argv we were asked to run and
@@ -54,6 +75,10 @@ const hasDevToolsSecurityStatus: RunnerErrorDetailsMatch = (details) =>
   typeof details.devToolsSecurityStatus === 'string';
 const hasUsbmuxDeviceUnattached: RunnerErrorDetailsMatch = (details) =>
   details.usbmuxDeviceAttached === false;
+const hasRunnerConnectFailureReason =
+  (reason: RunnerConnectFailureReason): RunnerErrorDetailsMatch =>
+  (details) =>
+    details.runnerConnectFailureReason === reason;
 /**
  * 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
@@ -188,17 +213,21 @@ export const RUNNER_ERROR_RULES: readonly RunnerErrorRule[] = [
     verdicts: { retryable: true, connectRetry: true },
   },
   {
-    // Says `artifactSuspect: false` on purpose: its message also reads as a refused
-    // connection, and a boot that cannot compile is not cured by wiping derived data.
+    // Says `artifactSuspect: false` on purpose: a boot that cannot compile is not cured by wiping
+    // derived data.
     reason: 'xcodebuild_exited_early',
-    match: { code: 'COMMAND_FAILED', messageIncludesAll: ['xcodebuild exited early'] },
+    match: {
+      code: 'COMMAND_FAILED',
+      details: hasRunnerConnectFailureReason('xcodebuild_exited_early'),
+    },
     verdicts: { retryable: false, connectRetry: false, artifactSuspect: false },
   },
   {
     // A device still mid-attachment is not a runner we can talk to yet, and waiting on
     // it inside this request is what the caller's own retry is for.
     reason: 'device_busy_connecting',
-    match: { code: 'COMMAND_FAILED', messageIncludesAll: ['device is busy', 'connecting'] },
+    // Xcode/CoreDevice text: "Device is busy (Connecting to <device>)".
+    match: { code: 'COMMAND_FAILED', foreignMessageIncludesAll: ['device is busy', 'connecting'] },
     verdicts: { retryable: false, connectRetry: false },
   },
   {
@@ -212,7 +241,10 @@ export const RUNNER_ERROR_RULES: readonly RunnerErrorRule[] = [
   },
   {
     reason: 'runner_connect_refused',
-    match: { code: 'COMMAND_FAILED', messageIncludesAll: ['runner did not accept connection'] },
+    match: {
+      code: 'COMMAND_FAILED',
+      details: hasRunnerConnectFailureReason('runner_connect_refused'),
+    },
     verdicts: {
       retryable: true,
       connectRetry: true,
@@ -224,22 +256,28 @@ export const RUNNER_ERROR_RULES: readonly RunnerErrorRule[] = [
     // Every endpoint answered and none of them had a runner: with a restored artifact
     // in hand, that artifact is the common cause.
     reason: 'runner_endpoint_probe_exhausted',
-    match: { code: 'COMMAND_FAILED', messageIncludesAll: ['runner endpoint probe failed'] },
+    match: {
+      code: 'COMMAND_FAILED',
+      details: hasRunnerConnectFailureReason('runner_endpoint_probe_exhausted'),
+    },
     verdicts: { artifactSuspect: true },
   },
   {
     reason: 'fetch_failed',
-    match: { code: 'COMMAND_FAILED', messageIncludesAll: ['fetch failed'] },
+    // Node's fetch (undici) rejects a failed request with TypeError "fetch failed".
+    match: { code: 'COMMAND_FAILED', foreignMessageIncludesAll: ['fetch failed'] },
     verdicts: { retryable: true, connectRetry: true },
   },
   {
     reason: 'econnrefused',
-    match: { code: 'COMMAND_FAILED', messageIncludesAll: ['econnrefused'] },
+    // Node's net socket: "connect ECONNREFUSED <address>".
+    match: { code: 'COMMAND_FAILED', foreignMessageIncludesAll: ['econnrefused'] },
     verdicts: { retryable: true, connectRetry: true },
   },
   {
     reason: 'socket_hang_up',
-    match: { code: 'COMMAND_FAILED', messageIncludesAll: ['socket hang up'] },
+    // Node's http client: "socket hang up" when the peer closes before responding.
+    match: { code: 'COMMAND_FAILED', foreignMessageIncludesAll: ['socket hang up'] },
     verdicts: { retryable: true, connectRetry: true },
   },
   {
@@ -266,7 +304,8 @@ export const RUNNER_ERROR_RULES: readonly RunnerErrorRule[] = [
   // caller and no recovery verdicts, because there is no session to invalidate and nothing was sent
   // to resend. Specific rows precede generic ones: the classifier takes the first match.
   //
-  // Why these rows are text matchers while the rows above key on a code or a typed field:
+  // Why these rows are text matchers while the rows above key on a code, a typed field, or a
+  // foreign runtime's message:
   // `runnerToolText` reads xcodebuild's own prose because that prose is the only publication these
   // failures have — there is no code and no typed field to key on. Its haystack is deliberately
   // narrow: our message plus the tool's stdout/stderr, never the whole details bag, which also
@@ -390,7 +429,7 @@ function matchesRunnerErrorRule(error: AppError, match: RunnerErrorMatch): boole
   if (!matchesRunnerErrorDetails(error, match.details)) return false;
   if (!matchesRunnerToolText(error, match.toolTextIncludesAll)) return false;
   if (!matchesRunnerToolTextLine(error, match.toolTextLineIncludesAll)) return false;
-  return matchesRunnerErrorMessage(error, match.messageIncludesAll);
+  return matchesRunnerErrorMessage(error, match.foreignMessageIncludesAll);
 }
 
 function matchesRunnerErrorDetails(error: AppError, details: RunnerErrorMatch['details']): boolean {
@@ -522,17 +561,10 @@ export function resolveRunnerFatalErrorReason(error: unknown): string | undefine
 /**
  * A connect-shaped failure that surfaced before the command was sent: restart
  * the runner session and replay the command, rather than probing a runner
- * that never accepted the connection. Composed with the connect-retry axis so
- * a terminal connect verdict (cable unattached, xcodebuild exited early)
- * still refuses the restart. Matching is table-driven and therefore
- * case-insensitive, unlike the raw-message check it replaced; the message is
- * our own transport literal, so no real error changes class.
+ * that never accepted the connection.
  */
 export function shouldRestartRunnerBeforeCommandSend(error: unknown): boolean {
-  return (
-    (runnerErrorVerdict(error, 'restartBeforeSend') ?? false) &&
-    shouldRetryRunnerConnectError(error)
-  );
+  return runnerErrorVerdict(error, 'restartBeforeSend') ?? false;
 }
 
 /**
diff --git a/packages/platform-apple/src/runner/runner-startup-transport.ts b/packages/platform-apple/src/runner/runner-startup-transport.ts
index df48f0863b..4eb7ce8488 100644
--- a/packages/platform-apple/src/runner/runner-startup-transport.ts
+++ b/packages/platform-apple/src/runner/runner-startup-transport.ts
@@ -23,6 +23,7 @@ import {
   enrichRunnerStartupFailureWithDeviceStates,
   isUsbmuxDeviceUnattachedError,
   RUNNER_CACHE_RECOVERY_HINT,
+  runnerConnectFailureDetails,
   shouldRetryRunnerConnectError,
   type IosRunnerDeviceStates,
 } from './runner-error-classification.ts';
@@ -296,6 +297,7 @@ function buildRunnerEndpointProbeError(params: {
     port: params.port,
     endpoints: params.endpoints,
     lastError: params.lastError ? String(params.lastError) : undefined,
+    ...runnerConnectFailureDetails('runner_endpoint_probe_exhausted'),
   });
 }
 
@@ -451,6 +453,7 @@ async function postCommandViaSimulator(
         port,
         reason,
         hint: bootFailureHint(reason),
+        ...runnerConnectFailureDetails('runner_connect_refused'),
       };
     },
   );
@@ -500,6 +503,7 @@ function buildRunnerConnectError(params: {
       context: { platform: 'ios', phase: 'connect' },
     }),
     hint: bootFailureHint('IOS_RUNNER_CONNECT_TIMEOUT'),
+    ...runnerConnectFailureDetails('runner_connect_refused'),
   });
   // The other way the connect stage gives up: `xcodebuild` is still alive at the deadline. It gets
   // the same enrichment as the early exit below (#2683).
@@ -539,6 +543,7 @@ export async function buildRunnerEarlyExitError(params: {
     },
     reason,
     hint: resolveRunnerEarlyExitHint(message, output, output, reason),
+    ...runnerConnectFailureDetails('xcodebuild_exited_early'),
   });
   // The build catch is not the only way a runner stops before serving a command. A locked phone lets
   // the build finish and kills `xcodebuild test-without-building` instead, so nothing reaches that

From 81b476066977929515ef77942d5fa80bb76a4631 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Oskar=20Kwa=C5=9Bniewski?= <oskar@okwasniewski.com>
Date: Wed, 23 Sep 2026 18:53:45 +0200
Subject: [PATCH 053/132] fix(ios-runner): log the fast app guard and gesture
 policy only when they change (#2814)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(ios-runner): log the fast app guard and gesture policy only when they change

Two days of one e2e suite left a 374k-line runner.log: 35,080 FAST_APP_GUARD
and 5,612 SYNTHESIZED_GESTURE_POLICY lines, one per command, each restating a
fact that had not changed since the previous command.

Both markers now go through a small RepeatedLogSuppressor keyed by marker (and
gesture kind for the policy): a line is written when the fact differs from the
last one written under that key, and the suppressor is reset with the cached
target so a rebind states the fact once more. COMMAND_ACCEPTED/COMPLETED pairs
are untouched.

Verified on an iOS simulator against Settings: 8 tap commands wrote 1 guard
line and 1 policy line.

* docs(ios-runner): describe the log suppressor without suite-specific numbers

* refactor(ios-runner): two last-written fields replace the log suppressor

Review follow-ups on the deduped per-command markers:
- the RepeatedLogSuppressor class (string keys, lock, autoclosure) is gone;
  the two markers keep a last-written line beside the other target-bound state,
  the policy one keyed by SynthesizedGesturePolicyKind
- the target-reset chorus copied at three sites (host activate, invalidate,
  activate target) is one resetTargetBoundState(), so a rebind through any of
  them restates both markers, as the comment already claimed
- the guard line drops command=, which a deduped line would misreport; the
  command is on the adjacent COMMAND_ACCEPTED line
- the policy line is built by one pure function with its own unit test

* fix(ios-runner): reset log markers on a process rebind and count what they write

refreshCachedTargetIfProcessChanged rebinds the target but only cleared the
text-entry tap, so the new process could lose its guard or policy line. It now
runs resetTargetBoundState. Markers write through runnerMarkerWriter so tests
count emitted lines, and the fast app guard dedup is testable on its own. Drops
the unused command parameter of canUseFastForegroundAppGuard.

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

---------

Co-authored-by: Michał Pierzchała <thymikee@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
---
 .../RunnerTests+CommandExecution.swift        |  6 +-
 .../RunnerTests+Lifecycle.swift               | 67 +++++++++++++++----
 ...RunnerTests+SynthesizedGesturePolicy.swift | 66 +++++++++++++-----
 .../RunnerTests.swift                         |  7 ++
 4 files changed, 113 insertions(+), 33 deletions(-)

diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
index e731ad4e2c..223103f893 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
@@ -1569,8 +1569,7 @@ extension RunnerTests {
 
       let skipExistenceWait = canUseFastForegroundAppGuard(
         activeApp: activeApp,
-        requestedBundleId: requestedBundleId,
-        command: command.command
+        requestedBundleId: requestedBundleId
       )
       if !skipExistenceWait && !activeApp.waitForExistence(timeout: appExistenceTimeout) {
         if let bundleId = requestedBundleId {
@@ -1592,8 +1591,7 @@ extension RunnerTests {
         }
         let skipInteractionExistenceWait = canUseFastForegroundAppGuard(
           activeApp: activeApp,
-          requestedBundleId: requestedBundleId,
-          command: command.command
+          requestedBundleId: requestedBundleId
         )
         if !skipInteractionExistenceWait && !activeApp.waitForExistence(timeout: 2) {
           if let bundleId = requestedBundleId {
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Lifecycle.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Lifecycle.swift
index a74851b5ef..991b554053 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Lifecycle.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Lifecycle.swift
@@ -194,8 +194,17 @@ extension RunnerTests {
     currentApp = app
     currentBundleId = nil
     currentAppProcessIdentifier = nil
+    resetTargetBoundState()
+  }
+
+  /// State that belongs to the currently bound target and must not outlive it: the text-entry tap
+  /// witness, the fresh-process snapshot warmup exemption, and the last-written per-command log
+  /// markers. Every site that binds, rebinds, or drops the target runs this.
+  func resetTargetBoundState() {
     clearRememberedTextEntryTap()
     snapshotXCTestPenaltyWarmupExemptionPending = false
+    lastLoggedFastAppGuardLine = nil
+    lastLoggedGesturePolicyLines.removeAll()
   }
 
   func invalidateCachedTarget(reason: String) {
@@ -205,8 +214,7 @@ extension RunnerTests {
     currentApp = nil
     currentBundleId = nil
     currentAppProcessIdentifier = nil
-    clearRememberedTextEntryTap()
-    snapshotXCTestPenaltyWarmupExemptionPending = false
+    resetTargetBoundState()
   }
 
   func resetTargetAfterExternalRelaunch() -> Response {
@@ -236,7 +244,7 @@ extension RunnerTests {
     )
     currentApp = candidate
     currentAppProcessIdentifier = observedProcessIdentifier
-    clearRememberedTextEntryTap()
+    resetTargetBoundState()
     clearSnapshotXCTestChannelPenalty(reason: "target_process_changed")
     clearPrivateAXAcceptedDepth(reason: "target_process_changed")
     snapshotXCTestPenaltyWarmupExemptionPending = true
@@ -274,22 +282,26 @@ extension RunnerTests {
 
   func canUseFastForegroundAppGuard(
     activeApp: XCUIApplication,
-    requestedBundleId: String?,
-    command: CommandType
+    requestedBundleId: String?
   ) -> Bool {
     guard let requestedBundleId, currentBundleId == requestedBundleId, currentApp != nil else {
       return false
     }
     guard activeApp.state == .runningForeground else { return false }
-    NSLog(
-      "AGENT_DEVICE_RUNNER_FAST_APP_GUARD command=%@ bundle=%@ state=%d",
-      String(describing: command),
-      requestedBundleId,
-      activeApp.state.rawValue
-    )
+    writeFastAppGuardMarker(bundleId: requestedBundleId, state: activeApp.state)
     return true
   }
 
+  func writeFastAppGuardMarker(bundleId: String, state: XCUIApplication.State) {
+    // The command is on the adjacent COMMAND_ACCEPTED line; repeating it here would make a deduped
+    // marker read as if only that command ever passed the guard.
+    let line = "AGENT_DEVICE_RUNNER_FAST_APP_GUARD bundle=\(bundleId) state=\(state.rawValue)"
+    if lastLoggedFastAppGuardLine != line {
+      lastLoggedFastAppGuardLine = line
+      runnerMarkerWriter(line)
+    }
+  }
+
   /// The pid of the one other application holding an active accessibility session, or nil unless
   /// exactly one exists. What this proves is that liveness claim and nothing more: the private AX
   /// client exposes no ordering of `activeApplications`, so this is NOT a foreground owner — it is
@@ -340,8 +352,7 @@ extension RunnerTests {
     currentApp = target
     currentBundleId = bundleId
     currentAppProcessIdentifier = Self.processIdentifier(of: target)
-    clearRememberedTextEntryTap()
-    snapshotXCTestPenaltyWarmupExemptionPending = false
+    resetTargetBoundState()
     beginFirstInteractionStabilization()
     return target
   }
@@ -507,3 +518,33 @@ extension RunnerTests {
     usleep(useconds_t(delay * 1_000_000))
   }
 }
+
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS
+extension RunnerTests {
+  func testResettingTargetBoundStateForgetsTheLastWrittenMarkers() {
+    defer { invalidateCachedTarget(reason: "unit_test_cleanup") }
+    lastLoggedFastAppGuardLine = "AGENT_DEVICE_RUNNER_FAST_APP_GUARD bundle=app state=4"
+    lastLoggedGesturePolicyLines[.scroll] = "AGENT_DEVICE_RUNNER_SYNTHESIZED_GESTURE_POLICY kind=scroll"
+    resetTargetBoundState()
+    XCTAssertNil(lastLoggedFastAppGuardLine, "a rebind must state the guard once more")
+    XCTAssertTrue(lastLoggedGesturePolicyLines.isEmpty, "a rebind must state the policy once more")
+  }
+
+  func testFastAppGuardMarkerWritesOnceUntilTheFactChanges() {
+    var written: [String] = []
+    runnerMarkerWriter = { written.append($0) }
+    defer {
+      runnerMarkerWriter = { NSLog("%@", $0) }
+      invalidateCachedTarget(reason: "unit_test_cleanup")
+    }
+    writeFastAppGuardMarker(bundleId: "com.example.app", state: .runningForeground)
+    writeFastAppGuardMarker(bundleId: "com.example.app", state: .runningForeground)
+    XCTAssertEqual(written.count, 1, "a repeated fact writes no second line")
+    writeFastAppGuardMarker(bundleId: "com.example.other", state: .runningForeground)
+    XCTAssertEqual(written.count, 2, "a changed fact writes a new line")
+    resetTargetBoundState()
+    writeFastAppGuardMarker(bundleId: "com.example.other", state: .runningForeground)
+    XCTAssertEqual(written.count, 3, "a rebind states the same fact once more")
+  }
+}
+#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SynthesizedGesturePolicy.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SynthesizedGesturePolicy.swift
index 15af0ebee6..a74bcd7908 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SynthesizedGesturePolicy.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SynthesizedGesturePolicy.swift
@@ -139,26 +139,60 @@ extension RunnerTests {
     fallbackAttempted: Bool
   ) {
 #if os(iOS)
-    guard let context else {
-      NSLog(
-        "AGENT_DEVICE_RUNNER_SYNTHESIZED_GESTURE_POLICY kind=%@ context=unavailable fallbackAttempted=%@",
-        kind.rawValue,
-        fallbackAttempted.description
-      )
-      return
-    }
-    NSLog(
-      "AGENT_DEVICE_RUNNER_SYNTHESIZED_GESTURE_POLICY kind=%@ axHealth=%@ frameSource=window keyboardPolicy=%@ fallbackPolicy=%@ fallbackAllowed=%@ fallbackAttempted=%@",
-      kind.rawValue,
-      context.accessibilityHealth.rawValue,
-      context.keyboardPolicy.rawValue,
-      context.fallbackPolicy.rawValue,
-      context.allowsXCTestCoordinateFallback.description,
-      fallbackAttempted.description
+    let line = Self.synthesizedGesturePolicyLine(
+      kind: kind,
+      context: context,
+      fallbackAttempted: fallbackAttempted
     )
+    // The same decision for the same gesture kind on every command is one line; a changed policy
+    // (AX health, keyboard, fallback) is a new one.
+    if lastLoggedGesturePolicyLines[kind] != line {
+      lastLoggedGesturePolicyLines[kind] = line
+      runnerMarkerWriter(line)
+    }
 #endif
   }
+
+  static func synthesizedGesturePolicyLine(
+    kind: SynthesizedGesturePolicyKind,
+    context: SynthesizedCoordinateContext?,
+    fallbackAttempted: Bool
+  ) -> String {
+    guard let context else {
+      return "AGENT_DEVICE_RUNNER_SYNTHESIZED_GESTURE_POLICY kind=\(kind.rawValue)"
+        + " context=unavailable fallbackAttempted=\(fallbackAttempted)"
+    }
+    return "AGENT_DEVICE_RUNNER_SYNTHESIZED_GESTURE_POLICY kind=\(kind.rawValue)"
+      + " axHealth=\(context.accessibilityHealth.rawValue) frameSource=window"
+      + " keyboardPolicy=\(context.keyboardPolicy.rawValue)"
+      + " fallbackPolicy=\(context.fallbackPolicy.rawValue)"
+      + " fallbackAllowed=\(context.allowsXCTestCoordinateFallback)"
+      + " fallbackAttempted=\(fallbackAttempted)"
+  }
+}
+
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS && os(iOS)
+extension RunnerTests {
+  func testSynthesizedGesturePolicyMarkerWritesOncePerKindUntilTheDecisionChanges() {
+    var written: [String] = []
+    runnerMarkerWriter = { written.append($0) }
+    defer {
+      runnerMarkerWriter = { NSLog("%@", $0) }
+      invalidateCachedTarget(reason: "unit_test_cleanup")
+    }
+    logSynthesizedGesturePolicyDecision(kind: .coordinateTap, context: nil, fallbackAttempted: false)
+    logSynthesizedGesturePolicyDecision(kind: .coordinateTap, context: nil, fallbackAttempted: false)
+    XCTAssertEqual(written.count, 1, "a repeated decision writes no second line")
+    logSynthesizedGesturePolicyDecision(kind: .scroll, context: nil, fallbackAttempted: false)
+    XCTAssertEqual(written.count, 2, "each gesture kind states its own decision")
+    logSynthesizedGesturePolicyDecision(kind: .coordinateTap, context: nil, fallbackAttempted: true)
+    XCTAssertEqual(written.count, 3, "a changed decision writes a new line")
+    resetTargetBoundState()
+    logSynthesizedGesturePolicyDecision(kind: .coordinateTap, context: nil, fallbackAttempted: true)
+    XCTAssertEqual(written.count, 4, "a rebind states the same decision once more")
+  }
 }
+#endif
 
 #if AGENT_DEVICE_RUNNER_UNIT_TESTS
 extension RunnerTests {
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift
index 594f4e71a4..afee02d03b 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift
@@ -76,6 +76,13 @@ final class RunnerTests: XCTestCase {
   let minRecordingFps = 1
   let maxRecordingFps = 120
   var needsPostSnapshotInteractionDelay = false
+  // Per-command markers that restate a fact of the bound target (the fast app guard, the
+  // synthesized gesture policy per gesture kind) write only when that fact changes; otherwise a
+  // long session fills runner.log with one identical line per command. Cleared with the rest of the
+  // target-bound state so a rebind states the fact once more.
+  var lastLoggedFastAppGuardLine: String?
+  var lastLoggedGesturePolicyLines: [SynthesizedGesturePolicyKind: String] = [:]
+  var runnerMarkerWriter: (String) -> Void = { NSLog("%@", $0) }
   /// When the first interaction after an activation may run, on the monotonic uptime clock.
   /// The guarantee is a minimum gap *since the activation*, not a pause at the interaction:
   /// a caller that already spent that gap elsewhere (an agent's round trip is 190-260 ms)

From 802adbeb911407c7e11d021856cdc2186f895a79 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Oskar=20Kwa=C5=9Bniewski?= <oskar@okwasniewski.com>
Date: Wed, 23 Sep 2026 18:54:30 +0200
Subject: [PATCH 054/132] fix(daemon): refuse to replace a reachable daemon
 newer than the client (#2811)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(daemon): refuse to replace a reachable daemon newer than the client

In a project depending on @e2edev/mobile (pinning agent-device 0.21.6) an
unrelated dependency hoisted agent-device 0.20.8 onto node_modules/.bin.
Running it printed "Replacing daemon (pid 88723, v0.21.6): version mismatch
(client v0.20.8)" and killed the daemon that owned the live e2e session. The
next engine command replaced it back, so every stray old-CLI invocation cost
two daemon restarts and the attached sessions.

A version mismatch now distinguishes direction. A daemon OLDER than the client
is still replaced (the upgrade path). A reachable daemon NEWER than the client
is neither reused nor replaced: the command fails with both versions and the
stop command for a deliberate downgrade. An unreachable newer daemon is dead
and replaced as before.

* fix(daemon): compare daemon versions as SemVer and quote the stop hint

Review follow-ups on the newer-daemon takeover refusal:
- isNewerVersion orders numeric release segments, ranks a release above any
  prerelease of the same base (0.21.13 > 0.21.13-dev, the shape main carries
  between releases) and compares prerelease fields per SemVer; tests cover the
  -dev, rc and build-metadata cases
- restore the readVersion and project-root tests the previous commit replaced
  and append the comparator cases instead
- shell-quote the state dir in the stop hint so it pastes back correctly
- move the sendToDaemon refusal test into its own file; the lifecycle suite is
  past the size tripwire and may not grow

* refactor(host-kit): split the SemVer comparator so each rule reads alone

The Fallow complexity gate flagged compareVersions at cyclomatic 18; release,
prerelease and per-field comparison are now separate functions.

* refactor(daemon): takeover decision as a value, one SemVer comparator

Review follow-ups on the newer-daemon refusal:
- resolveDaemonTakeover returns a typed decision (reuse | replace | refuseNewer)
  instead of a reason string that sometimes throws; the lifecycle layer, which
  already owns the takeover notice and knows the state dir, builds the refusal
  error and its shell-quoted hint. The launch-spec module no longer imports
  device-shell.
- compareVersions is exported from host-kit/version and src/cli/update-check.ts
  uses it, deleting its numeric-collation copy (which ranked 0.12.0 below
  0.12.0-dev and never prompted a -dev build). parseVersion is one anchored
  regex; a malformed version reads as 0.0.0 and the doc says so.
- the loopback daemon fixture and captureStderr move to
  src/__tests__/test-utils/daemon-http-fixture.ts, shared by the lifecycle suite
  and the new refusal test instead of copied.

* fix(daemon): refuse a live newer daemon on any transport it advertises

The refusal keyed off reachability over the client's transport preference, so an
older client with --daemon-transport http replaced a newer socket-only daemon.
Reuse still requires the client's transport; refusal only needs the daemon alive.

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

---------

Co-authored-by: Michał Pierzchała <thymikee@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
---
 .../host-kit/src/internal/version.test.ts     |  31 +++-
 packages/host-kit/src/internal/version.ts     |  66 ++++++++
 packages/host-kit/src/version.ts              |   7 +-
 .../test-utils/daemon-http-fixture.ts         |  74 +++++++++
 src/__tests__/update-check.test.ts            |  26 +++
 src/cli/update-check.ts                       |   5 +-
 .../__tests__/daemon-client-lifecycle.test.ts |  72 +--------
 .../daemon-client-newer-daemon.test.ts        | 134 ++++++++++++++++
 .../__tests__/daemon-launch-spec.test.ts      | 150 +++++++++++++-----
 src/daemon-client/daemon-client-lifecycle.ts  |  39 ++++-
 src/daemon-client/daemon-launch-spec.ts       |  61 +++++--
 11 files changed, 535 insertions(+), 130 deletions(-)
 create mode 100644 src/__tests__/test-utils/daemon-http-fixture.ts
 create mode 100644 src/daemon-client/__tests__/daemon-client-newer-daemon.test.ts

diff --git a/packages/host-kit/src/internal/version.test.ts b/packages/host-kit/src/internal/version.test.ts
index 6e7e164f59..e46f17e3f3 100644
--- a/packages/host-kit/src/internal/version.test.ts
+++ b/packages/host-kit/src/internal/version.test.ts
@@ -5,7 +5,7 @@ import { afterEach, test, vi } from 'vitest';
 import { mkdtempForTestSync } from './tmp-dir.fixtures.ts';
 import { resetAllProcessMemosForTests } from '@agent-device/kernel/ttl-memo';
 import { resolveAgentDeviceProjectRoot } from './project-root.ts';
-import { findProjectRoot, readVersion } from './version.ts';
+import { compareVersions, findProjectRoot, isNewerVersion, readVersion } from './version.ts';
 
 afterEach(() => {
   vi.restoreAllMocks();
@@ -128,3 +128,32 @@ test('from this source tree, the project root is the agent-device manifest, not
   assert.equal(manifest.name, 'agent-device');
   assert.equal(readVersion(), manifest.version);
 });
+
+test('isNewerVersion orders releases numerically per segment', () => {
+  assert.equal(isNewerVersion('0.21.6', '0.20.8'), true);
+  assert.equal(isNewerVersion('0.21.12', '0.21.6'), true);
+  assert.equal(isNewerVersion('1.0.0', '0.21.12'), true);
+  assert.equal(isNewerVersion('0.20.8', '0.21.6'), false);
+  assert.equal(isNewerVersion('0.21.6', '0.21.6'), false);
+});
+
+test('isNewerVersion ranks a release above the prerelease of the same base', () => {
+  // main carries `-dev` between releases (scripts/release-mark-dev.mjs): a released client meeting
+  // a `-dev` daemon of the same base is the upgrade, and the reverse is the downgrade.
+  assert.equal(isNewerVersion('0.21.13', '0.21.13-dev'), true);
+  assert.equal(isNewerVersion('0.21.13-dev', '0.21.13'), false);
+  assert.equal(isNewerVersion('0.21.13-dev', '0.21.12'), true);
+  assert.equal(isNewerVersion('0.21.12', '0.21.13-dev'), false);
+  assert.equal(isNewerVersion('0.21.13-dev', '0.21.13-dev'), false);
+  assert.equal(isNewerVersion('0.21.13-rc.2', '0.21.13-rc.1'), true);
+  assert.equal(isNewerVersion('0.21.13-rc.10', '0.21.13-rc.9'), true);
+  assert.equal(isNewerVersion('0.21.13-beta', '0.21.13-alpha.1'), true);
+  assert.equal(isNewerVersion('0.21.13+build.2', '0.21.13+build.1'), false);
+});
+
+test('compareVersions reads malformed or prefixed versions conservatively', () => {
+  assert.equal(compareVersions('v0.21.13', '0.21.13'), 0);
+  assert.equal(compareVersions('garbage', '0.0.1'), -1);
+  assert.equal(compareVersions('garbage', '0.0.0'), 0);
+  assert.equal(compareVersions('1.2.3.4', '1.2.3'), -1, 'four segments is not a version');
+});
diff --git a/packages/host-kit/src/internal/version.ts b/packages/host-kit/src/internal/version.ts
index bc10587fea..82d9c14823 100644
--- a/packages/host-kit/src/internal/version.ts
+++ b/packages/host-kit/src/internal/version.ts
@@ -31,3 +31,69 @@ export function findProjectRoot(): string {
   projectRootMemo.set('self', resolved);
   return resolved;
 }
+
+/**
+ * Whether `candidate` is a later release than `baseline` (see {@link compareVersions}).
+ */
+export function isNewerVersion(candidate: string, baseline: string): boolean {
+  return compareVersions(candidate, baseline) > 0;
+}
+
+/**
+ * SemVer order for the versions this package publishes: numeric `major.minor.patch` first, then a
+ * release sorts after any prerelease of the same base (`0.21.13` > `0.21.13-dev`, the shape main
+ * carries between releases), and prerelease fields compare per dot-separated field, numerically
+ * when both are numbers and lexically otherwise. Build metadata is ignored. A string that is not a
+ * version at all reads as `0.0.0`, so a malformed version always compares as the oldest.
+ */
+export function compareVersions(left: string, right: string): number {
+  const a = parseVersion(left);
+  const b = parseVersion(right);
+  return compareRelease(a.release, b.release) || comparePrerelease(a.prerelease, b.prerelease);
+}
+
+const SEMVER = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+
+type ParsedVersion = { release: [number, number, number]; prerelease: string[] };
+
+function parseVersion(version: string): ParsedVersion {
+  const match = SEMVER.exec(version.trim());
+  if (!match) return { release: [0, 0, 0], prerelease: [] };
+  return {
+    release: [Number(match[1]), Number(match[2]), Number(match[3])],
+    prerelease: match[4]?.split('.') ?? [],
+  };
+}
+
+function compareRelease(a: ParsedVersion['release'], b: ParsedVersion['release']): number {
+  for (let i = 0; i < 3; i += 1) {
+    if (a[i] !== b[i]) return a[i]! > b[i]! ? 1 : -1;
+  }
+  return 0;
+}
+
+/** A release (no prerelease) sorts after every prerelease of the same base. */
+function comparePrerelease(a: string[], b: string[]): number {
+  if (a.length === 0) return b.length === 0 ? 0 : 1;
+  if (b.length === 0) return -1;
+  const fields = Math.max(a.length, b.length);
+  for (let i = 0; i < fields; i += 1) {
+    const x = a[i];
+    const y = b[i];
+    if (x === undefined) return -1;
+    if (y === undefined) return 1;
+    const order = comparePrereleaseField(x, y);
+    if (order !== 0) return order;
+  }
+  return 0;
+}
+
+/** Numeric fields compare as numbers and sort below alphanumeric ones; the rest compare lexically. */
+function comparePrereleaseField(x: string, y: string): number {
+  if (x === y) return 0;
+  const xNumeric = /^\d+$/.test(x);
+  const yNumeric = /^\d+$/.test(y);
+  if (xNumeric && yNumeric) return Number(x) > Number(y) ? 1 : -1;
+  if (xNumeric !== yNumeric) return xNumeric ? -1 : 1;
+  return x > y ? 1 : -1;
+}
diff --git a/packages/host-kit/src/version.ts b/packages/host-kit/src/version.ts
index 00d05cc677..2db3b9d7a0 100644
--- a/packages/host-kit/src/version.ts
+++ b/packages/host-kit/src/version.ts
@@ -1,2 +1,7 @@
-export { findProjectRoot, readVersion } from './internal/version.ts';
+export {
+  compareVersions,
+  findProjectRoot,
+  isNewerVersion,
+  readVersion,
+} from './internal/version.ts';
 export { DAEMON_SOURCE_ENTRY, isSourceCheckoutProjectRoot } from './internal/project-root.ts';
diff --git a/src/__tests__/test-utils/daemon-http-fixture.ts b/src/__tests__/test-utils/daemon-http-fixture.ts
new file mode 100644
index 0000000000..65dba9ab23
--- /dev/null
+++ b/src/__tests__/test-utils/daemon-http-fixture.ts
@@ -0,0 +1,74 @@
+import http from 'node:http';
+import { listenOnLoopback } from './loopback.ts';
+
+// A loopback stand-in for a running daemon: answers `GET /health`, echoes `responseData` as the
+// result of every `POST /rpc`, and records what it was asked, for the daemon-client tests that
+// decide which daemon a command keeps.
+
+export type HttpDaemonFixture = {
+  server: http.Server;
+  port: number;
+  seenPaths: string[];
+  rpcRequests: Record<string, any>[];
+};
+
+export async function startHttpDaemonFixture(
+  responseData: Record<string, unknown>,
+): Promise<HttpDaemonFixture> {
+  const seenPaths: string[] = [];
+  const rpcRequests: Record<string, any>[] = [];
+  const server = http.createServer((req, res) => {
+    const url = new URL(req.url || '/', 'http://127.0.0.1');
+    seenPaths.push(`${req.method ?? 'GET'} ${url.pathname}`);
+
+    if (req.method === 'GET' && url.pathname === '/health') {
+      res.writeHead(200);
+      res.end('ok');
+      return;
+    }
+
+    if (req.method === 'POST' && url.pathname === '/rpc') {
+      const chunks: Buffer[] = [];
+      req.on('data', (chunk) => {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+      });
+      req.on('end', () => {
+        const rpcRequest = JSON.parse(Buffer.concat(chunks).toString('utf8')) as Record<
+          string,
+          any
+        >;
+        rpcRequests.push(rpcRequest);
+        res.writeHead(200, { 'content-type': 'application/json' });
+        res.end(
+          JSON.stringify({
+            jsonrpc: '2.0',
+            id: rpcRequest.id,
+            result: { ok: true, data: responseData },
+          }),
+        );
+      });
+      return;
+    }
+
+    res.writeHead(404);
+    res.end('not found');
+  });
+  const port = await listenOnLoopback(server);
+  return { server, port, seenPaths, rpcRequests };
+}
+
+/** Swaps `process.stderr.write` for a buffer until `restore`, so a test can read what was printed. */
+export function captureStderr(): { read: () => string; restore: () => void } {
+  const originalWrite = process.stderr.write.bind(process.stderr);
+  let captured = '';
+  (process.stderr as { write: typeof process.stderr.write }).write = ((chunk: unknown) => {
+    captured += String(chunk);
+    return true;
+  }) as typeof process.stderr.write;
+  return {
+    read: () => captured,
+    restore: () => {
+      process.stderr.write = originalWrite;
+    },
+  };
+}
diff --git a/src/__tests__/update-check.test.ts b/src/__tests__/update-check.test.ts
index 903bc31091..58e2baf6b7 100644
--- a/src/__tests__/update-check.test.ts
+++ b/src/__tests__/update-check.test.ts
@@ -87,6 +87,32 @@ test('notifier prints cached upgrade notice once for a newly discovered version'
   assert.equal(cache.prompted, true);
 });
 
+test('notifier treats the release as newer than the -dev build of the same base', () => {
+  // main carries `-dev` between releases; the shared SemVer comparator ranks the release above it,
+  // where numeric string collation ranked it below and never prompted.
+  const stateDir = makeTempStateDir();
+  cleanupPaths.push(stateDir);
+  writeCache(stateDir, {
+    latestVersion: '0.12.0',
+    checkedAt: '2026-03-25T10:00:00.000Z',
+  });
+
+  let stderr = '';
+  vi.spyOn(process.stderr, 'write').mockImplementation(((chunk: unknown) => {
+    stderr += String(chunk);
+    return true;
+  }) as typeof process.stderr.write);
+
+  maybeRunUpgradeNotifier({
+    command: 'devices',
+    currentVersion: '0.12.0-dev',
+    stateDir,
+    flags: {},
+  });
+
+  assert.match(stderr, /Update available: agent-device 0\.12\.0-dev -> 0\.12\.0/);
+});
+
 test('notifier skips repeat prompts after the cached version was already shown', () => {
   const stateDir = makeTempStateDir();
   cleanupPaths.push(stateDir);
diff --git a/src/cli/update-check.ts b/src/cli/update-check.ts
index e430e336a2..6a1e0a7039 100644
--- a/src/cli/update-check.ts
+++ b/src/cli/update-check.ts
@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { runCmdDetached } from '@agent-device/host-kit/command';
+import { compareVersions } from '@agent-device/host-kit/version';
 
 const PACKAGE_NAME = 'agent-device';
 const UPDATE_CHECK_INTERVAL_MS = 14 * 24 * 60 * 60 * 1000;
@@ -168,10 +169,6 @@ function parseTimestamp(value: string | undefined): number | undefined {
   return Number.isNaN(parsed) ? undefined : parsed;
 }
 
-function compareVersions(left: string, right: string): number {
-  return left.localeCompare(right, undefined, { numeric: true });
-}
-
 export function readUpdateCheckWorkerArgs(
   argv: string[],
 ): { cachePath: string; currentVersion: string } | null {
diff --git a/src/daemon-client/__tests__/daemon-client-lifecycle.test.ts b/src/daemon-client/__tests__/daemon-client-lifecycle.test.ts
index 810672ff6b..073f789a58 100644
--- a/src/daemon-client/__tests__/daemon-client-lifecycle.test.ts
+++ b/src/daemon-client/__tests__/daemon-client-lifecycle.test.ts
@@ -28,6 +28,11 @@ import {
   listenOnLoopback,
   supportsLoopbackBind,
 } from '../../__tests__/test-utils/loopback.ts';
+import {
+  captureStderr,
+  startHttpDaemonFixture,
+  type HttpDaemonFixture,
+} from '../../__tests__/test-utils/daemon-http-fixture.ts';
 import { AppError } from '@agent-device/kernel/errors';
 import { runCmdDetachedMonitored, runCmdSync } from '@agent-device/host-kit/command';
 import { shellQuoteIfNeeded } from '@agent-device/kernel/device-shell';
@@ -46,13 +51,6 @@ type DaemonInfoFixture = {
   processStartTime?: string;
 };
 
-type HttpDaemonFixture = {
-  server: http.Server;
-  port: number;
-  seenPaths: string[];
-  rpcRequests: Record<string, any>[];
-};
-
 const mockRunCmdDetached = vi.mocked(runCmdDetachedMonitored);
 const mockRunCmdSync = vi.mocked(runCmdSync);
 const mockSleep = vi.mocked(sleep);
@@ -109,51 +107,6 @@ function writeDaemonLock(
   );
 }
 
-async function startHttpDaemonFixture(
-  responseData: Record<string, unknown>,
-): Promise<HttpDaemonFixture> {
-  const seenPaths: string[] = [];
-  const rpcRequests: Record<string, any>[] = [];
-  const server = http.createServer((req, res) => {
-    const url = new URL(req.url || '/', 'http://127.0.0.1');
-    seenPaths.push(`${req.method ?? 'GET'} ${url.pathname}`);
-
-    if (req.method === 'GET' && url.pathname === '/health') {
-      res.writeHead(200);
-      res.end('ok');
-      return;
-    }
-
-    if (req.method === 'POST' && url.pathname === '/rpc') {
-      const chunks: Buffer[] = [];
-      req.on('data', (chunk) => {
-        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
-      });
-      req.on('end', () => {
-        const rpcRequest = JSON.parse(Buffer.concat(chunks).toString('utf8')) as Record<
-          string,
-          any
-        >;
-        rpcRequests.push(rpcRequest);
-        res.writeHead(200, { 'content-type': 'application/json' });
-        res.end(
-          JSON.stringify({
-            jsonrpc: '2.0',
-            id: rpcRequest.id,
-            result: { ok: true, data: responseData },
-          }),
-        );
-      });
-      return;
-    }
-
-    res.writeHead(404);
-    res.end('not found');
-  });
-  const port = await listenOnLoopback(server);
-  return { server, port, seenPaths, rpcRequests };
-}
-
 /** Like `startHttpDaemonFixture`, but every RPC call returns `errorResult` as an `{ok:false}` result. */
 async function startHttpDaemonErrorFixture(
   errorResult: Record<string, unknown>,
@@ -649,21 +602,6 @@ test('sendToDaemon replaces socket-only daemon metadata when HTTP transport is r
   }
 });
 
-function captureStderr(): { read: () => string; restore: () => void } {
-  const originalWrite = process.stderr.write.bind(process.stderr);
-  let captured = '';
-  (process.stderr as { write: typeof process.stderr.write }).write = ((chunk: unknown) => {
-    captured += String(chunk);
-    return true;
-  }) as typeof process.stderr.write;
-  return {
-    read: () => captured,
-    restore: () => {
-      process.stderr.write = originalWrite;
-    },
-  };
-}
-
 test('sendRequest timeout cleanup uses resolved daemon paths instead of request flags', async (t) => {
   if (!(await supportsLoopbackBind())) {
     t.skip('loopback listeners are not permitted in this environment');
diff --git a/src/daemon-client/__tests__/daemon-client-newer-daemon.test.ts b/src/daemon-client/__tests__/daemon-client-newer-daemon.test.ts
new file mode 100644
index 0000000000..4229f8cc79
--- /dev/null
+++ b/src/daemon-client/__tests__/daemon-client-newer-daemon.test.ts
@@ -0,0 +1,134 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import { afterEach, test, vi } from 'vitest';
+import { mkdtempForTestSync } from '../../__tests__/test-utils/tmp-dir.ts';
+
+vi.mock('@agent-device/host-kit/command', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('@agent-device/host-kit/command')>()),
+  runCmdDetached: vi.fn(),
+  runCmdDetachedMonitored: vi.fn(),
+  runCmdSync: vi.fn(() => ({ exitCode: 1, stdout: '', stderr: '' })),
+}));
+
+import { resolveDaemonPaths } from '../../daemon-resolution.ts';
+import { sendToDaemon } from '../daemon-client.ts';
+import { closeLoopbackServer, supportsLoopbackBind } from '../../__tests__/test-utils/loopback.ts';
+import {
+  captureStderr,
+  startHttpDaemonFixture,
+} from '../../__tests__/test-utils/daemon-http-fixture.ts';
+import { AppError } from '@agent-device/kernel/errors';
+import { runCmdDetachedMonitored } from '@agent-device/host-kit/command';
+
+// The daemon-version half of the takeover ladder (`resolveDaemonTakeover`): an older CLI
+// hoisted onto PATH meets the daemon a newer install started, with live sessions attached. It must
+// neither spawn a replacement nor kill the daemon.
+
+const mockRunCmdDetached = vi.mocked(runCmdDetachedMonitored);
+
+afterEach(() => {
+  mockRunCmdDetached.mockReset();
+  vi.unstubAllEnvs();
+});
+
+test('sendToDaemon refuses to replace a reachable daemon newer than the client', async (t) => {
+  if (!(await supportsLoopbackBind())) {
+    t.skip('loopback listeners are not permitted in this environment');
+    return;
+  }
+  const stateDir = mkdtempForTestSync('agent-device-daemon-newer-refused-');
+  const paths = resolveDaemonPaths(stateDir);
+  const newerDaemon = await startHttpDaemonFixture({ via: 'newer-daemon' });
+  vi.stubEnv('AGENT_DEVICE_STATE_DIR', stateDir);
+  fs.mkdirSync(paths.baseDir, { recursive: true });
+  fs.writeFileSync(
+    paths.infoPath,
+    `${JSON.stringify({
+      token: 'local-secret',
+      pid: 999_999,
+      version: '999.0.0',
+      httpPort: newerDaemon.port,
+      transport: 'http',
+    })}\n`,
+    'utf8',
+  );
+  const stderrCapture = captureStderr();
+
+  try {
+    await assert.rejects(
+      () =>
+        sendToDaemon({
+          session: 'default',
+          command: 'newer-daemon-smoke',
+          positionals: [],
+          flags: { stateDir, daemonTransport: 'http' },
+          meta: { requestId: 'req-newer-daemon' },
+        }),
+      (error: unknown) => {
+        assert.ok(error instanceof AppError);
+        assert.match(error.message, /v999\.0\.0\) is newer than this client/);
+        assert.match(String(error.details?.hint), /agent-device daemon stop --state-dir /);
+        return true;
+      },
+    );
+
+    assert.equal(mockRunCmdDetached.mock.calls.length, 0, 'no replacement daemon is spawned');
+    assert.deepEqual(newerDaemon.seenPaths, ['GET /health']);
+    assert.equal(stderrCapture.read(), '', 'no takeover notice is printed');
+    assert.ok(fs.existsSync(paths.infoPath), 'the newer daemon keeps its metadata');
+  } finally {
+    stderrCapture.restore();
+    await closeLoopbackServer(newerDaemon.server);
+    fs.rmSync(stateDir, { recursive: true, force: true });
+  }
+});
+
+test('sendToDaemon refuses a newer socket-only daemon when the client prefers http', async (t) => {
+  if (!(await supportsLoopbackBind())) {
+    t.skip('loopback listeners are not permitted in this environment');
+    return;
+  }
+  const stateDir = mkdtempForTestSync('agent-device-daemon-newer-socket-only-');
+  const paths = resolveDaemonPaths(stateDir);
+  const newerDaemon = await startHttpDaemonFixture({ via: 'newer-socket-daemon' });
+  vi.stubEnv('AGENT_DEVICE_STATE_DIR', stateDir);
+  fs.mkdirSync(paths.baseDir, { recursive: true });
+  fs.writeFileSync(
+    paths.infoPath,
+    `${JSON.stringify({
+      token: 'local-secret',
+      pid: 999_999,
+      version: '999.0.0',
+      port: newerDaemon.port,
+      transport: 'socket',
+    })}\n`,
+    'utf8',
+  );
+  const stderrCapture = captureStderr();
+
+  try {
+    await assert.rejects(
+      () =>
+        sendToDaemon({
+          session: 'default',
+          command: 'newer-daemon-smoke',
+          positionals: [],
+          flags: { stateDir, daemonTransport: 'http' },
+          meta: { requestId: 'req-newer-socket-daemon' },
+        }),
+      (error: unknown) => {
+        assert.ok(error instanceof AppError);
+        assert.match(error.message, /v999\.0\.0\) is newer than this client/);
+        return true;
+      },
+    );
+
+    assert.equal(mockRunCmdDetached.mock.calls.length, 0, 'no replacement daemon is spawned');
+    assert.equal(stderrCapture.read(), '', 'no takeover notice is printed');
+    assert.ok(fs.existsSync(paths.infoPath), 'the newer daemon keeps its metadata');
+  } finally {
+    stderrCapture.restore();
+    await closeLoopbackServer(newerDaemon.server);
+    fs.rmSync(stateDir, { recursive: true, force: true });
+  }
+});
diff --git a/src/daemon-client/__tests__/daemon-launch-spec.test.ts b/src/daemon-client/__tests__/daemon-launch-spec.test.ts
index 0a9b7f587f..37af703064 100644
--- a/src/daemon-client/__tests__/daemon-launch-spec.test.ts
+++ b/src/daemon-client/__tests__/daemon-launch-spec.test.ts
@@ -5,7 +5,8 @@ import { afterEach, test, vi } from 'vitest';
 import { computeDaemonCodeSignature } from '@agent-device/host-kit/code-signature';
 import {
   resolveDaemonLaunchSpec,
-  resolveDaemonTakeoverReason,
+  resolveDaemonTakeover,
+  type DaemonReachability,
   resolveLocalDaemonCodeIdentity,
 } from '../daemon-launch-spec.ts';
 import { isSourceCheckoutProjectRoot, readVersion } from '@agent-device/host-kit/version';
@@ -100,6 +101,53 @@ test('a source client fingerprints the source entry through the stat-validated c
   }
 });
 
+test('a reachable daemon newer than the client is refused, not replaced', async () => {
+  assert.deepEqual(
+    await resolveDaemonTakeover(runningDaemon({ version: '999.0.0' }), reachable()),
+    {
+      kind: 'refuseNewer',
+      daemonVersion: '999.0.0',
+      clientVersion: readVersion(),
+    },
+  );
+});
+
+test('an unreachable newer daemon is replaced like any version mismatch', async () => {
+  assert.deepEqual(
+    await resolveDaemonTakeover(runningDaemon({ version: '999.0.0' }), unreachable()),
+    {
+      kind: 'replace',
+      reason: `version mismatch (client v${readVersion()})`,
+    },
+  );
+});
+
+test('a newer daemon alive only on a transport the client does not prefer is still refused', async () => {
+  assert.deepEqual(
+    await resolveDaemonTakeover(runningDaemon({ version: '999.0.0' }), onlyOnAnotherTransport()),
+    { kind: 'refuseNewer', daemonVersion: '999.0.0', clientVersion: readVersion() },
+  );
+});
+
+test('a same-version daemon the client transport cannot reach is replaced', async () => {
+  useClientTree(false);
+
+  assert.deepEqual(
+    await resolveDaemonTakeover(
+      runningDaemon({ codeOrigin: 'installed' }),
+      onlyOnAnotherTransport(),
+    ),
+    { kind: 'replace', reason: 'unreachable' },
+  );
+});
+
+test('a reachable daemon older than the client is replaced', async () => {
+  assert.deepEqual(await resolveDaemonTakeover(runningDaemon({ version: '0.0.1' }), reachable()), {
+    kind: 'replace',
+    reason: `version mismatch (client v${readVersion()})`,
+  });
+});
+
 /**
  * Which daemon a command keeps. `daemon-client-lifecycle.test.ts` pins the same
  * decision end to end from a source checkout, which is what this test process runs
@@ -110,6 +158,18 @@ function useClientTree(sourceCheckout: boolean): void {
   vi.mocked(isSourceCheckoutProjectRoot).mockReturnValue(sourceCheckout);
 }
 
+function reachable(): DaemonReachability {
+  return { viaClientTransport: true, onAnyAdvertisedTransport: async () => true };
+}
+
+function unreachable(): DaemonReachability {
+  return { viaClientTransport: false, onAnyAdvertisedTransport: async () => false };
+}
+
+function onlyOnAnotherTransport(): DaemonReachability {
+  return { viaClientTransport: false, onAnyAdvertisedTransport: async () => true };
+}
+
 function runningDaemon(info: {
   version?: string;
   codeOrigin?: 'installed' | 'checkout';
@@ -142,12 +202,12 @@ test('an installed client keeps an installed daemon whose code signature differs
   // whole of the identity either can offer, and the session on the daemon stands.
   useClientTree(false);
 
-  assert.equal(
-    await resolveDaemonTakeoverReason(
+  assert.deepEqual(
+    await resolveDaemonTakeover(
       runningDaemon({ codeOrigin: 'installed', codeSignature: 'some-other-install' }),
-      true,
+      reachable(),
     ),
-    undefined,
+    { kind: 'reuse' },
   );
 });
 
@@ -157,21 +217,24 @@ test('an installed client replaces a daemon that reports a source checkout (#245
   // fingerprint of its own to notice.
   useClientTree(false);
 
-  assert.equal(
-    await resolveDaemonTakeoverReason(
+  assert.deepEqual(
+    await resolveDaemonTakeover(
       runningDaemon({ codeOrigin: 'checkout', codeSignature: 'edited-checkout' }),
-      true,
+      reachable(),
     ),
-    'code origin mismatch (daemon checkout, client installed)',
+    { kind: 'replace', reason: 'code origin mismatch (daemon checkout, client installed)' },
   );
 });
 
 test('an installed client replaces a daemon that predates the code origin field (#2458)', async () => {
   useClientTree(false);
 
-  assert.equal(
-    await resolveDaemonTakeoverReason(runningDaemon({ codeSignature: 'any' }), true),
-    'code origin mismatch (daemon unreported, client installed)',
+  assert.deepEqual(
+    await resolveDaemonTakeover(runningDaemon({ codeSignature: 'any' }), reachable()),
+    {
+      kind: 'replace',
+      reason: 'code origin mismatch (daemon unreported, client installed)',
+    },
   );
 });
 
@@ -180,12 +243,12 @@ test('a source checkout keeps a daemon that reports the same code signature', as
   const ownCodeSignature = await ownCheckoutCodeSignature();
   assert.ok(ownCodeSignature);
 
-  assert.equal(
-    await resolveDaemonTakeoverReason(
+  assert.deepEqual(
+    await resolveDaemonTakeover(
       runningDaemon({ codeOrigin: 'checkout', codeSignature: ownCodeSignature }),
-      true,
+      reachable(),
     ),
-    undefined,
+    { kind: 'reuse' },
   );
 });
 
@@ -194,12 +257,15 @@ test('a source checkout replaces a daemon whose code signature differs', async (
   // notice a daemon serving code its client no longer has.
   useClientTree(true);
 
-  assert.equal(
-    await resolveDaemonTakeoverReason(
+  assert.deepEqual(
+    await resolveDaemonTakeover(
       runningDaemon({ codeOrigin: 'checkout', codeSignature: 'an-older-build' }),
-      true,
+      reachable(),
     ),
-    'code-signature mismatch',
+    {
+      kind: 'replace',
+      reason: 'code-signature mismatch',
+    },
   );
 });
 
@@ -208,12 +274,15 @@ test('a source checkout replaces a daemon that reports an installed package', as
   // nor disprove what an install holds, and must not run it on faith.
   useClientTree(true);
 
-  assert.equal(
-    await resolveDaemonTakeoverReason(
+  assert.deepEqual(
+    await resolveDaemonTakeover(
       runningDaemon({ codeOrigin: 'installed', codeSignature: 'the-published-artifact' }),
-      true,
+      reachable(),
     ),
-    'code origin mismatch (daemon installed, client checkout)',
+    {
+      kind: 'replace',
+      reason: 'code origin mismatch (daemon installed, client checkout)',
+    },
   );
 });
 
@@ -222,21 +291,21 @@ test('a source checkout judges a daemon that predates the code origin field by i
   // comparison they were reused under until now.
   useClientTree(true);
 
-  assert.equal(
-    await resolveDaemonTakeoverReason(runningDaemon({}), true),
-    'code-signature mismatch',
-  );
+  assert.deepEqual(await resolveDaemonTakeover(runningDaemon({}), reachable()), {
+    kind: 'replace',
+    reason: 'code-signature mismatch',
+  });
 });
 
 test('a mismatched version replaces the daemon whichever tree the client runs from', async () => {
-  const expected = `version mismatch (client v${readVersion()})`;
+  const expected = { kind: 'replace', reason: `version mismatch (client v${readVersion()})` };
   for (const sourceCheckout of [false, true]) {
     useClientTree(sourceCheckout);
 
-    assert.equal(
-      await resolveDaemonTakeoverReason(
+    assert.deepEqual(
+      await resolveDaemonTakeover(
         runningDaemon({ version: '0.0.0-mismatch', codeOrigin: 'installed', codeSignature: 'any' }),
-        true,
+        reachable(),
       ),
       expected,
     );
@@ -246,13 +315,18 @@ test('a mismatched version replaces the daemon whichever tree the client runs fr
 test('a reachable daemon of a matching identity survives, an unreachable one does not', async () => {
   useClientTree(false);
 
-  assert.equal(
-    await resolveDaemonTakeoverReason(runningDaemon({ codeOrigin: 'installed' }), true),
-    undefined,
+  assert.deepEqual(
+    await resolveDaemonTakeover(runningDaemon({ codeOrigin: 'installed' }), reachable()),
+    {
+      kind: 'reuse',
+    },
   );
-  assert.equal(
-    await resolveDaemonTakeoverReason(runningDaemon({ codeOrigin: 'installed' }), false),
-    'unreachable',
+  assert.deepEqual(
+    await resolveDaemonTakeover(runningDaemon({ codeOrigin: 'installed' }), unreachable()),
+    {
+      kind: 'replace',
+      reason: 'unreachable',
+    },
   );
 });
 
diff --git a/src/daemon-client/daemon-client-lifecycle.ts b/src/daemon-client/daemon-client-lifecycle.ts
index d8d194e1c3..21c728798b 100644
--- a/src/daemon-client/daemon-client-lifecycle.ts
+++ b/src/daemon-client/daemon-client-lifecycle.ts
@@ -19,7 +19,11 @@ import {
   type DaemonServerMode,
   type DaemonTransportPreference,
 } from '../daemon-resolution.ts';
-import { resolveDaemonLaunchSpec, resolveDaemonTakeoverReason } from './daemon-launch-spec.ts';
+import {
+  resolveDaemonLaunchSpec,
+  resolveDaemonTakeover,
+  type DaemonTakeoverDecision,
+} from './daemon-launch-spec.ts';
 import { PUBLIC_COMMANDS } from '@agent-device/command-registry/catalog';
 
 import {
@@ -181,11 +185,18 @@ async function readReusableLocalDaemon(settings: DaemonClientSettings): Promise<
   const existing = readDaemonInfo(settings.paths.infoPath);
   if (!existing) return null;
 
-  const existingReachable = await canConnectReusableDaemon(existing, settings.transportPreference);
-  const takeoverReason = await resolveDaemonTakeoverReason(existing, existingReachable);
-  if (!takeoverReason) return existing;
+  const viaClientTransport = await canConnectReusableDaemon(existing, settings.transportPreference);
+  const decision = await resolveDaemonTakeover(existing, {
+    viaClientTransport,
+    onAnyAdvertisedTransport: async () =>
+      viaClientTransport || (await canConnectReusableDaemon(existing, 'auto')),
+  });
+  if (decision.kind === 'reuse') return existing;
+  if (decision.kind === 'refuseNewer') {
+    throw newerDaemonRefusedError(existing, decision, settings.paths.baseDir);
+  }
 
-  emitDaemonTakeoverNotice(existing, takeoverReason, settings.paths.baseDir);
+  emitDaemonTakeoverNotice(existing, decision.reason, settings.paths.baseDir);
   await stopDaemonProcessForTakeover(existing);
   removeDaemonInfo(settings.paths.infoPath);
   return null;
@@ -212,6 +223,24 @@ function isDaemonTransportUnavailableError(error: unknown): boolean {
   );
 }
 
+function newerDaemonRefusedError(
+  info: DaemonInfo,
+  decision: Extract<DaemonTakeoverDecision, { kind: 'refuseNewer' }>,
+  stateDir: string,
+): AppError {
+  const { daemonVersion, clientVersion } = decision;
+  return new AppError(
+    'COMMAND_FAILED',
+    `Daemon (pid ${info.pid}, v${daemonVersion}) is newer than this client (v${clientVersion}); refusing to replace it.`,
+    {
+      daemonPid: info.pid,
+      daemonVersion,
+      clientVersion,
+      hint: `Use the agent-device v${daemonVersion} CLI that started it, or stop it deliberately: agent-device daemon stop --state-dir ${shellQuoteIfNeeded(stateDir)}`,
+    },
+  );
+}
+
 function emitDaemonTakeoverNotice(info: DaemonInfo, reason: string, stateDir: string): void {
   try {
     const identity = info.version ? `pid ${info.pid}, v${info.version}` : `pid ${info.pid}`;
diff --git a/src/daemon-client/daemon-launch-spec.ts b/src/daemon-client/daemon-launch-spec.ts
index 645bc89636..d0cd527bb3 100644
--- a/src/daemon-client/daemon-launch-spec.ts
+++ b/src/daemon-client/daemon-launch-spec.ts
@@ -1,7 +1,12 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { AppError } from '@agent-device/kernel/errors';
-import { DAEMON_SOURCE_ENTRY, findProjectRoot, readVersion } from '@agent-device/host-kit/version';
+import {
+  DAEMON_SOURCE_ENTRY,
+  findProjectRoot,
+  isNewerVersion,
+  readVersion,
+} from '@agent-device/host-kit/version';
 import { createTtlMemo } from '@agent-device/kernel/ttl-memo';
 
 import {
@@ -102,25 +107,53 @@ export async function resolveLocalDaemonCodeIdentity(): Promise<LocalDaemonCodeI
   };
 }
 
+/** What to do with the daemon already running on this state directory. */
+export type DaemonTakeoverDecision =
+  | { kind: 'reuse' }
+  | { kind: 'replace'; reason: string }
+  | { kind: 'refuseNewer'; daemonVersion: string; clientVersion: string };
+
 /**
- * Why the daemon already running on this state directory cannot be reused, or
- * `undefined` when it can be.
+ * Reuse needs the daemon on the transport this client will route through; refusal needs only
+ * proof that the daemon is alive, on any transport its metadata advertises. A client whose
+ * transport preference the daemon does not serve must still see a live newer daemon.
+ */
+export type DaemonReachability = {
+  viaClientTransport: boolean;
+  onAnyAdvertisedTransport: () => Promise<boolean>;
+};
+
+/**
+ * One ladder decides reuse, replace, or refuse, so a daemon can never be reused and announced as
+ * replaced, or replaced without a reason to print. The version answers first because it is cheap
+ * and decides alone for the common pair of installed trees; the code identity
+ * (`resolveCodeIdentityMismatch`) answers next and unreachability last.
  *
- * One ladder answers both questions, so a daemon can never be reused and announced as
- * replaced, or replaced without a reason to print. The version answers first because
- * it is cheap and decides alone for the common pair of installed trees; the code
- * identity (`resolveCodeIdentityMismatch`) answers next and unreachability last.
+ * A live daemon NEWER than this client is neither reused nor replaced: it was started by a
+ * newer install that may still own live sessions, and an older binary that a package manager
+ * hoisted onto PATH must not kill it under that install. An unreachable newer daemon is dead and
+ * replaced like any version mismatch.
  */
-export async function resolveDaemonTakeoverReason(
+export async function resolveDaemonTakeover(
   info: DaemonInfo,
-  reachable: boolean,
-): Promise<string | undefined> {
-  if (info.version !== readVersion()) return `version mismatch (client v${readVersion()})`;
+  reachability: DaemonReachability,
+): Promise<DaemonTakeoverDecision> {
+  const clientVersion = readVersion();
+  if (info.version !== clientVersion) {
+    if (
+      info.version &&
+      isNewerVersion(info.version, clientVersion) &&
+      (await reachability.onAnyAdvertisedTransport())
+    ) {
+      return { kind: 'refuseNewer', daemonVersion: info.version, clientVersion };
+    }
+    return { kind: 'replace', reason: `version mismatch (client v${clientVersion})` };
+  }
   const localIdentity = await resolveLocalDaemonCodeIdentity();
   const codeMismatch = resolveCodeIdentityMismatch(localIdentity, info);
-  if (codeMismatch) return codeMismatch;
-  if (!reachable) return 'unreachable';
-  return undefined;
+  if (codeMismatch) return { kind: 'replace', reason: codeMismatch };
+  if (!reachability.viaClientTransport) return { kind: 'replace', reason: 'unreachable' };
+  return { kind: 'reuse' };
 }
 
 /**

From 5c0c4128ad0ed643339acbe94a09acce58e9983c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Wed, 23 Sep 2026 18:55:10 +0200
Subject: [PATCH 055/132] fix(ios): spawn the AX bridge and fold helper inside
 the scoped simulator set (#2818)

* fix(ios): spawn the AX bridge and fold helper inside the scoped simulator set

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* test(ios): prove the adapter carries the simulator set to the bridge start

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .../platform-apple/src/foldable/pose.test.ts  |  6 +--
 packages/platform-apple/src/foldable/pose.ts  |  2 +-
 .../src/foldable/simulator-hid.test.ts        | 25 ++++++++-
 .../src/foldable/simulator-hid.ts             |  8 +--
 .../src/snapshot-source/adapter.test.ts       | 13 ++++-
 .../src/snapshot-source/host.test.ts          | 51 ++++++++++++++++++-
 .../src/snapshot-source/host.ts               | 36 ++++++++-----
 .../src/snapshot-source/lifecycle.test.ts     | 24 ++++++++-
 .../src/snapshot-source/lifecycle.ts          |  2 +-
 .../src/snapshot-source/types.ts              |  4 +-
 .../src/snapshot-target.test.ts               | 29 ++++++++---
 .../platform-apple/src/snapshot-target.ts     |  2 +
 12 files changed, 165 insertions(+), 37 deletions(-)

diff --git a/packages/platform-apple/src/foldable/pose.test.ts b/packages/platform-apple/src/foldable/pose.test.ts
index 244f0b04e5..cfd1bf60ee 100644
--- a/packages/platform-apple/src/foldable/pose.test.ts
+++ b/packages/platform-apple/src/foldable/pose.test.ts
@@ -89,7 +89,7 @@ test('sends the simulator HID pose and reports the pose CoreDevice read back', a
     screen: { display: 'LCD-1', coordinateSpace: 'native-panel', widthPt: 669, heightPt: 951 },
   });
 
-  expect(mockSend).toHaveBeenCalledWith(duo.id, 'open', undefined);
+  expect(mockSend).toHaveBeenCalledWith(duo, 'open', undefined);
   expect(mockHinge).toHaveBeenCalledTimes(2);
 });
 
@@ -162,7 +162,7 @@ test('sends half-open and reports it only once the hinge has stopped', async ()
     hingeAngleDegrees: 130,
     screen: { display: 'LCD-1', coordinateSpace: 'native-panel', widthPt: 669, heightPt: 951 },
   });
-  expect(mockSend).toHaveBeenCalledWith(duo.id, 'half-open', undefined);
+  expect(mockSend).toHaveBeenCalledWith(duo, 'half-open', undefined);
   expect(mockHinge).toHaveBeenCalledTimes(3);
 });
 
@@ -358,7 +358,7 @@ test('reports a custom final angle only after it reaches and holds that angle',
     pose: 'half-open',
     hingeAngleDegrees: 100,
   });
-  expect(mockSend).toHaveBeenCalledWith(duo.id, keyframes, undefined);
+  expect(mockSend).toHaveBeenCalledWith(duo, keyframes, undefined);
 });
 
 test.each([
diff --git a/packages/platform-apple/src/foldable/pose.ts b/packages/platform-apple/src/foldable/pose.ts
index 03e8afe959..16b32a3f61 100644
--- a/packages/platform-apple/src/foldable/pose.ts
+++ b/packages/platform-apple/src/foldable/pose.ts
@@ -45,7 +45,7 @@ export async function setAppleFoldPose(
   const inventory = await queryAppleDisplayInventory(device, { signal: options.signal });
   requireFoldableInventory(device, inventory);
 
-  await sendSimulatorFoldPose(device.id, intent.keyframes ?? pose, options.signal);
+  await sendSimulatorFoldPose(device, intent.keyframes ?? pose, options.signal);
   emitDiagnostic({
     level: 'info',
     phase: 'apple_fold_pose_dispatched',
diff --git a/packages/platform-apple/src/foldable/simulator-hid.test.ts b/packages/platform-apple/src/foldable/simulator-hid.test.ts
index 56f5aaafce..3fc7c397c6 100644
--- a/packages/platform-apple/src/foldable/simulator-hid.test.ts
+++ b/packages/platform-apple/src/foldable/simulator-hid.test.ts
@@ -2,8 +2,11 @@ import { expect, test } from 'vitest';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { withAppleToolProvider, createLocalAppleToolProvider } from '../core/tool-provider.ts';
+import { IOS_SIMULATOR } from '../__tests__/device-fixtures.ts';
 import { sendSimulatorFoldPose } from './simulator-hid.ts';
 
+const selectedDuo = { ...IOS_SIMULATOR, id: 'selected-duo' };
+
 test.each(['success', 'build', 'dispatch', 'cancel'] as const)(
   'HID route targets the UDID, cleans temporary artifacts, and handles %s',
   async (failure) => {
@@ -29,7 +32,7 @@ test.each(['success', 'build', 'dispatch', 'cancel'] as const)(
         },
       }),
       async () => {
-        const operation = sendSimulatorFoldPose('selected-duo', 'half-open', controller.signal);
+        const operation = sendSimulatorFoldPose(selectedDuo, 'half-open', controller.signal);
         if (failure === 'success') await expect(operation).resolves.toBeUndefined();
         else if (failure === 'cancel') await expect(operation).rejects.toThrow('cancelled');
         else
@@ -64,7 +67,25 @@ test('streams all keyframes in one process with a duration-derived timeout', asy
         return { stdout: '', stderr: '', exitCode: 0 };
       },
     }),
-    () => sendSimulatorFoldPose('duo', keyframes),
+    () => sendSimulatorFoldPose(selectedDuo, keyframes),
   );
   expect(dispatches).toBe(1);
 });
+
+test('HID dispatch addresses the UDID inside its scoped simulator set', async () => {
+  const dispatches: string[][] = [];
+  let binary = '';
+  await withAppleToolProvider(
+    createLocalAppleToolProvider({
+      runCommand: async (_command, args) => {
+        if (args.includes('clang')) binary = args.at(-1)!;
+        else dispatches.push(args);
+        return { stdout: '', stderr: '', exitCode: 0 };
+      },
+    }),
+    () => sendSimulatorFoldPose({ ...selectedDuo, simulatorSetPath: '/tmp/scoped-set' }, 'closed'),
+  );
+  expect(dispatches).toEqual([
+    ['simctl', '--set', '/tmp/scoped-set', 'spawn', 'selected-duo', binary, 'closed'],
+  ]);
+});
diff --git a/packages/platform-apple/src/foldable/simulator-hid.ts b/packages/platform-apple/src/foldable/simulator-hid.ts
index ec5e14f179..b59c90cb92 100644
--- a/packages/platform-apple/src/foldable/simulator-hid.ts
+++ b/packages/platform-apple/src/foldable/simulator-hid.ts
@@ -1,14 +1,16 @@
 import path from 'node:path';
 import type { FoldKeyframe, FoldPose } from '@agent-device/contracts/device';
+import type { DeviceInfo } from '@agent-device/kernel/device';
 import { AppError } from '@agent-device/kernel/errors';
 import { execFailureDetails } from '@agent-device/host-kit/command';
 import { makeHostTemporaryDirectory, removeHostDirectory } from '@agent-device/host-kit/host-file';
 import { findProjectRoot } from '@agent-device/host-kit/version';
+import { runSimctlForDevice } from '../core/simctl.ts';
 import { runXcrun } from '../core/tool-provider.ts';
 
 /** Compiles for the selected Xcode and dispatches inside exactly the requested simulator. */
 export async function sendSimulatorFoldPose(
-  udid: string,
+  device: DeviceInfo,
   pose: FoldPose | readonly FoldKeyframe[],
   signal?: AbortSignal,
 ): Promise<void> {
@@ -49,7 +51,7 @@ export async function sendSimulatorFoldPose(
     signal?.throwIfAborted();
     const durationMs = typeof pose === 'string' ? 0 : pose.at(-1)!.atMs;
     const payload = typeof pose === 'string' ? pose : JSON.stringify(pose);
-    const sent = await runXcrun(['simctl', 'spawn', udid, binary, payload], {
+    const sent = await runSimctlForDevice(device, ['spawn', device.id, binary, payload], {
       signal,
       timeoutMs: durationMs + 10_000,
       // simctl must forward termination to the guest before the host kills it.
@@ -60,7 +62,7 @@ export async function sendSimulatorFoldPose(
       throw new AppError(
         'COMMAND_FAILED',
         'Unable to send the simulator hinge pose',
-        execFailureDetails(sent, { reason: 'fold-hid-dispatch-failed', deviceId: udid }),
+        execFailureDetails(sent, { reason: 'fold-hid-dispatch-failed', deviceId: device.id }),
       );
     }
   } finally {
diff --git a/packages/platform-apple/src/snapshot-source/adapter.test.ts b/packages/platform-apple/src/snapshot-source/adapter.test.ts
index 5b9a6fed68..d419def596 100644
--- a/packages/platform-apple/src/snapshot-source/adapter.test.ts
+++ b/packages/platform-apple/src/snapshot-source/adapter.test.ts
@@ -47,9 +47,13 @@ test('the Simulator AX source returns raw acquisition facts and discloses unsupp
 
   try {
     const result = await source.acquire({
-      target: { ...sourceTarget, targetId: 'target-1' },
+      target: { ...sourceTarget, targetId: 'target-1', simulatorSetPath: '/tmp/scoped-set' },
       hint,
     });
+    assert.deepEqual(
+      fixture.startedTargets.map((started) => started.simulatorSetPath),
+      ['/tmp/scoped-set'],
+    );
     assert.equal(fixture.builds, 1);
     // Four identity probes and one clang build: the identity read execs one Xcode-owned binary.
     assert.equal(fixture.runs, 5);
@@ -465,6 +469,7 @@ type AdapterFixture = {
   omitViewport: boolean;
   omitRecovery: boolean;
   diagnostics: Record<string, unknown>[];
+  startedTargets: Array<Parameters<SnapshotSourceHost['start']>[0]>;
 };
 
 function targetForTest() {
@@ -492,6 +497,7 @@ function createAdapterHost(buildDelayMs = 0): AdapterFixture {
     omitViewport: false,
     omitRecovery: false,
     diagnostics: [],
+    startedTargets: [],
   };
   const host: SnapshotSourceHost = {
     ...realHost,
@@ -520,7 +526,10 @@ function createAdapterHost(buildDelayMs = 0): AdapterFixture {
         exitCode: 0,
       };
     },
-    start: () => new AdapterProcess(),
+    start: (target) => {
+      fixture.startedTargets.push(target);
+      return new AdapterProcess();
+    },
     connect: async () => new AdapterSocket(fixture),
     readTargetProcessStartTime: async () => 'target-start',
   };
diff --git a/packages/platform-apple/src/snapshot-source/host.test.ts b/packages/platform-apple/src/snapshot-source/host.test.ts
index f0e35b44f0..893677b787 100644
--- a/packages/platform-apple/src/snapshot-source/host.test.ts
+++ b/packages/platform-apple/src/snapshot-source/host.test.ts
@@ -1,7 +1,14 @@
 import assert from 'node:assert/strict';
-import { test } from 'vitest';
+import { EventEmitter } from 'node:events';
+import { test, vi } from 'vitest';
+import { runCmdBackground } from '@agent-device/host-kit/command';
 import { createSnapshotSourceHost, snapshotSourceSocketPath } from './host.ts';
 
+vi.mock('@agent-device/host-kit/command', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('@agent-device/host-kit/command')>()),
+  runCmdBackground: vi.fn(),
+}));
+
 test('snapshot bridge socket paths stay within the AF_UNIX limit and are target-specific', () => {
   const host = createSnapshotSourceHost();
   const first = snapshotSourceSocketPath(host, 'simulator-1', 'owner-1');
@@ -14,3 +21,45 @@ test('snapshot bridge socket paths stay within the AF_UNIX limit and are target-
   assert.notEqual(first, second);
   assert.notEqual(first, otherOwner);
 });
+
+test.each([
+  ['the default simulator set', undefined, []],
+  ['a scoped simulator set', '/tmp/scoped-set', ['--set', '/tmp/scoped-set']],
+] as const)('the bridge spawns inside %s', (_label, simulatorSetPath, setArgs) => {
+  const spawn = vi.mocked(runCmdBackground);
+  spawn.mockReset();
+  const child = Object.assign(new EventEmitter(), {
+    pid: 4242,
+    exitCode: null,
+    signalCode: null,
+    stderr: null,
+  });
+  spawn.mockReturnValue({
+    child: child as unknown as ReturnType<typeof runCmdBackground>['child'],
+    wait: new Promise(() => {}),
+  });
+
+  const started = createSnapshotSourceHost().start(
+    { udid: 'simulator-1', ...(simulatorSetPath ? { simulatorSetPath } : {}) },
+    '/tmp/bridge',
+    '/tmp/bridge.sock',
+  );
+
+  assert.equal(started.pid, 4242);
+  assert.deepEqual(spawn.mock.calls[0]?.slice(0, 2), [
+    'xcrun',
+    [
+      'simctl',
+      ...setArgs,
+      'spawn',
+      'simulator-1',
+      '/tmp/bridge',
+      'serve',
+      '/tmp/bridge.sock',
+      '--idle-timeout',
+      '60',
+      '--exit-on-disconnect',
+      'false',
+    ],
+  ]);
+});
diff --git a/packages/platform-apple/src/snapshot-source/host.ts b/packages/platform-apple/src/snapshot-source/host.ts
index d658ec3478..b80421d1fe 100644
--- a/packages/platform-apple/src/snapshot-source/host.ts
+++ b/packages/platform-apple/src/snapshot-source/host.ts
@@ -23,8 +23,14 @@ import { emitDiagnostic, withDiagnosticTimer } from '@agent-device/host-kit/diag
 import { findProjectRoot } from '@agent-device/host-kit/version';
 import { SnapshotSourceError, snapshotSourceError } from './errors.ts';
 import { remainingSnapshotSourceMs } from './deadline.ts';
-import type { SnapshotSourceHost, SnapshotSourceProcess, SnapshotSourceSocket } from './types.ts';
+import type {
+  SnapshotSourceHost,
+  SnapshotSourceProcess,
+  SnapshotSourceSocket,
+  SnapshotSourceTarget,
+} from './types.ts';
 import { readSnapshotTargetProcessStartTime } from '../snapshot-process.ts';
+import { buildSimctlArgs } from '../core/simctl.ts';
 
 const BRIDGE_IDLE_TIMEOUT_SECONDS = 60;
 const MAX_PROCESS_LOG_BYTES = 64 * 1024;
@@ -54,7 +60,7 @@ export function createSnapshotSourceHost(): SnapshotSourceHost {
 }
 
 function startSnapshotBridge(
-  udid: string,
+  target: Pick<SnapshotSourceTarget, 'udid' | 'simulatorSetPath'>,
   bridgePath: string,
   socketPath: string,
   options: { signal?: AbortSignal } = {},
@@ -64,18 +70,20 @@ function startSnapshotBridge(
   }
   const started = runCmdBackground(
     'xcrun',
-    [
-      'simctl',
-      'spawn',
-      udid,
-      bridgePath,
-      'serve',
-      socketPath,
-      '--idle-timeout',
-      String(BRIDGE_IDLE_TIMEOUT_SECONDS),
-      '--exit-on-disconnect',
-      'false',
-    ],
+    buildSimctlArgs(
+      [
+        'spawn',
+        target.udid,
+        bridgePath,
+        'serve',
+        socketPath,
+        '--idle-timeout',
+        String(BRIDGE_IDLE_TIMEOUT_SECONDS),
+        '--exit-on-disconnect',
+        'false',
+      ],
+      { simulatorSetPath: target.simulatorSetPath },
+    ),
     {
       allowFailure: true,
       captureOutput: false,
diff --git a/packages/platform-apple/src/snapshot-source/lifecycle.test.ts b/packages/platform-apple/src/snapshot-source/lifecycle.test.ts
index 7b16deae22..c2da49247f 100644
--- a/packages/platform-apple/src/snapshot-source/lifecycle.test.ts
+++ b/packages/platform-apple/src/snapshot-source/lifecycle.test.ts
@@ -53,6 +53,23 @@ test('the bridge manager reuses a healthy per-device helper and stops it exactly
   assert.deepEqual(fixture.processes[0]!.signals, ['SIGTERM']);
 });
 
+test('the helper starts inside the simulator set that owns the target', async () => {
+  const fixture = createLifecycleFixture();
+  const manager = new SnapshotBridgeManager(fixture.host);
+  const scopedTarget = { ...target, simulatorSetPath: '/tmp/scoped-set' };
+
+  await manager.request({
+    target: scopedTarget,
+    bridge,
+    limits,
+    maxDepth: 10,
+    deadline: deadline(),
+  });
+
+  assert.deepEqual(fixture.startedTargets, [scopedTarget]);
+  await manager.close();
+});
+
 test('a new target generation reuses the healthy helper and carries generation per request', async () => {
   const fixture = createLifecycleFixture();
   const manager = new SnapshotBridgeManager(fixture.host);
@@ -368,6 +385,7 @@ type LifecycleFixture = {
   sockets: FakeSocket[];
   diagnostics: Array<Parameters<SnapshotSourceHost['emitDiagnostic']>[0]>;
   socketPaths: string[];
+  startedTargets: Array<Parameters<SnapshotSourceHost['start']>[0]>;
 };
 
 function deadline(signal?: AbortSignal, timeoutMs = limits.maxDurationMs) {
@@ -396,12 +414,14 @@ function createLifecycleFixture(
   const sockets: FakeSocket[] = [];
   const diagnostics: LifecycleFixture['diagnostics'] = [];
   const socketPaths: string[] = [];
+  const startedTargets: LifecycleFixture['startedTargets'] = [];
   const realHost = createSnapshotSourceHost();
   const host: SnapshotSourceHost = {
     ...realHost,
     emitDiagnostic: (event) => diagnostics.push(event),
     readTargetProcessStartTime: async () => options.targetStartTimes?.shift() ?? 'target-start',
-    start: (_udid, _bridgePath, socketPath) => {
+    start: (startedTarget, _bridgePath, socketPath) => {
+      startedTargets.push(startedTarget);
       socketPaths.push(socketPath);
       const process = new FakeProcess(700 + processes.length);
       processes.push(process);
@@ -434,7 +454,7 @@ function createLifecycleFixture(
       return socket;
     },
   };
-  return { host, processes, sockets, diagnostics, socketPaths };
+  return { host, processes, sockets, diagnostics, socketPaths, startedTargets };
 }
 
 class FakeProcess implements SnapshotSourceProcess {
diff --git a/packages/platform-apple/src/snapshot-source/lifecycle.ts b/packages/platform-apple/src/snapshot-source/lifecycle.ts
index 12a02c43ed..d89abcc129 100644
--- a/packages/platform-apple/src/snapshot-source/lifecycle.ts
+++ b/packages/platform-apple/src/snapshot-source/lifecycle.ts
@@ -140,7 +140,7 @@ export class SnapshotBridgeManager {
     const socketPath = snapshotSourceSocketPath(this.host, input.target.udid, this.ownerId);
     await this.host.ensureDirectory(path.dirname(socketPath));
     await this.host.remove(socketPath);
-    const bridgeProcess = this.host.start(input.target.udid, input.bridge.path, socketPath, {
+    const bridgeProcess = this.host.start(input.target, input.bridge.path, socketPath, {
       signal: deadline.signal,
     });
     const session: BridgeSession = {
diff --git a/packages/platform-apple/src/snapshot-source/types.ts b/packages/platform-apple/src/snapshot-source/types.ts
index aaae313b98..2cec940121 100644
--- a/packages/platform-apple/src/snapshot-source/types.ts
+++ b/packages/platform-apple/src/snapshot-source/types.ts
@@ -22,6 +22,8 @@ export type SnapshotSourceTarget = Readonly<{
   generation: string;
   targetId?: string;
   processStartTime?: string;
+  /** Device set that owns `udid`; absent for the default CoreSimulator set. */
+  simulatorSetPath?: string;
 }>;
 
 export type SnapshotSourceRequest = Readonly<{
@@ -82,7 +84,7 @@ export type SnapshotSourceHost = Readonly<{
   homeDirectory(): string;
   run(command: string, args: string[], options?: ExecOptions): Promise<ExecResult>;
   start(
-    udid: string,
+    target: Pick<SnapshotSourceTarget, 'udid' | 'simulatorSetPath'>,
     bridgePath: string,
     socketPath: string,
     options?: { signal?: AbortSignal },
diff --git a/packages/platform-apple/src/snapshot-target.test.ts b/packages/platform-apple/src/snapshot-target.test.ts
index 5d50ac9ff2..08e830ca80 100644
--- a/packages/platform-apple/src/snapshot-target.test.ts
+++ b/packages/platform-apple/src/snapshot-target.test.ts
@@ -19,12 +19,11 @@ const signal = () => new AbortController().signal;
 function targetFixture() {
   const state = { pid: 42, launch: 'launch-a', start: 'start-a' as string | null };
   const run = vi.fn(async (args: string[], _options?: { timeoutMs?: number }) => ({
-    stdout:
-      args[0] === 'spawn'
-        ? `90\t0\tUIKitApplication:com.example.app.beta[wrong][rb-legacy]\n${state.pid}\t0\tUIKitApplication:${app}[${state.launch}][rb-legacy]`
-        : JSON.stringify({
-            devices: { 'com.apple.CoreSimulator.SimRuntime.iOS-26-0': [{ udid: ios.id }] },
-          }),
+    stdout: args.includes('spawn')
+      ? `90\t0\tUIKitApplication:com.example.app.beta[wrong][rb-legacy]\n${state.pid}\t0\tUIKitApplication:${app}[${state.launch}][rb-legacy]`
+      : JSON.stringify({
+          devices: { 'com.apple.CoreSimulator.SimRuntime.iOS-26-0': [{ udid: ios.id }] },
+        }),
     stderr: '',
     exitCode: 0,
   }));
@@ -43,7 +42,7 @@ function targetFixture() {
     runCommand,
     provider,
     resolve,
-    discoveryCount: () => run.mock.calls.filter(([args]) => args[0] === 'spawn').length,
+    discoveryCount: () => run.mock.calls.filter(([args]) => args.includes('spawn')).length,
   };
 }
 
@@ -66,6 +65,22 @@ test('an unchanged OS process reuses its exact app target without another simctl
   });
 });
 
+test('a target in a scoped simulator set carries that set to the bridge', async () => {
+  const fixture = targetFixture();
+  await withAppleToolProvider(fixture.provider, async () => {
+    const target = await fixture.resolve(
+      { ...ios, simulatorSetPath: '/tmp/scoped-set' },
+      app,
+      signal(),
+    );
+    expect(target.simulatorSetPath).toBe('/tmp/scoped-set');
+    expect(fixture.run.mock.calls.map(([args]) => args.slice(0, 2))).toEqual([
+      ['--set', '/tmp/scoped-set'],
+      ['--set', '/tmp/scoped-set'],
+    ]);
+  });
+});
+
 test('PID reuse cannot reuse a target from a different OS process start', async () => {
   const fixture = targetFixture();
   await withAppleToolProvider(fixture.provider, async () => {
diff --git a/packages/platform-apple/src/snapshot-target.ts b/packages/platform-apple/src/snapshot-target.ts
index 544dad5e21..18bce81b92 100644
--- a/packages/platform-apple/src/snapshot-target.ts
+++ b/packages/platform-apple/src/snapshot-target.ts
@@ -23,6 +23,7 @@ export type SimulatorSnapshotTarget = Readonly<{
   generation: string;
   targetId: string;
   processStartTime: string;
+  simulatorSetPath?: string;
 }>;
 
 export type SimulatorSnapshotTargetResolver = (
@@ -106,6 +107,7 @@ async function resolveSimulatorSnapshotTarget(
     generation: `${job.pid}:${job.label}:${processStartTime}`,
     targetId: `${device.id}:${appBundleId}`,
     processStartTime,
+    ...(device.simulatorSetPath ? { simulatorSetPath: device.simulatorSetPath } : {}),
   });
 }
 

From 339524268706a9f2b7c987f2ceb4ea3f6200befc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Wed, 23 Sep 2026 18:55:10 +0200
Subject: [PATCH 056/132] refactor(ios): one simctl --set builder and one
 simulator state parser (#2824)

* refactor(ios): build every simctl set prefix in core/simctl and merge the state parsers

Every simctl call site now scopes its argv through core/simctl.ts
(scopeSimctlArgs/scopeSimctlArgsForDevice for the host tool seam,
buildSimctlArgs/buildSimctlArgsForDevice for xcrun), and every direct run
goes through runSimctlForDevice. The runSimctl/simctlArgs alias in
apps-simctl.ts, the simulator-state.ts builder, and the screenshot shims
are gone.

The two `simctl list devices -j` state parsers collapse into
readSimctlDeviceState; the snapshot target's runtime projection shares
its raw reader. Inventory keeps its strict projection.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* refactor(ios): fold the missing-app output check into its only caller

apps-simctl.ts held nothing simctl-related once its runner alias was
gone; the devicectl uninstall path is its only consumer. Also states the
device-list reader's real throw contract.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(ios): keep the simctl device-list parser in the already-eager simctl module

Extracting the shared simctl-list-devices parser into its own module added a
new static edge to platform-apple/src/core/simulator.ts, tripping the
simulator-facade eager-closure budget (24 -> 25). Fold the parser into
core/simctl.ts, which simulator.ts already evaluates, instead of giving it a
new file.

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .../src/core/__tests__/app-device-io.test.ts  |  5 +-
 .../src/core/__tests__/app-resolution.test.ts |  5 +-
 .../src/core/__tests__/simctl.test.ts         | 77 ++++++++++++++++++-
 .../platform-apple/src/core/app-device-io.ts  |  8 +-
 .../platform-apple/src/core/app-launch.ts     |  8 +-
 .../platform-apple/src/core/app-resolution.ts |  6 +-
 .../platform-apple/src/core/app-settings.ts   | 29 ++++---
 .../platform-apple/src/core/apps-simctl.ts    | 23 ------
 .../src/core/physical-device-apps.ts          |  9 ++-
 .../src/core/screenshot-status-bar.ts         | 12 +--
 .../platform-apple/src/core/screenshot.ts     | 19 +++--
 .../src/core/settings-text-size.ts            |  6 +-
 packages/platform-apple/src/core/simctl.ts    | 53 ++++++++++---
 packages/platform-apple/src/core/simulator.ts | 17 +---
 .../platform-apple/src/deployment/runtime.ts  | 11 ++-
 .../platform-apple/src/logs/log-predicate.ts  | 33 ++++----
 packages/platform-apple/src/logs/start.ts     |  4 +-
 .../platform-apple/src/network/runtime.ts     |  6 +-
 .../platform-apple/src/readiness/runtime.ts   | 13 +++-
 .../platform-apple/src/shutdown/runtime.ts    |  5 +-
 .../platform-apple/src/simulator-inventory.ts |  4 +-
 .../platform-apple/src/simulator-state.ts     | 20 +----
 .../platform-apple/src/snapshot-target.ts     | 11 +--
 23 files changed, 232 insertions(+), 152 deletions(-)
 delete mode 100644 packages/platform-apple/src/core/apps-simctl.ts

diff --git a/packages/platform-apple/src/core/__tests__/app-device-io.test.ts b/packages/platform-apple/src/core/__tests__/app-device-io.test.ts
index c82875ac0e..374026368c 100644
--- a/packages/platform-apple/src/core/__tests__/app-device-io.test.ts
+++ b/packages/platform-apple/src/core/__tests__/app-device-io.test.ts
@@ -12,7 +12,10 @@ vi.mock('../simulator.ts', () => ({
     if (device.kind !== 'simulator') throw new Error('simulator required');
   },
 }));
-vi.mock('../apps-simctl.ts', () => ({ runSimctl }));
+vi.mock('../simctl.ts', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('../simctl.ts')>()),
+  runSimctlForDevice: runSimctl,
+}));
 
 import { pushIosNotification } from '../app-device-io.ts';
 
diff --git a/packages/platform-apple/src/core/__tests__/app-resolution.test.ts b/packages/platform-apple/src/core/__tests__/app-resolution.test.ts
index 1966aa1b7d..8567df0f36 100644
--- a/packages/platform-apple/src/core/__tests__/app-resolution.test.ts
+++ b/packages/platform-apple/src/core/__tests__/app-resolution.test.ts
@@ -3,7 +3,10 @@ import { beforeEach, test, vi } from 'vitest';
 
 const { mockRunSimctl } = vi.hoisted(() => ({ mockRunSimctl: vi.fn() }));
 
-vi.mock('../apps-simctl.ts', () => ({ runSimctl: mockRunSimctl }));
+vi.mock('../simctl.ts', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('../simctl.ts')>()),
+  runSimctlForDevice: mockRunSimctl,
+}));
 
 import {
   detectSoleRunningIosSimulatorApp,
diff --git a/packages/platform-apple/src/core/__tests__/simctl.test.ts b/packages/platform-apple/src/core/__tests__/simctl.test.ts
index cc37aa8a62..1845a402c0 100644
--- a/packages/platform-apple/src/core/__tests__/simctl.test.ts
+++ b/packages/platform-apple/src/core/__tests__/simctl.test.ts
@@ -1,6 +1,13 @@
 import { test } from 'vitest';
 import assert from 'node:assert/strict';
-import { buildSimctlArgs, buildSimctlArgsForDevice } from '../simctl.ts';
+import {
+  buildSimctlArgs,
+  buildSimctlArgsForDevice,
+  readSimctlDevicesByRuntime,
+  readSimctlDeviceState,
+  scopeSimctlArgs,
+  scopeSimctlArgsForDevice,
+} from '../simctl.ts';
 import type { DeviceInfo } from '@agent-device/kernel/device';
 
 const IOS_SIMULATOR: DeviceInfo = {
@@ -48,3 +55,71 @@ test('buildSimctlArgsForDevice leaves non-simulator commands unchanged', () => {
   ]);
   assert.deepEqual(args, ['simctl', 'bootstatus', 'sim-1', '-b']);
 });
+
+test('scopeSimctlArgs prefixes a trimmed simulator set and omits a blank one', () => {
+  assert.deepEqual(scopeSimctlArgs(['list', 'devices', '-j'], { simulatorSetPath: ' /tmp/set ' }), [
+    '--set',
+    '/tmp/set',
+    'list',
+    'devices',
+    '-j',
+  ]);
+  assert.deepEqual(scopeSimctlArgs(['list', 'devices', '-j'], { simulatorSetPath: '  ' }), [
+    'list',
+    'devices',
+    '-j',
+  ]);
+});
+
+test('scopeSimctlArgsForDevice scopes simulators only', () => {
+  const scoped = { ...IOS_SIMULATOR, simulatorSetPath: '/tmp/tenant-c/simulator-set' };
+  assert.deepEqual(scopeSimctlArgsForDevice(scoped, ['shutdown', 'sim-1']), [
+    '--set',
+    '/tmp/tenant-c/simulator-set',
+    'shutdown',
+    'sim-1',
+  ]);
+  assert.deepEqual(scopeSimctlArgsForDevice({ ...scoped, kind: 'device' }, ['shutdown', 'sim-1']), [
+    'shutdown',
+    'sim-1',
+  ]);
+});
+
+const LISTING = JSON.stringify({
+  devices: {
+    'com.apple.CoreSimulator.SimRuntime.iOS-18-0': [
+      { udid: 'sim-a', state: 'Shutdown', name: 'iPhone 16' },
+    ],
+    'com.apple.CoreSimulator.SimRuntime.iOS-26-0': [
+      { udid: 'sim-b', state: 'Booted', name: 'iPhone 17' },
+    ],
+  },
+});
+
+test('readSimctlDeviceState reports the listed state of the requested simulator', () => {
+  assert.equal(readSimctlDeviceState(LISTING, 'sim-b'), 'Booted');
+  assert.equal(readSimctlDeviceState(LISTING, 'sim-a'), 'Shutdown');
+});
+
+test('readSimctlDeviceState is null for an unlisted, unreadable, or empty listing', () => {
+  assert.equal(readSimctlDeviceState(LISTING, 'sim-missing'), null);
+  assert.equal(readSimctlDeviceState('not json', 'sim-b'), null);
+  assert.equal(readSimctlDeviceState('{}', 'sim-b'), null);
+  assert.equal(readSimctlDeviceState(JSON.stringify({ devices: { runtime: {} } }), 'sim-b'), null);
+});
+
+test('readSimctlDevicesByRuntime keys each device list by its runtime', () => {
+  const devicesByRuntime = readSimctlDevicesByRuntime(LISTING);
+  assert.deepEqual(
+    Object.entries(devicesByRuntime).map(([runtime, devices]) => [
+      runtime,
+      devices.map(({ udid }) => udid),
+    ]),
+    [
+      ['com.apple.CoreSimulator.SimRuntime.iOS-18-0', ['sim-a']],
+      ['com.apple.CoreSimulator.SimRuntime.iOS-26-0', ['sim-b']],
+    ],
+  );
+  assert.deepEqual(readSimctlDevicesByRuntime('{}'), {});
+  assert.throws(() => readSimctlDevicesByRuntime('not json'), SyntaxError);
+});
diff --git a/packages/platform-apple/src/core/app-device-io.ts b/packages/platform-apple/src/core/app-device-io.ts
index 99aaca3d4f..42ea707965 100644
--- a/packages/platform-apple/src/core/app-device-io.ts
+++ b/packages/platform-apple/src/core/app-device-io.ts
@@ -8,7 +8,7 @@ import {
 } from '@agent-device/host-kit/host-file';
 import { ensureBootedSimulator, requireSimulatorDevice } from './simulator.ts';
 import { readMacOsClipboardText, writeMacOsClipboardText } from '../os/macos/apps.ts';
-import { runSimctl } from './apps-simctl.ts';
+import { runSimctlForDevice } from './simctl.ts';
 
 export async function readIosClipboardText(device: DeviceInfo): Promise<string> {
   if (isMacOs(device)) {
@@ -17,7 +17,7 @@ export async function readIosClipboardText(device: DeviceInfo): Promise<string>
   requireSimulatorDevice(device, 'clipboard');
   await ensureBootedSimulator(device);
   const result = requireExecSuccess(
-    await runSimctl(device, ['pbpaste', device.id], { allowFailure: true }),
+    await runSimctlForDevice(device, ['pbpaste', device.id], { allowFailure: true }),
     'Failed to read iOS simulator clipboard',
   );
   return result.stdout.replaceAll('\r\n', '\n').replace(/\n$/, '');
@@ -31,7 +31,7 @@ export async function writeIosClipboardText(device: DeviceInfo, text: string): P
   requireSimulatorDevice(device, 'clipboard');
   await ensureBootedSimulator(device);
   requireExecSuccess(
-    await runSimctl(device, ['pbcopy', device.id], {
+    await runSimctlForDevice(device, ['pbcopy', device.id], {
       allowFailure: true,
       stdin: text,
     }),
@@ -52,7 +52,7 @@ export async function pushIosNotification(
   const payloadPath = path.join(tempDir, 'payload.apns');
   try {
     await writeHostTextFile(payloadPath, `${JSON.stringify(payload)}\n`);
-    await runSimctl(device, ['push', device.id, bundleId, payloadPath], {
+    await runSimctlForDevice(device, ['push', device.id, bundleId, payloadPath], {
       signal: options.signal,
     });
   } finally {
diff --git a/packages/platform-apple/src/core/app-launch.ts b/packages/platform-apple/src/core/app-launch.ts
index 4c02959798..652eeb3ab4 100644
--- a/packages/platform-apple/src/core/app-launch.ts
+++ b/packages/platform-apple/src/core/app-launch.ts
@@ -30,7 +30,7 @@ import { ensureBootedSimulator } from './simulator.ts';
 import { runXcrun } from './tool-provider.ts';
 import { closeMacOsApp, openMacOsApp } from '../os/macos/apps.ts';
 import { resolveIosApp } from './app-resolution.ts';
-import { runSimctl, simctlArgs } from './apps-simctl.ts';
+import { buildSimctlArgsForDevice, runSimctlForDevice } from './simctl.ts';
 
 const IOS_SIMULATOR_CONSOLE_CAPTURE_MS = 25_000;
 const IOS_SIMULATOR_LAUNCH_ARGS_WITH_URL_MESSAGE =
@@ -153,7 +153,7 @@ async function openIosSimulatorUrl(
     throw new AppError('INVALID_ARGS', IOS_SIMULATOR_LAUNCH_ARGS_WITH_URL_MESSAGE);
   }
   await ensureBootedSimulator(device);
-  await runSimctl(device, ['openurl', device.id, url]);
+  await runSimctlForDevice(device, ['openurl', device.id, url]);
 }
 
 export async function openIosDevice(device: DeviceInfo): Promise<void> {
@@ -208,7 +208,7 @@ async function assertNotSystemSurfaceHost(bundleId: string): Promise<void> {
 async function terminateIosSimulatorApp(device: DeviceInfo, bundleId: string): Promise<void> {
   await assertNotSystemSurfaceHost(bundleId);
   await ensureBootedSimulator(device);
-  const terminateArgs = simctlArgs(device, ['terminate', device.id, bundleId]);
+  const terminateArgs = buildSimctlArgsForDevice(device, ['terminate', device.id, bundleId]);
   const result = await runXcrun(terminateArgs, {
     allowFailure: true,
     timeoutMs: IOS_SIMULATOR_TERMINATE_TIMEOUT_MS,
@@ -244,7 +244,7 @@ async function launchIosSimulatorApp(
           });
         }
 
-        const launchArgs = simctlArgs(
+        const launchArgs = buildSimctlArgsForDevice(
           device,
           buildIosSimulatorLaunchArgs(device.id, bundleId, options),
         );
diff --git a/packages/platform-apple/src/core/app-resolution.ts b/packages/platform-apple/src/core/app-resolution.ts
index 2e7cda261b..e2aeb78500 100644
--- a/packages/platform-apple/src/core/app-resolution.ts
+++ b/packages/platform-apple/src/core/app-resolution.ts
@@ -13,7 +13,7 @@ import { filterAppleAppsByBundlePrefix } from './app-filter.ts';
 import { buildAppNotInstalledError } from './app-resolution-error.ts';
 import { listMacApps, resolveMacOsApp } from '../os/macos/apps.ts';
 import { runAppleToolCommand } from './tool-provider.ts';
-import { runSimctl } from './apps-simctl.ts';
+import { runSimctlForDevice } from './simctl.ts';
 import { resolveIosPhysicalDeviceControl } from './physical-device-control.ts';
 import { createTtlMemo } from '@agent-device/kernel/ttl-memo';
 
@@ -147,7 +147,7 @@ export async function detectSoleRunningIosSimulatorApp(
 }
 
 async function listRunningIosSimulatorBundleIds(device: DeviceInfo): Promise<string[]> {
-  const result = await runSimctl(device, ['spawn', device.id, 'launchctl', 'list'], {
+  const result = await runSimctlForDevice(device, ['spawn', device.id, 'launchctl', 'list'], {
     allowFailure: true,
     timeoutMs: IOS_FOREGROUND_APP_PROBE_TIMEOUT_MS,
   });
@@ -229,7 +229,7 @@ async function listSimulatorAppMetadata(
   device: DeviceInfo,
   options?: SimulatorAppListOptions,
 ): Promise<SimulatorAppMetadata[]> {
-  const result = await runSimctl(device, ['listapps', device.id], {
+  const result = await runSimctlForDevice(device, ['listapps', device.id], {
     allowFailure: true,
     timeoutMs: options?.timeoutMs,
   });
diff --git a/packages/platform-apple/src/core/app-settings.ts b/packages/platform-apple/src/core/app-settings.ts
index f9ba502ac2..b2d1d25896 100644
--- a/packages/platform-apple/src/core/app-settings.ts
+++ b/packages/platform-apple/src/core/app-settings.ts
@@ -24,7 +24,7 @@ import { runMacOsPermissionAction, type MacOsPermissionTarget } from '../os/maco
 import { closeIosApp } from './app-launch.ts';
 import { readIosTextSize, setIosTextSize } from './settings-text-size.ts';
 import { resolveIosApp } from './app-resolution.ts';
-import { runSimctl, simctlArgs } from './apps-simctl.ts';
+import { buildSimctlArgsForDevice, runSimctlForDevice } from './simctl.ts';
 import {
   invalidateSimulatorStatusBarOverrideCache,
   rememberClearedStatusBarOverrides,
@@ -78,7 +78,7 @@ export async function setIosSetting(
       if (state.toLowerCase() !== 'clear') {
         throw new AppError('INVALID_ARGS', 'settings reset-keychain only supports clear.');
       }
-      await runSimctl(device, ['keychain', device.id, 'reset']);
+      await runSimctlForDevice(device, ['keychain', device.id, 'reset']);
       return {
         scope: 'simulator',
         cleared: true,
@@ -89,14 +89,14 @@ export async function setIosSetting(
     case 'wifi': {
       const enabled = parseSettingState(state);
       const mode = enabled ? 'active' : 'failed';
-      await runSimctl(device, ['status_bar', device.id, 'override', '--wifiMode', mode]);
+      await runSimctlForDevice(device, ['status_bar', device.id, 'override', '--wifiMode', mode]);
       invalidateSimulatorStatusBarOverrideCache(device);
       return;
     }
     case 'airplane': {
       const enabled = parseSettingState(state);
       if (enabled) {
-        await runSimctl(device, [
+        await runSimctlForDevice(device, [
           'status_bar',
           device.id,
           'override',
@@ -115,7 +115,7 @@ export async function setIosSetting(
         ]);
         invalidateSimulatorStatusBarOverrideCache(device);
       } else {
-        await runSimctl(device, ['status_bar', device.id, 'clear']);
+        await runSimctlForDevice(device, ['status_bar', device.id, 'clear']);
         rememberClearedStatusBarOverrides(device);
       }
       return;
@@ -123,7 +123,12 @@ export async function setIosSetting(
     case 'location': {
       if (state.toLowerCase() === 'set') {
         const { latitude, longitude } = requireLocationCoordinates(options);
-        await runSimctl(device, ['location', device.id, 'set', `${latitude},${longitude}`]);
+        await runSimctlForDevice(device, [
+          'location',
+          device.id,
+          'set',
+          `${latitude},${longitude}`,
+        ]);
         return { latitude, longitude };
       }
       const enabled = parseSettingState(state);
@@ -131,7 +136,7 @@ export async function setIosSetting(
         throw new AppError('INVALID_ARGS', 'location setting requires an active app in session');
       }
       const action = enabled ? 'grant' : 'revoke';
-      await runSimctl(device, ['privacy', device.id, action, 'location', appBundleId]);
+      await runSimctlForDevice(device, ['privacy', device.id, action, 'location', appBundleId]);
       return;
     }
     case 'faceid':
@@ -148,7 +153,7 @@ export async function setIosSetting(
     }
     case 'appearance': {
       const target = await resolveIosAppearanceTarget(device, state);
-      await runSimctl(device, ['ui', device.id, 'appearance', target]);
+      await runSimctlForDevice(device, ['ui', device.id, 'appearance', target]);
       return;
     }
     case 'text-size': {
@@ -201,7 +206,7 @@ async function clearIosSimulatorAppState(
   await closeIosApp(device, bundleId);
 
   const result = requireExecSuccess(
-    await runSimctl(device, ['get_app_container', device.id, bundleId, 'data'], {
+    await runSimctlForDevice(device, ['get_app_container', device.id, bundleId, 'data'], {
       allowFailure: true,
     }),
     `simctl get_app_container failed for ${bundleId}`,
@@ -244,7 +249,7 @@ async function resolveIosAppearanceTarget(
   if (action !== 'toggle') return action;
 
   const currentResult = requireExecSuccess(
-    await runSimctl(device, ['ui', device.id, 'appearance'], {
+    await runSimctlForDevice(device, ['ui', device.id, 'appearance'], {
       allowFailure: true,
     }),
     'Failed to read current iOS appearance',
@@ -291,7 +296,7 @@ async function runIosPrivacyCommand(
   appBundleId: string,
 ): Promise<void> {
   try {
-    await runSimctl(device, ['privacy', device.id, action, target, appBundleId]);
+    await runSimctlForDevice(device, ['privacy', device.id, action, target, appBundleId]);
   } catch (error) {
     if (!isPrivacyServiceRefusedError(error)) throw error;
     throw privacyServiceRefusedError(device, action, target, appBundleId, error);
@@ -406,7 +411,7 @@ async function runIosBiometricSimctlCommand(
   const failures: CommandAttemptFailure[] = [];
 
   for (const args of attempts) {
-    const commandArgs = simctlArgs(device, args);
+    const commandArgs = buildSimctlArgsForDevice(device, args);
     const result = await runXcrun(commandArgs, { allowFailure: true });
     if (result.exitCode === 0) return;
     failures.push({
diff --git a/packages/platform-apple/src/core/apps-simctl.ts b/packages/platform-apple/src/core/apps-simctl.ts
deleted file mode 100644
index c5e0d04abe..0000000000
--- a/packages/platform-apple/src/core/apps-simctl.ts
+++ /dev/null
@@ -1,23 +0,0 @@
-import type { DeviceInfo } from '@agent-device/kernel/device';
-import { buildSimctlArgsForDevice } from './simctl.ts';
-import { runXcrun } from './tool-provider.ts';
-
-export function simctlArgs(device: DeviceInfo, args: string[]): string[] {
-  return buildSimctlArgsForDevice(device, args);
-}
-
-export function runSimctl(
-  device: DeviceInfo,
-  args: string[],
-  options?: Parameters<typeof runXcrun>[1],
-) {
-  return runXcrun(simctlArgs(device, args), options);
-}
-
-export function isMissingAppErrorOutput(output: string): boolean {
-  return (
-    output.includes('not installed') ||
-    output.includes('not found') ||
-    output.includes('no such file')
-  );
-}
diff --git a/packages/platform-apple/src/core/physical-device-apps.ts b/packages/platform-apple/src/core/physical-device-apps.ts
index 65cd80d2ad..256782d280 100644
--- a/packages/platform-apple/src/core/physical-device-apps.ts
+++ b/packages/platform-apple/src/core/physical-device-apps.ts
@@ -8,7 +8,6 @@ import {
   terminateIosDeviceApp,
 } from './devicectl.ts';
 import type { IosAppInfo, IosDeviceAppProcesses } from './app-info.ts';
-import { isMissingAppErrorOutput } from './apps-simctl.ts';
 
 export async function listCoreDeviceApps(
   device: DeviceInfo,
@@ -61,3 +60,11 @@ export async function resolveCoreDeviceAppProcesses(
 ): Promise<IosDeviceAppProcesses> {
   return await resolveIosDeviceAppProcesses(device, bundleId);
 }
+
+function isMissingAppErrorOutput(output: string): boolean {
+  return (
+    output.includes('not installed') ||
+    output.includes('not found') ||
+    output.includes('no such file')
+  );
+}
diff --git a/packages/platform-apple/src/core/screenshot-status-bar.ts b/packages/platform-apple/src/core/screenshot-status-bar.ts
index 0ba2eb5a82..42233be14c 100644
--- a/packages/platform-apple/src/core/screenshot-status-bar.ts
+++ b/packages/platform-apple/src/core/screenshot-status-bar.ts
@@ -1,5 +1,5 @@
 import type { DeviceInfo } from '@agent-device/kernel/device';
-import { requireExecSuccess, type ExecOptions } from '@agent-device/host-kit/command';
+import { requireExecSuccess } from '@agent-device/host-kit/command';
 import { emitDiagnostic } from '@agent-device/host-kit/diagnostics';
 import { AppError } from '@agent-device/kernel/errors';
 
@@ -55,10 +55,6 @@ const CELLULAR_MODE_BY_CODE: Record<number, string> = {
   3: 'active',
 };
 
-function runSimctl(device: DeviceInfo, args: string[], options?: ExecOptions) {
-  return runSimctlForDevice(device, args, options);
-}
-
 const devicesKnownWithoutStatusBarOverrides = new Set<string>();
 
 export async function prepareSimulatorStatusBarForScreenshot(
@@ -130,7 +126,7 @@ async function readSimulatorStatusBarOverrides(
   device: DeviceInfo,
 ): Promise<RestorableStatusBarOverrides | null> {
   const result = requireExecSuccess(
-    await runSimctl(device, ['status_bar', device.id, 'list'], {
+    await runSimctlForDevice(device, ['status_bar', device.id, 'list'], {
       allowFailure: true,
     }),
     'Failed to read simulator status bar overrides',
@@ -139,7 +135,7 @@ async function readSimulatorStatusBarOverrides(
 }
 
 async function clearSimulatorStatusBarOverride(device: DeviceInfo): Promise<void> {
-  await runSimctl(device, ['status_bar', device.id, 'clear']);
+  await runSimctlForDevice(device, ['status_bar', device.id, 'clear']);
 }
 
 async function applySimulatorStatusBarOverrideArgs(
@@ -147,7 +143,7 @@ async function applySimulatorStatusBarOverrideArgs(
   args: string[],
 ): Promise<void> {
   if (args.length === 0) return;
-  await runSimctl(device, ['status_bar', device.id, 'override', ...args]);
+  await runSimctlForDevice(device, ['status_bar', device.id, 'override', ...args]);
 }
 
 function parseSimulatorStatusBarOverrides(output: string): RestorableStatusBarOverrides | null {
diff --git a/packages/platform-apple/src/core/screenshot.ts b/packages/platform-apple/src/core/screenshot.ts
index a4d00c1a73..b966b51ac4 100644
--- a/packages/platform-apple/src/core/screenshot.ts
+++ b/packages/platform-apple/src/core/screenshot.ts
@@ -1,6 +1,5 @@
 import path from 'node:path';
 import { isMacOs, type DeviceInfo } from '@agent-device/kernel/device';
-import { type ExecOptions } from '@agent-device/host-kit/command';
 import { emitDiagnostic } from '@agent-device/host-kit/diagnostics';
 import { copyHostFile } from '@agent-device/host-kit/host-file';
 import { Deadline, retryWithPolicy } from '@agent-device/host-kit/retry';
@@ -37,10 +36,6 @@ import { runSimctlForDevice } from './simctl.ts';
 import { appleToolFailureText, extractAppleToolErrorMeta } from './tool-diagnostics.ts';
 import { resolveIosPhysicalDeviceControl } from './physical-device-control.ts';
 
-function runSimctl(device: DeviceInfo, args: string[], options?: ExecOptions) {
-  return runSimctlForDevice(device, args, options);
-}
-
 type SimulatorScreenshotFlowDeps = {
   ensureBooted: (device: DeviceInfo) => Promise<void>;
   prepareStatusBarForScreenshot: (device: DeviceInfo) => Promise<() => Promise<void>>;
@@ -213,7 +208,7 @@ export async function captureSimulatorScreenshotWithRetry(
   ];
   await retryWithPolicy(
     async ({ deadline: attemptDeadline }) => {
-      await runSimctl(device, argv, {
+      await runSimctlForDevice(device, argv, {
         timeoutMs: Math.max(
           1_000,
           attemptDeadline?.remainingMs() ?? IOS_SIMULATOR_SCREENSHOT_TIMEOUT_MS,
@@ -299,7 +294,7 @@ async function copyRunnerScreenshotFromSimulator(
     iosSimulatorRunnerContainerCache.delete(device.id);
   }
   for (const bundleId of IOS_RUNNER_CONTAINER_BUNDLE_IDS) {
-    const containerResult = await runSimctl(
+    const containerResult = await runSimctlForDevice(
       device,
       ['get_app_container', device.id, bundleId, 'data'],
       {
@@ -496,9 +491,13 @@ async function readIosSimulatorMainScreenScale(device: DeviceInfo): Promise<numb
   if (cachedScale !== undefined) {
     return cachedScale;
   }
-  const scaleResult = await runSimctl(device, ['getenv', device.id, 'SIMULATOR_MAINSCREEN_SCALE'], {
-    timeoutMs: IOS_SIMULATOR_SCREENSHOT_SCALE_TIMEOUT_MS,
-  });
+  const scaleResult = await runSimctlForDevice(
+    device,
+    ['getenv', device.id, 'SIMULATOR_MAINSCREEN_SCALE'],
+    {
+      timeoutMs: IOS_SIMULATOR_SCREENSHOT_SCALE_TIMEOUT_MS,
+    },
+  );
   const scale = Number(scaleResult.stdout.trim());
   if (!Number.isFinite(scale) || scale <= 0) {
     throw new AppError(
diff --git a/packages/platform-apple/src/core/settings-text-size.ts b/packages/platform-apple/src/core/settings-text-size.ts
index abefa50a72..e212d5f9bf 100644
--- a/packages/platform-apple/src/core/settings-text-size.ts
+++ b/packages/platform-apple/src/core/settings-text-size.ts
@@ -12,7 +12,7 @@ import {
 } from '@agent-device/kernel/device';
 import { AppError } from '@agent-device/kernel/errors';
 import { requireExecSuccess } from '@agent-device/host-kit/command';
-import { runSimctl } from './apps-simctl.ts';
+import { runSimctlForDevice } from './simctl.ts';
 import { ensureBootedSimulator } from './simulator.ts';
 
 /**
@@ -51,7 +51,7 @@ export async function setIosTextSize(
 ): Promise<TextSizeSettingPayload> {
   requireTextSizeLeaf(device);
   const category = parseTextSizeCategory(state);
-  await runSimctl(device, ['ui', device.id, 'content_size', category]);
+  await runSimctlForDevice(device, ['ui', device.id, 'content_size', category]);
   return textSizeSettingPayload(category, category);
 }
 
@@ -65,7 +65,7 @@ export async function readIosTextSize(device: DeviceInfo): Promise<TextSizeSetti
   requireTextSizeLeaf(device);
   await ensureBootedSimulator(device);
   const result = requireExecSuccess(
-    await runSimctl(device, ['ui', device.id, 'content_size'], { allowFailure: true }),
+    await runSimctlForDevice(device, ['ui', device.id, 'content_size'], { allowFailure: true }),
     'Failed to read iOS content size category',
   );
   const reported = result.stdout.trim();
diff --git a/packages/platform-apple/src/core/simctl.ts b/packages/platform-apple/src/core/simctl.ts
index 3997a6f4f1..b47011bcdd 100644
--- a/packages/platform-apple/src/core/simctl.ts
+++ b/packages/platform-apple/src/core/simctl.ts
@@ -7,23 +7,58 @@ type SimctlArgsOptions = {
   simulatorSetPath?: string;
 };
 
-export function buildSimctlArgs(args: string[], options: SimctlArgsOptions = {}): string[] {
+/** Arguments that follow the `simctl` tool name, scoped to the simulator set when one is given. */
+export function scopeSimctlArgs(
+  args: readonly string[],
+  options: SimctlArgsOptions = {},
+): string[] {
   const simulatorSetPath = resolveIosSimulatorDeviceSetPath(options.simulatorSetPath);
-  if (!simulatorSetPath) return ['simctl', ...args];
-  return ['simctl', '--set', simulatorSetPath, ...args];
+  if (!simulatorSetPath) return [...args];
+  return ['--set', simulatorSetPath, ...args];
 }
 
-export function buildSimctlArgsForDevice(device: DeviceInfo, args: string[]): string[] {
-  if (!isIosFamily(device) || device.kind !== 'simulator') {
-    return ['simctl', ...args];
-  }
-  return buildSimctlArgs(args, { simulatorSetPath: device.simulatorSetPath });
+/** Arguments that follow the `simctl` tool name, scoped to the simulator set holding the device. */
+export function scopeSimctlArgsForDevice(device: DeviceInfo, args: readonly string[]): string[] {
+  if (!isIosFamily(device) || device.kind !== 'simulator') return [...args];
+  return scopeSimctlArgs(args, { simulatorSetPath: device.simulatorSetPath });
+}
+
+export function buildSimctlArgs(
+  args: readonly string[],
+  options: SimctlArgsOptions = {},
+): string[] {
+  return ['simctl', ...scopeSimctlArgs(args, options)];
+}
+
+export function buildSimctlArgsForDevice(device: DeviceInfo, args: readonly string[]): string[] {
+  return ['simctl', ...scopeSimctlArgsForDevice(device, args)];
 }
 
 export function runSimctlForDevice(
   device: DeviceInfo,
-  args: string[],
+  args: readonly string[],
   options?: ExecOptions,
 ): Promise<ExecResult> {
   return runXcrun(buildSimctlArgsForDevice(device, args), options);
 }
+
+type SimctlListedDevice = { udid?: string; state?: string };
+
+/** The runtime-keyed device lists of `simctl list devices -j` output; throws unless it is a JSON object. */
+export function readSimctlDevicesByRuntime(stdout: string): Record<string, SimctlListedDevice[]> {
+  const payload = JSON.parse(stdout) as { devices?: Record<string, SimctlListedDevice[]> };
+  return payload.devices ?? {};
+}
+
+/** The listed state of one simulator; null when the listing is unreadable or omits the device. */
+export function readSimctlDeviceState(stdout: string, udid: string): string | null {
+  try {
+    for (const devices of Object.values(readSimctlDevicesByRuntime(stdout))) {
+      const match = devices.find((entry) => entry.udid === udid);
+      if (match) return match.state ?? null;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
diff --git a/packages/platform-apple/src/core/simulator.ts b/packages/platform-apple/src/core/simulator.ts
index 6ba17b5552..7ffd1b56d1 100644
--- a/packages/platform-apple/src/core/simulator.ts
+++ b/packages/platform-apple/src/core/simulator.ts
@@ -12,7 +12,7 @@ import {
   IOS_SIMCTL_LIST_TIMEOUT_MS,
   IOS_SIMULATOR_FOCUS_TIMEOUT_MS,
 } from './config.ts';
-import { buildSimctlArgsForDevice } from './simctl.ts';
+import { buildSimctlArgsForDevice, readSimctlDeviceState } from './simctl.ts';
 import { runAppleToolCommand, runXcrun } from './tool-provider.ts';
 
 const simulatorReadiness = createScopedProvider<
@@ -237,18 +237,5 @@ async function getSimulatorState(device: DeviceInfo, signal?: AbortSignal): Prom
     timeoutMs: IOS_SIMCTL_LIST_TIMEOUT_MS,
   });
   if (result.exitCode !== 0) return null;
-
-  try {
-    const payload = JSON.parse(result.stdout) as {
-      devices: Record<string, { udid: string; state: string }[]>;
-    };
-
-    for (const runtime of Object.values(payload.devices ?? {})) {
-      const match = runtime.find((entry) => entry.udid === device.id);
-      if (match) return match.state;
-    }
-    return null;
-  } catch {
-    return null;
-  }
+  return readSimctlDeviceState(result.stdout, device.id);
 }
diff --git a/packages/platform-apple/src/deployment/runtime.ts b/packages/platform-apple/src/deployment/runtime.ts
index d480a69f3e..394310eb70 100644
--- a/packages/platform-apple/src/deployment/runtime.ts
+++ b/packages/platform-apple/src/deployment/runtime.ts
@@ -11,7 +11,7 @@ import type { RuntimeOperationFact } from '@agent-device/contracts/platform-runt
 import { isIosFamily, type DeviceInfo } from '@agent-device/kernel/device';
 import { AppError } from '@agent-device/kernel/errors';
 import { ensureAppleReady } from '../readiness/runtime.ts';
-import { simctlArgs } from '../simulator-state.ts';
+import { scopeSimctlArgsForDevice } from '../core/simctl.ts';
 
 const available = Object.freeze({ available: true } as const);
 const coreDeviceRequired = Object.freeze({
@@ -137,7 +137,10 @@ async function installAppleApp(
   await ensureAppleReady(host, device, signal);
   const result = await host.appleTools.run(
     device.kind === 'simulator'
-      ? { tool: 'simctl', args: simctlArgs(device, ['install', device.id, installablePath]) }
+      ? {
+          tool: 'simctl',
+          args: scopeSimctlArgsForDevice(device, ['install', device.id, installablePath]),
+        }
       : {
           tool: 'devicectl',
           args: ['device', 'install', 'app', '--device', device.id, installablePath],
@@ -159,7 +162,7 @@ async function uninstallAppleApp(
     device.kind === 'simulator'
       ? {
           tool: 'simctl',
-          args: simctlArgs(device, ['uninstall', device.id, bundleId]),
+          args: scopeSimctlArgsForDevice(device, ['uninstall', device.id, bundleId]),
           allowFailure: true,
         }
       : {
@@ -192,7 +195,7 @@ async function pushAppleNotification(
     const result = await host.appleTools.run(
       {
         tool: 'simctl',
-        args: simctlArgs(device, ['push', device.id, input.appId, payload.path]),
+        args: scopeSimctlArgsForDevice(device, ['push', device.id, input.appId, payload.path]),
       },
       signal,
     );
diff --git a/packages/platform-apple/src/logs/log-predicate.ts b/packages/platform-apple/src/logs/log-predicate.ts
index 8669df5549..4fa3e598de 100644
--- a/packages/platform-apple/src/logs/log-predicate.ts
+++ b/packages/platform-apple/src/logs/log-predicate.ts
@@ -1,3 +1,5 @@
+import { buildSimctlArgs } from '../core/simctl.ts';
+
 export function buildAppleLogPredicate(appBundleId: string, executableName?: string): string {
   const escapedBundleId = escapePredicateString(appBundleId);
   const clauses = [
@@ -25,22 +27,21 @@ export function buildIosSimulatorLogStreamArgs(params: {
   executableName?: string;
   simulatorSetPath?: string;
 }): string[] {
-  const simctlPrefix = params.simulatorSetPath
-    ? ['simctl', '--set', params.simulatorSetPath]
-    : ['simctl'];
-  return [
-    ...simctlPrefix,
-    'spawn',
-    params.deviceId,
-    'log',
-    'stream',
-    '--style',
-    'compact',
-    '--level',
-    'info',
-    '--predicate',
-    buildAppleLogPredicate(params.appBundleId, params.executableName),
-  ];
+  return buildSimctlArgs(
+    [
+      'spawn',
+      params.deviceId,
+      'log',
+      'stream',
+      '--style',
+      'compact',
+      '--level',
+      'info',
+      '--predicate',
+      buildAppleLogPredicate(params.appBundleId, params.executableName),
+    ],
+    { simulatorSetPath: params.simulatorSetPath },
+  );
 }
 
 export function buildIosDeviceConsoleLaunchArgs(deviceId: string, appBundleId: string): string[] {
diff --git a/packages/platform-apple/src/logs/start.ts b/packages/platform-apple/src/logs/start.ts
index a615d73dcf..a25b3a67e8 100644
--- a/packages/platform-apple/src/logs/start.ts
+++ b/packages/platform-apple/src/logs/start.ts
@@ -17,6 +17,7 @@ import {
   createAppLogLiveHandleFromFinish,
   createAppLogStartResult,
 } from '@agent-device/capture-kit';
+import { scopeSimctlArgsForDevice } from '../core/simctl.ts';
 import { APPLE_XCTEST_LOGS_HINT, backendForAppleDevice } from './backend.ts';
 import {
   checkCoreDeviceConsoleCaptureSupport,
@@ -174,11 +175,10 @@ async function resolveSimulatorExecutable(
   appBundleId: string,
   signal?: AbortSignal,
 ): Promise<string | undefined> {
-  const prefix = device.simulatorSetPath ? ['--set', device.simulatorSetPath] : [];
   const container = await host.appleTools.run(
     {
       tool: 'simctl',
-      args: [...prefix, 'get_app_container', device.id, appBundleId, 'app'],
+      args: scopeSimctlArgsForDevice(device, ['get_app_container', device.id, appBundleId, 'app']),
       allowFailure: true,
       timeoutMs: 4_000,
     },
diff --git a/packages/platform-apple/src/network/runtime.ts b/packages/platform-apple/src/network/runtime.ts
index a1f3b0a2a9..cc9b021c89 100644
--- a/packages/platform-apple/src/network/runtime.ts
+++ b/packages/platform-apple/src/network/runtime.ts
@@ -7,6 +7,7 @@ import {
   type NetworkScan,
 } from '@agent-device/capture-kit';
 import { isIosFamily, type DeviceInfo } from '@agent-device/kernel/device';
+import { scopeSimctlArgsForDevice } from '../core/simctl.ts';
 import { backendForAppleDevice } from '../logs/backend.ts';
 
 export async function dumpAppleNetworkTraffic(
@@ -88,8 +89,7 @@ async function recoverSimulatorTraffic(
   appLogPath: string,
   signal: AbortSignal,
 ): Promise<{ scan: NetworkScan; lineCount: number } | undefined> {
-  const args = [
-    ...(device.simulatorSetPath ? ['--set', device.simulatorSetPath] : []),
+  const args = scopeSimctlArgsForDevice(device, [
     'spawn',
     device.id,
     'log',
@@ -99,7 +99,7 @@ async function recoverSimulatorTraffic(
     '--info',
     '--predicate',
     buildPredicate(input.appBundleId as string),
-  ];
+  ]);
   const startedAt = input.appLogSnapshot?.startedAt;
   args.push(
     ...(typeof startedAt === 'number' && Number.isFinite(startedAt) && startedAt > 0
diff --git a/packages/platform-apple/src/readiness/runtime.ts b/packages/platform-apple/src/readiness/runtime.ts
index c8f41c18c1..e9b0877ef6 100644
--- a/packages/platform-apple/src/readiness/runtime.ts
+++ b/packages/platform-apple/src/readiness/runtime.ts
@@ -3,7 +3,8 @@ import { isMacOs, type DeviceInfo } from '@agent-device/kernel/device';
 import { AppError } from '@agent-device/kernel/errors';
 import { emitRequestProgress } from '@agent-device/host-kit/request';
 import { delegateManagedDeviceReadiness } from '@agent-device/provision-kit/managed-device-scope';
-import { getSimulatorState, simctlArgs } from '../simulator-state.ts';
+import { scopeSimctlArgsForDevice } from '../core/simctl.ts';
+import { getSimulatorState } from '../simulator-state.ts';
 
 /** Readiness reads exactly these host ports; the lifecycle binding composes the same subset. */
 export type AppleReadinessHost = Pick<
@@ -98,7 +99,7 @@ async function startSimulatorBoot(
   const boot = await host.appleTools.run(
     {
       tool: 'simctl',
-      args: simctlArgs(device, ['boot', device.id]),
+      args: scopeSimctlArgsForDevice(device, ['boot', device.id]),
       allowFailure: true,
       timeoutMs: remainingBootBudgetMs(deadlineAtMs, device),
     },
@@ -131,7 +132,7 @@ async function waitForSimulatorBoot(
   const status = await host.appleTools.run(
     {
       tool: 'simctl',
-      args: simctlArgs(device, ['bootstatus', device.id, '-b']),
+      args: scopeSimctlArgsForDevice(device, ['bootstatus', device.id, '-b']),
       allowFailure: true,
       timeoutMs: remainingBootBudgetMs(deadlineAtMs, device),
     },
@@ -194,6 +195,10 @@ async function showSimulator(host: AppleReadinessHost, signal: AbortSignal): Pro
 
 function scheduleSimulatorShutdown(host: AppleReadinessHost, device: DeviceInfo): void {
   void host.appleTools
-    .run({ tool: 'simctl', args: simctlArgs(device, ['shutdown', device.id]), allowFailure: true })
+    .run({
+      tool: 'simctl',
+      args: scopeSimctlArgsForDevice(device, ['shutdown', device.id]),
+      allowFailure: true,
+    })
     .catch(() => {});
 }
diff --git a/packages/platform-apple/src/shutdown/runtime.ts b/packages/platform-apple/src/shutdown/runtime.ts
index 3ee3a9a37f..d0e5931c5f 100644
--- a/packages/platform-apple/src/shutdown/runtime.ts
+++ b/packages/platform-apple/src/shutdown/runtime.ts
@@ -2,7 +2,8 @@ import type { DeviceShutdownRuntimeDependencies } from '@agent-device/contracts/
 import type { TargetShutdownResult } from '@agent-device/contracts/device';
 import { isIosFamily, type DeviceInfo } from '@agent-device/kernel/device';
 import { normalizeError } from '@agent-device/kernel/errors';
-import { getSimulatorState, simctlArgs } from '../simulator-state.ts';
+import { scopeSimctlArgsForDevice } from '../core/simctl.ts';
+import { getSimulatorState } from '../simulator-state.ts';
 
 const SHUTDOWN_TIMEOUT_MS = 15_000;
 
@@ -37,7 +38,7 @@ async function shutdownAppleTarget(
     const result = await appleTools.run(
       {
         tool: 'simctl',
-        args: simctlArgs(device, ['shutdown', device.id]),
+        args: scopeSimctlArgsForDevice(device, ['shutdown', device.id]),
         allowFailure: true,
         timeoutMs: SHUTDOWN_TIMEOUT_MS,
       },
diff --git a/packages/platform-apple/src/simulator-inventory.ts b/packages/platform-apple/src/simulator-inventory.ts
index 3878add11e..80e80bf052 100644
--- a/packages/platform-apple/src/simulator-inventory.ts
+++ b/packages/platform-apple/src/simulator-inventory.ts
@@ -5,6 +5,7 @@ import type {
 } from '@agent-device/contracts/platform-runtime-host';
 import { sortAppleDevicesForSelection, type DeviceInfo } from '@agent-device/kernel/device';
 import { AppError } from '@agent-device/kernel/errors';
+import { scopeSimctlArgs } from './core/simctl.ts';
 import {
   isSupportedAppleRuntime,
   resolveAppleOs,
@@ -26,8 +27,7 @@ type SimctlListDevicesPayload = {
 const BOOTED_SIMULATOR_PROBE_TIMEOUT_MS = 3_000;
 
 export function buildSimctlListArgs(simulatorSetPath: string | undefined): string[] {
-  const path = simulatorSetPath?.trim();
-  return path ? ['--set', path, 'list', 'devices', '-j'] : ['list', 'devices', '-j'];
+  return scopeSimctlArgs(['list', 'devices', '-j'], { simulatorSetPath });
 }
 
 export function parseSimctlAppleDevices(
diff --git a/packages/platform-apple/src/simulator-state.ts b/packages/platform-apple/src/simulator-state.ts
index 9f80f3614f..df6235deaa 100644
--- a/packages/platform-apple/src/simulator-state.ts
+++ b/packages/platform-apple/src/simulator-state.ts
@@ -1,5 +1,6 @@
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import type { AppleToolHost } from '@agent-device/contracts/platform-runtime-host';
+import { readSimctlDeviceState, scopeSimctlArgsForDevice } from './core/simctl.ts';
 
 export async function getSimulatorState(
   appleTools: AppleToolHost,
@@ -10,27 +11,12 @@ export async function getSimulatorState(
   const result = await appleTools.run(
     {
       tool: 'simctl',
-      args: simctlArgs(device, ['list', 'devices', '-j']),
+      args: scopeSimctlArgsForDevice(device, ['list', 'devices', '-j']),
       allowFailure: true,
       timeoutMs,
     },
     signal,
   );
   if (result.exitCode !== 0) return null;
-  try {
-    const payload = JSON.parse(result.stdout) as {
-      devices?: Record<string, Array<{ udid: string; state: string }>>;
-    };
-    return (
-      Object.values(payload.devices ?? {})
-        .flat()
-        .find(({ udid }) => udid === device.id)?.state ?? null
-    );
-  } catch {
-    return null;
-  }
-}
-
-export function simctlArgs(device: DeviceInfo, args: readonly string[]): string[] {
-  return device.simulatorSetPath ? ['--set', device.simulatorSetPath, ...args] : [...args];
+  return readSimctlDeviceState(result.stdout, device.id);
 }
diff --git a/packages/platform-apple/src/snapshot-target.ts b/packages/platform-apple/src/snapshot-target.ts
index 18bce81b92..3f3cb2755e 100644
--- a/packages/platform-apple/src/snapshot-target.ts
+++ b/packages/platform-apple/src/snapshot-target.ts
@@ -1,7 +1,7 @@
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import { AppError } from '@agent-device/kernel/errors';
 import { createDetachedAttempts, waitForDetachedAttempt } from './detached-attempt.ts';
-import { runSimctl } from './core/apps-simctl.ts';
+import { readSimctlDevicesByRuntime, runSimctlForDevice } from './core/simctl.ts';
 import { readSnapshotTargetProcessStartTime } from './snapshot-process.ts';
 
 /** Identity re-check of a cached target: one local `ps`, never CoreSimulator IPC. */
@@ -77,7 +77,7 @@ async function resolveSimulatorSnapshotTarget(
   // failure would release its single-flight slot while the other probe still runs, and every
   // capture after it would start a probe of its own.
   const [jobsProbe, runtimeProbe] = await Promise.allSettled([
-    runSimctl(device, ['spawn', device.id, 'launchctl', 'list'], {
+    runSimctlForDevice(device, ['spawn', device.id, 'launchctl', 'list'], {
       allowFailure: true,
       timeoutMs: remainingMs(deadline),
     }),
@@ -118,15 +118,12 @@ async function readSimulatorRuntime(
 ): Promise<string> {
   const existing = runtimeByDevice.get(device.id);
   if (existing) return await existing;
-  const pending = runSimctl(device, ['list', 'devices', '-j'], {
+  const pending = runSimctlForDevice(device, ['list', 'devices', '-j'], {
     allowFailure: true,
     timeoutMs: remainingMs(deadline),
   }).then((result) => {
     if (result.exitCode !== 0) throw targetError('simulator-runtime-probe-failed', device, '');
-    const payload = JSON.parse(result.stdout) as {
-      devices?: Record<string, Array<{ udid?: string }>>;
-    };
-    const runtime = Object.entries(payload.devices ?? {}).find(([, devices]) =>
+    const runtime = Object.entries(readSimctlDevicesByRuntime(result.stdout)).find(([, devices]) =>
       devices.some((candidate) => candidate.udid === device.id),
     )?.[0];
     if (!runtime) throw targetError('simulator-runtime-unavailable', device, '');

From 3fac0d8f58264e9c0c53c695bd60e50eec6dcfdf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Wed, 23 Sep 2026 19:17:08 +0200
Subject: [PATCH 057/132] fix(ios): let a Simulator open wait out a slow app
 discovery before observing the launch (#2838)

The launch-observation probe read a target discovery that outlasted one
1.5 s wait slice as an unobservable app. On a loaded host simctl
launchctl list takes longer than that, so open --relaunch returned
before the discovery, the AX-bridge preparation or the first bridge
connection, and the first wait after it paid all three in one poll
behind a runner findText. On iOS smoke CI that poll consumed the whole
10 s budget (wait_capture_stalled, captures: 1) at step 7 of
smoke:automation-input.

The probe now keeps joining the running discovery, bounded by the
discovery's own deadline; any other resolution failure still ends it at
once. The discovery-pending reason and its predicate move to the
resolver that owns them, shared by the capture route.
---
 CHANGELOG.md                                  |  8 +++
 packages/platform-apple/src/open-policy.ts    |  7 +-
 .../src/snapshot-observability.test.ts        | 27 ++++++++
 .../src/snapshot-observability.ts             | 33 +++++++--
 .../platform-apple/src/snapshot-route.test.ts | 68 +++++++++++++++++++
 packages/platform-apple/src/snapshot-route.ts |  9 +--
 .../platform-apple/src/snapshot-target.ts     | 12 +++-
 7 files changed, 148 insertions(+), 16 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1e9850d969..9bf19bbaba 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+- Fixed (ios): `open` on a local Simulator now waits for the launched app's discovery before it
+  decides whether the app is observable. On a loaded host `simctl spawn launchctl list` outlasts one
+  1.5 s discovery wait slice, and the launch observation read that slice as an unobservable app, so
+  the open returned before the discovery, the AX-bridge preparation or the first bridge connection.
+  The first `wait` after the open then paid all three in one poll, behind a runner `findText`, and on
+  CI it spent its whole 10 s budget there (`wait_capture_stalled` with `captures: 1`). The probe now
+  joins the running discovery, bounded by the discovery's own deadline, and then observes the launch
+  as before. A resolution failure other than a pending discovery still ends the probe at once.
 - Fixed (ios): a local Simulator snapshot taken through the host AX bridge once again publishes the
   geometric `hittable` fact, so `is hittable` and a `hittable:` selector resolve the same controls on
   the bridge and the XCTest runner. The snapshot capability table has declared `hittable =
diff --git a/packages/platform-apple/src/open-policy.ts b/packages/platform-apple/src/open-policy.ts
index df7608e794..67f0ebe24a 100644
--- a/packages/platform-apple/src/open-policy.ts
+++ b/packages/platform-apple/src/open-policy.ts
@@ -69,9 +69,10 @@ export function releaseSpeculativeRunner(
 
 /**
  * Lets the opened app become observable before the open returns. A local Simulator asks its AX
- * bridge, bounded by the launch-transition windows the bridge itself defines, so the first
- * observation never pays the launch and never falls back to a runner start for it. Any other
- * device, or a Simulator whose bridge cannot answer, keeps the fixed settle.
+ * bridge once the app's discovery settles, bounded by the discovery's own deadline and the
+ * launch-transition windows the bridge itself defines, so the first observation never pays the
+ * launch and never falls back to a runner start for it. Any other device, or a Simulator whose
+ * bridge cannot answer, keeps the fixed settle.
  */
 export async function settleAppleOpen(
   host: Pick<PlatformRuntimeHost, 'clock'>,
diff --git a/packages/platform-apple/src/snapshot-observability.test.ts b/packages/platform-apple/src/snapshot-observability.test.ts
index 00e4d58c94..d107e33ce5 100644
--- a/packages/platform-apple/src/snapshot-observability.test.ts
+++ b/packages/platform-apple/src/snapshot-observability.test.ts
@@ -4,6 +4,7 @@ import {
   withDiagnosticsScope,
 } from '@agent-device/host-kit/diagnostics';
 import type { DeviceInfo } from '@agent-device/kernel/device';
+import { AppError } from '@agent-device/kernel/errors';
 import { createLaunchObservationProbe } from './snapshot-observability.ts';
 import type { SnapshotSourceFailure, SnapshotSourceOutcome } from './snapshot-source-facade.ts';
 import type { SimulatorSnapshotTarget } from './snapshot-target.ts';
@@ -187,6 +188,32 @@ test('the skip is reported, so a live run can tell it from an unresolvable targe
   });
 });
 
+test.each([
+  ['a discovery still running is joined until it answers', 'simulator-target-discovery-pending', 3],
+  ['any other resolution failure is unobservable at once', 'simulator-target-unavailable', 1],
+])('%s', async (_name, reason, expectedResolutions) => {
+  let resolutions = 0;
+  const acquire = vi.fn(async () => acquired());
+  const observe = createLaunchObservationProbe({
+    source: { acquire, close: async () => {} },
+    resolveTarget: async () => {
+      resolutions += 1;
+      if (resolutions < 3) {
+        throw new AppError('COMMAND_FAILED', 'Unable to resolve the running iOS Simulator app.', {
+          reason,
+        });
+      }
+      return target;
+    },
+    clock: { now: () => 0, sleep: async () => {} },
+    isBridgeDisabled: () => false,
+  });
+  await expect(observe.awaitObservable(simulator, 'com.example.app', signal())).resolves.toBe(
+    expectedResolutions === 3 ? 'observable' : 'unobservable',
+  );
+  expect(resolutions).toBe(expectedResolutions);
+});
+
 test.each([
   ['a physical iOS device', { ...simulator, kind: 'device' as const }],
   ['a tvOS Simulator', { ...simulator, appleOs: 'tvos' as const, target: 'tv' as const }],
diff --git a/packages/platform-apple/src/snapshot-observability.ts b/packages/platform-apple/src/snapshot-observability.ts
index 94d75274f5..91ff821b3d 100644
--- a/packages/platform-apple/src/snapshot-observability.ts
+++ b/packages/platform-apple/src/snapshot-observability.ts
@@ -6,9 +6,10 @@ import { emitDiagnostic } from '@agent-device/host-kit/diagnostics';
 import type { PlatformRuntimeHost } from '@agent-device/contracts/platform-runtime-operations';
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import type { SimulatorSnapshotSource } from './snapshot-source-facade.ts';
-import type {
-  SimulatorSnapshotTarget,
-  SimulatorSnapshotTargetResolver,
+import {
+  isSimulatorTargetDiscoveryPending,
+  type SimulatorSnapshotTarget,
+  type SimulatorSnapshotTargetResolver,
 } from './snapshot-target.ts';
 
 /**
@@ -64,8 +65,7 @@ export function createLaunchObservationProbe(
       if (!hasSimulatorBridge(device)) return 'not-eligible';
       let deadline: number | undefined;
       for (;;) {
-        const target = await deps.resolveTarget(device, appBundleId, signal).catch(() => undefined);
-        signal.throwIfAborted();
+        const target = await resolveLaunchedTarget(deps.resolveTarget, device, appBundleId, signal);
         if (!target) return 'unobservable';
         // A generation whose bridge already failed a capture fails this probe the same way, and
         // the codes it fails with are the ones this loop re-reads for seconds. Ask the circuit
@@ -97,3 +97,26 @@ export function createLaunchObservationProbe(
     },
   });
 }
+
+/**
+ * The launched app's bridge target, or `undefined` when it cannot be resolved. A discovery that is
+ * still running has not answered yet, so the probe keeps joining it one wait slice at a time until
+ * the discovery's own deadline settles it. Returning early would hand the discovery, the bridge
+ * preparation and the first bridge connection to the first observation after the open, which pays
+ * them inside its own budget.
+ */
+async function resolveLaunchedTarget(
+  resolveTarget: SimulatorSnapshotTargetResolver,
+  device: DeviceInfo,
+  appBundleId: string,
+  signal: AbortSignal,
+): Promise<SimulatorSnapshotTarget | undefined> {
+  for (;;) {
+    try {
+      return await resolveTarget(device, appBundleId, signal);
+    } catch (error) {
+      signal.throwIfAborted();
+      if (!isSimulatorTargetDiscoveryPending(error)) return undefined;
+    }
+  }
+}
diff --git a/packages/platform-apple/src/snapshot-route.test.ts b/packages/platform-apple/src/snapshot-route.test.ts
index 4d9c0775b9..2f5a9b6647 100644
--- a/packages/platform-apple/src/snapshot-route.test.ts
+++ b/packages/platform-apple/src/snapshot-route.test.ts
@@ -546,6 +546,74 @@ test('a slow app discovery yields to a live runner within its wait slice, then s
   }
 });
 
+test('an open waits out a slow app discovery, so the first capture after it starts warm', async () => {
+  // iOS smoke `wait for Agent Device Tester` right after `open --relaunch`: `launchctl list`
+  // outlasted one discovery slice on CI, the open read that as an unobservable app and returned,
+  // and the wait's first poll paid the discovery, the bridge preparation and the first bridge
+  // connection behind a runner findText until its 10 s budget ran out.
+  let release!: () => void;
+  const released = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  const run = vi.fn(async (args: string[]) => {
+    if (args[0] === 'spawn') await released;
+    return {
+      stdout:
+        args[0] === 'spawn'
+          ? `42\t0\tUIKitApplication:${input.options.appBundleId}[launch-a][rb-legacy]`
+          : JSON.stringify({
+              devices: { 'com.apple.CoreSimulator.SimRuntime.iOS-26-0': [{ udid: ios.id }] },
+            }),
+      stderr: '',
+      exitCode: 0,
+    };
+  });
+  const runCommand = vi.fn(async () => ({ stdout: 'start-a', stderr: '', exitCode: 0 }));
+  const fallback = vi.fn(async () => runnerResult());
+  const source = sourceReturning(bridgeAcquisition());
+  const presentIosAcquisition = vi.fn(async () => ({
+    backend: 'xctest' as const,
+    producer: 'simulator-ax-bridge' as const,
+    nodes: [{ index: 0, type: 'Application' }],
+  }));
+  const baseHost = platformRuntimeHostFixture();
+  const route = createAppleSnapshotRoute(
+    {
+      ...baseHost,
+      appleApplications: { ...baseHost.appleApplications, hasLiveRunnerSession: async () => true },
+      snapshot: { captureSurface: vi.fn(), presentIosAcquisition },
+    },
+    { source, resolveTarget: createSimulatorSnapshotTargetResolver() },
+  );
+  vi.useFakeTimers();
+  try {
+    await withAppleToolProvider(
+      createLocalAppleToolProvider({ simctl: { run }, runCommand }),
+      async () => {
+        let verdict: string | undefined;
+        const observed = route
+          .awaitObservable(ios, input.options.appBundleId, signal())
+          .then((value) => (verdict = value));
+        await vi.advanceTimersByTimeAsync(4_500);
+        expect(verdict).toBeUndefined();
+        expect(source.acquire).not.toHaveBeenCalled();
+
+        release();
+        await vi.advanceTimersByTimeAsync(0);
+        await expect(observed).resolves.toBe('observable');
+        expect(source.acquire).toHaveBeenCalledOnce();
+
+        const first = await route.capture(ios, input, signal(), fallback);
+        expect(first.producer).toBe('simulator-ax-bridge');
+        expect(fallback).not.toHaveBeenCalled();
+        expect(run.mock.calls.filter(([args]) => args[0] === 'spawn')).toHaveLength(1);
+      },
+    );
+  } finally {
+    vi.useRealTimers();
+  }
+});
+
 test.each([
   'application-server-unavailable',
   'continuation-budget-exhausted',
diff --git a/packages/platform-apple/src/snapshot-route.ts b/packages/platform-apple/src/snapshot-route.ts
index 339f305088..1961abdca5 100644
--- a/packages/platform-apple/src/snapshot-route.ts
+++ b/packages/platform-apple/src/snapshot-route.ts
@@ -29,6 +29,7 @@ import {
 } from './snapshot-observability.ts';
 import {
   createSimulatorSnapshotTargetResolver,
+  isSimulatorTargetDiscoveryPending,
   type SimulatorSnapshotTarget,
   type SimulatorSnapshotTargetResolver,
 } from './snapshot-target.ts';
@@ -239,19 +240,13 @@ async function resolveTargetForObservation(
     try {
       return await resolveTarget(device, appBundleId, signal);
     } catch (error) {
-      if (!isDiscoveryPending(error)) throw error;
+      if (!isSimulatorTargetDiscoveryPending(error)) throw error;
       const execution = { requestId: input.execution?.requestId };
       if (await host.appleApplications.hasLiveRunnerSession(device, execution)) throw error;
     }
   }
 }
 
-function isDiscoveryPending(error: unknown): boolean {
-  return (
-    error instanceof AppError && error.details?.reason === 'simulator-target-discovery-pending'
-  );
-}
-
 function isEligible(device: DeviceInfo, input: CaptureSnapshotInput): boolean {
   return (
     device.platform === 'apple' &&
diff --git a/packages/platform-apple/src/snapshot-target.ts b/packages/platform-apple/src/snapshot-target.ts
index 3f3cb2755e..b24f7178d5 100644
--- a/packages/platform-apple/src/snapshot-target.ts
+++ b/packages/platform-apple/src/snapshot-target.ts
@@ -15,6 +15,8 @@ const TARGET_IDENTITY_TIMEOUT_MS = 3_000;
 const TARGET_DISCOVERY_WAIT_MS = 1_500;
 /** Overall deadline of one discovery (both simctl probes and the `ps` identity read). */
 const TARGET_DISCOVERY_TIMEOUT_MS = 15_000;
+/** A caller's wait slice ran out while the discovery it joined is still running. */
+const TARGET_DISCOVERY_PENDING = 'simulator-target-discovery-pending';
 
 export type SimulatorSnapshotTarget = Readonly<{
   udid: string;
@@ -62,11 +64,19 @@ export function createSimulatorSnapshotTargetResolver(): SimulatorSnapshotTarget
       },
       wait: (waitMs, stop) =>
         waitForDetachedAttempt({ waitMs, signal, stop, cancelled: () => signal.reason }),
-      pending: () => targetError('simulator-target-discovery-pending', device, appBundleId),
+      pending: () => targetError(TARGET_DISCOVERY_PENDING, device, appBundleId),
     });
   };
 }
 
+/**
+ * Whether a resolver failure only says the discovery is still running. The discovery keeps going
+ * under its own deadline, so asking again joins it rather than starting another.
+ */
+export function isSimulatorTargetDiscoveryPending(error: unknown): boolean {
+  return error instanceof AppError && error.details?.reason === TARGET_DISCOVERY_PENDING;
+}
+
 async function resolveSimulatorSnapshotTarget(
   device: DeviceInfo,
   appBundleId: string,

From 3f2fa08ca7e514bfb59d22d31c54efe59e991eb4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Wed, 23 Sep 2026 19:17:20 +0200
Subject: [PATCH 058/132] fix(ios): stop requesting tap synthesis the runner
 cannot perform on visionOS (#2835)

isIosFamily includes visionOS, so every producer of synthesized:true kept
sending it for visionOS taps even though the runner's synthesis path is
gated behind #if os(iOS) and falls through to an unsupported-message
XCTest fallback on visionOS. Add runnerSynthesizesTap, a named predicate
for the leaves the runner actually synthesizes on (iOS and iPadOS), and
route every synthesized:true producer through it, including the
runner-sequence press-series builder.
---
 packages/kernel/src/device.ts                 | 13 ++++
 .../core/__tests__/apple-core-stub-helpers.ts |  9 +++
 .../src/core/__tests__/interactions.test.ts   | 72 +++++++++++++++++++
 packages/platform-apple/src/interactions.ts   | 16 ++---
 .../src/runner/runner-sequence.ts             |  4 +-
 src/core/__tests__/device.test.ts             | 14 ++++
 6 files changed, 118 insertions(+), 10 deletions(-)

diff --git a/packages/kernel/src/device.ts b/packages/kernel/src/device.ts
index 27501cf043..4aeaa40641 100644
--- a/packages/kernel/src/device.ts
+++ b/packages/kernel/src/device.ts
@@ -178,6 +178,19 @@ export function isTvOsDevice(device: Pick<DeviceInfo, 'platform' | 'target'>): b
   return isApplePlatform(device.platform) && device.target === 'tv';
 }
 
+/**
+ * The Apple leaves whose runner synthesizes tap input (`RunnerTests+SynthesizedInteraction.swift`
+ * gates two-finger HID synthesis behind `#if os(iOS)`, which covers iOS and iPadOS only): every
+ * `isIosFamily` leaf except tvOS (no touchscreen) and visionOS (the runner's `#else` branch, no
+ * synthesis path). Every producer of `synthesized: true` gates on this predicate so none of them
+ * pays for a synthesis attempt the runner cannot perform.
+ */
+export function runnerSynthesizesTap(
+  device: Pick<DeviceInfo, 'platform' | 'appleOs' | 'target'>,
+): boolean {
+  return isIosFamily(device) && !isTvOsDevice(device) && device.appleOs !== 'visionos';
+}
+
 /** Resolve the stored Apple OS, preserving legacy target/leaf inference for old device records. */
 export function resolveDeviceAppleOs(
   device: Pick<DeviceInfo, 'platform' | 'target' | 'appleOs'>,
diff --git a/packages/platform-apple/src/core/__tests__/apple-core-stub-helpers.ts b/packages/platform-apple/src/core/__tests__/apple-core-stub-helpers.ts
index 2b632fabb6..767c608f68 100644
--- a/packages/platform-apple/src/core/__tests__/apple-core-stub-helpers.ts
+++ b/packages/platform-apple/src/core/__tests__/apple-core-stub-helpers.ts
@@ -34,3 +34,12 @@ export const TVOS_TEST_SIMULATOR: DeviceInfo = {
   target: 'tv',
   booted: true,
 };
+
+export const VISIONOS_TEST_SIMULATOR: DeviceInfo = {
+  platform: 'apple',
+  appleOs: 'visionos',
+  id: 'visionos-sim-1',
+  name: 'Apple Vision Pro',
+  kind: 'simulator',
+  booted: true,
+};
diff --git a/packages/platform-apple/src/core/__tests__/interactions.test.ts b/packages/platform-apple/src/core/__tests__/interactions.test.ts
index b07de9e36d..2834331578 100644
--- a/packages/platform-apple/src/core/__tests__/interactions.test.ts
+++ b/packages/platform-apple/src/core/__tests__/interactions.test.ts
@@ -21,6 +21,7 @@ import {
   IOS_TEST_SIMULATOR,
   MACOS_TEST_DEVICE,
   TVOS_TEST_SIMULATOR,
+  VISIONOS_TEST_SIMULATOR,
 } from './apple-core-stub-helpers.ts';
 
 vi.mock('../runner-client.ts', async (importOriginal) => {
@@ -141,6 +142,77 @@ test('iosRunnerOverrides uses synthesized iOS coordinate taps for selectors', as
   });
 });
 
+test('iosRunnerOverrides does not request synthesis for visionOS coordinate taps', async () => {
+  mockRunAppleRunnerCommand.mockResolvedValue({});
+
+  const { overrides } = iosRunnerOverrides(VISIONOS_TEST_SIMULATOR, {
+    appBundleId: 'com.example.App',
+  });
+
+  await overrides.tap(100, 200);
+
+  assert.deepEqual(mockRunAppleRunnerCommand.mock.calls[0]?.[1], {
+    command: 'tap',
+    x: 100,
+    y: 200,
+    appBundleId: 'com.example.App',
+  });
+});
+
+test('iosRunnerOverrides does not request synthesis for visionOS selector taps', async () => {
+  mockRunAppleRunnerCommand.mockResolvedValue({});
+
+  const { overrides } = iosRunnerOverrides(VISIONOS_TEST_SIMULATOR, {
+    appBundleId: 'com.example.App',
+  });
+
+  await overrides.tapElementSelector!({
+    key: 'label',
+    value: 'General',
+    expectedPoint: { x: 200, y: 300 },
+  });
+
+  assert.deepEqual(mockRunAppleRunnerCommand.mock.calls[0]?.[1], {
+    command: 'tap',
+    selectorKey: 'label',
+    selectorValue: 'General',
+    allowNonHittableCoordinateFallback: undefined,
+    x: 200,
+    y: 300,
+    appBundleId: 'com.example.App',
+  });
+});
+
+test('iosRunnerOverrides does not request synthesis for visionOS fused presses', async () => {
+  mockRunAppleRunnerCommand.mockResolvedValue({
+    completedSteps: 3,
+    sequenceResults: Array.from({ length: 3 }, () => ({ ok: true, kind: 'tap' })),
+  });
+  const { overrides } = iosRunnerOverrides(VISIONOS_TEST_SIMULATOR, {
+    appBundleId: 'com.example.App',
+  });
+
+  await overrides.pressPoint!(
+    { x: 100, y: 200 },
+    {
+      button: 'primary',
+      count: 3,
+      intervalMs: 40,
+      holdMs: 0,
+      jitterPx: 2,
+      doubleTap: false,
+    },
+  );
+
+  const command = mockRunAppleRunnerCommand.mock.calls[0]?.[1] as RunnerCommand;
+  assert.equal(command.command, 'sequence');
+  assert.deepEqual(command.steps, [
+    { kind: 'tap', x: 100, y: 200, pauseMs: 40 },
+    { kind: 'tap', x: 102, y: 200, pauseMs: 40 },
+    { kind: 'tap', x: 100, y: 202 },
+  ]);
+});
+
 test('iosRunnerOverrides owns fused repeated presses with deterministic jitter', async () => {
   mockRunAppleRunnerCommand.mockResolvedValue({
     completedSteps: 3,
diff --git a/packages/platform-apple/src/interactions.ts b/packages/platform-apple/src/interactions.ts
index 0c61d7486a..e6048040a0 100644
--- a/packages/platform-apple/src/interactions.ts
+++ b/packages/platform-apple/src/interactions.ts
@@ -19,7 +19,12 @@ import {
   assertScrollGestureInput,
 } from '@agent-device/contracts/scroll-gesture';
 import { assertAppleMultiTouchSupported } from './multitouch-support.ts';
-import { isIosFamily, isMacOs, isTvOsDevice, type DeviceInfo } from '@agent-device/kernel/device';
+import {
+  isMacOs,
+  isTvOsDevice,
+  runnerSynthesizesTap,
+  type DeviceInfo,
+} from '@agent-device/kernel/device';
 import { AppError } from '@agent-device/kernel/errors';
 import { runAppleRunnerCommand, runApplePressSeries } from './core/runner-client.ts';
 import {
@@ -99,7 +104,7 @@ export function iosRunnerOverrides(
             ...(selector.expectedPoint
               ? { x: selector.expectedPoint.x, y: selector.expectedPoint.y }
               : {}),
-            ...(shouldUseSynthesizedIosGesture(device) ? { synthesized: true } : {}),
+            ...(runnerSynthesizesTap(device) ? { synthesized: true } : {}),
             appBundleId: ctx.appBundleId,
           },
           runnerOpts,
@@ -386,16 +391,11 @@ function iosTapCommand(
     command: 'tap',
     x,
     y,
-    ...(shouldUseSynthesizedIosGesture(device) ? { synthesized: true } : {}),
+    ...(runnerSynthesizesTap(device) ? { synthesized: true } : {}),
     appBundleId: ctx.appBundleId,
   };
 }
 
-function shouldUseSynthesizedIosGesture(device: DeviceInfo): boolean {
-  // Two-finger HID synthesis is for touch-input iOS only; the tvOS leaf has no touch.
-  return isIosFamily(device) && !isTvOsDevice(device);
-}
-
 async function runAppleScroll(
   runRunnerCommand: RunAppleRunnerCommand,
   device: DeviceInfo,
diff --git a/packages/platform-apple/src/runner/runner-sequence.ts b/packages/platform-apple/src/runner/runner-sequence.ts
index 48fe8325fb..773b005907 100644
--- a/packages/platform-apple/src/runner/runner-sequence.ts
+++ b/packages/platform-apple/src/runner/runner-sequence.ts
@@ -1,6 +1,6 @@
 import type { PressPointOptions } from '@agent-device/contracts/interactor-types';
 import { pressJitter } from '@agent-device/contracts/touch-runtime';
-import { isIosFamily, isTvOsDevice, type DeviceInfo } from '@agent-device/kernel/device';
+import { runnerSynthesizesTap, type DeviceInfo } from '@agent-device/kernel/device';
 import { AppError, toAppErrorCode } from '@agent-device/kernel/errors';
 import type { RunnerCommand, RunnerSequenceStep } from './runner-contract.ts';
 
@@ -216,7 +216,7 @@ function buildPressSteps(
   options: PressPointOptions,
 ): RunnerSequenceStep[] {
   const kind = options.doubleTap ? 'doubleTap' : options.holdMs > 0 ? 'longPress' : 'tap';
-  const synthesized = kind === 'tap' && isIosFamily(device) && !isTvOsDevice(device);
+  const synthesized = kind === 'tap' && runnerSynthesizesTap(device);
   return Array.from({ length: options.count }, (_, index) => {
     const [dx, dy] = pressJitter(index, options.jitterPx);
     return {
diff --git a/src/core/__tests__/device.test.ts b/src/core/__tests__/device.test.ts
index abf4c02386..a4b0f306b6 100644
--- a/src/core/__tests__/device.test.ts
+++ b/src/core/__tests__/device.test.ts
@@ -8,13 +8,16 @@ import {
   resolveApplePlatformName,
   resolveAppleSimulatorSetPathForSelector,
   resolveDevice,
+  runnerSynthesizesTap,
 } from '@agent-device/kernel/device';
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import {
   ANDROID_TV_DEVICE,
   IOS_SIMULATOR,
+  IPADOS_SIMULATOR,
   MACOS_DEVICE,
   TVOS_SIMULATOR,
+  VISIONOS_SIMULATOR,
 } from '../../__tests__/test-utils/device-fixtures.ts';
 import { AppError } from '@agent-device/kernel/errors';
 
@@ -28,6 +31,17 @@ test('isTvOsDevice selects only the Apple tvOS leaf, not any TV target', () => {
   assert.equal(isTvOsDevice(ANDROID_TV_DEVICE), false);
 });
 
+test('runnerSynthesizesTap selects only the leaves whose runner has a synthesis path', () => {
+  // iOS and iPadOS: the runner's `#if os(iOS)` branch synthesizes.
+  assert.equal(runnerSynthesizesTap(IOS_SIMULATOR), true);
+  assert.equal(runnerSynthesizesTap(IPADOS_SIMULATOR), true);
+  // tvOS has no touchscreen; visionOS's runner has no synthesis path (falls to the
+  // Swift `#else` branch) — neither may carry `synthesized: true`.
+  assert.equal(runnerSynthesizesTap(TVOS_SIMULATOR), false);
+  assert.equal(runnerSynthesizesTap(VISIONOS_SIMULATOR), false);
+  assert.equal(runnerSynthesizesTap(MACOS_DEVICE), false);
+});
+
 test('matchesPlatformSelector resolves apple selector across Apple platforms', () => {
   assert.equal(matchesPlatformSelector({ platform: 'apple', appleOs: 'ios' }, 'apple'), true);
   assert.equal(matchesPlatformSelector({ platform: 'apple', appleOs: 'macos' }, 'apple'), true);

From c3e3451f8a0ce9b410f6c619556a8b60c5ff8f33 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Wed, 23 Sep 2026 19:20:46 +0200
Subject: [PATCH 059/132] test(ios): expect the AX bridge to derive hittability
 in the depth-frontier E2E (#2832)

#2775 made the Simulator AX bridge stamp geometric hittable and disclose the
hittability gap only when no viewport is reported. The live depth-frontier
scenario still required the old gap warning on every bridge capture, so every
iOS Smoke run on main and on rebased PRs failed after #2775 merged.

Assert the new contract instead: a bridge capture with a viewport carries no
hittability-gap warning, and the on-screen projected child is hittable.
---
 .../integration/ios-simulator-e2e/live-assertions.ts |  1 +
 .../live-snapshot-depth-frontier.ts                  | 12 +++++++++---
 2 files changed, 10 insertions(+), 3 deletions(-)

diff --git a/test/integration/ios-simulator-e2e/live-assertions.ts b/test/integration/ios-simulator-e2e/live-assertions.ts
index ba26e47bd0..f01d909243 100644
--- a/test/integration/ios-simulator-e2e/live-assertions.ts
+++ b/test/integration/ios-simulator-e2e/live-assertions.ts
@@ -23,6 +23,7 @@ export const { assertElementText, assertWaitSelector, assertWaitText, capturePng
 
 export type LiveSnapshotNode = {
   depth?: unknown;
+  hittable?: unknown;
   identifier?: unknown;
   index?: unknown;
   label?: unknown;
diff --git a/test/integration/ios-simulator-e2e/live-snapshot-depth-frontier.ts b/test/integration/ios-simulator-e2e/live-snapshot-depth-frontier.ts
index fcee786b44..84997a70d9 100644
--- a/test/integration/ios-simulator-e2e/live-snapshot-depth-frontier.ts
+++ b/test/integration/ios-simulator-e2e/live-snapshot-depth-frontier.ts
@@ -45,6 +45,11 @@ export async function assertRegularVisibleDepthFrontier(context: LiveContext): P
     regularRoot.index,
     `projected child should be reparented to the presented root: ${JSON.stringify(regular)}`,
   );
+  assert.equal(
+    projectedChild.hittable,
+    true,
+    `on-screen projected child should carry geometric hittability: ${JSON.stringify(regular)}`,
+  );
   assert.ok(
     regularNodes.every((node) => numericDepth(node) <= 1),
     `regular --depth 1 exceeded the presented frontier: ${JSON.stringify(regular)}`,
@@ -123,8 +128,9 @@ function assertSimulatorBridgeSnapshot(result: { json?: any }, description: stri
     undefined,
     `${description} must not carry XCTest tree quality metadata: ${JSON.stringify(result)}`,
   );
-  assert.ok(
-    result.json?.data?.warnings?.includes(MISSING_HITTABILITY_WARNING),
-    `${description} must disclose the Simulator AX bridge evidence gap: ${JSON.stringify(result)}`,
+  assert.equal(
+    result.json?.data?.warnings?.includes(MISSING_HITTABILITY_WARNING) ?? false,
+    false,
+    `${description} reported a viewport, so the AX bridge must derive hittability instead of disclosing it as missing: ${JSON.stringify(result)}`,
   );
 }

From 81f39ca0a17247167580bc6cf02a3bc562406ab9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Wed, 23 Sep 2026 19:23:48 +0200
Subject: [PATCH 060/132] fix(apple): classify visionOS simulators from their
 simctl runtime (#2829)

simctl deviceTypeIdentifiers are hyphenated (Apple-Vision-Pro-4K), so the
two-word vision phrases never matched them, and the runtime key was dropped
before classification. A visionOS simulator whose name lacked 'vision' was
reported as appleOs ios. Pass the runtime key, which names xrOS, as a
descriptor.
---
 .../src/simulator-inventory.test.ts           | 21 +++++++++++++++++++
 .../platform-apple/src/simulator-inventory.ts |  2 +-
 2 files changed, 22 insertions(+), 1 deletion(-)

diff --git a/packages/platform-apple/src/simulator-inventory.test.ts b/packages/platform-apple/src/simulator-inventory.test.ts
index 501e42d74c..bf2c66c02d 100644
--- a/packages/platform-apple/src/simulator-inventory.test.ts
+++ b/packages/platform-apple/src/simulator-inventory.test.ts
@@ -68,6 +68,27 @@ test('simctl parser keeps available supported runtimes and their target semantic
   ]);
 });
 
+test('simctl parser classifies visionOS from the runtime when the name is not descriptive', () => {
+  const [device] = parseSimctlAppleDevices(
+    {
+      devices: {
+        'com.apple.CoreSimulator.SimRuntime.xrOS-26-2': [
+          {
+            name: 'test-1',
+            udid: 'vision-1',
+            state: 'Shutdown',
+            isAvailable: true,
+            deviceTypeIdentifier: 'com.apple.CoreSimulator.SimDeviceType.Apple-Vision-Pro-4K',
+          },
+        ],
+      },
+    },
+    undefined,
+  );
+  assert.equal(device?.target, 'mobile');
+  assert.equal(device?.appleOs, 'visionos');
+});
+
 test('simulator inventory scopes bounded simctl and reports fresh booted observations', async () => {
   const calls: Array<{ tool: string; args: readonly string[]; timeoutMs?: number }> = [];
   const observed: string[] = [];
diff --git a/packages/platform-apple/src/simulator-inventory.ts b/packages/platform-apple/src/simulator-inventory.ts
index 80e80bf052..05d316a207 100644
--- a/packages/platform-apple/src/simulator-inventory.ts
+++ b/packages/platform-apple/src/simulator-inventory.ts
@@ -46,7 +46,7 @@ export function parseSimctlAppleDevices(
         name: device.name,
         kind: 'simulator',
         target,
-        appleOs: resolveAppleOs(target, [device.deviceTypeIdentifier ?? '', device.name]),
+        appleOs: resolveAppleOs(target, [runtime, device.deviceTypeIdentifier ?? '', device.name]),
         booted: device.state === 'Booted',
         ...(simulatorSetPath ? { simulatorSetPath } : {}),
       });

From db4feb9cebe29e341875f4780df62eefa413e029 Mon Sep 17 00:00:00 2001
From: alcpereira <48070464+alcpereira@users.noreply.github.com>
Date: Wed, 23 Sep 2026 18:44:06 +0100
Subject: [PATCH 061/132] fix(install): answer the direct lookup in the shape
 Node asks for (#2840) (#2844)

The direct install-source dispatcher pins the connection to the approved
address through a custom lookup that always answered with a single address.
Node 20+ enables network family autoselection by default and calls lookup
with `all: true`, expecting an array, so every direct download failed with
ERR_INVALID_IP_ADDRESS before a socket opened. Proxied downloads were
unaffected.

The lookup now returns `[{ address, family }]` when asked for all addresses
and the single-address form otherwise, matching the maestro runScript
dispatcher. The approved address is still the only one it ever returns.

Closes #2840

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .../install-source-network-transport.test.ts  | 36 +++++++++++++++++--
 .../src/install-source-network-transport.ts   | 10 +++++-
 2 files changed, 43 insertions(+), 3 deletions(-)

diff --git a/packages/provision-kit/src/install-source-network-transport.test.ts b/packages/provision-kit/src/install-source-network-transport.test.ts
index 6c8c78a506..3b219119d8 100644
--- a/packages/provision-kit/src/install-source-network-transport.test.ts
+++ b/packages/provision-kit/src/install-source-network-transport.test.ts
@@ -1,6 +1,13 @@
 import assert from 'node:assert/strict';
-import { test } from 'vitest';
-import { matchesNoProxy, resolveProxyForUrl } from './install-source-network-transport.ts';
+import http from 'node:http';
+import type { AddressInfo } from 'node:net';
+import { text } from 'node:stream/consumers';
+import { test, vi } from 'vitest';
+import {
+  matchesNoProxy,
+  requestApprovedUrl,
+  resolveProxyForUrl,
+} from './install-source-network-transport.ts';
 
 test('lowercase proxy variables override uppercase even when empty', () => {
   assert.equal(
@@ -37,3 +44,28 @@ test('NO_PROXY matches exact hosts, subdomains, ports, wildcards, and bracketed
   );
   assert.equal(matchesNoProxy(new URL('https://elsewhere.example'), '*'), true);
 });
+
+test('direct requests connect to the approved address through the real lookup', async () => {
+  vi.stubEnv('no_proxy', '*');
+  const server = http.createServer((_request, response) => response.end('artifact'));
+  await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+  try {
+    const { port } = server.address() as AddressInfo;
+    const response = await requestApprovedUrl({
+      url: new URL(`http://approved.invalid:${port}/app.zip`),
+      approvedAddress: '127.0.0.1',
+      family: 4,
+      headers: {},
+      signal: AbortSignal.timeout(5_000),
+    });
+    try {
+      assert.equal(response.statusCode, 200);
+      assert.equal(await text(response.body), 'artifact');
+    } finally {
+      await response.close();
+    }
+  } finally {
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+    vi.unstubAllEnvs();
+  }
+});
diff --git a/packages/provision-kit/src/install-source-network-transport.ts b/packages/provision-kit/src/install-source-network-transport.ts
index a32efb9f27..39491de4b6 100644
--- a/packages/provision-kit/src/install-source-network-transport.ts
+++ b/packages/provision-kit/src/install-source-network-transport.ts
@@ -73,7 +73,15 @@ export function matchesNoProxy(url: URL, raw: string | undefined): boolean {
 
 function directDispatcher(address: string, family: 4 | 6): Agent {
   return new Agent({
-    connect: { lookup: (_hostname, _options, callback) => callback(null, address, family) },
+    connect: {
+      lookup: (_hostname, options, callback) => {
+        if (options.all) {
+          callback(null, [{ address, family }]);
+          return;
+        }
+        callback(null, address, family);
+      },
+    },
   });
 }
 

From a913cb222128de3ec4d71dd0086a0221ac384575 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Wed, 23 Sep 2026 19:44:34 +0200
Subject: [PATCH 062/132] fix(ios): keep alert activation out of XCTest's
 interruption handling (#2843)

* fix(ios): keep alert activation out of XCTest's interruption handling

Before every event XCTest looks for SpringBoard banners and alerts over the target and runs its
interruption handler on them. For a notification banner the default handler waits up to 15 s for
it to leave, so an `alert accept` issued while a banner was visible tapped after the command's
deadline and answered ALERT_DEADLINE_EXCEEDED for a button it had in fact pressed (#2546's late
tap, from the banner side). Four iOS CI failures of the alert replacement tests carry this trace,
including main job 106127169259: banner wait from t=7.98 s, tap at t=15.12 s on a ~15 s deadline.

`withBoundedInteractionIdleTimeoutIfSupported(.preEventSkipped)` drops only the idle wait. Alert
activation now also sets XCUIApplication's `doesNotHandleUIInterruptions` on the alert's owner app
for the one tap. It keeps the XCTest coordinate tap and its post-event settle, which alert
verification relies on; the synthesized-event path would have dropped that settle too.

The runner host app gains a `--agent-device-alert-banner` fixture that keeps a notification banner
over its alert until the alert is answered. The new test fails on the old dispatch with the CI
signature (interruption monitors consulted, ALERT_DEADLINE_EXCEEDED after the button was activated)
and passes with the opt-out.

* test(ios): resolve the alert before the deadline the replacement fixtures assert on

Nine iOS CI failures of the alert replacement fixtures answered ALERT_DEADLINE_EXCEEDED with "No
alert button was activated": the command deadline also covered resolution, about two dozen
accessibility reads before any tap, and a contended hosted simulator spent it all there (job
106268275388 sampled a 0.823 s read, sized a 39.5 s deadline, then spent 39 s resolving). The
latency-sampled deadline from #2708 cannot predict a host that slows down mid-command.

The fixtures now resolve the alert first under a 60 s allowance and hand it to the command through
`alertResolutionOverrideForTesting`, so `timeoutMs` bounds only activation and verification, which
is what they prove: the replacement is never activated. That window gets a fixed 30 s. A confirmed
answer returns as soon as verification sees the replacement; only the unprovable-replacement
fixture pays it in full. The latency sampler and its decomposition test are removed.

The busy-app fixture asserted wall-clock success under a fixed 6 s deadline. It now records whether
the button was answered while its animation was still in flight, and the test asserts that instead.
Reverting the seam to a plain `activateElement` fails it with "Answered after the app went idle".

* test(ios): keep the busy alert fixture busy for the test's whole alert budget

The fixture's fixed 20 s backstop could stop the in-flight animation while a
contended host was still resolving the alert under the 60 s allowance, so a
correct activation read "Answered after the app went idle". The test now
passes the backstop as resolution allowance plus activation deadline.
---
 .github/workflows/ios.yml                     |   2 +-
 CHANGELOG.md                                  |   7 +
 .../AgentDeviceRunner/AgentDeviceRunnerApp.m  | 104 ++++++++++-
 .../RunnerTests+Alert.swift                   |  26 ++-
 .../RunnerTests+AlertObservationTests.swift   | 168 ++++++++----------
 5 files changed, 202 insertions(+), 105 deletions(-)

diff --git a/.github/workflows/ios.yml b/.github/workflows/ios.yml
index dc1cda0ec1..81434bc9a0 100644
--- a/.github/workflows/ios.yml
+++ b/.github/workflows/ios.yml
@@ -189,10 +189,10 @@ jobs:
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testAlertAcceptDoesNotActivateAReplacementWithASharedButton \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testAlertDismissDoesNotActivateAReplacementWithTheSameTitle \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testAlertCannotProveAnIdenticalReplacementAndDoesNotActivateIt \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testAlertReplacementCommandDeadlineScalesWithMeasuredLatency \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testAlertDeadlineBeforeActivationLeavesTheOriginalUntouched \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testAlertHittableProbeCompletingAfterDeadlineLeavesTheOriginalUntouched \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testAlertActivationIgnoresAnAppThatNeverSettlesBeforeTheDeadline \
+            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testAlertActivationDoesNotWaitOutANotificationBanner \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testSystemModalProbeSliceSharesAndClampsToPlanDeadline \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testDispatchRecoverySkipsBookkeepingWhileXCTestChannelOccupied \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testBoundedSystemModalProbeTimeoutRecoversThenReleasesOnDrain \
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9bf19bbaba..688e453617 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,13 @@
   CI it spent its whole 10 s budget there (`wait_capture_stalled` with `captures: 1`). The probe now
   joins the running discovery, bounded by the discovery's own deadline, and then observes the launch
   as before. A resolution failure other than a pending discovery still ends the probe at once.
+- Fixed (ios): `alert accept` and `alert dismiss` no longer land their tap after the command's
+  deadline when a notification banner is on screen. XCTest checks for SpringBoard banners and alerts
+  before every event and its default handler waited up to 15 s for a banner to leave, so the command
+  answered `ALERT_DEADLINE_EXCEEDED` ("The button was activated once") for a tap that arrived after
+  the caller was told it had failed (#2546's late tap, from the banner side). Alert activation now
+  opts out of XCTest's interruption handling, which also stops that handler from pressing a button of
+  its own choosing on an unrelated system alert while the command answers the alert it resolved.
 - Fixed (ios): a local Simulator snapshot taken through the host AX bridge once again publishes the
   geometric `hittable` fact, so `is hittable` and a `hittable:` selector resolve the same controls on
   the bridge and the XCTest runner. The snapshot capability table has declared `hittable =
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunner/AgentDeviceRunnerApp.m b/apple/runner/AgentDeviceRunner/AgentDeviceRunner/AgentDeviceRunnerApp.m
index 7ed0af0bb4..937f0f3d59 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunner/AgentDeviceRunnerApp.m
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunner/AgentDeviceRunnerApp.m
@@ -56,15 +56,25 @@ int main(int argc, const char *argv[]) {
 
 #else
 #import <UIKit/UIKit.h>
+#if TARGET_OS_IOS
+#import <UserNotifications/UserNotifications.h>
+#endif
 
 @interface AgentDeviceRunnerViewController : UIViewController
 @property(nonatomic, strong) UILabel *alertActionStatus;
+@property(nonatomic, strong) UILabel *alertActivationBusyAnswer;
 @property(nonatomic, assign) NSUInteger firstAlertActions;
 @property(nonatomic, assign) NSUInteger replacementAlertActions;
 @property(nonatomic, assign) BOOL alertFixtureStarted;
 @property(nonatomic, strong) NSTimer *alertActivationBusyBackstop;
+@property(nonatomic, strong) NSTimer *alertBannerRepost;
 @end
 
+#if TARGET_OS_IOS
+@interface AgentDeviceRunnerViewController () <UNUserNotificationCenterDelegate>
+@end
+#endif
+
 @implementation AgentDeviceRunnerViewController
 
 #if TARGET_OS_IOS
@@ -72,15 +82,21 @@ @implementation AgentDeviceRunnerViewController
 // may receive an event: the app keeps reporting work in flight, which is the state that cost an alert
 // command its whole deadline in #2546. It stops the moment an alert button is answered, since that
 // answer is the event the runner is trying to land, and the backstop stops it even when no answer
-// arrives so a regressed run finishes rather than waiting out XCTest's own timeout. A layer
+// arrives so a regressed run finishes rather than waiting out XCTest's own timeout. The test passes
+// the backstop after `--agent-device-alert-activation-busy`, sized to outlast its whole resolution
+// and activation budget, so a slow host cannot end the busy state before the answer lands. A layer
 // animation on its own is not enough; only a UIView animation counts as in-flight work here.
-static NSTimeInterval const kAgentDeviceAlertActivationBusyWindow = 20.0;
+static NSTimeInterval AgentDeviceAlertActivationBusyWindow(void) {
+  NSArray<NSString *> *arguments = NSProcessInfo.processInfo.arguments;
+  NSUInteger flag = [arguments indexOfObject:@"--agent-device-alert-activation-busy"];
+  return flag + 1 < arguments.count ? arguments[flag + 1].doubleValue : 0;
+}
 
 - (void)startAlertActivationBusy {
   if (self.alertActivationBusyBackstop != nil) {
     return;
   }
-  self.alertActivationBusyBackstop = [NSTimer scheduledTimerWithTimeInterval:kAgentDeviceAlertActivationBusyWindow
+  self.alertActivationBusyBackstop = [NSTimer scheduledTimerWithTimeInterval:AgentDeviceAlertActivationBusyWindow()
                                                                       target:self
                                                                     selector:@selector(stopAlertActivationBusy)
                                                                     userInfo:nil
@@ -101,6 +117,57 @@ - (void)stopAlertActivationBusy {
   self.alertActivationBusyBackstop = nil;
 }
 
+// A banner from this app, shown over its own alert and re-posted before the previous one expires so
+// one is on screen for as long as the first alert is unanswered. XCTest treats such a banner as an
+// interruption of every event aimed at the app (#2546's late tap, from the banner side).
+- (void)startAlertBannerThen:(dispatch_block_t)presentAlert {
+  UNUserNotificationCenter *center = UNUserNotificationCenter.currentNotificationCenter;
+  center.delegate = self;
+  [center requestAuthorizationWithOptions:UNAuthorizationOptionAlert
+                        completionHandler:^(BOOL granted, NSError *error) {
+                          (void)error;
+                          if (!granted) {
+                            return;
+                          }
+                          dispatch_async(dispatch_get_main_queue(), ^{
+                            presentAlert();
+                            [self postAlertBanner];
+                            self.alertBannerRepost = [NSTimer scheduledTimerWithTimeInterval:2.0
+                                                                                      target:self
+                                                                                    selector:@selector(postAlertBanner)
+                                                                                    userInfo:nil
+                                                                                     repeats:YES];
+                          });
+                        }];
+}
+
+- (void)postAlertBanner {
+  UNMutableNotificationContent *content = [[UNMutableNotificationContent alloc] init];
+  content.title = @"Agent Device banner";
+  content.body = @"Shown over the alert fixture";
+  UNNotificationRequest *request = [UNNotificationRequest requestWithIdentifier:NSUUID.UUID.UUIDString
+                                                                        content:content
+                                                                        trigger:nil];
+  [UNUserNotificationCenter.currentNotificationCenter addNotificationRequest:request withCompletionHandler:nil];
+}
+
+- (void)stopAlertBanner {
+  if (self.alertBannerRepost == nil) {
+    return;
+  }
+  [self.alertBannerRepost invalidate];
+  self.alertBannerRepost = nil;
+  [UNUserNotificationCenter.currentNotificationCenter removeAllDeliveredNotifications];
+}
+
+- (void)userNotificationCenter:(UNUserNotificationCenter *)center
+       willPresentNotification:(UNNotification *)notification
+         withCompletionHandler:(void (^)(UNNotificationPresentationOptions options))completionHandler {
+  (void)center;
+  (void)notification;
+  completionHandler(UNNotificationPresentationOptionBanner);
+}
+
 
 - (void)updateAlertActionStatus {
   self.alertActionStatus.text = [NSString stringWithFormat:@"First actions: %lu; replacement actions: %lu",
@@ -123,7 +190,12 @@ - (void)presentAlertFixtureReplacement:(BOOL)replacement {
         ? UIAlertActionStyleCancel : UIAlertActionStyleDefault;
     [alert addAction:[UIAlertAction actionWithTitle:buttonTitle style:style handler:^(UIAlertAction *action) {
       (void)action;
+      if (!replacement) {
+        self.alertActivationBusyAnswer.text = self.alertActivationBusyBackstop != nil
+            ? @"Answered while busy" : @"Answered after the app went idle";
+      }
       [self stopAlertActivationBusy];
+      [self stopAlertBanner];
       if (replacement) {
         self.replacementAlertActions += 1;
       } else {
@@ -145,9 +217,16 @@ - (void)viewDidAppear:(BOOL)animated {
   if (!self.alertFixtureStarted &&
       [NSProcessInfo.processInfo.arguments containsObject:@"--agent-device-alert-replacement-regression"]) {
     self.alertFixtureStarted = YES;
-    [self presentAlertFixtureReplacement:NO];
-    if ([NSProcessInfo.processInfo.arguments containsObject:@"--agent-device-alert-activation-busy"]) {
-      [self startAlertActivationBusy];
+    dispatch_block_t presentAlert = ^{
+      [self presentAlertFixtureReplacement:NO];
+      if ([NSProcessInfo.processInfo.arguments containsObject:@"--agent-device-alert-activation-busy"]) {
+        [self startAlertActivationBusy];
+      }
+    };
+    if ([NSProcessInfo.processInfo.arguments containsObject:@"--agent-device-alert-banner"]) {
+      [self startAlertBannerThen:presentAlert];
+    } else {
+      presentAlert();
     }
   }
 }
@@ -185,6 +264,19 @@ - (void)viewDidLoad {
     [self updateAlertActionStatus];
   }
 
+  if ([NSProcessInfo.processInfo.arguments containsObject:@"--agent-device-alert-activation-busy"]) {
+    UILabel *busyAnswer = [[UILabel alloc] init];
+    busyAnswer.text = @"Unanswered";
+    busyAnswer.accessibilityIdentifier = @"agent-device-alert-busy-answer";
+    busyAnswer.translatesAutoresizingMaskIntoConstraints = NO;
+    [self.view addSubview:busyAnswer];
+    [NSLayoutConstraint activateConstraints:@[
+      [busyAnswer.centerXAnchor constraintEqualToAnchor:self.view.centerXAnchor],
+      [busyAnswer.topAnchor constraintEqualToAnchor:label.bottomAnchor constant:24],
+    ]];
+    self.alertActivationBusyAnswer = busyAnswer;
+  }
+
   if ([NSProcessInfo.processInfo.arguments containsObject:@"--agent-device-text-entry-regression"]) {
     UITextField *textField = [[UITextField alloc] init];
     textField.accessibilityIdentifier = @"agent-device-hardware-keyboard-input";
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Alert.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Alert.swift
index 4503003d31..483862a3af 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Alert.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Alert.swift
@@ -76,15 +76,17 @@ extension RunnerTests {
         buttonFrame.origin.x, buttonFrame.origin.y, buttonFrame.size.width, buttonFrame.size.height,
         buttonFrame.midX, buttonFrame.midY
       )
-      // The hittable read above is this activation's readiness gate, so XCTest's pre-synthesis wait
-      // adds nothing and can cost more than the command has: the tap would land after the deadline
+      // The hittable read above is this activation's readiness gate, so XCTest's pre-synthesis waits
+      // add nothing and can cost more than the command has: the tap would land after the deadline
       // expired and the alert would be answered by a button the caller was told nothing about
       // (#2546). The post-tap settle stays, because the verification below reads the alert this tap
       // replaces; an alert that dismisses and presents an identical replacement passes through a
       // window with no alert, and a first read landing there reports a dismissal nothing proved.
       var outcome = RunnerInteractionOutcome.performed
-      withBoundedInteractionIdleTimeoutIfSupported(alert.ownerApp, waits: .preEventSkipped) {
-        outcome = activateElement(app: alert.ownerApp, element: button, action: "alert \(action)")
+      withUIInterruptionHandlingDisabledIfSupported(alert.ownerApp) {
+        withBoundedInteractionIdleTimeoutIfSupported(alert.ownerApp, waits: .preEventSkipped) {
+          outcome = activateElement(app: alert.ownerApp, element: button, action: "alert \(action)")
+        }
       }
       if let response = unsupportedResponse(for: outcome) {
         return response
@@ -114,6 +116,22 @@ extension RunnerTests {
     )
   }
 
+  /// Before each event XCTest looks for SpringBoard elements over the target and hands them to its
+  /// interruption handler, which waits up to 15 s for a notification banner to leave and taps a
+  /// button of its own choosing on any other alert. An alert command answers exactly the alert it
+  /// resolved, with the button it chose, before its deadline, so it opts out of both.
+  private func withUIInterruptionHandlingDisabledIfSupported(_ target: XCUIApplication, operation: () -> Void) {
+    let key = "doesNotHandleUIInterruptions"
+    guard target.responds(to: NSSelectorFromString("setDoesNotHandleUIInterruptions:")) else {
+      operation()
+      return
+    }
+    let previous = target.value(forKey: key) as? NSNumber
+    target.setValue(true, forKey: key)
+    defer { target.setValue(previous?.boolValue ?? false, forKey: key) }
+    operation()
+  }
+
   private func runnerAlert(_ modal: ResolvedBlockingSystemModal) -> RunnerAlert? {
     let buttons = modal.actions.filter { isEnabledElement($0) }
     guard !buttons.isEmpty else {
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+AlertObservationTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+AlertObservationTests.swift
index 508ed18691..b57b0ed27c 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+AlertObservationTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+AlertObservationTests.swift
@@ -18,23 +18,6 @@ extension RunnerTests {
     )
   }
 
-  func testAlertReplacementCommandDeadlineScalesWithMeasuredLatency() {
-    // A quiet host still asks for the production default: 24 reads at 10 ms is a quarter of a second.
-    XCTAssertEqual(RunnerTests.alertReplacementCommandTimeoutMs(measuredRoundTrip: 0.001), 10_000)
-    XCTAssertEqual(RunnerTests.alertReplacementCommandTimeoutMs(measuredRoundTrip: 0.01), 10_000)
-    // The linear region is where a contended host lands: one second per read buys the 24 reads
-    // twice over, which is what the red nightly nights needed and 10 s did not cover.
-    XCTAssertEqual(RunnerTests.alertReplacementCommandTimeoutMs(measuredRoundTrip: 1), 48_000)
-    // Past the cap the fixture gives up rather than dominate the lane, whatever the host costs.
-    XCTAssertEqual(RunnerTests.alertReplacementCommandTimeoutMs(measuredRoundTrip: 2.5), 60_000)
-    XCTAssertEqual(RunnerTests.alertReplacementCommandTimeoutMs(measuredRoundTrip: 300), 60_000)
-    XCTAssertEqual(
-      RunnerTests.alertResolutionReadsBeforeActivation,
-      24,
-      "the decomposition below is the traced command path; re-trace it before changing a count"
-    )
-  }
-
   func testAlertDeadlineBeforeActivationLeavesTheOriginalUntouched() throws {
     app.launchArguments = ["--agent-device-alert-replacement-regression"]
     app.launch()
@@ -43,7 +26,7 @@ extension RunnerTests {
       app.terminate()
     }
     XCTAssertTrue(app.alerts.firstMatch.waitForExistence(timeout: appExistenceTimeout))
-    let alert = try XCTUnwrap(resolveAlert(app: app, deadline: Date().addingTimeInterval(10)))
+    let alert = try resolveAlertBeforeTheCommand()
     let response = handleAlert(alert, action: "accept", deadline: .distantPast)
     XCTAssertFalse(response.ok)
     XCTAssertEqual(response.error?.code, "ALERT_DEADLINE_EXCEEDED")
@@ -60,7 +43,7 @@ extension RunnerTests {
       app.terminate()
     }
     XCTAssertTrue(app.alerts.firstMatch.waitForExistence(timeout: appExistenceTimeout))
-    let alert = try XCTUnwrap(resolveAlert(app: app, deadline: Date().addingTimeInterval(10)))
+    let alert = try resolveAlertBeforeTheCommand()
     alertButtonHittabilityProbeOverrideForTesting = { probeDeadline in
       while Date() < probeDeadline {
         Thread.sleep(forTimeInterval: min(0.02, max(0, probeDeadline.timeIntervalSinceNow)))
@@ -77,7 +60,8 @@ extension RunnerTests {
   func testAlertActivationIgnoresAnAppThatNeverSettlesBeforeTheDeadline() throws {
     app.launchArguments = [
       "--agent-device-alert-replacement-regression",
-      "--agent-device-alert-activation-busy"
+      "--agent-device-alert-activation-busy",
+      String(RunnerTests.alertResolutionAllowance + RunnerTests.alertActivationDeadline)
     ]
     app.launch()
     defer {
@@ -85,105 +69,101 @@ extension RunnerTests {
       app.terminate()
     }
     XCTAssertTrue(app.alerts.firstMatch.waitForExistence(timeout: appExistenceTimeout))
-    let alert = try XCTUnwrap(resolveAlert(app: app, deadline: Date().addingTimeInterval(10)))
+    let alert = try resolveAlertBeforeTheCommand()
 
-    let deadline = Date().addingTimeInterval(6)
-    let startedAt = Date()
-    let response = handleAlert(alert, action: "accept", deadline: deadline)
-    let elapsed = Date().timeIntervalSince(startedAt)
+    let response = handleAlert(alert, action: "accept", deadline: Date().addingTimeInterval(RunnerTests.alertActivationDeadline))
 
-    // The fixture keeps an animation in flight, which is what XCTest waits out before it synthesises
-    // an event, so this comes back early only because activation refused to wait for an app that has
-    // no intention of settling (#2546).
-    XCTAssertLessThan(elapsed, 9, "activation waited \(elapsed)s for a busy app to idle")
+    // The fixture keeps an animation in flight until a button is answered or its backstop, which
+    // outlasts resolution plus activation, stops it, and an in-flight animation is what XCTest waits
+    // out before it synthesises an event. An answer that arrives while the app is still busy is one
+    // activation did not wait to idle (#2546).
     XCTAssertTrue(response.ok, String(describing: response.error))
-    let recordedActions = app.staticTexts["agent-device-alert-actions"].label
-    if response.ok {
-      XCTAssertEqual(recordedActions, "First actions: 1; replacement actions: 0")
-    } else {
-      XCTAssertEqual(
-        recordedActions,
-        "First actions: 0; replacement actions: 0",
-        "a caller told about an expired deadline must not have a button activated behind it"
-      )
-    }
+    XCTAssertEqual(app.staticTexts["agent-device-alert-actions"].label, "First actions: 1; replacement actions: 0")
+    XCTAssertEqual(app.staticTexts["agent-device-alert-busy-answer"].label, "Answered while busy")
   }
 
-  /// The accessibility round trips `resolveAlert` spends before a button is chosen, decomposed from
-  /// the implementation rather than counted off one trace: the blocking-modal probe scans
-  /// SpringBoard's alert and sheet lists and re-reads the candidate it settles on; the app's own
-  /// alert list is resolved and then read for existence and frame; `actionableElements` issues one
-  /// fetch per member of `actionableTypes`; and every candidate then pays `exists`, `isHittable`,
-  /// `elementType`, `frame`, `label` and `isEnabled` of its own.
-  static let alertResolutionModalProbeReads = 3
-  static let alertResolutionAlertRootReads = 3
-  static let alertResolutionActionableTypeReads = 6
-  static let alertResolutionButtonCandidates = 2
-  static let alertResolutionCandidateReads = 6
-
-  static let alertResolutionReadsBeforeActivation =
-    alertResolutionModalProbeReads + alertResolutionAlertRootReads + alertResolutionActionableTypeReads
-    + alertResolutionButtonCandidates * alertResolutionCandidateReads
-
-  /// The reads that follow resolution — the hittability wait and the first verification observation
-  /// run on the same channel — plus the allowance for a host that gets slower mid-command.
-  private static let alertCommandSafetyFactor: TimeInterval = 2
-
-  /// No higher than the slowest test this lane already runs (61 s on a green nightly), so a badly
-  /// starved host cannot make these fixtures the lane's worst contributor. The cap covers the worst
-  /// night traced so far, which needed 40.4 s of deadline.
-  private static let alertCommandTimeoutCap: TimeInterval = 60
-
-  /// The alert command's deadline for the replacement fixtures.
-  ///
-  /// `timeoutMs` bounds the whole command, so it is only meaningful in units of what one
-  /// accessibility read costs this host right now: `RunnerTests+Alert.swift` starts the deadline at
-  /// dispatch and the resolution above spends all of it reading before anything is activated. The
-  /// hosted lane runs a read at about 10 ms on a healthy night and about 1.7 s on a red one, which
-  /// is why the fixed 10 s these fixtures asked for passed on green nights and expired mid-resolution
-  /// on red ones (runs 35, 36 and 37 needed 31.2 s, 30.6 s and 40.4 s). Deriving the budget from a
-  /// measured read is `docs/agents/testing.md`'s preferred answer for a timeout that only fails on a
-  /// contended host; production still defaults to `defaultAlertCommandTimeout` for real callers.
-  static func alertReplacementCommandTimeoutMs(measuredRoundTrip: TimeInterval) -> Int {
-    let derived = measuredRoundTrip * Double(alertResolutionReadsBeforeActivation) * alertCommandSafetyFactor
-    return Int((min(max(derived, defaultAlertCommandTimeout), alertCommandTimeoutCap) * 1000).rounded())
+  func testAlertActivationDoesNotWaitOutANotificationBanner() throws {
+    app.launchArguments = ["--agent-device-alert-replacement-regression", "--agent-device-alert-banner"]
+    app.launch()
+    let banner = XCUIApplication(bundleIdentifier: "com.apple.springboard")
+      .descendants(matching: .any)["NotificationShortLookView"]
+    var consultedInterruptions: [String] = []
+    let monitor = addUIInterruptionMonitor(withDescription: "alert activation banner") { element in
+      consultedInterruptions.append(element.identifier)
+      return false
+    }
+    defer {
+      removeUIInterruptionMonitor(monitor)
+      invalidateCachedTarget(reason: "unit_test_cleanup")
+      app.terminate()
+      _ = banner.waitForNonExistence(timeout: 15)
+    }
+    acceptNotificationAuthorizationUntilAlertAppears()
+    XCTAssertTrue(banner.waitForExistence(timeout: appExistenceTimeout), "the fixture keeps a banner up")
+    let alert = try resolveAlertBeforeTheCommand()
+
+    let response = handleAlert(alert, action: "accept", deadline: Date().addingTimeInterval(RunnerTests.alertActivationDeadline))
+
+    XCTAssertEqual(consultedInterruptions, [], "alert activation waited on XCTest's interruption handling")
+    XCTAssertTrue(response.ok, String(describing: response.error))
+    XCTAssertEqual(app.staticTexts["agent-device-alert-actions"].label, "First actions: 1; replacement actions: 0")
   }
 
-  /// Samples the read the command is about to pay 24 times, once the alert is up, so the sample comes
-  /// from the window the command runs in. Two samples and the slower one wins: a single lucky read
-  /// must not size the budget low, and this is a worst-of measurement, not a mean.
-  private func measuredAccessibilityRoundTrip() -> TimeInterval {
-    let recordedActions = app.staticTexts["agent-device-alert-actions"]
-    var roundTrip = TimeInterval(0.001)
-    for _ in 0..<2 {
-      let startedAt = Date()
-      _ = recordedActions.label
-      roundTrip = max(roundTrip, Date().timeIntervalSince(startedAt))
+  /// The banner fixture presents its alert only once this app may post notifications; a fresh
+  /// simulator asks first, through SpringBoard.
+  private func acceptNotificationAuthorizationUntilAlertAppears() {
+    let allow = XCUIApplication(bundleIdentifier: "com.apple.springboard").alerts.buttons["Allow"]
+    let fixtureAlert = app.alerts.firstMatch
+    let deadline = Date().addingTimeInterval(appExistenceTimeout)
+    while Date() < deadline, !fixtureAlert.exists {
+      if allow.exists {
+        allow.tap()
+      } else {
+        Thread.sleep(forTimeInterval: 0.25)
+      }
     }
-    return roundTrip
+    XCTAssertTrue(fixtureAlert.exists, "the banner fixture needs notification authorization before it presents its alert")
+  }
+
+  /// Resolution reads the alert, its owner and every candidate button before anything is activated,
+  /// and a contended hosted simulator has spent 40 s of reads there. These fixtures prove what
+  /// activation and verification do, so they resolve first under this allowance, which only a failed
+  /// resolution ever spends.
+  static let alertResolutionAllowance: TimeInterval = 60
+
+  /// The deadline activation and verification run under once the alert is resolved: a confirmed
+  /// answer returns as soon as verification sees the replacement, so only a fixture whose answer is
+  /// the deadline itself pays it in full. It buys the dozen reads after resolution 2.5 s each, above the
+  /// 1.7 s a read cost on the worst hosted nights traced (#2708).
+  static let alertActivationDeadline: TimeInterval = 30
+
+  private func resolveAlertBeforeTheCommand() throws -> RunnerAlert {
+    try XCTUnwrap(resolveAlert(app: app, deadline: Date().addingTimeInterval(RunnerTests.alertResolutionAllowance)))
   }
 
   private func assertReplacementAlertUntouched(action: String, arguments: [String], confirmed: Bool) throws {
     app.launchArguments = ["--agent-device-alert-replacement-regression"] + arguments
     app.launch()
     defer {
+      alertResolutionOverrideForTesting = nil
       invalidateCachedTarget(reason: "unit_test_cleanup")
       app.terminate()
     }
     XCTAssertTrue(app.alerts.firstMatch.waitForExistence(timeout: appExistenceTimeout))
-    let measuredRoundTrip = measuredAccessibilityRoundTrip()
-    let timeoutMs = RunnerTests.alertReplacementCommandTimeoutMs(measuredRoundTrip: measuredRoundTrip)
+    let original = try resolveAlertBeforeTheCommand()
+    alertResolutionOverrideForTesting = { _ in original }
+    let timeoutMs = Int(RunnerTests.alertActivationDeadline * 1000)
     let command = try runnerCommandFixture(
       #"{"command":"alert","commandId":"alert-replacement","action":"\#(action)","timeoutMs":\#(timeoutMs)}"#
     )
     let response = try executeOnMainPrepared(command: command, activeApp: app)
-    let budget = "timeoutMs \(timeoutMs) from a \(String(format: "%.3f", measuredRoundTrip))s read"
-    XCTAssertEqual(response.ok, confirmed, "\(budget): \(String(describing: response.error))")
+    alertResolutionOverrideForTesting = nil
+    XCTAssertEqual(response.ok, confirmed, String(describing: response.error))
     if !confirmed { XCTAssertEqual(response.error?.code, "ALERT_DEADLINE_EXCEEDED") }
     XCTAssertTrue(app.alerts.firstMatch.exists, "the replacement must remain visible")
     XCTAssertEqual(app.staticTexts["agent-device-alert-actions"].label, "First actions: 1; replacement actions: 0")
-    let current = try XCTUnwrap(resolveAlert(app: app, deadline: Date().addingTimeInterval(10)))
-    let inspection = handleAlert(current, action: "get", deadline: Date().addingTimeInterval(10))
+    let current = try resolveAlertBeforeTheCommand()
+    let inspection = handleAlert(current, action: "get", deadline: Date().addingTimeInterval(RunnerTests.alertActivationDeadline))
     XCTAssertTrue(inspection.ok)
     XCTAssertEqual(inspection.data?.items?.sorted(), ["Cancel", "OK"])
     XCTAssertEqual(app.staticTexts["agent-device-alert-actions"].label, "First actions: 1; replacement actions: 0")

From f5475e81d67d83aa0df31d9badcd0ece0027a691 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Wed, 23 Sep 2026 20:13:50 +0200
Subject: [PATCH 063/132] chore(ios-runner): delete the unreachable synthesized
 continuous drag profile (#2825)

* chore(ios-runner): delete the unreachable synthesized continuous drag profile

The only daemon producer of the runner `drag` command is macOS-only and never
sets `synthesized`, so the smoothstep `.continuous` profile could not run.
Remove the ObjC continuous path and frame-count export, the Swift enum case,
the `synthesized:` parameter and second synthesized block in
`executeDragGesture`, and its frame-count test. `.fastSwipe` and
`.controlledScroll` are untouched; ADR 0013 now describes the scroll schedule
that remains.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* refactor(ios-runner): carry the drag synthesis profile and policy as one optional

Plain coordinate drags no longer name a synthesized policy they never apply;
the activation-preflight drag fixture stops sending the ignored flag. ADR 0011
and 0013 describe the synthesized lanes that remain.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .../RunnerSynthesizedGesture.h                |  9 ---
 .../RunnerSynthesizedGesture.m                | 56 ---------------
 .../RunnerTests+CommandExecution.swift        | 69 ++++---------------
 .../RunnerTests+Interaction.swift             |  1 -
 .../RunnerTests+ScrollGesture.swift           |  5 --
 .../RunnerTests+SynthesizedInteraction.swift  | 12 +---
 .../0011-interaction-guarantee-contract.md    |  6 +-
 docs/adr/0013-unified-gesture-plans.md        | 27 ++++----
 8 files changed, 33 insertions(+), 152 deletions(-)

diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerSynthesizedGesture.h b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerSynthesizedGesture.h
index e606041e8d..27ee022545 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerSynthesizedGesture.h
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerSynthesizedGesture.h
@@ -2,7 +2,6 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
-FOUNDATION_EXPORT NSInteger RunnerContinuousDragFrameCount(double durationMs);
 FOUNDATION_EXPORT NSInteger RunnerControlledScrollFrameCount(double durationMs);
 FOUNDATION_EXPORT double RunnerControlledScrollProgress(double t);
 
@@ -19,14 +18,6 @@ FOUNDATION_EXPORT double RunnerControlledScrollProgress(double t);
                                                    y2:(double)y2
                                             durationMs:(double)durationMs;
 
-+ (NSString * _Nullable)synthesizeContinuousDragWithApplication:(id)application
-                                                resolvedWindow:(id _Nullable)resolvedWindow
-                                                             x:(double)x
-                                                             y:(double)y
-                                                            x2:(double)x2
-                                                            y2:(double)y2
-                                                     durationMs:(double)durationMs;
-
 + (NSString * _Nullable)synthesizeControlledScrollWithApplication:(id)application
                                                  resolvedWindow:(id _Nullable)resolvedWindow
                                                                 x:(double)x
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerSynthesizedGesture.m b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerSynthesizedGesture.m
index 5767bb0c7d..bb6a2039aa 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerSynthesizedGesture.m
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerSynthesizedGesture.m
@@ -52,12 +52,6 @@ static id RunnerSwipePointerPath(
   CGPoint end,
   double durationMs
 );
-static id RunnerContinuousDragPointerPath(
-  const RunnerGestureEventBridge *bridge,
-  CGPoint start,
-  CGPoint end,
-  double durationMs
-);
 static id RunnerControlledScrollPointerPath(
   const RunnerGestureEventBridge *bridge,
   CGPoint start,
@@ -72,7 +66,6 @@ static id RunnerSampledDragPointerPath(
   RunnerDragProgressFunction progress,
   NSInteger frameCount
 );
-static double RunnerSmoothstepProgress(double t);
 static NSString * _Nullable RunnerTrySynthesizeDrag(
   id application,
   id _Nullable resolvedWindow,
@@ -117,28 +110,6 @@ + (NSString * _Nullable)synthesizeSwipeWithApplication:(id)application
   }
 }
 
-+ (NSString * _Nullable)synthesizeContinuousDragWithApplication:(id)application
-                                                resolvedWindow:(id _Nullable)resolvedWindow
-                                                             x:(double)x
-                                                             y:(double)y
-                                                            x2:(double)x2
-                                                            y2:(double)y2
-                                                     durationMs:(double)durationMs {
-  @try {
-    return RunnerTrySynthesizeDrag(
-      application,
-      resolvedWindow,
-      CGPointMake(x, y),
-      CGPointMake(x2, y2),
-      durationMs,
-      @"agent-device-continuous-drag",
-      RunnerContinuousDragPointerPath
-    );
-  } @catch (NSException *exception) {
-    return RunnerFormatXCTestException(exception, @"private XCTest event synthesis failed");
-  }
-}
-
 + (NSString * _Nullable)synthesizeControlledScrollWithApplication:(id)application
                                                  resolvedWindow:(id _Nullable)resolvedWindow
                                                                 x:(double)x
@@ -411,25 +382,6 @@ static id RunnerSwipePointerPath(
   return path;
 }
 
-static id RunnerContinuousDragPointerPath(
-  const RunnerGestureEventBridge *bridge,
-  CGPoint start,
-  CGPoint end,
-  double durationMs
-) {
-  // This is velocity shaping, not just interpolation density: smoothstep's endpoint slope is zero,
-  // while a planned linear segment reaches lift with nonzero velocity unless a destination hold
-  // follows it. UIKit uses finger-up velocity for scroll deceleration. See ADR 0013 and issue #1586.
-  return RunnerSampledDragPointerPath(
-    bridge,
-    start,
-    end,
-    durationMs,
-    RunnerSmoothstepProgress,
-    RunnerContinuousDragFrameCount(durationMs)
-  );
-}
-
 static id RunnerControlledScrollPointerPath(
   const RunnerGestureEventBridge *bridge,
   CGPoint start,
@@ -478,14 +430,6 @@ static id RunnerSampledDragPointerPath(
   return path;
 }
 
-static double RunnerSmoothstepProgress(double t) {
-  return t * t * (3.0 - 2.0 * t);
-}
-
-NSInteger RunnerContinuousDragFrameCount(double durationMs) {
-  return MAX(3, (NSInteger)(durationMs / RunnerDragSampleIntervalMs));
-}
-
 NSInteger RunnerControlledScrollFrameCount(double durationMs) {
   return MIN(
     RunnerControlledScrollMaxFrameCount,
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
index 223103f893..b4e50a3ab5 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
@@ -796,7 +796,7 @@ extension RunnerTests {
       app.terminate()
     }
     let drag = try runnerCommandFixture(
-      #"{"command":"drag","commandId":"drag-1","x":10,"y":20,"x2":30,"y2":40,"synthesized":true}"#
+      #"{"command":"drag","commandId":"drag-1","x":10,"y":20,"x2":30,"y2":40}"#
     )
     let scroll = try runnerCommandFixture(
       #"{"command":"scroll","commandId":"scroll-1","direction":"down","pixels":400}"#
@@ -1867,9 +1867,7 @@ extension RunnerTests {
         x2: x2,
         y2: y2,
         durationMs: defaults.durationMs,
-        synthesized: command.synthesized == true,
-        message: "dragged",
-        synthesizedPolicyKind: .synthesizedDrag
+        message: "dragged"
       )
     case .scroll:
       // Fused frame-resolve + drag scroll for non-tvOS. On iOS this intentionally stays on the
@@ -2240,10 +2238,8 @@ extension RunnerTests {
             x2: last.x,
             y2: last.y,
             durationMs: plan.durationMs,
-            synthesized: true,
             message: plan.intent,
-            synthesizedPolicyKind: .synthesizedDrag,
-            synthesizedProfile: .fastSwipe
+            synthesized: (profile: .fastSwipe, policyKind: .synthesizedDrag)
           )
         )
       case .sampled:
@@ -2307,11 +2303,9 @@ extension RunnerTests {
       x2: x2,
       y2: y2,
       durationMs: durationMs,
-      synthesized: true,
       message: message,
       synthesizedContext: context,
-      synthesizedPolicyKind: .scroll,
-      synthesizedProfile: scrollDragProfile(releaseBehavior: releaseBehavior)
+      synthesized: (profile: scrollDragProfile(releaseBehavior: releaseBehavior), policyKind: .scroll)
     )
 #else
     return executeDragGesture(
@@ -2321,15 +2315,13 @@ extension RunnerTests {
       x2: x2,
       y2: y2,
       durationMs: durationMs,
-      synthesized: false,
-      message: message,
-      synthesizedPolicyKind: .scroll
+      message: message
     )
 #endif
   }
 
-  /// Shared drag execution for explicit drag commands. The iOS synthesized lane keeps its
-  /// fallback policy explicit; viewport scrolling owns a separate single drag specification.
+  /// Shared coordinate drag execution. Callers that pass `synthesized` take the iOS synthesized
+  /// lane with that profile and fallback policy; the rest perform an XCTest coordinate drag.
   private func executeDragGesture(
     activeApp: XCUIApplication,
     x: Double,
@@ -2337,11 +2329,9 @@ extension RunnerTests {
     x2: Double,
     y2: Double,
     durationMs: Double?,
-    synthesized: Bool,
     message: String,
     synthesizedContext: SynthesizedCoordinateContext? = nil,
-    synthesizedPolicyKind: SynthesizedGesturePolicyKind,
-    synthesizedProfile: SynthesizedDragProfile = .continuous
+    synthesized: (profile: SynthesizedDragProfile, policyKind: SynthesizedGesturePolicyKind)? = nil
   ) -> Response {
     let durationMs = durationMs ?? runnerDefaultDragDurationMs
     let commandName = dragCommandName(message: message)
@@ -2351,7 +2341,7 @@ extension RunnerTests {
         error: ErrorPayload(code: "INVALID_ARGS", message: "\(commandName) requires finite coordinates")
       )
     }
-    if synthesized, let synthesizedResponse = executeSynthesizedDragGesture(
+    if let synthesized, let synthesizedResponse = executeSynthesizedDragGesture(
       activeApp: activeApp,
       x: x,
       y: y,
@@ -2360,8 +2350,8 @@ extension RunnerTests {
       durationMs: durationMs,
       message: message,
       context: synthesizedContext,
-      policyKind: synthesizedPolicyKind,
-      profile: synthesizedProfile
+      policyKind: synthesized.policyKind,
+      profile: synthesized.profile
     ) {
       return synthesizedResponse
     }
@@ -2373,33 +2363,9 @@ extension RunnerTests {
       x2: dragPoints.x2,
       y2: dragPoints.y2
     )
-    var fallback: GestureFallback?
-    if synthesized {
-      let durationMs = min(max(durationMs, 16), 10000)
-      let context = synthesizedCoordinateContext(
-        app: activeApp,
-        policy: synthesizedGesturePolicy(synthesizedPolicyKind)
-      )
-      let (timing, outcome) = performGesture(activeApp, idleTimeout: false) {
-        synthesizedDragAt(
-          app: activeApp,
-          x: dragPoints.x,
-          y: dragPoints.y,
-          x2: dragPoints.x2,
-          y2: dragPoints.y2,
-          durationMs: durationMs,
-          profile: synthesizedProfile,
-          context: context
-        )
-      }
-      if case .performed = outcome {
-        return gestureResponse(message: message, timing: timing, frame: .drag(dragFrame))
-      }
-      fallback = gestureFallback(strategy: "xctest-coordinate-drag", from: outcome)
-    }
-    let holdDuration = synthesized
-      ? synthesizedSwipeFallbackHoldDuration(durationMs: durationMs)
-      : coordinateDragHoldDuration()
+    let holdDuration = synthesized == nil
+      ? coordinateDragHoldDuration()
+      : synthesizedSwipeFallbackHoldDuration(durationMs: durationMs)
     let (timing, outcome) = performGesture(activeApp) {
       dragAt(
         app: activeApp,
@@ -2413,12 +2379,7 @@ extension RunnerTests {
     if let response = unsupportedResponse(for: outcome) {
       return response
     }
-    return gestureResponse(
-      message: message,
-      timing: timing,
-      frame: .drag(dragFrame),
-      fallback: fallback
-    )
+    return gestureResponse(message: message, timing: timing, frame: .drag(dragFrame))
   }
 
   private func executeSynthesizedDragGesture(
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift
index ba896c9164..8f0a101429 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift
@@ -18,7 +18,6 @@ extension RunnerTests {
   }
 
   enum SynthesizedDragProfile: Equatable {
-    case continuous
     case controlledScroll
     case fastSwipe
   }
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+ScrollGesture.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+ScrollGesture.swift
index 6b3423777c..f6ebb6866b 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+ScrollGesture.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+ScrollGesture.swift
@@ -256,11 +256,6 @@ extension RunnerTests {
     XCTAssertLessThan(finalSampleTravel, 0.1)
   }
 
-  func testContinuousDragRetainsSixteenMillisecondSamplingAtLongDurations() {
-    XCTAssertEqual(RunnerContinuousDragFrameCount(1_000), 62)
-    XCTAssertEqual(RunnerContinuousDragFrameCount(10_000), 625)
-  }
-
   func testRunnerScrollGesturePlanRejectsUnknownDirection() {
     XCTAssertNil(RunnerScrollDirection(rawValue: "sideways"))
   }
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SynthesizedInteraction.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SynthesizedInteraction.swift
index b1e8db0915..1d307ddd91 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SynthesizedInteraction.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SynthesizedInteraction.swift
@@ -9,7 +9,7 @@ extension RunnerTests {
     x2: Double,
     y2: Double,
     durationMs: Double,
-    profile: SynthesizedDragProfile = .continuous,
+    profile: SynthesizedDragProfile,
     context: SynthesizedCoordinateContext? = nil
   ) -> RunnerInteractionOutcome {
 #if os(iOS)
@@ -48,16 +48,6 @@ extension RunnerTests {
       orientation: orientation
     )
     let message = switch profile {
-    case .continuous:
-      RunnerSynthesizedGesture.synthesizeContinuousDrag(
-        withApplication: app,
-        resolvedWindow: context.resolvedWindow,
-        x: Double(start.x),
-        y: Double(start.y),
-        x2: Double(end.x),
-        y2: Double(end.y),
-        durationMs: durationMs
-      )
     case .controlledScroll:
       RunnerSynthesizedGesture.synthesizeControlledScroll(
         withApplication: app,
diff --git a/docs/adr/0011-interaction-guarantee-contract.md b/docs/adr/0011-interaction-guarantee-contract.md
index ada94c5ff6..51665d3613 100644
--- a/docs/adr/0011-interaction-guarantee-contract.md
+++ b/docs/adr/0011-interaction-guarantee-contract.md
@@ -305,9 +305,9 @@ truth because the current table has only three behaviors:
   fallback;
 - default iOS scroll probes keyboards only after AX is known healthy and must
   not fall back to `XCUICoordinate`;
-- explicit synthesized drag, including synthesized sequence tap/drag steps, may
-  still use the coordinate fallback before AX health is known, but stops using
-  it once a snapshot stamps AX unavailable.
+- synthesized one-contact `gesture` plans and synthesized sequence tap steps may
+  still use the coordinate fallback before AX health is known, but stop using it
+  once a snapshot stamps AX unavailable.
 
 The non-obvious parts are covered by gated XCTest policy tests instead of a
 cross-language mirror. A future sibling registry should only be introduced once
diff --git a/docs/adr/0013-unified-gesture-plans.md b/docs/adr/0013-unified-gesture-plans.md
index 7b93bc34c3..7d9f0a5f39 100644
--- a/docs/adr/0013-unified-gesture-plans.md
+++ b/docs/adr/0013-unified-gesture-plans.md
@@ -113,19 +113,20 @@ Platform adapters consume the canonical plan:
   The three schedules shape that velocity differently. `endpoint-hold` moves quickly for 100 ms and
   becomes stationary before lift. `timed-pan` and target-authored drag submit the authored samples
   unchanged, preserving piecewise-linear movement plus explicit source and destination holds. The
-  runner's coordinate `drag` and fused `scroll` compatibility path instead expands the movement to
-  roughly 16 ms samples using smoothstep `s(t) = 3t² - 2t³`. A linear segment has constant movement
-  velocity through its endpoint unless a destination hold follows it; smoothstep has zero slope at
-  both endpoints and a peak velocity 1.5 times its average. Identical endpoints and total durations
-  can consequently produce different recognizer and deceleration outcomes. Neither a destination
-  hold nor an analytically zero endpoint slope proves a controlled release by itself: XCTest event
-  sampling and app recognizer thresholds can still leave observable post-lift motion, so live
-  evidence must measure the resulting content offset after pointer-up.
-
-  Live iOS characterization in [issue #1586](https://github.com/callstack/agent-device/issues/1586)
-  confirmed that distinction: the schedules crossed the same fling-recognizer thresholds in the
-  tested range but produced materially different post-release ScrollView positions and
-  long-duration recognition behavior. The distinction is intentional policy at the Apple adapter
+  runner's fused `scroll` reuses `endpoint-hold` for inertial release; controlled release instead
+  expands the movement to evenly spaced samples, one per roughly 16 ms capped at 30, using cubic
+  ease-out `s(t) = 1 - (1 - t)³`. A linear segment has constant movement velocity through its
+  endpoint unless a destination hold follows it; cubic ease-out decelerates from the first movement
+  and has zero slope at lift, with a starting velocity three times its average. Identical endpoints
+  and total durations can consequently produce different recognizer and deceleration outcomes.
+  Neither a destination hold nor an analytically zero endpoint slope proves a controlled release by
+  itself: XCTest event sampling and app recognizer thresholds can still leave observable post-lift
+  motion, so live evidence must measure the resulting content offset after pointer-up.
+
+  Live iOS characterization of an eased sampled schedule against the linear ones in
+  [issue #1586](https://github.com/callstack/agent-device/issues/1586) confirmed that distinction:
+  the schedules crossed the same fling-recognizer thresholds in the tested range but produced
+  materially different post-release ScrollView positions and long-duration recognition behavior. The distinction is intentional policy at the Apple adapter
   boundary, not a second interpretation of a `GesturePlan`; changes require live evidence for both
   recognizer activation and post-release content movement.
 - WebDriver lowers a supported plan to synchronized W3C pointer action sources. A one-contact

From 7939464ddcb45f1603da104c6ff1041c096b8154 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Wed, 23 Sep 2026 20:13:51 +0200
Subject: [PATCH 064/132] chore(ios-runner): remove unset env knobs, the dead
 back wire command, and unreachable paths (#2828)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* chore(ios-runner): remove the runner env knobs nothing sets

AGENT_DEVICE_RUNNER_DISABLE_READONLY_RETRY, AGENT_DEVICE_RUNNER_DISABLE_SAFE_MODAL_PROBE and
AGENT_DEVICE_RUNNER_NOOP_STARTUP were only reachable through the process.env pass-through; no
repo code, CI job or doc sets them. The safe modal probe is now unconditional, and RunnerEnv loses
its only-caller isTruthy helper.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* chore(ios-runner): delete the dead back wire command and unreachable dispatch paths

- `back`: the daemon resolves only `backInApp`/`backSystem`, so the RunnerCommand union member,
  its trait row, the Swift case and its handler go.
- Selector-keyed `type`: runner adoption checks the artifact fingerprint, so no older daemon can
  send it; the element-focus entry point it alone used goes with it.
- Main-thread dispatch: the transport always executes on `commandExecutionQueue`, so the
  `Thread.isMainThread` branch in `executeDispatched`, the prepared-path `.snapshot` case, and the
  main-thread shortcuts that only those reached are removed. The test-only `execute(command:)`
  now dispatches like the transport, so tests exercise the production path.
- Custom-action coverage: the bridge in the same target always writes all four keys, so the
  older-bridge defaults for `truncated`/`blocked` go and a partial dictionary is malformed.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* chore(platform-apple): require simctl and devicectl on the Apple tool provider

Every resolved provider is normalized through createLocalAppleToolProvider, which always fills
both subcommand providers, so runXcrun's `?? runCommand('xcrun', …)` fallback was unreachable.
The fields are now required and runXcrun calls them directly.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* refactor(ios-runner): route test commands through the transport's own dispatch

The transport's inline status/uptime answer and its journal-accept-then-enqueue step are now named
functions, and the test-only execute(command:) calls them rather than re-stating them, so unit
tests take the same dispatch path as a daemon request. The wait uses a standalone expectation so a
command that outlives it cannot fulfill into an ended wait context.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .github/workflows/xctest-nightly.yml          |   6 +-
 .../RunnerTests+AXSnapshotFallback.swift      |  29 +++--
 .../RunnerTests+CommandExecution.swift        | 111 ++++++------------
 .../RunnerTests+CommandJournal.swift          |   2 +-
 .../RunnerTests+Environment.swift             |  12 --
 .../RunnerTests+Lifecycle.swift               |   5 +-
 .../RunnerTests+Models.swift                  |   3 +-
 .../RunnerTests+SystemModal.swift             |  12 +-
 .../RunnerTests+TextEntryFocus.swift          |  39 +-----
 .../RunnerTests+Transport.swift               |  43 +++++--
 .../RunnerTests.swift                         |   5 -
 .../RunnerTests+AlertDispatchTests.swift      |  47 ++------
 .../platform-apple/src/core/tool-provider.ts  |  14 +--
 packages/platform-apple/src/index.test.ts     |   4 +-
 .../runner/__tests__/runner-client.test.ts    |   1 -
 .../__tests__/runner-command-traits.test.ts   |   1 -
 .../src/runner/runner-command-traits.ts       |   1 -
 .../src/runner/runner-contract.ts             |   1 -
 src/platform-runtime-apple-tool-host.test.ts  |   5 +
 19 files changed, 120 insertions(+), 221 deletions(-)

diff --git a/.github/workflows/xctest-nightly.yml b/.github/workflows/xctest-nightly.yml
index 91ba7a5648..39ae0d1783 100644
--- a/.github/workflows/xctest-nightly.yml
+++ b/.github/workflows/xctest-nightly.yml
@@ -126,10 +126,8 @@ jobs:
       # (packages/platform-apple/src/runner/runner-session.ts always passes it as the sole
       # `-only-testing:`). It compiles unconditionally — the `#if AGENT_DEVICE_RUNNER_UNIT_TESTS`
       # block ends well above it — so an unfiltered run reaches it in alphabetical order and
-      # hangs the job until `timeout-minutes`. Its one escape hatch,
-      # AGENT_DEVICE_RUNNER_NOOP_STARTUP, is an environment variable, and the comment above
-      # the flag records that env plumbing into a simulator test process is not dependable;
-      # `-skip-testing:` is the lever that works from here.
+      # hangs the job until `timeout-minutes`. The method has no in-process escape hatch, so
+      # `-skip-testing:` is the lever that keeps it out of this run.
       #
       # A typo in that identifier silently re-arms the hang, so
       # `pnpm check:xctest-selection` validates `-skip-testing:` exactly like `-only-testing:`.
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+AXSnapshotFallback.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+AXSnapshotFallback.swift
index 9d41034d68..354ffba76c 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+AXSnapshotFallback.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+AXSnapshotFallback.swift
@@ -55,14 +55,10 @@ extension RunnerTests {
   static func privateAXCustomActionCoverage(_ raw: Any?) -> SnapshotCustomActionCoverage? {
     guard let coverage = raw as? [String: Any],
       let read = (coverage[RunnerAXSnapshotCustomActionsReadKey] as? NSNumber)?.intValue,
-      let candidates = (coverage[RunnerAXSnapshotCustomActionsCandidatesKey] as? NSNumber)?.intValue
+      let candidates = (coverage[RunnerAXSnapshotCustomActionsCandidatesKey] as? NSNumber)?.intValue,
+      let truncated = (coverage[RunnerAXSnapshotCustomActionsTruncatedKey] as? NSNumber)?.intValue,
+      let blocked = (coverage[RunnerAXSnapshotCustomActionsBlockedKey] as? NSNumber)?.boolValue
     else { return nil }
-    // read/candidates are the ratio and must both be present; the truncation
-    // count is additive, so an older bridge that omits it reads as zero rather
-    // than voiding the whole coverage.
-    let truncated =
-      (coverage[RunnerAXSnapshotCustomActionsTruncatedKey] as? NSNumber)?.intValue ?? 0
-    let blocked = (coverage[RunnerAXSnapshotCustomActionsBlockedKey] as? NSNumber)?.boolValue ?? false
     return SnapshotCustomActionCoverage(
       read: read, candidates: candidates, truncated: truncated, blocked: blocked)
   }
@@ -513,19 +509,28 @@ extension RunnerTests {
   /// The disclosure only exists if the counts survive the bridge boundary, and
   /// "did not ask" must stay distinguishable from "read none".
   func testCustomActionCoverageParsesOnlyCompletePairs() {
-    let coverage = Self.privateAXCustomActionCoverage([
+    let complete: [String: Any] = [
       RunnerAXSnapshotCustomActionsReadKey: 12,
       RunnerAXSnapshotCustomActionsCandidatesKey: 19,
-    ])
+      RunnerAXSnapshotCustomActionsTruncatedKey: 2,
+      RunnerAXSnapshotCustomActionsBlockedKey: true,
+    ]
+    let coverage = Self.privateAXCustomActionCoverage(complete)
     XCTAssertEqual(coverage?.read, 12)
     XCTAssertEqual(coverage?.candidates, 19)
+    XCTAssertEqual(coverage?.truncated, 2)
+    XCTAssertEqual(coverage?.blocked, true)
 
     // Absent key = the capture never asked; it must not read as (0, 0), which
     // would warn "0 of 0" on every default capture.
     XCTAssertNil(Self.privateAXCustomActionCoverage(nil))
-    // A half-present pair cannot express a ratio, so it is dropped whole.
-    XCTAssertNil(
-      Self.privateAXCustomActionCoverage([RunnerAXSnapshotCustomActionsReadKey: 12]))
+    // The bridge in this target always writes all four keys, so a partial
+    // dictionary is malformed and is dropped whole.
+    for key in complete.keys {
+      var partial = complete
+      partial.removeValue(forKey: key)
+      XCTAssertNil(Self.privateAXCustomActionCoverage(partial), "missing \(key)")
+    }
   }
 
   /// The AX call cannot be cancelled once issued, so the read deadline frees
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
index b4e50a3ab5..1f8477482b 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
@@ -824,7 +824,7 @@ extension RunnerTests {
   }
 #endif
 
-  func testExecuteDispatchedReturnsBusyBeforeMainThreadFastPath() throws {
+  func testDispatchReturnsBusyBeforeQueueingMainThreadWork() throws {
     let command = try runnerCommandFixture(#"{"command":"snapshot","commandId":"snapshot-busy"}"#)
     abandonedMainThreadWorkCount = 1
     abandonedMainThreadWorkSince = Date(timeIntervalSinceNow: -2)
@@ -833,14 +833,14 @@ extension RunnerTests {
       abandonedMainThreadWorkSince = nil
     }
 
-    let response = try executeDispatched(command: command)
+    let response = try execute(command: command)
 
     XCTAssertFalse(response.ok)
     XCTAssertEqual(response.error?.code, "RUNNER_BUSY")
     XCTAssertTrue(response.error?.message.contains("previous command") == true)
   }
 
-  func testExecuteDispatchedReturnsWedgedBeforeMainThreadFastPath() throws {
+  func testDispatchReturnsWedgedBeforeQueueingMainThreadWork() throws {
     let command = try runnerCommandFixture(#"{"command":"snapshot","commandId":"snapshot-wedged"}"#)
     abandonedMainThreadWorkCount = 1
     abandonedMainThreadWorkSince = Date(timeIntervalSinceNow: -(mainThreadWedgeThreshold + 1))
@@ -849,7 +849,7 @@ extension RunnerTests {
       abandonedMainThreadWorkSince = nil
     }
 
-    let response = try executeDispatched(command: command)
+    let response = try execute(command: command)
 
     XCTAssertFalse(response.ok)
     XCTAssertEqual(response.error?.code, "RUNNER_WEDGED")
@@ -936,15 +936,32 @@ extension RunnerTests {
 #endif
 
 #if AGENT_DEVICE_RUNNER_UNIT_TESTS
+  /// Routes `command` through the transport's inline and queued paths. The calling test's main
+  /// thread serves the command's main-thread work while it waits.
   func execute(command: Command) throws -> Response {
-    if command.command == .status {
-      return executeStatus(command: command)
+    dispatchPrecondition(condition: .onQueue(.main))
+    if let response = inlineResponse(for: command) {
+      return response
     }
-    if command.command == .uptime {
-      return executeUptime()
+    final class ResultBox {
+      var result: Result<Response, Error>?
     }
-    commandJournal.accept(command: command)
-    return try executeAccepted(command: command)
+    let box = ResultBox()
+    let executed = XCTestExpectation(description: "\(command.command.rawValue) executed off main")
+    enqueueAccepted(command: command) { result in
+      box.result = result
+      executed.fulfill()
+    }
+    guard XCTWaiter.wait(for: [executed], timeout: mainThreadExecutionTimeout + 5) == .completed,
+      let result = box.result
+    else {
+      throw NSError(
+        domain: RunnerErrorDomain.general,
+        code: RunnerErrorCode.commandReturnedNoResponse,
+        userInfo: [NSLocalizedDescriptionKey: "command did not finish on the command queue"]
+      )
+    }
+    return try result.get()
   }
 #endif
 
@@ -1063,14 +1080,6 @@ extension RunnerTests {
     let alertDeadline = command.command == .alert
       ? Date().addingTimeInterval(Self.alertCommandTimeout(timeoutMs: command.timeoutMs))
       : nil
-    if Thread.isMainThread {
-      let routeToSpringboard = shouldRouteToSpringboardBlockingSystemModal(command)
-      return try executeOnMainSafely(
-        command: command,
-        alertDeadline: alertDeadline,
-        routeToSpringboard: routeToSpringboard
-      )
-    }
     // Resolve this before the command's outer main-thread block. If the bounded probe abandons
     // slow XCTest enumeration, return the established recoverable response instead of queueing
     // command preparation behind work that may outlive the 30-second command watchdog.
@@ -1300,7 +1309,7 @@ extension RunnerTests {
   private func executeSnapshotPrepared(
     command: Command,
     activeApp: XCUIApplication,
-    systemSurface: SystemSurfaceHost? = nil
+    systemSurface: SystemSurfaceHost?
   ) throws -> Response {
     let options = Self.presentationOptions(from: command)
     do {
@@ -1332,10 +1341,6 @@ extension RunnerTests {
   }
 
   private func setNeedsPostSnapshotInteractionDelay() {
-    if Thread.isMainThread {
-      needsPostSnapshotInteractionDelay = true
-      return
-    }
     guard !hasAbandonedMainThreadWork() else {
       NSLog("AGENT_DEVICE_RUNNER_POST_SNAPSHOT_DELAY_MARK_SKIPPED_XCTEST_OCCUPIED")
       return
@@ -1354,10 +1359,6 @@ extension RunnerTests {
   }
 
   private func invalidateCachedTargetAfterSnapshotFailure() {
-    if Thread.isMainThread {
-      invalidateCachedTarget(reason: "ax_snapshot_failure")
-      return
-    }
     // Abandoned work ahead of this hop cannot be cancelled: queue the drop behind it without
     // waiting, so the failed capture answers now and the next command still finds the target gone.
     guard !hasAbandonedMainThreadWork() else {
@@ -1633,7 +1634,8 @@ extension RunnerTests {
       clearRememberedTextEntryTap()
     }
     switch command.command {
-    case .status, .activate, .terminate, .targetReset, .shutdown, .recordStart, .recordStop, .uptime:
+    case .status, .activate, .terminate, .targetReset, .shutdown, .recordStart, .recordStop, .uptime,
+      .snapshot:
       return Response(
         ok: false,
         error: ErrorPayload(
@@ -2049,8 +2051,6 @@ extension RunnerTests {
         return Response(ok: false, error: ErrorPayload(message: "readText did not resolve text"))
       }
       return Response(ok: true, data: DataPayload(text: text))
-    case .snapshot:
-      return try executeSnapshotPrepared(command: command, activeApp: activeApp)
     case .screenshot:
 #if os(macOS)
       // macOS keeps the app-targeted capture behavior for window-level screenshots.
@@ -2116,11 +2116,10 @@ extension RunnerTests {
         inlineScreenshot: command.inlineScreenshot == true
       )
 #endif
-    case .back, .backInApp:
+    case .backInApp:
       switch tapInAppBackControl(app: activeApp) {
       case .performed:
-        let message = command.command == .back ? "back" : "backInApp"
-        return Response(ok: true, data: DataPayload(message: message))
+        return Response(ok: true, data: DataPayload(message: "backInApp"))
       case .unavailable:
         return Response(
           ok: false,
@@ -2612,15 +2611,6 @@ extension RunnerTests {
     }
     #endif
     let probeDeadline = Date().addingTimeInterval(systemModalProbeBudget)
-    // `runMainThreadWork` executes inline for a main-thread caller, so that path cannot use its
-    // timeout machinery. Direct main-thread dispatch keeps the prior synchronous modal check;
-    // normal off-main command dispatch uses the bounded probe and post-probe busy recovery.
-    if Thread.isMainThread {
-      return firstBlockingSystemModal(
-        in: springboard,
-        deadline: probeDeadline
-      ) != nil
-    }
     return boundedBlockingSystemAlertSnapshot(
       deadline: probeDeadline
     ) != nil
@@ -2668,15 +2658,12 @@ extension RunnerTests {
     let textEntryMode = resolveTextEntryMode(command)
     let target: TextEntryTarget
     var resolvedCoordinateContext: SynthesizedCoordinateContext?
-    var maestroNonHittableCoordinateFallbackUsed: Bool?
-    if command.allowNonHittableCoordinateFallback == true,
-      command.x != nil,
-      command.y != nil
-    {
-      // The shared runtime has already resolved this node as non-hittable and
-      // deliberately selected Maestro's coordinate compatibility route.
-      maestroNonHittableCoordinateFallbackUsed = true
-    }
+    // The shared runtime has already resolved this node as non-hittable and
+    // deliberately selected Maestro's coordinate compatibility route.
+    let maestroNonHittableCoordinateFallbackUsed: Bool? =
+      command.allowNonHittableCoordinateFallback == true && command.x != nil && command.y != nil
+      ? true
+      : nil
     let focusStartedAt = Date()
 #if os(iOS)
     let xCTestChannelPenalized = isSnapshotXCTestChannelPenalized(bundleId: currentBundleId)
@@ -2721,28 +2708,6 @@ extension RunnerTests {
 #endif
     if let resolvedCoordinateTarget {
       target = resolvedCoordinateTarget
-    } else if let selectorKey = command.selectorKey, let selectorValue = command.selectorValue {
-      // Released daemons may still send selector-keyed type commands even though current
-      // daemons resolve fill selectors through the runtime tree before reaching the runner.
-      let match = findElement(
-        app: activeApp,
-        selectorKey: selectorKey,
-        selectorValue: selectorValue,
-        allowNonHittableFallback: command.allowNonHittableCoordinateFallback == true
-      )
-      if match.isAmbiguous {
-        return Response(ok: false, error: ErrorPayload(code: "AMBIGUOUS_MATCH", message: "selector matched multiple elements"))
-      }
-      guard let element = match.element else {
-        return Response(ok: false, error: ErrorPayload(code: "NO_MATCH", message: "selector did not match an element"))
-      }
-      guard isTextEntryElement(element) else {
-        return Response(ok: false, error: ErrorPayload(code: "INVALID_TARGET", message: "selector did not match a text input"))
-      }
-      if command.allowNonHittableCoordinateFallback == true {
-        maestroNonHittableCoordinateFallbackUsed = match.usedNonHittableFallback
-      }
-      target = focusTextInputForTextEntry(app: activeApp, element: element)
     } else {
       target = focusTextInputForTextEntry(app: activeApp, x: command.x, y: command.y)
     }
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandJournal.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandJournal.swift
index f15acf8f9b..9ed3b9f51f 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandJournal.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandJournal.swift
@@ -136,7 +136,7 @@ final class RunnerCommandJournal {
     case .snapshot, .screenshot:
       return false
     case .tap, .mouseClick, .longPress, .drag,
-         .remotePress, .type, .swipe, .scroll, .desktopScroll, .findText, .querySelector, .readText, .back,
+         .remotePress, .type, .swipe, .scroll, .desktopScroll, .findText, .querySelector, .readText,
          .backInApp, .backSystem, .home, .rotate, .appSwitcher, .actionButton, .keyboardDismiss, .keyboardReturn,
          .alert, .sequence, .gesture, .gestureViewport, .recordStart, .recordStop,
          .status, .uptime, .activate, .terminate, .targetReset, .shutdown:
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Environment.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Environment.swift
index 610c3384c6..0ae4f1f1c9 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Environment.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Environment.swift
@@ -15,16 +15,4 @@ enum RunnerEnv {
     }
     return 0
   }
-
-  static func isTruthy(_ name: String) -> Bool {
-    guard let raw = ProcessInfo.processInfo.environment[name] else {
-      return false
-    }
-    switch raw.trimmingCharacters(in: .whitespacesAndNewlines).lowercased() {
-    case "1", "true", "yes", "on":
-      return true
-    default:
-      return false
-    }
-  }
 }
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Lifecycle.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Lifecycle.swift
index 991b554053..57bde60d26 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Lifecycle.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Lifecycle.swift
@@ -426,10 +426,7 @@ extension RunnerTests {
   }
 
   func shouldRetryCommand(_ command: Command) -> Bool {
-    if RunnerEnv.isTruthy("AGENT_DEVICE_RUNNER_DISABLE_READONLY_RETRY") {
-      return false
-    }
-    return isReadOnlyCommand(command)
+    isReadOnlyCommand(command)
   }
 
   func shouldRetryException(_ command: Command, message: String) -> Bool {
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift
index 81068ab004..4ddd306b16 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift
@@ -17,7 +17,6 @@ enum CommandType: String, Codable {
   case readText
   case snapshot
   case screenshot
-  case back
   case backInApp
   case backSystem
   case home
@@ -78,7 +77,7 @@ extension CommandType {
     // classification as .drag. .desktopScroll is the macOS frame-resolve + wheel event sibling.
     // .sequence is the fused multi-step gesture batch.
     case .tap, .longPress, .drag, .remotePress, .type, .swipe, .scroll, .desktopScroll,
-         .back, .backInApp, .backSystem, .rotate, .appSwitcher,
+         .backInApp, .backSystem, .rotate, .appSwitcher,
          .keyboardDismiss, .keyboardReturn, .sequence, .gesture:
       return CommandTraits(isInteraction: true, readOnly: .never, isLifecycle: false)
 
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SystemModal.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SystemModal.swift
index 5618d78358..c05d3fb2f9 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SystemModal.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SystemModal.swift
@@ -69,15 +69,7 @@ extension RunnerTests {
     in springboard: XCUIApplication,
     deadline: Date = .distantFuture
   ) -> XCUIElement? {
-    let disableSafeProbe = RunnerEnv.isTruthy("AGENT_DEVICE_RUNNER_DISABLE_SAFE_MODAL_PROBE")
-    let queryElements: (() -> [XCUIElement]) -> [XCUIElement] = { fetch in
-      if disableSafeProbe {
-        return fetch()
-      }
-      return self.safeElementsQuery(fetch)
-    }
-
-    let alerts = queryElements {
+    let alerts = safeElementsQuery {
       springboard.alerts.allElementsBoundByIndex
     }
     for alert in alerts {
@@ -92,7 +84,7 @@ extension RunnerTests {
       return nil
     }
 
-    let sheets = queryElements {
+    let sheets = safeElementsQuery {
       springboard.sheets.allElementsBoundByIndex
     }
     for sheet in sheets {
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+TextEntryFocus.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+TextEntryFocus.swift
index da780c8270..6d49503938 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+TextEntryFocus.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+TextEntryFocus.swift
@@ -1,8 +1,8 @@
 import XCTest
 
 // Text-entry target acquisition: choosing the element a `type`/`fill` will address and getting
-// focus onto it — the one-shot tap witness, the post-tap stabilization, and the two
-// `focusTextInputForTextEntry` entry points the command layer calls. Whether that target is ready
+// focus onto it — the one-shot tap witness, the post-tap stabilization, and the
+// `focusTextInputForTextEntry` entry point the command layer calls. Whether that target is ready
 // is RunnerTests+TextEntryReadiness.swift's question, and this file asks it rather than answering
 // it.
 extension RunnerTests {
@@ -152,41 +152,6 @@ extension RunnerTests {
     )
   }
 
-  func focusTextInputForTextEntry(app: XCUIApplication, element: XCUIElement) -> TextEntryTarget {
-    let point = textEntryRefreshPoint(for: element)
-    let keyboardVisibleBeforeTap = isKeyboardVisible(app: app)
-    if let point {
-      _ = tapAt(app: app, x: point.x, y: point.y)
-    }
-    // See the coordinate-target path above: direct element typing keeps this scoped to the
-    // tapped target, while the first-character warmup and final verify still catch dropped input.
-    if keyboardVisibleBeforeTap {
-      return TextEntryTarget(
-        element: element,
-        refreshPoint: textEntryRefreshPoint(for: element) ?? point,
-        prefersFocusedElement: false
-      )
-    }
-    let stabilized = stabilizeTextInputBeforeTyping(
-      app: app,
-      target: element,
-      keyboardVisibleBeforeTap: keyboardVisibleBeforeTap
-    )
-    let readyTarget = TextEntryTarget(
-      element: stabilized.element ?? element,
-      refreshPoint: point,
-      prefersFocusedElement: false
-    )
-    let resolved = stabilized.focusConfirmed
-      ? (stabilized.element ?? element)
-      : (waitForTextEntryReadiness(app: app, target: readyTarget) ?? stabilized.element ?? element)
-    return TextEntryTarget(
-      element: resolved,
-      refreshPoint: textEntryRefreshPoint(for: resolved) ?? point,
-      prefersFocusedElement: false
-    )
-  }
-
   private func textEntryRefreshPoint(for element: XCUIElement?) -> CGPoint? {
     guard let element else {
       return nil
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Transport.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Transport.swift
index 5545ab6b9c..e694f41baa 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Transport.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Transport.swift
@@ -108,12 +108,8 @@ extension RunnerTests {
 
     do {
       let command = try JSONDecoder().decode(Command.self, from: body)
-      if command.command == .status {
-        completion((jsonResponse(status: 200, response: executeStatus(command: command)), false))
-        return
-      }
-      if command.command == .uptime {
-        completion((jsonResponse(status: 200, response: executeUptime()), false))
+      if let response = inlineResponse(for: command) {
+        completion((jsonResponse(status: 200, response: response), false))
         return
       }
       // Re-sends of a still-executing commandId (the daemon's transport retry loop) attach to
@@ -127,10 +123,9 @@ extension RunnerTests {
         command.command.rawValue,
         command.commandId ?? ""
       )
-      commandJournal.accept(command: command)
-      commandExecutionQueue.async {
-        do {
-          let response = try self.executeAccepted(command: command)
+      enqueueAccepted(command: command) { result in
+        switch result {
+        case .success(let response):
           NSLog(
             "AGENT_DEVICE_RUNNER_COMMAND_COMPLETED command=%@ commandId=%@ ok=%d",
             command.command.rawValue,
@@ -142,7 +137,7 @@ extension RunnerTests {
             result: (self.jsonResponse(status: 200, response: response), command.command == .shutdown),
             completion: completion
           )
-        } catch {
+        case .failure(let error):
           NSLog(
             "AGENT_DEVICE_RUNNER_COMMAND_FAILED command=%@ commandId=%@ error=%@",
             command.command.rawValue,
@@ -174,6 +169,32 @@ extension RunnerTests {
     }
   }
 
+  // MARK: - Command Routing
+
+  /// Status and uptime read runner state without entering the journal or the command queue.
+  func inlineResponse(for command: Command) -> Response? {
+    switch command.command {
+    case .status:
+      return executeStatus(command: command)
+    case .uptime:
+      return executeUptime()
+    default:
+      return nil
+    }
+  }
+
+  /// Journal-accepts `command` and executes it on `commandExecutionQueue`; `completion` runs on that
+  /// queue.
+  func enqueueAccepted(
+    command: Command,
+    completion: @escaping (Result<Response, Error>) -> Void
+  ) {
+    commandJournal.accept(command: command)
+    commandExecutionQueue.async {
+      completion(Result { try self.executeAccepted(command: command) })
+    }
+  }
+
   // MARK: - In-Flight Command Coalescing
 
   /// Returns true when this send duplicated a still-executing commandId and was attached as a
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift
index afee02d03b..0785df2b96 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift
@@ -270,11 +270,6 @@ final class RunnerTests: XCTestCase {
 
   @MainActor
   func testCommand() throws {
-    if RunnerEnv.isTruthy("AGENT_DEVICE_RUNNER_NOOP_STARTUP") {
-      NSLog("AGENT_DEVICE_RUNNER_NOOP_STARTUP=1")
-      return
-    }
-
     doneExpectation = expectation(description: "agent-device command handled")
     NSLog("AGENT_DEVICE_RUNNER_HEADLESS_STARTUP=1")
     let desiredPort = RunnerEnv.resolvePort()
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+AlertDispatchTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+AlertDispatchTests.swift
index 7cbca88ed1..0fe213c883 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+AlertDispatchTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+AlertDispatchTests.swift
@@ -6,11 +6,8 @@ extension RunnerTests {
     final class ResultBox {
       var routingProbeCount = 0
       var resolutionCount = 0
-      var response: Response?
-      var error: Error?
     }
     let box = ResultBox()
-    let finished = expectation(description: "alert dispatch finished")
     currentApp = springboard
     currentBundleId = Self.springboardBundleId
     systemModalProbeOverrideForTesting = { _ in
@@ -30,31 +27,19 @@ extension RunnerTests {
     let command = try runnerCommandFixture(
       #"{"command":"alert","commandId":"alert-routing-once","appBundleId":"com.apple.springboard","action":"get","timeoutMs":1000}"#
     )
-    DispatchQueue(label: "agent-device.runner.tests.alert-routing").async {
-      do {
-        box.response = try self.execute(command: command)
-      } catch {
-        box.error = error
-      }
-      finished.fulfill()
-    }
-    wait(for: [finished], timeout: 2)
-    XCTAssertNil(box.error)
-    XCTAssertEqual(box.response?.error?.code, "ALERT_NOT_FOUND")
+    let response = try execute(command: command)
+    XCTAssertEqual(response.error?.code, "ALERT_NOT_FOUND")
     XCTAssertEqual(box.resolutionCount, 1)
     XCTAssertEqual(box.routingProbeCount, 0)
   }
 
   func testAlertResolutionCannotBypassRequestedDeadline() throws {
     final class ResultBox {
-      var error: Error?
       var observedDeadline: Date?
-      var commandStartedAt: Date?
     }
     let box = ResultBox()
     let releaseResolution = DispatchSemaphore(value: 0)
     let resolutionExited = expectation(description: "bounded alert resolution exited")
-    let commandFinished = expectation(description: "alert command respected its deadline")
     let command = try runnerCommandFixture(
       #"{"command":"alert","commandId":"alert-deadline","appBundleId":"com.apple.springboard","action":"get","timeoutMs":500}"#
     )
@@ -73,26 +58,16 @@ extension RunnerTests {
       currentBundleId = nil
     }
 
-    DispatchQueue(label: "agent-device.runner.tests.alert-deadline").async {
-      box.commandStartedAt = Date()
-      do {
-        _ = try self.execute(command: command)
-      } catch {
-        box.error = error
-      }
-      commandFinished.fulfill()
-    }
-
-    wait(for: [commandFinished], timeout: 1)
-    let error = box.error as NSError?
-    XCTAssertEqual(error?.domain, RunnerErrorDomain.general)
-    XCTAssertEqual(error?.code, RunnerErrorCode.mainThreadExecutionTimedOut)
-    XCTAssertNotNil(box.observedDeadline)
-    if let observedDeadline = box.observedDeadline,
-      let commandStartedAt = box.commandStartedAt
-    {
-      XCTAssertEqual(observedDeadline.timeIntervalSince(commandStartedAt), 0.5, accuracy: 0.05)
+    let commandStartedAt = Date()
+    // The resolution outlives the 500 ms request, so only the deadline-bounded dispatch can throw
+    // the main-thread timeout; a bypassed deadline answers ALERT_NOT_FOUND once it returns.
+    XCTAssertThrowsError(try execute(command: command)) { error in
+      let error = error as NSError
+      XCTAssertEqual(error.domain, RunnerErrorDomain.general)
+      XCTAssertEqual(error.code, RunnerErrorCode.mainThreadExecutionTimedOut)
     }
+    let observedDeadline = try XCTUnwrap(box.observedDeadline)
+    XCTAssertEqual(observedDeadline.timeIntervalSince(commandStartedAt), 0.5, accuracy: 0.05)
 
     releaseResolution.signal()
     wait(for: [resolutionExited], timeout: 1)
diff --git a/packages/platform-apple/src/core/tool-provider.ts b/packages/platform-apple/src/core/tool-provider.ts
index 0f6f0bd7cc..02d3190073 100644
--- a/packages/platform-apple/src/core/tool-provider.ts
+++ b/packages/platform-apple/src/core/tool-provider.ts
@@ -29,8 +29,8 @@ export type {
 
 export type AppleToolProvider = {
   runCommand: AppleToolCommandExecutor;
-  simctl?: AppleXcrunToolProvider;
-  devicectl?: AppleXcrunToolProvider;
+  simctl: AppleXcrunToolProvider;
+  devicectl: AppleXcrunToolProvider;
   macosHelper?: AppleMacOsHelperProvider;
   macosHost?: AppleMacOsHostProvider;
   plist?: ApplePlistProvider;
@@ -118,12 +118,10 @@ export async function runXcrun(args: string[], options?: ExecOptions): Promise<E
   const provider = resolveAppleToolProvider();
   const [tool, ...toolArgs] = args;
   if (tool === 'simctl') {
-    return await (provider.simctl?.run(toolArgs, options) ??
-      provider.runCommand('xcrun', args, options));
+    return await provider.simctl.run(toolArgs, options);
   }
   if (tool === 'devicectl') {
-    return await (provider.devicectl?.run(toolArgs, options) ??
-      provider.runCommand('xcrun', args, options));
+    return await provider.devicectl.run(toolArgs, options);
   }
   return await runAppleToolCommand('xcrun', args, options);
 }
@@ -139,8 +137,8 @@ function normalizeAppleToolProvider(provider: AppleToolProvider): AppleToolProvi
   return createLocalAppleToolProvider({
     ...provider,
     runCommand: coerceRunCommand(provider.runCommand),
-    ...(provider.simctl ? { simctl: { run: coerceRun(provider.simctl.run) } } : {}),
-    ...(provider.devicectl ? { devicectl: { run: coerceRun(provider.devicectl.run) } } : {}),
+    simctl: { run: coerceRun(provider.simctl.run) },
+    devicectl: { run: coerceRun(provider.devicectl.run) },
     ...(provider.macosHelper ? { macosHelper: { run: coerceRun(provider.macosHelper.run) } } : {}),
   });
 }
diff --git a/packages/platform-apple/src/index.test.ts b/packages/platform-apple/src/index.test.ts
index 1d30b39220..d4315d38af 100644
--- a/packages/platform-apple/src/index.test.ts
+++ b/packages/platform-apple/src/index.test.ts
@@ -18,8 +18,8 @@ test('lazy Apple tool provider preserves the local semantic operation shape', ()
 
   assert.equal(typeof provider.runCommand, 'function');
   assert.equal(typeof provider.whichCommand, 'function');
-  assert.equal(typeof provider.simctl?.run, 'function');
-  assert.equal(typeof provider.devicectl?.run, 'function');
+  assert.equal(typeof provider.simctl.run, 'function');
+  assert.equal(typeof provider.devicectl.run, 'function');
   assert.equal(typeof provider.plist?.readJson, 'function');
   assert.equal(typeof provider.macosHost?.openBundle, 'function');
   assert.equal(typeof provider.macosHost?.listApps, 'function');
diff --git a/packages/platform-apple/src/runner/__tests__/runner-client.test.ts b/packages/platform-apple/src/runner/__tests__/runner-client.test.ts
index 1e2252e5eb..b954d5e73c 100644
--- a/packages/platform-apple/src/runner/__tests__/runner-client.test.ts
+++ b/packages/platform-apple/src/runner/__tests__/runner-client.test.ts
@@ -121,7 +121,6 @@ const runnerProtocolCommandFixtures: Record<RunnerCommand['command'], RunnerComm
     raw: false,
   },
   screenshot: { command: 'screenshot', outPath: '/tmp/runner-screenshot.png', fullscreen: true },
-  back: { command: 'back' },
   backInApp: { command: 'backInApp' },
   backSystem: { command: 'backSystem' },
   home: { command: 'home' },
diff --git a/packages/platform-apple/src/runner/__tests__/runner-command-traits.test.ts b/packages/platform-apple/src/runner/__tests__/runner-command-traits.test.ts
index cf3bbd284e..3f5db74422 100644
--- a/packages/platform-apple/src/runner/__tests__/runner-command-traits.test.ts
+++ b/packages/platform-apple/src/runner/__tests__/runner-command-traits.test.ts
@@ -49,7 +49,6 @@ test('runner command trait table pins lifecycle-sensitive command groups', () =>
     default: [
       'actionButton',
       'appSwitcher',
-      'back',
       'backInApp',
       'backSystem',
       'home',
diff --git a/packages/platform-apple/src/runner/runner-command-traits.ts b/packages/platform-apple/src/runner/runner-command-traits.ts
index 5e3bcce382..75307908c5 100644
--- a/packages/platform-apple/src/runner/runner-command-traits.ts
+++ b/packages/platform-apple/src/runner/runner-command-traits.ts
@@ -66,7 +66,6 @@ export const RUNNER_COMMAND_TRAITS = {
   readText: READ_ONLY_TRAITS,
   snapshot: READ_ONLY_TRAITS,
   screenshot: READ_ONLY_TRAITS,
-  back: DEFAULT_TRAITS,
   backInApp: DEFAULT_TRAITS,
   backSystem: DEFAULT_TRAITS,
   home: DEFAULT_TRAITS,
diff --git a/packages/platform-apple/src/runner/runner-contract.ts b/packages/platform-apple/src/runner/runner-contract.ts
index 2dd42692b7..b7ecaafd14 100644
--- a/packages/platform-apple/src/runner/runner-contract.ts
+++ b/packages/platform-apple/src/runner/runner-contract.ts
@@ -48,7 +48,6 @@ export type RunnerCommand = {
     | 'readText'
     | 'snapshot'
     | 'screenshot'
-    | 'back'
     | 'backInApp'
     | 'backSystem'
     | 'home'
diff --git a/src/platform-runtime-apple-tool-host.test.ts b/src/platform-runtime-apple-tool-host.test.ts
index 55da2a86dd..0f59de4daa 100644
--- a/src/platform-runtime-apple-tool-host.test.ts
+++ b/src/platform-runtime-apple-tool-host.test.ts
@@ -14,6 +14,11 @@ test('Apple tool host uses a full scoped provider when local xcrun is unavailabl
       throw new Error('local command fallback is unavailable');
     },
     whichCommand,
+    simctl: {
+      run: async () => {
+        throw new Error('simctl is unscripted');
+      },
+    },
     devicectl: { run },
   };
   const host = createAppleToolHost();

From 4bce8fa42a6dfab938b3f7dcf1177b18b3f7a925 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Wed, 23 Sep 2026 20:13:51 +0200
Subject: [PATCH 065/132] refactor(ios-runner): key runner retry decisions on
 typed failures, not message text (#2831)

* refactor(ios-runner): key the runner's read-only retry on typed failures, not message text

The response retry now reads a runner-internal `retryableFailure` that the target-app-unavailable
responses carry from the place they are produced; it is excluded from encoding so the host sees the
same error JSON. The exception retry drops the main-thread-timeout branch (that text is only ever a
Swift NSError, never an ObjC exception reason) and the snapshot timeout branch (snapshot dispatches
through its own recovery loop and never reaches the exception catcher).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* test(ios-runner): pin the error payload wire shape beside its model

Moves the wire-shape pin to a Models test file and adds a field-drift check: every stored
ErrorPayload field except the runner-internal retryable failure must reach the encoded JSON.
The exception-retry test builds its commands through the shared fixture helper.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .../RunnerTests+CommandExecution.swift        | 11 +++----
 .../RunnerTests+Lifecycle.swift               | 16 ++--------
 .../RunnerTests+Models.swift                  | 22 +++++++++++++
 .../RunnerTests+Snapshot.swift                |  2 +-
 .../RunnerTests+LifecycleTests.swift          | 31 ++++++++++++++++++
 .../UnitTests/RunnerTests+ModelsTests.swift   | 32 +++++++++++++++++++
 6 files changed, 94 insertions(+), 20 deletions(-)
 create mode 100644 apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+ModelsTests.swift

diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
index 1f8477482b..6be914e7cc 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
@@ -1576,10 +1576,10 @@ extension RunnerTests {
         if let bundleId = requestedBundleId {
           activeApp = activateTarget(bundleId: bundleId, reason: "missing_after_wait")
           guard activeApp.waitForExistence(timeout: appExistenceTimeout) else {
-            return .response(Response(ok: false, error: ErrorPayload(message: "app '\(bundleId)' is not available")))
+            return .response(Response(ok: false, error: .targetAppUnavailable(bundleId: bundleId)))
           }
         } else {
-          return .response(Response(ok: false, error: ErrorPayload(message: "runner app is not available")))
+          return .response(Response(ok: false, error: .targetAppUnavailable(bundleId: nil)))
         }
       }
 
@@ -1595,10 +1595,9 @@ extension RunnerTests {
           requestedBundleId: requestedBundleId
         )
         if !skipInteractionExistenceWait && !activeApp.waitForExistence(timeout: 2) {
-          if let bundleId = requestedBundleId {
-            return .response(Response(ok: false, error: ErrorPayload(message: "app '\(bundleId)' is not available")))
-          }
-          return .response(Response(ok: false, error: ErrorPayload(message: "runner app is not available")))
+          return .response(
+            Response(ok: false, error: .targetAppUnavailable(bundleId: requestedBundleId))
+          )
         }
         applyInteractionStabilizationIfNeeded()
       }
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Lifecycle.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Lifecycle.swift
index 57bde60d26..57e4467cd3 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Lifecycle.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Lifecycle.swift
@@ -431,17 +431,8 @@ extension RunnerTests {
 
   func shouldRetryException(_ command: Command, message: String) -> Bool {
     guard shouldRetryCommand(command) else { return false }
-    let normalized = message.lowercased()
-    if normalized.contains("kaxerrorservernotfound") {
-      return true
-    }
-    if normalized.contains("main thread execution timed out") {
-      return true
-    }
-    if normalized.contains("timed out") && command.command == .snapshot {
-      return true
-    }
-    return false
+    // XCTest raises this AX error as an ObjC exception whose reason is the only handle on it.
+    return message.lowercased().contains("kaxerrorservernotfound")
   }
 
   // MARK: - Command Classification
@@ -460,8 +451,7 @@ extension RunnerTests {
 
   func shouldRetryResponse(_ response: Response) -> Bool {
     guard response.ok == false else { return false }
-    guard let message = response.error?.message.lowercased() else { return false }
-    return message.contains("is not available")
+    return response.error?.retryableFailure != nil
   }
 
   func isInteractionCommand(_ command: CommandType) -> Bool {
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift
index 4ddd306b16..2a4b84de27 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift
@@ -385,8 +385,30 @@ struct SnapshotQualityPayload: Codable {
   }
 }
 
+/// A runner failure the read-only retry may recover from by re-resolving the target.
+enum RetryableResponseFailure: Equatable {
+  case targetAppUnavailable
+}
+
 struct ErrorPayload: Codable {
   var code: String?
   let message: String
   var hint: String?
+  /// Runner-internal: read by `shouldRetryResponse` and never encoded, so the host's decoding of
+  /// the error is unchanged.
+  var retryableFailure: RetryableResponseFailure? = nil
+
+  private enum CodingKeys: String, CodingKey {
+    case code
+    case message
+    case hint
+  }
+
+  static func targetAppUnavailable(bundleId: String?) -> ErrorPayload {
+    let subject = bundleId.map { "app '\($0)'" } ?? "runner app"
+    return ErrorPayload(
+      message: "\(subject) is not available",
+      retryableFailure: .targetAppUnavailable
+    )
+  }
 }
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Snapshot.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Snapshot.swift
index 04e83a38f3..83686731cf 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Snapshot.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Snapshot.swift
@@ -764,7 +764,7 @@ extension RunnerTests {
       Command.self,
       from: Data(#"{"command":"snapshot","commandId":"recovery-guard"}"#.utf8)
     )
-    let recovered = Response(ok: false, error: ErrorPayload(message: "target is not available"))
+    let recovered = Response(ok: false, error: .targetAppUnavailable(bundleId: nil))
 
     setAbandonedMainThreadWork(1)
     defer { setAbandonedMainThreadWork(0) }
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+LifecycleTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+LifecycleTests.swift
index c9c14b436d..cba532f03b 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+LifecycleTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+LifecycleTests.swift
@@ -28,6 +28,37 @@ extension RunnerTests {
     }
   }
 
+  func testTargetAppUnavailableResponseIsRetried() {
+    for bundleId in ["com.example.app", nil] as [String?] {
+      let response = Response(ok: false, error: .targetAppUnavailable(bundleId: bundleId))
+      XCTAssertTrue(shouldRetryResponse(response), String(describing: bundleId))
+    }
+    let reworded = ErrorPayload(message: "target vanished", retryableFailure: .targetAppUnavailable)
+    XCTAssertTrue(shouldRetryResponse(Response(ok: false, error: reworded)))
+  }
+
+  func testUntypedUnavailableMessageIsNotRetried() {
+    for message in ["app 'com.example.app' is not available", "runner app is not available"] {
+      let response = Response(ok: false, error: ErrorPayload(message: message))
+      XCTAssertFalse(shouldRetryResponse(response), message)
+    }
+    let succeeded = Response(ok: true, error: .targetAppUnavailable(bundleId: nil))
+    XCTAssertFalse(shouldRetryResponse(succeeded))
+  }
+
+  func testExceptionRetryIsLimitedToTheAxServerNotFoundReadOnlyCase() throws {
+    let readText = try runnerCommandFixture(#"{"command":"readText"}"#)
+    let snapshot = try runnerCommandFixture(#"{"command":"snapshot"}"#)
+    let tap = try runnerCommandFixture(#"{"command":"tap"}"#)
+    let axServerNotFound = "NSException: Error kAXErrorServerNotFound"
+    XCTAssertTrue(shouldRetryException(readText, message: axServerNotFound))
+    XCTAssertFalse(shouldRetryException(tap, message: axServerNotFound))
+    XCTAssertFalse(
+      shouldRetryException(readText, message: "NSException: main thread execution timed out")
+    )
+    XCTAssertFalse(shouldRetryException(snapshot, message: "NSException: query timed out"))
+  }
+
   func testInlineScreenshotResponseKeepsDisplayFactsBesideTheImage() throws {
     let pngData = Data([0x89, 0x50, 0x4E, 0x47])
     let response = screenshotResponse(
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+ModelsTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+ModelsTests.swift
new file mode 100644
index 0000000000..d0079bf728
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+ModelsTests.swift
@@ -0,0 +1,32 @@
+import Foundation
+import XCTest
+
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS
+extension RunnerTests {
+  func testErrorPayloadEncodesEveryFieldButTheRunnerInternalRetryableFailure() throws {
+    let payload = ErrorPayload(
+      code: "CODE",
+      message: "message",
+      hint: "hint",
+      retryableFailure: .targetAppUnavailable
+    )
+    let encoded = try JSONEncoder().encode(payload)
+    let object = try XCTUnwrap(JSONSerialization.jsonObject(with: encoded) as? [String: Any])
+    let storedFields = Set(Mirror(reflecting: payload).children.compactMap(\.label))
+    XCTAssertEqual(Set(object.keys), storedFields.subtracting(["retryableFailure"]))
+  }
+
+  func testTargetAppUnavailableErrorKeepsItsWireShape() throws {
+    let encoded = try JSONEncoder().encode(
+      ErrorPayload.targetAppUnavailable(bundleId: "com.example.app")
+    )
+    let object = try XCTUnwrap(JSONSerialization.jsonObject(with: encoded) as? [String: Any])
+    XCTAssertEqual(Array(object.keys), ["message"])
+    XCTAssertEqual(object["message"] as? String, "app 'com.example.app' is not available")
+    XCTAssertEqual(
+      ErrorPayload.targetAppUnavailable(bundleId: nil).message,
+      "runner app is not available"
+    )
+  }
+}
+#endif

From dabbeb54cd92df1df0ae08fba4f5510bf7316592 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Wed, 23 Sep 2026 20:13:52 +0200
Subject: [PATCH 066/132] refactor(ios-runner): drop the runner's snapshot
 warning text; the verdict carries every disclosure (#2834)

* refactor(ios-runner): drop the runner's snapshot warning text; the verdict carries every disclosure

The runner rendered recovery, sparse, custom-action coverage and depth warnings into the
snapshot payload's message for daemons that predate snapshotQuality. The daemon renders each
of those from the structured verdict and ignores message whenever a verdict is present, and
local runner adoption pairs only same-version runners, so the text had no reader. The stamped
payload now forwards the underlying payload message unchanged.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* chore(gates): select the stamped-payload disclosure test in the iOS runner PR lane

The deleted partial-coverage message test is replaced in the PR list by the test that pins the
stamped payload leaving disclosures to the verdict.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .github/workflows/ios.yml                     |   2 +-
 .../RunnerTests+AXSnapshotFallback.swift      |  38 +----
 .../RunnerTests+SnapshotCapturePlan.swift     | 130 +++++-------------
 ...s+SnapshotPresentationInvariantTests.swift |  14 --
 .../interactor-runner-provider.test.ts        |  26 ++++
 src/commands/capture/runtime/snapshot.test.ts |  26 ++++
 6 files changed, 93 insertions(+), 143 deletions(-)

diff --git a/.github/workflows/ios.yml b/.github/workflows/ios.yml
index 81434bc9a0..0fd974f719 100644
--- a/.github/workflows/ios.yml
+++ b/.github/workflows/ios.yml
@@ -251,7 +251,7 @@ jobs:
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testPrivateAXNodesCarryAnnotatedCustomActions \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testRequestPinnedBackendReportsItsOwnReason \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testCustomActionCoverageParsesOnlyCompletePairs \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testPartialCustomActionPassIsDisclosedAndCompleteOneIsNot \
+            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testStampedPayloadCarriesDisclosuresOnlyInTheVerdict \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testActionNamesAreCappedPerElementAndReported \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testHungCustomActionReadIsContainedAndRecovers \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testAbandonedTreeCaptureSkipsQuerySweepAndHonorsWarmupExemption \
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+AXSnapshotFallback.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+AXSnapshotFallback.swift
index 354ffba76c..f77e0f6035 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+AXSnapshotFallback.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+AXSnapshotFallback.swift
@@ -583,13 +583,9 @@ extension RunnerTests {
     XCTAssertEqual(coverage[RunnerAXSnapshotCustomActionsCandidatesKey] as? Int, 1)
     XCTAssertEqual(
       RunnerAXSnapshotBridge.customActionReadDispatchCount(), dispatchesBefore + 1)
-
-    // And the rendered verdict names the hang, not the scroll remedy.
-    let blockedWarnings = Self.customActionCoverageWarnings(
-      Self.privateAXCustomActionCoverage(coverage)!)
-    XCTAssertEqual(blockedWarnings.count, 1)
-    XCTAssertTrue(blockedWarnings[0].contains("still hung"))
-    XCTAssertFalse(blockedWarnings[0].contains("Scroll"))
+    XCTAssertEqual(
+      Self.privateAXCustomActionCoverage(coverage),
+      SnapshotCustomActionCoverage(read: 0, candidates: 1, truncated: 0, blocked: true))
 
     // 4. Recovery: once the wedged call returns, reads resume by themselves.
     hung.release()
@@ -645,34 +641,6 @@ extension RunnerTests {
     XCTAssertFalse(truncated.boolValue)
   }
 
-  /// A capped pass must say so; a complete one must stay silent.
-  func testPartialCustomActionPassIsDisclosedAndCompleteOneIsNot() {
-    let partial = SnapshotQuality(
-      state: "recovered", backend: "private-ax", reason: nil, reasonCode: "requested-backend",
-      effectiveDepth: nil, collapsedLeafIndexes: nil,
-      customActions: SnapshotCustomActionCoverage(read: 12, candidates: 19, truncated: 0, blocked: false))
-    let message = Self.legacyQualityMessage(partial)
-    XCTAssertTrue(message?.contains("12 of 19 merged elements") == true)
-    XCTAssertTrue(message?.contains("remaining 7") == true)
-    XCTAssertTrue(message?.contains("Scroll them into view") == true)
-
-    // Every candidate read: nothing to disclose, and a healthy capture stays silent.
-    let complete = SnapshotQuality(
-      state: "healthy", backend: "private-ax", reason: nil, reasonCode: nil,
-      effectiveDepth: nil, collapsedLeafIndexes: nil,
-      customActions: SnapshotCustomActionCoverage(read: 19, candidates: 19, truncated: 0, blocked: false))
-    XCTAssertNil(Self.legacyQualityMessage(complete))
-
-    // A healthy capture with an incomplete pass still discloses — the guard must
-    // not key the disclosure off degradation state.
-    let healthyButCapped = SnapshotQuality(
-      state: "healthy", backend: "private-ax", reason: nil, reasonCode: nil,
-      effectiveDepth: nil, collapsedLeafIndexes: nil,
-      customActions: SnapshotCustomActionCoverage(read: 12, candidates: 19, truncated: 0, blocked: false))
-    XCTAssertTrue(
-      Self.legacyQualityMessage(healthyButCapped)?.contains("12 of 19") == true)
-  }
-
   /// Action names annotated by the bridge must survive into the emitted node —
   /// the whole point of the capture is that the merged card names its hidden
   /// affordances.
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotCapturePlan.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotCapturePlan.swift
index 7c6bc29443..16a999ab5d 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotCapturePlan.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotCapturePlan.swift
@@ -648,8 +648,7 @@ extension RunnerTests {
       timing: capture.timing
     )
     return DataPayload(
-      // Legacy human text for older daemons that read message instead of snapshotQuality.
-      message: Self.legacyQualityMessage(quality) ?? payload.message,
+      message: payload.message,
       nodes: payload.nodes,
       // Completeness, never provenance: a whole tree that a later backend produced (state
       // "recovered") stays untruncated, so strict absence reads can trust it. Only a real cap
@@ -666,75 +665,6 @@ extension RunnerTests {
       runnerFatalReason: payload.runnerFatalReason
     )
   }
-
-  /// Response level, one line per incompleteness. An unread merged element is
-  /// byte-identical to one with no actions, and a clipped list looks complete,
-  /// so both have to name themselves.
-  static func customActionCoverageWarnings(_ coverage: SnapshotCustomActionCoverage) -> [String] {
-    var lines: [String] = []
-    if coverage.blocked {
-      // Scrolling is the remedy for a budget stop, not for this one — saying it
-      // here would send the reader off doing something that cannot help.
-      lines.append(
-        "Custom actions were not read: an earlier accessibility read is still hung, so this "
-          + "capture skipped the read pass instead of queueing behind it. No element's actions "
-          + "list is authoritative here. Reads resume once that call returns.")
-    } else if coverage.read < coverage.candidates {
-      lines.append(
-        "Custom actions were read for \(coverage.read) of \(coverage.candidates) merged elements, "
-          + "on-screen ones first; the remaining \(coverage.candidates - coverage.read) were not read, "
-          + "so an absent actions list on those is not evidence that they have none. "
-          + "Scroll them into view and re-run to read them.")
-    }
-    if coverage.truncated > 0 {
-      lines.append(
-        "\(coverage.truncated) element(s) published more custom actions than are shown; those "
-          + "lists are clipped to the first 8 names, and long names are shortened.")
-    }
-    return lines
-  }
-
-  static func legacyQualityMessage(_ quality: SnapshotQuality) -> String? {
-    let customActionWarnings =
-      quality.customActions.map { Self.customActionCoverageWarnings($0) } ?? []
-    guard quality.state != "healthy" || quality.collapsedLeafIndexes != nil
-      || !customActionWarnings.isEmpty
-    else { return nil }
-    var parts: [String] = []
-    if quality.state == "recovered" {
-      let meaning: String
-      switch quality.reasonCode {
-      case "budget", "deferred":
-        meaning = " The primary capture ran out of its time budget (busy app or simulator); the recovered tree is authoritative for this screen."
-      case "presentation-failed":
-        meaning = " The runner rejected a regular presentation because its cumulative clip invariant failed; report this as a runner bug and treat screenshot as visual truth."
-      default:
-        meaning = " This usually means the app publishes an unhealthy accessibility tree — fixing the app's accessibility is the real cure. Treat screenshot as visual truth when this warning appears."
-      }
-      parts.append(
-        "Detected an overly complex or slow accessibility tree. Fell back to the \(quality.backend) snapshot backend"
-          + (quality.reason.map { " after: \($0)." } ?? ".")
-          + meaning
-      )
-    }
-    if quality.state == "sparse" {
-      parts.append(
-        "No snapshot backend could read this screen"
-          + (quality.reason.map { " (\($0))" } ?? "")
-          + ". Use screenshot as visual truth and coordinate taps."
-      )
-    }
-    parts.append(contentsOf: customActionWarnings)
-    if let depth = quality.effectiveDepth {
-      // No --depth remedy here: an explicit --depth capture disables the
-      // frontier extension, so following it would return strictly less than
-      // this capture did. A plain re-run retries with a fresh extension budget.
-      parts.append(
-        "The accessibility server rejected deeper requests; content below depth \(depth) may be missing — re-run snapshot to retry deeper content."
-      )
-    }
-    return parts.isEmpty ? nil : parts.joined(separator: " ")
-  }
 }
 
 #if AGENT_DEVICE_RUNNER_UNIT_TESTS
@@ -830,28 +760,6 @@ extension RunnerTests {
     XCTAssertNil(Self.collapsedLeafIndexes([root, prose]))
   }
 
-  func testLegacyQualityMessageStatesFallbackMeaning() {
-    let recovered = SnapshotQuality(
-      state: "recovered",
-      backend: "queries",
-      reason: "snapshot returned only structural application/window nodes",
-      reasonCode: "sparse-tree",
-      effectiveDepth: nil,
-      collapsedLeafIndexes: nil,
-      customActions: nil
-    )
-    let message = Self.legacyQualityMessage(recovered)
-    XCTAssertTrue(message?.contains("queries snapshot backend") == true)
-    XCTAssertTrue(message?.contains("fixing the app's accessibility") == true)
-    XCTAssertTrue(message?.contains("screenshot as visual truth") == true)
-    XCTAssertNil(
-      Self.legacyQualityMessage(
-        SnapshotQuality(
-          state: "healthy", backend: "tree", reason: nil, reasonCode: nil, effectiveDepth: nil,
-          collapsedLeafIndexes: nil, customActions: nil)
-      )
-    )
-  }
   func testTerminalFailsClosedOnInteractiveAxFailureRegardlessOfSparseBest() {
     // Interactive AX failure must invalidate + fail closed; a later tier's sparse synthetic-root
     // "best" must never downgrade this to a returned-sparse payload (regression: best == nil guard).
@@ -897,6 +805,42 @@ extension RunnerTests {
     XCTAssertEqual(payload.nodes?.count, 1)
   }
 
+  func testStampedPayloadCarriesDisclosuresOnlyInTheVerdict() {
+    let root = planTestNode(index: 0, type: "Application", label: "App")
+    let merged = planTestNode(
+      index: 1,
+      type: "Other",
+      label: (0...30).map { "Tab \($0)" }.joined(separator: ", "),
+      parentIndex: 0
+    )
+    let coverage = SnapshotCustomActionCoverage(
+      read: 12, candidates: 19, truncated: 0, blocked: false)
+    let silent = stampedSnapshotPayload(
+      SnapshotBackendCapture(
+        payload: DataPayload(nodes: [root, merged], truncated: false),
+        effectiveDepth: nil,
+        customActions: coverage
+      ),
+      backend: .recursiveTree,
+      state: "healthy",
+      reason: nil
+    )
+    XCTAssertNil(silent.message)
+    XCTAssertEqual(silent.snapshotQuality?.customActions, coverage)
+    XCTAssertEqual(silent.snapshotQuality?.collapsedLeafIndexes, [1])
+
+    let underlying = stampedSnapshotPayload(
+      SnapshotBackendCapture(
+        payload: DataPayload(message: "underlying", nodes: [root], truncated: false),
+        effectiveDepth: 4
+      ),
+      backend: .privateAX,
+      state: "recovered",
+      reason: (reason: "tree capture timed out", code: "budget")
+    )
+    XCTAssertEqual(underlying.message, "underlying")
+  }
+
   func testStampedPayloadTruncationTracksCompletenessNotRecoveryProvenance() {
     let complete = SnapshotBackendCapture(
       payload: DataPayload(
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotPresentationInvariantTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotPresentationInvariantTests.swift
index 65012e982d..c0c739b86d 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotPresentationInvariantTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotPresentationInvariantTests.swift
@@ -338,20 +338,6 @@ extension RunnerTests {
     XCTAssertEqual(Self.snapshotQualityReasonCode(for: captureFailure), "presentation-failed")
     XCTAssertNotEqual(Self.snapshotQualityReasonCode(for: captureFailure), "capture-failed")
     XCTAssertTrue(captureFailure.message.contains("cumulative clip"))
-
-    let warning = Self.legacyQualityMessage(
-      SnapshotQuality(
-        state: "recovered",
-        backend: "queries",
-        reason: captureFailure.message,
-        reasonCode: captureFailure.qualityReasonCode,
-        effectiveDepth: nil,
-        collapsedLeafIndexes: nil,
-        customActions: nil
-      )
-    )
-    XCTAssertTrue(warning?.contains("runner bug") == true)
-    XCTAssertFalse(warning?.contains("fixing the app's accessibility") == true)
   }
 }
 #endif
diff --git a/packages/platform-apple/src/__tests__/interactor-runner-provider.test.ts b/packages/platform-apple/src/__tests__/interactor-runner-provider.test.ts
index d55f0a4c0a..d0106f3392 100644
--- a/packages/platform-apple/src/__tests__/interactor-runner-provider.test.ts
+++ b/packages/platform-apple/src/__tests__/interactor-runner-provider.test.ts
@@ -266,6 +266,32 @@ test('snapshot publishes runner presentation through the engine and drops its qu
   assert.equal('qualityPayload' in result, false);
 });
 
+test('a message-less runner capture leaves its disclosures to the verdict', async () => {
+  const coverage = { read: 12, candidates: 19, truncated: 0, blocked: false };
+  const interactor = createAppleInteractor(
+    IOS_SIMULATOR,
+    {},
+    {
+      hasLiveSession: () => true,
+      runCommand: async () => ({
+        ...runnerResultFor({ command: 'snapshot' }),
+        snapshotQuality: {
+          state: 'healthy',
+          backend: 'tree',
+          customActions: coverage,
+          collapsedLeafIndexes: [1],
+        },
+      }),
+    },
+  );
+
+  const result = presentedSnapshot(await interactor.snapshot());
+
+  assert.equal('warnings' in result, false);
+  assert.deepEqual(result.quality?.customActions, coverage);
+  assert.deepEqual(result.quality?.collapsedLeafIndexes, [1]);
+});
+
 test('macOS app snapshots preserve runner nodes outside the iOS presentation engine', async () => {
   const nodes = [{ index: 0, type: 'Application', label: 'System Settings' }];
   const interactor = createAppleInteractor(
diff --git a/src/commands/capture/runtime/snapshot.test.ts b/src/commands/capture/runtime/snapshot.test.ts
index fa3056a692..378c3596a1 100644
--- a/src/commands/capture/runtime/snapshot.test.ts
+++ b/src/commands/capture/runtime/snapshot.test.ts
@@ -364,6 +364,32 @@ test('runtime snapshot renders the structured quality verdict and skips legacy d
   assert.deepEqual(result.snapshotQuality?.state, 'recovered');
 });
 
+test('runtime snapshot renders healthy-capture disclosures from the verdict alone', async () => {
+  const tabBarLabel = Array.from({ length: 12 }, (_, i) => `Tab ${i}`).join(', ');
+  const device = createSnapshotOnlyDevice({
+    nodes: [
+      { ref: 'e1', index: 0, depth: 0, type: 'Application', label: 'App' },
+      { ref: 'e2', index: 1, depth: 1, parentIndex: 0, type: 'Other', label: tabBarLabel },
+      { ref: 'e3', index: 2, depth: 1, parentIndex: 0, type: 'Button', label: 'Ok' },
+    ],
+    truncated: false,
+    backend: 'xctest',
+    quality: {
+      state: 'healthy',
+      backend: 'tree',
+      customActions: { read: 12, candidates: 19, truncated: 0, blocked: false },
+      collapsedLeafIndexes: [1],
+    },
+  });
+
+  const result = await device.capture.snapshot({ session: 'default' });
+
+  assert.deepEqual(result.warnings, [
+    'Custom actions were read for 12 of 19 merged elements, on-screen ones first; the remaining 7 were not read, so an absent actions list on those is not evidence that they have none. Scroll them into view and re-run to read them.',
+    "@e2 [Other] merges many labels into a single accessibility element. The app likely marks a container as accessible, which hides every descendant from assistive tech and automation — the children cannot be addressed individually. Fix the app's accessibility (mark the rows, not the container); until then use screenshot as visual truth and coordinate taps.",
+  ]);
+});
+
 test('runtime snapshot does not warn for a normal iOS interactive output', async () => {
   const device = createSnapshotOnlyDevice({
     nodes: [

From fa3b7291fe888c03da60477254f3cbd65430dbb3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Wed, 23 Sep 2026 20:13:52 +0200
Subject: [PATCH 067/132] refactor(ios-runner): restrict the tap-witness
 synthesized type route to the bare submit key (#2845)

* refactor(ios-runner): restrict the tap-witness synthesized type route to the bare submit key

The daemon sends ordinary `type` text in append mode and only the bare "\n"
with no text-entry mode, so the tap-witness synthesis gate now admits only
that shape. The ordinary-text commit wait it guarded never ran in production
and is deleted with its append-only outcome function and tests; the
replacement commit wait keeps every helper it shares.

Runner tests now send the daemon's request shapes: ordinary text in append
mode asserting the final field value, and a separate bare "\n" test asserting
the submission route. The touched command-level tests move to UnitTests/.

Closes #2800

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* chore(gates): select the bare submit-key route tests in the iOS runner PR lane

Replaces the deleted append-mode commit-progress test in the PR XCTest list
with the submit-key route test and its synthesis-unavailable refusal.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .github/workflows/ios.yml                     |   3 +-
 .../RunnerTests+CommandExecution.swift        | 102 ---------
 ...unnerTests+SynthesizedCommitDeadline.swift |  78 ++-----
 .../RunnerTests+SynthesizedTextEntry.swift    | 140 +++---------
 .../RunnerTests+TextEntry.swift               |   2 +-
 .../RunnerTests+TextTyping.swift              |  20 +-
 ...RunnerTests+CoordinateTextEntryTests.swift |   2 +-
 ...Tests+SynthesizedCommitDeadlineTests.swift |  43 +---
 .../RunnerTests+TextEntryPolicyTests.swift    | 199 +++---------------
 .../RunnerTests+TextInputProbeTests.swift     |   7 +-
 .../RunnerTests+TextTypingTests.swift         | 193 +++++++++++++++++
 .../apple-runner-log-redaction.test.ts        |   4 +-
 website/docs/docs/commands.md                 |   4 +-
 13 files changed, 295 insertions(+), 502 deletions(-)
 create mode 100644 apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+TextTypingTests.swift

diff --git a/.github/workflows/ios.yml b/.github/workflows/ios.yml
index 0fd974f719..4bc494a504 100644
--- a/.github/workflows/ios.yml
+++ b/.github/workflows/ios.yml
@@ -162,7 +162,8 @@ jobs:
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testHardwareKeyboardResponderConfirmsItsOwnKeyboardFocus \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testPenalizedCoordinateTapOnNonTextControlDoesNotAuthorizeBareType \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testBareDelayedTypeFailsWhenTappedInputDisappearsMidCommand \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testSynthesizedTextCommitProgressWalksExpectedPrefixOnly \
+            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testBareSubmitKeyUsesSynthesizedFirstResponderAfterHiddenKeyboardTap \
+            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testBareSubmitKeyRefusesWhenPrivateSynthesisIsUnavailable \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testEmptyReplacementWithoutResolvableTargetFailsClosed \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testTextEntryTapWitnessIsBoundToTargetIdentity \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testCoordinateTapTextInputProbeSkipsPenalizedXCTestChannel \
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
index 6be914e7cc..2e87e03529 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
@@ -345,76 +345,6 @@ extension RunnerTests {
 #endif
 
 #if os(iOS)
-  func testTypeWithoutResolvedInputReturnsTypedFailureBeforeDispatchingText() throws {
-    let command = try runnerCommandFixture(
-      #"{"command":"type","commandId":"type-without-focus","text":"hello"}"#
-    )
-
-    let response = executeTypeCommand(
-      activeApp: XCUIApplication(bundleIdentifier: "com.example.agentdevice.missing-input"),
-      command: command
-    )
-
-    XCTAssertFalse(response.ok)
-    XCTAssertEqual(response.error?.code, "TEXT_INPUT_NOT_FOCUSED")
-    XCTAssertEqual(
-      response.error?.hint,
-      "Focus a visible text input, then retry type or fill. If the input is not exposed by accessibility, use a coordinate focus command before typing."
-    )
-  }
-
-  func testBareTypeUsesTappedInputWhenSoftwareKeyboardIsHidden() throws {
-    // The fixture uses a real text responder with an empty input view to model hardware-keyboard input.
-    app.launchArguments = ["--agent-device-text-entry-regression"]
-    app.launch()
-    defer {
-      invalidateCachedTarget(reason: "unit_test_cleanup")
-      app.terminate()
-    }
-    XCTAssertTrue(app.waitForExistence(timeout: appExistenceTimeout))
-
-    let textField = app.textFields["agent-device-hardware-keyboard-input"]
-    XCTAssertTrue(textField.waitForExistence(timeout: appExistenceTimeout))
-    let frame = textField.frame
-    XCTAssertFalse(frame.isEmpty)
-
-    let tapCommand = try runnerCommandFixture(
-      #"{"command":"tap","commandId":"tap-hardware-keyboard-input","selectorKey":"id","selectorValue":"agent-device-hardware-keyboard-input"}"#
-    )
-    let tapResponse = try executeOnMainPrepared(command: tapCommand, activeApp: app)
-    XCTAssertTrue(tapResponse.ok, String(describing: tapResponse.error))
-    // A precondition, not a product claim. The fixture's empty `inputView` is what keeps the
-    // keyboard down, but nothing in this bundle owns the simulator's own keyboard settings, so an
-    // ambient flip that raised one here would be an environment fact — and reporting it as a
-    // failed assertion is what made this read as a product regression on unrelated PRs (#1874).
-    try XCTSkipIf(
-      isKeyboardVisible(app: app),
-      "software keyboard is up: this simulator cannot exercise the hidden-keyboard responder path"
-    )
-
-    let failureCountBefore = currentXCTestFailureCount()
-    let typeCommand = try runnerCommandFixture(
-      #"{"command":"type","commandId":"type-hardware-keyboard","text":"hardware-keyboard"}"#
-    )
-    let typeResponse = executeTypeCommand(activeApp: app, command: typeCommand)
-
-    XCTAssertTrue(typeResponse.ok, String(describing: typeResponse.error))
-    XCTAssertFalse(didRecordXCTestFailure(since: failureCountBefore))
-    XCTAssertEqual(typeResponse.data?.textEntryRoute, "synthesized-first-responder")
-    XCTAssertEqual(String(describing: textField.value ?? ""), "hardware-keyboard")
-
-    let secondFailureCountBefore = currentXCTestFailureCount()
-    let secondTypeCommand = try runnerCommandFixture(
-      #"{"command":"type","commandId":"type-hardware-keyboard-again","text":"-again"}"#
-    )
-    let secondTypeResponse = executeTypeCommand(activeApp: app, command: secondTypeCommand)
-
-    XCTAssertFalse(secondTypeResponse.ok)
-    XCTAssertEqual(secondTypeResponse.error?.code, "TEXT_INPUT_NOT_FOCUSED")
-    XCTAssertFalse(didRecordXCTestFailure(since: secondFailureCountBefore))
-    XCTAssertEqual(String(describing: textField.value ?? ""), "hardware-keyboard")
-  }
-
   // `waitForTextEntryReadiness`'s hardware-keyboard fallback returns early only on confirmed
   // focus (#1874), and `keyboardFocusConfirmed` reads that from the app-wide focus predicate this
   // bundle otherwise refuses to trust. Two XCTest facts it rests on, neither a repository
@@ -464,38 +394,6 @@ extension RunnerTests {
       "focus held by another element must read as a refusal, never as this element's focus"
     )
   }
-
-  func testBareDelayedTypeFailsWhenTappedInputDisappearsMidCommand() throws {
-    app.launchArguments = [
-      "--agent-device-text-entry-regression",
-      "--agent-device-text-entry-disappear-after-input",
-    ]
-    app.launch()
-    defer {
-      invalidateCachedTarget(reason: "unit_test_cleanup")
-      app.terminate()
-    }
-    XCTAssertTrue(app.waitForExistence(timeout: appExistenceTimeout))
-
-    let textField = app.textFields["agent-device-hardware-keyboard-input"]
-    XCTAssertTrue(textField.waitForExistence(timeout: appExistenceTimeout))
-    let tapCommand = try runnerCommandFixture(
-      #"{"command":"tap","commandId":"tap-disappearing-input","selectorKey":"id","selectorValue":"agent-device-hardware-keyboard-input"}"#
-    )
-    let tapResponse = try executeOnMainPrepared(command: tapCommand, activeApp: app)
-    XCTAssertTrue(tapResponse.ok, String(describing: tapResponse.error))
-
-    let failureCountBefore = currentXCTestFailureCount()
-    let typeCommand = try runnerCommandFixture(
-      #"{"command":"type","commandId":"type-disappearing-input","text":"ab","delayMs":50}"#
-    )
-    let typeResponse = executeTypeCommand(activeApp: app, command: typeCommand)
-
-    XCTAssertFalse(didRecordXCTestFailure(since: failureCountBefore))
-    XCTAssertFalse(typeResponse.ok)
-    XCTAssertEqual(typeResponse.error?.code, "TEXT_INPUT_NOT_FOCUSED")
-    XCTAssertFalse(textField.exists)
-  }
 #endif
 
   func testInjectedTapRecordedFailureGateIsTapOnlyAndCountGated() {
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SynthesizedCommitDeadline.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SynthesizedCommitDeadline.swift
index b88d2d5aa9..08edcf6cd8 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SynthesizedCommitDeadline.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SynthesizedCommitDeadline.swift
@@ -1,11 +1,11 @@
 import XCTest
 
-// The synthesized text-entry commit wait, end to end: the deadline that bounds it, the two waits
-// that run it, the observation/pacing they poll through, and the value-free cadence line that path
-// is allowed to log. Split from RunnerTests+SynthesizedTextEntry.swift, which keeps the
-// private-XCTest synthesis boundary and the route policies; the pure outcome functions these wrap
-// stay there next to the rules they encode. Everything that touches the polled field value now
-// lives in this one file, which is the surface apple-runner-log-redaction.test.ts guards.
+// The synthesized replacement commit wait, end to end: the deadline that bounds it, the wait that
+// runs it, the observation/pacing it polls through, and the value-free cadence line that path is
+// allowed to log. RunnerTests+SynthesizedTextEntry.swift keeps the private-XCTest synthesis
+// boundary, the route policies, and the pure outcome function this wraps. Everything that touches
+// the polled field value lives in this one file, which is the surface
+// apple-runner-log-redaction.test.ts guards.
 extension RunnerTests {
   /// One commit wait's running deadline.
   ///
@@ -57,54 +57,17 @@ extension RunnerTests {
     }
   }
 
-  /// Blocks until the synthesized bare-type text is observable in the target field, so `type`
-  /// cannot report ok while trailing characters are still uncommitted on a slow simulator.
-  ///
-  /// Observation only. A stalled prefix cannot be told apart from a suffix still queued in the
-  /// event stream, so re-synthesizing the difference risks committing it twice after the command
-  /// already reported success (#1676 rejected exactly that repair). Reporting `.notObserved` is
-  /// what the caller does instead: the partial value is the agent's to resolve, and a named
-  /// failure beats a success that misdescribes the field. Text carrying a submit key is skipped
-  /// outright: the app may clear or rewrite the field on submit, so `textBefore + typedText` is
-  /// not the value to wait for.
-  func awaitSynthesizedFirstResponderCommit(
-    app: XCUIApplication,
-    target: TextEntryTarget,
-    textBefore: String?,
-    typedText: String
-  ) -> SynthesizedTextCommitOutcome {
-    guard let textBefore, !typedText.contains("\n"), !typedText.contains("\r") else {
-      return .unobservable
-    }
-    let expectedText = textBefore + typedText
-    let waitStartedAt = Date()
-    NSLog("[DEBUG-1874] wait start expectedLen=%ld route=append", expectedText.count)
-    let ingredients = synthesizedCommitPollingIngredients(app: app, target: target, expectedText: expectedText)
-    let outcome = Self.awaitSynthesizedCommitOutcome(
-      expectedText: expectedText,
-      placeholder: ingredients.placeholder,
-      now: { Date() },
-      observe: ingredients.observe,
-      waitForNextObservation: ingredients.waitForNextObservation
-    )
-    NSLog(
-      "[DEBUG-1874] wait outcome=%@ elapsedMs=%.0f route=append",
-      String(describing: outcome),
-      waitStartedAt.timeIntervalSinceNow * -1000
-    )
-    return outcome
-  }
-
   /// Blocks until the synthesized replacement text (`fill`) is observable in the target field, so
   /// `fill` cannot report ok while the select-all-and-retype it posted is still uncommitted — or
   /// silently wrong — on a slow or channel-penalized simulator (this route runs only when the
-  /// XCTest channel is already penalized, and never resolves an `XCUIElement`, so it previously had
-  /// no verification at all).
+  /// XCTest channel is already penalized, and never resolves an `XCUIElement`).
   ///
-  /// Unlike the append route, the expected value is the final text itself — replacement mode
-  /// clears the field first, so there is no `textBefore` prefix to account for — and unlike the
-  /// append route, a settled mismatch is always reported rather than trusted: see
-  /// `awaitSynthesizedReplacementCommitOutcome`'s doc comment.
+  /// Observation only. A stalled prefix cannot be told apart from a suffix still queued in the
+  /// event stream, so re-synthesizing the difference risks committing it twice after the command
+  /// already reported success. The expected value is the
+  /// final text itself, and a settled mismatch is always reported: see
+  /// `awaitSynthesizedReplacementCommitOutcome`'s doc comment. Text carrying a submit key is
+  /// skipped outright: the app may clear or rewrite the field on submit.
   func awaitSynthesizedReplacementCommit(
     app: XCUIApplication,
     target: TextEntryTarget,
@@ -160,16 +123,9 @@ extension RunnerTests {
     )
   }
 
-  /// The placeholder/observe/pacing ingredients shared by the append route
-  /// (`awaitSynthesizedFirstResponderCommit`) and the replacement route
-  /// (`awaitSynthesizedReplacementCommit`). What must NOT be shared is which outcome function
-  /// consumes them: see `awaitSynthesizedReplacementCommitOutcome`'s doc comment for why append
-  /// mode's "trust a diverged value" rule is wrong for replacement mode. Each caller therefore
-  /// calls its own named outcome function directly, with real argument labels — deliberately not
-  /// a stored closure/function-value parameter here, which would erase those labels at the call
-  /// site and make the observe closure unrecognizable to the static content-redaction check in
-  /// `apple-runner-log-redaction.test.ts` (`extractObserveClosure` locates the labeled closure
-  /// literal by its text; a closure passed as a plain function value carries no such label).
+  /// The placeholder/observe/pacing ingredients the commit wait polls through. The observe closure
+  /// stays a labeled closure literal here: the static content-redaction check in
+  /// `apple-runner-log-redaction.test.ts` (`extractObserveClosure`) locates it by that text.
   private func synthesizedCommitPollingIngredients(
     app: XCUIApplication,
     target: TextEntryTarget,
@@ -189,7 +145,7 @@ extension RunnerTests {
           treatingPlaceholderAsEmpty: true
         )
         // Cadence evidence stays value-free: the polled value is user content typed through
-        // `type`/`fill` and must never reach runner.log. Lengths and the expected-prefix walk
+        // `fill` and must never reach runner.log. Lengths and the expected-prefix walk
         // are enough to distinguish throttling (prefix grows slowly) from a wedge (it freezes).
         Self.logCommitCadence(
           elapsedMs: Int(waitStartedAt.timeIntervalSinceNow * -1000),
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SynthesizedTextEntry.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SynthesizedTextEntry.swift
index 357af4f8d3..59086f3bd6 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SynthesizedTextEntry.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SynthesizedTextEntry.swift
@@ -127,10 +127,9 @@ extension RunnerTests {
         sleepFor(request.delaySeconds)
       }
     }
-    // The private synthesize call returns at post time, not commit time (same as bare `type`,
-    // see awaitSynthesizedFirstResponderCommit) — but this route never resolves an XCUIElement,
-    // so without this wait it had no way to notice a dropped or still-in-flight character at all
-    // and reported ok purely because the event posted. Wait here, on the same request.target
+    // The private synthesize call returns at post time, not commit time, and this route never
+    // resolves an XCUIElement, so without this wait it had no way to notice a dropped or
+    // still-in-flight character at all. Wait here, on the same request.target
     // (element nil, refreshPoint set) that gated this route, so each poll re-resolves via the
     // refresh point rather than trusting a stale element handle.
     let commit = awaitSynthesizedReplacementCommit(
@@ -168,37 +167,16 @@ extension RunnerTests {
     !hasResolvedElement && hasRefreshPoint && xCTestChannelPenalized
   }
 
+  /// The tap-witness route carries only the bare submit key, the one text the daemon sends without
+  /// a text-entry mode. Ordinary `type` text arrives in `.append` mode and is typed through the
+  /// resolved XCUIElement, where it is verified.
   static func shouldUseSynthesizedFirstResponderType(
     repairMode: TextTypingRepairMode,
+    text: String,
     fromTapWitness: Bool,
     softwareKeyboardVisible: Bool
   ) -> Bool {
-    repairMode == .none && fromTapWitness && !softwareKeyboardVisible
-  }
-
-  enum SynthesizedTextCommitProgress: Equatable {
-    case committed
-    case pending
-    case diverged
-  }
-
-  // The private synthesize call returns once the event record is posted, not once the target
-  // app has committed the characters, so intermediate reads walk prefix-by-prefix toward the
-  // expected value. Anything off that prefix path means the app transformed the input
-  // (formatter, mid-text caret, autocomplete) and the runner must not second-guess it. An
-  // unreadable value — secure field, or the element stopped resolving — ends the wait the
-  // same way.
-  static func synthesizedTextCommitProgress(
-    observedText: String?,
-    expectedText: String
-  ) -> SynthesizedTextCommitProgress {
-    guard let observedText else {
-      return .diverged
-    }
-    if observedText == expectedText {
-      return .committed
-    }
-    return expectedText.hasPrefix(observedText) ? .pending : .diverged
+    repairMode == .none && text == "\n" && fromTapWitness && !softwareKeyboardVisible
   }
 
   /// Length of the shared prefix of two strings. Feeds value-free commit-wait logging: the
@@ -213,73 +191,19 @@ extension RunnerTests {
     return length
   }
 
-  /// How the commit wait ended. Distinct from `SynthesizedTextCommitProgress`, which classifies a
-  /// single observation: this is the whole wait's verdict, and it exists so the deadline can be
-  /// told apart from success. The wait used to return `Void`, which made an expired deadline
-  /// indistinguishable from a committed one — `type` then reported ok with a partial value in the
-  /// field (#1874, #1844).
+  /// How the commit wait ended: the whole wait's verdict, so the deadline can be told apart from
+  /// success.
   enum SynthesizedTextCommitOutcome: Equatable {
-    /// The wait's success case, but its meaning is route-specific: for append mode (bare `type`),
-    /// the expected text committed OR the app transformed the input in a way the runner must not
-    /// second-guess; for replacement mode (`fill`), it means only an exact match — see
-    /// `awaitSynthesizedReplacementCommitOutcome`'s doc comment for why replacement mode has no
-    /// "trust it" case.
+    /// The field holds exactly the expected text.
     case settled
-    /// There was nothing to wait for — no readable baseline, or the text carries a submit key.
+    /// There was nothing to wait for: the text carries a submit key.
     case unobservable
     /// The deadline expired with the expected text still not observed.
     case notObserved
   }
 
-  /// The commit wait's decision, with observation, pacing and the clock injected so both deadline
-  /// branches are exercisable without a simulator (the macOS host lane runs this; the member
-  /// wrapper below binds the real XCUI reads).
-  ///
-  /// The deadline is a local `var`, started from this loop's own first `now()` and advanced from
-  /// the same observation the progress check reads, so "did the burst move" and "is time up" are
-  /// two statements in one loop. The budget defaults to the shipped one, so only a test that is
-  /// asking about time has to name it.
-  static func awaitSynthesizedCommitOutcome(
-    expectedText: String,
-    placeholder: String?,
-    stallBudget: TimeInterval = TextEntryTiming.synthesizedCommitStallTimeout,
-    ceiling: TimeInterval = TextEntryTiming.synthesizedCommitCeiling,
-    now: () -> Date = { Date() },
-    observe: () -> String?,
-    waitForNextObservation: () -> Void
-  ) -> SynthesizedTextCommitOutcome {
-    // A placeholder-equal AX value cannot prove a commit: an input handler may clear even a
-    // previously non-empty field after dispatch, making the empty field render the same value.
-    // Refuse before polling because no later read can distinguish those states.
-    if Self.textMatchesPlaceholder(expectedText, placeholder: placeholder) {
-      return .notObserved
-    }
-    var deadline = SynthesizedCommitDeadline(startedAt: now(), stallBudget: stallBudget, ceiling: ceiling)
-    // The deadline is checked AFTER an observation, never before one, so the last thing that
-    // happens before condemning a commit is a read. Checking first would condemn a commit that
-    // landed during the final poll sleep — the exact loaded-host timing this wait exists for.
-    while true {
-      let observedText = observe()
-      switch synthesizedTextCommitProgress(observedText: observedText, expectedText: expectedText) {
-      case .committed, .diverged:
-        return .settled
-      case .pending:
-        // One clock sample, so the instant an observation is recorded at is the instant it is
-        // judged against.
-        let sampledAt = now()
-        deadline.record(
-          expectedPrefixLength: Self.commonPrefixLength(observedText ?? "", expectedText),
-          at: sampledAt
-        )
-        if deadline.isExpired(at: sampledAt) { return .notObserved }
-        waitForNextObservation()
-      }
-    }
-  }
-
-  /// The command-level consequence of a commit wait. `.unobservable` is not a failure: there was
-  /// no baseline to compare against, which is the pre-existing contract for submit-key text and
-  /// unreadable fields, not evidence that anything went wrong.
+  /// The command-level consequence of a commit wait. `.unobservable` is not a failure: the app
+  /// may clear or rewrite the field on submit, so there is no value to compare against.
   static func textEntryFailure(
     forCommitOutcome outcome: SynthesizedTextCommitOutcome
   ) -> TextEntryFailure? {
@@ -291,22 +215,16 @@ extension RunnerTests {
     }
   }
 
-  /// The replacement-mode counterpart of `awaitSynthesizedCommitOutcome`. It must NOT reuse that
-  /// function's `synthesizedTextCommitProgress`: prefix-walk's `.diverged` case exists to trust an
-  /// app that transforms bare-`type` input (formatter, autocomplete) rather than second-guess it —
-  /// but that same rule silently accepts a dropped-character corruption too, because a value with a
-  /// hole in the middle ("ada@example" -> "aexample") is neither a matching prefix NOR the full
-  /// string, yet still gets classified `.diverged` -> `.settled` -> reported `ok: true`. This is not
-  /// a hypothetical: it is the exact shape of the corruption this wait exists to catch (`fill`
-  /// reporting success over "Avelace"/"aexample"-style drops), verified against both live examples
-  /// before writing this comment.
+  /// The replacement commit wait's decision, with observation, pacing and the clock injected so
+  /// both deadline branches are exercisable without a simulator (the macOS host lane runs this;
+  /// `awaitSynthesizedReplacementCommit` binds the real XCUI reads). The budget defaults to the
+  /// shipped one, so only a test that is asking about time has to name it.
   ///
-  /// `.replacement` mode does not need prefix tolerance for legitimate transforms either:
-  /// `isRepairableTextEntryMismatch` (RunnerTests+TextTyping.swift) already treats every mismatch in
-  /// `.replacement` mode as repairable unconditionally, with no formatter/autocomplete carve-out —
-  /// `fill` fully owns the field via select-all, so there is no legitimate reason for the settled
-  /// value to be anything other than exactly what was requested. A settled non-match is therefore
-  /// always the wait's failure case, never a `.settled` pass-through.
+  /// Only an exact match settles. A value with a hole in the middle ("ada@example" -> "aexample")
+  /// is the corruption this wait exists to catch, and `.replacement` mode has no formatter or
+  /// autocomplete carve-out: `isRepairableTextEntryMismatch` (RunnerTests+TextTyping.swift) treats
+  /// every `.replacement` mismatch as repairable, because `fill` owns the whole field via
+  /// select-all. A settled non-match is therefore always the wait's failure case.
   static func awaitSynthesizedReplacementCommitOutcome(
     expectedText: String,
     placeholder: String?,
@@ -316,18 +234,24 @@ extension RunnerTests {
     observe: () -> String?,
     waitForNextObservation: () -> Void
   ) -> SynthesizedTextCommitOutcome {
+    // A placeholder-equal AX value cannot prove a commit: an input handler may clear the field
+    // after dispatch, making the empty field render the same value. Refuse before polling because
+    // no later read can distinguish those states.
     if Self.textMatchesPlaceholder(expectedText, placeholder: placeholder) {
       return .notObserved
     }
     var deadline = SynthesizedCommitDeadline(startedAt: now(), stallBudget: stallBudget, ceiling: ceiling)
+    // The deadline is checked AFTER an observation, never before one, so the last thing that
+    // happens before condemning a commit is a read. Checking first would condemn a commit that
+    // landed during the final poll sleep — the exact loaded-host timing this wait exists for.
     while true {
       let observedText = observe()
       if observedText == expectedText {
         return .settled
       }
-      // Prefix growth cannot settle this wait — a value with a hole in the middle is still a
-      // failure, see the doc comment above — but it is the same evidence that the burst is still
-      // landing, so it buys the same time here as it does in append mode.
+      // Prefix growth cannot settle this wait, but it is evidence that the burst is still
+      // landing, so it buys time. One clock sample, so the instant an observation is recorded at
+      // is the instant it is judged against.
       let sampledAt = now()
       deadline.record(
         expectedPrefixLength: Self.commonPrefixLength(observedText ?? "", expectedText),
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+TextEntry.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+TextEntry.swift
index c3b3ec4b05..8aed63e9a5 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+TextEntry.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+TextEntry.swift
@@ -25,7 +25,7 @@ extension RunnerTests {
       case .notFocused:
         return "Focus a visible text input, then retry type or fill. If the input is not exposed by accessibility, use a coordinate focus command before typing."
       case .synthesisUnavailable:
-        return "Show the software keyboard, then retry type or fill."
+        return "Show the software keyboard, then retry type."
       case .commitNotObserved:
         return "The field may hold none, part, or all of the text. Run snapshot -i and inspect the field: if it already matches, continue; otherwise retry fill with the full text quoted and --delay-ms 80. Do not use type, which appends to whatever committed."
       }
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+TextTyping.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+TextTyping.swift
index 422da3e710..241d312dcb 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+TextTyping.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+TextTyping.swift
@@ -77,6 +77,7 @@ extension RunnerTests {
     }
     let shouldUseSynthesizedFirstResponderType = Self.shouldUseSynthesizedFirstResponderType(
       repairMode: repairMode,
+      text: text,
       fromTapWitness: activeTarget.fromTapWitness,
       softwareKeyboardVisible: isKeyboardVisible(app: app)
     )
@@ -142,26 +143,9 @@ extension RunnerTests {
         }
         textEntryRoute = "synthesized-first-responder"
         NSLog("AGENT_DEVICE_RUNNER_TEXT_ENTRY_ROUTE route=synthesized-first-responder")
-        let textBefore = editableTextValue(for: currentTarget, treatingPlaceholderAsEmpty: true)
         switch synthesizer.enterText(app: app, text: value, replacingExistingText: false) {
         case .continueTyping:
-          // No refresh point: like the tap-witness target itself, the commit wait must observe
-          // only the element the tap selected, never rediscover a different field.
-          let commit = awaitSynthesizedFirstResponderCommit(
-            app: app,
-            target: TextEntryTarget(
-              element: currentTarget,
-              refreshPoint: nil,
-              prefersFocusedElement: false,
-              fromTapWitness: true
-            ),
-            textBefore: textBefore,
-            typedText: value
-          )
-          // The characters were posted, so the element stays on the tuple for the caller's
-          // bookkeeping; the failure is what makes the command refuse. Reporting ok here is the
-          // defect this route had — the deadline was indistinguishable from a commit.
-          return (currentTarget, Self.textEntryFailure(forCommitOutcome: commit))
+          return (currentTarget, nil)
         case .fallback:
           return (nil, .synthesisUnavailable)
         case .raise(let message):
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+CoordinateTextEntryTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+CoordinateTextEntryTests.swift
index ed2b0001ca..e7bd7961c5 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+CoordinateTextEntryTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+CoordinateTextEntryTests.swift
@@ -42,7 +42,7 @@ extension RunnerTests {
 
     let failureCountBefore = currentXCTestFailureCount()
     let typeCommand = try runnerCommandFixture(
-      #"{"command":"type","commandId":"type-after-penalized-non-text-target","text":"must-not-type"}"#
+      #"{"command":"type","commandId":"type-after-penalized-non-text-target","text":"must-not-type","textEntryMode":"append"}"#
     )
     let typeResponse = executeTypeCommand(activeApp: app, command: typeCommand)
 
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SynthesizedCommitDeadlineTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SynthesizedCommitDeadlineTests.swift
index 840a6b0ef4..f4be5b61e7 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SynthesizedCommitDeadlineTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SynthesizedCommitDeadlineTests.swift
@@ -2,7 +2,7 @@ import XCTest
 
 extension RunnerTests {
 #if AGENT_DEVICE_RUNNER_UNIT_TESTS
-  /// A hand-driven clock for the commit waits. Time moves only where the wait sleeps, which is
+  /// A hand-driven clock for the commit wait. Time moves only where the wait sleeps, which is
   /// what makes "the burst kept landing" and "the pipeline froze" expressible as two sequences of
   /// the same length rather than as wall-clock luck — and a test that never advances it cannot
   /// expire any budget, so only a test asking about time names `stallBudget`/`ceiling`.
@@ -29,7 +29,7 @@ extension RunnerTests {
     let expected = "hardware"
     let clock = CommitWaitClock()
     var landed = 0
-    let outcome = Self.awaitSynthesizedCommitOutcome(
+    let outcome = Self.awaitSynthesizedReplacementCommitOutcome(
       expectedText: expected,
       placeholder: nil,
       stallBudget: 3,
@@ -55,7 +55,7 @@ extension RunnerTests {
     let clock = CommitWaitClock()
     clock.advance(60)
     var polls = 0
-    let outcome = Self.awaitSynthesizedCommitOutcome(
+    let outcome = Self.awaitSynthesizedReplacementCommitOutcome(
       expectedText: "hardware",
       placeholder: nil,
       stallBudget: 3,
@@ -76,7 +76,7 @@ extension RunnerTests {
   // fails today starts passing merely by waiting longer.
   func testCommitWaitCondemnsAFrozenPipelineAtTheStallBudget() {
     let clock = CommitWaitClock()
-    let outcome = Self.awaitSynthesizedCommitOutcome(
+    let outcome = Self.awaitSynthesizedReplacementCommitOutcome(
       expectedText: "hardware",
       placeholder: nil,
       stallBudget: 3,
@@ -89,32 +89,9 @@ extension RunnerTests {
     XCTAssertEqual(clock.elapsed, 3, "a frozen prefix must give up on the stall budget, not the ceiling")
   }
 
-  // Progress buys time, but not without bound: one character per stall window would otherwise
-  // hold the command open until the daemon's own 45s budget killed the request. Here every poll
-  // lands a character, so only the ceiling can stop it.
-  func testCommitWaitCeilingStopsAnIndefinitelyThrottledPipeline() {
-    let clock = CommitWaitClock()
-    var landed = 0
-    let outcome = Self.awaitSynthesizedCommitOutcome(
-      expectedText: String(repeating: "a", count: 100),
-      placeholder: nil,
-      stallBudget: 3,
-      ceiling: 10,
-      now: clock.read,
-      observe: { String(repeating: "a", count: landed) },
-      waitForNextObservation: {
-        landed += 1
-        clock.advance(2)
-      }
-    )
-    XCTAssertEqual(outcome, .notObserved)
-    XCTAssertEqual(clock.elapsed, 10, "the ceiling is absolute, however long characters keep arriving")
-  }
-
   // Only forward movement is evidence the burst is still landing. A field the app clears
   // mid-flight would otherwise reset the stall clock on every poll and hold every wedged wait
-  // open to the ceiling. Replacement mode, because that is where a non-matching value keeps
-  // polling rather than settling as `.diverged`.
+  // open to the ceiling.
   func testCommitWaitTreatsARetreatingValueAsNoProgress() {
     let clock = CommitWaitClock()
     let observations = ["ada@", "", "ada@", "", "ada@"]
@@ -135,11 +112,11 @@ extension RunnerTests {
     XCTAssertEqual(clock.elapsed, 3, "churn between two values is not progress and must not buy time")
   }
 
-  // The replacement route earns time the same way, and is bounded the same way — it is the route
-  // `fill` takes when the XCTest channel is penalized, i.e. the one that runs on a loaded host.
-  // Here every poll lands one more character of a value that never completes, so the wait can only
-  // end at the ceiling: it proves the growing prefix carried it past the 3s stall budget (a flat
-  // deadline stops at t=3) and that the ceiling still stops it.
+  // Progress buys time, but not without bound: one character per stall window would otherwise
+  // hold the command open until the daemon's own 45s budget killed the request. Here every poll
+  // lands one more character of a value that never completes, so the wait can only end at the
+  // ceiling: it proves the growing prefix carried it past the 3s stall budget (a flat deadline
+  // stops at t=3) and that the ceiling still stops it.
   func testReplacementCommitWaitOutlivesTheFlatDeadlineThenStopsAtTheCeiling() {
     let expected = "ada@example.com"
     let clock = CommitWaitClock()
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+TextEntryPolicyTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+TextEntryPolicyTests.swift
index beff83964c..556dd1aa65 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+TextEntryPolicyTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+TextEntryPolicyTests.swift
@@ -41,155 +41,34 @@ extension RunnerTests {
     }
   }
 
-  func testSynthesizedFirstResponderTypeRequiresHiddenKeyboardTapWitness() {
-    let cases: [(TextTypingRepairMode, Bool, Bool, Bool)] = [
-      (.none, true, false, true),
-      (.none, true, true, false),
-      (.none, false, false, false),
-      (.append, true, false, false),
-      (.replacement, true, false, false),
+  func testSynthesizedFirstResponderTypeAdmitsOnlyTheBareSubmitKeyAfterAHiddenKeyboardTap() {
+    let cases: [(TextTypingRepairMode, String, Bool, Bool, Bool)] = [
+      (.none, "\n", true, false, true),
+      (.none, "\n", true, true, false),
+      (.none, "\n", false, false, false),
+      (.none, "hardware-keyboard", true, false, false),
+      (.none, "\r", true, false, false),
+      (.none, "search\n", true, false, false),
+      (.append, "\n", true, false, false),
+      (.append, "hardware-keyboard", true, false, false),
+      (.replacement, "\n", true, false, false),
     ]
-    for (mode, fromTapWitness, softwareKeyboardVisible, expected) in cases {
+    for (mode, text, fromTapWitness, softwareKeyboardVisible, expected) in cases {
       XCTAssertEqual(
         Self.shouldUseSynthesizedFirstResponderType(
           repairMode: mode,
+          text: text,
           fromTapWitness: fromTapWitness,
           softwareKeyboardVisible: softwareKeyboardVisible
         ),
-        expected
+        expected,
+        "mode: \(mode), text: \(text.debugDescription)"
       )
     }
   }
 
-  func testSynthesizedTextCommitProgressWalksExpectedPrefixOnly() {
-    let expected = "hardware-keyboard"
-    XCTAssertEqual(
-      Self.synthesizedTextCommitProgress(observedText: "hardware-keyboard", expectedText: expected),
-      .committed
-    )
-    XCTAssertEqual(
-      Self.synthesizedTextCommitProgress(observedText: "", expectedText: expected),
-      .pending
-    )
-    XCTAssertEqual(
-      Self.synthesizedTextCommitProgress(observedText: "hardware-keyboa", expectedText: expected),
-      .pending
-    )
-    // Transformed input (formatter, mid-text caret, autocomplete) must stop the wait.
-    XCTAssertEqual(
-      Self.synthesizedTextCommitProgress(observedText: "hardwarX", expectedText: expected),
-      .diverged
-    )
-    XCTAssertEqual(
-      Self.synthesizedTextCommitProgress(observedText: "hardware-keyboards", expectedText: expected),
-      .diverged
-    )
-    XCTAssertEqual(
-      Self.synthesizedTextCommitProgress(observedText: nil, expectedText: expected),
-      .diverged
-    )
-  }
-
-  // The regression behind #1874/#1844: the wait used to return Void, so an expired deadline was
-  // indistinguishable from a commit and `type` reported ok over a partially committed field. The
-  // CI signature was a field holding "h" out of "hardware-keyboard" with the command successful.
-  func testSynthesizedCommitDeadlineIsNotReportedAsACommit() {
-    let clock = CommitWaitClock()
-    var observations = 0
-    let outcome = Self.awaitSynthesizedCommitOutcome(
-      expectedText: "hardware-keyboard",
-      placeholder: nil,
-      stallBudget: 3,
-      ceiling: 10,
-      now: clock.read,
-      observe: { "h" },
-      waitForNextObservation: {
-        observations += 1
-        clock.advance(1)
-      }
-    )
-    XCTAssertEqual(outcome, .notObserved)
-    XCTAssertEqual(observations, 3, "a pending prefix must keep polling until the deadline")
-  }
-
-  func testSynthesizedCommitStopsAtTheFirstSettledObservation() {
-    for observed in ["hardware-keyboard", "hardwarX", nil] {
-      var polls = 0
-      let outcome = Self.awaitSynthesizedCommitOutcome(
-        expectedText: "hardware-keyboard",
-        placeholder: nil,
-        observe: { observed },
-        waitForNextObservation: { polls += 1 }
-      )
-      // `.diverged` settles the wait too: the app transformed the input and the runner must not
-      // second-guess it. Only an outstanding strict prefix keeps waiting.
-      XCTAssertEqual(outcome, .settled, "observed: \(observed ?? "nil")")
-      XCTAssertEqual(polls, 0, "observed: \(observed ?? "nil")")
-    }
-  }
-
-  func testSynthesizedCommitWalksAPrefixToCompletion() {
-    let steps = ["", "hardware-", "hardware-keyboard"]
-    var index = 0
-    let outcome = Self.awaitSynthesizedCommitOutcome(
-      expectedText: "hardware-keyboard",
-      placeholder: nil,
-      observe: { steps[min(index, steps.count - 1)] },
-      waitForNextObservation: { index += 1 }
-    )
-    XCTAssertEqual(outcome, .settled)
-    XCTAssertEqual(index, 2)
-  }
-
-  // Adversarial-review finding: the deadline used to be checked BEFORE observing, so a commit
-  // landing during the final poll sleep was condemned as never observed — a false failure under
-  // exactly the loaded-host timing this wait exists for. Red against that ordering.
-  func testCommitLandingDuringTheFinalSleepIsStillObserved() {
-    let clock = CommitWaitClock()
-    var polls = 0
-    let outcome = Self.awaitSynthesizedCommitOutcome(
-      expectedText: "hardware-keyboard",
-      placeholder: nil,
-      stallBudget: 3,
-      ceiling: 10,
-      now: clock.read,
-      // The value lands during the sleep that takes the clock past the stall budget: the read
-      // happens first, so it is still observed.
-      observe: { polls == 0 ? "hardware-" : "hardware-keyboard" },
-      waitForNextObservation: {
-        polls += 1
-        clock.advance(9)
-      }
-    )
-    XCTAssertEqual(outcome, .settled)
-  }
-
-  // A pre-dispatch value cannot identify what a later placeholder-equal AX value represents.
-  // Here the field starts at "0", but its input handler clears it after `type ".00"`; the empty
-  // field then renders its "0.00" placeholder. Reporting success would describe an empty field as
-  // committed text.
-  func testClearAfterDispatchCannotTurnThePlaceholderIntoCommitEvidence() {
-    let textBeforeDispatch = "0"
-    let expectedText = textBeforeDispatch + ".00"
-    var observations = 0
-    let outcome = Self.awaitSynthesizedCommitOutcome(
-      expectedText: expectedText,
-      placeholder: "0.00",
-      observe: {
-        observations += 1
-        return "0.00"
-      },
-      waitForNextObservation: {}
-    )
-    XCTAssertEqual(
-      Self.textEntryFailure(forCommitOutcome: outcome)?.rawValue,
-      "TEXT_INPUT_COMMIT_NOT_OBSERVED"
-    )
-    XCTAssertEqual(observations, 0, "no post-dispatch read can resolve this collision")
-  }
-
   // The guard must stay narrow: it fires only when the WHOLE expected value is the placeholder.
-  // Widening it would refuse ordinary typing into any placeheld field, which is most of them.
+  // Widening it would refuse ordinary entry into any placeheld field, which is most of them.
   func testPlaceholderGuardDoesNotFireOnOrdinaryTyping() {
     let cases: [(placeholder: String?, expectedText: String)] = [
       ("0.00", "0.005"),
@@ -199,7 +78,7 @@ extension RunnerTests {
       ("   ", ""),
     ]
     for testCase in cases {
-      let outcome = Self.awaitSynthesizedCommitOutcome(
+      let outcome = Self.awaitSynthesizedReplacementCommitOutcome(
         expectedText: testCase.expectedText,
         placeholder: testCase.placeholder,
         observe: { testCase.expectedText },
@@ -209,32 +88,16 @@ extension RunnerTests {
     }
   }
 
-  // The bug this whole route exists to fix: `awaitSynthesizedCommitOutcome` (append/`type`) treats
-  // any non-prefix value as `.diverged` -> `.settled`, i.e. "trust the app, don't second-guess it."
-  // That rule is correct for `type` (an autocomplete/formatter can legitimately transform bare
-  // input) but silently swallows a dropped-character corruption in `.replacement` mode, because a
-  // value with a hole in the middle is neither a matching prefix nor an exact match — it still hits
-  // `.diverged`. These are the two corruption strings actually observed in CI on `fill`
+  // A value with a hole in the middle is neither a matching prefix nor an exact match, and must
+  // never settle. These are the two corruption strings actually observed in CI on `fill`
   // (id="field-name" "Ada Lovelace" -> "Avelace", id="field-email" "ada@example" -> "aexample";
-  // first character and tail survive, a middle run is missing). Confirms
-  // `awaitSynthesizedReplacementCommitOutcome` reports `.notObserved` for both, where
-  // `awaitSynthesizedCommitOutcome` (proven by the assertion inside the loop) reports `.settled`.
+  // first character and tail survive, a middle run is missing).
   func testSynthesizedReplacementCommitCatchesDroppedMiddleCharacters() {
     let corruptions: [(expected: String, observedAfterDrop: String)] = [
       (expected: "Ada Lovelace", observedAfterDrop: "Avelace"),
       (expected: "ada@example", observedAfterDrop: "aexample"),
     ]
     for corruption in corruptions {
-      XCTAssertEqual(
-        Self.awaitSynthesizedCommitOutcome(
-          expectedText: corruption.expected,
-          placeholder: nil,
-          observe: { corruption.observedAfterDrop },
-          waitForNextObservation: {}
-        ),
-        .settled,
-        "append-mode's diverge-trusting outcome must stay unchanged by this fix"
-      )
       let clock = CommitWaitClock()
       var polls = 0
       let outcome = Self.awaitSynthesizedReplacementCommitOutcome(
@@ -255,10 +118,7 @@ extension RunnerTests {
   }
 
   // The non-failure counterpart: replacement mode must still tolerate real commit lag (the value
-  // converges to an exact match over a few polls), not just instant matches. Mirrors
-  // `testSynthesizedCommitWalksAPrefixToCompletion`, but replacement mode has no "prefix" concept —
-  // every intermediate read here is deliberately NOT a prefix of the final value, to prove the wait
-  // does not depend on prefix-walking to keep polling.
+  // converges to an exact match over a few polls), not just instant matches.
   func testSynthesizedReplacementCommitToleratesLagUntilExactMatch() {
     let steps = ["", "ad", "ada@example"]
     var index = 0
@@ -272,8 +132,8 @@ extension RunnerTests {
     XCTAssertEqual(index, 2)
   }
 
-  // Same ordering guarantee as `testCommitLandingDuringTheFinalSleepIsStillObserved`: the deadline
-  // is checked AFTER an observation, so a match landing during the final poll sleep is still caught.
+  // The deadline is checked AFTER an observation, so a match landing during the final poll sleep
+  // is still caught.
   func testSynthesizedReplacementCommitLandingDuringTheFinalSleepIsStillObserved() {
     let clock = CommitWaitClock()
     var polls = 0
@@ -292,8 +152,9 @@ extension RunnerTests {
     XCTAssertEqual(outcome, .settled)
   }
 
-  // Same placeholder-collision guard as append mode, and for the same reason: a pre-dispatch value
-  // cannot identify what a later placeholder-equal AX value represents, so refuse before polling.
+  // A pre-dispatch value cannot identify what a later placeholder-equal AX value represents: an
+  // input handler may clear the field after dispatch and the empty field then renders the
+  // placeholder. Reporting success would describe an empty field as committed text.
   func testSynthesizedReplacementCommitPlaceholderGuardRefusesWithoutPolling() {
     var observations = 0
     let outcome = Self.awaitSynthesizedReplacementCommitOutcome(
@@ -310,8 +171,7 @@ extension RunnerTests {
   }
 
   // The mapping the command actually refuses on. `.unobservable` must stay a success: it is the
-  // pre-existing contract for submit-key text and unreadable fields, so inverting it would fail
-  // every `type "...\n"`.
+  // contract for submit-key text, so inverting it would fail every `fill` ending in a submit key.
   func testOnlyAnUnobservedCommitBecomesACommandFailure() {
     XCTAssertNil(Self.textEntryFailure(forCommitOutcome: .settled))
     XCTAssertNil(Self.textEntryFailure(forCommitOutcome: .unobservable))
@@ -465,9 +325,8 @@ extension RunnerTests {
     XCTAssertNil(result.observedText)
   }
 
-  // Companion to the above: text carrying a submit key must skip the wait entirely, same as the
-  // append route (`awaitSynthesizedFirstResponderCommit`) — the app may clear or rewrite the field
-  // on submit, so there is nothing meaningful to poll toward.
+  // Companion to the above: text carrying a submit key must skip the wait entirely — the app may
+  // clear or rewrite the field on submit, so there is nothing meaningful to poll toward.
   func testSynthesizedReplacementCommitSkipsSubmitKeyText() {
     for expectedText in ["ada@example.test\n", "ada@example.test\r"] {
       XCTAssertEqual(
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+TextInputProbeTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+TextInputProbeTests.swift
index fd1a0d51c9..28686cec65 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+TextInputProbeTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+TextInputProbeTests.swift
@@ -75,10 +75,11 @@ extension RunnerTests {
     XCTAssertNotNil(textEntryTapWitness)
     XCTAssertFalse(isSnapshotXCTestChannelPenalized(bundleId: currentBundleId))
     try XCTSkipIf(isKeyboardVisible(app: app), "software keyboard is up; hidden-keyboard witness cannot be exercised")
-    let type = try runnerCommandFixture(#"{"appBundleId":"com.callstack.agentdevice.runner","command":"type","commandId":"type-healthy-probe","text":"probe-witness"}"#)
+    let type = try runnerCommandFixture(#"{"appBundleId":"com.callstack.agentdevice.runner","command":"type","commandId":"type-healthy-probe","text":"probe-witness","textEntryMode":"append"}"#)
     let typed = try execute(command: type)
     XCTAssertTrue(typed.ok, String(describing: typed.error))
-    XCTAssertEqual(typed.data?.textEntryRoute, "synthesized-first-responder")
+    XCTAssertEqual(typed.data?.textEntryRoute, "xctest-element")
+    XCTAssertNil(textEntryTapWitness, "the type must consume the tap witness it was addressed by")
     XCTAssertEqual(field.value as? String, "probe-witness")
     XCTAssertFalse(didRecordXCTestFailure(since: failures))
   }
@@ -153,7 +154,7 @@ extension RunnerTests {
     XCTAssertFalse(didRecordXCTestFailure(since: failures))
     XCTAssertFalse(isSnapshotXCTestChannelPenalized(bundleId: currentBundleId))
     XCTAssertNil(textEntryTapWitness)
-    let type = try runnerCommandFixture(#"{"appBundleId":"com.callstack.agentdevice.runner","command":"type","commandId":"type-after-unavailable-probe","text":"must-not-type"}"#)
+    let type = try runnerCommandFixture(#"{"appBundleId":"com.callstack.agentdevice.runner","command":"type","commandId":"type-after-unavailable-probe","text":"must-not-type","textEntryMode":"append"}"#)
     let typed = try execute(command: type)
     XCTAssertFalse(typed.ok)
     XCTAssertEqual(typed.error?.code, "TEXT_INPUT_NOT_FOCUSED")
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+TextTypingTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+TextTypingTests.swift
new file mode 100644
index 0000000000..214f599bd6
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+TextTypingTests.swift
@@ -0,0 +1,193 @@
+import XCTest
+
+// Command-level `type` coverage in the request shapes the daemon sends: ordinary text in
+// `textEntryMode: "append"`, and the bare submit key with no mode.
+extension RunnerTests {
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS && os(iOS)
+  func testTypeWithoutResolvedInputReturnsTypedFailureBeforeDispatchingText() throws {
+    let command = try runnerCommandFixture(
+      #"{"command":"type","commandId":"type-without-focus","text":"hello","textEntryMode":"append"}"#
+    )
+
+    let response = executeTypeCommand(
+      activeApp: XCUIApplication(bundleIdentifier: "com.example.agentdevice.missing-input"),
+      command: command
+    )
+
+    XCTAssertFalse(response.ok)
+    XCTAssertEqual(response.error?.code, "TEXT_INPUT_NOT_FOCUSED")
+    XCTAssertEqual(
+      response.error?.hint,
+      "Focus a visible text input, then retry type or fill. If the input is not exposed by accessibility, use a coordinate focus command before typing."
+    )
+  }
+
+  func testBareTypeUsesTappedInputWhenSoftwareKeyboardIsHidden() throws {
+    // The fixture uses a real text responder with an empty input view to model hardware-keyboard input.
+    let textField = try launchHardwareKeyboardFixture()
+    try tapHardwareKeyboardInput(commandId: "tap-hardware-keyboard-input")
+    try skipUnlessSoftwareKeyboardIsHidden()
+
+    let failureCountBefore = currentXCTestFailureCount()
+    let typeResponse = executeTypeCommand(
+      activeApp: app,
+      command: try runnerCommandFixture(
+        #"{"command":"type","commandId":"type-hardware-keyboard","text":"hardware-keyboard","textEntryMode":"append"}"#
+      )
+    )
+
+    XCTAssertTrue(typeResponse.ok, String(describing: typeResponse.error))
+    XCTAssertFalse(didRecordXCTestFailure(since: failureCountBefore))
+    XCTAssertEqual(typeResponse.data?.textEntryRoute, "xctest-element")
+    XCTAssertNil(textEntryTapWitness, "the type must consume the tap witness it was addressed by")
+    XCTAssertEqual(textField.value as? String, "hardware-keyboard")
+
+    // The tap witness is one-shot: a second bare type without a new tap has no target.
+    let unfocusedFailureCountBefore = currentXCTestFailureCount()
+    let unfocusedResponse = executeTypeCommand(
+      activeApp: app,
+      command: try runnerCommandFixture(
+        #"{"command":"type","commandId":"type-hardware-keyboard-unfocused","text":"-again","textEntryMode":"append"}"#
+      )
+    )
+
+    XCTAssertFalse(unfocusedResponse.ok)
+    XCTAssertEqual(unfocusedResponse.error?.code, "TEXT_INPUT_NOT_FOCUSED")
+    XCTAssertFalse(didRecordXCTestFailure(since: unfocusedFailureCountBefore))
+    XCTAssertEqual(textField.value as? String, "hardware-keyboard")
+
+    try tapHardwareKeyboardInput(commandId: "tap-hardware-keyboard-input-again")
+    // The first tap already proved this simulator keeps the keyboard down for the fixture, so a
+    // keyboard here is a product change, not an environment fact.
+    XCTAssertFalse(isKeyboardVisible(app: app))
+    let appendFailureCountBefore = currentXCTestFailureCount()
+    let appendResponse = executeTypeCommand(
+      activeApp: app,
+      command: try runnerCommandFixture(
+        #"{"command":"type","commandId":"type-hardware-keyboard-again","text":"-again","textEntryMode":"append"}"#
+      )
+    )
+
+    XCTAssertTrue(appendResponse.ok, String(describing: appendResponse.error))
+    XCTAssertFalse(didRecordXCTestFailure(since: appendFailureCountBefore))
+    XCTAssertEqual(appendResponse.data?.textEntryRoute, "xctest-element")
+    XCTAssertEqual(textField.value as? String, "hardware-keyboard-again")
+  }
+
+  func testBareSubmitKeyUsesSynthesizedFirstResponderAfterHiddenKeyboardTap() throws {
+    _ = try launchHardwareKeyboardFixture()
+    try tapHardwareKeyboardInput(commandId: "tap-hardware-keyboard-submit")
+    try skipUnlessSoftwareKeyboardIsHidden()
+
+    let failureCountBefore = currentXCTestFailureCount()
+    let submitResponse = executeTypeCommand(
+      activeApp: app,
+      command: try runnerCommandFixture(
+        #"{"command":"type","commandId":"type-hardware-keyboard-submit","text":"\n"}"#
+      )
+    )
+
+    XCTAssertTrue(submitResponse.ok, String(describing: submitResponse.error))
+    XCTAssertFalse(didRecordXCTestFailure(since: failureCountBefore))
+    XCTAssertEqual(submitResponse.data?.textEntryRoute, "synthesized-first-responder")
+    XCTAssertNil(textEntryTapWitness, "the submit must consume the tap witness it was addressed by")
+  }
+
+  func testBareSubmitKeyRefusesWhenPrivateSynthesisIsUnavailable() throws {
+    let textField = try launchHardwareKeyboardFixture()
+    try skipUnlessSoftwareKeyboardIsHidden()
+
+    let failureCountBefore = currentXCTestFailureCount()
+    let result = typeTextReliably(
+      app: app,
+      target: TextEntryTarget(
+        element: textField,
+        refreshPoint: nil,
+        prefersFocusedElement: false,
+        fromTapWitness: true
+      ),
+      text: "\n",
+      delaySeconds: 0,
+      synthesizer: UnavailableTextEntrySynthesizer()
+    )
+
+    XCTAssertEqual(result.failure, .synthesisUnavailable)
+    XCTAssertEqual(result.textEntryRoute, "synthesized-first-responder")
+    XCTAssertFalse(didRecordXCTestFailure(since: failureCountBefore))
+  }
+
+  func testBareDelayedTypeFailsWhenTappedInputDisappearsMidCommand() throws {
+    app.launchArguments = [
+      "--agent-device-text-entry-regression",
+      "--agent-device-text-entry-disappear-after-input",
+    ]
+    app.launch()
+    defer {
+      invalidateCachedTarget(reason: "unit_test_cleanup")
+      app.terminate()
+    }
+    XCTAssertTrue(app.waitForExistence(timeout: appExistenceTimeout))
+
+    let textField = app.textFields["agent-device-hardware-keyboard-input"]
+    XCTAssertTrue(textField.waitForExistence(timeout: appExistenceTimeout))
+    let tapCommand = try runnerCommandFixture(
+      #"{"command":"tap","commandId":"tap-disappearing-input","selectorKey":"id","selectorValue":"agent-device-hardware-keyboard-input"}"#
+    )
+    let tapResponse = try executeOnMainPrepared(command: tapCommand, activeApp: app)
+    XCTAssertTrue(tapResponse.ok, String(describing: tapResponse.error))
+
+    let failureCountBefore = currentXCTestFailureCount()
+    let typeCommand = try runnerCommandFixture(
+      #"{"command":"type","commandId":"type-disappearing-input","text":"ab","delayMs":50,"textEntryMode":"append"}"#
+    )
+    let typeResponse = executeTypeCommand(activeApp: app, command: typeCommand)
+
+    XCTAssertFalse(didRecordXCTestFailure(since: failureCountBefore))
+    XCTAssertFalse(typeResponse.ok)
+    XCTAssertEqual(typeResponse.error?.code, "TEXT_INPUT_NOT_FOCUSED")
+    XCTAssertFalse(textField.exists)
+  }
+
+  private struct UnavailableTextEntrySynthesizer: TextEntrySynthesizing {
+    func enterText(
+      app _: XCUIApplication,
+      text _: String,
+      replacingExistingText _: Bool
+    ) -> SynthesizedTextEntryAction {
+      .fallback
+    }
+  }
+
+  private func launchHardwareKeyboardFixture() throws -> XCUIElement {
+    app.launchArguments = ["--agent-device-text-entry-regression"]
+    app.launch()
+    addTeardownBlock { [self] in
+      invalidateCachedTarget(reason: "unit_test_cleanup")
+      app.terminate()
+    }
+    XCTAssertTrue(app.waitForExistence(timeout: appExistenceTimeout))
+    let textField = app.textFields["agent-device-hardware-keyboard-input"]
+    XCTAssertTrue(textField.waitForExistence(timeout: appExistenceTimeout))
+    XCTAssertFalse(textField.frame.isEmpty)
+    return textField
+  }
+
+  private func tapHardwareKeyboardInput(commandId: String) throws {
+    let tapCommand = try runnerCommandFixture(
+      #"{"command":"tap","commandId":"\#(commandId)","selectorKey":"id","selectorValue":"agent-device-hardware-keyboard-input"}"#
+    )
+    let tapResponse = try executeOnMainPrepared(command: tapCommand, activeApp: app)
+    XCTAssertTrue(tapResponse.ok, String(describing: tapResponse.error))
+  }
+
+  // A precondition, not a product claim. The fixture's empty `inputView` is what keeps the
+  // keyboard down, but nothing in this bundle owns the simulator's own keyboard settings, so an
+  // ambient keyboard here is an environment fact rather than a product regression.
+  private func skipUnlessSoftwareKeyboardIsHidden() throws {
+    try XCTSkipIf(
+      isKeyboardVisible(app: app),
+      "software keyboard is up: this simulator cannot exercise the hidden-keyboard responder path"
+    )
+  }
+#endif
+}
diff --git a/src/__tests__/apple-runner-log-redaction.test.ts b/src/__tests__/apple-runner-log-redaction.test.ts
index 3cb18245bf..25b266a502 100644
--- a/src/__tests__/apple-runner-log-redaction.test.ts
+++ b/src/__tests__/apple-runner-log-redaction.test.ts
@@ -10,8 +10,8 @@ const commitWaitPath = path.join(
   'apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SynthesizedCommitDeadline.swift',
 );
 
-// The synthesized bare-type commit wait polls the target field's live value on the shipped
-// `type` path. That value is user content — a `type` command may carry credentials, tokens, or
+// The synthesized replacement commit wait polls the target field's live value on the shipped
+// `fill` path. That value is user content — a `fill` command may carry credentials, tokens, or
 // PII — and runner.log persists across the session. Cadence evidence must stay value-free.
 //
 // The enforcement is a typed Swift boundary (`logCommitCadence`), whose parameters are Ints
diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md
index 5a675ccdc6..cb6ba7c8f8 100644
--- a/website/docs/docs/commands.md
+++ b/website/docs/docs/commands.md
@@ -485,8 +485,8 @@ agent-device gesture transform 200 420 80 -40 2 35 700 # combined pan, zoom, and
 `fill` clears then types. `type` does not clear.
 `type` accepts text only. Do not pass `@ref` to `type`; use `fill @ref "text"` to target a field directly, or `press @ref` then `type "text"` to append in the focused field.
 If `type` reports `TEXT_INPUT_NOT_FOCUSED`, focus a visible text input and retry; when accessibility does not expose the input, use a coordinate focus command before typing.
-On iOS, if `type` reports `TEXT_INPUT_SYNTHESIS_UNAVAILABLE` while the software keyboard is hidden, show the software keyboard, then retry `type` or `fill`. The runner reports this error instead of risking partial input through an unreliable text-entry path.
-On iOS, if `type` or `fill` reports `TEXT_INPUT_COMMIT_NOT_OBSERVED`, the runner could not confirm the typed text reached the field — either it did not land before the runner's deadline, or the expected final text is identical to the field's placeholder. In the latter case, accessibility cannot distinguish committed text from an empty field rendering that placeholder, even if the field held content before dispatch. The field may hold none, part, or all of the text: run `snapshot -i` and inspect it. If it already matches, continue; otherwise retry with the full text quoted and `fill --delay-ms 80`, which replaces the whole value. Do not use `type`, which appends to whatever committed. This covers the bare-type route and the coordinate-driven `fill` route taken when the accessibility channel is under load, both of which observe the field after synthesizing; it is not a guarantee that every text-entry route verifies its result.
+On iOS, if `type "\n"` reports `TEXT_INPUT_SYNTHESIS_UNAVAILABLE` after tapping a field while the software keyboard is hidden, show the software keyboard, then retry. The runner reports this error instead of risking input through an unreliable text-entry path.
+On iOS, if `fill` reports `TEXT_INPUT_COMMIT_NOT_OBSERVED`, the runner could not confirm the typed text reached the field — either it did not land before the runner's deadline, or the expected final text is identical to the field's placeholder. In the latter case, accessibility cannot distinguish committed text from an empty field rendering that placeholder, even if the field held content before dispatch. The field may hold none, part, or all of the text: run `snapshot -i` and inspect it. If it already matches, continue; otherwise retry with the full text quoted and `fill --delay-ms 80`, which replaces the whole value. Do not use `type`, which appends to whatever committed. This covers the coordinate-driven `fill` route taken when the accessibility channel is under load, which observes the field after synthesizing; it is not a guarantee that every text-entry route verifies its result.
 Use plain `fill` or `type` first for ordinary login and form fields. Use `--delay-ms` on `type` or `fill` only when a debounced search field or search-as-you-type input actually misses characters, or when the app must receive incremental updates.
 Delayed typing intentionally prefers paced character entry over clipboard-style fallbacks so the target field receives each incremental update.
 On Android, `fill` also verifies text and treats IME-owned capture as a terminal failure instead of retrying against the wrong field.

From 5d0e66da25b90cc0d3fe537e414debc7a769e48b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Wed, 23 Sep 2026 20:43:28 +0200
Subject: [PATCH 068/132] fix(macos): refuse --fullscreen on every
 helper-captured surface (#2849)

* fix(macos): reject --fullscreen on desktop and menubar surfaces

desktop and menubar always capture the main display through the macOS
helper, so an explicit --fullscreen on either named a frame the
capture could never vary. It was parsed, ignored, and echoed back
unchanged. Refuse it before any capture with a typed INVALID_ARGS
reason instead. macOS app sessions (runner path) and every other
platform keep accepting --fullscreen unchanged.

Remove the now-dead --fullscreen plumbing: the helper's argument
parse, its capture parameter, and the fullscreen response field; the
TS helper argv and its return type.

* test(macos): prove --fullscreen desktop refusal through the daemon router

The provider-scenario suite still sent screenshotFullscreen:true on the
desktop surface and asserted a --fullscreen helper argv, so it exercised
the pre-fix contract and was the only test reaching the refusal through
daemon -> bound screenshot runtime -> interactor. Add a direct refusal
check (INVALID_ARGS, details.reason
SCREENSHOT_FULLSCREEN_MACOS_HELPER_SURFACE_FIXED_FRAME, no helper call),
strip screenshotFullscreen from the two desktop capture steps and their
expected argv, and stop echoing the retired fullscreen field from the
fake helper.

Update the desktop-inspection recipe and add a prose note documenting
that desktop/menubar refuse --fullscreen. Record the behavior change in
the changelog, including its effect on recorded scripts and project
config that set screenshotFullscreen for those surfaces.

* fix(macos): derive --fullscreen refusal from the helper-routing predicate

rejectsMacOsHelperFullscreen hand-listed desktop/menubar as a second,
independently maintained copy of usesMacOsSurfaceScreenshot's routing
condition, so it silently missed frontmost-app: that surface also
captures through the macOS helper's fixed main-display frame but kept
accepting and ignoring --fullscreen. Key the refusal directly off
usesMacOsSurfaceScreenshot instead, so every surface it routes to the
helper today or in the future refuses the flag, and delete the
separate list.

* test(macos): pin every helper-routed surface refuses --fullscreen

Derive the covered surfaces from SESSION_SURFACES filtered to
non-'app' (the routing predicate's own domain) instead of a hand
list, so screenshot-macos-surface.test.ts now exercises
frontmost-app alongside desktop/menubar and stays complete if a
future surface is added. Add a matching frontmost-app refusal check
to the provider-scenario daemon-router test, next to the existing
desktop one.

* docs(macos): scope --fullscreen refusal wording to every helper-routed surface

The screenshot command's cliDetail, the commands.md prose, and the
Unreleased CHANGELOG entry named only desktop/menubar; widen them to
match the fix now that frontmost-app also refuses.

* docs(macos): capitalize the --fullscreen surface refusal sentence in screenshot help
---
 CHANGELOG.md                                  |  8 ++
 apple/macos-helper/Package.swift              |  4 +
 .../Sources/AgentDeviceMacOSHelper/main.swift |  9 +-
 .../ScreenshotResponseTests.swift             | 15 +++
 packages/contracts/src/facades/capture.ts     |  2 +
 packages/contracts/src/screenshot.ts          | 13 +++
 .../screenshot-macos-surface.test.ts          | 92 +++++++++++++++++++
 packages/platform-apple/src/interactor.ts     | 17 +++-
 .../src/os/macos/helper.test.ts               | 26 +++++-
 .../platform-apple/src/os/macos/helper.ts     |  6 +-
 src/commands/capture/screenshot.ts            |  2 +-
 .../provider-scenarios/macos-desktop.test.ts  | 72 +++++++++++++--
 .../provider-scenarios/macos-world.ts         |  1 -
 website/docs/docs/commands.md                 |  3 +-
 14 files changed, 248 insertions(+), 22 deletions(-)
 create mode 100644 apple/macos-helper/Tests/AgentDeviceMacOSHelperTests/ScreenshotResponseTests.swift
 create mode 100644 packages/platform-apple/src/__tests__/screenshot-macos-surface.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 688e453617..2cdcb0b8eb 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,6 +17,14 @@
   the caller was told it had failed (#2546's late tap, from the banner side). Alert activation now
   opts out of XCTest's interruption handling, which also stops that handler from pressing a button of
   its own choosing on an unrelated system alert while the command answers the alert it resolved.
+- Fixed (macos): `screenshot --fullscreen` on the `desktop`, `menubar`, or `frontmost-app` surface
+  now refuses with `INVALID_ARGS` (`details.reason:
+  SCREENSHOT_FULLSCREEN_MACOS_HELPER_SURFACE_FIXED_FRAME`) instead of being accepted and silently
+  ignored. Every one of those surfaces captures through the macOS helper, which always reads the
+  main display, so the flag never named a frame the capture could vary. A `.ad` script or project
+  config that sets `screenshotFullscreen` for one of those surfaces now fails instead of succeeding
+  with the same image it always produced; drop the flag there. macOS app sessions and every other
+  platform keep accepting `--fullscreen` unchanged. (#2799)
 - Fixed (ios): a local Simulator snapshot taken through the host AX bridge once again publishes the
   geometric `hittable` fact, so `is hittable` and a `hittable:` selector resolve the same controls on
   the bridge and the XCTest runner. The snapshot capability table has declared `hittable =
diff --git a/apple/macos-helper/Package.swift b/apple/macos-helper/Package.swift
index 3a472a3ca2..844c6cb2bb 100644
--- a/apple/macos-helper/Package.swift
+++ b/apple/macos-helper/Package.swift
@@ -22,5 +22,9 @@ let package = Package(
       name: "AgentDeviceMacOSInputTests",
       dependencies: ["AgentDeviceMacOSInput"]
     ),
+    .testTarget(
+      name: "AgentDeviceMacOSHelperTests",
+      dependencies: ["AgentDeviceMacOSHelper"]
+    ),
   ]
 )
diff --git a/apple/macos-helper/Sources/AgentDeviceMacOSHelper/main.swift b/apple/macos-helper/Sources/AgentDeviceMacOSHelper/main.swift
index cc9be1260a..1dc3445312 100644
--- a/apple/macos-helper/Sources/AgentDeviceMacOSHelper/main.swift
+++ b/apple/macos-helper/Sources/AgentDeviceMacOSHelper/main.swift
@@ -75,7 +75,6 @@ struct PressResponse: Encodable {
 struct ScreenshotResponse: Encodable {
   let path: String
   let surface: String?
-  let fullscreen: Bool
 }
 
 struct AgentDeviceMacOSHelper {
@@ -436,9 +435,8 @@ struct AgentDeviceMacOSHelper {
     }
 
     let surface = optionValue(arguments: arguments, name: "--surface")
-    let fullscreen = arguments.contains("--fullscreen")
-    try captureSurfaceScreenshot(surface: surface, outPath: outPath, fullscreen: fullscreen)
-    return SuccessEnvelope(data: ScreenshotResponse(path: outPath, surface: surface, fullscreen: fullscreen))
+    try captureSurfaceScreenshot(surface: surface, outPath: outPath)
+    return SuccessEnvelope(data: ScreenshotResponse(path: outPath, surface: surface))
   }
 
   static func handleAudioProbe(arguments: [String]) throws -> any Encodable {
@@ -547,8 +545,7 @@ private func pressAtPosition(_ request: MouseClickRequest) throws {
   }
 }
 
-private func captureSurfaceScreenshot(surface: String?, outPath: String, fullscreen: Bool) throws {
-  _ = fullscreen
+private func captureSurfaceScreenshot(surface: String?, outPath: String) throws {
   guard #available(macOS 15.2, *) else {
     throw HelperError.commandFailed(
       "screenshot on macOS desktop and menubar surfaces requires macOS 15.2 or newer"
diff --git a/apple/macos-helper/Tests/AgentDeviceMacOSHelperTests/ScreenshotResponseTests.swift b/apple/macos-helper/Tests/AgentDeviceMacOSHelperTests/ScreenshotResponseTests.swift
new file mode 100644
index 0000000000..a5471c009f
--- /dev/null
+++ b/apple/macos-helper/Tests/AgentDeviceMacOSHelperTests/ScreenshotResponseTests.swift
@@ -0,0 +1,15 @@
+import XCTest
+
+@testable import AgentDeviceMacOSHelper
+
+/// `captureSurfaceScreenshot` always reads the main display, so the response describes only
+/// what was actually captured: no field for an argument the helper does not read.
+final class ScreenshotResponseTests: XCTestCase {
+  func testResponseNeverCarriesAFullscreenField() throws {
+    let response = ScreenshotResponse(path: "/tmp/out.png", surface: "desktop")
+    let data = try JSONEncoder().encode(response)
+    let decoded = try JSONSerialization.jsonObject(with: data) as? [String: Any]
+
+    XCTAssertEqual(Set(decoded?.keys.map { $0 } ?? []), ["path", "surface"])
+  }
+}
diff --git a/packages/contracts/src/facades/capture.ts b/packages/contracts/src/facades/capture.ts
index 9b10f17115..a25a0c2258 100644
--- a/packages/contracts/src/facades/capture.ts
+++ b/packages/contracts/src/facades/capture.ts
@@ -4,6 +4,7 @@ export {
   SCREENSHOT_ACTION_FLAG_KEYS,
   SCREENSHOT_COMMAND_FLAG_KEYS,
   SCREENSHOT_CROP_REASONS,
+  SCREENSHOT_FULLSCREEN_REASONS,
   SCREENSHOT_SCALE_LIMITS,
   SCREENSHOT_SPECIFIC_FLAG_DEFINITIONS,
   appendScreenshotScriptFlags,
@@ -18,6 +19,7 @@ export {
 export type {
   ScreenshotCropReason,
   ScreenshotDispatchFlags,
+  ScreenshotFullscreenReason,
   ScreenshotPublicOptions,
   ScreenshotRequestFlags,
   ScreenshotRuntimeFlags,
diff --git a/packages/contracts/src/screenshot.ts b/packages/contracts/src/screenshot.ts
index a759c80073..e3610f8a5d 100644
--- a/packages/contracts/src/screenshot.ts
+++ b/packages/contracts/src/screenshot.ts
@@ -67,6 +67,19 @@ export const SCREENSHOT_CROP_REASONS = {
 export type ScreenshotCropReason =
   (typeof SCREENSHOT_CROP_REASONS)[keyof typeof SCREENSHOT_CROP_REASONS];
 
+/**
+ * Machine-readable `screenshot --fullscreen` refusal reason. Every macOS surface captured through
+ * the helper (every `--surface` other than `app`) always reads the main display; an explicit
+ * `--fullscreen` on one of them names a frame the capture cannot vary, so it is refused with this
+ * reason in `error.details.reason` rather than silently ignored.
+ */
+export const SCREENSHOT_FULLSCREEN_REASONS = {
+  macOsHelperSurfaceFixedFrame: 'SCREENSHOT_FULLSCREEN_MACOS_HELPER_SURFACE_FIXED_FRAME',
+} as const;
+
+export type ScreenshotFullscreenReason =
+  (typeof SCREENSHOT_FULLSCREEN_REASONS)[keyof typeof SCREENSHOT_FULLSCREEN_REASONS];
+
 export const SCREENSHOT_COMMAND_FLAG_KEYS = [
   'out',
   'overlayRefs',
diff --git a/packages/platform-apple/src/__tests__/screenshot-macos-surface.test.ts b/packages/platform-apple/src/__tests__/screenshot-macos-surface.test.ts
new file mode 100644
index 0000000000..3d41e5d0d1
--- /dev/null
+++ b/packages/platform-apple/src/__tests__/screenshot-macos-surface.test.ts
@@ -0,0 +1,92 @@
+import { beforeEach, expect, test, vi } from 'vitest';
+import type { DeviceInfo } from '@agent-device/kernel/device';
+import { SCREENSHOT_FULLSCREEN_REASONS } from '@agent-device/contracts/capture';
+import { SESSION_SURFACES } from '@agent-device/contracts/session';
+
+vi.mock('../os/macos/helper.ts', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../os/macos/helper.ts')>();
+  return {
+    ...actual,
+    runMacOsScreenshotAction: vi.fn(async (outPath: string) => ({ path: outPath })),
+  };
+});
+
+vi.mock('../core/screenshot.ts', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../core/screenshot.ts')>();
+  return {
+    ...actual,
+    captureScreenshotViaRunner: vi.fn(),
+    screenshotIos: vi.fn(),
+  };
+});
+
+import { createAppleInteractor } from '../interactor.ts';
+import { runMacOsScreenshotAction } from '../os/macos/helper.ts';
+import { screenshotIos } from '../core/screenshot.ts';
+
+const macOsDevice: DeviceInfo = {
+  platform: 'apple',
+  appleOs: 'macos',
+  id: 'host-mac',
+  name: 'Host Mac',
+  kind: 'device',
+  target: 'desktop',
+  booted: true,
+};
+
+beforeEach(() => {
+  vi.mocked(runMacOsScreenshotAction).mockClear();
+  vi.mocked(screenshotIos).mockClear();
+});
+
+// The helper-routed domain, derived from the same condition `usesMacOsSurfaceScreenshot` applies
+// (every session surface except `app`) rather than a hand-picked list — so adding a surface to
+// `SESSION_SURFACES` extends this coverage automatically instead of silently falling outside it.
+const helperRoutedSurfaces = SESSION_SURFACES.filter((surface) => surface !== 'app');
+
+test.each(helperRoutedSurfaces)(
+  'refuses an explicit --fullscreen on the macOS %s surface before any capture',
+  async (surface) => {
+    const interactor = createAppleInteractor(macOsDevice, {});
+
+    await expect(
+      interactor.screenshot('/tmp/out.png', { surface, fullscreen: true }),
+    ).rejects.toMatchObject({
+      code: 'INVALID_ARGS',
+      details: expect.objectContaining({
+        reason: SCREENSHOT_FULLSCREEN_REASONS.macOsHelperSurfaceFixedFrame,
+        surface,
+      }),
+    });
+
+    expect(runMacOsScreenshotAction).not.toHaveBeenCalled();
+  },
+);
+
+test.each(helperRoutedSurfaces)(
+  'captures the %s surface through the helper when --fullscreen is not requested',
+  async (surface) => {
+    const interactor = createAppleInteractor(macOsDevice, {});
+
+    await interactor.screenshot('/tmp/out.png', { surface });
+
+    expect(runMacOsScreenshotAction).toHaveBeenCalledOnce();
+    const [, options] = vi.mocked(runMacOsScreenshotAction).mock.calls[0]!;
+    expect(options).toEqual({ surface });
+    expect(Object.hasOwn(options ?? {}, 'fullscreen')).toBe(false);
+  },
+);
+
+test('keeps a macOS app session on the runner path with --fullscreen unchanged', async () => {
+  const interactor = createAppleInteractor(macOsDevice, {});
+
+  await interactor.screenshot('/tmp/out.png', { surface: 'app', fullscreen: true });
+
+  expect(runMacOsScreenshotAction).not.toHaveBeenCalled();
+  expect(screenshotIos).toHaveBeenCalledOnce();
+  expect(screenshotIos).toHaveBeenCalledWith(
+    macOsDevice,
+    '/tmp/out.png',
+    expect.objectContaining({ fullscreen: true }),
+  );
+});
diff --git a/packages/platform-apple/src/interactor.ts b/packages/platform-apple/src/interactor.ts
index 313c797765..945a32309f 100644
--- a/packages/platform-apple/src/interactor.ts
+++ b/packages/platform-apple/src/interactor.ts
@@ -13,6 +13,7 @@ import {
   type AppleRunnerProvider,
 } from './runner/index.ts';
 import { toAppleTvRemoteButton } from '@agent-device/contracts/tv-remote';
+import { SCREENSHOT_FULLSCREEN_REASONS } from '@agent-device/contracts/capture';
 import type { SessionSurface } from '@agent-device/contracts/session';
 import { DEVICE_ROTATIONS, type DeviceRotation } from '@agent-device/contracts/device';
 import { normalizeSnapshotScope } from '@agent-device/contracts/snapshot';
@@ -386,9 +387,18 @@ async function runAppleScreenshot(
   runnerOpts: RunnerCallOptions,
 ): Promise<void> {
   if (usesMacOsSurfaceScreenshot(device, options.surface)) {
+    if (options.fullscreen) {
+      throw new AppError(
+        'INVALID_ARGS',
+        `screenshot --fullscreen is not accepted on the macOS ${options.surface} surface: it always captures the main display`,
+        {
+          reason: SCREENSHOT_FULLSCREEN_REASONS.macOsHelperSurfaceFixedFrame,
+          surface: options.surface,
+        },
+      );
+    }
     await runMacOsScreenshotAction(outPath, {
       surface: options.surface,
-      fullscreen: options.fullscreen,
     });
     return;
   }
@@ -414,6 +424,11 @@ async function runAppleScreenshot(
   });
 }
 
+/**
+ * Every surface this admits captures through the macOS helper's fixed main-display frame, so
+ * `runAppleScreenshot` also keys its `--fullscreen` refusal directly off this predicate: whichever
+ * surface routes here cannot vary its captured frame, helper-routed today or added later.
+ */
 function usesMacOsSurfaceScreenshot(
   device: DeviceInfo,
   surface: ScreenshotOptions['surface'],
diff --git a/packages/platform-apple/src/os/macos/helper.test.ts b/packages/platform-apple/src/os/macos/helper.test.ts
index eb8d24b0e9..483483d494 100644
--- a/packages/platform-apple/src/os/macos/helper.test.ts
+++ b/packages/platform-apple/src/os/macos/helper.test.ts
@@ -1,7 +1,12 @@
 import assert from 'node:assert/strict';
 import { test } from 'vitest';
 import { createLocalAppleToolProvider, withAppleToolProvider } from '../../core/tool-provider.ts';
-import { macOsClickScheduleMs, runMacOsPressAction, runMacOsSnapshotAction } from './helper.ts';
+import {
+  macOsClickScheduleMs,
+  runMacOsPressAction,
+  runMacOsScreenshotAction,
+  runMacOsSnapshotAction,
+} from './helper.ts';
 
 test('macOS helper snapshot passes cancellation to the helper process', async () => {
   const controller = new AbortController();
@@ -207,3 +212,22 @@ test('macOS helper press stays a single held click when nothing is repeated', as
   assert.equal(receivedArgs.includes('--hold-ms'), false);
   assert.equal(receivedArgs.includes('--interval-ms'), false);
 });
+
+test('macOS helper screenshot argv carries only --out and --surface', async () => {
+  let receivedArgs: string[] = [];
+  const provider = createLocalAppleToolProvider({
+    macosHelper: {
+      run: async (args) => {
+        receivedArgs = args;
+        return helperReturn({ path: '/tmp/out.png', surface: 'desktop' });
+      },
+    },
+  });
+
+  await withAppleToolProvider(
+    provider,
+    async () => await runMacOsScreenshotAction('/tmp/out.png', { surface: 'desktop' }),
+  );
+
+  assert.deepEqual(receivedArgs, ['screenshot', '--out', '/tmp/out.png', '--surface', 'desktop']);
+});
diff --git a/packages/platform-apple/src/os/macos/helper.ts b/packages/platform-apple/src/os/macos/helper.ts
index a0bd002176..b807ab1589 100644
--- a/packages/platform-apple/src/os/macos/helper.ts
+++ b/packages/platform-apple/src/os/macos/helper.ts
@@ -473,16 +473,12 @@ export async function runMacOsPressAction(
 
 export async function runMacOsScreenshotAction(
   outPath: string,
-  options: { surface?: SessionSurface; fullscreen?: boolean } = {},
+  options: { surface?: SessionSurface } = {},
 ): Promise<{
   path: string;
   surface?: SessionSurface;
-  fullscreen: boolean;
 }> {
   const args = ['screenshot', '--out', outPath];
   appendMacOsHelperContextArgs(args, options);
-  if (options.fullscreen) {
-    args.push('--fullscreen');
-  }
   return await runMacOsHelper(args);
 }
diff --git a/src/commands/capture/screenshot.ts b/src/commands/capture/screenshot.ts
index 67a86c38d3..283fc30659 100644
--- a/src/commands/capture/screenshot.ts
+++ b/src/commands/capture/screenshot.ts
@@ -74,7 +74,7 @@ export const screenshotCommandFacet = defineCommandFacet({
   text: {
     summary: 'Capture a screenshot',
     cliDetail:
-      'Web defaults to the viewport; use --fullscreen, --full, or -f for the entire page. iOS simulators default to 1x logical-point output; use --pixel-density to request a different screenshot density. macOS app sessions default to the app window; use --fullscreen for full desktop, --scale to downscale, --crop-on <selector> to crop the capture to the frame the selector resolves on the same screen (currently iOS simulators and Android emulators), --overlay-refs to annotate current refs, --normalize-status-bar for deterministic iOS simulator chrome, or --no-stabilize for low-latency Android capture loops.',
+      'Web defaults to the viewport; use --fullscreen, --full, or -f for the entire page. iOS simulators default to 1x logical-point output; use --pixel-density to request a different screenshot density. macOS app sessions default to the app window; use --fullscreen for full desktop, --scale to downscale, --crop-on <selector> to crop the capture to the frame the selector resolves on the same screen (currently iOS simulators and Android emulators), --overlay-refs to annotate current refs, --normalize-status-bar for deterministic iOS simulator chrome, or --no-stabilize for low-latency Android capture loops. On macOS, any --surface other than app (desktop, menubar, frontmost-app) always captures the main display and refuses an explicit --fullscreen.',
   },
   metadata: screenshotCommandMetadata,
   run: (client, input) => client.capture.screenshot(input),
diff --git a/test/integration/provider-scenarios/macos-desktop.test.ts b/test/integration/provider-scenarios/macos-desktop.test.ts
index 9df52ff9d6..e982520fa5 100644
--- a/test/integration/provider-scenarios/macos-desktop.test.ts
+++ b/test/integration/provider-scenarios/macos-desktop.test.ts
@@ -1,7 +1,13 @@
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import { test } from 'vitest';
-import { assertFlatToolCall, assertPngDimensions, assertPngFile } from './assertions.ts';
+import { SCREENSHOT_FULLSCREEN_REASONS } from '@agent-device/contracts/capture';
+import {
+  assertFlatToolCall,
+  assertPngDimensions,
+  assertPngFile,
+  assertRpcError,
+} from './assertions.ts';
 import { PROVIDER_SCENARIO_MACOS } from './fixtures.ts';
 import { createProviderScenarioTempPath, withProviderScenarioResource } from './harness.ts';
 import { createMacOsDesktopWorld } from './macos-world.ts';
@@ -292,6 +298,36 @@ test('Provider-backed integration macOS desktop flow uses semantic host and help
             flags: { doubleTap: true },
             expectData: { x: 116, y: 80, doubleTap: true },
           },
+        ]);
+
+        const helperScreenshotCallsBeforeFrontmostRefusal = appleTool.calls.filter(
+          (call) => call[0] === 'macos-helper' && call[1] === 'screenshot',
+        ).length;
+        const frontmostFullscreenRefusal = await daemon.callCommand('screenshot', [], {
+          out: screenshotPath,
+          screenshotFullscreen: true,
+        });
+        const frontmostRefusalErrorData = assertRpcError(
+          frontmostFullscreenRefusal,
+          'INVALID_ARGS',
+          /--fullscreen is not accepted on the macOS frontmost-app surface/,
+        );
+        const frontmostRefusalDetails = frontmostRefusalErrorData.details as
+          | Record<string, unknown>
+          | undefined;
+        assert.equal(
+          frontmostRefusalDetails?.reason,
+          SCREENSHOT_FULLSCREEN_REASONS.macOsHelperSurfaceFixedFrame,
+        );
+        assert.equal(frontmostRefusalDetails?.surface, 'frontmost-app');
+        assert.equal(
+          appleTool.calls.filter((call) => call[0] === 'macos-helper' && call[1] === 'screenshot')
+            .length,
+          helperScreenshotCallsBeforeFrontmostRefusal,
+          'A refused --fullscreen frontmost-app screenshot must not reach the macos-helper',
+        );
+
+        await runProviderScenario(daemon, [
           {
             name: 'switch to desktop surface',
             command: 'open',
@@ -304,6 +340,34 @@ test('Provider-backed integration macOS desktop flow uses semantic host and help
               appBundleId: undefined,
             },
           },
+        ]);
+
+        const helperScreenshotCallsBeforeRefusal = appleTool.calls.filter(
+          (call) => call[0] === 'macos-helper' && call[1] === 'screenshot',
+        ).length;
+        const fullscreenRefusal = await daemon.callCommand('screenshot', [], {
+          out: screenshotPath,
+          screenshotFullscreen: true,
+        });
+        const refusalErrorData = assertRpcError(
+          fullscreenRefusal,
+          'INVALID_ARGS',
+          /--fullscreen is not accepted on the macOS desktop surface/,
+        );
+        const refusalDetails = refusalErrorData.details as Record<string, unknown> | undefined;
+        assert.equal(
+          refusalDetails?.reason,
+          SCREENSHOT_FULLSCREEN_REASONS.macOsHelperSurfaceFixedFrame,
+        );
+        assert.equal(refusalDetails?.surface, 'desktop');
+        assert.equal(
+          appleTool.calls.filter((call) => call[0] === 'macos-helper' && call[1] === 'screenshot')
+            .length,
+          helperScreenshotCallsBeforeRefusal,
+          'A refused --fullscreen desktop screenshot must not reach the macos-helper',
+        );
+
+        await runProviderScenario(daemon, [
           {
             name: 'read desktop surface state',
             command: 'appstate',
@@ -316,11 +380,10 @@ test('Provider-backed integration macOS desktop flow uses semantic host and help
             },
           },
           {
-            name: 'capture fullscreen desktop screenshot',
+            name: 'capture desktop screenshot',
             command: 'screenshot',
             flags: {
               out: screenshotPath,
-              screenshotFullscreen: true,
             },
             expectData: { path: screenshotPath },
             assert: () => {
@@ -332,7 +395,6 @@ test('Provider-backed integration macOS desktop flow uses semantic host and help
             command: 'screenshot',
             flags: {
               out: scaledScreenshotPath,
-              screenshotFullscreen: true,
               screenshotScale: 0.5,
             },
             expectData: { path: scaledScreenshotPath },
@@ -493,7 +555,6 @@ test('Provider-backed integration macOS desktop flow uses semantic host and help
           screenshotPath,
           '--surface',
           'desktop',
-          '--fullscreen',
         ]);
         assertFlatToolCall(appleTool.calls, [
           'macos-helper',
@@ -502,7 +563,6 @@ test('Provider-backed integration macOS desktop flow uses semantic host and help
           scaledScreenshotPath,
           '--surface',
           'desktop',
-          '--fullscreen',
         ]);
         assertFlatToolCall(appleTool.calls, [
           'macos-helper',
diff --git a/test/integration/provider-scenarios/macos-world.ts b/test/integration/provider-scenarios/macos-world.ts
index 66338a228b..3fbb9897cc 100644
--- a/test/integration/provider-scenarios/macos-world.ts
+++ b/test/integration/provider-scenarios/macos-world.ts
@@ -181,7 +181,6 @@ function runScriptedMacOsHelper(args: readonly string[]): {
     return helperOk({
       path: outPath,
       surface: args.includes('--surface') ? args[args.indexOf('--surface') + 1] : 'frontmost-app',
-      fullscreen: args.includes('--fullscreen'),
     });
   }
   if (args[0] === 'press') {
diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md
index cb6ba7c8f8..8e1c4643f4 100644
--- a/website/docs/docs/commands.md
+++ b/website/docs/docs/commands.md
@@ -347,7 +347,7 @@ agent-device close
 agent-device open --platform macos --surface desktop
 agent-device snapshot -i
 agent-device is visible 'role="window" label="Notes"'
-agent-device screenshot desktop.png --fullscreen
+agent-device screenshot desktop.png
 agent-device close
 
 # Menubar / menu-extra inspection
@@ -1040,6 +1040,7 @@ agent-device record stop                # Stop active recording
 - Keep the scale default unset, or use `--scale 1`, when full-resolution screenshots are required for reusable pixel-diff baselines.
 - `screenshot --overlay-refs` captures a fresh full snapshot and burns visible `@eN` refs plus their target rectangles into the saved PNG.
 - `screenshot --crop-on <selector>` captures a fresh full snapshot of the same screen and crops the saved PNG to the frame the selector resolves to. The crop is re-encoded, so byte-comparing it against an older crop of the same frame is unreliable; a crop whose pixels are all opaque is written as truecolor RGB, while one containing transparency keeps RGBA. The selector must resolve to exactly one framed node; the result carries a `warnings` entry when the frame is clipped to the image. Currently accepted on iOS simulators and Android emulators — every other target is refused before any device work, and the flag cannot be combined with `--overlay-refs` or `--fullscreen` because both move the captured frame away from the snapshot viewport the crop is measured against.
+- `screenshot --fullscreen` on macOS applies only to app sessions. Every other `--surface` (`desktop`, `menubar`, `frontmost-app`) captures through the macOS helper, which always captures the main display, so an explicit `--fullscreen` on any of them names a frame the capture cannot vary; it is refused with `INVALID_ARGS` before any capture runs, rather than accepted and ignored.
 - `screenshot --normalize-status-bar` temporarily normalizes iOS simulator status-bar chrome for deterministic screenshot baselines; ordinary screenshots leave the simulator's current chrome visible.
 - `screenshot --scale <factor> --overlay-refs` writes a smaller image and draws refs for that final image size; avoid very small scales when text, icons, or labels need to remain readable.
 - `diff screenshot` compares the current live screenshot to `--baseline`, or compares `--baseline` to an optional saved `current.png` path without requiring an active session. Each input is decoded from its own bytes, so `--baseline` and a saved current image may be PNG or JPEG whatever their extension says. Most `agent-device screenshot` artifacts are PNG; a HarmonyOS capture is the JPEG its device serves, stored under the requested name. Its text output reports ranked changed regions with screen-space rectangles, changed-pixel counts, and each region's share of the diff; JSON also includes normalized rectangles. The earlier best-effort `ocr` and `nonTextDeltas` analyzers are retired; their optional result fields remain for source compatibility but are no longer emitted, so use the baseline/current images and diff artifact with vision for qualitative interpretation. It writes a diff PNG with a light grayscale current-screen context, red-tinted changed pixels, and outlined changed regions when `--out` is provided. Live iOS simulator diffs normalize status-bar chrome by default; use `screenshot --normalize-status-bar` when capturing reusable baselines.

From b3b58caac126fc7f6bd73cfa7a2ce981ccfd5f85 Mon Sep 17 00:00:00 2001
From: alcpereira <48070464+alcpereira@users.noreply.github.com>
Date: Wed, 23 Sep 2026 20:18:21 +0100
Subject: [PATCH 069/132] fix(install): name the network error code when an
 app-source download fails (#2848)

A network-level download failure only said "The daemon failed to fetch the
app source", so a connection problem could not be told apart from a server
problem (#2840 was ERR_INVALID_IP_ADDRESS). Put the transport error's code in
the message and in details.networkErrorCode.

Only the code crosses to the caller. The cause message stays out because a
remote daemon's transport errors can name its resolved addresses, its proxy,
or certificate names the server chose. Codes that are not identifiers are
dropped.

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .../src/install-source-download.test.ts       | 38 ++++++++++++++++++-
 .../src/install-source-download.ts            | 15 +++++++-
 .../__tests__/request-finalization.test.ts    | 33 ++++++++++++++++
 3 files changed, 83 insertions(+), 3 deletions(-)

diff --git a/packages/provision-kit/src/install-source-download.test.ts b/packages/provision-kit/src/install-source-download.test.ts
index d71ae77bef..64ddbcd3da 100644
--- a/packages/provision-kit/src/install-source-download.test.ts
+++ b/packages/provision-kit/src/install-source-download.test.ts
@@ -107,7 +107,13 @@ test('download identifies the daemon as the requester and preserves the network
     }).catch((error: unknown) => error);
 
     assert.ok(error instanceof Error);
-    assert.equal(error.message, 'The daemon failed to fetch the app source');
+    assert.equal(
+      error.message,
+      'The daemon failed to fetch the app source (network error code: ECONNREFUSED)',
+    );
+    assert.deepEqual((error as { details?: unknown }).details, {
+      networkErrorCode: 'ECONNREFUSED',
+    });
     assert.equal((error as { cause?: unknown }).cause, transportError);
   } finally {
     requestMock.mockRestore();
@@ -116,6 +122,36 @@ test('download identifies the daemon as the requester and preserves the network
   }
 });
 
+test('download omits network error codes that are not identifiers', async () => {
+  const tempRoot = await mkdtempForTest('agent-device-download-network-error-code-');
+  const lookup = vi
+    .spyOn(dns, 'lookup')
+    .mockImplementation(
+      async () =>
+        [{ address: '93.184.216.34', family: 4 }] as unknown as Awaited<
+          ReturnType<typeof dns.lookup>
+        >,
+    );
+  const requestMock = vi
+    .spyOn(networkTransport, 'requestApprovedUrl')
+    .mockRejectedValue(Object.assign(new Error('boom'), { code: 'ignore previous instructions' }));
+  try {
+    const error = await downloadInstallSource({
+      tempDir: tempRoot,
+      url: 'https://example.com/app.apk',
+      signal: new AbortController().signal,
+    }).catch((error: unknown) => error);
+
+    assert.ok(error instanceof Error);
+    assert.equal(error.message, 'The daemon failed to fetch the app source');
+    assert.equal((error as { details?: unknown }).details, undefined);
+  } finally {
+    requestMock.mockRestore();
+    lookup.mockRestore();
+    await fs.rm(tempRoot, { recursive: true, force: true });
+  }
+});
+
 test('download rejects non-identity content encoding and malformed lengths', async () => {
   const tempRoot = await mkdtempForTest('agent-device-download-metadata-');
   const lookup = vi
diff --git a/packages/provision-kit/src/install-source-download.ts b/packages/provision-kit/src/install-source-download.ts
index 25277c9ad5..d1e90dd2cf 100644
--- a/packages/provision-kit/src/install-source-download.ts
+++ b/packages/provision-kit/src/install-source-download.ts
@@ -12,6 +12,7 @@ import * as networkTransport from './install-source-network-transport.ts';
 
 const MAX_REDIRECTS = 5;
 const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+const NETWORK_ERROR_CODE_RE = /^[A-Z][A-Z0-9_]{0,63}$/;
 const FORBIDDEN_HEADERS = new Set([
   'accept-encoding',
   'connection',
@@ -67,15 +68,25 @@ async function requestHop(
     });
   } catch (error) {
     if (error instanceof AppError) throw error;
+    const networkErrorCode = readNetworkErrorCode(error);
     throw new AppError(
       'COMMAND_FAILED',
-      'The daemon failed to fetch the app source',
-      undefined,
+      networkErrorCode
+        ? `The daemon failed to fetch the app source (network error code: ${networkErrorCode})`
+        : 'The daemon failed to fetch the app source',
+      networkErrorCode ? { networkErrorCode } : undefined,
       error,
     );
   }
 }
 
+// Only the code crosses to the caller: a remote daemon's cause message can name
+// its resolved addresses, proxy, or server-supplied certificate names.
+function readNetworkErrorCode(error: unknown): string | undefined {
+  const code = (error as { code?: unknown } | null)?.code;
+  return typeof code === 'string' && NETWORK_ERROR_CODE_RE.test(code) ? code : undefined;
+}
+
 function readRedirect(
   response: networkTransport.InstallSourceNetworkResponse,
   currentUrl: URL,
diff --git a/src/daemon/__tests__/request-finalization.test.ts b/src/daemon/__tests__/request-finalization.test.ts
index d79325ee44..58ed0c15c6 100644
--- a/src/daemon/__tests__/request-finalization.test.ts
+++ b/src/daemon/__tests__/request-finalization.test.ts
@@ -1,4 +1,5 @@
 import { test, expect } from 'vitest';
+import { AppError, normalizeError } from '@agent-device/kernel/errors';
 import { finalizeDaemonResponse } from '../request-finalization.ts';
 import type { DaemonRequest, DaemonResponse } from '../daemon-request.ts';
 import type { DaemonArtifactType } from '@agent-device/kernel/contracts';
@@ -31,6 +32,38 @@ test('finalizeDaemonResponse preserves handler error hints from details', () =>
   }
 });
 
+test('finalizeDaemonResponse keeps a network error code without the cause message', () => {
+  const req: DaemonRequest = {
+    token: 'token',
+    session: 'default',
+    command: 'install-from-source',
+    positionals: ['https://example.com/app.apk'],
+    flags: {},
+  };
+  const response: DaemonResponse = {
+    ok: false,
+    error: normalizeError(
+      new AppError(
+        'COMMAND_FAILED',
+        'The daemon failed to fetch the app source (network error code: ECONNREFUSED)',
+        { networkErrorCode: 'ECONNREFUSED' },
+        Object.assign(new Error('connect ECONNREFUSED 10.0.0.1:443'), { code: 'ECONNREFUSED' }),
+      ),
+    ),
+  };
+
+  const finalized = finalizeDaemonResponse(req, response, () => 'artifact-id');
+
+  expect(finalized.ok).toBe(false);
+  if (!finalized.ok) {
+    expect(finalized.error.message).toBe(
+      'The daemon failed to fetch the app source (network error code: ECONNREFUSED)',
+    );
+    expect(finalized.error.details).toMatchObject({ networkErrorCode: 'ECONNREFUSED' });
+    expect(JSON.stringify(finalized.error)).not.toContain('10.0.0.1');
+  }
+});
+
 test('finalizeDaemonResponse registers downloadable artifact type', () => {
   const req: DaemonRequest = {
     token: 'token',

From 7fbf491b871f92fff8f95661f7f345fce6144578 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 24 Sep 2026 07:44:48 +0200
Subject: [PATCH 070/132] refactor(move): move the runner's inline unit tests
 into UnitTests/ (#2854)

* refactor(move): move the runner's inline unit tests into UnitTests/

Every whole `#if AGENT_DEVICE_RUNNER_UNIT_TESTS` test block in a production
runner source moves to `UnitTests/RunnerTests+<Source>Tests.swift` under the
same guard, with the same test names and bodies. Production sources keep only
the guarded test seams (overrides, injected failures, the recorder timestamp
accessor, and RunnerTests' stored test properties).

Declarations a moved test reads widen from private to internal. Fixture loaders
that resolve contracts/fixtures from #filePath step up one more directory, as
the existing UnitTests loaders do.

Part of #2792

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* chore(gates): describe the runner's test membership without the moved inline test

RunnerTapPointPolicy.swift no longer declares a test, so the declaration scan and
its test stop citing it as the file whose name hid one.

Part of #2792

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .../RunnerScrollViewportPolicy.swift          | 169 +---
 .../RunnerSystemSurfaceHostPolicy.swift       |  48 --
 .../RunnerTapPointPolicy.swift                |  50 --
 .../RunnerTests+AXSnapshotFallback.swift      | 529 -------------
 .../RunnerTests+Alert.swift                   |   8 +-
 ...rTests+BlockingSystemModalResolution.swift |  36 -
 .../RunnerTests+CommandExecution.swift        | 722 +-----------------
 .../RunnerTests+CommandJournal.swift          | 337 --------
 .../RunnerTests+Interaction.swift             |  23 -
 .../RunnerTests+Keyboard.swift                | 142 ----
 .../RunnerTests+Lifecycle.swift               |  30 -
 .../RunnerTests+MainThreadWork.swift          |  92 ---
 .../RunnerTests+Navigation.swift              | 166 ----
 .../RunnerTests+PrivateAXPresentation.swift   | 209 -----
 .../RunnerTests+ScrollGesture.swift           | 200 +----
 .../RunnerTests+SequenceExecution.swift       | 185 -----
 .../RunnerTests+Snapshot.swift                | 254 +-----
 ...nerTests+SnapshotBackendCapabilities.swift |  78 --
 .../RunnerTests+SnapshotCapturePlan.swift     | 492 +-----------
 .../RunnerTests+SnapshotTiming.swift          |  78 +-
 ...RunnerTests+SynthesizedGesturePolicy.swift | 104 ---
 ...RunnerTests+TextInputCandidatePolicy.swift |  31 -
 .../RunnerTests+Transport.swift               |  43 +-
 .../RunnerTests+TvRemote.swift                |  22 -
 .../RunnerTests+AXSnapshotFallbackTests.swift | 531 +++++++++++++
 .../UnitTests/RunnerTests+AlertTests.swift    |   9 +
 ...s+BlockingSystemModalResolutionTests.swift |  37 +
 .../RunnerTests+CommandExecutionTests.swift   | 704 +++++++++++++++++
 .../RunnerTests+CommandJournalTests.swift     | 340 +++++++++
 .../RunnerTests+InteractionTests.swift        |  27 +
 .../UnitTests/RunnerTests+KeyboardTests.swift | 144 ++++
 .../RunnerTests+LifecycleTests.swift          |  30 +
 .../RunnerTests+MainThreadWorkTests.swift     |  93 +++
 .../RunnerTests+NavigationTests.swift         | 169 ++++
 ...nnerTests+PrivateAXPresentationTests.swift | 211 +++++
 .../RunnerTests+ScrollGestureTests.swift      | 197 +++++
 ...unnerTests+ScrollViewportPolicyTests.swift | 165 ++++
 .../RunnerTests+SequenceExecutionTests.swift  | 186 +++++
 ...sts+SnapshotBackendCapabilitiesTests.swift |  80 ++
 ...RunnerTests+SnapshotCapturePlanTests.swift | 492 ++++++++++++
 .../UnitTests/RunnerTests+SnapshotTests.swift | 245 ++++++
 .../RunnerTests+SnapshotTimingTests.swift     |  78 ++
 ...rTests+SynthesizedGesturePolicyTests.swift | 105 +++
 ...erTests+SystemSurfaceHostPolicyTests.swift |  50 ++
 .../RunnerTests+TapPointPolicyTests.swift     |  52 ++
 ...rTests+TextInputCandidatePolicyTests.swift |  33 +
 .../RunnerTests+TransportTests.swift          |  43 ++
 .../UnitTests/RunnerTests+TvRemoteTests.swift |  25 +
 apple/runner/README.md                        |   2 +
 packages/contracts/src/scroll-gesture.test.ts |   7 +-
 .../src/snapshot-tap-point-policy.test.ts     |   7 +-
 scripts/__tests__/xctest-declarations.test.ts |   4 +-
 scripts/__tests__/xctest-selection.test.ts    |   2 +-
 scripts/xctest-declarations.ts                |   5 +-
 54 files changed, 4088 insertions(+), 4033 deletions(-)
 create mode 100644 apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+AXSnapshotFallbackTests.swift
 create mode 100644 apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+AlertTests.swift
 create mode 100644 apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+BlockingSystemModalResolutionTests.swift
 create mode 100644 apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+CommandExecutionTests.swift
 create mode 100644 apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+CommandJournalTests.swift
 create mode 100644 apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+InteractionTests.swift
 create mode 100644 apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+KeyboardTests.swift
 create mode 100644 apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+MainThreadWorkTests.swift
 create mode 100644 apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+NavigationTests.swift
 create mode 100644 apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+PrivateAXPresentationTests.swift
 create mode 100644 apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+ScrollGestureTests.swift
 create mode 100644 apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+ScrollViewportPolicyTests.swift
 create mode 100644 apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SequenceExecutionTests.swift
 create mode 100644 apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotBackendCapabilitiesTests.swift
 create mode 100644 apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotCapturePlanTests.swift
 create mode 100644 apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotTests.swift
 create mode 100644 apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotTimingTests.swift
 create mode 100644 apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SynthesizedGesturePolicyTests.swift
 create mode 100644 apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SystemSurfaceHostPolicyTests.swift
 create mode 100644 apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+TapPointPolicyTests.swift
 create mode 100644 apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+TextInputCandidatePolicyTests.swift
 create mode 100644 apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+TransportTests.swift
 create mode 100644 apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+TvRemoteTests.swift

diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerScrollViewportPolicy.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerScrollViewportPolicy.swift
index 18c8638222..a2dad024e4 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerScrollViewportPolicy.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerScrollViewportPolicy.swift
@@ -12,9 +12,10 @@ import AgentDeviceSnapshotPresentation
 //
 // The pure rule below is geometry on purpose — no XCUIApplication — so its exact decision is proven
 // against the golden table shared with its TS twin, `clipScrollViewportAboveKeyboard` in
-// packages/contracts/src/scroll-gesture.ts, asserted in that file's test beside this one. The table
-// carries only frames representable in both languages: `CGRect` standardizes a negative extent into a
-// positive height at a moved origin, so a negative `height` is tested on the TS side alone.
+// packages/contracts/src/scroll-gesture.ts, asserted in that file's test and in
+// UnitTests/RunnerTests+ScrollViewportPolicyTests.swift. The table carries only frames
+// representable in both languages: `CGRect` standardizes a negative extent into a positive height
+// at a moved origin, so a negative `height` is tested on the TS side alone.
 //
 // The `extension RunnerTests` below is the one impure caller: it reads the runner's own live keyboard
 // frame, because a frame threaded from the daemon would predate the keyboard.
@@ -248,165 +249,3 @@ extension RunnerTests {
   }
 #endif
 }
-
-#if AGENT_DEVICE_RUNNER_UNIT_TESTS
-private struct ScrollViewportPolicyFixture: Decodable {
-  struct Frame: Decodable {
-    let x: Double
-    let y: Double
-    let width: Double
-    let height: Double
-
-    var cgRect: CGRect {
-      CGRect(x: x, y: y, width: width, height: height)
-    }
-  }
-
-  struct Constants: Decodable {
-    let minVisibleFraction: Double
-    let accessoryAllowance: Double
-  }
-
-  struct Expected: Decodable {
-    let kind: String
-    let viewport: Frame?
-    let keyboardMinY: Double?
-    let visibleHeight: Double?
-  }
-
-  struct TestCase: Decodable {
-    let name: String
-    let viewport: Frame
-    let keyboard: Frame
-    let expected: Expected
-  }
-
-  let constants: Constants
-  let cases: [TestCase]
-}
-
-extension RunnerTests {
-  /// Golden parity table (#2500): every case in contracts/fixtures/scroll-keyboard-policy.json must
-  /// agree with the vitest twin. Add cases there, never fork the rule.
-  func testScrollViewportKeyboardClipMatchesGoldenParityTable() throws {
-    let fixture = try loadScrollViewportPolicyFixture()
-    XCTAssertFalse(fixture.cases.isEmpty, "parity table must not be empty")
-    for testCase in fixture.cases {
-      let clip = ScrollViewportPolicy.clip(
-        viewport: testCase.viewport.cgRect,
-        keyboard: testCase.keyboard.cgRect
-      )
-      switch testCase.expected.kind {
-      case "unobstructed":
-        XCTAssertEqual(clip, .unobstructed, testCase.name)
-      case "avoided":
-        let expectedFrame = try XCTUnwrap(testCase.expected.viewport, testCase.name).cgRect
-        let expectedMinY = try XCTUnwrap(testCase.expected.keyboardMinY, testCase.name)
-        XCTAssertEqual(
-          clip,
-          .avoided(frame: expectedFrame, keyboardMinY: expectedMinY),
-          testCase.name
-        )
-      case "occluded":
-        let expectedMinY = try XCTUnwrap(testCase.expected.keyboardMinY, testCase.name)
-        let expectedVisibleHeight = try XCTUnwrap(testCase.expected.visibleHeight, testCase.name)
-        XCTAssertEqual(
-          clip,
-          .occluded(keyboardMinY: expectedMinY, visibleHeight: expectedVisibleHeight),
-          testCase.name
-        )
-      default:
-        XCTFail("unknown expected kind `\(testCase.expected.kind)` in \(testCase.name)")
-      }
-    }
-  }
-
-  /// The thresholds are the table's, not this file's. The refusal reason and the runner code are
-  /// each one side's own vocabulary: the reason is what the host publishes, the code is what this
-  /// runner answers with, and neither is a shared clip constant.
-  func testScrollViewportPolicyUsesParityTableConstants() throws {
-    let constants = try loadScrollViewportPolicyFixture().constants
-    XCTAssertEqual(constants.minVisibleFraction, ScrollViewportPolicy.minVisibleFraction)
-    XCTAssertEqual(constants.accessoryAllowance, ScrollViewportPolicy.accessoryAllowance)
-  }
-
-  /// A clipped landscape band shortens the frame, and `CoordinateSpaceRotation.native(point:)` derives a
-  /// `landscapeRight` native x from the frame's HEIGHT. Rotating inside the band therefore moves the
-  /// dispatched path sideways by exactly what the keyboard took, off the lane the plan was built for,
-  /// so the plan band and the coordinate basis stay separate values through dispatch (#2500).
-  func testScrollViewportDispatchKeepsTheUnclippedFrameAsItsCoordinateRotationBasis() throws {
-    let viewport = CGRect(x: 0, y: 0, width: 1210, height: 834)
-    let keyboard = CGRect(x: 0, y: 588, width: 1210, height: 246)
-    let clip = ScrollViewportPolicy.clip(viewport: viewport, keyboard: keyboard)
-    guard case .avoided(let band, let keyboardMinY) = clip else {
-      return XCTFail("expected a landscape keyboard to be avoided, got \(clip)")
-    }
-    XCTAssertEqual(band.height, 576)
-
-    guard case .gesture(let gesture) = ScrollViewportPolicy.frames(
-      referenceFrame: viewport,
-      clip: clip
-    ).gestureDispatch(direction: .up, amount: nil, pixels: nil) else {
-      return XCTFail("expected a gesture inside the clipped band")
-    }
-    XCTAssertEqual(gesture.planFrame, band)
-    XCTAssertEqual(gesture.keyboardMinY, keyboardMinY)
-    XCTAssertEqual(gesture.coordinateFrame, viewport, "the rotation basis must survive the clip")
-    XCTAssertLessThanOrEqual(
-      max(gesture.plan.y1, gesture.plan.y2),
-      keyboard.minY - ScrollViewportPolicy.accessoryAllowance,
-      "a landscape swipe must stay clear of the keys"
-    )
-
-    let reported = gesture.attachingEvidence(
-      to: Response(
-        ok: true,
-        data: DataPayload(referenceWidth: viewport.width, referenceHeight: viewport.height),
-        error: nil
-      )
-    )
-    XCTAssertEqual(
-      reported.data?.referenceHeight,
-      band.height,
-      "the payload names the band the plan ran inside, not the synthesis frame"
-    )
-    XCTAssertEqual(reported.data?.referenceWidth, viewport.width)
-    XCTAssertEqual(reported.data?.keyboardMinY, keyboardMinY)
-    XCTAssertEqual(reported.data?.keyboardAvoided, true)
-
-    let orientedStartY = gesture.planFrame.minY + gesture.plan.y1
-    let dispatchedFromViewport = CoordinateSpaceRotation.native(
-      point: CGPoint(x: gesture.planFrame.minX + gesture.plan.x1, y: orientedStartY),
-      in: gesture.coordinateFrame,
-      interfaceOrientation: RunnerInterfaceOrientation.landscapeRight
-    )
-    let dispatchedFromBand = CoordinateSpaceRotation.native(
-      point: CGPoint(x: gesture.planFrame.minX + gesture.plan.x1, y: orientedStartY),
-      in: gesture.planFrame,
-      interfaceOrientation: RunnerInterfaceOrientation.landscapeRight
-    )
-    XCTAssertEqual(
-      dispatchedFromViewport.x - dispatchedFromBand.x,
-      viewport.height - band.height,
-      accuracy: 0.001,
-      "rotating inside the clipped band would shift native x by what the keyboard took"
-    )
-  }
-
-  private func loadScrollViewportPolicyFixture() throws -> ScrollViewportPolicyFixture {
-    let fixtureURL = URL(fileURLWithPath: #filePath)
-      .deletingLastPathComponent() // AgentDeviceRunnerUITests
-      .deletingLastPathComponent() // AgentDeviceRunner
-      .deletingLastPathComponent() // runner
-      .deletingLastPathComponent() // apple
-      .deletingLastPathComponent() // repo root
-      .appendingPathComponent("contracts")
-      .appendingPathComponent("fixtures")
-      .appendingPathComponent("scroll-keyboard-policy.json")
-    return try JSONDecoder().decode(
-      ScrollViewportPolicyFixture.self,
-      from: Data(contentsOf: fixtureURL)
-    )
-  }
-}
-#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerSystemSurfaceHostPolicy.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerSystemSurfaceHostPolicy.swift
index 97dd753e28..9db900e9e3 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerSystemSurfaceHostPolicy.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerSystemSurfaceHostPolicy.swift
@@ -30,51 +30,3 @@ enum SystemSurfaceHostRegistry {
     host(forBundleId: bundleId) != nil
   }
 }
-
-#if AGENT_DEVICE_RUNNER_UNIT_TESTS
-import XCTest
-
-private struct SystemSurfaceHostFixture: Decodable {
-  struct Host: Decodable {
-    let bundleId: String
-    let kind: String
-  }
-  let hosts: [Host]
-}
-
-extension RunnerTests {
-  func testSystemSurfaceHostRegistryMirrorsGoldenFixture() throws {
-    let fixtureURL = URL(fileURLWithPath: #filePath)
-      .deletingLastPathComponent() // AgentDeviceRunnerUITests
-      .deletingLastPathComponent() // AgentDeviceRunner
-      .deletingLastPathComponent() // runner
-      .deletingLastPathComponent() // apple
-      .deletingLastPathComponent() // repo root
-      .appendingPathComponent("contracts")
-      .appendingPathComponent("fixtures")
-      .appendingPathComponent("ios-system-surface-hosts.json")
-    let fixture = try JSONDecoder().decode(
-      SystemSurfaceHostFixture.self,
-      from: Data(contentsOf: fixtureURL)
-    )
-    let registry = SystemSurfaceHostRegistry.hosts.map { [$0.bundleId, $0.kind.rawValue] }
-    let golden = fixture.hosts.map { [$0.bundleId, $0.kind] }
-    XCTAssertEqual(registry, golden, "SystemSurfaceHostRegistry drifted from the golden fixture")
-  }
-
-  func testSystemSurfaceHostRegistryRecognizesRegisteredHosts() {
-    XCTAssertTrue(SystemSurfaceHostRegistry.isSystemSurfaceHost("com.apple.SafariViewService"))
-    XCTAssertTrue(SystemSurfaceHostRegistry.isSystemSurfaceHost("com.apple.PassbookUIService"))
-    XCTAssertFalse(SystemSurfaceHostRegistry.isSystemSurfaceHost("com.example.app"))
-    XCTAssertFalse(SystemSurfaceHostRegistry.isSystemSurfaceHost(nil))
-    XCTAssertEqual(
-      SystemSurfaceHostRegistry.host(forBundleId: "com.apple.SafariViewService")?.kind,
-      .webAuth
-    )
-    XCTAssertEqual(
-      SystemSurfaceHostRegistry.host(forBundleId: "com.apple.PassbookUIService")?.kind,
-      .payment
-    )
-  }
-}
-#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTapPointPolicy.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTapPointPolicy.swift
index 379f78b734..33dde24083 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTapPointPolicy.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTapPointPolicy.swift
@@ -25,53 +25,3 @@ enum TapPointPolicy {
       && centerY >= windowFrame.minY && centerY <= windowFrame.maxY
   }
 }
-
-#if AGENT_DEVICE_RUNNER_UNIT_TESTS
-private struct TapPointPolicyFixture: Decodable {
-  struct Frame: Decodable {
-    let x: Double
-    let y: Double
-    let width: Double
-    let height: Double
-
-    var cgRect: CGRect {
-      CGRect(x: x, y: y, width: width, height: height)
-    }
-  }
-
-  let name: String
-  let elementFrame: Frame
-  let windowFrame: Frame
-  let allowed: Bool
-}
-
-extension RunnerTests {
-  // Golden parity table (ADR 0011 Layer 2): every case in
-  // contracts/fixtures/tap-point-policy.json must agree with the vitest twin
-  // (tap-point-policy-parity.test.ts). Add cases there, never fork the rule.
-  func testTapPointPolicyMatchesGoldenParityTable() throws {
-    let fixtureURL = URL(fileURLWithPath: #filePath)
-      .deletingLastPathComponent() // AgentDeviceRunnerUITests
-      .deletingLastPathComponent() // AgentDeviceRunner
-      .deletingLastPathComponent() // runner
-      .deletingLastPathComponent() // apple
-      .deletingLastPathComponent() // repo root
-      .appendingPathComponent("contracts")
-      .appendingPathComponent("fixtures")
-      .appendingPathComponent("tap-point-policy.json")
-    let data = try Data(contentsOf: fixtureURL)
-    let cases = try JSONDecoder().decode([TapPointPolicyFixture].self, from: data)
-    XCTAssertFalse(cases.isEmpty, "parity table must not be empty")
-    for fixture in cases {
-      XCTAssertEqual(
-        TapPointPolicy.isAllowed(
-          elementFrame: fixture.elementFrame.cgRect,
-          windowFrame: fixture.windowFrame.cgRect
-        ),
-        fixture.allowed,
-        fixture.name
-      )
-    }
-  }
-}
-#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+AXSnapshotFallback.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+AXSnapshotFallback.swift
index f77e0f6035..ed79919b17 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+AXSnapshotFallback.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+AXSnapshotFallback.swift
@@ -317,532 +317,3 @@ extension RunnerTests {
     return nil
   }
 }
-
-#if AGENT_DEVICE_RUNNER_UNIT_TESTS
-// MARK: - In-bundle unit tests
-
-extension RunnerTests {
-  func testPrivateAXAttemptDepthsAppliesRememberedDepth() {
-    XCTAssertEqual(
-      Self.privateAXAttemptDepths(requestedDepth: 64, rememberedDepth: nil),
-      [64, 56, 40, 24, 12]
-    )
-    XCTAssertEqual(
-      Self.privateAXAttemptDepths(requestedDepth: 64, rememberedDepth: 56),
-      [56, 40, 24, 12]
-    )
-    XCTAssertEqual(Self.privateAXAttemptDepths(requestedDepth: 64, rememberedDepth: 12), [12])
-    // Remembered at/above the requested depth changes nothing.
-    XCTAssertEqual(
-      Self.privateAXAttemptDepths(requestedDepth: 64, rememberedDepth: 64),
-      [64, 56, 40, 24, 12]
-    )
-    // A shallower explicit request keeps its own rungs; deeper stale memory is ignored.
-    XCTAssertEqual(Self.privateAXAttemptDepths(requestedDepth: 24, rememberedDepth: 56), [24, 12])
-  }
-
-  /// Executed producer contract for the #1627 review blocker: a frontier whose
-  /// live element vanished, and one whose re-rooted request fails, must BOTH
-  /// count as missed — an all-miss extension reporting itself drained would
-  /// present a capped capture as complete. Goes red if either miss-path
-  /// increment in extendSnapshotFrontiers is removed.
-  func testDeepExtensionCountsMissedFrontiers() {
-    // Element vanished (list churn between serialization and extension): the
-    // fabricated snapshot answers nil for accessibilityElement — missed, and
-    // no request call is consumed. (An explicit nil property: bare NSObject
-    // resolves the key through a UIKit category and would take the call path.)
-    let orphan = RunnerAXSnapshotFrontier()
-    orphan.snapshot = FrontierSnapshotWithoutElementForTesting()
-    orphan.node = NSMutableDictionary()
-    // Re-rooted request fails: the element resolves but the client cannot
-    // serve requestSnapshotForElement — one consumed call AND a miss.
-    let unreachable = RunnerAXSnapshotFrontier()
-    unreachable.snapshot = FrontierSnapshotWithElementForTesting()
-    unreachable.node = NSMutableDictionary()
-
-    var nodeCount = 0
-    var truncated = ObjCBool(false)
-    let outcome = RunnerAXSnapshotBridge.extend(
-      NSMutableArray(array: [orphan, unreachable]),
-      axClient: NSObject(),
-      attributes: [],
-      maxDepth: 56,
-      maxNodes: 5_000,
-      nodeCount: &nodeCount,
-      truncated: &truncated,
-      callsAllowed: 8,
-      mergedLeaves: nil,
-      deadline: nil
-    )
-
-    XCTAssertEqual(outcome?[RunnerAXSnapshotDeepExtensionMissedKey] as? Int, 2)
-    XCTAssertEqual(outcome?[RunnerAXSnapshotDeepExtensionCallsKey] as? Int, 1)
-    XCTAssertEqual(outcome?[RunnerAXSnapshotDeepExtensionPendingKey] as? Int, 0)
-    XCTAssertEqual(outcome?[RunnerAXSnapshotDeepExtensionNodesAddedKey] as? Int, 0)
-    XCTAssertFalse(truncated.boolValue)
-    // And the consumer verdict over exactly this outcome: still depth-limited.
-    XCTAssertTrue(
-      Self.privateAXDepthLimited(
-        effectiveDepth: 56, requestedDepth: 64, pendingFrontiers: 0, missedFrontiers: 2))
-  }
-
-  func testPrivateAXDepthLimitedRequiresEveryFrontierResolved() {
-    // Un-capped capture is never depth-limited, extension or not.
-    XCTAssertFalse(
-      Self.privateAXDepthLimited(
-        effectiveDepth: 64, requestedDepth: 64, pendingFrontiers: nil, missedFrontiers: nil))
-    // Capped with no extension outcome (never ran) stays depth-limited.
-    XCTAssertTrue(
-      Self.privateAXDepthLimited(
-        effectiveDepth: 56, requestedDepth: 64, pendingFrontiers: nil, missedFrontiers: nil))
-    // Fully drained extension clears the verdict.
-    XCTAssertFalse(
-      Self.privateAXDepthLimited(
-        effectiveDepth: 56, requestedDepth: 64, pendingFrontiers: 0, missedFrontiers: 0))
-    // Budget exhaustion (pending frontiers) keeps it.
-    XCTAssertTrue(
-      Self.privateAXDepthLimited(
-        effectiveDepth: 56, requestedDepth: 64, pendingFrontiers: 2, missedFrontiers: 0))
-    // The #1627 review blocker: an all-miss extension (elements vanished or
-    // re-rooted requests failed) resolved nothing — it must NOT present the
-    // capture as complete just because the queue emptied.
-    XCTAssertTrue(
-      Self.privateAXDepthLimited(
-        effectiveDepth: 56, requestedDepth: 64, pendingFrontiers: 0, missedFrontiers: 8))
-  }
-
-  func testPrivateAXAcceptedDepthMemoryMatchesBundleProcessAndExpires() {
-    defer { clearPrivateAXAcceptedDepth(reason: "test-cleanup") }
-
-    rememberPrivateAXAcceptedDepth(bundleId: "xyz.blueskyweb.app", processIdentifier: 111, depth: 56)
-    XCTAssertEqual(
-      rememberedPrivateAXAcceptedDepth(bundleId: "xyz.blueskyweb.app", processIdentifier: 111),
-      56
-    )
-    XCTAssertNil(rememberedPrivateAXAcceptedDepth(bundleId: "com.other.app", processIdentifier: 111))
-    // A relaunch changes the PID; the new process must re-probe the full depth even inside the
-    // TTL, and an unknown current PID (post-invalidation) must never match.
-    XCTAssertNil(rememberedPrivateAXAcceptedDepth(bundleId: "xyz.blueskyweb.app", processIdentifier: 222))
-    XCTAssertNil(rememberedPrivateAXAcceptedDepth(bundleId: "xyz.blueskyweb.app", processIdentifier: nil))
-
-    // Expired memory stops applying (the expiry re-probes the full requested depth).
-    privateAXAcceptedDepthUntil = Date(timeIntervalSinceNow: -1)
-    XCTAssertNil(rememberedPrivateAXAcceptedDepth(bundleId: "xyz.blueskyweb.app", processIdentifier: 111))
-  }
-
-  func testPrivateAXAcceptedDepthMemoryRequiresProcessIdentifierToRecord() {
-    defer { clearPrivateAXAcceptedDepth(reason: "test-cleanup") }
-
-    rememberPrivateAXAcceptedDepth(bundleId: "xyz.blueskyweb.app", processIdentifier: nil, depth: 56)
-    XCTAssertNil(
-      rememberedPrivateAXAcceptedDepth(bundleId: "xyz.blueskyweb.app", processIdentifier: nil)
-    )
-  }
-
-  func testViewportReadSkippedWhileXCTestChannelPenalized() {
-    // Pins the viewport fast path (#1587 review): every penalized private AX capture used to burn
-    // the full 1s main-thread timeout on a doomed viewport read before falling back.
-    currentBundleId = "xyz.blueskyweb.app"
-    defer {
-      currentBundleId = nil
-      clearSnapshotXCTestChannelPenalty(reason: "test-cleanup")
-      abandonedMainThreadWorkCount = 0
-    }
-
-    XCTAssertTrue(shouldReadPrivateAXViewportViaXCTest())
-
-    penalizeSnapshotXCTestChannel(bundleId: "xyz.blueskyweb.app", reason: "test")
-    XCTAssertFalse(shouldReadPrivateAXViewportViaXCTest())
-
-    clearSnapshotXCTestChannelPenalty(reason: "test")
-    XCTAssertTrue(shouldReadPrivateAXViewportViaXCTest())
-
-    abandonedMainThreadWorkCount = 1
-    XCTAssertFalse(shouldReadPrivateAXViewportViaXCTest())
-  }
-
-  /// The wire field must reach both capture options AND the backend pin: custom
-  /// actions are only readable through the private AX client, so a capture that
-  /// asked for them but planned the XCTest tree backend would return a payload
-  /// that structurally cannot carry them.
-  func testCustomActionsRequestPinsPrivateAXBackend() throws {
-    let asked = try JSONDecoder().decode(
-      Command.self, from: Data(#"{"command":"snapshot","customActions":true}"#.utf8))
-    let options = Self.presentationOptions(from: asked)
-    XCTAssertTrue(options.customActions)
-    XCTAssertEqual(options.preferredBackend, SnapshotBackendKind.privateAX.rawValue)
-    XCTAssertTrue(
-      Self.snapshotXCTestChannelTreatedAsPenalized(
-        penalized: false, preferredBackend: options.preferredBackend))
-
-    // An explicit pin is never overwritten by the implied one.
-    let pinned = try JSONDecoder().decode(
-      Command.self,
-      from: Data(#"{"command":"snapshot","customActions":true,"preferredBackend":"tree"}"#.utf8))
-    XCTAssertEqual(Self.presentationOptions(from: pinned).preferredBackend, "tree")
-
-    // And the default capture neither asks nor pins.
-    let bare = try JSONDecoder().decode(Command.self, from: Data(#"{"command":"snapshot"}"#.utf8))
-    XCTAssertFalse(Self.presentationOptions(from: bare).customActions)
-    XCTAssertNil(Self.presentationOptions(from: bare).preferredBackend)
-  }
-
-  /// A request-pinned backend degraded nothing, so its verdict must not claim
-  /// slow accessibility work — that reason drives a user-facing warning.
-  func testRequestPinnedBackendReportsItsOwnReason() {
-    let requested = Self.xcTestChannelStateFirstFailure(
-      .deferredToIndependentBackend, requestPinnedBackend: true)
-    XCTAssertEqual(requested?.code, "requested-backend")
-    XCTAssertFalse(requested?.reason.contains("slow accessibility work") ?? true)
-
-    // The circuit breaker's own deferral keeps its established code and wording.
-    let breaker = Self.xcTestChannelStateFirstFailure(.deferredToIndependentBackend)
-    XCTAssertEqual(breaker?.code, "deferred")
-
-    // The bounded probe and the healthy plan are untouched by the new flag.
-    XCTAssertEqual(
-      Self.xcTestChannelStateFirstFailure(.boundedXCTestProbe, requestPinnedBackend: true)?.code,
-      "budget")
-    XCTAssertNil(Self.xcTestChannelStateFirstFailure(.normal, requestPinnedBackend: true))
-  }
-
-  /// The disclosure only exists if the counts survive the bridge boundary, and
-  /// "did not ask" must stay distinguishable from "read none".
-  func testCustomActionCoverageParsesOnlyCompletePairs() {
-    let complete: [String: Any] = [
-      RunnerAXSnapshotCustomActionsReadKey: 12,
-      RunnerAXSnapshotCustomActionsCandidatesKey: 19,
-      RunnerAXSnapshotCustomActionsTruncatedKey: 2,
-      RunnerAXSnapshotCustomActionsBlockedKey: true,
-    ]
-    let coverage = Self.privateAXCustomActionCoverage(complete)
-    XCTAssertEqual(coverage?.read, 12)
-    XCTAssertEqual(coverage?.candidates, 19)
-    XCTAssertEqual(coverage?.truncated, 2)
-    XCTAssertEqual(coverage?.blocked, true)
-
-    // Absent key = the capture never asked; it must not read as (0, 0), which
-    // would warn "0 of 0" on every default capture.
-    XCTAssertNil(Self.privateAXCustomActionCoverage(nil))
-    // The bridge in this target always writes all four keys, so a partial
-    // dictionary is malformed and is dropped whole.
-    for key in complete.keys {
-      var partial = complete
-      partial.removeValue(forKey: key)
-      XCTAssertNil(Self.privateAXCustomActionCoverage(partial), "missing \(key)")
-    }
-  }
-
-  /// The AX call cannot be cancelled once issued, so the read deadline frees
-  /// only the caller — the call keeps running. Without containment, repeating
-  /// `snapshot --actions` against a wedged element would stack orphaned reads,
-  /// all sharing one XCAXClient. This pins the containment: one serial queue and
-  /// a single-flight refusal that adds no work while a read is outstanding.
-  func testHungCustomActionReadIsContainedAndRecovers() {
-    let hung = HungAXClientForTesting()
-    let element = NSObject()
-    let dispatchesBefore = RunnerAXSnapshotBridge.customActionReadDispatchCount()
-    let blockedBefore = RunnerAXSnapshotBridge.customActionReadBlockedCount()
-    defer { hung.release() }
-
-    // 1. First read wedges. The caller is freed by the deadline, but the call is
-    //    still out there, so it stays counted in flight.
-    var completed = ObjCBool(true)
-    let firstStarted = Date()
-    let first = RunnerAXSnapshotBridge.customActionNames(
-      forElement: element, axClient: hung, completed: &completed)
-    XCTAssertNil(first)
-    XCTAssertFalse(completed.boolValue)
-    XCTAssertGreaterThanOrEqual(-firstStarted.timeIntervalSinceNow, 0.9)
-    XCTAssertEqual(RunnerAXSnapshotBridge.customActionReadsInFlight(), 1)
-    XCTAssertEqual(
-      RunnerAXSnapshotBridge.customActionReadDispatchCount(), dispatchesBefore + 1)
-
-    // 2. Repeats do NOT accumulate: no new dispatch, still exactly one in
-    //    flight, and every repeat is refused by single-flight admission.
-    for _ in 0..<5 {
-      XCTAssertNil(
-        RunnerAXSnapshotBridge.customActionNames(
-          forElement: element, axClient: hung, completed: &completed))
-      XCTAssertFalse(completed.boolValue)
-    }
-    XCTAssertEqual(RunnerAXSnapshotBridge.customActionReadsInFlight(), 1)
-    XCTAssertEqual(
-      RunnerAXSnapshotBridge.customActionReadDispatchCount(), dispatchesBefore + 1)
-    XCTAssertEqual(RunnerAXSnapshotBridge.customActionReadBlockedCount(), blockedBefore + 5)
-
-    // 3. A capture in that state discloses the skip rather than presenting the
-    //    unread elements as action-free — and spends no read budget doing it.
-    let leaf = RunnerAXSnapshotFrontier()
-    leaf.snapshot = FrontierSnapshotWithElementForTesting()
-    leaf.node = NSMutableDictionary(dictionary: ["label": "feedItem", "children": []])
-    let coverage = RunnerAXSnapshotBridge.annotateCustomActions(
-      onMergedLeaves: [leaf], axClient: hung, limit: 12, rootFrame: .zero, deadline: nil)
-    XCTAssertEqual(coverage[RunnerAXSnapshotCustomActionsBlockedKey] as? Bool, true)
-    XCTAssertEqual(coverage[RunnerAXSnapshotCustomActionsReadKey] as? Int, 0)
-    XCTAssertEqual(coverage[RunnerAXSnapshotCustomActionsCandidatesKey] as? Int, 1)
-    XCTAssertEqual(
-      RunnerAXSnapshotBridge.customActionReadDispatchCount(), dispatchesBefore + 1)
-    XCTAssertEqual(
-      Self.privateAXCustomActionCoverage(coverage),
-      SnapshotCustomActionCoverage(read: 0, candidates: 1, truncated: 0, blocked: true))
-
-    // 4. Recovery: once the wedged call returns, reads resume by themselves.
-    hung.release()
-    let recovered = expectation(description: "in-flight drains")
-    DispatchQueue.global().async {
-      while RunnerAXSnapshotBridge.customActionReadsInFlight() > 0 {
-        usleep(20_000)
-      }
-      recovered.fulfill()
-    }
-    wait(for: [recovered], timeout: 5)
-
-    completed = ObjCBool(false)
-    XCTAssertNil(
-      RunnerAXSnapshotBridge.customActionNames(
-        forElement: element, axClient: hung, completed: &completed))
-    // Completed (the fake answers nil actions), which is the point: the pass is
-    // live again rather than latched off.
-    XCTAssertTrue(completed.boolValue)
-    XCTAssertEqual(
-      RunnerAXSnapshotBridge.customActionReadDispatchCount(), dispatchesBefore + 2)
-  }
-
-  /// The element budget bounds how many elements we read; these caps bound what
-  /// any ONE element can put in the response. Clipping must be reported, since
-  /// a clipped list looks exactly like a complete one.
-  func testActionNamesAreCappedPerElementAndReported() {
-    var truncated = ObjCBool(true)
-
-    // Under both caps: untouched, nothing to report.
-    let small = ["Reply", "Repost"]
-    XCTAssertEqual(
-      RunnerAXSnapshotBridge.cappedActionNames(small, truncated: &truncated), small)
-    XCTAssertFalse(truncated.boolValue)
-
-    // More actions than the per-element cap: clipped to the first 8, reported.
-    let many = (1...20).map { "Action \($0)" }
-    let cappedMany = RunnerAXSnapshotBridge.cappedActionNames(many, truncated: &truncated)
-    XCTAssertEqual(cappedMany.count, 8)
-    XCTAssertEqual(cappedMany.first, "Action 1")
-    XCTAssertTrue(truncated.boolValue)
-
-    // A single very long name is shortened, reported, and stays one string.
-    let long = String(repeating: "a", count: 500)
-    let cappedLong = RunnerAXSnapshotBridge.cappedActionNames([long], truncated: &truncated)
-    XCTAssertEqual(cappedLong.count, 1)
-    XCTAssertTrue(truncated.boolValue)
-    XCTAssertLessThan(cappedLong[0].count, long.count)
-    XCTAssertTrue(cappedLong[0].hasSuffix("…"))
-
-    // Empty input is not "truncated".
-    XCTAssertEqual(RunnerAXSnapshotBridge.cappedActionNames([], truncated: &truncated), [])
-    XCTAssertFalse(truncated.boolValue)
-  }
-
-  /// Action names annotated by the bridge must survive into the emitted node —
-  /// the whole point of the capture is that the merged card names its hidden
-  /// affordances.
-  func testPrivateAXNodesCarryAnnotatedCustomActions() {
-    let tree: [String: Any] = [
-      "type": Int(XCUIElement.ElementType.application.rawValue),
-      "label": "Blue Sky",
-      "frame": ["x": 0, "y": 0, "width": 390, "height": 844],
-      "children": [
-        [
-          "type": Int(XCUIElement.ElementType.link.rawValue),
-          "label": "feedItem-by-whiskers.test",
-          "frame": ["x": 0, "y": 100, "width": 390, "height": 200],
-          "actions": ["Reply", "Repost", "Open post options menu"],
-          "children": [],
-        ],
-        [
-          "type": Int(XCUIElement.ElementType.button.rawValue),
-          "label": "Compose",
-          "frame": ["x": 300, "y": 700, "width": 60, "height": 60],
-          "children": [],
-        ],
-      ],
-    ]
-    let nodes = privateAXAcquisition(
-      rawRoot: tree,
-      hint: CaptureHint(
-        projection: .regular, depth: nil, regularPresentedDepth: nil,
-        interactiveOnly: false, customActions: false)
-    )
-
-    let card = nodes.first { $0.label == "feedItem-by-whiskers.test" }
-    XCTAssertEqual(card?.actions, ["Reply", "Repost", "Open post options menu"])
-    // A node the bridge did not annotate stays absent, not empty.
-    XCTAssertNil(nodes.first { $0.label == "Compose" }?.actions)
-  }
-
-  func testPrivateAXAcquisitionDoesNotInterpretScope() {
-    let tree: [String: Any] = [
-      "type": 1, "label": "App",
-      "children": [
-        [
-          "type": 9, "identifier": "homeScreen",
-          "children": [
-            ["type": 48, "label": "Post body without the scope text", "children": []]
-          ],
-        ],
-        ["type": 9, "label": "unrelated sibling", "children": []],
-      ],
-    ]
-    // Scope never reaches acquisition: the hint derived for a scoped request carries no scope,
-    // and the backend has no way to interpret one.
-    let nodes = privateAXAcquisition(
-      rawRoot: tree,
-      hint: SnapshotPresentation.captureHint(
-        for: PresentationOptions(
-          interactiveOnly: false,
-          depth: nil,
-          scope: "homeScreen",
-          raw: false
-        )
-      )
-    )
-
-    let labels = nodes.compactMap { $0.label ?? $0.identifier }
-    XCTAssertTrue(labels.contains("homeScreen"))
-    // Descendants of the matched scope are included even when they do not contain the text.
-    XCTAssertTrue(labels.contains("Post body without the scope text"))
-    XCTAssertTrue(labels.contains("unrelated sibling"))
-  }
-
-  func testPrivateAXInteractiveFiltersLoginLikeHiddenDrawer() throws {
-    let tree: [String: Any] = [
-      "type": Int(XCUIElement.ElementType.application.rawValue),
-      "label": "Blue Sky",
-      "frame": ["x": 0, "y": 0, "width": 390, "height": 844],
-      "children": [
-        [
-          "type": Int(XCUIElement.ElementType.scrollView.rawValue),
-          "frame": ["x": 0, "y": 0, "width": 390, "height": 844],
-          "children": [
-            [
-              "type": Int(XCUIElement.ElementType.image.rawValue),
-              "label": "Callstack",
-              "frame": ["x": 145, "y": 104, "width": 100, "height": 100],
-              "children": [],
-            ],
-            [
-              "type": Int(XCUIElement.ElementType.staticText.rawValue),
-              "label": "Welcome back",
-              "frame": ["x": 32, "y": 260, "width": 326, "height": 32],
-              "children": [],
-            ],
-            [
-              "type": Int(XCUIElement.ElementType.textField.rawValue),
-              "label": "Email",
-              "identifier": "login.email",
-              "frame": ["x": 32, "y": 348, "width": 326, "height": 48],
-              "children": [],
-            ],
-            [
-              "type": Int(XCUIElement.ElementType.secureTextField.rawValue),
-              "label": "Password",
-              "identifier": "login.password",
-              "frame": ["x": 32, "y": 412, "width": 326, "height": 48],
-              "children": [],
-            ],
-            [
-              "type": Int(XCUIElement.ElementType.button.rawValue),
-              "label": "Sign in",
-              "identifier": "login.submit",
-              "frame": ["x": 32, "y": 492, "width": 326, "height": 52],
-              "children": [],
-            ],
-            [
-              "type": Int(XCUIElement.ElementType.link.rawValue),
-              "label": "Forgot password?",
-              "frame": ["x": 128, "y": 568, "width": 134, "height": 32],
-              "children": [],
-            ],
-            [
-              "type": Int(XCUIElement.ElementType.button.rawValue),
-              "label": "Admin settings",
-              "frame": ["x": -260, "y": 184, "width": 220, "height": 44],
-              "children": [],
-            ],
-            [
-              "type": Int(XCUIElement.ElementType.other.rawValue),
-              "frame": ["x": 16, "y": 184, "width": 220, "height": 44],
-              "children": [],
-            ],
-          ],
-        ]
-      ],
-    ]
-    let viewport = CGRect(x: 0, y: 0, width: 390, height: 844)
-    let hint = CaptureHint(
-      projection: .regular, depth: nil, regularPresentedDepth: nil,
-      interactiveOnly: true, customActions: false)
-    let acquired = SnapshotGeometrySpace.normalized(
-      nodes: privateAXAcquisition(rawRoot: tree, hint: hint),
-      viewport: viewport,
-      interfaceOrientation: RunnerInterfaceOrientation.portrait
-    )
-    // Acquisition serializes the drawer too; the shared fold is what hides it (#1797).
-    XCTAssertTrue(acquired.compactMap(\.label).contains("Admin settings"))
-
-    let capture = try SnapshotPresentation.presentRegular(
-      SnapshotAcquisition(
-        hint: hint, nodes: acquired, truncated: false, effectiveDepth: nil, viewport: viewport),
-      options: PresentationOptions(interactiveOnly: true, depth: nil, scope: nil, raw: false),
-      policy: .cursorProjected
-    )
-    let labels = capture.nodes.compactMap { $0.label }
-    XCTAssertEqual(
-      labels,
-      ["Blue Sky", "Callstack", "Welcome back", "Email", "Password", "Sign in", "Forgot password?"]
-    )
-    XCTAssertFalse(labels.contains("Admin settings"))
-  }
-}
-
-/// Stands in for an AX client whose `attributesForElement:` never returns —
-/// the wedged-server case the containment exists for. `release()` lets the
-/// hung call finish so recovery is observable.
-private final class HungAXClientForTesting: NSObject {
-  private let gate = DispatchSemaphore(value: 0)
-  private let releasedOnce = NSLock()
-  private var released = false
-
-  @objc(attributesForElement:attributes:error:)
-  func attributes(forElement element: Any, attributes: Any, error: NSErrorPointer) -> Any? {
-    releasedOnce.lock()
-    let alreadyReleased = released
-    releasedOnce.unlock()
-    // Once the wedge clears, the server answers normally again — that is what
-    // makes the recovery leg a recovery rather than a second hang.
-    if alreadyReleased {
-      return nil
-    }
-    gate.wait()
-    return nil
-  }
-
-  func release() {
-    releasedOnce.lock()
-    defer { releasedOnce.unlock() }
-    guard !released else { return }
-    released = true
-    gate.signal()
-  }
-}
-
-/// Minimal snapshot stand-in whose accessibilityElement resolves (so the
-/// extension proceeds to the request) while the paired fake client cannot
-/// serve it — the failed-re-root miss path.
-private final class FrontierSnapshotWithElementForTesting: NSObject {
-  @objc let accessibilityElement = NSObject()
-}
-
-/// The vanished-element case: KVC resolves the property and gets nil.
-private final class FrontierSnapshotWithoutElementForTesting: NSObject {
-  @objc let accessibilityElement: NSObject? = nil
-}
-#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Alert.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Alert.swift
index 483862a3af..60df7eea72 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Alert.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Alert.swift
@@ -188,7 +188,7 @@ extension RunnerTests {
     return buttons.first(where: { isDismissButton($0.label) }) ?? buttons.last
   }
 
-  private func isAcceptButton(_ label: String) -> Bool {
+  func isAcceptButton(_ label: String) -> Bool {
     let normalized = label.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
     return [
       "ok",
@@ -201,12 +201,6 @@ extension RunnerTests {
     ].contains(normalized) || normalized.hasPrefix("confirm")
   }
 
-#if AGENT_DEVICE_RUNNER_UNIT_TESTS
-  func testAlertAcceptTreatsOpenAsAffirmative() {
-    XCTAssertTrue(isAcceptButton("Open"))
-  }
-#endif
-
   private func isDismissButton(_ label: String) -> Bool {
     [
       "cancel",
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+BlockingSystemModalResolution.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+BlockingSystemModalResolution.swift
index 2b92c09bdc..687d36d8b8 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+BlockingSystemModalResolution.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+BlockingSystemModalResolution.swift
@@ -79,39 +79,3 @@ enum RemoteHostedSystemModalPolicy {
     state == .runningForeground
   }
 }
-
-#if AGENT_DEVICE_RUNNER_UNIT_TESTS
-extension RunnerTests {
-  func testRemoteHostProbeRunsOnlyWhenSpringboardModalHasNoActions() {
-    XCTAssertTrue(RemoteHostedSystemModalPolicy.shouldProbeRemoteHost(springboardActionCount: 0))
-    XCTAssertFalse(RemoteHostedSystemModalPolicy.shouldProbeRemoteHost(springboardActionCount: 1))
-    XCTAssertFalse(RemoteHostedSystemModalPolicy.shouldProbeRemoteHost(springboardActionCount: 3))
-  }
-
-  func testRemoteHostStateGateFailsClosedToForeground() {
-    XCTAssertTrue(RemoteHostedSystemModalPolicy.isEligibleHostState(.runningForeground))
-    XCTAssertFalse(RemoteHostedSystemModalPolicy.isEligibleHostState(.runningBackground))
-    XCTAssertFalse(RemoteHostedSystemModalPolicy.isEligibleHostState(.notRunning))
-    XCTAssertFalse(RemoteHostedSystemModalPolicy.isEligibleHostState(.unknown))
-  }
-
-  // No SpringBoard host (`hasSpringBoardSystemModalHost`) means modal resolution must return
-  // `.absent` without probing com.apple.springboard (#1351). Written for tvOS, where no lane
-  // ever executed it; `resolveBlockingSystemModal` takes that decision at RUNTIME off the same
-  // flag on macOS, so the host lane runs the real branch on every PR.
-  //
-  // Its former sibling `testBlockingSystemAlertSnapshotIsNilOnTvOS` is deleted rather than
-  // widened: `blockingSystemAlertSnapshot` is `#if os(macOS) return nil`, so on the only lane
-  // that could run it the assertion would pin a compile-time literal — a green that no change
-  // to the runner could turn red. The runtime gate it meant to cover is this test's subject,
-  // and the nil it returns on macOS is the compiler's business, not a test's.
-  #if os(tvOS) || os(macOS)
-  func testResolveBlockingSystemModalIsAbsentWithoutSpringBoardHost() {
-    guard case .absent = resolveBlockingSystemModal(deadline: .distantFuture) else {
-      XCTFail("blocking system-modal resolution must be .absent without a SpringBoard host")
-      return
-    }
-  }
-  #endif
-}
-#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
index 2e87e03529..c1aa92ca27 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
@@ -1,32 +1,6 @@
 import XCTest
 import AgentDeviceSnapshotPresentation
 
-#if AGENT_DEVICE_RUNNER_UNIT_TESTS && os(iOS)
-import ObjectiveC.runtime
-
-private final class RunnerSynthesizedSwipeFailureStub: NSObject {
-  @objc(synthesizeSwipeWithApplication:resolvedWindow:x:y:x2:y2:durationMs:)
-  class func synthesizeSwipe(
-    application: XCUIApplication,
-    resolvedWindow: Any?,
-    x: Double,
-    y: Double,
-    x2: Double,
-    y2: Double,
-    durationMs: Double
-  ) -> String? {
-    "forced private synthesis failure"
-  }
-}
-
-private final class RunnerSynthesizedTapFailureStub: NSObject {
-  @objc(synthesizeTapWithApplication:resolvedWindow:x:y:)
-  class func synthesizeTap(application: XCUIApplication, resolvedWindow: Any?, x: Double, y: Double) -> String? {
-    "forced private synthesis failure"
-  }
-}
-#endif
-
 extension RunnerTests {
   // MARK: - Main Thread Dispatch
 
@@ -110,7 +84,7 @@ extension RunnerTests {
 
   /// Single factory for the success payload every gesture returns (message + gesture timing +
   /// an optional touch/drag visualization frame), so the field shape lives in one place.
-  private func gestureResponse(
+  func gestureResponse(
     message: String,
     timing: (gestureStartUptimeMs: Double, gestureEndUptimeMs: Double),
     frame: GestureFrame = .none,
@@ -165,7 +139,7 @@ extension RunnerTests {
   /// Gesture plans already return canonical centroid endpoints from the portable runtime.
   /// Keep runner timing/fallback diagnostics, but do not leak the coordinate-drag adapter's
   /// visualization frame into only the fast-fling response shape.
-  private func canonicalPlannedGestureResponse(_ response: Response) -> Response {
+  func canonicalPlannedGestureResponse(_ response: Response) -> Response {
     guard response.ok, let data = response.data else { return response }
     return Response(
       ok: true,
@@ -191,678 +165,6 @@ extension RunnerTests {
     return gestureResponse(message: plan.intent, timing: timing)
   }
 
-#if AGENT_DEVICE_RUNNER_UNIT_TESTS
-  func testGestureResponseIncludesSynthesizedTapFallbackDiagnostics() {
-    let response = gestureResponse(
-      message: "tapped",
-      timing: (gestureStartUptimeMs: 1, gestureEndUptimeMs: 2),
-      fallback: GestureFallback(
-        strategy: "xctest-coordinate-tap",
-        message: "Runner synthesized coordinate tap is unavailable",
-        hint: "Using XCTest coordinate tap fallback."
-      )
-    )
-
-    XCTAssertEqual(response.ok, true)
-    XCTAssertEqual(response.data?.gestureFallback, "xctest-coordinate-tap")
-    XCTAssertEqual(
-      response.data?.gestureFallbackMessage,
-      "Runner synthesized coordinate tap is unavailable"
-    )
-    XCTAssertEqual(response.data?.gestureFallbackHint, "Using XCTest coordinate tap fallback.")
-  }
-
-  func testGestureResponseIncludesMaestroNonHittableFallbackUsage() {
-    let response = gestureResponse(
-      message: "tapped via non-hittable coordinate fallback",
-      timing: (gestureStartUptimeMs: 1, gestureEndUptimeMs: 2),
-      frame: .touch(nil),
-      maestroNonHittableCoordinateFallbackUsed: true
-    )
-
-    XCTAssertEqual(response.data?.maestroNonHittableCoordinateFallbackUsed, true)
-  }
-
-  func testCanonicalPlannedGestureResponseOmitsDragFrameAndPreservesDiagnostics() {
-    let response = gestureResponse(
-      message: "fling",
-      timing: (gestureStartUptimeMs: 1, gestureEndUptimeMs: 2),
-      frame: .drag(
-        DragVisualizationFrame(
-          x: 160,
-          y: 150,
-          x2: 40,
-          y2: 150,
-          referenceWidth: 200,
-          referenceHeight: 300
-        )
-      ),
-      fallback: GestureFallback(
-        strategy: "xctest-coordinate-drag",
-        message: "Private synthesis unavailable",
-        hint: "Using XCTest coordinate fallback."
-      )
-    )
-
-    let canonical = canonicalPlannedGestureResponse(response)
-
-    XCTAssertEqual(canonical.data?.gestureStartUptimeMs, 1)
-    XCTAssertEqual(canonical.data?.gestureEndUptimeMs, 2)
-    XCTAssertEqual(canonical.data?.gestureFallback, "xctest-coordinate-drag")
-    XCTAssertEqual(canonical.data?.gestureFallbackMessage, "Private synthesis unavailable")
-    XCTAssertEqual(canonical.data?.gestureFallbackHint, "Using XCTest coordinate fallback.")
-    XCTAssertNil(canonical.data?.x)
-    XCTAssertNil(canonical.data?.y)
-    XCTAssertNil(canonical.data?.x2)
-    XCTAssertNil(canonical.data?.y2)
-    XCTAssertNil(canonical.data?.referenceWidth)
-    XCTAssertNil(canonical.data?.referenceHeight)
-  }
-
-#if os(iOS)
-  func testSinglePointerFlingFallsBackToXCTestCoordinateDragWhenPrivateSynthesisFails() throws {
-    let selector = NSSelectorFromString(
-      "synthesizeSwipeWithApplication:resolvedWindow:x:y:x2:y2:durationMs:"
-    )
-    guard
-      let synthesizedSwipeMethod = class_getClassMethod(RunnerSynthesizedGesture.self, selector),
-      let failureStubMethod = class_getClassMethod(RunnerSynthesizedSwipeFailureStub.self, selector)
-    else {
-      XCTFail("unable to install synthesized swipe failure stub")
-      return
-    }
-    let originalImplementation = method_getImplementation(synthesizedSwipeMethod)
-    method_setImplementation(
-      synthesizedSwipeMethod,
-      method_getImplementation(failureStubMethod)
-    )
-    app.launch()
-    runnerAccessibilityHealth = .healthy
-    defer {
-      method_setImplementation(synthesizedSwipeMethod, originalImplementation)
-      invalidateCachedTarget(reason: "unit_test_cleanup")
-      app.terminate()
-    }
-    let command = try runnerCommandFixture(
-      """
-      {"command":"gesture","commandId":"gesture-fling-fallback","gesturePlan":{"topology":"single","intent":"fling","executionProfile":"endpoint-hold","durationMs":100,"viewport":{"x":0,"y":0,"width":200,"height":300},"pointers":[{"pointerId":0,"samples":[{"offsetMs":0,"point":{"x":160,"y":150}},{"offsetMs":100,"point":{"x":40,"y":150}}]}]}}
-      """
-    )
-
-    let response = try executeOnMainPrepared(command: command, activeApp: app)
-
-    XCTAssertTrue(response.ok)
-    XCTAssertEqual(response.data?.message, "fling")
-    XCTAssertEqual(response.data?.gestureFallback, "xctest-coordinate-drag")
-    XCTAssertEqual(response.data?.gestureFallbackMessage, "forced private synthesis failure")
-    XCTAssertEqual(
-      response.data?.gestureFallbackHint,
-      "Private XCTest event synthesis is required for AX-free coordinate drag on iOS; update Xcode if this persists."
-    )
-    XCTAssertNil(response.data?.x)
-    XCTAssertNil(response.data?.y)
-    XCTAssertNil(response.data?.x2)
-    XCTAssertNil(response.data?.y2)
-  }
-
-  func testSelectorTapFallsBackToXCTestCoordinateWhenPrivateSynthesisFails() throws {
-    let selector = NSSelectorFromString("synthesizeTapWithApplication:resolvedWindow:x:y:")
-    guard
-      let synthesizedTapMethod = class_getClassMethod(RunnerSynthesizedGesture.self, selector),
-      let failureStubMethod = class_getClassMethod(RunnerSynthesizedTapFailureStub.self, selector)
-    else {
-      XCTFail("unable to install synthesized tap failure stub")
-      return
-    }
-    let originalImplementation = method_getImplementation(synthesizedTapMethod)
-    method_setImplementation(
-      synthesizedTapMethod,
-      method_getImplementation(failureStubMethod)
-    )
-    app.launch()
-    currentApp = app
-    runnerAccessibilityHealth = .healthy
-    defer {
-      method_setImplementation(synthesizedTapMethod, originalImplementation)
-      invalidateCachedTarget(reason: "unit_test_cleanup")
-      app.terminate()
-    }
-    let command = try runnerCommandFixture(
-      #"{"command":"tap","commandId":"selector-tap-fallback","selectorKey":"label","selectorValue":"Agent Device Runner","synthesized":true}"#
-    )
-
-    let response = try executeOnMainPrepared(command: command, activeApp: app)
-
-    XCTAssertTrue(response.ok)
-    XCTAssertEqual(response.data?.message, "tapped")
-    XCTAssertEqual(response.data?.gestureFallback, "xctest-coordinate-tap")
-    XCTAssertEqual(response.data?.gestureFallbackMessage, "forced private synthesis failure")
-    XCTAssertEqual(
-      response.data?.gestureFallbackHint,
-      "Falling back to XCTest coordinate tap may be slower and can still need a healthy accessibility tree."
-    )
-  }
-#endif
-
-#if os(iOS)
-  // `waitForTextEntryReadiness`'s hardware-keyboard fallback returns early only on confirmed
-  // focus (#1874), and `keyboardFocusConfirmed` reads that from the app-wide focus predicate this
-  // bundle otherwise refuses to trust. Two XCTest facts it rests on, neither a repository
-  // invariant: the predicate reports a responder that shows NO software keyboard at all, and it
-  // names the element well enough to tell the tapped field from another one. The fixture field is
-  // the exact shape the fallback exists for — a real responder with an empty `inputView` — so this
-  // is where both are observable. If either regressed, readiness would silently stop taking the
-  // fallback and spend the full readinessTimeout on every hardware-keyboard field, which no other
-  // assertion would notice.
-  func testHardwareKeyboardResponderConfirmsItsOwnKeyboardFocus() throws {
-    app.launchArguments = ["--agent-device-text-entry-regression"]
-    app.launch()
-    defer {
-      invalidateCachedTarget(reason: "unit_test_cleanup")
-      app.terminate()
-    }
-    XCTAssertTrue(app.waitForExistence(timeout: appExistenceTimeout))
-
-    let textField = app.textFields["agent-device-hardware-keyboard-input"]
-    XCTAssertTrue(textField.waitForExistence(timeout: appExistenceTimeout))
-    let otherElement = app.staticTexts["Agent Device Runner"]
-    XCTAssertTrue(otherElement.waitForExistence(timeout: appExistenceTimeout))
-    XCTAssertFalse(
-      keyboardFocusConfirmed(app: app, element: textField),
-      "an untapped field must not confirm focus, or the fallback would fire immediately"
-    )
-
-    let tapCommand = try runnerCommandFixture(
-      #"{"command":"tap","commandId":"tap-focus-confirmation","selectorKey":"id","selectorValue":"agent-device-hardware-keyboard-input"}"#
-    )
-    let tapResponse = try executeOnMainPrepared(command: tapCommand, activeApp: app)
-    XCTAssertTrue(tapResponse.ok, String(describing: tapResponse.error))
-    try XCTSkipIf(
-      isKeyboardVisible(app: app),
-      "software keyboard is up: this simulator cannot exercise the hidden-keyboard responder path"
-    )
-
-    let deadline = Date().addingTimeInterval(TextEntryTiming.readinessTimeout)
-    var confirmed = keyboardFocusConfirmed(app: app, element: textField)
-    while !confirmed && Date() < deadline {
-      sleepFor(TextEntryTiming.pollInterval)
-      confirmed = keyboardFocusConfirmed(app: app, element: textField)
-    }
-    XCTAssertTrue(confirmed, "a tapped responder must confirm its own keyboard focus")
-    XCTAssertFalse(
-      keyboardFocusConfirmed(app: app, element: otherElement),
-      "focus held by another element must read as a refusal, never as this element's focus"
-    )
-  }
-#endif
-
-  func testInjectedTapRecordedFailureGateIsTapOnlyAndCountGated() {
-    // The seam's recording side cannot run in-bundle (a real XCTIssue would
-    // fail this very test run — same constraint the record(_:) suppression
-    // tests document); the live daemon proof covers it. This pins the gate.
-    XCTAssertFalse(RunnerTests.shouldInjectTapRecordedFailure(command: .tap, remaining: 0))
-    XCTAssertTrue(RunnerTests.shouldInjectTapRecordedFailure(command: .tap, remaining: 1))
-    XCTAssertFalse(RunnerTests.shouldInjectTapRecordedFailure(command: .type, remaining: 1))
-    XCTAssertFalse(RunnerTests.shouldInjectTapRecordedFailure(command: .snapshot, remaining: 1))
-  }
-
-  func testXCTestRecordedFailureResponseFailsMutatingSuccesses() throws {
-    let command = try runnerCommandFixture(#"{"command":"tap","commandId":"tap-1"}"#)
-    let response = Response(ok: true, data: DataPayload(message: "tapped"))
-
-    let failureResponse = xctestRecordedFailureResponse(command: command, response: response)
-
-    XCTAssertEqual(failureResponse?.ok, false)
-    XCTAssertEqual(failureResponse?.error?.code, "XCTEST_RECORDED_FAILURE")
-    XCTAssertEqual(
-      failureResponse?.error?.message,
-      "XCTest recorded a failure while executing tap; the action may not have been performed."
-    )
-  }
-
-  func testXCTestRecordedFailureResponseFailsActionButtonSuccess() throws {
-    // The Action Button press carries no settle and no post-action observation, so this conversion is
-    // the only evidence the press landed. That is why the press is not classified runner-lifecycle:
-    // `isLifecycle` would silence the conversion here (#2699, #2702 review).
-    let command = try runnerCommandFixture(#"{"command":"actionButton","commandId":"action-button-1"}"#)
-    let response = Response(ok: true, data: DataPayload(message: "actionButton"))
-
-    let failureResponse = xctestRecordedFailureResponse(command: command, response: response)
-
-    XCTAssertEqual(failureResponse?.ok, false)
-    XCTAssertEqual(failureResponse?.error?.code, "XCTEST_RECORDED_FAILURE")
-    XCTAssertEqual(
-      failureResponse?.error?.message,
-      "XCTest recorded a failure while executing actionButton; the action may not have been performed."
-    )
-  }
-
-  func testXCTestRecordedFailureResponseDoesNotWrapReadOnlyOrRunnerFatalResponses() throws {
-    let snapshotCommand = try runnerCommandFixture(#"{"command":"snapshot","commandId":"snapshot-1"}"#)
-    let tapCommand = try runnerCommandFixture(#"{"command":"tap","commandId":"tap-1"}"#)
-    let runnerFatalResponse = Response(
-      ok: true,
-      data: DataPayload(runnerFatal: true, runnerFatalReason: "ax_snapshot_unavailable")
-    )
-
-    XCTAssertNil(
-      xctestRecordedFailureResponse(
-        command: snapshotCommand,
-        response: Response(ok: true, data: DataPayload(nodes: [], truncated: false))
-      )
-    )
-    XCTAssertNil(xctestRecordedFailureResponse(command: tapCommand, response: runnerFatalResponse))
-  }
-
-  // Simulator-only from here to the matching #endif: these launch the host app, route through
-  // SpringBoard, or assert the iOS-only alert/system-modal branches. Tests outside the
-  // `os(iOS)` regions in this file are pure runner decisions and also run on the macOS host
-  // lane (ci.yml) — see the classification convention in RunnerTests.swift.
-#if os(iOS)
-  func testMissingBundleCommandInvalidatesCompleteCachedTargetState() throws {
-    app.launch()
-    currentApp = app
-    currentBundleId = "com.example.stale-target"
-    currentAppProcessIdentifier = 42
-    snapshotXCTestPenaltyWarmupExemptionPending = true
-    defer {
-      invalidateCachedTarget(reason: "unit_test_cleanup")
-      app.terminate()
-    }
-    let command = try runnerCommandFixture(
-      #"{"command":"snapshot","commandId":"snapshot-without-bundle"}"#
-    )
-
-    _ = prepareActiveCommandContext(command: command)
-
-    XCTAssertNil(currentApp)
-    XCTAssertNil(currentBundleId)
-    XCTAssertNil(currentAppProcessIdentifier)
-    XCTAssertFalse(snapshotXCTestPenaltyWarmupExemptionPending)
-  }
-
-  func testSkipAppActivationPreflightIncludesForegroundCachedCoordinateOnlyTaps() throws {
-    app.launch()
-    currentApp = app
-    currentBundleId = nil
-    defer {
-      currentApp = nil
-      currentBundleId = nil
-      app.terminate()
-    }
-    let tap = try runnerCommandFixture(
-      #"{"command":"tap","commandId":"tap-1","x":10,"y":20}"#
-    )
-
-    XCTAssertTrue(shouldSkipAppActivationPreflight(tap))
-  }
-
-  func testSkipAppActivationPreflightRejectsMissingChangedAndBackgroundTargets() throws {
-    let coordinateTap = try runnerCommandFixture(
-      #"{"command":"tap","commandId":"tap-1","x":10,"y":20}"#
-    )
-    currentApp = nil
-    currentBundleId = nil
-    XCTAssertFalse(shouldSkipAppActivationPreflight(coordinateTap))
-
-    app.launch()
-    currentApp = app
-    currentBundleId = "com.example.current"
-    defer {
-      currentApp = nil
-      currentBundleId = nil
-      app.terminate()
-    }
-    let changedBundleTap = try runnerCommandFixture(
-      #"{"command":"tap","commandId":"tap-2","appBundleId":"com.example.other","x":10,"y":20}"#
-    )
-
-    XCTAssertFalse(shouldSkipAppActivationPreflight(changedBundleTap))
-
-    app.terminate()
-    currentApp = app
-    currentBundleId = nil
-
-    XCTAssertFalse(shouldSkipAppActivationPreflight(coordinateTap))
-  }
-
-  func testActionButtonPressSkipsAppActivationPreflightWithoutBeingRunnerLifecycle() throws {
-    currentApp = nil
-    currentBundleId = nil
-    let press = try runnerCommandFixture(#"{"command":"actionButton","commandId":"action-button-1"}"#)
-
-    // The skip is its own decision, reached without the lifecycle flag that would also drop the
-    // recorded-failure conversion; no cached target and no foreground app is required for it.
-    XCTAssertFalse(isRunnerLifecycleCommand(.actionButton))
-    XCTAssertTrue(shouldSkipAppActivationPreflight(press))
-  }
-
-  func testPrepareActiveCommandContextRoutesBlockingSystemModalToSpringboard() throws {
-    blockingSystemModalPresenceOverrideForTesting = true
-    currentApp = nil
-    currentBundleId = nil
-    defer {
-      blockingSystemModalPresenceOverrideForTesting = nil
-      currentApp = nil
-      currentBundleId = nil
-    }
-    let tap = try runnerCommandFixture(
-      #"{"command":"tap","commandId":"tap-1","x":10,"y":20}"#
-    )
-
-    let preparation = prepareActiveCommandContext(
-      command: tap,
-      routeToSpringboard: shouldRouteToSpringboardBlockingSystemModal(tap)
-    )
-
-    guard case .context(let context) = preparation else {
-      XCTFail("expected command context")
-      return
-    }
-    XCTAssertTrue(context.app === springboard)
-  }
-
-  func testExecuteDispatchedReturnsBusyBeforeBlockingSystemModalProbeDrains() throws {
-    app.launch()
-    currentApp = app
-    currentBundleId = nil
-    defer {
-      currentApp = nil
-      currentBundleId = nil
-      systemModalProbeOverrideForTesting = nil
-      clearSnapshotXCTestChannelPenalty(reason: "test-cleanup")
-      app.terminate()
-    }
-
-    final class ResultBox {
-      var response: Response?
-      var error: Error?
-      var commandRecoveredBeforeRelease = false
-      var wasBusyBeforeRelease = false
-      var hadAbandonedProbeBeforeRelease = false
-      var drained = false
-    }
-    let box = ResultBox()
-    let probeStarted = expectation(description: "system-modal routing probe started")
-    let verificationFinished = expectation(description: "command recovery and modal probe drain verified")
-    let probeReleaseGate = DispatchSemaphore(value: 0)
-    let commandFinishedGate = DispatchSemaphore(value: 0)
-    systemModalProbeOverrideForTesting = { _ in
-      probeStarted.fulfill()
-      _ = probeReleaseGate.wait(timeout: .now() + 15)
-      return DataPayload(message: "late system modal")
-    }
-
-    let command = try runnerCommandFixture(
-      #"{"command":"tap","commandId":"bounded-modal-routing","x":10,"y":20}"#
-    )
-    DispatchQueue(label: "agent-device.runner.tests.modal-routing-probe").async {
-      do {
-        box.response = try self.executeDispatched(command: command)
-      } catch {
-        box.error = error
-      }
-      commandFinishedGate.signal()
-    }
-    DispatchQueue(label: "agent-device.runner.tests.modal-routing-probe-verifier").async {
-      let commandWait = commandFinishedGate.wait(
-        timeout: .now() + self.systemModalProbeBudget + 3
-      )
-      box.commandRecoveredBeforeRelease = commandWait == .success
-        && box.error == nil
-        && box.response?.error?.code == "RUNNER_BUSY"
-      if case .busy = self.currentMainThreadBusyState() {
-        box.wasBusyBeforeRelease = true
-      }
-      box.hadAbandonedProbeBeforeRelease = self.hasAbandonedMainThreadWork()
-
-      // The XCTest main thread is blocked inside the injected probe, so this verifier owns the
-      // ordered release after recording the command result and abandoned-work state above.
-      probeReleaseGate.signal()
-      let deadline = Date().addingTimeInterval(5)
-      while self.hasAbandonedMainThreadWork(), Date() < deadline {
-        self.sleepFor(0.002)
-      }
-      box.drained = !self.hasAbandonedMainThreadWork()
-      verificationFinished.fulfill()
-    }
-
-    wait(for: [probeStarted, verificationFinished], timeout: 15)
-    XCTAssertTrue(
-      box.commandRecoveredBeforeRelease,
-      "the public coordinate tap must return RUNNER_BUSY before the blocked modal probe drains"
-    )
-    XCTAssertTrue(box.wasBusyBeforeRelease)
-    XCTAssertTrue(box.hadAbandonedProbeBeforeRelease)
-    XCTAssertTrue(box.drained)
-    guard case .idle = currentMainThreadBusyState() else {
-      return XCTFail("expected the runner to become idle after the routing probe drained")
-    }
-    XCTAssertFalse(hasAbandonedMainThreadWork())
-  }
-
-  func testSkipAppActivationPreflightRejectsSelectorAndMixedSequenceGestures() throws {
-    app.launch()
-    currentApp = app
-    currentBundleId = nil
-    defer {
-      currentApp = nil
-      currentBundleId = nil
-      app.terminate()
-    }
-    let selectorTap = try runnerCommandFixture(
-      #"{"command":"tap","commandId":"tap-1","selectorKey":"label","selectorValue":"Search","synthesized":true}"#
-    )
-    let standardDrag = try runnerCommandFixture(
-      #"{"command":"drag","commandId":"drag-1","x":10,"y":20,"x2":30,"y2":40}"#
-    )
-    let mixedSequence = try runnerCommandFixture(
-      """
-      {"command":"sequence","commandId":"seq-1","steps":[
-        {"kind":"tap","x":10,"y":20,"synthesized":true},
-        {"kind":"doubleTap","x":30,"y":40}
-      ]}
-      """
-    )
-
-    XCTAssertFalse(shouldSkipAppActivationPreflight(selectorTap))
-    XCTAssertFalse(shouldSkipAppActivationPreflight(standardDrag))
-    XCTAssertFalse(shouldSkipAppActivationPreflight(mixedSequence))
-  }
-
-  // Launches nothing, but still simulator-only: `shouldSkipAppActivationPreflight` is
-  // `#if os(iOS) …guards… #else return false #endif`, so on macOS this asserts a compile-time
-  // literal and no edit to the iOS body could make it red. Its five siblings above and below
-  // are gated for the same reason.
-  func testSkipAppActivationPreflightRequiresCachedForegroundTarget() throws {
-    currentApp = nil
-    currentBundleId = nil
-    let scroll = try runnerCommandFixture(
-      #"{"command":"scroll","commandId":"scroll-1","direction":"down","pixels":400}"#
-    )
-
-    XCTAssertFalse(shouldSkipAppActivationPreflight(scroll))
-  }
-
-  func testSkipAppActivationPreflightKeepsDragScrollAndSequenceOnForegroundGuard() throws {
-    app.launch()
-    currentApp = app
-    currentBundleId = nil
-    defer {
-      currentApp = nil
-      currentBundleId = nil
-      app.terminate()
-    }
-    let drag = try runnerCommandFixture(
-      #"{"command":"drag","commandId":"drag-1","x":10,"y":20,"x2":30,"y2":40}"#
-    )
-    let scroll = try runnerCommandFixture(
-      #"{"command":"scroll","commandId":"scroll-1","direction":"down","pixels":400}"#
-    )
-    let sequence = try runnerCommandFixture(
-      """
-      {"command":"sequence","commandId":"seq-1","steps":[
-        {"kind":"tap","x":10,"y":20,"synthesized":true},
-        {"kind":"longPress","x":10,"y":200,"durationMs":300}
-      ]}
-      """
-    )
-
-    XCTAssertFalse(shouldSkipAppActivationPreflight(drag))
-    XCTAssertFalse(shouldSkipAppActivationPreflight(scroll))
-    XCTAssertFalse(shouldSkipAppActivationPreflight(sequence))
-  }
-
-  func testSkipAppActivationPreflightIncludesAlertCommands() throws {
-    let alert = try runnerCommandFixture(
-      #"{"command":"alert","commandId":"alert-1","action":"get"}"#
-    )
-
-    XCTAssertTrue(shouldSkipAppActivationPreflight(alert))
-  }
-#endif
-
-  func testDispatchReturnsBusyBeforeQueueingMainThreadWork() throws {
-    let command = try runnerCommandFixture(#"{"command":"snapshot","commandId":"snapshot-busy"}"#)
-    abandonedMainThreadWorkCount = 1
-    abandonedMainThreadWorkSince = Date(timeIntervalSinceNow: -2)
-    defer {
-      abandonedMainThreadWorkCount = 0
-      abandonedMainThreadWorkSince = nil
-    }
-
-    let response = try execute(command: command)
-
-    XCTAssertFalse(response.ok)
-    XCTAssertEqual(response.error?.code, "RUNNER_BUSY")
-    XCTAssertTrue(response.error?.message.contains("previous command") == true)
-  }
-
-  func testDispatchReturnsWedgedBeforeQueueingMainThreadWork() throws {
-    let command = try runnerCommandFixture(#"{"command":"snapshot","commandId":"snapshot-wedged"}"#)
-    abandonedMainThreadWorkCount = 1
-    abandonedMainThreadWorkSince = Date(timeIntervalSinceNow: -(mainThreadWedgeThreshold + 1))
-    defer {
-      abandonedMainThreadWorkCount = 0
-      abandonedMainThreadWorkSince = nil
-    }
-
-    let response = try execute(command: command)
-
-    XCTAssertFalse(response.ok)
-    XCTAssertEqual(response.error?.code, "RUNNER_WEDGED")
-    XCTAssertTrue(response.error?.hint?.contains("runner session will be restarted") == true)
-  }
-
-  func testPostSnapshotDelayMarkDoesNotQueueBehindAbandonedMainThreadWork() {
-    abandonedMainThreadWorkCount = 1
-    defer {
-      abandonedMainThreadWorkCount = 0
-      needsPostSnapshotInteractionDelay = false
-    }
-
-    let finished = expectation(description: "off-main caller finished")
-    DispatchQueue(label: "agent-device.runner.tests.post-snapshot-delay").async {
-      self.setNeedsPostSnapshotInteractionDelay()
-      finished.fulfill()
-    }
-
-    wait(for: [finished], timeout: 1)
-    mainThreadWorkLock.lock()
-    let abandonedWorkCount = abandonedMainThreadWorkCount
-    mainThreadWorkLock.unlock()
-    XCTAssertEqual(abandonedWorkCount, 1, "the skipped mark must not add an abandoned unit")
-    XCTAssertFalse(needsPostSnapshotInteractionDelay)
-  }
-
-  func testSnapshotFailureInvalidationQueuesBehindAbandonedMainThreadWorkWithoutWaiting() {
-    currentBundleId = "com.example.stale-target"
-    defer { currentBundleId = nil }
-
-    final class ResultBox {
-      var elapsed: TimeInterval?
-      var bundleStillCachedWhileBlocked: Bool?
-      var abandonedWhileBlocked: Int?
-    }
-    let box = ResultBox()
-    let mainBlocked = DispatchSemaphore(value: 0)
-    let releaseMain = DispatchSemaphore(value: 0)
-    let finished = expectation(description: "invalidation returned while main was blocked")
-
-    DispatchQueue(label: "agent-device.runner.tests.snapshot-invalidation").async {
-      _ = try? self.runMainThreadWork(
-        "command_execution",
-        timeout: 0,
-        timeoutError: self.mainThreadExecutionTimeoutError
-      ) {
-        mainBlocked.signal()
-        _ = releaseMain.wait(timeout: .now() + 5)
-        return true
-      }
-      _ = mainBlocked.wait(timeout: .now() + 2)
-      let startedAt = Date()
-      self.invalidateCachedTargetAfterSnapshotFailure()
-      box.elapsed = Date().timeIntervalSince(startedAt)
-      box.bundleStillCachedWhileBlocked = self.currentBundleId != nil
-      self.mainThreadWorkLock.lock()
-      box.abandonedWhileBlocked = self.abandonedMainThreadWorkCount
-      self.mainThreadWorkLock.unlock()
-      releaseMain.signal()
-      finished.fulfill()
-    }
-
-    wait(for: [finished], timeout: 8)
-    let drainDeadline = Date().addingTimeInterval(2)
-    while hasAbandonedMainThreadWork() || currentBundleId != nil, Date() < drainDeadline {
-      sleepFor(0.005)
-    }
-
-    XCTAssertLessThan(
-      box.elapsed ?? .infinity,
-      0.5,
-      "the failed capture must not wait behind abandoned main-thread work"
-    )
-    XCTAssertEqual(
-      box.bundleStillCachedWhileBlocked,
-      true,
-      "the drop must queue behind the blocked main thread, not run early"
-    )
-    XCTAssertEqual(box.abandonedWhileBlocked, 1, "the deferred drop must not add an abandoned unit")
-    XCTAssertFalse(hasAbandonedMainThreadWork())
-    XCTAssertNil(currentBundleId, "the drop must run once the main thread frees")
-  }
-#endif
-
-#if AGENT_DEVICE_RUNNER_UNIT_TESTS
-  /// Routes `command` through the transport's inline and queued paths. The calling test's main
-  /// thread serves the command's main-thread work while it waits.
-  func execute(command: Command) throws -> Response {
-    dispatchPrecondition(condition: .onQueue(.main))
-    if let response = inlineResponse(for: command) {
-      return response
-    }
-    final class ResultBox {
-      var result: Result<Response, Error>?
-    }
-    let box = ResultBox()
-    let executed = XCTestExpectation(description: "\(command.command.rawValue) executed off main")
-    enqueueAccepted(command: command) { result in
-      box.result = result
-      executed.fulfill()
-    }
-    guard XCTWaiter.wait(for: [executed], timeout: mainThreadExecutionTimeout + 5) == .completed,
-      let result = box.result
-    else {
-      throw NSError(
-        domain: RunnerErrorDomain.general,
-        code: RunnerErrorCode.commandReturnedNoResponse,
-        userInfo: [NSLocalizedDescriptionKey: "command did not finish on the command queue"]
-      )
-    }
-    return try result.get()
-  }
-#endif
-
   func executeAccepted(command: Command) throws -> Response {
     commandJournal.start(command: command)
     pendingTargetActivation = nil
@@ -967,7 +269,7 @@ extension RunnerTests {
     }
   }
 
-  private func executeDispatched(command: Command) throws -> Response {
+  func executeDispatched(command: Command) throws -> Response {
     // XCTest work cannot be cancelled mid-flight: once the watchdog abandons a main-queue
     // block, queueing more main-thread commands behind it only buries the runner deeper.
     // Refuse fast instead so the daemon backs off while the abandoned work drains; past the
@@ -1238,7 +540,7 @@ extension RunnerTests {
     }
   }
 
-  private func setNeedsPostSnapshotInteractionDelay() {
+  func setNeedsPostSnapshotInteractionDelay() {
     guard !hasAbandonedMainThreadWork() else {
       NSLog("AGENT_DEVICE_RUNNER_POST_SNAPSHOT_DELAY_MARK_SKIPPED_XCTEST_OCCUPIED")
       return
@@ -1256,7 +558,7 @@ extension RunnerTests {
     }
   }
 
-  private func invalidateCachedTargetAfterSnapshotFailure() {
+  func invalidateCachedTargetAfterSnapshotFailure() {
     // Abandoned work ahead of this hop cannot be cancelled: queue the drop behind it without
     // waiting, so the failed capture answers now and the next command still finds the target gone.
     guard !hasAbandonedMainThreadWork() else {
@@ -1424,7 +726,7 @@ extension RunnerTests {
     )
   }
 
-  private func prepareActiveCommandContext(
+  func prepareActiveCommandContext(
     command: Command,
     routeToSpringboard: Bool = false
   ) -> ActiveCommandPreparation {
@@ -2446,7 +1748,7 @@ extension RunnerTests {
     return currentXCTestFailureCount() > failureCountBefore
   }
 
-  private func xctestRecordedFailureResponse(command: Command, response: Response) -> Response? {
+  func xctestRecordedFailureResponse(command: Command, response: Response) -> Response? {
     guard response.ok else { return nil }
     if response.data?.runnerFatal == true {
       return nil
@@ -2464,13 +1766,7 @@ extension RunnerTests {
     )
   }
 
-#if AGENT_DEVICE_RUNNER_UNIT_TESTS
-  func runnerCommandFixture(_ json: String) throws -> Command {
-    try JSONDecoder().decode(Command.self, from: Data(json.utf8))
-  }
-#endif
-
-  private func shouldSkipAppActivationPreflight(_ command: Command) -> Bool {
+  func shouldSkipAppActivationPreflight(_ command: Command) -> Bool {
 #if os(iOS)
     if command.command == .alert {
       return true
@@ -2495,7 +1791,7 @@ extension RunnerTests {
 #endif
   }
 
-  private func shouldRouteToSpringboardBlockingSystemModal(
+  func shouldRouteToSpringboardBlockingSystemModal(
     _ command: Command
   ) -> Bool {
 #if os(iOS)
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandJournal.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandJournal.swift
index 9ed3b9f51f..c91955116d 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandJournal.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandJournal.swift
@@ -144,340 +144,3 @@ final class RunnerCommandJournal {
     }
   }
 }
-
-#if AGENT_DEVICE_RUNNER_UNIT_TESTS
-extension RunnerTests {
-  func testUptimeBypassesCommandJournal() throws {
-    let command = runnerJournalCommand("uptime", id: "uptime-probe")
-
-    let response = try execute(command: command)
-    let status = commandJournal.status(normalizedCommandId: "uptime-probe")
-
-    XCTAssertEqual(response.ok, true)
-    XCTAssertNotNil(response.data?.currentUptimeMs)
-    XCTAssertEqual(status.lifecycleState, RunnerCommandLifecycleState.notAccepted.rawValue)
-  }
-
-  func testStampingCurrentUptimePreservesPayload() {
-    let stamped = Response(ok: true, data: DataPayload(message: "recording started"))
-      .stampingCurrentUptimeMs(123.5)
-
-    XCTAssertEqual(stamped.ok, true)
-    XCTAssertEqual(stamped.data?.message, "recording started")
-    XCTAssertEqual(stamped.data?.currentUptimeMs, 123.5)
-  }
-
-  func testStampingCurrentUptimeCreatesPayloadWhenNil() {
-    let stamped = Response(ok: true).stampingCurrentUptimeMs(456.0)
-
-    XCTAssertEqual(stamped.ok, true)
-    XCTAssertEqual(stamped.data?.currentUptimeMs, 456.0)
-  }
-
-  func testStampingCurrentUptimeSkipsErrorResponses() {
-    let response = Response(ok: false, error: ErrorPayload(message: "boom"))
-    let stamped = response.stampingCurrentUptimeMs(789.0)
-
-    XCTAssertEqual(stamped.ok, false)
-    XCTAssertNil(stamped.data)
-    XCTAssertEqual(stamped.error?.message, "boom")
-  }
-
-  func testStampingCurrentMainThreadBusyPreservesPayload() {
-    let stamped = Response(ok: true, data: DataPayload(nodes: [], truncated: false))
-      .stampingCurrentMainThreadBusy(true)
-
-    XCTAssertEqual(stamped.ok, true)
-    XCTAssertEqual(stamped.data?.runnerMainThreadBusy, true)
-  }
-
-  func testStampingCurrentMainThreadBusySkipsErrorResponses() {
-    let response = Response(ok: false, error: ErrorPayload(code: "RUNNER_BUSY", message: "busy"))
-    let stamped = response.stampingCurrentMainThreadBusy(true)
-
-    XCTAssertEqual(stamped.ok, false)
-    XCTAssertNil(stamped.data)
-    XCTAssertEqual(stamped.error?.code, "RUNNER_BUSY")
-  }
-
-  func testMainThreadBusyStateReportsOccupancy() {
-    XCTAssertFalse(MainThreadBusyState.idle.reportsMainThreadBusy)
-    XCTAssertTrue(MainThreadBusyState.busy(abandonedForSeconds: 5).reportsMainThreadBusy)
-    XCTAssertTrue(MainThreadBusyState.wedged(abandonedForSeconds: 200).reportsMainThreadBusy)
-    XCTAssertEqual(
-      Response(ok: true).stampingCurrentMainThreadBusy(false).data?.runnerMainThreadBusy, false)
-  }
-
-  func testCommandFailedResponseTagsMainThreadTimeoutWithTypedCode() {
-    let timeout = NSError(
-      domain: RunnerErrorDomain.general,
-      code: RunnerErrorCode.mainThreadExecutionTimedOut,
-      userInfo: [NSLocalizedDescriptionKey: "main thread execution timed out"]
-    )
-
-    let response = commandFailedResponse(from: timeout)
-
-    XCTAssertEqual(response.ok, false)
-    XCTAssertEqual(response.error?.code, RunnerWireErrorCode.mainThreadTimeout)
-  }
-
-  func testCommandFailedResponseKeepsGenericCodeForOtherErrors() {
-    let other = NSError(domain: "SomeOtherDomain", code: 99, userInfo: nil)
-
-    let response = commandFailedResponse(from: other)
-
-    XCTAssertEqual(response.error?.code, "COMMAND_FAILED")
-  }
-
-  func testJournalStoredResponseStaysUnstamped() throws {
-    let journal = RunnerCommandJournal()
-    let recordStart = runnerJournalCommand("recordStart", id: "record-start-anchor")
-
-    journal.accept(command: recordStart)
-    journal.finish(
-      command: recordStart,
-      response: Response(ok: true, data: DataPayload(message: "recording started"))
-    )
-
-    let status = journal.status(normalizedCommandId: "record-start-anchor")
-    let responseJson = try XCTUnwrap(status.lifecycleResponseJson)
-    XCTAssertFalse(responseJson.contains("currentUptimeMs"))
-  }
-
-  func testCommandJournalRetentionPolicy() throws {
-    let journal = RunnerCommandJournal()
-
-    let uptime = runnerJournalCommand("uptime", id: "small-scalar")
-    journal.accept(command: uptime)
-    journal.finish(
-      command: uptime,
-      response: Response(ok: true, data: DataPayload(currentUptimeMs: 12.5))
-    )
-
-    let scalarStatus = journal.status(normalizedCommandId: "small-scalar")
-    XCTAssertEqual(scalarStatus.lifecycleState, RunnerCommandLifecycleState.completed.rawValue)
-    XCTAssertEqual(scalarStatus.lifecycleResponseOk, true)
-    XCTAssertNotNil(scalarStatus.lifecycleResponseJson)
-    let scalarResponse = try decodeRunnerJournalResponse(scalarStatus.lifecycleResponseJson)
-    XCTAssertEqual(scalarResponse.data?.currentUptimeMs, 12.5)
-
-    let querySelector = runnerJournalCommand("querySelector", id: "small-object")
-    journal.accept(command: querySelector)
-    journal.finish(
-      command: querySelector,
-      response: Response(ok: true, data: DataPayload(found: true, nodes: [runnerJournalNode()]))
-    )
-
-    let objectStatus = journal.status(normalizedCommandId: "small-object")
-    XCTAssertNotNil(objectStatus.lifecycleResponseJson)
-    let objectResponse = try decodeRunnerJournalResponse(objectStatus.lifecycleResponseJson)
-    XCTAssertEqual(objectResponse.data?.found, true)
-    XCTAssertEqual(objectResponse.data?.nodes?.count, 1)
-
-    let snapshot = runnerJournalCommand("snapshot", id: "snapshot-tree")
-    journal.accept(command: snapshot)
-    journal.finish(
-      command: snapshot,
-      response: Response(ok: true, data: DataPayload(nodes: [runnerJournalNode()], truncated: false))
-    )
-
-    let snapshotStatus = journal.status(normalizedCommandId: "snapshot-tree")
-    XCTAssertEqual(snapshotStatus.lifecycleState, RunnerCommandLifecycleState.completed.rawValue)
-    XCTAssertEqual(snapshotStatus.lifecycleResponseOk, true)
-    XCTAssertNil(snapshotStatus.lifecycleResponseJson)
-
-    let screenshot = runnerJournalCommand("screenshot", id: "screenshot-artifact")
-    journal.accept(command: screenshot)
-    journal.finish(
-      command: screenshot,
-      response: Response(ok: true, data: DataPayload(message: "tmp/screenshot-1.png"))
-    )
-
-    let screenshotStatus = journal.status(normalizedCommandId: "screenshot-artifact")
-    XCTAssertEqual(screenshotStatus.lifecycleState, RunnerCommandLifecycleState.completed.rawValue)
-    XCTAssertEqual(screenshotStatus.lifecycleResponseOk, true)
-    XCTAssertNil(screenshotStatus.lifecycleResponseJson)
-
-    let scroll = runnerJournalCommand("scroll", id: "scroll-drag")
-    journal.accept(command: scroll)
-    journal.finish(
-      command: scroll,
-      response: Response(
-        ok: true,
-        data: DataPayload(
-          message: "scrolled",
-          gestureStartUptimeMs: 1,
-          gestureEndUptimeMs: 2,
-          x: 155,
-          y: 420,
-          x2: 155,
-          y2: 301,
-          referenceWidth: 300,
-          referenceHeight: 600
-        )
-      )
-    )
-
-    let scrollStatus = journal.status(normalizedCommandId: "scroll-drag")
-    XCTAssertEqual(scrollStatus.lifecycleState, RunnerCommandLifecycleState.completed.rawValue)
-    XCTAssertEqual(scrollStatus.lifecycleResponseOk, true)
-    XCTAssertNotNil(scrollStatus.lifecycleResponseJson)
-    let scrollResponse = try decodeRunnerJournalResponse(scrollStatus.lifecycleResponseJson)
-    XCTAssertEqual(scrollResponse.data?.x, 155)
-    XCTAssertEqual(scrollResponse.data?.y, 420)
-    XCTAssertEqual(scrollResponse.data?.x2, 155)
-    XCTAssertEqual(scrollResponse.data?.y2, 301)
-    XCTAssertEqual(scrollResponse.data?.referenceWidth, 300)
-    XCTAssertEqual(scrollResponse.data?.referenceHeight, 600)
-
-    let largeRead = runnerJournalCommand("readText", id: "large-read")
-    journal.accept(command: largeRead)
-    journal.finish(
-      command: largeRead,
-      response: Response(ok: true, data: DataPayload(text: String(repeating: "x", count: 17 * 1024)))
-    )
-
-    let largeReadStatus = journal.status(normalizedCommandId: "large-read")
-    XCTAssertEqual(largeReadStatus.lifecycleState, RunnerCommandLifecycleState.completed.rawValue)
-    XCTAssertEqual(largeReadStatus.lifecycleResponseOk, true)
-    XCTAssertNil(largeReadStatus.lifecycleResponseJson)
-  }
-
-  func testCommandJournalKeepsErrorMetadataWhenResponseJsonIsDropped() {
-    let journal = RunnerCommandJournal()
-    let snapshot = runnerJournalCommand("snapshot", id: "snapshot-error")
-    let hint = "Try a smaller read such as snapshot -s <visible label or id> -d 8."
-
-    journal.accept(command: snapshot)
-    journal.finish(
-      command: snapshot,
-      response: Response(
-        ok: false,
-        error: ErrorPayload(
-          code: "IOS_AX_SNAPSHOT_FAILED",
-          message: "iOS XCTest snapshot failed while serializing the accessibility tree.",
-          hint: hint
-        )
-      )
-    )
-
-    let status = journal.status(normalizedCommandId: "snapshot-error")
-    XCTAssertEqual(status.lifecycleState, RunnerCommandLifecycleState.failed.rawValue)
-    XCTAssertEqual(status.lifecycleResponseOk, false)
-    XCTAssertNil(status.lifecycleResponseJson)
-    XCTAssertEqual(status.lifecycleErrorCode, "IOS_AX_SNAPSHOT_FAILED")
-    XCTAssertEqual(
-      status.lifecycleErrorMessage,
-      "iOS XCTest snapshot failed while serializing the accessibility tree."
-    )
-    XCTAssertEqual(status.lifecycleErrorHint, hint)
-  }
-
-  func testCommandJournalRetainsCompletedSequenceResults() throws {
-    let journal = RunnerCommandJournal()
-    let sequence = runnerJournalCommand("sequence", id: "sequence-completed")
-    let results = (0..<20).map { _ in
-      SequenceStepResult(
-        ok: true,
-        kind: "tap",
-        errorCode: nil,
-        errorMessage: nil,
-        gestureStartUptimeMs: 100,
-        gestureEndUptimeMs: 120
-      )
-    }
-
-    journal.accept(command: sequence)
-    journal.finish(
-      command: sequence,
-      response: Response(
-        ok: true,
-        data: DataPayload(
-          message: "sequence",
-          completedSteps: 20,
-          failedStepIndex: nil,
-          sequenceResults: results
-        )
-      )
-    )
-
-    let status = journal.status(normalizedCommandId: "sequence-completed")
-    XCTAssertEqual(status.lifecycleState, RunnerCommandLifecycleState.completed.rawValue)
-    XCTAssertEqual(status.lifecycleResponseOk, true)
-    let json = try XCTUnwrap(status.lifecycleResponseJson)
-    // Worst-case 20-step response must stay under the 16KB journal retention cap.
-    XCTAssertLessThan(json.utf8.count, 16 * 1024)
-    let decoded = try decodeRunnerJournalResponse(status.lifecycleResponseJson)
-    XCTAssertEqual(decoded.data?.completedSteps, 20)
-    XCTAssertEqual(decoded.data?.sequenceResults?.count, 20)
-  }
-
-  func testCommandJournalRetainsFailedSequenceResults() throws {
-    let journal = RunnerCommandJournal()
-    let sequence = runnerJournalCommand("sequence", id: "sequence-failed")
-    let longError = String(repeating: "z", count: 200)
-    let results: [SequenceStepResult] = [
-      SequenceStepResult(ok: true, kind: "tap", errorCode: nil, errorMessage: nil,
-                         gestureStartUptimeMs: 100, gestureEndUptimeMs: 120),
-      SequenceStepResult(ok: true, kind: "tap", errorCode: nil, errorMessage: nil,
-                         gestureStartUptimeMs: 130, gestureEndUptimeMs: 150),
-      SequenceStepResult(ok: false, kind: "longPress", errorCode: "UNSUPPORTED_OPERATION",
-                         errorMessage: longError, gestureStartUptimeMs: 160, gestureEndUptimeMs: 180),
-    ]
-
-    journal.accept(command: sequence)
-    journal.finish(
-      command: sequence,
-      response: Response(
-        ok: true,
-        data: DataPayload(
-          message: "sequence",
-          completedSteps: 2,
-          failedStepIndex: 2,
-          sequenceResults: results
-        )
-      )
-    )
-
-    let status = journal.status(normalizedCommandId: "sequence-failed")
-    XCTAssertEqual(status.lifecycleState, RunnerCommandLifecycleState.completed.rawValue)
-    let decoded = try decodeRunnerJournalResponse(status.lifecycleResponseJson)
-    XCTAssertEqual(decoded.data?.completedSteps, 2)
-    XCTAssertEqual(decoded.data?.failedStepIndex, 2)
-    XCTAssertEqual(decoded.data?.sequenceResults?.count, 3)
-    XCTAssertEqual(decoded.data?.sequenceResults?[2].ok, false)
-    XCTAssertEqual(decoded.data?.sequenceResults?[2].errorCode, "UNSUPPORTED_OPERATION")
-  }
-
-  private func runnerJournalCommand(_ command: String, id: String) -> Command {
-    let json = #"{"command":"\#(command)","commandId":"\#(id)"}"#
-    return try! JSONDecoder().decode(Command.self, from: Data(json.utf8))
-  }
-
-  private func runnerJournalNode() -> PresentedNode {
-    SnapshotPresentation.singleElementRead(
-      RawAXNode(
-        index: 0,
-        type: "button",
-        label: "Continue",
-        identifier: "continue",
-        value: nil,
-        rect: SnapshotRect(x: 10, y: 20, width: 100, height: 44),
-        enabled: true,
-        focused: nil,
-        selected: nil,
-        hittable: true,
-        depth: 0,
-        parentIndex: nil,
-        hiddenContentAbove: nil,
-        hiddenContentBelow: nil
-      )
-    )
-  }
-
-  private func decodeRunnerJournalResponse(_ responseJson: String?) throws -> Response {
-    let responseJson = try XCTUnwrap(responseJson)
-    return try JSONDecoder().decode(Response.self, from: Data(responseJson.utf8))
-  }
-}
-#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift
index 8f0a101429..002459b19c 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift
@@ -602,27 +602,4 @@ extension RunnerTests {
 #endif
   }
 #endif
-
-#if AGENT_DEVICE_RUNNER_UNIT_TESTS
-  func testDesktopScrollWheelDeltasMapDirections() {
-    XCTAssertEqual(desktopScrollWheelDeltas(direction: .up, pixels: 120).vertical, 120)
-    XCTAssertEqual(desktopScrollWheelDeltas(direction: .down, pixels: 120).vertical, -120)
-    XCTAssertEqual(desktopScrollWheelDeltas(direction: .left, pixels: 120).horizontal, 120)
-    XCTAssertEqual(desktopScrollWheelDeltas(direction: .right, pixels: 120).horizontal, -120)
-  }
-
-  func testDesktopScrollWheelDeltaEventsHonorDurationAndPreservePixels() {
-    let events = desktopScrollWheelDeltaEvents(direction: .down, pixels: 200, durationMs: 50)
-    XCTAssertEqual(events.count, 4)
-    XCTAssertEqual(events.map(\.vertical).reduce(0, +), -200)
-    XCTAssertEqual(events.map(\.horizontal).reduce(0, +), 0)
-    XCTAssertEqual(desktopScrollEventIntervalSeconds(durationMs: 50, eventCount: events.count), 0.05 / 3.0)
-  }
-
-  func testDesktopScrollWheelDeltaEventsKeepInstantScrollSingleEvent() {
-    let events = desktopScrollWheelDeltaEvents(direction: .down, pixels: 200, durationMs: 0)
-    XCTAssertEqual(events.count, 1)
-    XCTAssertEqual(events.first?.vertical, -200)
-  }
-#endif
 }
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Keyboard.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Keyboard.swift
index a3fab3fad7..d743ec2a7c 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Keyboard.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Keyboard.swift
@@ -447,145 +447,3 @@ func runnerScreenshotStabilitySettled(
   guard let first = window.first, let firstData = first else { return false }
   return window.allSatisfy { $0 == firstData }
 }
-
-#if AGENT_DEVICE_RUNNER_UNIT_TESTS
-extension RunnerTests {
-  func testKeyboardBandFactReadFailureIsStatedAsUnmeasurableNotAbsence() {
-    // Absence would let a consumer claim the screen is clear of a keyboard on the strength of a read
-    // that never answered.
-    let fact = runnerKeyboardBandFact(
-      readSucceeded: false,
-      exists: false,
-      frame: CGRect(x: 0, y: 198, width: 402, height: 204)
-    )
-    XCTAssertEqual(fact, .unmeasurable(RunnerKeyboardBandReason.queryFailed))
-    XCTAssertEqual(fact.payload.kind, "unmeasurable")
-    XCTAssertEqual(fact.payload.reason, RunnerKeyboardBandReason.queryFailed)
-    XCTAssertNil(fact.payload.frame)
-  }
-
-  func testKeyboardBandFactPublishesAbsenceWhenTheQueryFindsNoKeyboard() {
-    let fact = runnerKeyboardBandFact(readSucceeded: true, exists: false, frame: .zero)
-    XCTAssertEqual(fact, .absent)
-    XCTAssertEqual(fact.payload.kind, "absent")
-    XCTAssertNil(fact.payload.frame)
-    XCTAssertNil(fact.payload.reason)
-  }
-
-  func testKeyboardBandFactPublishesTheMeasuredBandInAppOrientationSpace() {
-    // The landscape band measured on iPhone 17 Pro (iOS 26.2) after #2653: full width across the
-    // bottom of a 402 pt-tall app, which is what the tree reported as a strip down the left edge.
-    let frame = CGRect(x: 0, y: 198, width: 874, height: 204)
-    let fact = runnerKeyboardBandFact(readSucceeded: true, exists: true, frame: frame)
-    XCTAssertEqual(fact, .visible(frame))
-    let payload = fact.payload
-    XCTAssertEqual(payload.kind, "visible")
-    XCTAssertEqual(payload.frame, SnapshotRect(x: 0, y: 198, width: 874, height: 204))
-    XCTAssertNil(payload.reason)
-  }
-
-  func testKeyboardBandFactRefusesUnusableGeometryInsteadOfClaimingAbsence() {
-    let nan = CGFloat(Double.nan)
-    let infinite = CGFloat.infinity
-    let unusable: [CGRect] = [
-      .zero,
-      CGRect(x: 0, y: 198, width: 0, height: 204),
-      CGRect(x: 0, y: 198, width: 874, height: -1),
-      CGRect(x: 0, y: 198, width: -874, height: 204),
-      CGRect(x: 0, y: nan, width: 874, height: 204),
-      CGRect(x: 0, y: 198, width: nan, height: 204),
-      CGRect(x: infinite, y: 198, width: 874, height: 204)
-    ]
-    for frame in unusable {
-      let fact = runnerKeyboardBandFact(readSucceeded: true, exists: true, frame: frame)
-      XCTAssertEqual(
-        fact,
-        .unmeasurable(RunnerKeyboardBandReason.unusableFrame),
-        "expected \(frame) to be refused as a band"
-      )
-    }
-  }
-
-  func testKeyboardBandFactPayloadRoundTripsThroughTheWireShape() throws {
-    let cases: [RunnerKeyboardBandFact] = [
-      .visible(CGRect(x: 0, y: 583, width: 402, height: 291)),
-      .absent,
-      .unmeasurable(RunnerKeyboardBandReason.queryTimeout)
-    ]
-    for fact in cases {
-      let data = try JSONEncoder().encode(fact.payload)
-      // `encodeIfPresent` for the two optional fields: a fact carries its own evidence and nothing
-      // else, so the daemon never has to distinguish a null from an absent key.
-      let object = try XCTUnwrap(JSONSerialization.jsonObject(with: data) as? [String: Any])
-      switch fact {
-      case .visible:
-        XCTAssertNil(object["reason"])
-        XCTAssertNotNil(object["frame"])
-      case .absent:
-        XCTAssertNil(object["frame"])
-        XCTAssertNil(object["reason"])
-      case .unmeasurable:
-        XCTAssertNil(object["frame"])
-        XCTAssertNotNil(object["reason"])
-      }
-      XCTAssertEqual(try JSONDecoder().decode(KeyboardBandFactPayload.self, from: data), fact.payload)
-    }
-  }
-
-  func testRunnerScreenshotStabilitySettledNeedsEnoughSamples() {
-    XCTAssertFalse(runnerScreenshotStabilitySettled([], requiredConsecutiveMatches: 3))
-    XCTAssertFalse(runnerScreenshotStabilitySettled([Data([1])], requiredConsecutiveMatches: 3))
-    let frame = Data([1, 2, 3])
-    XCTAssertFalse(
-      runnerScreenshotStabilitySettled([frame, frame], requiredConsecutiveMatches: 3)
-    )
-  }
-
-  func testRunnerScreenshotStabilitySettledTrueWhenWindowMatches() {
-    let frame = Data([1, 2, 3])
-    XCTAssertTrue(
-      runnerScreenshotStabilitySettled([Data([9]), frame, frame, frame], requiredConsecutiveMatches: 3)
-    )
-  }
-
-  func testRunnerScreenshotStabilitySettledFalseOnMidWindowMismatch() {
-    // A momentary pause (two matching samples) followed by resumed movement
-    // must not read as settled: the 3-sample window still spans the mismatch.
-    let frame = Data([1, 2, 3])
-    let moved = Data([4, 5, 6])
-    XCTAssertFalse(
-      runnerScreenshotStabilitySettled([frame, frame, moved], requiredConsecutiveMatches: 3)
-    )
-  }
-
-  func testRunnerScreenshotStabilitySettledFalseOnFailedCapture() {
-    // A nil sample (failed screenshot) never counts as a match, even against
-    // other nils — an unverifiable run must not look "stable".
-    XCTAssertFalse(runnerScreenshotStabilitySettled([nil, nil, nil], requiredConsecutiveMatches: 3))
-    let frame = Data([1, 2, 3])
-    XCTAssertFalse(
-      runnerScreenshotStabilitySettled([frame, frame, nil], requiredConsecutiveMatches: 3)
-    )
-  }
-
-  func testRunnerScreenshotStabilitySettledOnlyLooksAtTheTrailingWindow() {
-    // An older mismatch before the trailing window must not block settlement
-    // once the required run of most-recent samples agrees.
-    let frame = Data([9])
-    XCTAssertTrue(
-      runnerScreenshotStabilitySettled(
-        [Data([1]), Data([2]), frame, frame, frame],
-        requiredConsecutiveMatches: 3
-      )
-    )
-  }
-
-  func testRunnerScreenshotStabilitySettledRejectsDegenerateRequirement() {
-    // Fewer than 2 required matches would make any single sample "settled" —
-    // guard against a misconfigured caller rather than silently no-op the wait.
-    XCTAssertFalse(
-      runnerScreenshotStabilitySettled([Data([1])], requiredConsecutiveMatches: 1)
-    )
-  }
-}
-#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Lifecycle.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Lifecycle.swift
index 57e4467cd3..0314cbab9b 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Lifecycle.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Lifecycle.swift
@@ -505,33 +505,3 @@ extension RunnerTests {
     usleep(useconds_t(delay * 1_000_000))
   }
 }
-
-#if AGENT_DEVICE_RUNNER_UNIT_TESTS
-extension RunnerTests {
-  func testResettingTargetBoundStateForgetsTheLastWrittenMarkers() {
-    defer { invalidateCachedTarget(reason: "unit_test_cleanup") }
-    lastLoggedFastAppGuardLine = "AGENT_DEVICE_RUNNER_FAST_APP_GUARD bundle=app state=4"
-    lastLoggedGesturePolicyLines[.scroll] = "AGENT_DEVICE_RUNNER_SYNTHESIZED_GESTURE_POLICY kind=scroll"
-    resetTargetBoundState()
-    XCTAssertNil(lastLoggedFastAppGuardLine, "a rebind must state the guard once more")
-    XCTAssertTrue(lastLoggedGesturePolicyLines.isEmpty, "a rebind must state the policy once more")
-  }
-
-  func testFastAppGuardMarkerWritesOnceUntilTheFactChanges() {
-    var written: [String] = []
-    runnerMarkerWriter = { written.append($0) }
-    defer {
-      runnerMarkerWriter = { NSLog("%@", $0) }
-      invalidateCachedTarget(reason: "unit_test_cleanup")
-    }
-    writeFastAppGuardMarker(bundleId: "com.example.app", state: .runningForeground)
-    writeFastAppGuardMarker(bundleId: "com.example.app", state: .runningForeground)
-    XCTAssertEqual(written.count, 1, "a repeated fact writes no second line")
-    writeFastAppGuardMarker(bundleId: "com.example.other", state: .runningForeground)
-    XCTAssertEqual(written.count, 2, "a changed fact writes a new line")
-    resetTargetBoundState()
-    writeFastAppGuardMarker(bundleId: "com.example.other", state: .runningForeground)
-    XCTAssertEqual(written.count, 3, "a rebind states the same fact once more")
-  }
-}
-#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+MainThreadWork.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+MainThreadWork.swift
index c0dafe8f05..d624b10ba6 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+MainThreadWork.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+MainThreadWork.swift
@@ -135,95 +135,3 @@ extension RunnerTests {
     )
   }
 }
-
-#if AGENT_DEVICE_RUNNER_UNIT_TESTS
-extension RunnerTests {
-  func testRunMainThreadWorkExecutesOffMainCallerOnMainThread() {
-    final class ResultBox {
-      var observedMainThread: Bool?
-      var error: Error?
-    }
-    let box = ResultBox()
-    let finished = expectation(description: "off-main caller finished")
-
-    DispatchQueue(label: "agent-device.runner.tests.off-main").async {
-      do {
-        box.observedMainThread = try self.runMainThreadWork(
-          "command_execution",
-          timeout: 1,
-          timeoutError: self.mainThreadExecutionTimeoutError
-        ) {
-          Thread.isMainThread
-        }
-      } catch {
-        box.error = error
-      }
-      finished.fulfill()
-    }
-
-    wait(for: [finished], timeout: 2)
-    XCTAssertNil(box.error)
-    XCTAssertEqual(box.observedMainThread, true)
-  }
-
-  func testRunMainThreadWorkTimeoutMarksAbandonedUntilDrained() {
-    final class ResultBox {
-      var error: Error?
-      var abandonedCount: Int?
-      var abandonedSinceSet: Bool?
-      var busyWhileAbandoned = false
-    }
-    let box = ResultBox()
-    let releaseWork = DispatchSemaphore(value: 0)
-    let observedAbandoned = DispatchSemaphore(value: 0)
-    let timedOut = expectation(description: "off-main caller timed out")
-
-    DispatchQueue(label: "agent-device.runner.tests.timeout").async {
-      do {
-        _ = try self.runMainThreadWork(
-          "command_execution",
-          timeout: 0,
-          timeoutError: self.mainThreadExecutionTimeoutError
-        ) {
-          _ = releaseWork.wait(timeout: .now() + 2)
-          return true
-        }
-      } catch {
-        box.error = error
-      }
-      self.mainThreadWorkLock.lock()
-      box.abandonedCount = self.abandonedMainThreadWorkCount
-      box.abandonedSinceSet = self.abandonedMainThreadWorkSince != nil
-      self.mainThreadWorkLock.unlock()
-      if case .busy = self.currentMainThreadBusyState() {
-        box.busyWhileAbandoned = true
-      }
-      observedAbandoned.signal()
-      timedOut.fulfill()
-    }
-    DispatchQueue(label: "agent-device.runner.tests.release-timeout").async {
-      _ = observedAbandoned.wait(timeout: .now() + 2)
-      releaseWork.signal()
-    }
-
-    wait(for: [timedOut], timeout: 3)
-    let drainDeadline = Date().addingTimeInterval(2)
-    while hasAbandonedMainThreadWork(), Date() < drainDeadline {
-      sleepFor(0.005)
-    }
-
-    XCTAssertEqual((box.error as NSError?)?.code, RunnerErrorCode.mainThreadExecutionTimedOut)
-    XCTAssertEqual(box.abandonedCount, 1)
-    XCTAssertEqual(box.abandonedSinceSet, true)
-    XCTAssertTrue(box.busyWhileAbandoned)
-    XCTAssertFalse(hasAbandonedMainThreadWork(), "drained work must release the main thread")
-    mainThreadWorkLock.lock()
-    let sinceCleared = abandonedMainThreadWorkSince == nil
-    mainThreadWorkLock.unlock()
-    XCTAssertTrue(sinceCleared)
-    guard case .idle = currentMainThreadBusyState() else {
-      return XCTFail("expected the runner idle once the abandoned work drained")
-    }
-  }
-}
-#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Navigation.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Navigation.swift
index 650d7559bb..a4df398737 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Navigation.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Navigation.swift
@@ -303,170 +303,4 @@ extension RunnerTests {
     let element = app.descendants(matching: .any).matching(predicate).firstMatch
     return element.exists ? element : nil
   }
-
-#if AGENT_DEVICE_RUNNER_UNIT_TESTS
-  func testTopLeadingNavigationFallbackPointTargetsHeaderControlBand() throws {
-    let point = try XCTUnwrap(
-      Self.topLeadingNavigationFallbackPoint(
-        in: CGRect(x: 0, y: 0, width: 430, height: 932)
-      )
-    )
-
-    XCTAssertEqual(point.x, 34.4, accuracy: 0.01)
-    XCTAssertEqual(point.y, 132, accuracy: 0.01)
-  }
-
-  func testTopLeadingNavigationFallbackPointRejectsInvalidFrame() {
-    XCTAssertNil(Self.topLeadingNavigationFallbackPoint(in: .infinite))
-    XCTAssertNil(Self.topLeadingNavigationFallbackPoint(in: .zero))
-  }
-
-  func testNavigationBackControlRankPrefersBackThenCloseThenCancel() {
-    XCTAssertEqual(Self.navigationBackControlRank(label: "Back", identifier: ""), 0)
-    XCTAssertEqual(Self.navigationBackControlRank(label: "Close", identifier: ""), 1)
-    XCTAssertEqual(Self.navigationBackControlRank(label: "Cancel search", identifier: ""), 2)
-    XCTAssertNil(Self.navigationBackControlRank(label: "Search for more feeds", identifier: ""))
-  }
-
-  func testNavigationBackPredicateUsesTheSharedKeywordTable() {
-    let predicate = Self.navigationBackPredicate()
-
-    XCTAssertTrue(predicate.evaluate(with: ["label": "Back", "identifier": ""]))
-    XCTAssertTrue(predicate.evaluate(with: ["label": "", "identifier": "close-button"]))
-    XCTAssertFalse(predicate.evaluate(with: ["label": "Search for more feeds", "identifier": ""]))
-  }
-
-  func testTopNavigationControlFrameAcceptsOnlyHeaderBand() {
-    let window = CGRect(x: 0, y: 0, width: 430, height: 932)
-
-    XCTAssertTrue(
-      Self.isTopNavigationControlFrame(
-        CGRect(x: 340, y: 84, width: 72, height: 44),
-        in: window
-      )
-    )
-    XCTAssertFalse(
-      Self.isTopNavigationControlFrame(
-        CGRect(x: 20, y: 760, width: 72, height: 44),
-        in: window
-      )
-    )
-    XCTAssertFalse(Self.isTopNavigationControlFrame(.infinite, in: window))
-  }
-
-  func testNavigationVisualVerificationSeparatesNoChangeFromNoSample() {
-    XCTAssertEqual(
-      Self.navigationVisualObservation(before: Data([1, 2, 3]), after: Data([1, 2, 4])),
-      .changed
-    )
-    XCTAssertEqual(
-      Self.navigationVisualObservation(before: Data([1, 2, 3]), after: Data([1, 2, 3])),
-      .unchanged
-    )
-    // A missing sample is neither a change nor a no-change; treating it as "unchanged" would let a
-    // capture that refused become the reason the `back` command claims no control exists (#2728).
-    XCTAssertEqual(Self.navigationVisualObservation(before: nil, after: Data([1])), .unobserved)
-    XCTAssertEqual(Self.navigationVisualObservation(before: Data([1]), after: nil), .unobserved)
-    XCTAssertEqual(Self.navigationVisualObservation(before: nil, after: nil), .unobserved)
-  }
-
-  func testNavigationFallbackReportsTheRefusalItHitNotADefaultCode() {
-    // The refusal from the most recent sample wins, so the code names what the fallback last looked at
-    // before giving up; an earlier refusal is reported only when the later sample carried none (#2728).
-    let after = NavigationVisualSample(
-      data: nil,
-      refusalCode: "APP_SCREEN_WINDOW_UNRESOLVED",
-      refusalHint: "after hint"
-    )
-    let before = NavigationVisualSample(
-      data: nil,
-      refusalCode: "APP_SCREEN_UNRESOLVED",
-      refusalHint: "before hint"
-    )
-    let laterWins = Self.navigationFallbackErrorPayload(after: after, before: before)
-    XCTAssertEqual(laterWins.code, "APP_SCREEN_WINDOW_UNRESOLVED")
-    XCTAssertEqual(laterWins.hint, "after hint")
-
-    let onlyBefore = Self.navigationFallbackErrorPayload(
-      after: NavigationVisualSample(data: nil),
-      before: before
-    )
-    XCTAssertEqual(onlyBefore.code, "APP_SCREEN_UNRESOLVED")
-    XCTAssertEqual(onlyBefore.hint, "before hint")
-
-    // Neither side named a reason (unreachable on iOS): a real capture code, never a bare failure.
-    let unnamed = Self.navigationFallbackErrorPayload(
-      after: NavigationVisualSample(data: nil),
-      before: NavigationVisualSample(data: nil)
-    )
-    XCTAssertEqual(unnamed.code, "APP_SCREEN_UNRESOLVED")
-    XCTAssertTrue(unnamed.message.contains("unknown outcome"))
-  }
-
-  func testVerifyNavigationFallbackOutcomeReportsUnresolvedWindowWithoutSystemSurface() {
-    // The in-app `back` fallback ran its tap but the app resolved no window. It must name that refusal
-    // as an unknown outcome AND must not have sampled the system surface: capturing SpringBoard's home
-    // screen twice reads as "unchanged" and launders a wrong-process frame into "no back control
-    // exists" (#2728). This drives the SAME `navigationFallbackSample` production calls, handing it a
-    // system surface that fails the test if consulted — so reverting the fallback to sample SpringBoard
-    // (or dropping the refusal code) turns this red, which an inline `.never` re-creation could not.
-    var askedSystemSurface = false
-    let sample = Self.navigationFallbackSample(
-      resolvingApp: { .failure(.unresolvedWindow) },
-      systemSurface: {
-        askedSystemSurface = true
-        return .failure(.unresolvedWindow)
-      },
-      encoding: { _ in Data([1, 2, 3]) }
-    )
-    XCTAssertFalse(askedSystemSurface, "the in-app fallback samples the app only, never SpringBoard")
-
-    XCTAssertNil(sample.data)
-    XCTAssertEqual(sample.refusalCode, "APP_SCREEN_WINDOW_UNRESOLVED")
-
-    let observation = Self.navigationVisualObservation(before: sample.data, after: sample.data)
-    XCTAssertEqual(observation, .unobserved)
-
-    switch Self.inAppBackOutcome(observation: observation, before: sample, after: sample) {
-    case .unverified(let payload):
-      XCTAssertEqual(payload.code, "APP_SCREEN_WINDOW_UNRESOLVED")
-    case .performed, .unavailable:
-      XCTFail("a refused capture must report an unknown outcome, not 'no back control'")
-    }
-  }
-
-  func testNavigationVisualSampleDistinguishesEncodedFrameFromRefusal() {
-    // The same capture entry point yields three different samples, and only the refusal ones may carry
-    // a code: an encoded frame is evidence, a resolved-but-unencodable image and a refusal are not
-    // (#2728). Reverting the mapping to a plain no-sample loses the reason a host keys on.
-    let captured = CapturedAppScreen(
-      image: RunnerImage(),
-      displayID: 3,
-      pixelWidth: 12,
-      pixelHeight: 24,
-      pixelsPerPoint: 3
-    )
-
-    let encoded = Self.navigationVisualSample(
-      from: .success(captured),
-      encoding: { _ in Data([7, 7]) }
-    )
-    XCTAssertEqual(encoded.data, Data([7, 7]))
-    XCTAssertNil(encoded.refusalCode)
-
-    let unencodable = Self.navigationVisualSample(
-      from: .success(captured),
-      encoding: { _ in nil }
-    )
-    XCTAssertNil(unencodable.data)
-    XCTAssertEqual(unencodable.refusalCode, "APP_SCREEN_CAPTURE_UNRENDERABLE")
-
-    let refused = Self.navigationVisualSample(
-      from: .failure(.unresolvedScreen),
-      encoding: { _ in Data([7, 7]) }
-    )
-    XCTAssertNil(refused.data)
-    XCTAssertEqual(refused.refusalCode, "APP_SCREEN_UNRESOLVED")
-  }
-#endif
 }
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+PrivateAXPresentation.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+PrivateAXPresentation.swift
index 202e2d061b..b95b1dc5a1 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+PrivateAXPresentation.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+PrivateAXPresentation.swift
@@ -89,212 +89,3 @@ extension RunnerTests {
     (value as? Bool) ?? (value as? NSNumber)?.boolValue
   }
 }
-
-#if AGENT_DEVICE_RUNNER_UNIT_TESTS
-extension RunnerTests {
-  fileprivate static func privateAXFrame(
-    _ x: Double, _ y: Double, _ width: Double, _ height: Double
-  ) -> [String: Any] {
-    ["x": x, "y": y, "width": width, "height": height]
-  }
-
-  /// A scroll container whose second row is scrolled out of the viewport, plus an unlabeled
-  /// decoration: the shapes the regular projection folds away and the raw projection must keep.
-  fileprivate static var privateAXScrolledFixture: [String: Any] {
-    let frame = privateAXFrame
-    return ["type": Int(XCUIElement.ElementType.application.rawValue),
-      "label": "Element", "frame": frame(0, 0, 402, 874), "children": [[
-        "type": Int(XCUIElement.ElementType.scrollView.rawValue), "frame": frame(0, 96, 402, 700),
-        "actions": ["Scroll down"],
-        "children": [
-          ["type": Int(XCUIElement.ElementType.button.rawValue), "label": "Profile picture",
-            "frame": frame(16, 120, 44, 44),
-            "children": [["type": Int(XCUIElement.ElementType.image.rawValue),
-              "frame": frame(16, 120, 1, 1)]]],
-          ["type": Int(XCUIElement.ElementType.button.rawValue), "label": "Theme",
-            "frame": frame(16, 900, 360, 44)]]]]]
-  }
-
-  /// Acquire with the private-AX serializer, run the one normalization pass the production capture
-  /// plan runs (`captureWithBackend`), then present through the shared regular fold -- the production
-  /// route for this backend since the fold moved into presentation (#1797, #2661).
-  fileprivate func privateAXRegularPresentation(
-    rawRoot: [String: Any],
-    viewport: CGRect,
-    interactiveOnly: Bool = false
-  ) throws -> [PresentedNode] {
-    let hint = CaptureHint(
-      projection: .regular, depth: nil, regularPresentedDepth: nil,
-      interactiveOnly: interactiveOnly, customActions: false)
-    let nodes = privateAXNormalizedAcquisition(
-      rawRoot: rawRoot, hint: hint, viewport: viewport,
-      interfaceOrientation: RunnerInterfaceOrientation.portrait)
-    return try SnapshotPresentation.presentRegular(
-      SnapshotAcquisition(
-        hint: hint, nodes: nodes, truncated: false, effectiveDepth: nil, viewport: viewport,
-        interfaceOrientation: RunnerInterfaceOrientation.portrait),
-      options: PresentationOptions(
-        interactiveOnly: interactiveOnly, depth: nil, scope: nil, raw: false),
-      policy: .cursorProjected
-    ).nodes
-  }
-
-  /// Acquire, then normalize once -- the exact pair `captureWithBackend` runs for this backend.
-  fileprivate func privateAXNormalizedAcquisition(
-    rawRoot: [String: Any],
-    hint: CaptureHint,
-    viewport: CGRect,
-    interfaceOrientation: Int
-  ) -> [RawAXNode] {
-    SnapshotGeometrySpace.normalized(
-      nodes: privateAXAcquisition(rawRoot: rawRoot, hint: hint),
-      viewport: viewport,
-      interfaceOrientation: interfaceOrientation
-    )
-  }
-
-  /// The one normalization pass has to reach the node it publishes: this asserts the rotated rect of
-  /// a key under a turned surface host, and an untouched sibling under the app's own window, so a
-  /// pass that drops the space a subtree declared fails here.
-  func testPrivateAXAcquisitionPublishesATurnedSurfaceHostInAppOrientationSpace() {
-    let frame = Self.privateAXFrame
-    let appWindow: [String: Any] = [
-      "type": Int(XCUIElement.ElementType.window.rawValue),
-      "frame": frame(0, 0, 874, 402),
-      "children": [
-        ["type": Int(XCUIElement.ElementType.button.rawValue), "label": "Home",
-          "frame": frame(204, 323, 91, 55), "children": []]
-      ]
-    ]
-    let keyboardWindow: [String: Any] = [
-      "type": Int(XCUIElement.ElementType.window.rawValue),
-      "frame": frame(0, 0, 874, 402),
-      "children": [
-        ["type": Int(XCUIElement.ElementType.other.rawValue),
-          "frame": frame(0, 0, 402, 874),
-          "children": [
-            ["type": Int(XCUIElement.ElementType.key.rawValue), "label": "q",
-              "frame": frame(154, 77, 45, 72), "children": []]
-          ]]
-      ]
-    ]
-    let hint = CaptureHint(
-      projection: .raw, depth: nil, regularPresentedDepth: nil,
-      interactiveOnly: false, customActions: false)
-    let nodes = privateAXNormalizedAcquisition(
-      rawRoot: [
-        "type": Int(XCUIElement.ElementType.application.rawValue),
-        "label": "Element", "frame": frame(0, 0, 874, 402),
-        "children": [appWindow, keyboardWindow]
-      ],
-      hint: hint,
-      viewport: CGRect(x: 0, y: 0, width: 874, height: 402),
-      interfaceOrientation: RunnerInterfaceOrientation.landscapeRight
-    )
-
-    // Measured on iPhone 17 Pro (26.2): the key plane's left column arrives 154 pt along the device's
-    // long axis and comes back 203 pt down the app's short one.
-    XCTAssertEqual(
-      nodes.first { $0.label == "q" }?.rect,
-      SnapshotRect(x: 77, y: 203, width: 72, height: 45)
-    )
-    XCTAssertEqual(
-      nodes.first { $0.label == "Home" }?.rect,
-      SnapshotRect(x: 204, y: 323, width: 91, height: 55)
-    )
-  }
-
-  func testPrivateAXRegularPresentationProjectsToViewportAndKeepsScrollHint() throws {
-    let nodes = try privateAXRegularPresentation(
-      rawRoot: Self.privateAXScrolledFixture,
-      viewport: CGRect(x: 0, y: 0, width: 402, height: 874))
-    XCTAssertEqual(nodes.compactMap(\.label), ["Element", "Profile picture"])
-    let scrollView = nodes.first { $0.type == "ScrollView" }
-    XCTAssertEqual(scrollView?.hiddenContentBelow, true)
-    XCTAssertEqual(scrollView?.actions, ["Scroll down"])
-  }
-
-  /// #1797 D4: the raw projection is the acquired tree. The offscreen row and the sub-pixel
-  /// decoration the regular projection folds away are both present, at traversal depth, and every
-  /// regular node still appears -- `regular ⊆ raw` on the same capture.
-  func testPrivateAXRawProjectionKeepsEveryAcquiredNode() throws {
-    let viewport = CGRect(x: 0, y: 0, width: 402, height: 874)
-    let root = Self.privateAXScrolledFixture
-    let regular = try privateAXRegularPresentation(rawRoot: root, viewport: viewport,
-      interactiveOnly: true)
-    let raw = privateAXNormalizedAcquisition(rawRoot: root,
-      hint: CaptureHint(
-        projection: .raw, depth: nil, regularPresentedDepth: nil,
-        interactiveOnly: false, customActions: false),
-      viewport: viewport,
-      interfaceOrientation: RunnerInterfaceOrientation.portrait)
-
-    XCTAssertEqual(raw.map(\.type), ["Application", "ScrollView", "Button", "Image", "Button"])
-    XCTAssertEqual(raw.map(\.depth), [0, 1, 2, 3, 2])
-    XCTAssertEqual(raw.map(\.parentIndex), [nil, 0, 1, 2, 1])
-    XCTAssertEqual(raw.compactMap(\.label), ["Element", "Profile picture", "Theme"])
-    // The offscreen row is a reported fact in raw, and reported facts do not become hittable
-    // just because the projection kept them.
-    XCTAssertEqual(raw.last?.hittable, false)
-    XCTAssertTrue(raw.allSatisfy { $0.hiddenContentAbove == nil && $0.hiddenContentBelow == nil })
-
-    let rawKeys = Set(raw.map { "\($0.type)-\($0.label ?? "")-\($0.rect.y)" })
-    for node in regular {
-      XCTAssertTrue(
-        rawKeys.contains("\(node.type)-\(node.label ?? "")-\(node.rect.y)"),
-        "regular node \(node.type)/\(node.label ?? "") is missing from the raw projection"
-      )
-    }
-    XCTAssertGreaterThan(raw.count, regular.count)
-  }
-
-  /// Raw depth is traversal depth, so a raw `--depth` request is the one narrowing this backend
-  /// can prove complete.
-  func testPrivateAXRawProjectionAppliesRequestedTraversalDepth() {
-    let raw = privateAXNormalizedAcquisition(rawRoot: Self.privateAXScrolledFixture,
-      hint: CaptureHint(
-        projection: .raw, depth: 2, regularPresentedDepth: nil,
-        interactiveOnly: false, customActions: false),
-      viewport: CGRect(x: 0, y: 0, width: 402, height: 874),
-      interfaceOrientation: RunnerInterfaceOrientation.portrait)
-    XCTAssertEqual(raw.map(\.type), ["Application", "ScrollView", "Button", "Button"])
-    XCTAssertEqual(raw.map(\.depth), [0, 1, 2, 2])
-  }
-
-  func testPrivateAXPresentationKeepsOffscreenSubtreeExcludedWhenChildFramesAreClamped() throws {
-    let frame = Self.privateAXFrame
-    let root: [String: Any] = ["type": Int(XCUIElement.ElementType.application.rawValue),
-      "label": "Element", "frame": frame(0, 0, 402, 874), "children": [[
-        "type": Int(XCUIElement.ElementType.table.rawValue), "frame": frame(0, 96, 402, 700),
-        "children": [["type": Int(XCUIElement.ElementType.cell.rawValue),
-          "label": "Theme", "frame": frame(0, 900, 402, 44), "children": [[
-            "type": Int(XCUIElement.ElementType.staticText.rawValue),
-            "label": "Theme", "frame": frame(16, 96, 120, 44)],
-          ["type": Int(XCUIElement.ElementType.switch.rawValue),
-            "label": "Theme", "frame": frame(340, 96, 46, 44)]]]]]]]
-
-    let nodes = try privateAXRegularPresentation(
-      rawRoot: root, viewport: CGRect(x: 0, y: 0, width: 402, height: 874))
-
-    XCTAssertEqual(nodes.compactMap(\.label), ["Element"])
-    XCTAssertEqual(nodes.first { $0.type == "Table" }?.hiddenContentBelow, true)
-  }
-
-  func testPrivateAXGeometrylessSemanticsAreNeverActionableOrScrollContexts() throws {
-    let zero = ["x": 0, "y": 0, "width": 0, "height": 0]
-    let root: [String: Any] = ["type": Int(XCUIElement.ElementType.application.rawValue),
-      "label": "Element", "frame": ["x": 0, "y": 0, "width": 402, "height": 874],
-      "children": [["type": Int(XCUIElement.ElementType.scrollView.rawValue),
-        "label": "Settings semantics", "frame": zero, "children": [[
-          "type": Int(XCUIElement.ElementType.button.rawValue), "label": "Theme", "frame": zero],
-        ["type": Int(XCUIElement.ElementType.other.rawValue), "frame": zero]]]]]
-    let nodes = try privateAXRegularPresentation(
-      rawRoot: root, viewport: CGRect(x: 0, y: 0, width: 402, height: 874),
-      interactiveOnly: true)
-    XCTAssertEqual(nodes.compactMap(\.label), ["Element", "Settings semantics", "Theme"])
-    XCTAssertEqual(nodes.filter { $0.index != 0 }.map(\.hittable), [false, false])
-    XCTAssertFalse(nodes.contains { $0.type == "Other" })
-    XCTAssertTrue(nodes.allSatisfy { $0.hiddenContentAbove == nil && $0.hiddenContentBelow == nil })
-  }
-}
-#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+ScrollGesture.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+ScrollGesture.swift
index f6ebb6866b..326eec698f 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+ScrollGesture.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+ScrollGesture.swift
@@ -5,8 +5,9 @@ import XCTest
 // This is a deliberate two-place invariant: the daemon keeps the TS implementation (for Android,
 // recording, and reported-pixels), and the runner places the gesture with this Swift copy. Both
 // ports are asserted against the same table, contracts/fixtures/scroll-gesture.json (gated
-// XCTest at the bottom of this file, vitest twin packages/contracts/src/scroll-gesture.test.ts) —
-// if you change the math in either language, update the other and the table.
+// XCTest in UnitTests/RunnerTests+ScrollGestureTests.swift, vitest twin
+// packages/contracts/src/scroll-gesture.test.ts) — if you change the math in either language,
+// update the other and the table.
 //
 // All inputs here are positive (reference dims, travel, center), so Swift's `.rounded()`
 // (half away from zero) matches JS `Math.round` (half up) on every value computed below.
@@ -96,198 +97,3 @@ func runnerDragCommandDefaults(_ command: Command) -> RunnerDragCommandDefaults
     durationMs: command.durationMs ?? runnerDefaultDragDurationMs
   )
 }
-
-#if AGENT_DEVICE_RUNNER_UNIT_TESTS
-private struct ScrollGestureFixture: Decodable {
-  struct Constants: Decodable {
-    let defaultIosScrollAmount: Double
-    let defaultMobileScrollDurationMs: Double
-    let defaultIosScrollDurationMs: Double
-    let defaultScrollAmount: Double
-    let defaultEdgePaddingFraction: Double
-    let ordinaryScrollReleaseBehavior: String
-    let edgeScrollReleaseBehavior: String
-  }
-  struct Expected: Decodable {
-    let x1: Double
-    let y1: Double
-    let x2: Double
-    let y2: Double
-    let pixels: Double
-  }
-  struct Case: Decodable {
-    let name: String
-    let direction: String
-    let amount: Double?
-    let pixels: Double?
-    let referenceWidth: Double
-    let referenceHeight: Double
-    let expected: Expected
-  }
-
-  let constants: Constants
-  let cases: [Case]
-}
-
-extension RunnerTests {
-  // Cross-language parity table: every case in contracts/fixtures/scroll-gesture.json must agree
-  // with the vitest twin (packages/contracts/src/scroll-gesture.test.ts). Add vectors there,
-  // never fork the math.
-  private func loadScrollGestureFixture() throws -> ScrollGestureFixture {
-    let fixtureURL = URL(fileURLWithPath: #filePath)
-      .deletingLastPathComponent() // AgentDeviceRunnerUITests
-      .deletingLastPathComponent() // AgentDeviceRunner
-      .deletingLastPathComponent() // runner
-      .deletingLastPathComponent() // apple
-      .deletingLastPathComponent() // repo root
-      .appendingPathComponent("contracts")
-      .appendingPathComponent("fixtures")
-      .appendingPathComponent("scroll-gesture.json")
-    return try JSONDecoder().decode(ScrollGestureFixture.self, from: Data(contentsOf: fixtureURL))
-  }
-
-  func testRunnerScrollGesturePlanMatchesParityTable() throws {
-    let fixture = try loadScrollGestureFixture()
-    XCTAssertFalse(fixture.cases.isEmpty, "parity table must not be empty")
-    for testCase in fixture.cases {
-      let plan = try XCTUnwrap(
-        runnerScrollGesturePlan(
-          direction: try XCTUnwrap(RunnerScrollDirection(rawValue: testCase.direction)),
-          amount: testCase.amount,
-          pixels: testCase.pixels,
-          referenceWidth: testCase.referenceWidth,
-          referenceHeight: testCase.referenceHeight
-        ),
-        testCase.name
-      )
-      XCTAssertEqual(plan.x1, testCase.expected.x1, testCase.name)
-      XCTAssertEqual(plan.y1, testCase.expected.y1, testCase.name)
-      XCTAssertEqual(plan.x2, testCase.expected.x2, testCase.name)
-      XCTAssertEqual(plan.y2, testCase.expected.y2, testCase.name)
-      XCTAssertEqual(plan.travelPixels, testCase.expected.pixels, testCase.name)
-    }
-  }
-
-  // The planner constants are private on both sides; the table pins them behaviourally on a
-  // 1000px axis where every rounding step is exact.
-  func testRunnerScrollGesturePlanUsesParityTableConstants() throws {
-    let constants = try loadScrollGestureFixture().constants
-    let defaultScroll = try JSONDecoder().decode(
-      Command.self, from: Data(#"{"command":"scroll"}"#.utf8))
-    let defaults = runnerDragCommandDefaults(defaultScroll)
-    XCTAssertEqual(defaults.durationMs, constants.defaultIosScrollDurationMs)
-    XCTAssertEqual(defaults.scrollAmount, constants.defaultIosScrollAmount)
-    let defaulted = try XCTUnwrap(
-      runnerScrollGesturePlan(
-        direction: .down, amount: nil, pixels: nil, referenceWidth: 1000, referenceHeight: 1000
-      )
-    )
-    XCTAssertEqual(defaulted.travelPixels, 1000 * constants.defaultScrollAmount)
-    let saturated = try XCTUnwrap(
-      runnerScrollGesturePlan(
-        direction: .down, amount: 10, pixels: nil, referenceWidth: 1000, referenceHeight: 1000
-      )
-    )
-    XCTAssertEqual(
-      saturated.travelPixels, 1000 - 2 * 1000 * constants.defaultEdgePaddingFraction)
-  }
-
-  func testRunnerScrollAndDragCommandDefaultsStayDistinct() throws {
-    func command(_ json: String) throws -> Command {
-      try JSONDecoder().decode(Command.self, from: Data(json.utf8))
-    }
-
-    let pixelScroll = runnerDragCommandDefaults(
-      try command(#"{"command":"scroll","pixels":120}"#))
-    XCTAssertNil(pixelScroll.scrollAmount)
-    XCTAssertEqual(pixelScroll.durationMs, 400)
-
-    let drag = runnerDragCommandDefaults(try command(#"{"command":"drag"}"#))
-    XCTAssertNil(drag.scrollAmount)
-    XCTAssertEqual(drag.durationMs, 250)
-
-    let explicitScroll = runnerDragCommandDefaults(
-      try command(#"{"command":"scroll","amount":0.5,"durationMs":125}"#))
-    XCTAssertEqual(explicitScroll.scrollAmount, 0.5)
-    XCTAssertEqual(explicitScroll.durationMs, 125)
-
-    let explicitDrag = runnerDragCommandDefaults(
-      try command(#"{"command":"drag","durationMs":125}"#))
-    XCTAssertEqual(explicitDrag.durationMs, 125)
-  }
-
-  func testRunnerScrollReleaseBehaviorSelectsTheDragProfile() throws {
-    let constants = try loadScrollGestureFixture().constants
-    let controlled = try XCTUnwrap(ScrollReleaseBehavior(rawValue: constants.ordinaryScrollReleaseBehavior))
-    let inertial = try XCTUnwrap(ScrollReleaseBehavior(rawValue: constants.edgeScrollReleaseBehavior))
-    XCTAssertEqual(
-      scrollDragProfile(releaseBehavior: nil),
-      .controlledScroll
-    )
-    XCTAssertEqual(
-      scrollDragProfile(releaseBehavior: controlled),
-      .controlledScroll
-    )
-    XCTAssertEqual(
-      scrollDragProfile(releaseBehavior: inertial),
-      .fastSwipe
-    )
-  }
-
-  func testControlledScrollProfileUsesReliableCadenceAndMonotonicDeceleration() {
-    XCTAssertEqual(RunnerControlledScrollFrameCount(350), 21)
-    XCTAssertEqual(RunnerControlledScrollFrameCount(400), 24)
-    XCTAssertEqual(RunnerControlledScrollFrameCount(500), 30)
-    XCTAssertEqual(RunnerControlledScrollFrameCount(1_000), 30)
-    XCTAssertEqual(RunnerControlledScrollFrameCount(10_000), 30)
-
-    let frameCount = RunnerControlledScrollFrameCount(400)
-    let progress = (0...frameCount).map {
-      RunnerControlledScrollProgress(Double($0) / Double(frameCount))
-    }
-    let deltas = zip(progress.dropFirst(), progress).map { $0.0 - $0.1 }
-    XCTAssertEqual(progress.first, 0)
-    XCTAssertEqual(progress.last, 1)
-    XCTAssertTrue(zip(deltas, deltas.dropFirst()).allSatisfy { $0.1 <= $0.0 })
-
-    let iPhoneViewportPoints = 874.0
-    let defaultFingerTravel = iPhoneViewportPoints * 0.65
-    let finalSampleTravel = (1 - progress[progress.count - 2]) * defaultFingerTravel
-    XCTAssertLessThan(finalSampleTravel, 0.1)
-  }
-
-  func testRunnerScrollGesturePlanRejectsUnknownDirection() {
-    XCTAssertNil(RunnerScrollDirection(rawValue: "sideways"))
-  }
-
-  func testRunnerScrollGesturePlanRejectsInvalidAmountAndPixels() {
-    XCTAssertNil(
-      runnerScrollGesturePlan(
-        direction: .down,
-        amount: 0,
-        pixels: nil,
-        referenceWidth: 300,
-        referenceHeight: 600
-      )
-    )
-    XCTAssertNil(
-      runnerScrollGesturePlan(
-        direction: .down,
-        amount: nil,
-        pixels: -10,
-        referenceWidth: 300,
-        referenceHeight: 600
-      )
-    )
-    XCTAssertNil(
-      runnerScrollGesturePlan(
-        direction: .down,
-        amount: .infinity,
-        pixels: nil,
-        referenceWidth: 300,
-        referenceHeight: 600
-      )
-    )
-  }
-}
-#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SequenceExecution.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SequenceExecution.swift
index 8b0b5da622..b6ea551520 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SequenceExecution.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SequenceExecution.swift
@@ -239,188 +239,3 @@ extension RunnerTests {
     Response(ok: false, error: ErrorPayload(code: "INVALID_ARGS", message: message))
   }
 }
-
-#if AGENT_DEVICE_RUNNER_UNIT_TESTS
-// MARK: - In-bundle unit tests (device-free)
-
-extension RunnerTests {
-  func testSequenceDecodesStepsFromWire() throws {
-    let json = """
-    {"command":"sequence","commandId":"seq-1","steps":[
-      {"kind":"tap","x":100,"y":200},
-      {"kind":"doubleTap","x":101,"y":200},
-      {"kind":"longPress","x":102,"y":200,"durationMs":300,"pauseMs":50}
-    ]}
-    """
-    let command = try JSONDecoder().decode(Command.self, from: Data(json.utf8))
-    XCTAssertEqual(command.command, .sequence)
-    XCTAssertEqual(command.steps?.count, 3)
-    XCTAssertEqual(command.steps?[0].kind, "tap")
-    XCTAssertEqual(command.steps?[1].kind, "doubleTap")
-    XCTAssertEqual(command.steps?[2].pauseMs, 50)
-  }
-
-  func testSequenceAcceptsDoubleTapKind() {
-    // A doubleTap step missing coords must fail on the coords check, not the kind allowlist —
-    // proving "doubleTap" passes validateSequenceStep without needing a device to execute on.
-    let response = executeSequenceForTest(steps: [
-      sequenceStep(kind: "doubleTap", x: nil)
-    ])
-    XCTAssertEqual(response.ok, false)
-    XCTAssertEqual(response.error?.code, "INVALID_ARGS")
-    XCTAssertTrue(response.error?.message.contains("requires finite x and y") ?? false)
-    XCTAssertFalse(response.error?.message.contains("unsupported kind") ?? true)
-  }
-
-  func testSequenceRejectsUnknownKind() throws {
-    let response = executeSequenceForTest(steps: [
-      sequenceStep(kind: "tap", x: 1, y: 2),
-      sequenceStep(kind: "pinch", x: 3, y: 4),
-    ])
-    XCTAssertEqual(response.ok, false)
-    XCTAssertEqual(response.error?.code, "INVALID_ARGS")
-    XCTAssertTrue(response.error?.message.contains("step 1") ?? false)
-    XCTAssertTrue(response.error?.message.contains("pinch") ?? false)
-  }
-
-  func testSequenceRejectsEmpty() {
-    let response = executeSequenceForTest(steps: [])
-    XCTAssertEqual(response.ok, false)
-    XCTAssertEqual(response.error?.code, "INVALID_ARGS")
-  }
-
-  func testSequenceRejectsTooManySteps() {
-    let steps = (0..<21).map { _ in sequenceStep(kind: "tap", x: 1, y: 2) }
-    let response = executeSequenceForTest(steps: steps)
-    XCTAssertEqual(response.ok, false)
-    XCTAssertEqual(response.error?.code, "INVALID_ARGS")
-    XCTAssertTrue(response.error?.message.contains("at most 20") ?? false)
-  }
-
-  func testSequenceHasSynthesizedCoordinateStep() {
-    XCTAssertTrue(
-      sequenceHasSynthesizedCoordinateStep([
-        sequenceStep(kind: "tap", x: 1, y: 2, synthesized: true),
-      ])
-    )
-    XCTAssertFalse(
-      sequenceHasSynthesizedCoordinateStep([
-        sequenceStep(kind: "tap", x: 1, y: 2),
-        sequenceStep(kind: "doubleTap", x: 1, y: 2, synthesized: true),
-      ])
-    )
-  }
-
-  func testAssembleSequencePreservesOrderOnSuccess() {
-    let steps = [
-      sequenceStep(kind: "tap", x: 1, y: 1),
-      sequenceStep(kind: "longPress", x: 2, y: 2),
-      sequenceStep(kind: "tap", x: 3, y: 3),
-    ]
-    var calls: [Int] = []
-    let execution = assembleSequenceExecution(steps: steps) { index, _ in
-      calls.append(index)
-      return SequenceStepOutcome(
-        outcome: .performed,
-        gestureStartUptimeMs: Double(index * 10),
-        gestureEndUptimeMs: Double(index * 10 + 5)
-      )
-    }
-    XCTAssertEqual(calls, [0, 1, 2])
-    XCTAssertEqual(execution.completedSteps, 3)
-    XCTAssertNil(execution.failedStepIndex)
-    XCTAssertEqual(execution.results.map { $0.kind }, ["tap", "longPress", "tap"])
-    XCTAssertEqual(execution.gestureStartUptimeMs, 0)
-    XCTAssertEqual(execution.gestureEndUptimeMs, 25)
-  }
-
-  func testAssembleSequenceStopsAtFirstFailure() {
-    let steps = [
-      sequenceStep(kind: "tap", x: 1, y: 1),
-      sequenceStep(kind: "longPress", x: 2, y: 2),
-      sequenceStep(kind: "tap", x: 3, y: 3),
-    ]
-    var calls: [Int] = []
-    let execution = assembleSequenceExecution(steps: steps) { index, _ in
-      calls.append(index)
-      if index == 1 {
-        return SequenceStepOutcome(
-          outcome: .unsupported(message: "long press unsupported", hint: nil),
-          gestureStartUptimeMs: 10,
-          gestureEndUptimeMs: 15
-        )
-      }
-      return SequenceStepOutcome(outcome: .performed, gestureStartUptimeMs: 0, gestureEndUptimeMs: 5)
-    }
-    // Step 2 is never invoked.
-    XCTAssertEqual(calls, [0, 1])
-    XCTAssertEqual(execution.completedSteps, 1)
-    XCTAssertEqual(execution.failedStepIndex, 1)
-    // results.count == completedSteps + 1 (the failed step).
-    XCTAssertEqual(execution.results.count, 2)
-    XCTAssertEqual(execution.results[1].ok, false)
-    XCTAssertEqual(execution.results[1].errorCode, "UNSUPPORTED_OPERATION")
-    XCTAssertEqual(execution.results[1].errorMessage, "long press unsupported")
-  }
-
-  func testSequenceWorstCaseResponseStaysUnderJournalCap() throws {
-    let longMessage = String(repeating: "e", count: 200)
-    let results = (0..<20).map { index in
-      SequenceStepResult(
-        ok: index < 19,
-        kind: "longPress",
-        errorCode: index < 19 ? nil : "UNSUPPORTED_OPERATION",
-        errorMessage: index < 19 ? nil : longMessage,
-        gestureStartUptimeMs: 123456.789,
-        gestureEndUptimeMs: 123466.789
-      )
-    }
-    let response = Response(
-      ok: true,
-      data: DataPayload(
-        message: "sequence",
-        completedSteps: 19,
-        failedStepIndex: 19,
-        sequenceResults: results
-      )
-    )
-    let encoded = try JSONEncoder().encode(response)
-    XCTAssertLessThan(encoded.count, 16 * 1024)
-  }
-
-  private func sequenceStep(
-    kind: String,
-    x: Double?,
-    y: Double? = nil,
-    synthesized: Bool? = nil
-  ) -> SequenceStep {
-    SequenceStep(
-      kind: kind,
-      x: x,
-      y: y,
-      durationMs: nil,
-      pauseMs: nil,
-      synthesized: synthesized
-    )
-  }
-
-  /// Validation runs before any executor call, so the INVALID_ARGS paths are exercised without
-  /// reaching the device executor (which is never invoked when validation rejects).
-  private func executeSequenceForTest(steps: [SequenceStep]) -> Response {
-    let command = makeSequenceCommand(steps: steps)
-    return executeSequence(command: command, activeApp: app)
-  }
-
-  /// Build a sequence Command via JSON so the test does not depend on the memberwise init's
-  /// parameter order.
-  private func makeSequenceCommand(steps: [SequenceStep]) -> Command {
-    struct SequenceCommandFixture: Encodable {
-      let command = "sequence"
-      let commandId = "seq-test"
-      let steps: [SequenceStep]
-    }
-    let data = try! JSONEncoder().encode(SequenceCommandFixture(steps: steps))
-    return try! JSONDecoder().decode(Command.self, from: data)
-  }
-}
-#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Snapshot.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Snapshot.swift
index 83686731cf..14fe138387 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Snapshot.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Snapshot.swift
@@ -5,12 +5,12 @@ extension RunnerTests {
   static let axSnapshotErrorCode = "IOS_AX_SNAPSHOT_FAILED"
   static let axSnapshotFailureMessage =
     "iOS XCTest snapshot failed while serializing the accessibility tree."
-  private static let axSnapshotUnavailableReason = "ax_snapshot_unavailable"
+  static let axSnapshotUnavailableReason = "ax_snapshot_unavailable"
   static let axSnapshotHint =
     "Snapshot state is unavailable because XCTest could not serialize this iOS accessibility tree. This can be specific to the current screen. Use plain screenshot, not screenshot --overlay-refs, as visual truth; navigate with coordinate commands if needed; then retry snapshot -i after reaching another screen. If you own the app and need full-tree inspection, simplify this screen's accessibility tree and expose stable ids on actionable controls."
-  private static let rawSnapshotTooLargeCode = "IOS_RAW_SNAPSHOT_TOO_LARGE"
-  private static let rawSnapshotMaxNodes = 5_000
-  private static let rawSnapshotTooLargeHint =
+  static let rawSnapshotTooLargeCode = "IOS_RAW_SNAPSHOT_TOO_LARGE"
+  static let rawSnapshotMaxNodes = 5_000
+  static let rawSnapshotTooLargeHint =
     "Raw iOS snapshot exceeded the runner payload guard. Use regular snapshot for visible UI, or scope/depth-limit raw snapshot when inspecting a large accessibility tree."
   // Runaway guard for the regular tree walk: a work bound only. A screen that trips it raises this
   // number in ADR 0004's name rather than bounding the walk by geometry again.
@@ -523,11 +523,11 @@ extension RunnerTests {
     )
   }
 
-  private func recoveredSnapshotMessage(_ failure: SnapshotCaptureFailure) -> String {
+  func recoveredSnapshotMessage(_ failure: SnapshotCaptureFailure) -> String {
     return "\(failure.message) Hint: \(failure.hint)"
   }
 
-  private func rawSnapshotTooLargeFailure(nodeCount: Int) -> SnapshotCaptureFailure {
+  func rawSnapshotTooLargeFailure(nodeCount: Int) -> SnapshotCaptureFailure {
     SnapshotCaptureFailure(
       code: Self.rawSnapshotTooLargeCode,
       message: "iOS raw snapshot exceeded \(Self.rawSnapshotMaxNodes) nodes while walking node \(nodeCount).",
@@ -558,246 +558,4 @@ extension RunnerTests {
       runnerFatalReason: runnerFatalReason
     )
   }
-
-#if AGENT_DEVICE_RUNNER_UNIT_TESTS
-  func testSnapshotAccessibilityUnavailableMarksSparseSnapshotRunnerFatal() {
-    currentApp = app
-    currentBundleId = "com.example.app"
-
-    let payload = snapshotAccessibilityUnavailable(
-      failure: SnapshotCaptureFailure(
-        code: Self.axSnapshotErrorCode,
-        message: Self.axSnapshotFailureMessage,
-        hint: Self.axSnapshotHint
-      )
-    )
-
-    XCTAssertEqual(payload.message, "\(Self.axSnapshotFailureMessage) Hint: \(Self.axSnapshotHint)")
-    XCTAssertEqual(payload.nodes?.count, 1)
-    XCTAssertEqual(payload.nodes?.first?.type, "Application")
-    XCTAssertEqual(payload.truncated, true)
-    XCTAssertEqual(payload.runnerFatal, true)
-    XCTAssertEqual(payload.runnerFatalReason, Self.axSnapshotUnavailableReason)
-    // The planned terminal result carries the structured verdict like every other planned
-    // snapshot — downstream sparse handling keys off it, not off node shapes.
-    XCTAssertEqual(payload.snapshotQuality?.state, "sparse")
-    XCTAssertEqual(payload.snapshotQuality?.reasonCode, "ax-rejected")
-    XCTAssertEqual(payload.snapshotQuality?.reason, Self.axSnapshotFailureMessage)
-    XCTAssertNil(currentApp)
-    XCTAssertNil(currentBundleId)
-  }
-
-  func testRecoveredSnapshotMessagePreservesHint() {
-    let message = recoveredSnapshotMessage(
-      SnapshotCaptureFailure(
-        code: Self.axSnapshotErrorCode,
-        message: Self.axSnapshotFailureMessage,
-        hint: Self.axSnapshotHint
-      )
-    )
-
-    XCTAssertTrue(message.contains(Self.axSnapshotFailureMessage))
-    XCTAssertTrue(message.contains(Self.axSnapshotHint))
-  }
-
-  func testRawSnapshotTooLargeFailureIsStructured() {
-    let failure = rawSnapshotTooLargeFailure(nodeCount: Self.rawSnapshotMaxNodes + 1)
-
-    XCTAssertEqual(failure.code, Self.rawSnapshotTooLargeCode)
-    XCTAssertTrue(failure.message.contains("\(Self.rawSnapshotMaxNodes) nodes"))
-    XCTAssertEqual(failure.hint, Self.rawSnapshotTooLargeHint)
-  }
-
-  func testSystemModalProbeSliceSharesAndClampsToPlanDeadline() {
-    // Fresh plan deadline: the probe gets its full dedicated budget.
-    XCTAssertEqual(Self.systemModalProbeSlice(budget: 4, deadlineRemaining: 20), 4)
-    // Nearly-spent plan deadline: the probe is clamped so it can't run past the shared budget.
-    XCTAssertEqual(Self.systemModalProbeSlice(budget: 4, deadlineRemaining: 1.5), 1.5)
-    // Exactly/already exhausted deadline: skip the probe entirely (0), never a negative timeout.
-    XCTAssertEqual(Self.systemModalProbeSlice(budget: 4, deadlineRemaining: 0), 0)
-    XCTAssertEqual(Self.systemModalProbeSlice(budget: 4, deadlineRemaining: -5), 0)
-  }
-
-  // Simulator-only: the bounded probe body returns nil on macOS (no SpringBoard host), so the
-  // timeout/penalty/drain machinery below only exists on the iOS branch.
-#if os(iOS)
-  /// Regression for #1244/#1248: drives the bounded system-modal probe through a real,
-  /// production-only command entry point (`snapshotFast` or `snapshotRaw` -- see the two test
-  /// methods below), not `boundedBlockingSystemAlertSnapshot` directly, with
-  /// `systemModalProbeOverrideForTesting` set to a closure that blocks past the probe's real
-  /// slice, forcing a real `runMainThreadWork` timeout. This is revert-sensitive on both halves
-  /// of the fix, for either entry point:
-  ///   - if the entry point reverted to calling the unbounded `blockingSystemAlertSnapshot`
-  ///     directly (or dropped the `runMainThreadWork` wrap), nothing here would ever time out,
-  ///     so the mid-flight busy/penalty assertions below would never be met;
-  ///   - if the `onAbandoned` penalty hook or the abandoned-work accounting were dropped, the
-  ///     timeout would still fire, but the busy/penalty and drain assertions would not hold.
-  ///
-  /// The drain assertion is synchronized on the *real* release rather than raced: after
-  /// signaling the probe to finish, the background queue polls `hasAbandonedMainThreadWork()`
-  /// (bounded) and only then fulfills `drained`, which the test `wait(for:timeout:)`s on before
-  /// asserting `.idle`/`hasAbandonedMainThreadWork() == false` below -- so a slow drain fails that
-  /// assertion instead of racing a fixed-timing guess.
-  private func assertBoundedSystemModalProbeTimeoutRecoversThenReleasesOnDrain(
-    entryPointName: String,
-    callEntryPoint: @escaping (XCUIApplication, PresentationOptions) throws -> DataPayload
-  ) {
-    let targetBundleId = "com.callstack.agentdevice.runner.missing.snapshot-timeout-test"
-    let snapshotTarget = XCUIApplication(bundleIdentifier: targetBundleId)
-    let probeReleaseGate = DispatchSemaphore(value: 0)
-    currentApp = snapshotTarget
-    currentBundleId = targetBundleId
-    defer {
-      probeReleaseGate.signal()
-      currentApp = nil
-      currentBundleId = nil
-      systemModalProbeOverrideForTesting = nil
-      clearSnapshotXCTestChannelPenalty(reason: "test-cleanup")
-    }
-
-    final class ResultBox {
-      var payload: DataPayload?
-      var wasBusyBeforeDrain = false
-      var hadAbandonedCaptureBeforeDrain = false
-      var wasPenalizedBeforeDrain = false
-    }
-    let box = ResultBox()
-    // The test owns release of the injected probe. A fixed timeout races the capture plan's
-    // independent fallback tiers on loaded CI hosts and can drain before the test records the
-    // abandoned-work state. The defer above still releases the probe if an earlier assertion or
-    // expectation fails.
-    systemModalProbeOverrideForTesting = { _ in
-      probeReleaseGate.wait()
-      return nil
-    }
-
-    let completion = expectation(
-      description: "\(entryPointName) recovered while the probe was abandoned, then released it"
-    )
-    let drained = expectation(description: "\(entryPointName) modal probe drained")
-    DispatchQueue(label: "agent-device.runner.tests.modal-probe-timeout").async {
-      box.payload = try? callEntryPoint(
-        snapshotTarget,
-        PresentationOptions(interactiveOnly: false, depth: nil, scope: nil, raw: false)
-      )
-
-      // 1) Penalty/busy accounting: must already be in place by the time the entry point
-      // returns, well before we release the still-blocked probe below.
-      if case .busy = self.currentMainThreadBusyState() {
-        box.wasBusyBeforeDrain = true
-      }
-      box.hadAbandonedCaptureBeforeDrain = self.hasAbandonedMainThreadWork()
-      box.wasPenalizedBeforeDrain = self.isSnapshotXCTestChannelPenalized(bundleId: self.currentBundleId)
-
-      // 2) `box.payload` above was already produced -- through the capture plan's recovery
-      // tiers -- while the probe is still blocked on `probeReleaseGate`, i.e. recovered before
-      // drain, not queued behind it.
-      completion.fulfill()
-
-      // 3) Only now let the abandoned probe finish, then block this queue (never the test's
-      // main-thread wait) on the *real* drain signal -- the abandoned-work count reaching zero
-      // -- bounded so a revert that never drains fulfills `drained` anyway and lets the
-      // assertions below report the regression explicitly instead of just timing out.
-      probeReleaseGate.signal()
-      let drainDeadline = Date().addingTimeInterval(5)
-      while self.hasAbandonedMainThreadWork(), Date() < drainDeadline {
-        self.sleepFor(0.002)
-      }
-      drained.fulfill()
-    }
-
-    wait(for: [completion], timeout: 15)
-
-    // 1) Penalty/busy accounting.
-    XCTAssertTrue(
-      box.wasBusyBeforeDrain,
-      "expected RUNNER_BUSY while the \(entryPointName) modal probe timeout is outstanding"
-    )
-    XCTAssertTrue(
-      box.hadAbandonedCaptureBeforeDrain,
-      "onAbandoned must retain the abandoned XCTest channel work for \(entryPointName)"
-    )
-    XCTAssertTrue(
-      box.wasPenalizedBeforeDrain,
-      "a timed-out modal probe must penalize the XCTest snapshot channel for \(entryPointName)"
-    )
-
-    // 2) Recovered response before drain.
-    XCTAssertNotNil(
-      box.payload,
-      "\(entryPointName) must recover a payload through the capture plan while the probe drains"
-    )
-
-    // 3) Bounded, deterministic drain barrier, then release assertions.
-    wait(for: [drained], timeout: 6)
-    guard case .idle = currentMainThreadBusyState() else {
-      return XCTFail("expected the runner to be idle once the abandoned \(entryPointName) probe drained")
-    }
-    XCTAssertFalse(
-      hasAbandonedMainThreadWork(),
-      "the drained probe must release the main thread for \(entryPointName)"
-    )
-  }
-
-  func testBoundedSystemModalProbeTimeoutRecoversThenReleasesOnDrain() {
-    assertBoundedSystemModalProbeTimeoutRecoversThenReleasesOnDrain(entryPointName: "snapshotFast") {
-      target, options in
-      try self.snapshotFast(app: target, options: options)
-    }
-  }
-
-  func testBoundedSystemModalProbeTimeoutRecoversThenReleasesOnDrainForSnapshotRaw() {
-    assertBoundedSystemModalProbeTimeoutRecoversThenReleasesOnDrain(entryPointName: "snapshotRaw") {
-      target, options in
-      try self.snapshotRaw(app: target, options: options)
-    }
-  }
-#endif
-
-  func testDispatchRecoverySkipsBookkeepingWhileXCTestChannelOccupied() {
-    // The #1244 recovery shape: the modal probe abandoned an XCTest query that is still grinding on
-    // main, the capture recovered independently, and its response is ready. The recovery loop must
-    // return it without re-entering the main queue for recorded-failure/retry bookkeeping (that hop
-    // would block behind the abandoned query and re-stall the command), and a later command must
-    // still see the runner busy until the abandoned work drains. Removing the guard regresses this.
-    let command = try! JSONDecoder().decode(
-      Command.self,
-      from: Data(#"{"command":"snapshot","commandId":"recovery-guard"}"#.utf8)
-    )
-    let recovered = Response(ok: false, error: .targetAppUnavailable(bundleId: nil))
-
-    setAbandonedMainThreadWork(1)
-    defer { setAbandonedMainThreadWork(0) }
-    guard case .busy = currentMainThreadBusyState() else {
-      return XCTFail("expected RUNNER_BUSY while abandoned XCTest work is outstanding")
-    }
-
-    var occupiedCalls = 0
-    let occupied = try! executeDispatchedWithRecovery(command: command) {
-      occupiedCalls += 1
-      return recovered
-    }
-    XCTAssertEqual(occupiedCalls, 1, "recovered response must not retry behind abandoned XCTest work")
-    XCTAssertEqual(occupied.ok, false)
-
-    setAbandonedMainThreadWork(0)
-    guard case .idle = currentMainThreadBusyState() else {
-      return XCTFail("runner should be idle once the abandoned work drained")
-    }
-    var drainedCalls = 0
-    _ = try! executeDispatchedWithRecovery(command: command) {
-      drainedCalls += 1
-      return recovered
-    }
-    XCTAssertEqual(drainedCalls, 2, "with the channel free the read-only retry runs once")
-  }
-
-  private func setAbandonedMainThreadWork(_ count: Int) {
-    mainThreadWorkLock.lock()
-    abandonedMainThreadWorkCount = count
-    abandonedMainThreadWorkSince = count > 0 ? Date(timeIntervalSinceNow: -1) : nil
-    mainThreadWorkLock.unlock()
-  }
-#endif
-
 }
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotBackendCapabilities.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotBackendCapabilities.swift
index e4c43b54bd..4a5b478639 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotBackendCapabilities.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotBackendCapabilities.swift
@@ -86,81 +86,3 @@ enum SnapshotBackendKind: String, CaseIterable {
     }
   }
 }
-
-#if AGENT_DEVICE_RUNNER_UNIT_TESTS
-private struct SnapshotBackendParityFixture: Decodable {
-  struct Availability: Decodable {
-    let simulator: Bool
-    let physicalDevice: Bool
-  }
-
-  struct Backend: Decodable {
-    let name: String
-    let forceable: Bool
-    let supportsRawProjection: Bool
-    let regularDepth: String
-    let hittable: String
-    let availability: Availability
-  }
-
-  let backends: [Backend]
-}
-
-extension RunnerTests {
-  private func loadSnapshotBackendParityFixture() throws -> SnapshotBackendParityFixture {
-    let fixtureURL = URL(fileURLWithPath: #filePath)
-      .deletingLastPathComponent() // AgentDeviceRunnerUITests
-      .deletingLastPathComponent() // AgentDeviceRunner
-      .deletingLastPathComponent() // runner
-      .deletingLastPathComponent() // apple
-      .deletingLastPathComponent() // repo root
-      .appendingPathComponent("contracts")
-      .appendingPathComponent("fixtures")
-      .appendingPathComponent("ios-snapshot-backends.json")
-    return try JSONDecoder().decode(
-      SnapshotBackendParityFixture.self,
-      from: Data(contentsOf: fixtureURL)
-    )
-  }
-
-  /// The JSON table is the cross-runtime declaration used by the TypeScript capability registry
-  /// and this runner. A backend case, forceability branch, projection/depth claim, or availability
-  /// change that is not classified in both implementations fails before an iOS smoke can drift.
-  func testSnapshotBackendDeclarationsMatchCapabilityFixture() throws {
-    let fixture = try loadSnapshotBackendParityFixture()
-    XCTAssertEqual(
-      fixture.backends.map(\.name),
-      SnapshotBackendKind.allCases.map(\.rawValue)
-    )
-
-    for expected in fixture.backends {
-      guard let backend = SnapshotBackendKind(rawValue: expected.name) else {
-        XCTFail("fixture contains an unknown snapshot backend: \(expected.name)")
-        continue
-      }
-      XCTAssertEqual(backend.isForceable, expected.forceable, expected.name)
-      XCTAssertEqual(backend.supportsRawProjection, expected.supportsRawProjection, expected.name)
-      XCTAssertEqual(
-        backend.regularDepthCapability.rawValue,
-        expected.regularDepth,
-        "regular depth capability: \(expected.name)"
-      )
-      XCTAssertEqual(
-        backend.hittableSemantics,
-        expected.hittable,
-        "hittable semantics: \(expected.name)"
-      )
-      XCTAssertEqual(
-        backend.isAvailable(on: .simulator),
-        expected.availability.simulator,
-        "simulator availability: \(expected.name)"
-      )
-      XCTAssertEqual(
-        backend.isAvailable(on: .physicalDevice),
-        expected.availability.physicalDevice,
-        "physical-device availability: \(expected.name)"
-      )
-    }
-  }
-}
-#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotCapturePlan.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotCapturePlan.swift
index 16a999ab5d..b6e9946957 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotCapturePlan.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotCapturePlan.swift
@@ -629,7 +629,7 @@ extension RunnerTests {
 
   // MARK: Outcome stamping
 
-  private func stampedSnapshotPayload(
+  func stampedSnapshotPayload(
     _ capture: SnapshotBackendCapture,
     backend: SnapshotBackendKind,
     state: String,
@@ -666,493 +666,3 @@ extension RunnerTests {
     )
   }
 }
-
-#if AGENT_DEVICE_RUNNER_UNIT_TESTS
-// MARK: - In-bundle unit tests
-
-extension RunnerTests {
-  private func planTestNode(
-    index: Int,
-    type: String,
-    label: String? = nil,
-    identifier: String? = nil,
-    hittable: Bool = false,
-    parentIndex: Int? = nil
-  ) -> PresentedNode {
-    SnapshotPresentation.singleElementRead(
-      RawAXNode(
-        index: index,
-        type: type,
-        label: label,
-        identifier: identifier,
-        value: nil,
-        rect: SnapshotRect(.zero),
-        enabled: true,
-        focused: nil,
-        selected: nil,
-        hittable: hittable,
-        depth: parentIndex == nil ? 0 : 1,
-        parentIndex: parentIndex,
-        hiddenContentAbove: nil,
-        hiddenContentBelow: nil
-      )
-    )
-  }
-
-  func testSparsePayloadReasonMatrix() {
-    let root = planTestNode(index: 0, type: "Application", label: "Example App", hittable: true)
-    let window = planTestNode(index: 1, type: "Window", parentIndex: 0)
-    let button = planTestNode(index: 1, type: "Button", label: "Ok", hittable: true, parentIndex: 0)
-    let shell = planTestNode(
-      index: 1,
-      type: "Other",
-      identifier: "appShell",
-      parentIndex: 0
-    )
-    let serializationPlaceholder = planTestNode(
-      index: 2,
-      type: "Other",
-      label: "[object Object]",
-      parentIndex: 1
-    )
-
-    // Labeled, hittable root over a bare window is still sparse.
-    XCTAssertNotNil(Self.sparsePayloadReason(DataPayload(nodes: [root, window], truncated: false)))
-    // Deadline-truncated near-empty sweep needs recovery even with one real control.
-    XCTAssertNotNil(Self.sparsePayloadReason(DataPayload(nodes: [root, button], truncated: true)))
-    // The same tiny tree from a completed sweep is a legitimately minimal screen.
-    XCTAssertNil(Self.sparsePayloadReason(DataPayload(nodes: [root, button], truncated: false)))
-    // Container metadata plus a stringified serialization placeholder is not readable UI.
-    XCTAssertNotNil(
-      Self.sparsePayloadReason(
-        DataPayload(nodes: [root, shell, serializationPlaceholder], truncated: false)
-      )
-    )
-    let actionableShell = planTestNode(
-      index: 1,
-      type: "Other",
-      identifier: "checkout",
-      hittable: true,
-      parentIndex: 0
-    )
-    XCTAssertNil(
-      Self.sparsePayloadReason(DataPayload(nodes: [root, actionableShell], truncated: false))
-    )
-    // Empty payloads are degraded.
-    XCTAssertNotNil(Self.sparsePayloadReason(DataPayload(nodes: [], truncated: false)))
-  }
-
-  func testCollapsedLeafIndexesFlagsMergedContainersOnly() {
-    let root = planTestNode(index: 0, type: "Application", label: "App")
-    let merged = planTestNode(
-      index: 1,
-      type: "Other",
-      label: (0...30).map { "Row \($0), Tap" }.joined(separator: ", "),
-      parentIndex: 0
-    )
-    let prose = planTestNode(
-      index: 2,
-      type: "StaticText",
-      label: (0...30).map { "clause \($0)" }.joined(separator: ", "),
-      parentIndex: 0
-    )
-    XCTAssertEqual(Self.collapsedLeafIndexes([root, merged, prose]), [1])
-    XCTAssertNil(Self.collapsedLeafIndexes([root, prose]))
-  }
-
-  func testTerminalFailsClosedOnInteractiveAxFailureRegardlessOfSparseBest() {
-    // Interactive AX failure must invalidate + fail closed; a later tier's sparse synthetic-root
-    // "best" must never downgrade this to a returned-sparse payload (regression: best == nil guard).
-    XCTAssertEqual(
-      Self.resolveSnapshotPlanTerminal(terminal: .sparseWithFatalOnAXFailure, interactiveOnly: true),
-      .failClosed
-    )
-    XCTAssertEqual(
-      Self.resolveSnapshotPlanTerminal(terminal: .sparseWithFatalOnAXFailure, interactiveOnly: false),
-      .sparseBest
-    )
-    XCTAssertEqual(
-      Self.resolveSnapshotPlanTerminal(terminal: .throwOnAXFailure, interactiveOnly: true),
-      .throwAxFailure
-    )
-  }
-
-  func testXCTestChannelStateFirstFailureStampsDeferredCodeOnlyForDeferral() {
-    XCTAssertNil(Self.xcTestChannelStateFirstFailure(.normal))
-    XCTAssertEqual(Self.xcTestChannelStateFirstFailure(.deferredToIndependentBackend)?.code, "deferred")
-    XCTAssertEqual(Self.xcTestChannelStateFirstFailure(.boundedXCTestProbe)?.code, "budget")
-  }
-
-  func testSnapshotQualityCarriesPhaseTimingAtResponseLevel() {
-    let timing = SnapshotCaptureTiming(acquisitionMs: 12, presentationMs: 34)
-    let capture = SnapshotBackendCapture(
-      payload: DataPayload(
-        nodes: [planTestNode(index: 0, type: "Application", label: "App")],
-        truncated: false
-      ),
-      effectiveDepth: nil,
-      timing: timing
-    )
-
-    let payload = stampedSnapshotPayload(
-      capture,
-      backend: .recursiveTree,
-      state: "healthy",
-      reason: nil
-    )
-
-    XCTAssertEqual(payload.snapshotQuality?.timing, timing)
-    XCTAssertEqual(payload.nodes?.count, 1)
-  }
-
-  func testStampedPayloadCarriesDisclosuresOnlyInTheVerdict() {
-    let root = planTestNode(index: 0, type: "Application", label: "App")
-    let merged = planTestNode(
-      index: 1,
-      type: "Other",
-      label: (0...30).map { "Tab \($0)" }.joined(separator: ", "),
-      parentIndex: 0
-    )
-    let coverage = SnapshotCustomActionCoverage(
-      read: 12, candidates: 19, truncated: 0, blocked: false)
-    let silent = stampedSnapshotPayload(
-      SnapshotBackendCapture(
-        payload: DataPayload(nodes: [root, merged], truncated: false),
-        effectiveDepth: nil,
-        customActions: coverage
-      ),
-      backend: .recursiveTree,
-      state: "healthy",
-      reason: nil
-    )
-    XCTAssertNil(silent.message)
-    XCTAssertEqual(silent.snapshotQuality?.customActions, coverage)
-    XCTAssertEqual(silent.snapshotQuality?.collapsedLeafIndexes, [1])
-
-    let underlying = stampedSnapshotPayload(
-      SnapshotBackendCapture(
-        payload: DataPayload(message: "underlying", nodes: [root], truncated: false),
-        effectiveDepth: 4
-      ),
-      backend: .privateAX,
-      state: "recovered",
-      reason: (reason: "tree capture timed out", code: "budget")
-    )
-    XCTAssertEqual(underlying.message, "underlying")
-  }
-
-  func testStampedPayloadTruncationTracksCompletenessNotRecoveryProvenance() {
-    let complete = SnapshotBackendCapture(
-      payload: DataPayload(
-        nodes: [
-          planTestNode(index: 0, type: "Application", label: "App"),
-          planTestNode(index: 1, type: "Button", label: "Open", parentIndex: 0),
-        ],
-        truncated: false
-      ),
-      effectiveDepth: nil
-    )
-    let deferred: (reason: String, code: String) = (
-      "XCTest-backed snapshot tiers were deferred after recent slow accessibility work", "deferred"
-    )
-
-    // The CI signature behind `is absent ... capture was truncated`: a complete private AX
-    // tree selected while the XCTest channel is penalized is whole, and must say so.
-    let recovered = stampedSnapshotPayload(
-      complete, backend: .privateAX, state: "recovered", reason: deferred)
-    XCTAssertEqual(recovered.snapshotQuality?.state, "recovered")
-    XCTAssertEqual(recovered.truncated, false)
-
-    let depthLimited = stampedSnapshotPayload(
-      SnapshotBackendCapture(payload: complete.payload, effectiveDepth: 56),
-      backend: .privateAX, state: "recovered", reason: deferred)
-    XCTAssertEqual(depthLimited.truncated, true)
-
-    let cappedPayload = stampedSnapshotPayload(
-      SnapshotBackendCapture(
-        payload: DataPayload(nodes: complete.payload.nodes ?? [], truncated: true),
-        effectiveDepth: nil),
-      backend: .recursiveTree, state: "healthy", reason: nil)
-    XCTAssertEqual(cappedPayload.truncated, true)
-
-    let sparse = stampedSnapshotPayload(
-      complete, backend: .querySweep, state: "sparse",
-      reason: ("snapshot returned no semantic controls or content", "sparse-tree"))
-    XCTAssertEqual(sparse.truncated, true)
-  }
-
-  func testSnapshotQualityCarriesUnscopedQualityPayload() {
-    let quality = DataPayload(
-      nodes: [planTestNode(index: 0, type: "Application", label: "App")],
-      truncated: false
-    )
-    let capture = SnapshotBackendCapture(
-      payload: quality,
-      effectiveDepth: nil,
-      qualityPayload: quality
-    )
-
-    let payload = stampedSnapshotPayload(
-      capture,
-      backend: .recursiveTree,
-      state: "healthy",
-      reason: nil
-    )
-
-    XCTAssertEqual(payload.qualityPayload?.nodes.count, 1)
-    XCTAssertEqual(payload.qualityPayload?.truncated, false)
-    XCTAssertNil(payload.qualityPayload?.scope)
-  }
-
-  func testDirectPresentationDoesNotClaimPlanTiming() {
-    let options = PresentationOptions(
-      interactiveOnly: false,
-      depth: nil,
-      scope: nil,
-      raw: true
-    )
-    let result = SnapshotPresentation.presentRaw(
-      SnapshotAcquisition(
-        hint: SnapshotPresentation.captureHint(for: options),
-        nodes: [],
-        truncated: false,
-        effectiveDepth: nil,
-        viewport: .infinite
-      ),
-      options: options
-    )
-    let capture = Self.makeSnapshotBackendCapture(from: result)
-
-    let payload = stampedSnapshotPayload(
-      capture,
-      backend: .recursiveTree,
-      state: "healthy",
-      reason: nil
-    )
-
-    XCTAssertNil(payload.snapshotQuality?.timing)
-  }
-
-  /// The raw plan is derived from what each backend can actually serve, not from a second
-  /// hand-maintained list. Non-vacuity: flipping `querySweep.supportsRawProjection` to true adds it
-  /// to the plan and fails the first two assertions — which is exactly the shape of #1797 D4, a
-  /// `--raw` request answered by a backend that has no hierarchy to return.
-  func testRawDiagnosticPlanCarriesOnlyBackendsThatCanServeRaw() {
-    XCTAssertEqual(Self.rawDiagnosticPlan, [.recursiveTree, .privateAX])
-    XCTAssertEqual(
-      SnapshotBackendKind.allCases.filter { !$0.supportsRawProjection }, [.querySweep])
-    XCTAssertTrue(Self.rawDiagnosticPlan.allSatisfy(\.supportsRawProjection))
-    // Tree-first error propagation is the raw plan's other contract (ADR 0004).
-    XCTAssertEqual(Self.rawDiagnosticPlan.first, .recursiveTree)
-  }
-
-  /// A projection mismatch is a runner bug, not an accessibility failure: it must not take the
-  /// AX-failure terminal route (rethrow / fail-closed), just drop its tier with a named reason.
-  func testProjectionMismatchFailureIsStructuredAndNotAnAxFailure() {
-    let failure = Self.snapshotProjectionMismatchFailure(
-      .querySweep, requested: .raw, acquired: .regular)
-    XCTAssertEqual(failure.code, "IOS_SNAPSHOT_PROJECTION_MISMATCH")
-    XCTAssertTrue(failure.message.contains("queries"))
-    XCTAssertTrue(failure.message.contains("raw"))
-    XCTAssertFalse(Self.isAxSnapshotFailure(failure))
-  }
-
-  /// #1634 P2: the decoded wire field must reach capture options and its
-  /// applicable plan. A pinned REGULAR capture defers to privateAX-first; the
-  /// RAW diagnostic plan is never rerouted by the pin — raw keeps tree-first
-  /// error propagation, which is exactly why raw baselines are excluded from
-  /// corroboration daemon-side.
-  func testDecodedPreferredBackendReachesOptionsAndApplicablePlan() throws {
-    let json = #"{"command":"snapshot","preferredBackend":"private-ax"}"#
-    let command = try JSONDecoder().decode(Command.self, from: Data(json.utf8))
-    let options = Self.presentationOptions(from: command)
-    XCTAssertEqual(options.preferredBackend, "private-ax")
-    XCTAssertFalse(options.raw)
-
-    let treated = Self.snapshotXCTestChannelTreatedAsPenalized(
-      penalized: false, preferredBackend: options.preferredBackend)
-    let pinned = Self.effectiveSnapshotCapturePlan(
-      Self.regularVisiblePlan,
-      xCTestChannelPenalized: treated,
-      preferredBackend: options.preferredBackend
-    )
-    XCTAssertEqual(pinned.plan, [.privateAX])
-    XCTAssertEqual(pinned.xCTestChannelState, .deferredToIndependentBackend)
-
-    let raw = Self.effectiveSnapshotCapturePlan(
-      Self.rawDiagnosticPlan,
-      xCTestChannelPenalized: treated,
-      preferredBackend: options.preferredBackend
-    )
-    XCTAssertEqual(raw.plan, Self.rawDiagnosticPlan)
-
-    // A command without the field decodes to no pin and a normal plan.
-    let bare = try JSONDecoder().decode(
-      Command.self, from: Data(#"{"command":"snapshot"}"#.utf8))
-    XCTAssertNil(Self.presentationOptions(from: bare).preferredBackend)
-  }
-
-  /// #1635: the force seam must select the recursive tree even when the XCTest
-  /// channel is currently penalized. Without the preferred-backend argument,
-  /// this call returns the independent private-AX recovery plan instead.
-  func testPreferredTreeBackendPinsRegularPlanAndLeavesStructuredEvidence() {
-    let forced = Self.effectiveSnapshotCapturePlan(
-      Self.regularVisiblePlan,
-      xCTestChannelPenalized: true,
-      preferredBackend: SnapshotBackendKind.recursiveTree.rawValue
-    )
-    XCTAssertEqual(forced.plan, [.recursiveTree])
-    XCTAssertEqual(forced.xCTestChannelState, .normal)
-    XCTAssertEqual(
-      Self.xcTestChannelStateFirstFailure(
-        forced.xCTestChannelState,
-        preferredBackend: forced.preferredBackend?.rawValue
-      )?.code,
-      "requested-backend"
-    )
-  }
-
-  /// Same-backend evidence probes: a daemon-pinned private-AX capture takes the
-  /// penalized route even with a healthy channel, so tap-outcome corroboration
-  /// baselines and probes are always captured by the same backend (backends are
-  /// never comparable views of a screen). Composed with the plan rule, the pin
-  /// yields the privateAX-first deferred plan.
-  func testPreferredPrivateAXBackendPlansAsPenalized() {
-    XCTAssertTrue(
-      Self.snapshotXCTestChannelTreatedAsPenalized(penalized: false, preferredBackend: "private-ax"))
-    XCTAssertTrue(
-      Self.snapshotXCTestChannelTreatedAsPenalized(penalized: true, preferredBackend: nil))
-    XCTAssertFalse(
-      Self.snapshotXCTestChannelTreatedAsPenalized(penalized: false, preferredBackend: nil))
-    XCTAssertFalse(
-      Self.snapshotXCTestChannelTreatedAsPenalized(penalized: false, preferredBackend: "tree"))
-
-    let pinned = Self.effectiveSnapshotCapturePlan(
-      Self.regularVisiblePlan,
-      xCTestChannelPenalized: Self.snapshotXCTestChannelTreatedAsPenalized(
-        penalized: false, preferredBackend: "private-ax"
-      ),
-      preferredBackend: "private-ax"
-    )
-    XCTAssertEqual(pinned.plan, [.privateAX])
-    XCTAssertEqual(pinned.xCTestChannelState, .deferredToIndependentBackend)
-  }
-
-  func testEffectiveSnapshotCapturePlanDefersXCTestBackedTiersOnlyWhenPenalizedRegularPlan() {
-    let regular = Self.effectiveSnapshotCapturePlan(
-      Self.regularVisiblePlan,
-      xCTestChannelPenalized: true
-    )
-    XCTAssertEqual(regular.plan, [.privateAX])
-    XCTAssertEqual(regular.xCTestChannelState, .deferredToIndependentBackend)
-    XCTAssertNil(regular.treeCaptureSliceBudgetOverride)
-
-    let unpenalized = Self.effectiveSnapshotCapturePlan(
-      Self.regularVisiblePlan,
-      xCTestChannelPenalized: false
-    )
-    XCTAssertEqual(unpenalized.plan, Self.regularVisiblePlan)
-    XCTAssertEqual(unpenalized.xCTestChannelState, .normal)
-    XCTAssertNil(unpenalized.treeCaptureSliceBudgetOverride)
-
-    // The raw diagnostic plan preserves tree-first error propagation even under penalty.
-    let raw = Self.effectiveSnapshotCapturePlan(
-      Self.rawDiagnosticPlan,
-      xCTestChannelPenalized: true
-    )
-    XCTAssertEqual(raw.plan, Self.rawDiagnosticPlan)
-    XCTAssertEqual(raw.xCTestChannelState, .normal)
-    XCTAssertNil(raw.treeCaptureSliceBudgetOverride)
-  }
-
-  func testEffectiveSnapshotCapturePlanUsesBoundedXCTestProbeWhenNoIndependentBackendRuns() {
-    let physicalDevicePlan = Self.effectiveSnapshotCapturePlan(
-      Self.regularVisiblePlan,
-      xCTestChannelPenalized: true,
-      availableBackends: [.recursiveTree, .querySweep]
-    )
-
-    XCTAssertEqual(physicalDevicePlan.plan, [.recursiveTree, .querySweep])
-    XCTAssertEqual(physicalDevicePlan.xCTestChannelState, .boundedXCTestProbe)
-    XCTAssertEqual(
-      physicalDevicePlan.treeCaptureSliceBudgetOverride,
-      Self.penalizedXCTestProbeTreeSliceBudget
-    )
-  }
-
-  func testSnapshotXCTestChannelPenaltyMatchesBundleAndExpires() {
-    defer {
-      snapshotXCTestChannelPenaltyBundleId = nil
-      snapshotXCTestChannelPenaltyUntil = .distantPast
-    }
-
-    penalizeSnapshotXCTestChannel(bundleId: "xyz.blueskyweb.app", reason: "test")
-    XCTAssertTrue(isSnapshotXCTestChannelPenalized(bundleId: "xyz.blueskyweb.app"))
-    XCTAssertFalse(isSnapshotXCTestChannelPenalized(bundleId: "com.other.app"))
-
-    // A penalty recorded without a bundle applies to any current target.
-    penalizeSnapshotXCTestChannel(bundleId: nil, reason: "test")
-    XCTAssertTrue(isSnapshotXCTestChannelPenalized(bundleId: "com.other.app"))
-
-    // Expired penalties stop applying.
-    snapshotXCTestChannelPenaltyUntil = Date(timeIntervalSinceNow: -1)
-    XCTAssertFalse(isSnapshotXCTestChannelPenalized(bundleId: "com.other.app"))
-  }
-
-  func testAbandonedMainThreadWorkSkipsOnlyXCTestBackedSnapshotTiers() {
-    abandonedMainThreadWorkCount = 1
-    defer { abandonedMainThreadWorkCount = 0 }
-
-    XCTAssertTrue(shouldSkipSnapshotBackendForAbandonedMainThreadWork(.recursiveTree))
-    XCTAssertTrue(shouldSkipSnapshotBackendForAbandonedMainThreadWork(.querySweep))
-    XCTAssertFalse(shouldSkipSnapshotBackendForAbandonedMainThreadWork(.privateAX))
-  }
-
-#if os(iOS)
-  /// #2403: a plan pinned to private AX serves a regular `--depth` request through acquisition
-  /// and presentation. With a backend depth gate in `captureWithBackend`, private AX returns no
-  /// capture, the plan falls through to the synthetic sparse root, and the daemon rejects that
-  /// zero-rect root as a missing viewport.
-  func testPrivateAXPinnedRegularDepthReachesAcquisitionAndPresentation() throws {
-    app.launchArguments = ["--agent-device-selector-read-regression"]
-    app.launch()
-    currentApp = app
-    currentBundleId = nil
-    defer {
-      currentApp = nil
-      clearPrivateAXAcceptedDepth(reason: "test-cleanup")
-      app.terminate()
-    }
-    func capture(depth: Int?) throws -> DataPayload {
-      try runSnapshotCapturePlan(
-        Self.regularVisiblePlan,
-        app: app,
-        options: PresentationOptions(
-          interactiveOnly: false,
-          depth: depth,
-          scope: nil,
-          raw: false,
-          preferredBackend: SnapshotBackendKind.privateAX.rawValue
-        ),
-        terminal: .sparseWithFatalOnAXFailure
-      )
-    }
-
-    let capped = try capture(depth: 1)
-
-    let quality = try XCTUnwrap(capped.snapshotQuality)
-    XCTAssertEqual(quality.backend, SnapshotBackendKind.privateAX.rawValue)
-    XCTAssertNotEqual(quality.state, "sparse")
-    let nodes = try XCTUnwrap(capped.nodes)
-    XCTAssertGreaterThan(nodes.count, 1)
-    XCTAssertEqual(nodes.map(\.depth).max(), 1)
-    XCTAssertNotEqual(nodes[0].rect, SnapshotRect(x: 0, y: 0, width: 0, height: 0))
-    XCTAssertTrue(nodes.contains { $0.label == "Readable target" })
-
-    // The presented cut only ever narrows the unscoped capture from the same backend.
-    let unscoped = try XCTUnwrap(try capture(depth: nil).nodes)
-    XCTAssertLessThanOrEqual(nodes.count, unscoped.count)
-  }
-#endif
-}
-#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotTiming.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotTiming.swift
index 442aa6d1b9..288e4cca5a 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotTiming.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotTiming.swift
@@ -73,7 +73,7 @@ extension RunnerTests {
 
   /// The penalty breaker observes only acquisition facts. Presentation is a separate phase and
   /// cannot arm the breaker, even when it is slower than the acquisition that produced the tree.
-  private static func snapshotXCTestPenaltyReason(
+  static func snapshotXCTestPenaltyReason(
     kind: SnapshotBackendKind,
     attempt: SnapshotBackendAttempt,
     slowThresholdMs: Double
@@ -107,79 +107,3 @@ extension RunnerTests {
     )
   }
 }
-
-#if AGENT_DEVICE_RUNNER_UNIT_TESTS
-extension RunnerTests {
-  func testXCTestPenaltyDecisionSeparatesAcquisitionAndPresentation() {
-    let slowPresentation = SnapshotBackendAttempt(
-      outcome: .noCapture,
-      timing: SnapshotCaptureTiming(acquisitionMs: 100, presentationMs: 4_000)
-    )
-    XCTAssertNil(
-      Self.snapshotXCTestPenaltyReason(
-        kind: .recursiveTree,
-        attempt: slowPresentation,
-        slowThresholdMs: 3_000
-      )
-    )
-
-    let slowAcquisition = SnapshotBackendAttempt(
-      outcome: .noCapture,
-      timing: SnapshotCaptureTiming(acquisitionMs: 3_001, presentationMs: 100)
-    )
-    XCTAssertEqual(
-      Self.snapshotXCTestPenaltyReason(
-        kind: .recursiveTree,
-        attempt: slowAcquisition,
-        slowThresholdMs: 3_000
-      ),
-      "slow_tree_capture_3001ms"
-    )
-
-    let timeout = SnapshotCaptureFailure(
-      code: Self.xCTestSnapshotTimeoutCode,
-      message: "test timeout",
-      hint: "test"
-    )
-    let acquisitionFailure = SnapshotBackendAttempt(
-      outcome: .failed(timeout, phase: .acquisition),
-      timing: SnapshotCaptureTiming(acquisitionMs: 100, presentationMs: 100)
-    )
-    XCTAssertEqual(
-      Self.snapshotXCTestPenaltyReason(
-        kind: .recursiveTree,
-        attempt: acquisitionFailure,
-        slowThresholdMs: 3_000
-      ),
-      "tree_backend_timeout"
-    )
-
-    let presentationFailure = SnapshotBackendAttempt(
-      outcome: .failed(timeout, phase: .presentation),
-      timing: SnapshotCaptureTiming(acquisitionMs: 100, presentationMs: 100)
-    )
-    XCTAssertNil(
-      Self.snapshotXCTestPenaltyReason(
-        kind: .recursiveTree,
-        attempt: presentationFailure,
-        slowThresholdMs: 3_000
-      )
-    )
-  }
-
-  func testSnapshotPhaseTimerReportsAcquisitionAndPresentationSeparately() {
-    var now = Date(timeIntervalSinceReferenceDate: 100)
-    var timer = SnapshotPhaseTimer(now: { now })
-
-    _ = timer.measure(.acquisition) {
-      now = now.addingTimeInterval(2)
-    }
-    _ = timer.measure(.presentation) {
-      now = now.addingTimeInterval(5)
-    }
-
-    XCTAssertEqual(timer.timing.acquisitionMs, 2_000, accuracy: 0.001)
-    XCTAssertEqual(timer.timing.presentationMs, 5_000, accuracy: 0.001)
-  }
-}
-#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SynthesizedGesturePolicy.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SynthesizedGesturePolicy.swift
index a74bcd7908..74723a7f44 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SynthesizedGesturePolicy.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SynthesizedGesturePolicy.swift
@@ -170,107 +170,3 @@ extension RunnerTests {
       + " fallbackAttempted=\(fallbackAttempted)"
   }
 }
-
-#if AGENT_DEVICE_RUNNER_UNIT_TESTS && os(iOS)
-extension RunnerTests {
-  func testSynthesizedGesturePolicyMarkerWritesOncePerKindUntilTheDecisionChanges() {
-    var written: [String] = []
-    runnerMarkerWriter = { written.append($0) }
-    defer {
-      runnerMarkerWriter = { NSLog("%@", $0) }
-      invalidateCachedTarget(reason: "unit_test_cleanup")
-    }
-    logSynthesizedGesturePolicyDecision(kind: .coordinateTap, context: nil, fallbackAttempted: false)
-    logSynthesizedGesturePolicyDecision(kind: .coordinateTap, context: nil, fallbackAttempted: false)
-    XCTAssertEqual(written.count, 1, "a repeated decision writes no second line")
-    logSynthesizedGesturePolicyDecision(kind: .scroll, context: nil, fallbackAttempted: false)
-    XCTAssertEqual(written.count, 2, "each gesture kind states its own decision")
-    logSynthesizedGesturePolicyDecision(kind: .coordinateTap, context: nil, fallbackAttempted: true)
-    XCTAssertEqual(written.count, 3, "a changed decision writes a new line")
-    resetTargetBoundState()
-    logSynthesizedGesturePolicyDecision(kind: .coordinateTap, context: nil, fallbackAttempted: true)
-    XCTAssertEqual(written.count, 4, "a rebind states the same decision once more")
-  }
-}
-#endif
-
-#if AGENT_DEVICE_RUNNER_UNIT_TESTS
-extension RunnerTests {
-  func testSynthesizedFallbackPolicyRequiresPrivateSynthesisForScrollWhenAxUnavailableOrUnknown() {
-    XCTAssertFalse(
-      SynthesizedFallbackPolicy.privateSynthesisRequired
-        .allowsXCTestCoordinateFallback(accessibilityHealth: .unavailable)
-    )
-    XCTAssertFalse(
-      SynthesizedFallbackPolicy.privateSynthesisRequired
-        .allowsXCTestCoordinateFallback(accessibilityHealth: .unknown)
-    )
-    XCTAssertFalse(
-      SynthesizedFallbackPolicy.privateSynthesisRequired
-        .allowsXCTestCoordinateFallback(accessibilityHealth: .healthy)
-    )
-  }
-
-  func testSynthesizedDragCoordinateFallbackAllowsUnknownButNotUnavailableAccessibility() {
-    XCTAssertTrue(
-      SynthesizedFallbackPolicy.xctestCoordinateWhenAccessibilityAvailable
-        .allowsXCTestCoordinateFallback(accessibilityHealth: .healthy)
-    )
-    XCTAssertFalse(
-      SynthesizedFallbackPolicy.xctestCoordinateWhenAccessibilityAvailable
-        .allowsXCTestCoordinateFallback(accessibilityHealth: .unavailable)
-    )
-    XCTAssertTrue(
-      SynthesizedFallbackPolicy.xctestCoordinateWhenAccessibilityAvailable
-        .allowsXCTestCoordinateFallback(accessibilityHealth: .unknown)
-    )
-  }
-
-  /// Keyboard-policy semantics only. Which command gets which policy is the table below; a probe
-  /// that is merely permitted still costs a live AX fetch, so the two questions stay separate.
-  func testSynthesizedKeyboardPolicyAllowsProbeOnlyWhenAccessibilityPermitsIt() {
-    XCTAssertFalse(
-      SynthesizedKeyboardPolicy.whenAccessibilityHealthy
-        .allowsProbe(accessibilityHealth: .unknown)
-    )
-    XCTAssertTrue(
-      SynthesizedKeyboardPolicy.requiredWhenAvailable
-        .allowsProbe(accessibilityHealth: .unknown)
-    )
-    XCTAssertFalse(
-      SynthesizedKeyboardPolicy.requiredWhenAvailable
-        .allowsProbe(accessibilityHealth: .unavailable)
-    )
-  }
-
-  func testSynthesizedGesturePoliciesMatchCommandContracts() {
-    XCTAssertEqual(
-      synthesizedGesturePolicy(.coordinateTap),
-      SynthesizedGesturePolicy(
-        keyboardPolicy: .never,
-        fallbackPolicy: .xctestCoordinateAllowed
-      )
-    )
-    XCTAssertEqual(
-      synthesizedGesturePolicy(.scroll),
-      SynthesizedGesturePolicy(
-        keyboardPolicy: .requiredWhenAvailable,
-        fallbackPolicy: .privateSynthesisRequired
-      )
-    )
-    XCTAssertEqual(
-      synthesizedGesturePolicy(.synthesizedDrag),
-      SynthesizedGesturePolicy(
-        keyboardPolicy: .requiredWhenAvailable,
-        fallbackPolicy: .xctestCoordinateWhenAccessibilityAvailable
-      )
-    )
-  }
-
-  func testCoordinateTapTextInputProbeSkipsPenalizedXCTestChannel() {
-    XCTAssertTrue(shouldProbeCoordinateTapTextInput(xCTestChannelPenalized: false))
-    XCTAssertFalse(shouldProbeCoordinateTapTextInput(xCTestChannelPenalized: true))
-  }
-
-}
-#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+TextInputCandidatePolicy.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+TextInputCandidatePolicy.swift
index a46e48e80f..e8dc68912b 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+TextInputCandidatePolicy.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+TextInputCandidatePolicy.swift
@@ -14,34 +14,3 @@ func isCoordinateTextInputCandidate(
     && point.y >= frame.minY - tolerance
     && point.y <= frame.maxY + tolerance
 }
-
-extension RunnerTests {
-#if AGENT_DEVICE_RUNNER_UNIT_TESTS
-  func testCoordinateTextInputCandidateMustBeEnabledAndContainTheTouchPoint() {
-    let frame = CGRect(x: 10, y: 20, width: 100, height: 40)
-    let point = CGPoint(x: 50, y: 40)
-
-    XCTAssertTrue(
-      isCoordinateTextInputCandidate(
-        enabled: true,
-        frame: frame,
-        point: point
-      )
-    )
-    XCTAssertFalse(
-      isCoordinateTextInputCandidate(
-        enabled: false,
-        frame: frame,
-        point: point
-      )
-    )
-    XCTAssertFalse(
-      isCoordinateTextInputCandidate(
-        enabled: true,
-        frame: frame,
-        point: CGPoint(x: 200, y: 200)
-      )
-    )
-  }
-#endif
-}
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Transport.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Transport.swift
index e694f41baa..9db9f0f7e7 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Transport.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Transport.swift
@@ -200,7 +200,7 @@ extension RunnerTests {
   /// Returns true when this send duplicated a still-executing commandId and was attached as a
   /// waiter of the in-flight execution. Otherwise marks the commandId in flight and returns
   /// false so the caller enqueues the (single) execution.
-  private func attachToInFlightCommandIfNeeded(
+  func attachToInFlightCommandIfNeeded(
     command: Command,
     completion: @escaping ((data: Data, shouldFinish: Bool)) -> Void
   ) -> Bool {
@@ -221,7 +221,7 @@ extension RunnerTests {
     return false
   }
 
-  private func deliverCommandResult(
+  func deliverCommandResult(
     command: Command,
     result: (data: Data, shouldFinish: Bool),
     completion: ((data: Data, shouldFinish: Bool)) -> Void
@@ -239,45 +239,6 @@ extension RunnerTests {
     }
   }
 
-#if AGENT_DEVICE_RUNNER_UNIT_TESTS
-  func testDuplicateCommandIdCoalescesOntoInFlightExecution() throws {
-    let command = try JSONDecoder().decode(
-      Command.self,
-      from: Data(#"{"command":"snapshot","commandId":"snapshot-coalesce"}"#.utf8)
-    )
-    var primaryData: Data?
-    var waiterData: Data?
-    defer {
-      inFlightCommandIds.removeAll()
-      inFlightCommandWaiters.removeAll()
-    }
-
-    XCTAssertFalse(
-      attachToInFlightCommandIfNeeded(command: command) { result in
-        primaryData = result.data
-      }
-    )
-    XCTAssertTrue(
-      attachToInFlightCommandIfNeeded(command: command) { result in
-        waiterData = result.data
-      }
-    )
-
-    let delivered = Data("single-result".utf8)
-    deliverCommandResult(
-      command: command,
-      result: (delivered, false)
-    ) { result in
-      primaryData = result.data
-    }
-
-    XCTAssertEqual(primaryData, delivered)
-    XCTAssertEqual(waiterData, delivered)
-    XCTAssertFalse(inFlightCommandIds.contains("snapshot-coalesce"))
-    XCTAssertNil(inFlightCommandWaiters["snapshot-coalesce"])
-  }
-#endif
-
   // MARK: - Response Encoding
 
   private func jsonResponse(status: Int, response: Response) -> Data {
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+TvRemote.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+TvRemote.swift
index 252352baf0..b312933bb8 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+TvRemote.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+TvRemote.swift
@@ -18,28 +18,6 @@ enum TvRemoteButton: String {
 }
 
 extension RunnerTests {
-#if AGENT_DEVICE_RUNNER_UNIT_TESTS
-  func testTvRemoteButtonMappingAcceptsSupportedNamesAndRejectsUnknown() {
-    let supported = [
-      ("select", "select"),
-      ("SELECT", "select"),
-      ("menu", "menu"),
-      ("home", "home"),
-      ("up", "up"),
-      ("down", "down"),
-      ("left", "left"),
-      ("right", "right"),
-    ]
-    for (raw, expected) in supported {
-      XCTAssertEqual(tvRemoteButton(from: raw)?.rawValue, expected)
-    }
-
-    for raw in [String?(nil), "", "volumeUp", "select "] {
-      XCTAssertNil(tvRemoteButton(from: raw))
-    }
-  }
-#endif
-
   func resolveTvRemoteDoublePressDelay() -> TimeInterval {
     guard
       let raw = ProcessInfo.processInfo.environment["AGENT_DEVICE_TV_REMOTE_DOUBLE_PRESS_DELAY_MS"],
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+AXSnapshotFallbackTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+AXSnapshotFallbackTests.swift
new file mode 100644
index 0000000000..cbcad722a9
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+AXSnapshotFallbackTests.swift
@@ -0,0 +1,531 @@
+import XCTest
+import AgentDeviceSnapshotPresentation
+
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS
+// MARK: - In-bundle unit tests
+
+extension RunnerTests {
+  func testPrivateAXAttemptDepthsAppliesRememberedDepth() {
+    XCTAssertEqual(
+      Self.privateAXAttemptDepths(requestedDepth: 64, rememberedDepth: nil),
+      [64, 56, 40, 24, 12]
+    )
+    XCTAssertEqual(
+      Self.privateAXAttemptDepths(requestedDepth: 64, rememberedDepth: 56),
+      [56, 40, 24, 12]
+    )
+    XCTAssertEqual(Self.privateAXAttemptDepths(requestedDepth: 64, rememberedDepth: 12), [12])
+    // Remembered at/above the requested depth changes nothing.
+    XCTAssertEqual(
+      Self.privateAXAttemptDepths(requestedDepth: 64, rememberedDepth: 64),
+      [64, 56, 40, 24, 12]
+    )
+    // A shallower explicit request keeps its own rungs; deeper stale memory is ignored.
+    XCTAssertEqual(Self.privateAXAttemptDepths(requestedDepth: 24, rememberedDepth: 56), [24, 12])
+  }
+
+  /// Executed producer contract for the #1627 review blocker: a frontier whose
+  /// live element vanished, and one whose re-rooted request fails, must BOTH
+  /// count as missed — an all-miss extension reporting itself drained would
+  /// present a capped capture as complete. Goes red if either miss-path
+  /// increment in extendSnapshotFrontiers is removed.
+  func testDeepExtensionCountsMissedFrontiers() {
+    // Element vanished (list churn between serialization and extension): the
+    // fabricated snapshot answers nil for accessibilityElement — missed, and
+    // no request call is consumed. (An explicit nil property: bare NSObject
+    // resolves the key through a UIKit category and would take the call path.)
+    let orphan = RunnerAXSnapshotFrontier()
+    orphan.snapshot = FrontierSnapshotWithoutElementForTesting()
+    orphan.node = NSMutableDictionary()
+    // Re-rooted request fails: the element resolves but the client cannot
+    // serve requestSnapshotForElement — one consumed call AND a miss.
+    let unreachable = RunnerAXSnapshotFrontier()
+    unreachable.snapshot = FrontierSnapshotWithElementForTesting()
+    unreachable.node = NSMutableDictionary()
+
+    var nodeCount = 0
+    var truncated = ObjCBool(false)
+    let outcome = RunnerAXSnapshotBridge.extend(
+      NSMutableArray(array: [orphan, unreachable]),
+      axClient: NSObject(),
+      attributes: [],
+      maxDepth: 56,
+      maxNodes: 5_000,
+      nodeCount: &nodeCount,
+      truncated: &truncated,
+      callsAllowed: 8,
+      mergedLeaves: nil,
+      deadline: nil
+    )
+
+    XCTAssertEqual(outcome?[RunnerAXSnapshotDeepExtensionMissedKey] as? Int, 2)
+    XCTAssertEqual(outcome?[RunnerAXSnapshotDeepExtensionCallsKey] as? Int, 1)
+    XCTAssertEqual(outcome?[RunnerAXSnapshotDeepExtensionPendingKey] as? Int, 0)
+    XCTAssertEqual(outcome?[RunnerAXSnapshotDeepExtensionNodesAddedKey] as? Int, 0)
+    XCTAssertFalse(truncated.boolValue)
+    // And the consumer verdict over exactly this outcome: still depth-limited.
+    XCTAssertTrue(
+      Self.privateAXDepthLimited(
+        effectiveDepth: 56, requestedDepth: 64, pendingFrontiers: 0, missedFrontiers: 2))
+  }
+
+  func testPrivateAXDepthLimitedRequiresEveryFrontierResolved() {
+    // Un-capped capture is never depth-limited, extension or not.
+    XCTAssertFalse(
+      Self.privateAXDepthLimited(
+        effectiveDepth: 64, requestedDepth: 64, pendingFrontiers: nil, missedFrontiers: nil))
+    // Capped with no extension outcome (never ran) stays depth-limited.
+    XCTAssertTrue(
+      Self.privateAXDepthLimited(
+        effectiveDepth: 56, requestedDepth: 64, pendingFrontiers: nil, missedFrontiers: nil))
+    // Fully drained extension clears the verdict.
+    XCTAssertFalse(
+      Self.privateAXDepthLimited(
+        effectiveDepth: 56, requestedDepth: 64, pendingFrontiers: 0, missedFrontiers: 0))
+    // Budget exhaustion (pending frontiers) keeps it.
+    XCTAssertTrue(
+      Self.privateAXDepthLimited(
+        effectiveDepth: 56, requestedDepth: 64, pendingFrontiers: 2, missedFrontiers: 0))
+    // The #1627 review blocker: an all-miss extension (elements vanished or
+    // re-rooted requests failed) resolved nothing — it must NOT present the
+    // capture as complete just because the queue emptied.
+    XCTAssertTrue(
+      Self.privateAXDepthLimited(
+        effectiveDepth: 56, requestedDepth: 64, pendingFrontiers: 0, missedFrontiers: 8))
+  }
+
+  func testPrivateAXAcceptedDepthMemoryMatchesBundleProcessAndExpires() {
+    defer { clearPrivateAXAcceptedDepth(reason: "test-cleanup") }
+
+    rememberPrivateAXAcceptedDepth(bundleId: "xyz.blueskyweb.app", processIdentifier: 111, depth: 56)
+    XCTAssertEqual(
+      rememberedPrivateAXAcceptedDepth(bundleId: "xyz.blueskyweb.app", processIdentifier: 111),
+      56
+    )
+    XCTAssertNil(rememberedPrivateAXAcceptedDepth(bundleId: "com.other.app", processIdentifier: 111))
+    // A relaunch changes the PID; the new process must re-probe the full depth even inside the
+    // TTL, and an unknown current PID (post-invalidation) must never match.
+    XCTAssertNil(rememberedPrivateAXAcceptedDepth(bundleId: "xyz.blueskyweb.app", processIdentifier: 222))
+    XCTAssertNil(rememberedPrivateAXAcceptedDepth(bundleId: "xyz.blueskyweb.app", processIdentifier: nil))
+
+    // Expired memory stops applying (the expiry re-probes the full requested depth).
+    privateAXAcceptedDepthUntil = Date(timeIntervalSinceNow: -1)
+    XCTAssertNil(rememberedPrivateAXAcceptedDepth(bundleId: "xyz.blueskyweb.app", processIdentifier: 111))
+  }
+
+  func testPrivateAXAcceptedDepthMemoryRequiresProcessIdentifierToRecord() {
+    defer { clearPrivateAXAcceptedDepth(reason: "test-cleanup") }
+
+    rememberPrivateAXAcceptedDepth(bundleId: "xyz.blueskyweb.app", processIdentifier: nil, depth: 56)
+    XCTAssertNil(
+      rememberedPrivateAXAcceptedDepth(bundleId: "xyz.blueskyweb.app", processIdentifier: nil)
+    )
+  }
+
+  func testViewportReadSkippedWhileXCTestChannelPenalized() {
+    // Pins the viewport fast path (#1587 review): every penalized private AX capture used to burn
+    // the full 1s main-thread timeout on a doomed viewport read before falling back.
+    currentBundleId = "xyz.blueskyweb.app"
+    defer {
+      currentBundleId = nil
+      clearSnapshotXCTestChannelPenalty(reason: "test-cleanup")
+      abandonedMainThreadWorkCount = 0
+    }
+
+    XCTAssertTrue(shouldReadPrivateAXViewportViaXCTest())
+
+    penalizeSnapshotXCTestChannel(bundleId: "xyz.blueskyweb.app", reason: "test")
+    XCTAssertFalse(shouldReadPrivateAXViewportViaXCTest())
+
+    clearSnapshotXCTestChannelPenalty(reason: "test")
+    XCTAssertTrue(shouldReadPrivateAXViewportViaXCTest())
+
+    abandonedMainThreadWorkCount = 1
+    XCTAssertFalse(shouldReadPrivateAXViewportViaXCTest())
+  }
+
+  /// The wire field must reach both capture options AND the backend pin: custom
+  /// actions are only readable through the private AX client, so a capture that
+  /// asked for them but planned the XCTest tree backend would return a payload
+  /// that structurally cannot carry them.
+  func testCustomActionsRequestPinsPrivateAXBackend() throws {
+    let asked = try JSONDecoder().decode(
+      Command.self, from: Data(#"{"command":"snapshot","customActions":true}"#.utf8))
+    let options = Self.presentationOptions(from: asked)
+    XCTAssertTrue(options.customActions)
+    XCTAssertEqual(options.preferredBackend, SnapshotBackendKind.privateAX.rawValue)
+    XCTAssertTrue(
+      Self.snapshotXCTestChannelTreatedAsPenalized(
+        penalized: false, preferredBackend: options.preferredBackend))
+
+    // An explicit pin is never overwritten by the implied one.
+    let pinned = try JSONDecoder().decode(
+      Command.self,
+      from: Data(#"{"command":"snapshot","customActions":true,"preferredBackend":"tree"}"#.utf8))
+    XCTAssertEqual(Self.presentationOptions(from: pinned).preferredBackend, "tree")
+
+    // And the default capture neither asks nor pins.
+    let bare = try JSONDecoder().decode(Command.self, from: Data(#"{"command":"snapshot"}"#.utf8))
+    XCTAssertFalse(Self.presentationOptions(from: bare).customActions)
+    XCTAssertNil(Self.presentationOptions(from: bare).preferredBackend)
+  }
+
+  /// A request-pinned backend degraded nothing, so its verdict must not claim
+  /// slow accessibility work — that reason drives a user-facing warning.
+  func testRequestPinnedBackendReportsItsOwnReason() {
+    let requested = Self.xcTestChannelStateFirstFailure(
+      .deferredToIndependentBackend, requestPinnedBackend: true)
+    XCTAssertEqual(requested?.code, "requested-backend")
+    XCTAssertFalse(requested?.reason.contains("slow accessibility work") ?? true)
+
+    // The circuit breaker's own deferral keeps its established code and wording.
+    let breaker = Self.xcTestChannelStateFirstFailure(.deferredToIndependentBackend)
+    XCTAssertEqual(breaker?.code, "deferred")
+
+    // The bounded probe and the healthy plan are untouched by the new flag.
+    XCTAssertEqual(
+      Self.xcTestChannelStateFirstFailure(.boundedXCTestProbe, requestPinnedBackend: true)?.code,
+      "budget")
+    XCTAssertNil(Self.xcTestChannelStateFirstFailure(.normal, requestPinnedBackend: true))
+  }
+
+  /// The disclosure only exists if the counts survive the bridge boundary, and
+  /// "did not ask" must stay distinguishable from "read none".
+  func testCustomActionCoverageParsesOnlyCompletePairs() {
+    let complete: [String: Any] = [
+      RunnerAXSnapshotCustomActionsReadKey: 12,
+      RunnerAXSnapshotCustomActionsCandidatesKey: 19,
+      RunnerAXSnapshotCustomActionsTruncatedKey: 2,
+      RunnerAXSnapshotCustomActionsBlockedKey: true,
+    ]
+    let coverage = Self.privateAXCustomActionCoverage(complete)
+    XCTAssertEqual(coverage?.read, 12)
+    XCTAssertEqual(coverage?.candidates, 19)
+    XCTAssertEqual(coverage?.truncated, 2)
+    XCTAssertEqual(coverage?.blocked, true)
+
+    // Absent key = the capture never asked; it must not read as (0, 0), which
+    // would warn "0 of 0" on every default capture.
+    XCTAssertNil(Self.privateAXCustomActionCoverage(nil))
+    // The bridge in this target always writes all four keys, so a partial
+    // dictionary is malformed and is dropped whole.
+    for key in complete.keys {
+      var partial = complete
+      partial.removeValue(forKey: key)
+      XCTAssertNil(Self.privateAXCustomActionCoverage(partial), "missing \(key)")
+    }
+  }
+
+  /// The AX call cannot be cancelled once issued, so the read deadline frees
+  /// only the caller — the call keeps running. Without containment, repeating
+  /// `snapshot --actions` against a wedged element would stack orphaned reads,
+  /// all sharing one XCAXClient. This pins the containment: one serial queue and
+  /// a single-flight refusal that adds no work while a read is outstanding.
+  func testHungCustomActionReadIsContainedAndRecovers() {
+    let hung = HungAXClientForTesting()
+    let element = NSObject()
+    let dispatchesBefore = RunnerAXSnapshotBridge.customActionReadDispatchCount()
+    let blockedBefore = RunnerAXSnapshotBridge.customActionReadBlockedCount()
+    defer { hung.release() }
+
+    // 1. First read wedges. The caller is freed by the deadline, but the call is
+    //    still out there, so it stays counted in flight.
+    var completed = ObjCBool(true)
+    let firstStarted = Date()
+    let first = RunnerAXSnapshotBridge.customActionNames(
+      forElement: element, axClient: hung, completed: &completed)
+    XCTAssertNil(first)
+    XCTAssertFalse(completed.boolValue)
+    XCTAssertGreaterThanOrEqual(-firstStarted.timeIntervalSinceNow, 0.9)
+    XCTAssertEqual(RunnerAXSnapshotBridge.customActionReadsInFlight(), 1)
+    XCTAssertEqual(
+      RunnerAXSnapshotBridge.customActionReadDispatchCount(), dispatchesBefore + 1)
+
+    // 2. Repeats do NOT accumulate: no new dispatch, still exactly one in
+    //    flight, and every repeat is refused by single-flight admission.
+    for _ in 0..<5 {
+      XCTAssertNil(
+        RunnerAXSnapshotBridge.customActionNames(
+          forElement: element, axClient: hung, completed: &completed))
+      XCTAssertFalse(completed.boolValue)
+    }
+    XCTAssertEqual(RunnerAXSnapshotBridge.customActionReadsInFlight(), 1)
+    XCTAssertEqual(
+      RunnerAXSnapshotBridge.customActionReadDispatchCount(), dispatchesBefore + 1)
+    XCTAssertEqual(RunnerAXSnapshotBridge.customActionReadBlockedCount(), blockedBefore + 5)
+
+    // 3. A capture in that state discloses the skip rather than presenting the
+    //    unread elements as action-free — and spends no read budget doing it.
+    let leaf = RunnerAXSnapshotFrontier()
+    leaf.snapshot = FrontierSnapshotWithElementForTesting()
+    leaf.node = NSMutableDictionary(dictionary: ["label": "feedItem", "children": []])
+    let coverage = RunnerAXSnapshotBridge.annotateCustomActions(
+      onMergedLeaves: [leaf], axClient: hung, limit: 12, rootFrame: .zero, deadline: nil)
+    XCTAssertEqual(coverage[RunnerAXSnapshotCustomActionsBlockedKey] as? Bool, true)
+    XCTAssertEqual(coverage[RunnerAXSnapshotCustomActionsReadKey] as? Int, 0)
+    XCTAssertEqual(coverage[RunnerAXSnapshotCustomActionsCandidatesKey] as? Int, 1)
+    XCTAssertEqual(
+      RunnerAXSnapshotBridge.customActionReadDispatchCount(), dispatchesBefore + 1)
+    XCTAssertEqual(
+      Self.privateAXCustomActionCoverage(coverage),
+      SnapshotCustomActionCoverage(read: 0, candidates: 1, truncated: 0, blocked: true))
+
+    // 4. Recovery: once the wedged call returns, reads resume by themselves.
+    hung.release()
+    let recovered = expectation(description: "in-flight drains")
+    DispatchQueue.global().async {
+      while RunnerAXSnapshotBridge.customActionReadsInFlight() > 0 {
+        usleep(20_000)
+      }
+      recovered.fulfill()
+    }
+    wait(for: [recovered], timeout: 5)
+
+    completed = ObjCBool(false)
+    XCTAssertNil(
+      RunnerAXSnapshotBridge.customActionNames(
+        forElement: element, axClient: hung, completed: &completed))
+    // Completed (the fake answers nil actions), which is the point: the pass is
+    // live again rather than latched off.
+    XCTAssertTrue(completed.boolValue)
+    XCTAssertEqual(
+      RunnerAXSnapshotBridge.customActionReadDispatchCount(), dispatchesBefore + 2)
+  }
+
+  /// The element budget bounds how many elements we read; these caps bound what
+  /// any ONE element can put in the response. Clipping must be reported, since
+  /// a clipped list looks exactly like a complete one.
+  func testActionNamesAreCappedPerElementAndReported() {
+    var truncated = ObjCBool(true)
+
+    // Under both caps: untouched, nothing to report.
+    let small = ["Reply", "Repost"]
+    XCTAssertEqual(
+      RunnerAXSnapshotBridge.cappedActionNames(small, truncated: &truncated), small)
+    XCTAssertFalse(truncated.boolValue)
+
+    // More actions than the per-element cap: clipped to the first 8, reported.
+    let many = (1...20).map { "Action \($0)" }
+    let cappedMany = RunnerAXSnapshotBridge.cappedActionNames(many, truncated: &truncated)
+    XCTAssertEqual(cappedMany.count, 8)
+    XCTAssertEqual(cappedMany.first, "Action 1")
+    XCTAssertTrue(truncated.boolValue)
+
+    // A single very long name is shortened, reported, and stays one string.
+    let long = String(repeating: "a", count: 500)
+    let cappedLong = RunnerAXSnapshotBridge.cappedActionNames([long], truncated: &truncated)
+    XCTAssertEqual(cappedLong.count, 1)
+    XCTAssertTrue(truncated.boolValue)
+    XCTAssertLessThan(cappedLong[0].count, long.count)
+    XCTAssertTrue(cappedLong[0].hasSuffix("…"))
+
+    // Empty input is not "truncated".
+    XCTAssertEqual(RunnerAXSnapshotBridge.cappedActionNames([], truncated: &truncated), [])
+    XCTAssertFalse(truncated.boolValue)
+  }
+
+  /// Action names annotated by the bridge must survive into the emitted node —
+  /// the whole point of the capture is that the merged card names its hidden
+  /// affordances.
+  func testPrivateAXNodesCarryAnnotatedCustomActions() {
+    let tree: [String: Any] = [
+      "type": Int(XCUIElement.ElementType.application.rawValue),
+      "label": "Blue Sky",
+      "frame": ["x": 0, "y": 0, "width": 390, "height": 844],
+      "children": [
+        [
+          "type": Int(XCUIElement.ElementType.link.rawValue),
+          "label": "feedItem-by-whiskers.test",
+          "frame": ["x": 0, "y": 100, "width": 390, "height": 200],
+          "actions": ["Reply", "Repost", "Open post options menu"],
+          "children": [],
+        ],
+        [
+          "type": Int(XCUIElement.ElementType.button.rawValue),
+          "label": "Compose",
+          "frame": ["x": 300, "y": 700, "width": 60, "height": 60],
+          "children": [],
+        ],
+      ],
+    ]
+    let nodes = privateAXAcquisition(
+      rawRoot: tree,
+      hint: CaptureHint(
+        projection: .regular, depth: nil, regularPresentedDepth: nil,
+        interactiveOnly: false, customActions: false)
+    )
+
+    let card = nodes.first { $0.label == "feedItem-by-whiskers.test" }
+    XCTAssertEqual(card?.actions, ["Reply", "Repost", "Open post options menu"])
+    // A node the bridge did not annotate stays absent, not empty.
+    XCTAssertNil(nodes.first { $0.label == "Compose" }?.actions)
+  }
+
+  func testPrivateAXAcquisitionDoesNotInterpretScope() {
+    let tree: [String: Any] = [
+      "type": 1, "label": "App",
+      "children": [
+        [
+          "type": 9, "identifier": "homeScreen",
+          "children": [
+            ["type": 48, "label": "Post body without the scope text", "children": []]
+          ],
+        ],
+        ["type": 9, "label": "unrelated sibling", "children": []],
+      ],
+    ]
+    // Scope never reaches acquisition: the hint derived for a scoped request carries no scope,
+    // and the backend has no way to interpret one.
+    let nodes = privateAXAcquisition(
+      rawRoot: tree,
+      hint: SnapshotPresentation.captureHint(
+        for: PresentationOptions(
+          interactiveOnly: false,
+          depth: nil,
+          scope: "homeScreen",
+          raw: false
+        )
+      )
+    )
+
+    let labels = nodes.compactMap { $0.label ?? $0.identifier }
+    XCTAssertTrue(labels.contains("homeScreen"))
+    // Descendants of the matched scope are included even when they do not contain the text.
+    XCTAssertTrue(labels.contains("Post body without the scope text"))
+    XCTAssertTrue(labels.contains("unrelated sibling"))
+  }
+
+  func testPrivateAXInteractiveFiltersLoginLikeHiddenDrawer() throws {
+    let tree: [String: Any] = [
+      "type": Int(XCUIElement.ElementType.application.rawValue),
+      "label": "Blue Sky",
+      "frame": ["x": 0, "y": 0, "width": 390, "height": 844],
+      "children": [
+        [
+          "type": Int(XCUIElement.ElementType.scrollView.rawValue),
+          "frame": ["x": 0, "y": 0, "width": 390, "height": 844],
+          "children": [
+            [
+              "type": Int(XCUIElement.ElementType.image.rawValue),
+              "label": "Callstack",
+              "frame": ["x": 145, "y": 104, "width": 100, "height": 100],
+              "children": [],
+            ],
+            [
+              "type": Int(XCUIElement.ElementType.staticText.rawValue),
+              "label": "Welcome back",
+              "frame": ["x": 32, "y": 260, "width": 326, "height": 32],
+              "children": [],
+            ],
+            [
+              "type": Int(XCUIElement.ElementType.textField.rawValue),
+              "label": "Email",
+              "identifier": "login.email",
+              "frame": ["x": 32, "y": 348, "width": 326, "height": 48],
+              "children": [],
+            ],
+            [
+              "type": Int(XCUIElement.ElementType.secureTextField.rawValue),
+              "label": "Password",
+              "identifier": "login.password",
+              "frame": ["x": 32, "y": 412, "width": 326, "height": 48],
+              "children": [],
+            ],
+            [
+              "type": Int(XCUIElement.ElementType.button.rawValue),
+              "label": "Sign in",
+              "identifier": "login.submit",
+              "frame": ["x": 32, "y": 492, "width": 326, "height": 52],
+              "children": [],
+            ],
+            [
+              "type": Int(XCUIElement.ElementType.link.rawValue),
+              "label": "Forgot password?",
+              "frame": ["x": 128, "y": 568, "width": 134, "height": 32],
+              "children": [],
+            ],
+            [
+              "type": Int(XCUIElement.ElementType.button.rawValue),
+              "label": "Admin settings",
+              "frame": ["x": -260, "y": 184, "width": 220, "height": 44],
+              "children": [],
+            ],
+            [
+              "type": Int(XCUIElement.ElementType.other.rawValue),
+              "frame": ["x": 16, "y": 184, "width": 220, "height": 44],
+              "children": [],
+            ],
+          ],
+        ]
+      ],
+    ]
+    let viewport = CGRect(x: 0, y: 0, width: 390, height: 844)
+    let hint = CaptureHint(
+      projection: .regular, depth: nil, regularPresentedDepth: nil,
+      interactiveOnly: true, customActions: false)
+    let acquired = SnapshotGeometrySpace.normalized(
+      nodes: privateAXAcquisition(rawRoot: tree, hint: hint),
+      viewport: viewport,
+      interfaceOrientation: RunnerInterfaceOrientation.portrait
+    )
+    // Acquisition serializes the drawer too; the shared fold is what hides it (#1797).
+    XCTAssertTrue(acquired.compactMap(\.label).contains("Admin settings"))
+
+    let capture = try SnapshotPresentation.presentRegular(
+      SnapshotAcquisition(
+        hint: hint, nodes: acquired, truncated: false, effectiveDepth: nil, viewport: viewport),
+      options: PresentationOptions(interactiveOnly: true, depth: nil, scope: nil, raw: false),
+      policy: .cursorProjected
+    )
+    let labels = capture.nodes.compactMap { $0.label }
+    XCTAssertEqual(
+      labels,
+      ["Blue Sky", "Callstack", "Welcome back", "Email", "Password", "Sign in", "Forgot password?"]
+    )
+    XCTAssertFalse(labels.contains("Admin settings"))
+  }
+}
+
+/// Stands in for an AX client whose `attributesForElement:` never returns —
+/// the wedged-server case the containment exists for. `release()` lets the
+/// hung call finish so recovery is observable.
+private final class HungAXClientForTesting: NSObject {
+  private let gate = DispatchSemaphore(value: 0)
+  private let releasedOnce = NSLock()
+  private var released = false
+
+  @objc(attributesForElement:attributes:error:)
+  func attributes(forElement element: Any, attributes: Any, error: NSErrorPointer) -> Any? {
+    releasedOnce.lock()
+    let alreadyReleased = released
+    releasedOnce.unlock()
+    // Once the wedge clears, the server answers normally again — that is what
+    // makes the recovery leg a recovery rather than a second hang.
+    if alreadyReleased {
+      return nil
+    }
+    gate.wait()
+    return nil
+  }
+
+  func release() {
+    releasedOnce.lock()
+    defer { releasedOnce.unlock() }
+    guard !released else { return }
+    released = true
+    gate.signal()
+  }
+}
+
+/// Minimal snapshot stand-in whose accessibilityElement resolves (so the
+/// extension proceeds to the request) while the paired fake client cannot
+/// serve it — the failed-re-root miss path.
+private final class FrontierSnapshotWithElementForTesting: NSObject {
+  @objc let accessibilityElement = NSObject()
+}
+
+/// The vanished-element case: KVC resolves the property and gets nil.
+private final class FrontierSnapshotWithoutElementForTesting: NSObject {
+  @objc let accessibilityElement: NSObject? = nil
+}
+#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+AlertTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+AlertTests.swift
new file mode 100644
index 0000000000..1beb0bec9d
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+AlertTests.swift
@@ -0,0 +1,9 @@
+import XCTest
+
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS
+extension RunnerTests {
+  func testAlertAcceptTreatsOpenAsAffirmative() {
+    XCTAssertTrue(isAcceptButton("Open"))
+  }
+}
+#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+BlockingSystemModalResolutionTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+BlockingSystemModalResolutionTests.swift
new file mode 100644
index 0000000000..8a124bb669
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+BlockingSystemModalResolutionTests.swift
@@ -0,0 +1,37 @@
+import XCTest
+
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS
+extension RunnerTests {
+  func testRemoteHostProbeRunsOnlyWhenSpringboardModalHasNoActions() {
+    XCTAssertTrue(RemoteHostedSystemModalPolicy.shouldProbeRemoteHost(springboardActionCount: 0))
+    XCTAssertFalse(RemoteHostedSystemModalPolicy.shouldProbeRemoteHost(springboardActionCount: 1))
+    XCTAssertFalse(RemoteHostedSystemModalPolicy.shouldProbeRemoteHost(springboardActionCount: 3))
+  }
+
+  func testRemoteHostStateGateFailsClosedToForeground() {
+    XCTAssertTrue(RemoteHostedSystemModalPolicy.isEligibleHostState(.runningForeground))
+    XCTAssertFalse(RemoteHostedSystemModalPolicy.isEligibleHostState(.runningBackground))
+    XCTAssertFalse(RemoteHostedSystemModalPolicy.isEligibleHostState(.notRunning))
+    XCTAssertFalse(RemoteHostedSystemModalPolicy.isEligibleHostState(.unknown))
+  }
+
+  // No SpringBoard host (`hasSpringBoardSystemModalHost`) means modal resolution must return
+  // `.absent` without probing com.apple.springboard (#1351). Written for tvOS, where no lane
+  // ever executed it; `resolveBlockingSystemModal` takes that decision at RUNTIME off the same
+  // flag on macOS, so the host lane runs the real branch on every PR.
+  //
+  // Its former sibling `testBlockingSystemAlertSnapshotIsNilOnTvOS` is deleted rather than
+  // widened: `blockingSystemAlertSnapshot` is `#if os(macOS) return nil`, so on the only lane
+  // that could run it the assertion would pin a compile-time literal — a green that no change
+  // to the runner could turn red. The runtime gate it meant to cover is this test's subject,
+  // and the nil it returns on macOS is the compiler's business, not a test's.
+  #if os(tvOS) || os(macOS)
+  func testResolveBlockingSystemModalIsAbsentWithoutSpringBoardHost() {
+    guard case .absent = resolveBlockingSystemModal(deadline: .distantFuture) else {
+      XCTFail("blocking system-modal resolution must be .absent without a SpringBoard host")
+      return
+    }
+  }
+  #endif
+}
+#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+CommandExecutionTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+CommandExecutionTests.swift
new file mode 100644
index 0000000000..b763b9e07e
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+CommandExecutionTests.swift
@@ -0,0 +1,704 @@
+import XCTest
+import AgentDeviceSnapshotPresentation
+
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS && os(iOS)
+import ObjectiveC.runtime
+
+private final class RunnerSynthesizedSwipeFailureStub: NSObject {
+  @objc(synthesizeSwipeWithApplication:resolvedWindow:x:y:x2:y2:durationMs:)
+  class func synthesizeSwipe(
+    application: XCUIApplication,
+    resolvedWindow: Any?,
+    x: Double,
+    y: Double,
+    x2: Double,
+    y2: Double,
+    durationMs: Double
+  ) -> String? {
+    "forced private synthesis failure"
+  }
+}
+
+private final class RunnerSynthesizedTapFailureStub: NSObject {
+  @objc(synthesizeTapWithApplication:resolvedWindow:x:y:)
+  class func synthesizeTap(application: XCUIApplication, resolvedWindow: Any?, x: Double, y: Double) -> String? {
+    "forced private synthesis failure"
+  }
+}
+#endif
+
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS
+extension RunnerTests {
+  func testGestureResponseIncludesSynthesizedTapFallbackDiagnostics() {
+    let response = gestureResponse(
+      message: "tapped",
+      timing: (gestureStartUptimeMs: 1, gestureEndUptimeMs: 2),
+      fallback: GestureFallback(
+        strategy: "xctest-coordinate-tap",
+        message: "Runner synthesized coordinate tap is unavailable",
+        hint: "Using XCTest coordinate tap fallback."
+      )
+    )
+
+    XCTAssertEqual(response.ok, true)
+    XCTAssertEqual(response.data?.gestureFallback, "xctest-coordinate-tap")
+    XCTAssertEqual(
+      response.data?.gestureFallbackMessage,
+      "Runner synthesized coordinate tap is unavailable"
+    )
+    XCTAssertEqual(response.data?.gestureFallbackHint, "Using XCTest coordinate tap fallback.")
+  }
+
+  func testGestureResponseIncludesMaestroNonHittableFallbackUsage() {
+    let response = gestureResponse(
+      message: "tapped via non-hittable coordinate fallback",
+      timing: (gestureStartUptimeMs: 1, gestureEndUptimeMs: 2),
+      frame: .touch(nil),
+      maestroNonHittableCoordinateFallbackUsed: true
+    )
+
+    XCTAssertEqual(response.data?.maestroNonHittableCoordinateFallbackUsed, true)
+  }
+
+  func testCanonicalPlannedGestureResponseOmitsDragFrameAndPreservesDiagnostics() {
+    let response = gestureResponse(
+      message: "fling",
+      timing: (gestureStartUptimeMs: 1, gestureEndUptimeMs: 2),
+      frame: .drag(
+        DragVisualizationFrame(
+          x: 160,
+          y: 150,
+          x2: 40,
+          y2: 150,
+          referenceWidth: 200,
+          referenceHeight: 300
+        )
+      ),
+      fallback: GestureFallback(
+        strategy: "xctest-coordinate-drag",
+        message: "Private synthesis unavailable",
+        hint: "Using XCTest coordinate fallback."
+      )
+    )
+
+    let canonical = canonicalPlannedGestureResponse(response)
+
+    XCTAssertEqual(canonical.data?.gestureStartUptimeMs, 1)
+    XCTAssertEqual(canonical.data?.gestureEndUptimeMs, 2)
+    XCTAssertEqual(canonical.data?.gestureFallback, "xctest-coordinate-drag")
+    XCTAssertEqual(canonical.data?.gestureFallbackMessage, "Private synthesis unavailable")
+    XCTAssertEqual(canonical.data?.gestureFallbackHint, "Using XCTest coordinate fallback.")
+    XCTAssertNil(canonical.data?.x)
+    XCTAssertNil(canonical.data?.y)
+    XCTAssertNil(canonical.data?.x2)
+    XCTAssertNil(canonical.data?.y2)
+    XCTAssertNil(canonical.data?.referenceWidth)
+    XCTAssertNil(canonical.data?.referenceHeight)
+  }
+
+#if os(iOS)
+  func testSinglePointerFlingFallsBackToXCTestCoordinateDragWhenPrivateSynthesisFails() throws {
+    let selector = NSSelectorFromString(
+      "synthesizeSwipeWithApplication:resolvedWindow:x:y:x2:y2:durationMs:"
+    )
+    guard
+      let synthesizedSwipeMethod = class_getClassMethod(RunnerSynthesizedGesture.self, selector),
+      let failureStubMethod = class_getClassMethod(RunnerSynthesizedSwipeFailureStub.self, selector)
+    else {
+      XCTFail("unable to install synthesized swipe failure stub")
+      return
+    }
+    let originalImplementation = method_getImplementation(synthesizedSwipeMethod)
+    method_setImplementation(
+      synthesizedSwipeMethod,
+      method_getImplementation(failureStubMethod)
+    )
+    app.launch()
+    runnerAccessibilityHealth = .healthy
+    defer {
+      method_setImplementation(synthesizedSwipeMethod, originalImplementation)
+      invalidateCachedTarget(reason: "unit_test_cleanup")
+      app.terminate()
+    }
+    let command = try runnerCommandFixture(
+      """
+      {"command":"gesture","commandId":"gesture-fling-fallback","gesturePlan":{"topology":"single","intent":"fling","executionProfile":"endpoint-hold","durationMs":100,"viewport":{"x":0,"y":0,"width":200,"height":300},"pointers":[{"pointerId":0,"samples":[{"offsetMs":0,"point":{"x":160,"y":150}},{"offsetMs":100,"point":{"x":40,"y":150}}]}]}}
+      """
+    )
+
+    let response = try executeOnMainPrepared(command: command, activeApp: app)
+
+    XCTAssertTrue(response.ok)
+    XCTAssertEqual(response.data?.message, "fling")
+    XCTAssertEqual(response.data?.gestureFallback, "xctest-coordinate-drag")
+    XCTAssertEqual(response.data?.gestureFallbackMessage, "forced private synthesis failure")
+    XCTAssertEqual(
+      response.data?.gestureFallbackHint,
+      "Private XCTest event synthesis is required for AX-free coordinate drag on iOS; update Xcode if this persists."
+    )
+    XCTAssertNil(response.data?.x)
+    XCTAssertNil(response.data?.y)
+    XCTAssertNil(response.data?.x2)
+    XCTAssertNil(response.data?.y2)
+  }
+
+  func testSelectorTapFallsBackToXCTestCoordinateWhenPrivateSynthesisFails() throws {
+    let selector = NSSelectorFromString("synthesizeTapWithApplication:resolvedWindow:x:y:")
+    guard
+      let synthesizedTapMethod = class_getClassMethod(RunnerSynthesizedGesture.self, selector),
+      let failureStubMethod = class_getClassMethod(RunnerSynthesizedTapFailureStub.self, selector)
+    else {
+      XCTFail("unable to install synthesized tap failure stub")
+      return
+    }
+    let originalImplementation = method_getImplementation(synthesizedTapMethod)
+    method_setImplementation(
+      synthesizedTapMethod,
+      method_getImplementation(failureStubMethod)
+    )
+    app.launch()
+    currentApp = app
+    runnerAccessibilityHealth = .healthy
+    defer {
+      method_setImplementation(synthesizedTapMethod, originalImplementation)
+      invalidateCachedTarget(reason: "unit_test_cleanup")
+      app.terminate()
+    }
+    let command = try runnerCommandFixture(
+      #"{"command":"tap","commandId":"selector-tap-fallback","selectorKey":"label","selectorValue":"Agent Device Runner","synthesized":true}"#
+    )
+
+    let response = try executeOnMainPrepared(command: command, activeApp: app)
+
+    XCTAssertTrue(response.ok)
+    XCTAssertEqual(response.data?.message, "tapped")
+    XCTAssertEqual(response.data?.gestureFallback, "xctest-coordinate-tap")
+    XCTAssertEqual(response.data?.gestureFallbackMessage, "forced private synthesis failure")
+    XCTAssertEqual(
+      response.data?.gestureFallbackHint,
+      "Falling back to XCTest coordinate tap may be slower and can still need a healthy accessibility tree."
+    )
+  }
+#endif
+
+#if os(iOS)
+  // `waitForTextEntryReadiness`'s hardware-keyboard fallback returns early only on confirmed
+  // focus (#1874), and `keyboardFocusConfirmed` reads that from the app-wide focus predicate this
+  // bundle otherwise refuses to trust. Two XCTest facts it rests on, neither a repository
+  // invariant: the predicate reports a responder that shows NO software keyboard at all, and it
+  // names the element well enough to tell the tapped field from another one. The fixture field is
+  // the exact shape the fallback exists for — a real responder with an empty `inputView` — so this
+  // is where both are observable. If either regressed, readiness would silently stop taking the
+  // fallback and spend the full readinessTimeout on every hardware-keyboard field, which no other
+  // assertion would notice.
+  func testHardwareKeyboardResponderConfirmsItsOwnKeyboardFocus() throws {
+    app.launchArguments = ["--agent-device-text-entry-regression"]
+    app.launch()
+    defer {
+      invalidateCachedTarget(reason: "unit_test_cleanup")
+      app.terminate()
+    }
+    XCTAssertTrue(app.waitForExistence(timeout: appExistenceTimeout))
+
+    let textField = app.textFields["agent-device-hardware-keyboard-input"]
+    XCTAssertTrue(textField.waitForExistence(timeout: appExistenceTimeout))
+    let otherElement = app.staticTexts["Agent Device Runner"]
+    XCTAssertTrue(otherElement.waitForExistence(timeout: appExistenceTimeout))
+    XCTAssertFalse(
+      keyboardFocusConfirmed(app: app, element: textField),
+      "an untapped field must not confirm focus, or the fallback would fire immediately"
+    )
+
+    let tapCommand = try runnerCommandFixture(
+      #"{"command":"tap","commandId":"tap-focus-confirmation","selectorKey":"id","selectorValue":"agent-device-hardware-keyboard-input"}"#
+    )
+    let tapResponse = try executeOnMainPrepared(command: tapCommand, activeApp: app)
+    XCTAssertTrue(tapResponse.ok, String(describing: tapResponse.error))
+    try XCTSkipIf(
+      isKeyboardVisible(app: app),
+      "software keyboard is up: this simulator cannot exercise the hidden-keyboard responder path"
+    )
+
+    let deadline = Date().addingTimeInterval(TextEntryTiming.readinessTimeout)
+    var confirmed = keyboardFocusConfirmed(app: app, element: textField)
+    while !confirmed && Date() < deadline {
+      sleepFor(TextEntryTiming.pollInterval)
+      confirmed = keyboardFocusConfirmed(app: app, element: textField)
+    }
+    XCTAssertTrue(confirmed, "a tapped responder must confirm its own keyboard focus")
+    XCTAssertFalse(
+      keyboardFocusConfirmed(app: app, element: otherElement),
+      "focus held by another element must read as a refusal, never as this element's focus"
+    )
+  }
+#endif
+
+  func testInjectedTapRecordedFailureGateIsTapOnlyAndCountGated() {
+    // The seam's recording side cannot run in-bundle (a real XCTIssue would
+    // fail this very test run — same constraint the record(_:) suppression
+    // tests document); the live daemon proof covers it. This pins the gate.
+    XCTAssertFalse(RunnerTests.shouldInjectTapRecordedFailure(command: .tap, remaining: 0))
+    XCTAssertTrue(RunnerTests.shouldInjectTapRecordedFailure(command: .tap, remaining: 1))
+    XCTAssertFalse(RunnerTests.shouldInjectTapRecordedFailure(command: .type, remaining: 1))
+    XCTAssertFalse(RunnerTests.shouldInjectTapRecordedFailure(command: .snapshot, remaining: 1))
+  }
+
+  func testXCTestRecordedFailureResponseFailsMutatingSuccesses() throws {
+    let command = try runnerCommandFixture(#"{"command":"tap","commandId":"tap-1"}"#)
+    let response = Response(ok: true, data: DataPayload(message: "tapped"))
+
+    let failureResponse = xctestRecordedFailureResponse(command: command, response: response)
+
+    XCTAssertEqual(failureResponse?.ok, false)
+    XCTAssertEqual(failureResponse?.error?.code, "XCTEST_RECORDED_FAILURE")
+    XCTAssertEqual(
+      failureResponse?.error?.message,
+      "XCTest recorded a failure while executing tap; the action may not have been performed."
+    )
+  }
+
+  func testXCTestRecordedFailureResponseFailsActionButtonSuccess() throws {
+    // The Action Button press carries no settle and no post-action observation, so this conversion is
+    // the only evidence the press landed. That is why the press is not classified runner-lifecycle:
+    // `isLifecycle` would silence the conversion here (#2699, #2702 review).
+    let command = try runnerCommandFixture(#"{"command":"actionButton","commandId":"action-button-1"}"#)
+    let response = Response(ok: true, data: DataPayload(message: "actionButton"))
+
+    let failureResponse = xctestRecordedFailureResponse(command: command, response: response)
+
+    XCTAssertEqual(failureResponse?.ok, false)
+    XCTAssertEqual(failureResponse?.error?.code, "XCTEST_RECORDED_FAILURE")
+    XCTAssertEqual(
+      failureResponse?.error?.message,
+      "XCTest recorded a failure while executing actionButton; the action may not have been performed."
+    )
+  }
+
+  func testXCTestRecordedFailureResponseDoesNotWrapReadOnlyOrRunnerFatalResponses() throws {
+    let snapshotCommand = try runnerCommandFixture(#"{"command":"snapshot","commandId":"snapshot-1"}"#)
+    let tapCommand = try runnerCommandFixture(#"{"command":"tap","commandId":"tap-1"}"#)
+    let runnerFatalResponse = Response(
+      ok: true,
+      data: DataPayload(runnerFatal: true, runnerFatalReason: "ax_snapshot_unavailable")
+    )
+
+    XCTAssertNil(
+      xctestRecordedFailureResponse(
+        command: snapshotCommand,
+        response: Response(ok: true, data: DataPayload(nodes: [], truncated: false))
+      )
+    )
+    XCTAssertNil(xctestRecordedFailureResponse(command: tapCommand, response: runnerFatalResponse))
+  }
+
+  // Simulator-only from here to the matching #endif: these launch the host app, route through
+  // SpringBoard, or assert the iOS-only alert/system-modal branches. Tests outside the
+  // `os(iOS)` regions in this file are pure runner decisions and also run on the macOS host
+  // lane (ci.yml) — see the classification convention in RunnerTests.swift.
+#if os(iOS)
+  func testMissingBundleCommandInvalidatesCompleteCachedTargetState() throws {
+    app.launch()
+    currentApp = app
+    currentBundleId = "com.example.stale-target"
+    currentAppProcessIdentifier = 42
+    snapshotXCTestPenaltyWarmupExemptionPending = true
+    defer {
+      invalidateCachedTarget(reason: "unit_test_cleanup")
+      app.terminate()
+    }
+    let command = try runnerCommandFixture(
+      #"{"command":"snapshot","commandId":"snapshot-without-bundle"}"#
+    )
+
+    _ = prepareActiveCommandContext(command: command)
+
+    XCTAssertNil(currentApp)
+    XCTAssertNil(currentBundleId)
+    XCTAssertNil(currentAppProcessIdentifier)
+    XCTAssertFalse(snapshotXCTestPenaltyWarmupExemptionPending)
+  }
+
+  func testSkipAppActivationPreflightIncludesForegroundCachedCoordinateOnlyTaps() throws {
+    app.launch()
+    currentApp = app
+    currentBundleId = nil
+    defer {
+      currentApp = nil
+      currentBundleId = nil
+      app.terminate()
+    }
+    let tap = try runnerCommandFixture(
+      #"{"command":"tap","commandId":"tap-1","x":10,"y":20}"#
+    )
+
+    XCTAssertTrue(shouldSkipAppActivationPreflight(tap))
+  }
+
+  func testSkipAppActivationPreflightRejectsMissingChangedAndBackgroundTargets() throws {
+    let coordinateTap = try runnerCommandFixture(
+      #"{"command":"tap","commandId":"tap-1","x":10,"y":20}"#
+    )
+    currentApp = nil
+    currentBundleId = nil
+    XCTAssertFalse(shouldSkipAppActivationPreflight(coordinateTap))
+
+    app.launch()
+    currentApp = app
+    currentBundleId = "com.example.current"
+    defer {
+      currentApp = nil
+      currentBundleId = nil
+      app.terminate()
+    }
+    let changedBundleTap = try runnerCommandFixture(
+      #"{"command":"tap","commandId":"tap-2","appBundleId":"com.example.other","x":10,"y":20}"#
+    )
+
+    XCTAssertFalse(shouldSkipAppActivationPreflight(changedBundleTap))
+
+    app.terminate()
+    currentApp = app
+    currentBundleId = nil
+
+    XCTAssertFalse(shouldSkipAppActivationPreflight(coordinateTap))
+  }
+
+  func testActionButtonPressSkipsAppActivationPreflightWithoutBeingRunnerLifecycle() throws {
+    currentApp = nil
+    currentBundleId = nil
+    let press = try runnerCommandFixture(#"{"command":"actionButton","commandId":"action-button-1"}"#)
+
+    // The skip is its own decision, reached without the lifecycle flag that would also drop the
+    // recorded-failure conversion; no cached target and no foreground app is required for it.
+    XCTAssertFalse(isRunnerLifecycleCommand(.actionButton))
+    XCTAssertTrue(shouldSkipAppActivationPreflight(press))
+  }
+
+  func testPrepareActiveCommandContextRoutesBlockingSystemModalToSpringboard() throws {
+    blockingSystemModalPresenceOverrideForTesting = true
+    currentApp = nil
+    currentBundleId = nil
+    defer {
+      blockingSystemModalPresenceOverrideForTesting = nil
+      currentApp = nil
+      currentBundleId = nil
+    }
+    let tap = try runnerCommandFixture(
+      #"{"command":"tap","commandId":"tap-1","x":10,"y":20}"#
+    )
+
+    let preparation = prepareActiveCommandContext(
+      command: tap,
+      routeToSpringboard: shouldRouteToSpringboardBlockingSystemModal(tap)
+    )
+
+    guard case .context(let context) = preparation else {
+      XCTFail("expected command context")
+      return
+    }
+    XCTAssertTrue(context.app === springboard)
+  }
+
+  func testExecuteDispatchedReturnsBusyBeforeBlockingSystemModalProbeDrains() throws {
+    app.launch()
+    currentApp = app
+    currentBundleId = nil
+    defer {
+      currentApp = nil
+      currentBundleId = nil
+      systemModalProbeOverrideForTesting = nil
+      clearSnapshotXCTestChannelPenalty(reason: "test-cleanup")
+      app.terminate()
+    }
+
+    final class ResultBox {
+      var response: Response?
+      var error: Error?
+      var commandRecoveredBeforeRelease = false
+      var wasBusyBeforeRelease = false
+      var hadAbandonedProbeBeforeRelease = false
+      var drained = false
+    }
+    let box = ResultBox()
+    let probeStarted = expectation(description: "system-modal routing probe started")
+    let verificationFinished = expectation(description: "command recovery and modal probe drain verified")
+    let probeReleaseGate = DispatchSemaphore(value: 0)
+    let commandFinishedGate = DispatchSemaphore(value: 0)
+    systemModalProbeOverrideForTesting = { _ in
+      probeStarted.fulfill()
+      _ = probeReleaseGate.wait(timeout: .now() + 15)
+      return DataPayload(message: "late system modal")
+    }
+
+    let command = try runnerCommandFixture(
+      #"{"command":"tap","commandId":"bounded-modal-routing","x":10,"y":20}"#
+    )
+    DispatchQueue(label: "agent-device.runner.tests.modal-routing-probe").async {
+      do {
+        box.response = try self.executeDispatched(command: command)
+      } catch {
+        box.error = error
+      }
+      commandFinishedGate.signal()
+    }
+    DispatchQueue(label: "agent-device.runner.tests.modal-routing-probe-verifier").async {
+      let commandWait = commandFinishedGate.wait(
+        timeout: .now() + self.systemModalProbeBudget + 3
+      )
+      box.commandRecoveredBeforeRelease = commandWait == .success
+        && box.error == nil
+        && box.response?.error?.code == "RUNNER_BUSY"
+      if case .busy = self.currentMainThreadBusyState() {
+        box.wasBusyBeforeRelease = true
+      }
+      box.hadAbandonedProbeBeforeRelease = self.hasAbandonedMainThreadWork()
+
+      // The XCTest main thread is blocked inside the injected probe, so this verifier owns the
+      // ordered release after recording the command result and abandoned-work state above.
+      probeReleaseGate.signal()
+      let deadline = Date().addingTimeInterval(5)
+      while self.hasAbandonedMainThreadWork(), Date() < deadline {
+        self.sleepFor(0.002)
+      }
+      box.drained = !self.hasAbandonedMainThreadWork()
+      verificationFinished.fulfill()
+    }
+
+    wait(for: [probeStarted, verificationFinished], timeout: 15)
+    XCTAssertTrue(
+      box.commandRecoveredBeforeRelease,
+      "the public coordinate tap must return RUNNER_BUSY before the blocked modal probe drains"
+    )
+    XCTAssertTrue(box.wasBusyBeforeRelease)
+    XCTAssertTrue(box.hadAbandonedProbeBeforeRelease)
+    XCTAssertTrue(box.drained)
+    guard case .idle = currentMainThreadBusyState() else {
+      return XCTFail("expected the runner to become idle after the routing probe drained")
+    }
+    XCTAssertFalse(hasAbandonedMainThreadWork())
+  }
+
+  func testSkipAppActivationPreflightRejectsSelectorAndMixedSequenceGestures() throws {
+    app.launch()
+    currentApp = app
+    currentBundleId = nil
+    defer {
+      currentApp = nil
+      currentBundleId = nil
+      app.terminate()
+    }
+    let selectorTap = try runnerCommandFixture(
+      #"{"command":"tap","commandId":"tap-1","selectorKey":"label","selectorValue":"Search","synthesized":true}"#
+    )
+    let standardDrag = try runnerCommandFixture(
+      #"{"command":"drag","commandId":"drag-1","x":10,"y":20,"x2":30,"y2":40}"#
+    )
+    let mixedSequence = try runnerCommandFixture(
+      """
+      {"command":"sequence","commandId":"seq-1","steps":[
+        {"kind":"tap","x":10,"y":20,"synthesized":true},
+        {"kind":"doubleTap","x":30,"y":40}
+      ]}
+      """
+    )
+
+    XCTAssertFalse(shouldSkipAppActivationPreflight(selectorTap))
+    XCTAssertFalse(shouldSkipAppActivationPreflight(standardDrag))
+    XCTAssertFalse(shouldSkipAppActivationPreflight(mixedSequence))
+  }
+
+  // Launches nothing, but still simulator-only: `shouldSkipAppActivationPreflight` is
+  // `#if os(iOS) …guards… #else return false #endif`, so on macOS this asserts a compile-time
+  // literal and no edit to the iOS body could make it red. Its five siblings above and below
+  // are gated for the same reason.
+  func testSkipAppActivationPreflightRequiresCachedForegroundTarget() throws {
+    currentApp = nil
+    currentBundleId = nil
+    let scroll = try runnerCommandFixture(
+      #"{"command":"scroll","commandId":"scroll-1","direction":"down","pixels":400}"#
+    )
+
+    XCTAssertFalse(shouldSkipAppActivationPreflight(scroll))
+  }
+
+  func testSkipAppActivationPreflightKeepsDragScrollAndSequenceOnForegroundGuard() throws {
+    app.launch()
+    currentApp = app
+    currentBundleId = nil
+    defer {
+      currentApp = nil
+      currentBundleId = nil
+      app.terminate()
+    }
+    let drag = try runnerCommandFixture(
+      #"{"command":"drag","commandId":"drag-1","x":10,"y":20,"x2":30,"y2":40}"#
+    )
+    let scroll = try runnerCommandFixture(
+      #"{"command":"scroll","commandId":"scroll-1","direction":"down","pixels":400}"#
+    )
+    let sequence = try runnerCommandFixture(
+      """
+      {"command":"sequence","commandId":"seq-1","steps":[
+        {"kind":"tap","x":10,"y":20,"synthesized":true},
+        {"kind":"longPress","x":10,"y":200,"durationMs":300}
+      ]}
+      """
+    )
+
+    XCTAssertFalse(shouldSkipAppActivationPreflight(drag))
+    XCTAssertFalse(shouldSkipAppActivationPreflight(scroll))
+    XCTAssertFalse(shouldSkipAppActivationPreflight(sequence))
+  }
+
+  func testSkipAppActivationPreflightIncludesAlertCommands() throws {
+    let alert = try runnerCommandFixture(
+      #"{"command":"alert","commandId":"alert-1","action":"get"}"#
+    )
+
+    XCTAssertTrue(shouldSkipAppActivationPreflight(alert))
+  }
+#endif
+
+  func testDispatchReturnsBusyBeforeQueueingMainThreadWork() throws {
+    let command = try runnerCommandFixture(#"{"command":"snapshot","commandId":"snapshot-busy"}"#)
+    abandonedMainThreadWorkCount = 1
+    abandonedMainThreadWorkSince = Date(timeIntervalSinceNow: -2)
+    defer {
+      abandonedMainThreadWorkCount = 0
+      abandonedMainThreadWorkSince = nil
+    }
+
+    let response = try execute(command: command)
+
+    XCTAssertFalse(response.ok)
+    XCTAssertEqual(response.error?.code, "RUNNER_BUSY")
+    XCTAssertTrue(response.error?.message.contains("previous command") == true)
+  }
+
+  func testDispatchReturnsWedgedBeforeQueueingMainThreadWork() throws {
+    let command = try runnerCommandFixture(#"{"command":"snapshot","commandId":"snapshot-wedged"}"#)
+    abandonedMainThreadWorkCount = 1
+    abandonedMainThreadWorkSince = Date(timeIntervalSinceNow: -(mainThreadWedgeThreshold + 1))
+    defer {
+      abandonedMainThreadWorkCount = 0
+      abandonedMainThreadWorkSince = nil
+    }
+
+    let response = try execute(command: command)
+
+    XCTAssertFalse(response.ok)
+    XCTAssertEqual(response.error?.code, "RUNNER_WEDGED")
+    XCTAssertTrue(response.error?.hint?.contains("runner session will be restarted") == true)
+  }
+
+  func testPostSnapshotDelayMarkDoesNotQueueBehindAbandonedMainThreadWork() {
+    abandonedMainThreadWorkCount = 1
+    defer {
+      abandonedMainThreadWorkCount = 0
+      needsPostSnapshotInteractionDelay = false
+    }
+
+    let finished = expectation(description: "off-main caller finished")
+    DispatchQueue(label: "agent-device.runner.tests.post-snapshot-delay").async {
+      self.setNeedsPostSnapshotInteractionDelay()
+      finished.fulfill()
+    }
+
+    wait(for: [finished], timeout: 1)
+    mainThreadWorkLock.lock()
+    let abandonedWorkCount = abandonedMainThreadWorkCount
+    mainThreadWorkLock.unlock()
+    XCTAssertEqual(abandonedWorkCount, 1, "the skipped mark must not add an abandoned unit")
+    XCTAssertFalse(needsPostSnapshotInteractionDelay)
+  }
+
+  func testSnapshotFailureInvalidationQueuesBehindAbandonedMainThreadWorkWithoutWaiting() {
+    currentBundleId = "com.example.stale-target"
+    defer { currentBundleId = nil }
+
+    final class ResultBox {
+      var elapsed: TimeInterval?
+      var bundleStillCachedWhileBlocked: Bool?
+      var abandonedWhileBlocked: Int?
+    }
+    let box = ResultBox()
+    let mainBlocked = DispatchSemaphore(value: 0)
+    let releaseMain = DispatchSemaphore(value: 0)
+    let finished = expectation(description: "invalidation returned while main was blocked")
+
+    DispatchQueue(label: "agent-device.runner.tests.snapshot-invalidation").async {
+      _ = try? self.runMainThreadWork(
+        "command_execution",
+        timeout: 0,
+        timeoutError: self.mainThreadExecutionTimeoutError
+      ) {
+        mainBlocked.signal()
+        _ = releaseMain.wait(timeout: .now() + 5)
+        return true
+      }
+      _ = mainBlocked.wait(timeout: .now() + 2)
+      let startedAt = Date()
+      self.invalidateCachedTargetAfterSnapshotFailure()
+      box.elapsed = Date().timeIntervalSince(startedAt)
+      box.bundleStillCachedWhileBlocked = self.currentBundleId != nil
+      self.mainThreadWorkLock.lock()
+      box.abandonedWhileBlocked = self.abandonedMainThreadWorkCount
+      self.mainThreadWorkLock.unlock()
+      releaseMain.signal()
+      finished.fulfill()
+    }
+
+    wait(for: [finished], timeout: 8)
+    let drainDeadline = Date().addingTimeInterval(2)
+    while hasAbandonedMainThreadWork() || currentBundleId != nil, Date() < drainDeadline {
+      sleepFor(0.005)
+    }
+
+    XCTAssertLessThan(
+      box.elapsed ?? .infinity,
+      0.5,
+      "the failed capture must not wait behind abandoned main-thread work"
+    )
+    XCTAssertEqual(
+      box.bundleStillCachedWhileBlocked,
+      true,
+      "the drop must queue behind the blocked main thread, not run early"
+    )
+    XCTAssertEqual(box.abandonedWhileBlocked, 1, "the deferred drop must not add an abandoned unit")
+    XCTAssertFalse(hasAbandonedMainThreadWork())
+    XCTAssertNil(currentBundleId, "the drop must run once the main thread frees")
+  }
+
+  /// Routes `command` through the transport's inline and queued paths. The calling test's main
+  /// thread serves the command's main-thread work while it waits.
+  func execute(command: Command) throws -> Response {
+    dispatchPrecondition(condition: .onQueue(.main))
+    if let response = inlineResponse(for: command) {
+      return response
+    }
+    final class ResultBox {
+      var result: Result<Response, Error>?
+    }
+    let box = ResultBox()
+    let executed = XCTestExpectation(description: "\(command.command.rawValue) executed off main")
+    enqueueAccepted(command: command) { result in
+      box.result = result
+      executed.fulfill()
+    }
+    guard XCTWaiter.wait(for: [executed], timeout: mainThreadExecutionTimeout + 5) == .completed,
+      let result = box.result
+    else {
+      throw NSError(
+        domain: RunnerErrorDomain.general,
+        code: RunnerErrorCode.commandReturnedNoResponse,
+        userInfo: [NSLocalizedDescriptionKey: "command did not finish on the command queue"]
+      )
+    }
+    return try result.get()
+  }
+
+  func runnerCommandFixture(_ json: String) throws -> Command {
+    try JSONDecoder().decode(Command.self, from: Data(json.utf8))
+  }
+}
+#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+CommandJournalTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+CommandJournalTests.swift
new file mode 100644
index 0000000000..44555b0b76
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+CommandJournalTests.swift
@@ -0,0 +1,340 @@
+import Foundation
+import XCTest
+import AgentDeviceSnapshotPresentation
+
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS
+extension RunnerTests {
+  func testUptimeBypassesCommandJournal() throws {
+    let command = runnerJournalCommand("uptime", id: "uptime-probe")
+
+    let response = try execute(command: command)
+    let status = commandJournal.status(normalizedCommandId: "uptime-probe")
+
+    XCTAssertEqual(response.ok, true)
+    XCTAssertNotNil(response.data?.currentUptimeMs)
+    XCTAssertEqual(status.lifecycleState, RunnerCommandLifecycleState.notAccepted.rawValue)
+  }
+
+  func testStampingCurrentUptimePreservesPayload() {
+    let stamped = Response(ok: true, data: DataPayload(message: "recording started"))
+      .stampingCurrentUptimeMs(123.5)
+
+    XCTAssertEqual(stamped.ok, true)
+    XCTAssertEqual(stamped.data?.message, "recording started")
+    XCTAssertEqual(stamped.data?.currentUptimeMs, 123.5)
+  }
+
+  func testStampingCurrentUptimeCreatesPayloadWhenNil() {
+    let stamped = Response(ok: true).stampingCurrentUptimeMs(456.0)
+
+    XCTAssertEqual(stamped.ok, true)
+    XCTAssertEqual(stamped.data?.currentUptimeMs, 456.0)
+  }
+
+  func testStampingCurrentUptimeSkipsErrorResponses() {
+    let response = Response(ok: false, error: ErrorPayload(message: "boom"))
+    let stamped = response.stampingCurrentUptimeMs(789.0)
+
+    XCTAssertEqual(stamped.ok, false)
+    XCTAssertNil(stamped.data)
+    XCTAssertEqual(stamped.error?.message, "boom")
+  }
+
+  func testStampingCurrentMainThreadBusyPreservesPayload() {
+    let stamped = Response(ok: true, data: DataPayload(nodes: [], truncated: false))
+      .stampingCurrentMainThreadBusy(true)
+
+    XCTAssertEqual(stamped.ok, true)
+    XCTAssertEqual(stamped.data?.runnerMainThreadBusy, true)
+  }
+
+  func testStampingCurrentMainThreadBusySkipsErrorResponses() {
+    let response = Response(ok: false, error: ErrorPayload(code: "RUNNER_BUSY", message: "busy"))
+    let stamped = response.stampingCurrentMainThreadBusy(true)
+
+    XCTAssertEqual(stamped.ok, false)
+    XCTAssertNil(stamped.data)
+    XCTAssertEqual(stamped.error?.code, "RUNNER_BUSY")
+  }
+
+  func testMainThreadBusyStateReportsOccupancy() {
+    XCTAssertFalse(MainThreadBusyState.idle.reportsMainThreadBusy)
+    XCTAssertTrue(MainThreadBusyState.busy(abandonedForSeconds: 5).reportsMainThreadBusy)
+    XCTAssertTrue(MainThreadBusyState.wedged(abandonedForSeconds: 200).reportsMainThreadBusy)
+    XCTAssertEqual(
+      Response(ok: true).stampingCurrentMainThreadBusy(false).data?.runnerMainThreadBusy, false)
+  }
+
+  func testCommandFailedResponseTagsMainThreadTimeoutWithTypedCode() {
+    let timeout = NSError(
+      domain: RunnerErrorDomain.general,
+      code: RunnerErrorCode.mainThreadExecutionTimedOut,
+      userInfo: [NSLocalizedDescriptionKey: "main thread execution timed out"]
+    )
+
+    let response = commandFailedResponse(from: timeout)
+
+    XCTAssertEqual(response.ok, false)
+    XCTAssertEqual(response.error?.code, RunnerWireErrorCode.mainThreadTimeout)
+  }
+
+  func testCommandFailedResponseKeepsGenericCodeForOtherErrors() {
+    let other = NSError(domain: "SomeOtherDomain", code: 99, userInfo: nil)
+
+    let response = commandFailedResponse(from: other)
+
+    XCTAssertEqual(response.error?.code, "COMMAND_FAILED")
+  }
+
+  func testJournalStoredResponseStaysUnstamped() throws {
+    let journal = RunnerCommandJournal()
+    let recordStart = runnerJournalCommand("recordStart", id: "record-start-anchor")
+
+    journal.accept(command: recordStart)
+    journal.finish(
+      command: recordStart,
+      response: Response(ok: true, data: DataPayload(message: "recording started"))
+    )
+
+    let status = journal.status(normalizedCommandId: "record-start-anchor")
+    let responseJson = try XCTUnwrap(status.lifecycleResponseJson)
+    XCTAssertFalse(responseJson.contains("currentUptimeMs"))
+  }
+
+  func testCommandJournalRetentionPolicy() throws {
+    let journal = RunnerCommandJournal()
+
+    let uptime = runnerJournalCommand("uptime", id: "small-scalar")
+    journal.accept(command: uptime)
+    journal.finish(
+      command: uptime,
+      response: Response(ok: true, data: DataPayload(currentUptimeMs: 12.5))
+    )
+
+    let scalarStatus = journal.status(normalizedCommandId: "small-scalar")
+    XCTAssertEqual(scalarStatus.lifecycleState, RunnerCommandLifecycleState.completed.rawValue)
+    XCTAssertEqual(scalarStatus.lifecycleResponseOk, true)
+    XCTAssertNotNil(scalarStatus.lifecycleResponseJson)
+    let scalarResponse = try decodeRunnerJournalResponse(scalarStatus.lifecycleResponseJson)
+    XCTAssertEqual(scalarResponse.data?.currentUptimeMs, 12.5)
+
+    let querySelector = runnerJournalCommand("querySelector", id: "small-object")
+    journal.accept(command: querySelector)
+    journal.finish(
+      command: querySelector,
+      response: Response(ok: true, data: DataPayload(found: true, nodes: [runnerJournalNode()]))
+    )
+
+    let objectStatus = journal.status(normalizedCommandId: "small-object")
+    XCTAssertNotNil(objectStatus.lifecycleResponseJson)
+    let objectResponse = try decodeRunnerJournalResponse(objectStatus.lifecycleResponseJson)
+    XCTAssertEqual(objectResponse.data?.found, true)
+    XCTAssertEqual(objectResponse.data?.nodes?.count, 1)
+
+    let snapshot = runnerJournalCommand("snapshot", id: "snapshot-tree")
+    journal.accept(command: snapshot)
+    journal.finish(
+      command: snapshot,
+      response: Response(ok: true, data: DataPayload(nodes: [runnerJournalNode()], truncated: false))
+    )
+
+    let snapshotStatus = journal.status(normalizedCommandId: "snapshot-tree")
+    XCTAssertEqual(snapshotStatus.lifecycleState, RunnerCommandLifecycleState.completed.rawValue)
+    XCTAssertEqual(snapshotStatus.lifecycleResponseOk, true)
+    XCTAssertNil(snapshotStatus.lifecycleResponseJson)
+
+    let screenshot = runnerJournalCommand("screenshot", id: "screenshot-artifact")
+    journal.accept(command: screenshot)
+    journal.finish(
+      command: screenshot,
+      response: Response(ok: true, data: DataPayload(message: "tmp/screenshot-1.png"))
+    )
+
+    let screenshotStatus = journal.status(normalizedCommandId: "screenshot-artifact")
+    XCTAssertEqual(screenshotStatus.lifecycleState, RunnerCommandLifecycleState.completed.rawValue)
+    XCTAssertEqual(screenshotStatus.lifecycleResponseOk, true)
+    XCTAssertNil(screenshotStatus.lifecycleResponseJson)
+
+    let scroll = runnerJournalCommand("scroll", id: "scroll-drag")
+    journal.accept(command: scroll)
+    journal.finish(
+      command: scroll,
+      response: Response(
+        ok: true,
+        data: DataPayload(
+          message: "scrolled",
+          gestureStartUptimeMs: 1,
+          gestureEndUptimeMs: 2,
+          x: 155,
+          y: 420,
+          x2: 155,
+          y2: 301,
+          referenceWidth: 300,
+          referenceHeight: 600
+        )
+      )
+    )
+
+    let scrollStatus = journal.status(normalizedCommandId: "scroll-drag")
+    XCTAssertEqual(scrollStatus.lifecycleState, RunnerCommandLifecycleState.completed.rawValue)
+    XCTAssertEqual(scrollStatus.lifecycleResponseOk, true)
+    XCTAssertNotNil(scrollStatus.lifecycleResponseJson)
+    let scrollResponse = try decodeRunnerJournalResponse(scrollStatus.lifecycleResponseJson)
+    XCTAssertEqual(scrollResponse.data?.x, 155)
+    XCTAssertEqual(scrollResponse.data?.y, 420)
+    XCTAssertEqual(scrollResponse.data?.x2, 155)
+    XCTAssertEqual(scrollResponse.data?.y2, 301)
+    XCTAssertEqual(scrollResponse.data?.referenceWidth, 300)
+    XCTAssertEqual(scrollResponse.data?.referenceHeight, 600)
+
+    let largeRead = runnerJournalCommand("readText", id: "large-read")
+    journal.accept(command: largeRead)
+    journal.finish(
+      command: largeRead,
+      response: Response(ok: true, data: DataPayload(text: String(repeating: "x", count: 17 * 1024)))
+    )
+
+    let largeReadStatus = journal.status(normalizedCommandId: "large-read")
+    XCTAssertEqual(largeReadStatus.lifecycleState, RunnerCommandLifecycleState.completed.rawValue)
+    XCTAssertEqual(largeReadStatus.lifecycleResponseOk, true)
+    XCTAssertNil(largeReadStatus.lifecycleResponseJson)
+  }
+
+  func testCommandJournalKeepsErrorMetadataWhenResponseJsonIsDropped() {
+    let journal = RunnerCommandJournal()
+    let snapshot = runnerJournalCommand("snapshot", id: "snapshot-error")
+    let hint = "Try a smaller read such as snapshot -s <visible label or id> -d 8."
+
+    journal.accept(command: snapshot)
+    journal.finish(
+      command: snapshot,
+      response: Response(
+        ok: false,
+        error: ErrorPayload(
+          code: "IOS_AX_SNAPSHOT_FAILED",
+          message: "iOS XCTest snapshot failed while serializing the accessibility tree.",
+          hint: hint
+        )
+      )
+    )
+
+    let status = journal.status(normalizedCommandId: "snapshot-error")
+    XCTAssertEqual(status.lifecycleState, RunnerCommandLifecycleState.failed.rawValue)
+    XCTAssertEqual(status.lifecycleResponseOk, false)
+    XCTAssertNil(status.lifecycleResponseJson)
+    XCTAssertEqual(status.lifecycleErrorCode, "IOS_AX_SNAPSHOT_FAILED")
+    XCTAssertEqual(
+      status.lifecycleErrorMessage,
+      "iOS XCTest snapshot failed while serializing the accessibility tree."
+    )
+    XCTAssertEqual(status.lifecycleErrorHint, hint)
+  }
+
+  func testCommandJournalRetainsCompletedSequenceResults() throws {
+    let journal = RunnerCommandJournal()
+    let sequence = runnerJournalCommand("sequence", id: "sequence-completed")
+    let results = (0..<20).map { _ in
+      SequenceStepResult(
+        ok: true,
+        kind: "tap",
+        errorCode: nil,
+        errorMessage: nil,
+        gestureStartUptimeMs: 100,
+        gestureEndUptimeMs: 120
+      )
+    }
+
+    journal.accept(command: sequence)
+    journal.finish(
+      command: sequence,
+      response: Response(
+        ok: true,
+        data: DataPayload(
+          message: "sequence",
+          completedSteps: 20,
+          failedStepIndex: nil,
+          sequenceResults: results
+        )
+      )
+    )
+
+    let status = journal.status(normalizedCommandId: "sequence-completed")
+    XCTAssertEqual(status.lifecycleState, RunnerCommandLifecycleState.completed.rawValue)
+    XCTAssertEqual(status.lifecycleResponseOk, true)
+    let json = try XCTUnwrap(status.lifecycleResponseJson)
+    // Worst-case 20-step response must stay under the 16KB journal retention cap.
+    XCTAssertLessThan(json.utf8.count, 16 * 1024)
+    let decoded = try decodeRunnerJournalResponse(status.lifecycleResponseJson)
+    XCTAssertEqual(decoded.data?.completedSteps, 20)
+    XCTAssertEqual(decoded.data?.sequenceResults?.count, 20)
+  }
+
+  func testCommandJournalRetainsFailedSequenceResults() throws {
+    let journal = RunnerCommandJournal()
+    let sequence = runnerJournalCommand("sequence", id: "sequence-failed")
+    let longError = String(repeating: "z", count: 200)
+    let results: [SequenceStepResult] = [
+      SequenceStepResult(ok: true, kind: "tap", errorCode: nil, errorMessage: nil,
+                         gestureStartUptimeMs: 100, gestureEndUptimeMs: 120),
+      SequenceStepResult(ok: true, kind: "tap", errorCode: nil, errorMessage: nil,
+                         gestureStartUptimeMs: 130, gestureEndUptimeMs: 150),
+      SequenceStepResult(ok: false, kind: "longPress", errorCode: "UNSUPPORTED_OPERATION",
+                         errorMessage: longError, gestureStartUptimeMs: 160, gestureEndUptimeMs: 180),
+    ]
+
+    journal.accept(command: sequence)
+    journal.finish(
+      command: sequence,
+      response: Response(
+        ok: true,
+        data: DataPayload(
+          message: "sequence",
+          completedSteps: 2,
+          failedStepIndex: 2,
+          sequenceResults: results
+        )
+      )
+    )
+
+    let status = journal.status(normalizedCommandId: "sequence-failed")
+    XCTAssertEqual(status.lifecycleState, RunnerCommandLifecycleState.completed.rawValue)
+    let decoded = try decodeRunnerJournalResponse(status.lifecycleResponseJson)
+    XCTAssertEqual(decoded.data?.completedSteps, 2)
+    XCTAssertEqual(decoded.data?.failedStepIndex, 2)
+    XCTAssertEqual(decoded.data?.sequenceResults?.count, 3)
+    XCTAssertEqual(decoded.data?.sequenceResults?[2].ok, false)
+    XCTAssertEqual(decoded.data?.sequenceResults?[2].errorCode, "UNSUPPORTED_OPERATION")
+  }
+
+  private func runnerJournalCommand(_ command: String, id: String) -> Command {
+    let json = #"{"command":"\#(command)","commandId":"\#(id)"}"#
+    return try! JSONDecoder().decode(Command.self, from: Data(json.utf8))
+  }
+
+  private func runnerJournalNode() -> PresentedNode {
+    SnapshotPresentation.singleElementRead(
+      RawAXNode(
+        index: 0,
+        type: "button",
+        label: "Continue",
+        identifier: "continue",
+        value: nil,
+        rect: SnapshotRect(x: 10, y: 20, width: 100, height: 44),
+        enabled: true,
+        focused: nil,
+        selected: nil,
+        hittable: true,
+        depth: 0,
+        parentIndex: nil,
+        hiddenContentAbove: nil,
+        hiddenContentBelow: nil
+      )
+    )
+  }
+
+  private func decodeRunnerJournalResponse(_ responseJson: String?) throws -> Response {
+    let responseJson = try XCTUnwrap(responseJson)
+    return try JSONDecoder().decode(Response.self, from: Data(responseJson.utf8))
+  }
+}
+#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+InteractionTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+InteractionTests.swift
new file mode 100644
index 0000000000..659dbd9c8b
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+InteractionTests.swift
@@ -0,0 +1,27 @@
+import XCTest
+import AgentDeviceSnapshotPresentation
+
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS
+extension RunnerTests {
+  func testDesktopScrollWheelDeltasMapDirections() {
+    XCTAssertEqual(desktopScrollWheelDeltas(direction: .up, pixels: 120).vertical, 120)
+    XCTAssertEqual(desktopScrollWheelDeltas(direction: .down, pixels: 120).vertical, -120)
+    XCTAssertEqual(desktopScrollWheelDeltas(direction: .left, pixels: 120).horizontal, 120)
+    XCTAssertEqual(desktopScrollWheelDeltas(direction: .right, pixels: 120).horizontal, -120)
+  }
+
+  func testDesktopScrollWheelDeltaEventsHonorDurationAndPreservePixels() {
+    let events = desktopScrollWheelDeltaEvents(direction: .down, pixels: 200, durationMs: 50)
+    XCTAssertEqual(events.count, 4)
+    XCTAssertEqual(events.map(\.vertical).reduce(0, +), -200)
+    XCTAssertEqual(events.map(\.horizontal).reduce(0, +), 0)
+    XCTAssertEqual(desktopScrollEventIntervalSeconds(durationMs: 50, eventCount: events.count), 0.05 / 3.0)
+  }
+
+  func testDesktopScrollWheelDeltaEventsKeepInstantScrollSingleEvent() {
+    let events = desktopScrollWheelDeltaEvents(direction: .down, pixels: 200, durationMs: 0)
+    XCTAssertEqual(events.count, 1)
+    XCTAssertEqual(events.first?.vertical, -200)
+  }
+}
+#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+KeyboardTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+KeyboardTests.swift
new file mode 100644
index 0000000000..8264903617
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+KeyboardTests.swift
@@ -0,0 +1,144 @@
+import XCTest
+import AgentDeviceSnapshotPresentation
+
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS
+extension RunnerTests {
+  func testKeyboardBandFactReadFailureIsStatedAsUnmeasurableNotAbsence() {
+    // Absence would let a consumer claim the screen is clear of a keyboard on the strength of a read
+    // that never answered.
+    let fact = runnerKeyboardBandFact(
+      readSucceeded: false,
+      exists: false,
+      frame: CGRect(x: 0, y: 198, width: 402, height: 204)
+    )
+    XCTAssertEqual(fact, .unmeasurable(RunnerKeyboardBandReason.queryFailed))
+    XCTAssertEqual(fact.payload.kind, "unmeasurable")
+    XCTAssertEqual(fact.payload.reason, RunnerKeyboardBandReason.queryFailed)
+    XCTAssertNil(fact.payload.frame)
+  }
+
+  func testKeyboardBandFactPublishesAbsenceWhenTheQueryFindsNoKeyboard() {
+    let fact = runnerKeyboardBandFact(readSucceeded: true, exists: false, frame: .zero)
+    XCTAssertEqual(fact, .absent)
+    XCTAssertEqual(fact.payload.kind, "absent")
+    XCTAssertNil(fact.payload.frame)
+    XCTAssertNil(fact.payload.reason)
+  }
+
+  func testKeyboardBandFactPublishesTheMeasuredBandInAppOrientationSpace() {
+    // The landscape band measured on iPhone 17 Pro (iOS 26.2) after #2653: full width across the
+    // bottom of a 402 pt-tall app, which is what the tree reported as a strip down the left edge.
+    let frame = CGRect(x: 0, y: 198, width: 874, height: 204)
+    let fact = runnerKeyboardBandFact(readSucceeded: true, exists: true, frame: frame)
+    XCTAssertEqual(fact, .visible(frame))
+    let payload = fact.payload
+    XCTAssertEqual(payload.kind, "visible")
+    XCTAssertEqual(payload.frame, SnapshotRect(x: 0, y: 198, width: 874, height: 204))
+    XCTAssertNil(payload.reason)
+  }
+
+  func testKeyboardBandFactRefusesUnusableGeometryInsteadOfClaimingAbsence() {
+    let nan = CGFloat(Double.nan)
+    let infinite = CGFloat.infinity
+    let unusable: [CGRect] = [
+      .zero,
+      CGRect(x: 0, y: 198, width: 0, height: 204),
+      CGRect(x: 0, y: 198, width: 874, height: -1),
+      CGRect(x: 0, y: 198, width: -874, height: 204),
+      CGRect(x: 0, y: nan, width: 874, height: 204),
+      CGRect(x: 0, y: 198, width: nan, height: 204),
+      CGRect(x: infinite, y: 198, width: 874, height: 204)
+    ]
+    for frame in unusable {
+      let fact = runnerKeyboardBandFact(readSucceeded: true, exists: true, frame: frame)
+      XCTAssertEqual(
+        fact,
+        .unmeasurable(RunnerKeyboardBandReason.unusableFrame),
+        "expected \(frame) to be refused as a band"
+      )
+    }
+  }
+
+  func testKeyboardBandFactPayloadRoundTripsThroughTheWireShape() throws {
+    let cases: [RunnerKeyboardBandFact] = [
+      .visible(CGRect(x: 0, y: 583, width: 402, height: 291)),
+      .absent,
+      .unmeasurable(RunnerKeyboardBandReason.queryTimeout)
+    ]
+    for fact in cases {
+      let data = try JSONEncoder().encode(fact.payload)
+      // `encodeIfPresent` for the two optional fields: a fact carries its own evidence and nothing
+      // else, so the daemon never has to distinguish a null from an absent key.
+      let object = try XCTUnwrap(JSONSerialization.jsonObject(with: data) as? [String: Any])
+      switch fact {
+      case .visible:
+        XCTAssertNil(object["reason"])
+        XCTAssertNotNil(object["frame"])
+      case .absent:
+        XCTAssertNil(object["frame"])
+        XCTAssertNil(object["reason"])
+      case .unmeasurable:
+        XCTAssertNil(object["frame"])
+        XCTAssertNotNil(object["reason"])
+      }
+      XCTAssertEqual(try JSONDecoder().decode(KeyboardBandFactPayload.self, from: data), fact.payload)
+    }
+  }
+
+  func testRunnerScreenshotStabilitySettledNeedsEnoughSamples() {
+    XCTAssertFalse(runnerScreenshotStabilitySettled([], requiredConsecutiveMatches: 3))
+    XCTAssertFalse(runnerScreenshotStabilitySettled([Data([1])], requiredConsecutiveMatches: 3))
+    let frame = Data([1, 2, 3])
+    XCTAssertFalse(
+      runnerScreenshotStabilitySettled([frame, frame], requiredConsecutiveMatches: 3)
+    )
+  }
+
+  func testRunnerScreenshotStabilitySettledTrueWhenWindowMatches() {
+    let frame = Data([1, 2, 3])
+    XCTAssertTrue(
+      runnerScreenshotStabilitySettled([Data([9]), frame, frame, frame], requiredConsecutiveMatches: 3)
+    )
+  }
+
+  func testRunnerScreenshotStabilitySettledFalseOnMidWindowMismatch() {
+    // A momentary pause (two matching samples) followed by resumed movement
+    // must not read as settled: the 3-sample window still spans the mismatch.
+    let frame = Data([1, 2, 3])
+    let moved = Data([4, 5, 6])
+    XCTAssertFalse(
+      runnerScreenshotStabilitySettled([frame, frame, moved], requiredConsecutiveMatches: 3)
+    )
+  }
+
+  func testRunnerScreenshotStabilitySettledFalseOnFailedCapture() {
+    // A nil sample (failed screenshot) never counts as a match, even against
+    // other nils — an unverifiable run must not look "stable".
+    XCTAssertFalse(runnerScreenshotStabilitySettled([nil, nil, nil], requiredConsecutiveMatches: 3))
+    let frame = Data([1, 2, 3])
+    XCTAssertFalse(
+      runnerScreenshotStabilitySettled([frame, frame, nil], requiredConsecutiveMatches: 3)
+    )
+  }
+
+  func testRunnerScreenshotStabilitySettledOnlyLooksAtTheTrailingWindow() {
+    // An older mismatch before the trailing window must not block settlement
+    // once the required run of most-recent samples agrees.
+    let frame = Data([9])
+    XCTAssertTrue(
+      runnerScreenshotStabilitySettled(
+        [Data([1]), Data([2]), frame, frame, frame],
+        requiredConsecutiveMatches: 3
+      )
+    )
+  }
+
+  func testRunnerScreenshotStabilitySettledRejectsDegenerateRequirement() {
+    // Fewer than 2 required matches would make any single sample "settled" —
+    // guard against a misconfigured caller rather than silently no-op the wait.
+    XCTAssertFalse(
+      runnerScreenshotStabilitySettled([Data([1])], requiredConsecutiveMatches: 1)
+    )
+  }
+}
+#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+LifecycleTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+LifecycleTests.swift
index cba532f03b..559fa9021b 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+LifecycleTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+LifecycleTests.swift
@@ -104,3 +104,33 @@ extension RunnerTests {
   }
 }
 #endif
+
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS
+extension RunnerTests {
+  func testResettingTargetBoundStateForgetsTheLastWrittenMarkers() {
+    defer { invalidateCachedTarget(reason: "unit_test_cleanup") }
+    lastLoggedFastAppGuardLine = "AGENT_DEVICE_RUNNER_FAST_APP_GUARD bundle=app state=4"
+    lastLoggedGesturePolicyLines[.scroll] = "AGENT_DEVICE_RUNNER_SYNTHESIZED_GESTURE_POLICY kind=scroll"
+    resetTargetBoundState()
+    XCTAssertNil(lastLoggedFastAppGuardLine, "a rebind must state the guard once more")
+    XCTAssertTrue(lastLoggedGesturePolicyLines.isEmpty, "a rebind must state the policy once more")
+  }
+
+  func testFastAppGuardMarkerWritesOnceUntilTheFactChanges() {
+    var written: [String] = []
+    runnerMarkerWriter = { written.append($0) }
+    defer {
+      runnerMarkerWriter = { NSLog("%@", $0) }
+      invalidateCachedTarget(reason: "unit_test_cleanup")
+    }
+    writeFastAppGuardMarker(bundleId: "com.example.app", state: .runningForeground)
+    writeFastAppGuardMarker(bundleId: "com.example.app", state: .runningForeground)
+    XCTAssertEqual(written.count, 1, "a repeated fact writes no second line")
+    writeFastAppGuardMarker(bundleId: "com.example.other", state: .runningForeground)
+    XCTAssertEqual(written.count, 2, "a changed fact writes a new line")
+    resetTargetBoundState()
+    writeFastAppGuardMarker(bundleId: "com.example.other", state: .runningForeground)
+    XCTAssertEqual(written.count, 3, "a rebind states the same fact once more")
+  }
+}
+#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+MainThreadWorkTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+MainThreadWorkTests.swift
new file mode 100644
index 0000000000..f98e37e7a8
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+MainThreadWorkTests.swift
@@ -0,0 +1,93 @@
+import XCTest
+
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS
+extension RunnerTests {
+  func testRunMainThreadWorkExecutesOffMainCallerOnMainThread() {
+    final class ResultBox {
+      var observedMainThread: Bool?
+      var error: Error?
+    }
+    let box = ResultBox()
+    let finished = expectation(description: "off-main caller finished")
+
+    DispatchQueue(label: "agent-device.runner.tests.off-main").async {
+      do {
+        box.observedMainThread = try self.runMainThreadWork(
+          "command_execution",
+          timeout: 1,
+          timeoutError: self.mainThreadExecutionTimeoutError
+        ) {
+          Thread.isMainThread
+        }
+      } catch {
+        box.error = error
+      }
+      finished.fulfill()
+    }
+
+    wait(for: [finished], timeout: 2)
+    XCTAssertNil(box.error)
+    XCTAssertEqual(box.observedMainThread, true)
+  }
+
+  func testRunMainThreadWorkTimeoutMarksAbandonedUntilDrained() {
+    final class ResultBox {
+      var error: Error?
+      var abandonedCount: Int?
+      var abandonedSinceSet: Bool?
+      var busyWhileAbandoned = false
+    }
+    let box = ResultBox()
+    let releaseWork = DispatchSemaphore(value: 0)
+    let observedAbandoned = DispatchSemaphore(value: 0)
+    let timedOut = expectation(description: "off-main caller timed out")
+
+    DispatchQueue(label: "agent-device.runner.tests.timeout").async {
+      do {
+        _ = try self.runMainThreadWork(
+          "command_execution",
+          timeout: 0,
+          timeoutError: self.mainThreadExecutionTimeoutError
+        ) {
+          _ = releaseWork.wait(timeout: .now() + 2)
+          return true
+        }
+      } catch {
+        box.error = error
+      }
+      self.mainThreadWorkLock.lock()
+      box.abandonedCount = self.abandonedMainThreadWorkCount
+      box.abandonedSinceSet = self.abandonedMainThreadWorkSince != nil
+      self.mainThreadWorkLock.unlock()
+      if case .busy = self.currentMainThreadBusyState() {
+        box.busyWhileAbandoned = true
+      }
+      observedAbandoned.signal()
+      timedOut.fulfill()
+    }
+    DispatchQueue(label: "agent-device.runner.tests.release-timeout").async {
+      _ = observedAbandoned.wait(timeout: .now() + 2)
+      releaseWork.signal()
+    }
+
+    wait(for: [timedOut], timeout: 3)
+    let drainDeadline = Date().addingTimeInterval(2)
+    while hasAbandonedMainThreadWork(), Date() < drainDeadline {
+      sleepFor(0.005)
+    }
+
+    XCTAssertEqual((box.error as NSError?)?.code, RunnerErrorCode.mainThreadExecutionTimedOut)
+    XCTAssertEqual(box.abandonedCount, 1)
+    XCTAssertEqual(box.abandonedSinceSet, true)
+    XCTAssertTrue(box.busyWhileAbandoned)
+    XCTAssertFalse(hasAbandonedMainThreadWork(), "drained work must release the main thread")
+    mainThreadWorkLock.lock()
+    let sinceCleared = abandonedMainThreadWorkSince == nil
+    mainThreadWorkLock.unlock()
+    XCTAssertTrue(sinceCleared)
+    guard case .idle = currentMainThreadBusyState() else {
+      return XCTFail("expected the runner idle once the abandoned work drained")
+    }
+  }
+}
+#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+NavigationTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+NavigationTests.swift
new file mode 100644
index 0000000000..e18e91241f
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+NavigationTests.swift
@@ -0,0 +1,169 @@
+import XCTest
+
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS
+extension RunnerTests {
+  func testTopLeadingNavigationFallbackPointTargetsHeaderControlBand() throws {
+    let point = try XCTUnwrap(
+      Self.topLeadingNavigationFallbackPoint(
+        in: CGRect(x: 0, y: 0, width: 430, height: 932)
+      )
+    )
+
+    XCTAssertEqual(point.x, 34.4, accuracy: 0.01)
+    XCTAssertEqual(point.y, 132, accuracy: 0.01)
+  }
+
+  func testTopLeadingNavigationFallbackPointRejectsInvalidFrame() {
+    XCTAssertNil(Self.topLeadingNavigationFallbackPoint(in: .infinite))
+    XCTAssertNil(Self.topLeadingNavigationFallbackPoint(in: .zero))
+  }
+
+  func testNavigationBackControlRankPrefersBackThenCloseThenCancel() {
+    XCTAssertEqual(Self.navigationBackControlRank(label: "Back", identifier: ""), 0)
+    XCTAssertEqual(Self.navigationBackControlRank(label: "Close", identifier: ""), 1)
+    XCTAssertEqual(Self.navigationBackControlRank(label: "Cancel search", identifier: ""), 2)
+    XCTAssertNil(Self.navigationBackControlRank(label: "Search for more feeds", identifier: ""))
+  }
+
+  func testNavigationBackPredicateUsesTheSharedKeywordTable() {
+    let predicate = Self.navigationBackPredicate()
+
+    XCTAssertTrue(predicate.evaluate(with: ["label": "Back", "identifier": ""]))
+    XCTAssertTrue(predicate.evaluate(with: ["label": "", "identifier": "close-button"]))
+    XCTAssertFalse(predicate.evaluate(with: ["label": "Search for more feeds", "identifier": ""]))
+  }
+
+  func testTopNavigationControlFrameAcceptsOnlyHeaderBand() {
+    let window = CGRect(x: 0, y: 0, width: 430, height: 932)
+
+    XCTAssertTrue(
+      Self.isTopNavigationControlFrame(
+        CGRect(x: 340, y: 84, width: 72, height: 44),
+        in: window
+      )
+    )
+    XCTAssertFalse(
+      Self.isTopNavigationControlFrame(
+        CGRect(x: 20, y: 760, width: 72, height: 44),
+        in: window
+      )
+    )
+    XCTAssertFalse(Self.isTopNavigationControlFrame(.infinite, in: window))
+  }
+
+  func testNavigationVisualVerificationSeparatesNoChangeFromNoSample() {
+    XCTAssertEqual(
+      Self.navigationVisualObservation(before: Data([1, 2, 3]), after: Data([1, 2, 4])),
+      .changed
+    )
+    XCTAssertEqual(
+      Self.navigationVisualObservation(before: Data([1, 2, 3]), after: Data([1, 2, 3])),
+      .unchanged
+    )
+    // A missing sample is neither a change nor a no-change; treating it as "unchanged" would let a
+    // capture that refused become the reason the `back` command claims no control exists (#2728).
+    XCTAssertEqual(Self.navigationVisualObservation(before: nil, after: Data([1])), .unobserved)
+    XCTAssertEqual(Self.navigationVisualObservation(before: Data([1]), after: nil), .unobserved)
+    XCTAssertEqual(Self.navigationVisualObservation(before: nil, after: nil), .unobserved)
+  }
+
+  func testNavigationFallbackReportsTheRefusalItHitNotADefaultCode() {
+    // The refusal from the most recent sample wins, so the code names what the fallback last looked at
+    // before giving up; an earlier refusal is reported only when the later sample carried none (#2728).
+    let after = NavigationVisualSample(
+      data: nil,
+      refusalCode: "APP_SCREEN_WINDOW_UNRESOLVED",
+      refusalHint: "after hint"
+    )
+    let before = NavigationVisualSample(
+      data: nil,
+      refusalCode: "APP_SCREEN_UNRESOLVED",
+      refusalHint: "before hint"
+    )
+    let laterWins = Self.navigationFallbackErrorPayload(after: after, before: before)
+    XCTAssertEqual(laterWins.code, "APP_SCREEN_WINDOW_UNRESOLVED")
+    XCTAssertEqual(laterWins.hint, "after hint")
+
+    let onlyBefore = Self.navigationFallbackErrorPayload(
+      after: NavigationVisualSample(data: nil),
+      before: before
+    )
+    XCTAssertEqual(onlyBefore.code, "APP_SCREEN_UNRESOLVED")
+    XCTAssertEqual(onlyBefore.hint, "before hint")
+
+    // Neither side named a reason (unreachable on iOS): a real capture code, never a bare failure.
+    let unnamed = Self.navigationFallbackErrorPayload(
+      after: NavigationVisualSample(data: nil),
+      before: NavigationVisualSample(data: nil)
+    )
+    XCTAssertEqual(unnamed.code, "APP_SCREEN_UNRESOLVED")
+    XCTAssertTrue(unnamed.message.contains("unknown outcome"))
+  }
+
+  func testVerifyNavigationFallbackOutcomeReportsUnresolvedWindowWithoutSystemSurface() {
+    // The in-app `back` fallback ran its tap but the app resolved no window. It must name that refusal
+    // as an unknown outcome AND must not have sampled the system surface: capturing SpringBoard's home
+    // screen twice reads as "unchanged" and launders a wrong-process frame into "no back control
+    // exists" (#2728). This drives the SAME `navigationFallbackSample` production calls, handing it a
+    // system surface that fails the test if consulted — so reverting the fallback to sample SpringBoard
+    // (or dropping the refusal code) turns this red, which an inline `.never` re-creation could not.
+    var askedSystemSurface = false
+    let sample = Self.navigationFallbackSample(
+      resolvingApp: { .failure(.unresolvedWindow) },
+      systemSurface: {
+        askedSystemSurface = true
+        return .failure(.unresolvedWindow)
+      },
+      encoding: { _ in Data([1, 2, 3]) }
+    )
+    XCTAssertFalse(askedSystemSurface, "the in-app fallback samples the app only, never SpringBoard")
+
+    XCTAssertNil(sample.data)
+    XCTAssertEqual(sample.refusalCode, "APP_SCREEN_WINDOW_UNRESOLVED")
+
+    let observation = Self.navigationVisualObservation(before: sample.data, after: sample.data)
+    XCTAssertEqual(observation, .unobserved)
+
+    switch Self.inAppBackOutcome(observation: observation, before: sample, after: sample) {
+    case .unverified(let payload):
+      XCTAssertEqual(payload.code, "APP_SCREEN_WINDOW_UNRESOLVED")
+    case .performed, .unavailable:
+      XCTFail("a refused capture must report an unknown outcome, not 'no back control'")
+    }
+  }
+
+  func testNavigationVisualSampleDistinguishesEncodedFrameFromRefusal() {
+    // The same capture entry point yields three different samples, and only the refusal ones may carry
+    // a code: an encoded frame is evidence, a resolved-but-unencodable image and a refusal are not
+    // (#2728). Reverting the mapping to a plain no-sample loses the reason a host keys on.
+    let captured = CapturedAppScreen(
+      image: RunnerImage(),
+      displayID: 3,
+      pixelWidth: 12,
+      pixelHeight: 24,
+      pixelsPerPoint: 3
+    )
+
+    let encoded = Self.navigationVisualSample(
+      from: .success(captured),
+      encoding: { _ in Data([7, 7]) }
+    )
+    XCTAssertEqual(encoded.data, Data([7, 7]))
+    XCTAssertNil(encoded.refusalCode)
+
+    let unencodable = Self.navigationVisualSample(
+      from: .success(captured),
+      encoding: { _ in nil }
+    )
+    XCTAssertNil(unencodable.data)
+    XCTAssertEqual(unencodable.refusalCode, "APP_SCREEN_CAPTURE_UNRENDERABLE")
+
+    let refused = Self.navigationVisualSample(
+      from: .failure(.unresolvedScreen),
+      encoding: { _ in Data([7, 7]) }
+    )
+    XCTAssertNil(refused.data)
+    XCTAssertEqual(refused.refusalCode, "APP_SCREEN_UNRESOLVED")
+  }
+}
+#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+PrivateAXPresentationTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+PrivateAXPresentationTests.swift
new file mode 100644
index 0000000000..23ee5db993
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+PrivateAXPresentationTests.swift
@@ -0,0 +1,211 @@
+import XCTest
+import AgentDeviceSnapshotPresentation
+
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS
+extension RunnerTests {
+  fileprivate static func privateAXFrame(
+    _ x: Double, _ y: Double, _ width: Double, _ height: Double
+  ) -> [String: Any] {
+    ["x": x, "y": y, "width": width, "height": height]
+  }
+
+  /// A scroll container whose second row is scrolled out of the viewport, plus an unlabeled
+  /// decoration: the shapes the regular projection folds away and the raw projection must keep.
+  fileprivate static var privateAXScrolledFixture: [String: Any] {
+    let frame = privateAXFrame
+    return ["type": Int(XCUIElement.ElementType.application.rawValue),
+      "label": "Element", "frame": frame(0, 0, 402, 874), "children": [[
+        "type": Int(XCUIElement.ElementType.scrollView.rawValue), "frame": frame(0, 96, 402, 700),
+        "actions": ["Scroll down"],
+        "children": [
+          ["type": Int(XCUIElement.ElementType.button.rawValue), "label": "Profile picture",
+            "frame": frame(16, 120, 44, 44),
+            "children": [["type": Int(XCUIElement.ElementType.image.rawValue),
+              "frame": frame(16, 120, 1, 1)]]],
+          ["type": Int(XCUIElement.ElementType.button.rawValue), "label": "Theme",
+            "frame": frame(16, 900, 360, 44)]]]]]
+  }
+
+  /// Acquire with the private-AX serializer, run the one normalization pass the production capture
+  /// plan runs (`captureWithBackend`), then present through the shared regular fold -- the production
+  /// route for this backend since the fold moved into presentation (#1797, #2661).
+  fileprivate func privateAXRegularPresentation(
+    rawRoot: [String: Any],
+    viewport: CGRect,
+    interactiveOnly: Bool = false
+  ) throws -> [PresentedNode] {
+    let hint = CaptureHint(
+      projection: .regular, depth: nil, regularPresentedDepth: nil,
+      interactiveOnly: interactiveOnly, customActions: false)
+    let nodes = privateAXNormalizedAcquisition(
+      rawRoot: rawRoot, hint: hint, viewport: viewport,
+      interfaceOrientation: RunnerInterfaceOrientation.portrait)
+    return try SnapshotPresentation.presentRegular(
+      SnapshotAcquisition(
+        hint: hint, nodes: nodes, truncated: false, effectiveDepth: nil, viewport: viewport,
+        interfaceOrientation: RunnerInterfaceOrientation.portrait),
+      options: PresentationOptions(
+        interactiveOnly: interactiveOnly, depth: nil, scope: nil, raw: false),
+      policy: .cursorProjected
+    ).nodes
+  }
+
+  /// Acquire, then normalize once -- the exact pair `captureWithBackend` runs for this backend.
+  fileprivate func privateAXNormalizedAcquisition(
+    rawRoot: [String: Any],
+    hint: CaptureHint,
+    viewport: CGRect,
+    interfaceOrientation: Int
+  ) -> [RawAXNode] {
+    SnapshotGeometrySpace.normalized(
+      nodes: privateAXAcquisition(rawRoot: rawRoot, hint: hint),
+      viewport: viewport,
+      interfaceOrientation: interfaceOrientation
+    )
+  }
+
+  /// The one normalization pass has to reach the node it publishes: this asserts the rotated rect of
+  /// a key under a turned surface host, and an untouched sibling under the app's own window, so a
+  /// pass that drops the space a subtree declared fails here.
+  func testPrivateAXAcquisitionPublishesATurnedSurfaceHostInAppOrientationSpace() {
+    let frame = Self.privateAXFrame
+    let appWindow: [String: Any] = [
+      "type": Int(XCUIElement.ElementType.window.rawValue),
+      "frame": frame(0, 0, 874, 402),
+      "children": [
+        ["type": Int(XCUIElement.ElementType.button.rawValue), "label": "Home",
+          "frame": frame(204, 323, 91, 55), "children": []]
+      ]
+    ]
+    let keyboardWindow: [String: Any] = [
+      "type": Int(XCUIElement.ElementType.window.rawValue),
+      "frame": frame(0, 0, 874, 402),
+      "children": [
+        ["type": Int(XCUIElement.ElementType.other.rawValue),
+          "frame": frame(0, 0, 402, 874),
+          "children": [
+            ["type": Int(XCUIElement.ElementType.key.rawValue), "label": "q",
+              "frame": frame(154, 77, 45, 72), "children": []]
+          ]]
+      ]
+    ]
+    let hint = CaptureHint(
+      projection: .raw, depth: nil, regularPresentedDepth: nil,
+      interactiveOnly: false, customActions: false)
+    let nodes = privateAXNormalizedAcquisition(
+      rawRoot: [
+        "type": Int(XCUIElement.ElementType.application.rawValue),
+        "label": "Element", "frame": frame(0, 0, 874, 402),
+        "children": [appWindow, keyboardWindow]
+      ],
+      hint: hint,
+      viewport: CGRect(x: 0, y: 0, width: 874, height: 402),
+      interfaceOrientation: RunnerInterfaceOrientation.landscapeRight
+    )
+
+    // Measured on iPhone 17 Pro (26.2): the key plane's left column arrives 154 pt along the device's
+    // long axis and comes back 203 pt down the app's short one.
+    XCTAssertEqual(
+      nodes.first { $0.label == "q" }?.rect,
+      SnapshotRect(x: 77, y: 203, width: 72, height: 45)
+    )
+    XCTAssertEqual(
+      nodes.first { $0.label == "Home" }?.rect,
+      SnapshotRect(x: 204, y: 323, width: 91, height: 55)
+    )
+  }
+
+  func testPrivateAXRegularPresentationProjectsToViewportAndKeepsScrollHint() throws {
+    let nodes = try privateAXRegularPresentation(
+      rawRoot: Self.privateAXScrolledFixture,
+      viewport: CGRect(x: 0, y: 0, width: 402, height: 874))
+    XCTAssertEqual(nodes.compactMap(\.label), ["Element", "Profile picture"])
+    let scrollView = nodes.first { $0.type == "ScrollView" }
+    XCTAssertEqual(scrollView?.hiddenContentBelow, true)
+    XCTAssertEqual(scrollView?.actions, ["Scroll down"])
+  }
+
+  /// #1797 D4: the raw projection is the acquired tree. The offscreen row and the sub-pixel
+  /// decoration the regular projection folds away are both present, at traversal depth, and every
+  /// regular node still appears -- `regular ⊆ raw` on the same capture.
+  func testPrivateAXRawProjectionKeepsEveryAcquiredNode() throws {
+    let viewport = CGRect(x: 0, y: 0, width: 402, height: 874)
+    let root = Self.privateAXScrolledFixture
+    let regular = try privateAXRegularPresentation(rawRoot: root, viewport: viewport,
+      interactiveOnly: true)
+    let raw = privateAXNormalizedAcquisition(rawRoot: root,
+      hint: CaptureHint(
+        projection: .raw, depth: nil, regularPresentedDepth: nil,
+        interactiveOnly: false, customActions: false),
+      viewport: viewport,
+      interfaceOrientation: RunnerInterfaceOrientation.portrait)
+
+    XCTAssertEqual(raw.map(\.type), ["Application", "ScrollView", "Button", "Image", "Button"])
+    XCTAssertEqual(raw.map(\.depth), [0, 1, 2, 3, 2])
+    XCTAssertEqual(raw.map(\.parentIndex), [nil, 0, 1, 2, 1])
+    XCTAssertEqual(raw.compactMap(\.label), ["Element", "Profile picture", "Theme"])
+    // The offscreen row is a reported fact in raw, and reported facts do not become hittable
+    // just because the projection kept them.
+    XCTAssertEqual(raw.last?.hittable, false)
+    XCTAssertTrue(raw.allSatisfy { $0.hiddenContentAbove == nil && $0.hiddenContentBelow == nil })
+
+    let rawKeys = Set(raw.map { "\($0.type)-\($0.label ?? "")-\($0.rect.y)" })
+    for node in regular {
+      XCTAssertTrue(
+        rawKeys.contains("\(node.type)-\(node.label ?? "")-\(node.rect.y)"),
+        "regular node \(node.type)/\(node.label ?? "") is missing from the raw projection"
+      )
+    }
+    XCTAssertGreaterThan(raw.count, regular.count)
+  }
+
+  /// Raw depth is traversal depth, so a raw `--depth` request is the one narrowing this backend
+  /// can prove complete.
+  func testPrivateAXRawProjectionAppliesRequestedTraversalDepth() {
+    let raw = privateAXNormalizedAcquisition(rawRoot: Self.privateAXScrolledFixture,
+      hint: CaptureHint(
+        projection: .raw, depth: 2, regularPresentedDepth: nil,
+        interactiveOnly: false, customActions: false),
+      viewport: CGRect(x: 0, y: 0, width: 402, height: 874),
+      interfaceOrientation: RunnerInterfaceOrientation.portrait)
+    XCTAssertEqual(raw.map(\.type), ["Application", "ScrollView", "Button", "Button"])
+    XCTAssertEqual(raw.map(\.depth), [0, 1, 2, 2])
+  }
+
+  func testPrivateAXPresentationKeepsOffscreenSubtreeExcludedWhenChildFramesAreClamped() throws {
+    let frame = Self.privateAXFrame
+    let root: [String: Any] = ["type": Int(XCUIElement.ElementType.application.rawValue),
+      "label": "Element", "frame": frame(0, 0, 402, 874), "children": [[
+        "type": Int(XCUIElement.ElementType.table.rawValue), "frame": frame(0, 96, 402, 700),
+        "children": [["type": Int(XCUIElement.ElementType.cell.rawValue),
+          "label": "Theme", "frame": frame(0, 900, 402, 44), "children": [[
+            "type": Int(XCUIElement.ElementType.staticText.rawValue),
+            "label": "Theme", "frame": frame(16, 96, 120, 44)],
+          ["type": Int(XCUIElement.ElementType.switch.rawValue),
+            "label": "Theme", "frame": frame(340, 96, 46, 44)]]]]]]]
+
+    let nodes = try privateAXRegularPresentation(
+      rawRoot: root, viewport: CGRect(x: 0, y: 0, width: 402, height: 874))
+
+    XCTAssertEqual(nodes.compactMap(\.label), ["Element"])
+    XCTAssertEqual(nodes.first { $0.type == "Table" }?.hiddenContentBelow, true)
+  }
+
+  func testPrivateAXGeometrylessSemanticsAreNeverActionableOrScrollContexts() throws {
+    let zero = ["x": 0, "y": 0, "width": 0, "height": 0]
+    let root: [String: Any] = ["type": Int(XCUIElement.ElementType.application.rawValue),
+      "label": "Element", "frame": ["x": 0, "y": 0, "width": 402, "height": 874],
+      "children": [["type": Int(XCUIElement.ElementType.scrollView.rawValue),
+        "label": "Settings semantics", "frame": zero, "children": [[
+          "type": Int(XCUIElement.ElementType.button.rawValue), "label": "Theme", "frame": zero],
+        ["type": Int(XCUIElement.ElementType.other.rawValue), "frame": zero]]]]]
+    let nodes = try privateAXRegularPresentation(
+      rawRoot: root, viewport: CGRect(x: 0, y: 0, width: 402, height: 874),
+      interactiveOnly: true)
+    XCTAssertEqual(nodes.compactMap(\.label), ["Element", "Settings semantics", "Theme"])
+    XCTAssertEqual(nodes.filter { $0.index != 0 }.map(\.hittable), [false, false])
+    XCTAssertFalse(nodes.contains { $0.type == "Other" })
+    XCTAssertTrue(nodes.allSatisfy { $0.hiddenContentAbove == nil && $0.hiddenContentBelow == nil })
+  }
+}
+#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+ScrollGestureTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+ScrollGestureTests.swift
new file mode 100644
index 0000000000..9e9b9d26fc
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+ScrollGestureTests.swift
@@ -0,0 +1,197 @@
+import XCTest
+
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS
+private struct ScrollGestureFixture: Decodable {
+  struct Constants: Decodable {
+    let defaultIosScrollAmount: Double
+    let defaultMobileScrollDurationMs: Double
+    let defaultIosScrollDurationMs: Double
+    let defaultScrollAmount: Double
+    let defaultEdgePaddingFraction: Double
+    let ordinaryScrollReleaseBehavior: String
+    let edgeScrollReleaseBehavior: String
+  }
+  struct Expected: Decodable {
+    let x1: Double
+    let y1: Double
+    let x2: Double
+    let y2: Double
+    let pixels: Double
+  }
+  struct Case: Decodable {
+    let name: String
+    let direction: String
+    let amount: Double?
+    let pixels: Double?
+    let referenceWidth: Double
+    let referenceHeight: Double
+    let expected: Expected
+  }
+
+  let constants: Constants
+  let cases: [Case]
+}
+
+extension RunnerTests {
+  // Cross-language parity table: every case in contracts/fixtures/scroll-gesture.json must agree
+  // with the vitest twin (packages/contracts/src/scroll-gesture.test.ts). Add vectors there,
+  // never fork the math.
+  private func loadScrollGestureFixture() throws -> ScrollGestureFixture {
+    let fixtureURL = URL(fileURLWithPath: #filePath)
+      .deletingLastPathComponent() // UnitTests
+      .deletingLastPathComponent() // AgentDeviceRunnerUITests
+      .deletingLastPathComponent() // AgentDeviceRunner
+      .deletingLastPathComponent() // runner
+      .deletingLastPathComponent() // apple
+      .deletingLastPathComponent() // repo root
+      .appendingPathComponent("contracts")
+      .appendingPathComponent("fixtures")
+      .appendingPathComponent("scroll-gesture.json")
+    return try JSONDecoder().decode(ScrollGestureFixture.self, from: Data(contentsOf: fixtureURL))
+  }
+
+  func testRunnerScrollGesturePlanMatchesParityTable() throws {
+    let fixture = try loadScrollGestureFixture()
+    XCTAssertFalse(fixture.cases.isEmpty, "parity table must not be empty")
+    for testCase in fixture.cases {
+      let plan = try XCTUnwrap(
+        runnerScrollGesturePlan(
+          direction: try XCTUnwrap(RunnerScrollDirection(rawValue: testCase.direction)),
+          amount: testCase.amount,
+          pixels: testCase.pixels,
+          referenceWidth: testCase.referenceWidth,
+          referenceHeight: testCase.referenceHeight
+        ),
+        testCase.name
+      )
+      XCTAssertEqual(plan.x1, testCase.expected.x1, testCase.name)
+      XCTAssertEqual(plan.y1, testCase.expected.y1, testCase.name)
+      XCTAssertEqual(plan.x2, testCase.expected.x2, testCase.name)
+      XCTAssertEqual(plan.y2, testCase.expected.y2, testCase.name)
+      XCTAssertEqual(plan.travelPixels, testCase.expected.pixels, testCase.name)
+    }
+  }
+
+  // The planner constants are private on both sides; the table pins them behaviourally on a
+  // 1000px axis where every rounding step is exact.
+  func testRunnerScrollGesturePlanUsesParityTableConstants() throws {
+    let constants = try loadScrollGestureFixture().constants
+    let defaultScroll = try JSONDecoder().decode(
+      Command.self, from: Data(#"{"command":"scroll"}"#.utf8))
+    let defaults = runnerDragCommandDefaults(defaultScroll)
+    XCTAssertEqual(defaults.durationMs, constants.defaultIosScrollDurationMs)
+    XCTAssertEqual(defaults.scrollAmount, constants.defaultIosScrollAmount)
+    let defaulted = try XCTUnwrap(
+      runnerScrollGesturePlan(
+        direction: .down, amount: nil, pixels: nil, referenceWidth: 1000, referenceHeight: 1000
+      )
+    )
+    XCTAssertEqual(defaulted.travelPixels, 1000 * constants.defaultScrollAmount)
+    let saturated = try XCTUnwrap(
+      runnerScrollGesturePlan(
+        direction: .down, amount: 10, pixels: nil, referenceWidth: 1000, referenceHeight: 1000
+      )
+    )
+    XCTAssertEqual(
+      saturated.travelPixels, 1000 - 2 * 1000 * constants.defaultEdgePaddingFraction)
+  }
+
+  func testRunnerScrollAndDragCommandDefaultsStayDistinct() throws {
+    func command(_ json: String) throws -> Command {
+      try JSONDecoder().decode(Command.self, from: Data(json.utf8))
+    }
+
+    let pixelScroll = runnerDragCommandDefaults(
+      try command(#"{"command":"scroll","pixels":120}"#))
+    XCTAssertNil(pixelScroll.scrollAmount)
+    XCTAssertEqual(pixelScroll.durationMs, 400)
+
+    let drag = runnerDragCommandDefaults(try command(#"{"command":"drag"}"#))
+    XCTAssertNil(drag.scrollAmount)
+    XCTAssertEqual(drag.durationMs, 250)
+
+    let explicitScroll = runnerDragCommandDefaults(
+      try command(#"{"command":"scroll","amount":0.5,"durationMs":125}"#))
+    XCTAssertEqual(explicitScroll.scrollAmount, 0.5)
+    XCTAssertEqual(explicitScroll.durationMs, 125)
+
+    let explicitDrag = runnerDragCommandDefaults(
+      try command(#"{"command":"drag","durationMs":125}"#))
+    XCTAssertEqual(explicitDrag.durationMs, 125)
+  }
+
+  func testRunnerScrollReleaseBehaviorSelectsTheDragProfile() throws {
+    let constants = try loadScrollGestureFixture().constants
+    let controlled = try XCTUnwrap(ScrollReleaseBehavior(rawValue: constants.ordinaryScrollReleaseBehavior))
+    let inertial = try XCTUnwrap(ScrollReleaseBehavior(rawValue: constants.edgeScrollReleaseBehavior))
+    XCTAssertEqual(
+      scrollDragProfile(releaseBehavior: nil),
+      .controlledScroll
+    )
+    XCTAssertEqual(
+      scrollDragProfile(releaseBehavior: controlled),
+      .controlledScroll
+    )
+    XCTAssertEqual(
+      scrollDragProfile(releaseBehavior: inertial),
+      .fastSwipe
+    )
+  }
+
+  func testControlledScrollProfileUsesReliableCadenceAndMonotonicDeceleration() {
+    XCTAssertEqual(RunnerControlledScrollFrameCount(350), 21)
+    XCTAssertEqual(RunnerControlledScrollFrameCount(400), 24)
+    XCTAssertEqual(RunnerControlledScrollFrameCount(500), 30)
+    XCTAssertEqual(RunnerControlledScrollFrameCount(1_000), 30)
+    XCTAssertEqual(RunnerControlledScrollFrameCount(10_000), 30)
+
+    let frameCount = RunnerControlledScrollFrameCount(400)
+    let progress = (0...frameCount).map {
+      RunnerControlledScrollProgress(Double($0) / Double(frameCount))
+    }
+    let deltas = zip(progress.dropFirst(), progress).map { $0.0 - $0.1 }
+    XCTAssertEqual(progress.first, 0)
+    XCTAssertEqual(progress.last, 1)
+    XCTAssertTrue(zip(deltas, deltas.dropFirst()).allSatisfy { $0.1 <= $0.0 })
+
+    let iPhoneViewportPoints = 874.0
+    let defaultFingerTravel = iPhoneViewportPoints * 0.65
+    let finalSampleTravel = (1 - progress[progress.count - 2]) * defaultFingerTravel
+    XCTAssertLessThan(finalSampleTravel, 0.1)
+  }
+
+  func testRunnerScrollGesturePlanRejectsUnknownDirection() {
+    XCTAssertNil(RunnerScrollDirection(rawValue: "sideways"))
+  }
+
+  func testRunnerScrollGesturePlanRejectsInvalidAmountAndPixels() {
+    XCTAssertNil(
+      runnerScrollGesturePlan(
+        direction: .down,
+        amount: 0,
+        pixels: nil,
+        referenceWidth: 300,
+        referenceHeight: 600
+      )
+    )
+    XCTAssertNil(
+      runnerScrollGesturePlan(
+        direction: .down,
+        amount: nil,
+        pixels: -10,
+        referenceWidth: 300,
+        referenceHeight: 600
+      )
+    )
+    XCTAssertNil(
+      runnerScrollGesturePlan(
+        direction: .down,
+        amount: .infinity,
+        pixels: nil,
+        referenceWidth: 300,
+        referenceHeight: 600
+      )
+    )
+  }
+}
+#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+ScrollViewportPolicyTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+ScrollViewportPolicyTests.swift
new file mode 100644
index 0000000000..208397cc95
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+ScrollViewportPolicyTests.swift
@@ -0,0 +1,165 @@
+import XCTest
+import AgentDeviceSnapshotPresentation
+
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS
+private struct ScrollViewportPolicyFixture: Decodable {
+  struct Frame: Decodable {
+    let x: Double
+    let y: Double
+    let width: Double
+    let height: Double
+
+    var cgRect: CGRect {
+      CGRect(x: x, y: y, width: width, height: height)
+    }
+  }
+
+  struct Constants: Decodable {
+    let minVisibleFraction: Double
+    let accessoryAllowance: Double
+  }
+
+  struct Expected: Decodable {
+    let kind: String
+    let viewport: Frame?
+    let keyboardMinY: Double?
+    let visibleHeight: Double?
+  }
+
+  struct TestCase: Decodable {
+    let name: String
+    let viewport: Frame
+    let keyboard: Frame
+    let expected: Expected
+  }
+
+  let constants: Constants
+  let cases: [TestCase]
+}
+
+extension RunnerTests {
+  /// Golden parity table (#2500): every case in contracts/fixtures/scroll-keyboard-policy.json must
+  /// agree with the vitest twin. Add cases there, never fork the rule.
+  func testScrollViewportKeyboardClipMatchesGoldenParityTable() throws {
+    let fixture = try loadScrollViewportPolicyFixture()
+    XCTAssertFalse(fixture.cases.isEmpty, "parity table must not be empty")
+    for testCase in fixture.cases {
+      let clip = ScrollViewportPolicy.clip(
+        viewport: testCase.viewport.cgRect,
+        keyboard: testCase.keyboard.cgRect
+      )
+      switch testCase.expected.kind {
+      case "unobstructed":
+        XCTAssertEqual(clip, .unobstructed, testCase.name)
+      case "avoided":
+        let expectedFrame = try XCTUnwrap(testCase.expected.viewport, testCase.name).cgRect
+        let expectedMinY = try XCTUnwrap(testCase.expected.keyboardMinY, testCase.name)
+        XCTAssertEqual(
+          clip,
+          .avoided(frame: expectedFrame, keyboardMinY: expectedMinY),
+          testCase.name
+        )
+      case "occluded":
+        let expectedMinY = try XCTUnwrap(testCase.expected.keyboardMinY, testCase.name)
+        let expectedVisibleHeight = try XCTUnwrap(testCase.expected.visibleHeight, testCase.name)
+        XCTAssertEqual(
+          clip,
+          .occluded(keyboardMinY: expectedMinY, visibleHeight: expectedVisibleHeight),
+          testCase.name
+        )
+      default:
+        XCTFail("unknown expected kind `\(testCase.expected.kind)` in \(testCase.name)")
+      }
+    }
+  }
+
+  /// The thresholds are the table's, not RunnerScrollViewportPolicy.swift's. The refusal reason
+  /// and the runner code are each one side's own vocabulary: the reason is what the host publishes,
+  /// the code is what this runner answers with, and neither is a shared clip constant.
+  func testScrollViewportPolicyUsesParityTableConstants() throws {
+    let constants = try loadScrollViewportPolicyFixture().constants
+    XCTAssertEqual(constants.minVisibleFraction, ScrollViewportPolicy.minVisibleFraction)
+    XCTAssertEqual(constants.accessoryAllowance, ScrollViewportPolicy.accessoryAllowance)
+  }
+
+  /// A clipped landscape band shortens the frame, and `CoordinateSpaceRotation.native(point:)` derives a
+  /// `landscapeRight` native x from the frame's HEIGHT. Rotating inside the band therefore moves the
+  /// dispatched path sideways by exactly what the keyboard took, off the lane the plan was built for,
+  /// so the plan band and the coordinate basis stay separate values through dispatch (#2500).
+  func testScrollViewportDispatchKeepsTheUnclippedFrameAsItsCoordinateRotationBasis() throws {
+    let viewport = CGRect(x: 0, y: 0, width: 1210, height: 834)
+    let keyboard = CGRect(x: 0, y: 588, width: 1210, height: 246)
+    let clip = ScrollViewportPolicy.clip(viewport: viewport, keyboard: keyboard)
+    guard case .avoided(let band, let keyboardMinY) = clip else {
+      return XCTFail("expected a landscape keyboard to be avoided, got \(clip)")
+    }
+    XCTAssertEqual(band.height, 576)
+
+    guard case .gesture(let gesture) = ScrollViewportPolicy.frames(
+      referenceFrame: viewport,
+      clip: clip
+    ).gestureDispatch(direction: .up, amount: nil, pixels: nil) else {
+      return XCTFail("expected a gesture inside the clipped band")
+    }
+    XCTAssertEqual(gesture.planFrame, band)
+    XCTAssertEqual(gesture.keyboardMinY, keyboardMinY)
+    XCTAssertEqual(gesture.coordinateFrame, viewport, "the rotation basis must survive the clip")
+    XCTAssertLessThanOrEqual(
+      max(gesture.plan.y1, gesture.plan.y2),
+      keyboard.minY - ScrollViewportPolicy.accessoryAllowance,
+      "a landscape swipe must stay clear of the keys"
+    )
+
+    let reported = gesture.attachingEvidence(
+      to: Response(
+        ok: true,
+        data: DataPayload(referenceWidth: viewport.width, referenceHeight: viewport.height),
+        error: nil
+      )
+    )
+    XCTAssertEqual(
+      reported.data?.referenceHeight,
+      band.height,
+      "the payload names the band the plan ran inside, not the synthesis frame"
+    )
+    XCTAssertEqual(reported.data?.referenceWidth, viewport.width)
+    XCTAssertEqual(reported.data?.keyboardMinY, keyboardMinY)
+    XCTAssertEqual(reported.data?.keyboardAvoided, true)
+
+    let orientedStartY = gesture.planFrame.minY + gesture.plan.y1
+    let dispatchedFromViewport = CoordinateSpaceRotation.native(
+      point: CGPoint(x: gesture.planFrame.minX + gesture.plan.x1, y: orientedStartY),
+      in: gesture.coordinateFrame,
+      interfaceOrientation: RunnerInterfaceOrientation.landscapeRight
+    )
+    let dispatchedFromBand = CoordinateSpaceRotation.native(
+      point: CGPoint(x: gesture.planFrame.minX + gesture.plan.x1, y: orientedStartY),
+      in: gesture.planFrame,
+      interfaceOrientation: RunnerInterfaceOrientation.landscapeRight
+    )
+    XCTAssertEqual(
+      dispatchedFromViewport.x - dispatchedFromBand.x,
+      viewport.height - band.height,
+      accuracy: 0.001,
+      "rotating inside the clipped band would shift native x by what the keyboard took"
+    )
+  }
+
+  private func loadScrollViewportPolicyFixture() throws -> ScrollViewportPolicyFixture {
+    let fixtureURL = URL(fileURLWithPath: #filePath)
+      .deletingLastPathComponent() // UnitTests
+      .deletingLastPathComponent() // AgentDeviceRunnerUITests
+      .deletingLastPathComponent() // AgentDeviceRunner
+      .deletingLastPathComponent() // runner
+      .deletingLastPathComponent() // apple
+      .deletingLastPathComponent() // repo root
+      .appendingPathComponent("contracts")
+      .appendingPathComponent("fixtures")
+      .appendingPathComponent("scroll-keyboard-policy.json")
+    return try JSONDecoder().decode(
+      ScrollViewportPolicyFixture.self,
+      from: Data(contentsOf: fixtureURL)
+    )
+  }
+}
+#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SequenceExecutionTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SequenceExecutionTests.swift
new file mode 100644
index 0000000000..a2e0327df6
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SequenceExecutionTests.swift
@@ -0,0 +1,186 @@
+import XCTest
+
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS
+// MARK: - In-bundle unit tests (device-free)
+
+extension RunnerTests {
+  func testSequenceDecodesStepsFromWire() throws {
+    let json = """
+    {"command":"sequence","commandId":"seq-1","steps":[
+      {"kind":"tap","x":100,"y":200},
+      {"kind":"doubleTap","x":101,"y":200},
+      {"kind":"longPress","x":102,"y":200,"durationMs":300,"pauseMs":50}
+    ]}
+    """
+    let command = try JSONDecoder().decode(Command.self, from: Data(json.utf8))
+    XCTAssertEqual(command.command, .sequence)
+    XCTAssertEqual(command.steps?.count, 3)
+    XCTAssertEqual(command.steps?[0].kind, "tap")
+    XCTAssertEqual(command.steps?[1].kind, "doubleTap")
+    XCTAssertEqual(command.steps?[2].pauseMs, 50)
+  }
+
+  func testSequenceAcceptsDoubleTapKind() {
+    // A doubleTap step missing coords must fail on the coords check, not the kind allowlist —
+    // proving "doubleTap" passes validateSequenceStep without needing a device to execute on.
+    let response = executeSequenceForTest(steps: [
+      sequenceStep(kind: "doubleTap", x: nil)
+    ])
+    XCTAssertEqual(response.ok, false)
+    XCTAssertEqual(response.error?.code, "INVALID_ARGS")
+    XCTAssertTrue(response.error?.message.contains("requires finite x and y") ?? false)
+    XCTAssertFalse(response.error?.message.contains("unsupported kind") ?? true)
+  }
+
+  func testSequenceRejectsUnknownKind() throws {
+    let response = executeSequenceForTest(steps: [
+      sequenceStep(kind: "tap", x: 1, y: 2),
+      sequenceStep(kind: "pinch", x: 3, y: 4),
+    ])
+    XCTAssertEqual(response.ok, false)
+    XCTAssertEqual(response.error?.code, "INVALID_ARGS")
+    XCTAssertTrue(response.error?.message.contains("step 1") ?? false)
+    XCTAssertTrue(response.error?.message.contains("pinch") ?? false)
+  }
+
+  func testSequenceRejectsEmpty() {
+    let response = executeSequenceForTest(steps: [])
+    XCTAssertEqual(response.ok, false)
+    XCTAssertEqual(response.error?.code, "INVALID_ARGS")
+  }
+
+  func testSequenceRejectsTooManySteps() {
+    let steps = (0..<21).map { _ in sequenceStep(kind: "tap", x: 1, y: 2) }
+    let response = executeSequenceForTest(steps: steps)
+    XCTAssertEqual(response.ok, false)
+    XCTAssertEqual(response.error?.code, "INVALID_ARGS")
+    XCTAssertTrue(response.error?.message.contains("at most 20") ?? false)
+  }
+
+  func testSequenceHasSynthesizedCoordinateStep() {
+    XCTAssertTrue(
+      sequenceHasSynthesizedCoordinateStep([
+        sequenceStep(kind: "tap", x: 1, y: 2, synthesized: true),
+      ])
+    )
+    XCTAssertFalse(
+      sequenceHasSynthesizedCoordinateStep([
+        sequenceStep(kind: "tap", x: 1, y: 2),
+        sequenceStep(kind: "doubleTap", x: 1, y: 2, synthesized: true),
+      ])
+    )
+  }
+
+  func testAssembleSequencePreservesOrderOnSuccess() {
+    let steps = [
+      sequenceStep(kind: "tap", x: 1, y: 1),
+      sequenceStep(kind: "longPress", x: 2, y: 2),
+      sequenceStep(kind: "tap", x: 3, y: 3),
+    ]
+    var calls: [Int] = []
+    let execution = assembleSequenceExecution(steps: steps) { index, _ in
+      calls.append(index)
+      return SequenceStepOutcome(
+        outcome: .performed,
+        gestureStartUptimeMs: Double(index * 10),
+        gestureEndUptimeMs: Double(index * 10 + 5)
+      )
+    }
+    XCTAssertEqual(calls, [0, 1, 2])
+    XCTAssertEqual(execution.completedSteps, 3)
+    XCTAssertNil(execution.failedStepIndex)
+    XCTAssertEqual(execution.results.map { $0.kind }, ["tap", "longPress", "tap"])
+    XCTAssertEqual(execution.gestureStartUptimeMs, 0)
+    XCTAssertEqual(execution.gestureEndUptimeMs, 25)
+  }
+
+  func testAssembleSequenceStopsAtFirstFailure() {
+    let steps = [
+      sequenceStep(kind: "tap", x: 1, y: 1),
+      sequenceStep(kind: "longPress", x: 2, y: 2),
+      sequenceStep(kind: "tap", x: 3, y: 3),
+    ]
+    var calls: [Int] = []
+    let execution = assembleSequenceExecution(steps: steps) { index, _ in
+      calls.append(index)
+      if index == 1 {
+        return SequenceStepOutcome(
+          outcome: .unsupported(message: "long press unsupported", hint: nil),
+          gestureStartUptimeMs: 10,
+          gestureEndUptimeMs: 15
+        )
+      }
+      return SequenceStepOutcome(outcome: .performed, gestureStartUptimeMs: 0, gestureEndUptimeMs: 5)
+    }
+    // Step 2 is never invoked.
+    XCTAssertEqual(calls, [0, 1])
+    XCTAssertEqual(execution.completedSteps, 1)
+    XCTAssertEqual(execution.failedStepIndex, 1)
+    // results.count == completedSteps + 1 (the failed step).
+    XCTAssertEqual(execution.results.count, 2)
+    XCTAssertEqual(execution.results[1].ok, false)
+    XCTAssertEqual(execution.results[1].errorCode, "UNSUPPORTED_OPERATION")
+    XCTAssertEqual(execution.results[1].errorMessage, "long press unsupported")
+  }
+
+  func testSequenceWorstCaseResponseStaysUnderJournalCap() throws {
+    let longMessage = String(repeating: "e", count: 200)
+    let results = (0..<20).map { index in
+      SequenceStepResult(
+        ok: index < 19,
+        kind: "longPress",
+        errorCode: index < 19 ? nil : "UNSUPPORTED_OPERATION",
+        errorMessage: index < 19 ? nil : longMessage,
+        gestureStartUptimeMs: 123456.789,
+        gestureEndUptimeMs: 123466.789
+      )
+    }
+    let response = Response(
+      ok: true,
+      data: DataPayload(
+        message: "sequence",
+        completedSteps: 19,
+        failedStepIndex: 19,
+        sequenceResults: results
+      )
+    )
+    let encoded = try JSONEncoder().encode(response)
+    XCTAssertLessThan(encoded.count, 16 * 1024)
+  }
+
+  private func sequenceStep(
+    kind: String,
+    x: Double?,
+    y: Double? = nil,
+    synthesized: Bool? = nil
+  ) -> SequenceStep {
+    SequenceStep(
+      kind: kind,
+      x: x,
+      y: y,
+      durationMs: nil,
+      pauseMs: nil,
+      synthesized: synthesized
+    )
+  }
+
+  /// Validation runs before any executor call, so the INVALID_ARGS paths are exercised without
+  /// reaching the device executor (which is never invoked when validation rejects).
+  private func executeSequenceForTest(steps: [SequenceStep]) -> Response {
+    let command = makeSequenceCommand(steps: steps)
+    return executeSequence(command: command, activeApp: app)
+  }
+
+  /// Build a sequence Command via JSON so the test does not depend on the memberwise init's
+  /// parameter order.
+  private func makeSequenceCommand(steps: [SequenceStep]) -> Command {
+    struct SequenceCommandFixture: Encodable {
+      let command = "sequence"
+      let commandId = "seq-test"
+      let steps: [SequenceStep]
+    }
+    let data = try! JSONEncoder().encode(SequenceCommandFixture(steps: steps))
+    return try! JSONDecoder().decode(Command.self, from: data)
+  }
+}
+#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotBackendCapabilitiesTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotBackendCapabilitiesTests.swift
new file mode 100644
index 0000000000..a56627eed9
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotBackendCapabilitiesTests.swift
@@ -0,0 +1,80 @@
+import XCTest
+
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS
+private struct SnapshotBackendParityFixture: Decodable {
+  struct Availability: Decodable {
+    let simulator: Bool
+    let physicalDevice: Bool
+  }
+
+  struct Backend: Decodable {
+    let name: String
+    let forceable: Bool
+    let supportsRawProjection: Bool
+    let regularDepth: String
+    let hittable: String
+    let availability: Availability
+  }
+
+  let backends: [Backend]
+}
+
+extension RunnerTests {
+  private func loadSnapshotBackendParityFixture() throws -> SnapshotBackendParityFixture {
+    let fixtureURL = URL(fileURLWithPath: #filePath)
+      .deletingLastPathComponent() // UnitTests
+      .deletingLastPathComponent() // AgentDeviceRunnerUITests
+      .deletingLastPathComponent() // AgentDeviceRunner
+      .deletingLastPathComponent() // runner
+      .deletingLastPathComponent() // apple
+      .deletingLastPathComponent() // repo root
+      .appendingPathComponent("contracts")
+      .appendingPathComponent("fixtures")
+      .appendingPathComponent("ios-snapshot-backends.json")
+    return try JSONDecoder().decode(
+      SnapshotBackendParityFixture.self,
+      from: Data(contentsOf: fixtureURL)
+    )
+  }
+
+  /// The JSON table is the cross-runtime declaration used by the TypeScript capability registry
+  /// and this runner. A backend case, forceability branch, projection/depth claim, or availability
+  /// change that is not classified in both implementations fails before an iOS smoke can drift.
+  func testSnapshotBackendDeclarationsMatchCapabilityFixture() throws {
+    let fixture = try loadSnapshotBackendParityFixture()
+    XCTAssertEqual(
+      fixture.backends.map(\.name),
+      SnapshotBackendKind.allCases.map(\.rawValue)
+    )
+
+    for expected in fixture.backends {
+      guard let backend = SnapshotBackendKind(rawValue: expected.name) else {
+        XCTFail("fixture contains an unknown snapshot backend: \(expected.name)")
+        continue
+      }
+      XCTAssertEqual(backend.isForceable, expected.forceable, expected.name)
+      XCTAssertEqual(backend.supportsRawProjection, expected.supportsRawProjection, expected.name)
+      XCTAssertEqual(
+        backend.regularDepthCapability.rawValue,
+        expected.regularDepth,
+        "regular depth capability: \(expected.name)"
+      )
+      XCTAssertEqual(
+        backend.hittableSemantics,
+        expected.hittable,
+        "hittable semantics: \(expected.name)"
+      )
+      XCTAssertEqual(
+        backend.isAvailable(on: .simulator),
+        expected.availability.simulator,
+        "simulator availability: \(expected.name)"
+      )
+      XCTAssertEqual(
+        backend.isAvailable(on: .physicalDevice),
+        expected.availability.physicalDevice,
+        "physical-device availability: \(expected.name)"
+      )
+    }
+  }
+}
+#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotCapturePlanTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotCapturePlanTests.swift
new file mode 100644
index 0000000000..f0eae25e74
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotCapturePlanTests.swift
@@ -0,0 +1,492 @@
+import XCTest
+import AgentDeviceSnapshotPresentation
+
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS
+// MARK: - In-bundle unit tests
+
+extension RunnerTests {
+  private func planTestNode(
+    index: Int,
+    type: String,
+    label: String? = nil,
+    identifier: String? = nil,
+    hittable: Bool = false,
+    parentIndex: Int? = nil
+  ) -> PresentedNode {
+    SnapshotPresentation.singleElementRead(
+      RawAXNode(
+        index: index,
+        type: type,
+        label: label,
+        identifier: identifier,
+        value: nil,
+        rect: SnapshotRect(.zero),
+        enabled: true,
+        focused: nil,
+        selected: nil,
+        hittable: hittable,
+        depth: parentIndex == nil ? 0 : 1,
+        parentIndex: parentIndex,
+        hiddenContentAbove: nil,
+        hiddenContentBelow: nil
+      )
+    )
+  }
+
+  func testSparsePayloadReasonMatrix() {
+    let root = planTestNode(index: 0, type: "Application", label: "Example App", hittable: true)
+    let window = planTestNode(index: 1, type: "Window", parentIndex: 0)
+    let button = planTestNode(index: 1, type: "Button", label: "Ok", hittable: true, parentIndex: 0)
+    let shell = planTestNode(
+      index: 1,
+      type: "Other",
+      identifier: "appShell",
+      parentIndex: 0
+    )
+    let serializationPlaceholder = planTestNode(
+      index: 2,
+      type: "Other",
+      label: "[object Object]",
+      parentIndex: 1
+    )
+
+    // Labeled, hittable root over a bare window is still sparse.
+    XCTAssertNotNil(Self.sparsePayloadReason(DataPayload(nodes: [root, window], truncated: false)))
+    // Deadline-truncated near-empty sweep needs recovery even with one real control.
+    XCTAssertNotNil(Self.sparsePayloadReason(DataPayload(nodes: [root, button], truncated: true)))
+    // The same tiny tree from a completed sweep is a legitimately minimal screen.
+    XCTAssertNil(Self.sparsePayloadReason(DataPayload(nodes: [root, button], truncated: false)))
+    // Container metadata plus a stringified serialization placeholder is not readable UI.
+    XCTAssertNotNil(
+      Self.sparsePayloadReason(
+        DataPayload(nodes: [root, shell, serializationPlaceholder], truncated: false)
+      )
+    )
+    let actionableShell = planTestNode(
+      index: 1,
+      type: "Other",
+      identifier: "checkout",
+      hittable: true,
+      parentIndex: 0
+    )
+    XCTAssertNil(
+      Self.sparsePayloadReason(DataPayload(nodes: [root, actionableShell], truncated: false))
+    )
+    // Empty payloads are degraded.
+    XCTAssertNotNil(Self.sparsePayloadReason(DataPayload(nodes: [], truncated: false)))
+  }
+
+  func testCollapsedLeafIndexesFlagsMergedContainersOnly() {
+    let root = planTestNode(index: 0, type: "Application", label: "App")
+    let merged = planTestNode(
+      index: 1,
+      type: "Other",
+      label: (0...30).map { "Row \($0), Tap" }.joined(separator: ", "),
+      parentIndex: 0
+    )
+    let prose = planTestNode(
+      index: 2,
+      type: "StaticText",
+      label: (0...30).map { "clause \($0)" }.joined(separator: ", "),
+      parentIndex: 0
+    )
+    XCTAssertEqual(Self.collapsedLeafIndexes([root, merged, prose]), [1])
+    XCTAssertNil(Self.collapsedLeafIndexes([root, prose]))
+  }
+
+  func testTerminalFailsClosedOnInteractiveAxFailureRegardlessOfSparseBest() {
+    // Interactive AX failure must invalidate + fail closed; a later tier's sparse synthetic-root
+    // "best" must never downgrade this to a returned-sparse payload (regression: best == nil guard).
+    XCTAssertEqual(
+      Self.resolveSnapshotPlanTerminal(terminal: .sparseWithFatalOnAXFailure, interactiveOnly: true),
+      .failClosed
+    )
+    XCTAssertEqual(
+      Self.resolveSnapshotPlanTerminal(terminal: .sparseWithFatalOnAXFailure, interactiveOnly: false),
+      .sparseBest
+    )
+    XCTAssertEqual(
+      Self.resolveSnapshotPlanTerminal(terminal: .throwOnAXFailure, interactiveOnly: true),
+      .throwAxFailure
+    )
+  }
+
+  func testXCTestChannelStateFirstFailureStampsDeferredCodeOnlyForDeferral() {
+    XCTAssertNil(Self.xcTestChannelStateFirstFailure(.normal))
+    XCTAssertEqual(Self.xcTestChannelStateFirstFailure(.deferredToIndependentBackend)?.code, "deferred")
+    XCTAssertEqual(Self.xcTestChannelStateFirstFailure(.boundedXCTestProbe)?.code, "budget")
+  }
+
+  func testSnapshotQualityCarriesPhaseTimingAtResponseLevel() {
+    let timing = SnapshotCaptureTiming(acquisitionMs: 12, presentationMs: 34)
+    let capture = SnapshotBackendCapture(
+      payload: DataPayload(
+        nodes: [planTestNode(index: 0, type: "Application", label: "App")],
+        truncated: false
+      ),
+      effectiveDepth: nil,
+      timing: timing
+    )
+
+    let payload = stampedSnapshotPayload(
+      capture,
+      backend: .recursiveTree,
+      state: "healthy",
+      reason: nil
+    )
+
+    XCTAssertEqual(payload.snapshotQuality?.timing, timing)
+    XCTAssertEqual(payload.nodes?.count, 1)
+  }
+
+  func testStampedPayloadCarriesDisclosuresOnlyInTheVerdict() {
+    let root = planTestNode(index: 0, type: "Application", label: "App")
+    let merged = planTestNode(
+      index: 1,
+      type: "Other",
+      label: (0...30).map { "Tab \($0)" }.joined(separator: ", "),
+      parentIndex: 0
+    )
+    let coverage = SnapshotCustomActionCoverage(
+      read: 12, candidates: 19, truncated: 0, blocked: false)
+    let silent = stampedSnapshotPayload(
+      SnapshotBackendCapture(
+        payload: DataPayload(nodes: [root, merged], truncated: false),
+        effectiveDepth: nil,
+        customActions: coverage
+      ),
+      backend: .recursiveTree,
+      state: "healthy",
+      reason: nil
+    )
+    XCTAssertNil(silent.message)
+    XCTAssertEqual(silent.snapshotQuality?.customActions, coverage)
+    XCTAssertEqual(silent.snapshotQuality?.collapsedLeafIndexes, [1])
+
+    let underlying = stampedSnapshotPayload(
+      SnapshotBackendCapture(
+        payload: DataPayload(message: "underlying", nodes: [root], truncated: false),
+        effectiveDepth: 4
+      ),
+      backend: .privateAX,
+      state: "recovered",
+      reason: (reason: "tree capture timed out", code: "budget")
+    )
+    XCTAssertEqual(underlying.message, "underlying")
+  }
+
+  func testStampedPayloadTruncationTracksCompletenessNotRecoveryProvenance() {
+    let complete = SnapshotBackendCapture(
+      payload: DataPayload(
+        nodes: [
+          planTestNode(index: 0, type: "Application", label: "App"),
+          planTestNode(index: 1, type: "Button", label: "Open", parentIndex: 0),
+        ],
+        truncated: false
+      ),
+      effectiveDepth: nil
+    )
+    let deferred: (reason: String, code: String) = (
+      "XCTest-backed snapshot tiers were deferred after recent slow accessibility work", "deferred"
+    )
+
+    // The CI signature behind `is absent ... capture was truncated`: a complete private AX
+    // tree selected while the XCTest channel is penalized is whole, and must say so.
+    let recovered = stampedSnapshotPayload(
+      complete, backend: .privateAX, state: "recovered", reason: deferred)
+    XCTAssertEqual(recovered.snapshotQuality?.state, "recovered")
+    XCTAssertEqual(recovered.truncated, false)
+
+    let depthLimited = stampedSnapshotPayload(
+      SnapshotBackendCapture(payload: complete.payload, effectiveDepth: 56),
+      backend: .privateAX, state: "recovered", reason: deferred)
+    XCTAssertEqual(depthLimited.truncated, true)
+
+    let cappedPayload = stampedSnapshotPayload(
+      SnapshotBackendCapture(
+        payload: DataPayload(nodes: complete.payload.nodes ?? [], truncated: true),
+        effectiveDepth: nil),
+      backend: .recursiveTree, state: "healthy", reason: nil)
+    XCTAssertEqual(cappedPayload.truncated, true)
+
+    let sparse = stampedSnapshotPayload(
+      complete, backend: .querySweep, state: "sparse",
+      reason: ("snapshot returned no semantic controls or content", "sparse-tree"))
+    XCTAssertEqual(sparse.truncated, true)
+  }
+
+  func testSnapshotQualityCarriesUnscopedQualityPayload() {
+    let quality = DataPayload(
+      nodes: [planTestNode(index: 0, type: "Application", label: "App")],
+      truncated: false
+    )
+    let capture = SnapshotBackendCapture(
+      payload: quality,
+      effectiveDepth: nil,
+      qualityPayload: quality
+    )
+
+    let payload = stampedSnapshotPayload(
+      capture,
+      backend: .recursiveTree,
+      state: "healthy",
+      reason: nil
+    )
+
+    XCTAssertEqual(payload.qualityPayload?.nodes.count, 1)
+    XCTAssertEqual(payload.qualityPayload?.truncated, false)
+    XCTAssertNil(payload.qualityPayload?.scope)
+  }
+
+  func testDirectPresentationDoesNotClaimPlanTiming() {
+    let options = PresentationOptions(
+      interactiveOnly: false,
+      depth: nil,
+      scope: nil,
+      raw: true
+    )
+    let result = SnapshotPresentation.presentRaw(
+      SnapshotAcquisition(
+        hint: SnapshotPresentation.captureHint(for: options),
+        nodes: [],
+        truncated: false,
+        effectiveDepth: nil,
+        viewport: .infinite
+      ),
+      options: options
+    )
+    let capture = Self.makeSnapshotBackendCapture(from: result)
+
+    let payload = stampedSnapshotPayload(
+      capture,
+      backend: .recursiveTree,
+      state: "healthy",
+      reason: nil
+    )
+
+    XCTAssertNil(payload.snapshotQuality?.timing)
+  }
+
+  /// The raw plan is derived from what each backend can actually serve, not from a second
+  /// hand-maintained list. Non-vacuity: flipping `querySweep.supportsRawProjection` to true adds it
+  /// to the plan and fails the first two assertions — which is exactly the shape of #1797 D4, a
+  /// `--raw` request answered by a backend that has no hierarchy to return.
+  func testRawDiagnosticPlanCarriesOnlyBackendsThatCanServeRaw() {
+    XCTAssertEqual(Self.rawDiagnosticPlan, [.recursiveTree, .privateAX])
+    XCTAssertEqual(
+      SnapshotBackendKind.allCases.filter { !$0.supportsRawProjection }, [.querySweep])
+    XCTAssertTrue(Self.rawDiagnosticPlan.allSatisfy(\.supportsRawProjection))
+    // Tree-first error propagation is the raw plan's other contract (ADR 0004).
+    XCTAssertEqual(Self.rawDiagnosticPlan.first, .recursiveTree)
+  }
+
+  /// A projection mismatch is a runner bug, not an accessibility failure: it must not take the
+  /// AX-failure terminal route (rethrow / fail-closed), just drop its tier with a named reason.
+  func testProjectionMismatchFailureIsStructuredAndNotAnAxFailure() {
+    let failure = Self.snapshotProjectionMismatchFailure(
+      .querySweep, requested: .raw, acquired: .regular)
+    XCTAssertEqual(failure.code, "IOS_SNAPSHOT_PROJECTION_MISMATCH")
+    XCTAssertTrue(failure.message.contains("queries"))
+    XCTAssertTrue(failure.message.contains("raw"))
+    XCTAssertFalse(Self.isAxSnapshotFailure(failure))
+  }
+
+  /// #1634 P2: the decoded wire field must reach capture options and its
+  /// applicable plan. A pinned REGULAR capture defers to privateAX-first; the
+  /// RAW diagnostic plan is never rerouted by the pin — raw keeps tree-first
+  /// error propagation, which is exactly why raw baselines are excluded from
+  /// corroboration daemon-side.
+  func testDecodedPreferredBackendReachesOptionsAndApplicablePlan() throws {
+    let json = #"{"command":"snapshot","preferredBackend":"private-ax"}"#
+    let command = try JSONDecoder().decode(Command.self, from: Data(json.utf8))
+    let options = Self.presentationOptions(from: command)
+    XCTAssertEqual(options.preferredBackend, "private-ax")
+    XCTAssertFalse(options.raw)
+
+    let treated = Self.snapshotXCTestChannelTreatedAsPenalized(
+      penalized: false, preferredBackend: options.preferredBackend)
+    let pinned = Self.effectiveSnapshotCapturePlan(
+      Self.regularVisiblePlan,
+      xCTestChannelPenalized: treated,
+      preferredBackend: options.preferredBackend
+    )
+    XCTAssertEqual(pinned.plan, [.privateAX])
+    XCTAssertEqual(pinned.xCTestChannelState, .deferredToIndependentBackend)
+
+    let raw = Self.effectiveSnapshotCapturePlan(
+      Self.rawDiagnosticPlan,
+      xCTestChannelPenalized: treated,
+      preferredBackend: options.preferredBackend
+    )
+    XCTAssertEqual(raw.plan, Self.rawDiagnosticPlan)
+
+    // A command without the field decodes to no pin and a normal plan.
+    let bare = try JSONDecoder().decode(
+      Command.self, from: Data(#"{"command":"snapshot"}"#.utf8))
+    XCTAssertNil(Self.presentationOptions(from: bare).preferredBackend)
+  }
+
+  /// #1635: the force seam must select the recursive tree even when the XCTest
+  /// channel is currently penalized. Without the preferred-backend argument,
+  /// this call returns the independent private-AX recovery plan instead.
+  func testPreferredTreeBackendPinsRegularPlanAndLeavesStructuredEvidence() {
+    let forced = Self.effectiveSnapshotCapturePlan(
+      Self.regularVisiblePlan,
+      xCTestChannelPenalized: true,
+      preferredBackend: SnapshotBackendKind.recursiveTree.rawValue
+    )
+    XCTAssertEqual(forced.plan, [.recursiveTree])
+    XCTAssertEqual(forced.xCTestChannelState, .normal)
+    XCTAssertEqual(
+      Self.xcTestChannelStateFirstFailure(
+        forced.xCTestChannelState,
+        preferredBackend: forced.preferredBackend?.rawValue
+      )?.code,
+      "requested-backend"
+    )
+  }
+
+  /// Same-backend evidence probes: a daemon-pinned private-AX capture takes the
+  /// penalized route even with a healthy channel, so tap-outcome corroboration
+  /// baselines and probes are always captured by the same backend (backends are
+  /// never comparable views of a screen). Composed with the plan rule, the pin
+  /// yields the privateAX-first deferred plan.
+  func testPreferredPrivateAXBackendPlansAsPenalized() {
+    XCTAssertTrue(
+      Self.snapshotXCTestChannelTreatedAsPenalized(penalized: false, preferredBackend: "private-ax"))
+    XCTAssertTrue(
+      Self.snapshotXCTestChannelTreatedAsPenalized(penalized: true, preferredBackend: nil))
+    XCTAssertFalse(
+      Self.snapshotXCTestChannelTreatedAsPenalized(penalized: false, preferredBackend: nil))
+    XCTAssertFalse(
+      Self.snapshotXCTestChannelTreatedAsPenalized(penalized: false, preferredBackend: "tree"))
+
+    let pinned = Self.effectiveSnapshotCapturePlan(
+      Self.regularVisiblePlan,
+      xCTestChannelPenalized: Self.snapshotXCTestChannelTreatedAsPenalized(
+        penalized: false, preferredBackend: "private-ax"
+      ),
+      preferredBackend: "private-ax"
+    )
+    XCTAssertEqual(pinned.plan, [.privateAX])
+    XCTAssertEqual(pinned.xCTestChannelState, .deferredToIndependentBackend)
+  }
+
+  func testEffectiveSnapshotCapturePlanDefersXCTestBackedTiersOnlyWhenPenalizedRegularPlan() {
+    let regular = Self.effectiveSnapshotCapturePlan(
+      Self.regularVisiblePlan,
+      xCTestChannelPenalized: true
+    )
+    XCTAssertEqual(regular.plan, [.privateAX])
+    XCTAssertEqual(regular.xCTestChannelState, .deferredToIndependentBackend)
+    XCTAssertNil(regular.treeCaptureSliceBudgetOverride)
+
+    let unpenalized = Self.effectiveSnapshotCapturePlan(
+      Self.regularVisiblePlan,
+      xCTestChannelPenalized: false
+    )
+    XCTAssertEqual(unpenalized.plan, Self.regularVisiblePlan)
+    XCTAssertEqual(unpenalized.xCTestChannelState, .normal)
+    XCTAssertNil(unpenalized.treeCaptureSliceBudgetOverride)
+
+    // The raw diagnostic plan preserves tree-first error propagation even under penalty.
+    let raw = Self.effectiveSnapshotCapturePlan(
+      Self.rawDiagnosticPlan,
+      xCTestChannelPenalized: true
+    )
+    XCTAssertEqual(raw.plan, Self.rawDiagnosticPlan)
+    XCTAssertEqual(raw.xCTestChannelState, .normal)
+    XCTAssertNil(raw.treeCaptureSliceBudgetOverride)
+  }
+
+  func testEffectiveSnapshotCapturePlanUsesBoundedXCTestProbeWhenNoIndependentBackendRuns() {
+    let physicalDevicePlan = Self.effectiveSnapshotCapturePlan(
+      Self.regularVisiblePlan,
+      xCTestChannelPenalized: true,
+      availableBackends: [.recursiveTree, .querySweep]
+    )
+
+    XCTAssertEqual(physicalDevicePlan.plan, [.recursiveTree, .querySweep])
+    XCTAssertEqual(physicalDevicePlan.xCTestChannelState, .boundedXCTestProbe)
+    XCTAssertEqual(
+      physicalDevicePlan.treeCaptureSliceBudgetOverride,
+      Self.penalizedXCTestProbeTreeSliceBudget
+    )
+  }
+
+  func testSnapshotXCTestChannelPenaltyMatchesBundleAndExpires() {
+    defer {
+      snapshotXCTestChannelPenaltyBundleId = nil
+      snapshotXCTestChannelPenaltyUntil = .distantPast
+    }
+
+    penalizeSnapshotXCTestChannel(bundleId: "xyz.blueskyweb.app", reason: "test")
+    XCTAssertTrue(isSnapshotXCTestChannelPenalized(bundleId: "xyz.blueskyweb.app"))
+    XCTAssertFalse(isSnapshotXCTestChannelPenalized(bundleId: "com.other.app"))
+
+    // A penalty recorded without a bundle applies to any current target.
+    penalizeSnapshotXCTestChannel(bundleId: nil, reason: "test")
+    XCTAssertTrue(isSnapshotXCTestChannelPenalized(bundleId: "com.other.app"))
+
+    // Expired penalties stop applying.
+    snapshotXCTestChannelPenaltyUntil = Date(timeIntervalSinceNow: -1)
+    XCTAssertFalse(isSnapshotXCTestChannelPenalized(bundleId: "com.other.app"))
+  }
+
+  func testAbandonedMainThreadWorkSkipsOnlyXCTestBackedSnapshotTiers() {
+    abandonedMainThreadWorkCount = 1
+    defer { abandonedMainThreadWorkCount = 0 }
+
+    XCTAssertTrue(shouldSkipSnapshotBackendForAbandonedMainThreadWork(.recursiveTree))
+    XCTAssertTrue(shouldSkipSnapshotBackendForAbandonedMainThreadWork(.querySweep))
+    XCTAssertFalse(shouldSkipSnapshotBackendForAbandonedMainThreadWork(.privateAX))
+  }
+
+#if os(iOS)
+  /// #2403: a plan pinned to private AX serves a regular `--depth` request through acquisition
+  /// and presentation. With a backend depth gate in `captureWithBackend`, private AX returns no
+  /// capture, the plan falls through to the synthetic sparse root, and the daemon rejects that
+  /// zero-rect root as a missing viewport.
+  func testPrivateAXPinnedRegularDepthReachesAcquisitionAndPresentation() throws {
+    app.launchArguments = ["--agent-device-selector-read-regression"]
+    app.launch()
+    currentApp = app
+    currentBundleId = nil
+    defer {
+      currentApp = nil
+      clearPrivateAXAcceptedDepth(reason: "test-cleanup")
+      app.terminate()
+    }
+    func capture(depth: Int?) throws -> DataPayload {
+      try runSnapshotCapturePlan(
+        Self.regularVisiblePlan,
+        app: app,
+        options: PresentationOptions(
+          interactiveOnly: false,
+          depth: depth,
+          scope: nil,
+          raw: false,
+          preferredBackend: SnapshotBackendKind.privateAX.rawValue
+        ),
+        terminal: .sparseWithFatalOnAXFailure
+      )
+    }
+
+    let capped = try capture(depth: 1)
+
+    let quality = try XCTUnwrap(capped.snapshotQuality)
+    XCTAssertEqual(quality.backend, SnapshotBackendKind.privateAX.rawValue)
+    XCTAssertNotEqual(quality.state, "sparse")
+    let nodes = try XCTUnwrap(capped.nodes)
+    XCTAssertGreaterThan(nodes.count, 1)
+    XCTAssertEqual(nodes.map(\.depth).max(), 1)
+    XCTAssertNotEqual(nodes[0].rect, SnapshotRect(x: 0, y: 0, width: 0, height: 0))
+    XCTAssertTrue(nodes.contains { $0.label == "Readable target" })
+
+    // The presented cut only ever narrows the unscoped capture from the same backend.
+    let unscoped = try XCTUnwrap(try capture(depth: nil).nodes)
+    XCTAssertLessThanOrEqual(nodes.count, unscoped.count)
+  }
+#endif
+}
+#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotTests.swift
new file mode 100644
index 0000000000..527da828fb
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotTests.swift
@@ -0,0 +1,245 @@
+import XCTest
+import AgentDeviceSnapshotPresentation
+
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS
+extension RunnerTests {
+  func testSnapshotAccessibilityUnavailableMarksSparseSnapshotRunnerFatal() {
+    currentApp = app
+    currentBundleId = "com.example.app"
+
+    let payload = snapshotAccessibilityUnavailable(
+      failure: SnapshotCaptureFailure(
+        code: Self.axSnapshotErrorCode,
+        message: Self.axSnapshotFailureMessage,
+        hint: Self.axSnapshotHint
+      )
+    )
+
+    XCTAssertEqual(payload.message, "\(Self.axSnapshotFailureMessage) Hint: \(Self.axSnapshotHint)")
+    XCTAssertEqual(payload.nodes?.count, 1)
+    XCTAssertEqual(payload.nodes?.first?.type, "Application")
+    XCTAssertEqual(payload.truncated, true)
+    XCTAssertEqual(payload.runnerFatal, true)
+    XCTAssertEqual(payload.runnerFatalReason, Self.axSnapshotUnavailableReason)
+    // The planned terminal result carries the structured verdict like every other planned
+    // snapshot — downstream sparse handling keys off it, not off node shapes.
+    XCTAssertEqual(payload.snapshotQuality?.state, "sparse")
+    XCTAssertEqual(payload.snapshotQuality?.reasonCode, "ax-rejected")
+    XCTAssertEqual(payload.snapshotQuality?.reason, Self.axSnapshotFailureMessage)
+    XCTAssertNil(currentApp)
+    XCTAssertNil(currentBundleId)
+  }
+
+  func testRecoveredSnapshotMessagePreservesHint() {
+    let message = recoveredSnapshotMessage(
+      SnapshotCaptureFailure(
+        code: Self.axSnapshotErrorCode,
+        message: Self.axSnapshotFailureMessage,
+        hint: Self.axSnapshotHint
+      )
+    )
+
+    XCTAssertTrue(message.contains(Self.axSnapshotFailureMessage))
+    XCTAssertTrue(message.contains(Self.axSnapshotHint))
+  }
+
+  func testRawSnapshotTooLargeFailureIsStructured() {
+    let failure = rawSnapshotTooLargeFailure(nodeCount: Self.rawSnapshotMaxNodes + 1)
+
+    XCTAssertEqual(failure.code, Self.rawSnapshotTooLargeCode)
+    XCTAssertTrue(failure.message.contains("\(Self.rawSnapshotMaxNodes) nodes"))
+    XCTAssertEqual(failure.hint, Self.rawSnapshotTooLargeHint)
+  }
+
+  func testSystemModalProbeSliceSharesAndClampsToPlanDeadline() {
+    // Fresh plan deadline: the probe gets its full dedicated budget.
+    XCTAssertEqual(Self.systemModalProbeSlice(budget: 4, deadlineRemaining: 20), 4)
+    // Nearly-spent plan deadline: the probe is clamped so it can't run past the shared budget.
+    XCTAssertEqual(Self.systemModalProbeSlice(budget: 4, deadlineRemaining: 1.5), 1.5)
+    // Exactly/already exhausted deadline: skip the probe entirely (0), never a negative timeout.
+    XCTAssertEqual(Self.systemModalProbeSlice(budget: 4, deadlineRemaining: 0), 0)
+    XCTAssertEqual(Self.systemModalProbeSlice(budget: 4, deadlineRemaining: -5), 0)
+  }
+
+  // Simulator-only: the bounded probe body returns nil on macOS (no SpringBoard host), so the
+  // timeout/penalty/drain machinery below only exists on the iOS branch.
+#if os(iOS)
+  /// Regression for #1244/#1248: drives the bounded system-modal probe through a real,
+  /// production-only command entry point (`snapshotFast` or `snapshotRaw` -- see the two test
+  /// methods below), not `boundedBlockingSystemAlertSnapshot` directly, with
+  /// `systemModalProbeOverrideForTesting` set to a closure that blocks past the probe's real
+  /// slice, forcing a real `runMainThreadWork` timeout. This is revert-sensitive on both halves
+  /// of the fix, for either entry point:
+  ///   - if the entry point reverted to calling the unbounded `blockingSystemAlertSnapshot`
+  ///     directly (or dropped the `runMainThreadWork` wrap), nothing here would ever time out,
+  ///     so the mid-flight busy/penalty assertions below would never be met;
+  ///   - if the `onAbandoned` penalty hook or the abandoned-work accounting were dropped, the
+  ///     timeout would still fire, but the busy/penalty and drain assertions would not hold.
+  ///
+  /// The drain assertion is synchronized on the *real* release rather than raced: after
+  /// signaling the probe to finish, the background queue polls `hasAbandonedMainThreadWork()`
+  /// (bounded) and only then fulfills `drained`, which the test `wait(for:timeout:)`s on before
+  /// asserting `.idle`/`hasAbandonedMainThreadWork() == false` below -- so a slow drain fails that
+  /// assertion instead of racing a fixed-timing guess.
+  private func assertBoundedSystemModalProbeTimeoutRecoversThenReleasesOnDrain(
+    entryPointName: String,
+    callEntryPoint: @escaping (XCUIApplication, PresentationOptions) throws -> DataPayload
+  ) {
+    let targetBundleId = "com.callstack.agentdevice.runner.missing.snapshot-timeout-test"
+    let snapshotTarget = XCUIApplication(bundleIdentifier: targetBundleId)
+    let probeReleaseGate = DispatchSemaphore(value: 0)
+    currentApp = snapshotTarget
+    currentBundleId = targetBundleId
+    defer {
+      probeReleaseGate.signal()
+      currentApp = nil
+      currentBundleId = nil
+      systemModalProbeOverrideForTesting = nil
+      clearSnapshotXCTestChannelPenalty(reason: "test-cleanup")
+    }
+
+    final class ResultBox {
+      var payload: DataPayload?
+      var wasBusyBeforeDrain = false
+      var hadAbandonedCaptureBeforeDrain = false
+      var wasPenalizedBeforeDrain = false
+    }
+    let box = ResultBox()
+    // The test owns release of the injected probe. A fixed timeout races the capture plan's
+    // independent fallback tiers on loaded CI hosts and can drain before the test records the
+    // abandoned-work state. The defer above still releases the probe if an earlier assertion or
+    // expectation fails.
+    systemModalProbeOverrideForTesting = { _ in
+      probeReleaseGate.wait()
+      return nil
+    }
+
+    let completion = expectation(
+      description: "\(entryPointName) recovered while the probe was abandoned, then released it"
+    )
+    let drained = expectation(description: "\(entryPointName) modal probe drained")
+    DispatchQueue(label: "agent-device.runner.tests.modal-probe-timeout").async {
+      box.payload = try? callEntryPoint(
+        snapshotTarget,
+        PresentationOptions(interactiveOnly: false, depth: nil, scope: nil, raw: false)
+      )
+
+      // 1) Penalty/busy accounting: must already be in place by the time the entry point
+      // returns, well before we release the still-blocked probe below.
+      if case .busy = self.currentMainThreadBusyState() {
+        box.wasBusyBeforeDrain = true
+      }
+      box.hadAbandonedCaptureBeforeDrain = self.hasAbandonedMainThreadWork()
+      box.wasPenalizedBeforeDrain = self.isSnapshotXCTestChannelPenalized(bundleId: self.currentBundleId)
+
+      // 2) `box.payload` above was already produced -- through the capture plan's recovery
+      // tiers -- while the probe is still blocked on `probeReleaseGate`, i.e. recovered before
+      // drain, not queued behind it.
+      completion.fulfill()
+
+      // 3) Only now let the abandoned probe finish, then block this queue (never the test's
+      // main-thread wait) on the *real* drain signal -- the abandoned-work count reaching zero
+      // -- bounded so a revert that never drains fulfills `drained` anyway and lets the
+      // assertions below report the regression explicitly instead of just timing out.
+      probeReleaseGate.signal()
+      let drainDeadline = Date().addingTimeInterval(5)
+      while self.hasAbandonedMainThreadWork(), Date() < drainDeadline {
+        self.sleepFor(0.002)
+      }
+      drained.fulfill()
+    }
+
+    wait(for: [completion], timeout: 15)
+
+    // 1) Penalty/busy accounting.
+    XCTAssertTrue(
+      box.wasBusyBeforeDrain,
+      "expected RUNNER_BUSY while the \(entryPointName) modal probe timeout is outstanding"
+    )
+    XCTAssertTrue(
+      box.hadAbandonedCaptureBeforeDrain,
+      "onAbandoned must retain the abandoned XCTest channel work for \(entryPointName)"
+    )
+    XCTAssertTrue(
+      box.wasPenalizedBeforeDrain,
+      "a timed-out modal probe must penalize the XCTest snapshot channel for \(entryPointName)"
+    )
+
+    // 2) Recovered response before drain.
+    XCTAssertNotNil(
+      box.payload,
+      "\(entryPointName) must recover a payload through the capture plan while the probe drains"
+    )
+
+    // 3) Bounded, deterministic drain barrier, then release assertions.
+    wait(for: [drained], timeout: 6)
+    guard case .idle = currentMainThreadBusyState() else {
+      return XCTFail("expected the runner to be idle once the abandoned \(entryPointName) probe drained")
+    }
+    XCTAssertFalse(
+      hasAbandonedMainThreadWork(),
+      "the drained probe must release the main thread for \(entryPointName)"
+    )
+  }
+
+  func testBoundedSystemModalProbeTimeoutRecoversThenReleasesOnDrain() {
+    assertBoundedSystemModalProbeTimeoutRecoversThenReleasesOnDrain(entryPointName: "snapshotFast") {
+      target, options in
+      try self.snapshotFast(app: target, options: options)
+    }
+  }
+
+  func testBoundedSystemModalProbeTimeoutRecoversThenReleasesOnDrainForSnapshotRaw() {
+    assertBoundedSystemModalProbeTimeoutRecoversThenReleasesOnDrain(entryPointName: "snapshotRaw") {
+      target, options in
+      try self.snapshotRaw(app: target, options: options)
+    }
+  }
+#endif
+
+  func testDispatchRecoverySkipsBookkeepingWhileXCTestChannelOccupied() {
+    // The #1244 recovery shape: the modal probe abandoned an XCTest query that is still grinding on
+    // main, the capture recovered independently, and its response is ready. The recovery loop must
+    // return it without re-entering the main queue for recorded-failure/retry bookkeeping (that hop
+    // would block behind the abandoned query and re-stall the command), and a later command must
+    // still see the runner busy until the abandoned work drains. Removing the guard regresses this.
+    let command = try! JSONDecoder().decode(
+      Command.self,
+      from: Data(#"{"command":"snapshot","commandId":"recovery-guard"}"#.utf8)
+    )
+    let recovered = Response(ok: false, error: .targetAppUnavailable(bundleId: nil))
+
+    setAbandonedMainThreadWork(1)
+    defer { setAbandonedMainThreadWork(0) }
+    guard case .busy = currentMainThreadBusyState() else {
+      return XCTFail("expected RUNNER_BUSY while abandoned XCTest work is outstanding")
+    }
+
+    var occupiedCalls = 0
+    let occupied = try! executeDispatchedWithRecovery(command: command) {
+      occupiedCalls += 1
+      return recovered
+    }
+    XCTAssertEqual(occupiedCalls, 1, "recovered response must not retry behind abandoned XCTest work")
+    XCTAssertEqual(occupied.ok, false)
+
+    setAbandonedMainThreadWork(0)
+    guard case .idle = currentMainThreadBusyState() else {
+      return XCTFail("runner should be idle once the abandoned work drained")
+    }
+    var drainedCalls = 0
+    _ = try! executeDispatchedWithRecovery(command: command) {
+      drainedCalls += 1
+      return recovered
+    }
+    XCTAssertEqual(drainedCalls, 2, "with the channel free the read-only retry runs once")
+  }
+
+  private func setAbandonedMainThreadWork(_ count: Int) {
+    mainThreadWorkLock.lock()
+    abandonedMainThreadWorkCount = count
+    abandonedMainThreadWorkSince = count > 0 ? Date(timeIntervalSinceNow: -1) : nil
+    mainThreadWorkLock.unlock()
+  }
+}
+#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotTimingTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotTimingTests.swift
new file mode 100644
index 0000000000..24fdcfaa46
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotTimingTests.swift
@@ -0,0 +1,78 @@
+import Foundation
+import XCTest
+
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS
+extension RunnerTests {
+  func testXCTestPenaltyDecisionSeparatesAcquisitionAndPresentation() {
+    let slowPresentation = SnapshotBackendAttempt(
+      outcome: .noCapture,
+      timing: SnapshotCaptureTiming(acquisitionMs: 100, presentationMs: 4_000)
+    )
+    XCTAssertNil(
+      Self.snapshotXCTestPenaltyReason(
+        kind: .recursiveTree,
+        attempt: slowPresentation,
+        slowThresholdMs: 3_000
+      )
+    )
+
+    let slowAcquisition = SnapshotBackendAttempt(
+      outcome: .noCapture,
+      timing: SnapshotCaptureTiming(acquisitionMs: 3_001, presentationMs: 100)
+    )
+    XCTAssertEqual(
+      Self.snapshotXCTestPenaltyReason(
+        kind: .recursiveTree,
+        attempt: slowAcquisition,
+        slowThresholdMs: 3_000
+      ),
+      "slow_tree_capture_3001ms"
+    )
+
+    let timeout = SnapshotCaptureFailure(
+      code: Self.xCTestSnapshotTimeoutCode,
+      message: "test timeout",
+      hint: "test"
+    )
+    let acquisitionFailure = SnapshotBackendAttempt(
+      outcome: .failed(timeout, phase: .acquisition),
+      timing: SnapshotCaptureTiming(acquisitionMs: 100, presentationMs: 100)
+    )
+    XCTAssertEqual(
+      Self.snapshotXCTestPenaltyReason(
+        kind: .recursiveTree,
+        attempt: acquisitionFailure,
+        slowThresholdMs: 3_000
+      ),
+      "tree_backend_timeout"
+    )
+
+    let presentationFailure = SnapshotBackendAttempt(
+      outcome: .failed(timeout, phase: .presentation),
+      timing: SnapshotCaptureTiming(acquisitionMs: 100, presentationMs: 100)
+    )
+    XCTAssertNil(
+      Self.snapshotXCTestPenaltyReason(
+        kind: .recursiveTree,
+        attempt: presentationFailure,
+        slowThresholdMs: 3_000
+      )
+    )
+  }
+
+  func testSnapshotPhaseTimerReportsAcquisitionAndPresentationSeparately() {
+    var now = Date(timeIntervalSinceReferenceDate: 100)
+    var timer = SnapshotPhaseTimer(now: { now })
+
+    _ = timer.measure(.acquisition) {
+      now = now.addingTimeInterval(2)
+    }
+    _ = timer.measure(.presentation) {
+      now = now.addingTimeInterval(5)
+    }
+
+    XCTAssertEqual(timer.timing.acquisitionMs, 2_000, accuracy: 0.001)
+    XCTAssertEqual(timer.timing.presentationMs, 5_000, accuracy: 0.001)
+  }
+}
+#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SynthesizedGesturePolicyTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SynthesizedGesturePolicyTests.swift
new file mode 100644
index 0000000000..acb3d9b032
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SynthesizedGesturePolicyTests.swift
@@ -0,0 +1,105 @@
+import XCTest
+
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS && os(iOS)
+extension RunnerTests {
+  func testSynthesizedGesturePolicyMarkerWritesOncePerKindUntilTheDecisionChanges() {
+    var written: [String] = []
+    runnerMarkerWriter = { written.append($0) }
+    defer {
+      runnerMarkerWriter = { NSLog("%@", $0) }
+      invalidateCachedTarget(reason: "unit_test_cleanup")
+    }
+    logSynthesizedGesturePolicyDecision(kind: .coordinateTap, context: nil, fallbackAttempted: false)
+    logSynthesizedGesturePolicyDecision(kind: .coordinateTap, context: nil, fallbackAttempted: false)
+    XCTAssertEqual(written.count, 1, "a repeated decision writes no second line")
+    logSynthesizedGesturePolicyDecision(kind: .scroll, context: nil, fallbackAttempted: false)
+    XCTAssertEqual(written.count, 2, "each gesture kind states its own decision")
+    logSynthesizedGesturePolicyDecision(kind: .coordinateTap, context: nil, fallbackAttempted: true)
+    XCTAssertEqual(written.count, 3, "a changed decision writes a new line")
+    resetTargetBoundState()
+    logSynthesizedGesturePolicyDecision(kind: .coordinateTap, context: nil, fallbackAttempted: true)
+    XCTAssertEqual(written.count, 4, "a rebind states the same decision once more")
+  }
+}
+#endif
+
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS
+extension RunnerTests {
+  func testSynthesizedFallbackPolicyRequiresPrivateSynthesisForScrollWhenAxUnavailableOrUnknown() {
+    XCTAssertFalse(
+      SynthesizedFallbackPolicy.privateSynthesisRequired
+        .allowsXCTestCoordinateFallback(accessibilityHealth: .unavailable)
+    )
+    XCTAssertFalse(
+      SynthesizedFallbackPolicy.privateSynthesisRequired
+        .allowsXCTestCoordinateFallback(accessibilityHealth: .unknown)
+    )
+    XCTAssertFalse(
+      SynthesizedFallbackPolicy.privateSynthesisRequired
+        .allowsXCTestCoordinateFallback(accessibilityHealth: .healthy)
+    )
+  }
+
+  func testSynthesizedDragCoordinateFallbackAllowsUnknownButNotUnavailableAccessibility() {
+    XCTAssertTrue(
+      SynthesizedFallbackPolicy.xctestCoordinateWhenAccessibilityAvailable
+        .allowsXCTestCoordinateFallback(accessibilityHealth: .healthy)
+    )
+    XCTAssertFalse(
+      SynthesizedFallbackPolicy.xctestCoordinateWhenAccessibilityAvailable
+        .allowsXCTestCoordinateFallback(accessibilityHealth: .unavailable)
+    )
+    XCTAssertTrue(
+      SynthesizedFallbackPolicy.xctestCoordinateWhenAccessibilityAvailable
+        .allowsXCTestCoordinateFallback(accessibilityHealth: .unknown)
+    )
+  }
+
+  /// Keyboard-policy semantics only. Which command gets which policy is the table below; a probe
+  /// that is merely permitted still costs a live AX fetch, so the two questions stay separate.
+  func testSynthesizedKeyboardPolicyAllowsProbeOnlyWhenAccessibilityPermitsIt() {
+    XCTAssertFalse(
+      SynthesizedKeyboardPolicy.whenAccessibilityHealthy
+        .allowsProbe(accessibilityHealth: .unknown)
+    )
+    XCTAssertTrue(
+      SynthesizedKeyboardPolicy.requiredWhenAvailable
+        .allowsProbe(accessibilityHealth: .unknown)
+    )
+    XCTAssertFalse(
+      SynthesizedKeyboardPolicy.requiredWhenAvailable
+        .allowsProbe(accessibilityHealth: .unavailable)
+    )
+  }
+
+  func testSynthesizedGesturePoliciesMatchCommandContracts() {
+    XCTAssertEqual(
+      synthesizedGesturePolicy(.coordinateTap),
+      SynthesizedGesturePolicy(
+        keyboardPolicy: .never,
+        fallbackPolicy: .xctestCoordinateAllowed
+      )
+    )
+    XCTAssertEqual(
+      synthesizedGesturePolicy(.scroll),
+      SynthesizedGesturePolicy(
+        keyboardPolicy: .requiredWhenAvailable,
+        fallbackPolicy: .privateSynthesisRequired
+      )
+    )
+    XCTAssertEqual(
+      synthesizedGesturePolicy(.synthesizedDrag),
+      SynthesizedGesturePolicy(
+        keyboardPolicy: .requiredWhenAvailable,
+        fallbackPolicy: .xctestCoordinateWhenAccessibilityAvailable
+      )
+    )
+  }
+
+  func testCoordinateTapTextInputProbeSkipsPenalizedXCTestChannel() {
+    XCTAssertTrue(shouldProbeCoordinateTapTextInput(xCTestChannelPenalized: false))
+    XCTAssertFalse(shouldProbeCoordinateTapTextInput(xCTestChannelPenalized: true))
+  }
+
+}
+#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SystemSurfaceHostPolicyTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SystemSurfaceHostPolicyTests.swift
new file mode 100644
index 0000000000..e16aac6e3b
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SystemSurfaceHostPolicyTests.swift
@@ -0,0 +1,50 @@
+import Foundation
+
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS
+import XCTest
+
+private struct SystemSurfaceHostFixture: Decodable {
+  struct Host: Decodable {
+    let bundleId: String
+    let kind: String
+  }
+  let hosts: [Host]
+}
+
+extension RunnerTests {
+  func testSystemSurfaceHostRegistryMirrorsGoldenFixture() throws {
+    let fixtureURL = URL(fileURLWithPath: #filePath)
+      .deletingLastPathComponent() // UnitTests
+      .deletingLastPathComponent() // AgentDeviceRunnerUITests
+      .deletingLastPathComponent() // AgentDeviceRunner
+      .deletingLastPathComponent() // runner
+      .deletingLastPathComponent() // apple
+      .deletingLastPathComponent() // repo root
+      .appendingPathComponent("contracts")
+      .appendingPathComponent("fixtures")
+      .appendingPathComponent("ios-system-surface-hosts.json")
+    let fixture = try JSONDecoder().decode(
+      SystemSurfaceHostFixture.self,
+      from: Data(contentsOf: fixtureURL)
+    )
+    let registry = SystemSurfaceHostRegistry.hosts.map { [$0.bundleId, $0.kind.rawValue] }
+    let golden = fixture.hosts.map { [$0.bundleId, $0.kind] }
+    XCTAssertEqual(registry, golden, "SystemSurfaceHostRegistry drifted from the golden fixture")
+  }
+
+  func testSystemSurfaceHostRegistryRecognizesRegisteredHosts() {
+    XCTAssertTrue(SystemSurfaceHostRegistry.isSystemSurfaceHost("com.apple.SafariViewService"))
+    XCTAssertTrue(SystemSurfaceHostRegistry.isSystemSurfaceHost("com.apple.PassbookUIService"))
+    XCTAssertFalse(SystemSurfaceHostRegistry.isSystemSurfaceHost("com.example.app"))
+    XCTAssertFalse(SystemSurfaceHostRegistry.isSystemSurfaceHost(nil))
+    XCTAssertEqual(
+      SystemSurfaceHostRegistry.host(forBundleId: "com.apple.SafariViewService")?.kind,
+      .webAuth
+    )
+    XCTAssertEqual(
+      SystemSurfaceHostRegistry.host(forBundleId: "com.apple.PassbookUIService")?.kind,
+      .payment
+    )
+  }
+}
+#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+TapPointPolicyTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+TapPointPolicyTests.swift
new file mode 100644
index 0000000000..791b1b2530
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+TapPointPolicyTests.swift
@@ -0,0 +1,52 @@
+import XCTest
+
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS
+private struct TapPointPolicyFixture: Decodable {
+  struct Frame: Decodable {
+    let x: Double
+    let y: Double
+    let width: Double
+    let height: Double
+
+    var cgRect: CGRect {
+      CGRect(x: x, y: y, width: width, height: height)
+    }
+  }
+
+  let name: String
+  let elementFrame: Frame
+  let windowFrame: Frame
+  let allowed: Bool
+}
+
+extension RunnerTests {
+  // Golden parity table (ADR 0011 Layer 2): every case in
+  // contracts/fixtures/tap-point-policy.json must agree with the vitest twin
+  // (tap-point-policy-parity.test.ts). Add cases there, never fork the rule.
+  func testTapPointPolicyMatchesGoldenParityTable() throws {
+    let fixtureURL = URL(fileURLWithPath: #filePath)
+      .deletingLastPathComponent() // UnitTests
+      .deletingLastPathComponent() // AgentDeviceRunnerUITests
+      .deletingLastPathComponent() // AgentDeviceRunner
+      .deletingLastPathComponent() // runner
+      .deletingLastPathComponent() // apple
+      .deletingLastPathComponent() // repo root
+      .appendingPathComponent("contracts")
+      .appendingPathComponent("fixtures")
+      .appendingPathComponent("tap-point-policy.json")
+    let data = try Data(contentsOf: fixtureURL)
+    let cases = try JSONDecoder().decode([TapPointPolicyFixture].self, from: data)
+    XCTAssertFalse(cases.isEmpty, "parity table must not be empty")
+    for fixture in cases {
+      XCTAssertEqual(
+        TapPointPolicy.isAllowed(
+          elementFrame: fixture.elementFrame.cgRect,
+          windowFrame: fixture.windowFrame.cgRect
+        ),
+        fixture.allowed,
+        fixture.name
+      )
+    }
+  }
+}
+#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+TextInputCandidatePolicyTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+TextInputCandidatePolicyTests.swift
new file mode 100644
index 0000000000..ec3201275b
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+TextInputCandidatePolicyTests.swift
@@ -0,0 +1,33 @@
+import CoreGraphics
+import XCTest
+
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS
+extension RunnerTests {
+  func testCoordinateTextInputCandidateMustBeEnabledAndContainTheTouchPoint() {
+    let frame = CGRect(x: 10, y: 20, width: 100, height: 40)
+    let point = CGPoint(x: 50, y: 40)
+
+    XCTAssertTrue(
+      isCoordinateTextInputCandidate(
+        enabled: true,
+        frame: frame,
+        point: point
+      )
+    )
+    XCTAssertFalse(
+      isCoordinateTextInputCandidate(
+        enabled: false,
+        frame: frame,
+        point: point
+      )
+    )
+    XCTAssertFalse(
+      isCoordinateTextInputCandidate(
+        enabled: true,
+        frame: frame,
+        point: CGPoint(x: 200, y: 200)
+      )
+    )
+  }
+}
+#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+TransportTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+TransportTests.swift
new file mode 100644
index 0000000000..42c0f53875
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+TransportTests.swift
@@ -0,0 +1,43 @@
+import XCTest
+import Network
+
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS
+extension RunnerTests {
+  func testDuplicateCommandIdCoalescesOntoInFlightExecution() throws {
+    let command = try JSONDecoder().decode(
+      Command.self,
+      from: Data(#"{"command":"snapshot","commandId":"snapshot-coalesce"}"#.utf8)
+    )
+    var primaryData: Data?
+    var waiterData: Data?
+    defer {
+      inFlightCommandIds.removeAll()
+      inFlightCommandWaiters.removeAll()
+    }
+
+    XCTAssertFalse(
+      attachToInFlightCommandIfNeeded(command: command) { result in
+        primaryData = result.data
+      }
+    )
+    XCTAssertTrue(
+      attachToInFlightCommandIfNeeded(command: command) { result in
+        waiterData = result.data
+      }
+    )
+
+    let delivered = Data("single-result".utf8)
+    deliverCommandResult(
+      command: command,
+      result: (delivered, false)
+    ) { result in
+      primaryData = result.data
+    }
+
+    XCTAssertEqual(primaryData, delivered)
+    XCTAssertEqual(waiterData, delivered)
+    XCTAssertFalse(inFlightCommandIds.contains("snapshot-coalesce"))
+    XCTAssertNil(inFlightCommandWaiters["snapshot-coalesce"])
+  }
+}
+#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+TvRemoteTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+TvRemoteTests.swift
new file mode 100644
index 0000000000..3cdcc89651
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+TvRemoteTests.swift
@@ -0,0 +1,25 @@
+import XCTest
+
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS
+extension RunnerTests {
+  func testTvRemoteButtonMappingAcceptsSupportedNamesAndRejectsUnknown() {
+    let supported = [
+      ("select", "select"),
+      ("SELECT", "select"),
+      ("menu", "menu"),
+      ("home", "home"),
+      ("up", "up"),
+      ("down", "down"),
+      ("left", "left"),
+      ("right", "right"),
+    ]
+    for (raw, expected) in supported {
+      XCTAssertEqual(tvRemoteButton(from: raw)?.rawValue, expected)
+    }
+
+    for raw in [String?(nil), "", "volumeUp", "select "] {
+      XCTAssertNil(tvRemoteButton(from: raw))
+    }
+  }
+}
+#endif
diff --git a/apple/runner/README.md b/apple/runner/README.md
index 4a657b6ce8..d899f9cfce 100644
--- a/apple/runner/README.md
+++ b/apple/runner/README.md
@@ -33,6 +33,8 @@ Protocol and maintenance references:
 - `RunnerTests+Snapshot.swift`: fast/raw snapshot builders and include/filter helpers.
 - `RunnerTests+SystemModal.swift`: SpringBoard/system modal detection and modal snapshot shaping.
 - `RunnerTests+ScreenRecorder.swift`: nested `ScreenRecorder` implementation.
+- `UnitTests/RunnerTests+<Source>Tests.swift`: the `AGENT_DEVICE_RUNNER_UNIT_TESTS` tests for each
+  source file. The packaged runner source omits this directory.
 
 ## Snapshot Strategy
 
diff --git a/packages/contracts/src/scroll-gesture.test.ts b/packages/contracts/src/scroll-gesture.test.ts
index 1c5f700560..de068535ad 100644
--- a/packages/contracts/src/scroll-gesture.test.ts
+++ b/packages/contracts/src/scroll-gesture.test.ts
@@ -60,8 +60,8 @@ test('buildInPageSwipeGesturePlan truncates percentage coordinates on odd viewpo
 
 // Cross-language parity table: every case in contracts/fixtures/scroll-gesture.json is asserted
 // here AND by the Swift port (runnerScrollGesturePlan in RunnerTests+ScrollGesture.swift, gated
-// XCTest in the same file). Add vectors to the table, never to one suite — drift on either side
-// turns CI red without a simulator.
+// XCTest in UnitTests/RunnerTests+ScrollGestureTests.swift). Add vectors to the table, never to
+// one suite — drift on either side turns CI red without a simulator.
 type ScrollGestureFixture = {
   constants: {
     defaultIosScrollAmount: number;
@@ -210,7 +210,8 @@ test('clampGestureCoordinate returns the lower bound for non-finite coordinates'
 
 // Golden parity table: the SAME JSON is asserted against the Swift twin
 // (ScrollViewportPolicy in apple/runner/AgentDeviceRunner/
-// AgentDeviceRunnerUITests/RunnerScrollViewportPolicy.swift, gated XCTest in the same file), so
+// AgentDeviceRunnerUITests/RunnerScrollViewportPolicy.swift, gated XCTest in
+// UnitTests/RunnerTests+ScrollViewportPolicyTests.swift), so
 // a clip that drifts between the iOS runner and the Android/TS owner turns CI red on whichever
 // side changed, without a simulator.
 
diff --git a/packages/contracts/src/snapshot-tap-point-policy.test.ts b/packages/contracts/src/snapshot-tap-point-policy.test.ts
index 9c93995319..526759a786 100644
--- a/packages/contracts/src/snapshot-tap-point-policy.test.ts
+++ b/packages/contracts/src/snapshot-tap-point-policy.test.ts
@@ -7,9 +7,10 @@ import type { Rect } from '@agent-device/kernel/snapshot';
 
 // ADR 0011 Layer 2 golden parity table: the SAME JSON is asserted against the
 // Swift twin (TapPointPolicy in apple/runner/AgentDeviceRunner/
-// AgentDeviceRunnerUITests/RunnerTapPointPolicy.swift, gated XCTest in the
-// same file), so drift between the runner's ELEMENT_OFFSCREEN guard and the
-// runtime's offscreen rule turns CI red on whichever side changed.
+// AgentDeviceRunnerUITests/RunnerTapPointPolicy.swift, gated XCTest in
+// UnitTests/RunnerTests+TapPointPolicyTests.swift), so drift between the
+// runner's ELEMENT_OFFSCREEN guard and the runtime's offscreen rule turns CI
+// red on whichever side changed.
 //
 // Scope: the table proves the GEOMETRIC rule only — element-frame center
 // inside the window frame, edges inclusive, empty frame fails open. The
diff --git a/scripts/__tests__/xctest-declarations.test.ts b/scripts/__tests__/xctest-declarations.test.ts
index a56e7eb4ed..70edbdd68b 100644
--- a/scripts/__tests__/xctest-declarations.test.ts
+++ b/scripts/__tests__/xctest-declarations.test.ts
@@ -55,8 +55,8 @@ describe('the declaration scan', () => {
   });
 
   test('reads a file whose name does not start with RunnerTests', () => {
-    // RunnerTapPointPolicy.swift is the real instance: the synchronized-root-group project
-    // compiles every .swift in the directory, so file naming carries no membership meaning.
+    // The synchronized-root-group project compiles every .swift in the directory, so file
+    // naming carries no membership meaning.
     expect(
       parseDeclaredTests(TARGET, [
         {
diff --git a/scripts/__tests__/xctest-selection.test.ts b/scripts/__tests__/xctest-selection.test.ts
index 177b5726e0..20f282fdea 100644
--- a/scripts/__tests__/xctest-selection.test.ts
+++ b/scripts/__tests__/xctest-selection.test.ts
@@ -113,7 +113,7 @@ describe('the real tree', () => {
     // own regex, because the Xcode project uses a PBXFileSystemSynchronizedRootGroup — every
     // .swift file in it is a member. Reusing the check's own file filter would make this
     // tautological, and a name-based filter is exactly the bug it caught
-    // (RunnerTapPointPolicy.swift declares a test and does not start with "RunnerTests").
+    // (RunnerTapPointPolicy.swift declared a test and does not start with "RunnerTests").
     const directory = path.join(repoRoot, RUNNER_TESTS_DIR);
     const countAddressableMethods = (sourceDirectory: string): number =>
       fs.readdirSync(sourceDirectory, { withFileTypes: true }).reduce((total, entry) => {
diff --git a/scripts/xctest-declarations.ts b/scripts/xctest-declarations.ts
index 0ab4caf1d3..59ef490648 100644
--- a/scripts/xctest-declarations.ts
+++ b/scripts/xctest-declarations.ts
@@ -14,9 +14,8 @@ import { activeSource, PLATFORMS, type Platform } from './swift-conditional-comp
 export const RUNNER_TESTS_DIR = 'apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests';
 
 // Every .swift file below the target directory is a member: the Xcode project uses a
-// PBXFileSystemSynchronizedRootGroup, so membership is the directory, not a file list. A
-// `RunnerTests*` name filter would miss RunnerTapPointPolicy.swift, which declares a real
-// addressable test inside `extension RunnerTests`.
+// PBXFileSystemSynchronizedRootGroup, so membership is the directory, not a file list, and a
+// file's name says nothing about whether it declares addressable tests.
 const SWIFT_SOURCE = /\.swift$/;
 
 // One ordered pass over the source. A column-0 type declaration moves the enclosing type;

From f356394d0028f6b4de299cd7b23c6b46871ec7f8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 24 Sep 2026 07:44:48 +0200
Subject: [PATCH 071/132] refactor(move): split
 RunnerTests+CommandExecution.swift along command families (#2855)

The 1,985-line file becomes six, each under 1,000 lines, by moving whole
declarations:

- CommandDispatch: executeAccepted through executeOnMain, the dispatched
  recovery loop, target preparation, activation preflight, and recorded-failure
  conversion.
- CommandExecution: the prepared-command switch (executeOnMainPrepared).
- GestureExecution: gesture timing and gesture response building.
- ScrollDragExecution: scroll and drag execution and their refusals.
- TypeExecution: executeTypeCommand.
- SnapshotExecution: snapshot dispatch, preparation, and post-capture marks.

Its tests split the same way, and the dispatch recovery test follows
executeDispatchedWithRecovery into CommandDispatchTests. The shared test
helpers move beside what they drive: execute(command:) to TransportTests and
runnerCommandFixture to ModelsTests. Declarations now read across files widen
from private to internal.

Closes #2792

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .../RunnerTests+CommandDispatch.swift         |  620 ++++++++
 .../RunnerTests+CommandExecution.swift        | 1345 -----------------
 .../RunnerTests+GestureExecution.swift        |  165 ++
 .../RunnerTests+ScrollDragExecution.swift     |  287 ++++
 .../RunnerTests+SnapshotExecution.swift       |  151 ++
 .../RunnerTests+TypeExecution.swift           |  142 ++
 .../RunnerTests+CommandDispatchTests.swift    |  409 +++++
 .../RunnerTests+CommandExecutionTests.swift   |  595 --------
 .../RunnerTests+GestureExecutionTests.swift   |   73 +
 .../UnitTests/RunnerTests+ModelsTests.swift   |    4 +
 ...RunnerTests+ScrollDragExecutionTests.swift |   72 +
 .../RunnerTests+SnapshotExecutionTests.swift  |   84 +
 .../UnitTests/RunnerTests+SnapshotTests.swift |   45 -
 .../RunnerTests+TransportTests.swift          |   28 +
 apple/runner/README.md                        |    7 +-
 15 files changed, 2041 insertions(+), 1986 deletions(-)
 create mode 100644 apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandDispatch.swift
 create mode 100644 apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+GestureExecution.swift
 create mode 100644 apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+ScrollDragExecution.swift
 create mode 100644 apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotExecution.swift
 create mode 100644 apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+TypeExecution.swift
 create mode 100644 apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+CommandDispatchTests.swift
 create mode 100644 apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+GestureExecutionTests.swift
 create mode 100644 apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+ScrollDragExecutionTests.swift
 create mode 100644 apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotExecutionTests.swift

diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandDispatch.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandDispatch.swift
new file mode 100644
index 0000000000..a791984dc1
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandDispatch.swift
@@ -0,0 +1,620 @@
+import XCTest
+import AgentDeviceSnapshotPresentation
+
+extension RunnerTests {
+  // MARK: - Main Thread Dispatch
+
+  func executeAccepted(command: Command) throws -> Response {
+    commandJournal.start(command: command)
+    pendingTargetActivation = nil
+    do {
+      let response = try executeDispatched(command: command)
+      commandJournal.finish(command: command, response: response)
+      guard let fact = pendingTargetActivation else { return response }
+      // Stamped after `finish`, like the uptime anchor: a journal-replayed result carries no
+      // activation fact, because the command that paid for it is the one being replayed, not one
+      // that just repaired foreground (#2682).
+      pendingTargetActivation = nil
+      return response.stampingTargetActivation(fact)
+    } catch {
+      pendingTargetActivation = nil
+      commandJournal.fail(command: command, error: error)
+      throw error
+    }
+  }
+
+  func executeStatus(command: Command) -> Response {
+    guard
+      let statusCommandId = command.statusCommandId?.trimmedNonEmpty
+    else {
+      return Response(
+        ok: false,
+        error: ErrorPayload(
+          code: "INVALID_ARGS",
+          message: "status requires statusCommandId",
+          hint: "Set statusCommandId to the commandId of the runner command to inspect."
+        )
+      )
+    }
+    return Response(ok: true, data: commandJournal.status(normalizedCommandId: statusCommandId))
+  }
+
+  func executeUptime() -> Response {
+    // Placeholder value: the transport layer (jsonResponse) overwrites currentUptimeMs with a
+    // fresher send-time stamp on every ok response; kept so direct callers still get a value.
+    Response(
+      ok: true,
+      data: DataPayload(currentUptimeMs: currentUptimeMs())
+    )
+  }
+
+  struct ActiveCommandContext {
+    let app: XCUIApplication
+    /// Set when `app` is a system surface served in place over the still-bound session app (#2438).
+    var systemSurface: SystemSurfaceHost? = nil
+  }
+
+  enum ActiveCommandPreparation {
+    case response(Response)
+    case context(ActiveCommandContext)
+  }
+
+  private func runnerBusyResponse(command: Command, abandonedForSeconds: TimeInterval) -> Response {
+    NSLog(
+      "AGENT_DEVICE_RUNNER_BUSY command=%@ commandId=%@ abandonedForSeconds=%.1f",
+      command.command.rawValue,
+      command.commandId ?? "",
+      abandonedForSeconds
+    )
+    return Response(
+      ok: false,
+      error: ErrorPayload(
+        code: "RUNNER_BUSY",
+        message:
+          "The iOS runner is still finishing a previous command that exceeded its execution watchdog (usually an accessibility capture on a heavy or animating screen).",
+        hint:
+          "Wait a few seconds and retry. If snapshots keep failing on this screen, use screenshot as visual truth and interact by coordinates, or navigate to another screen."
+      )
+    )
+  }
+
+  private func runnerWedgedResponse(command: Command, abandonedForSeconds: TimeInterval) -> Response {
+    NSLog(
+      "AGENT_DEVICE_RUNNER_WEDGED command=%@ commandId=%@ abandonedForSeconds=%.1f",
+      command.command.rawValue,
+      command.commandId ?? "",
+      abandonedForSeconds
+    )
+    return Response(
+      ok: false,
+      error: ErrorPayload(
+        code: "RUNNER_WEDGED",
+        message:
+          "The iOS runner main thread has been stuck in abandoned work for \(Int(abandonedForSeconds)) seconds and cannot recover on its own.",
+        hint:
+          "The runner session will be restarted. Retry the command after the restart; if this screen keeps wedging captures, use screenshot as visual truth and interact by coordinates."
+      )
+    )
+  }
+
+  private func runnerUnavailableResponse(command: Command) -> Response? {
+    switch currentMainThreadBusyState() {
+    case .idle:
+      return nil
+    case .busy(let abandonedForSeconds):
+      return runnerBusyResponse(command: command, abandonedForSeconds: abandonedForSeconds)
+    case .wedged(let abandonedForSeconds):
+      return runnerWedgedResponse(command: command, abandonedForSeconds: abandonedForSeconds)
+    }
+  }
+
+  func executeDispatched(command: Command) throws -> Response {
+    // XCTest work cannot be cancelled mid-flight: once the watchdog abandons a main-queue
+    // block, queueing more main-thread commands behind it only buries the runner deeper.
+    // Refuse fast instead so the daemon backs off while the abandoned work drains; past the
+    // wedge threshold, escalate so the daemon recycles this runner (#1105).
+    if let unavailable = runnerUnavailableResponse(command: command) {
+      return unavailable
+    }
+    let alertDeadline = command.command == .alert
+      ? Date().addingTimeInterval(Self.alertCommandTimeout(timeoutMs: command.timeoutMs))
+      : nil
+    // Resolve this before the command's outer main-thread block. If the bounded probe abandons
+    // slow XCTest enumeration, return the established recoverable response instead of queueing
+    // command preparation behind work that may outlive the 30-second command watchdog.
+    let routeToSpringboard = shouldRouteToSpringboardBlockingSystemModal(command)
+    if let unavailable = runnerUnavailableResponse(command: command) {
+      return unavailable
+    }
+    if command.command == .snapshot {
+      return try executeSnapshotDispatched(command: command)
+    }
+    if command.command == .alert, let deadline = alertDeadline {
+      return try runMainThreadWork(
+        "command_execution",
+        timeout: max(0.001, deadline.timeIntervalSinceNow),
+        timeoutError: mainThreadExecutionTimeoutError
+      ) {
+        try self.executeOnMainSafely(
+          command: command,
+          alertDeadline: deadline,
+          routeToSpringboard: routeToSpringboard
+        )
+      }
+    }
+    return try runMainThreadWork(
+      "command_execution",
+      timeout: mainThreadExecutionTimeout,
+      timeoutError: mainThreadExecutionTimeoutError
+    ) {
+      try self.executeOnMainSafely(command: command, routeToSpringboard: routeToSpringboard)
+    }
+  }
+
+  // MARK: - Command Handling
+
+  private func executeOnMainSafely(
+    command: Command,
+    alertDeadline: Date? = nil,
+    routeToSpringboard: Bool
+  ) throws -> Response {
+    var hasRetried = false
+    while true {
+      var response: Response?
+      var swiftError: Error?
+      let failureCountBefore = currentXCTestFailureCount()
+      let exceptionMessage = RunnerObjCExceptionCatcher.catchException({
+        do {
+          response = try self.executeOnMain(
+            command: command,
+            alertDeadline: alertDeadline,
+            routeToSpringboard: routeToSpringboard
+          )
+        } catch {
+          swiftError = error
+        }
+      })
+
+      if let exceptionMessage {
+        invalidateCachedTarget(reason: "objc_exception")
+        if !hasRetried, shouldRetryException(command, message: exceptionMessage) {
+          NSLog(
+            "AGENT_DEVICE_RUNNER_RETRY command=%@ reason=objc_exception",
+            command.command.rawValue
+          )
+          hasRetried = true
+          sleepFor(retryCooldown)
+          continue
+        }
+        throw NSError(
+          domain: RunnerErrorDomain.exception,
+          code: RunnerErrorCode.objcException,
+          userInfo: [NSLocalizedDescriptionKey: exceptionMessage]
+        )
+      }
+      if let swiftError {
+        throw swiftError
+      }
+      guard let response else {
+        throw NSError(
+          domain: RunnerErrorDomain.general,
+          code: RunnerErrorCode.commandReturnedNoResponse,
+          userInfo: [NSLocalizedDescriptionKey: "command returned no response"]
+        )
+      }
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS
+      // #1605 merge gate: the REAL gesture already executed above; recording a
+      // production-shaped issue here makes the per-command failure-count
+      // conversion below fire exactly as in the field (bsky-24: activation
+      // lands, bookkeeping records a failure). Compiled out of production.
+      if consumeInjectedTapRecordedFailureForTesting(command: command.command) {
+        record(
+          XCTIssue(
+            type: .assertionFailure,
+            compactDescription: "Injected tap recorded-failure (#1605 corroboration merge gate)"
+          )
+        )
+      }
+#endif
+      if didRecordXCTestFailure(since: failureCountBefore),
+        let failureResponse = xctestRecordedFailureResponse(command: command, response: response)
+      {
+        invalidateCachedTarget(reason: "xctest_recorded_failure")
+        return failureResponse
+      }
+      if !hasRetried, shouldRetryCommand(command), shouldRetryResponse(response) {
+        NSLog(
+          "AGENT_DEVICE_RUNNER_RETRY command=%@ reason=response_unavailable",
+          command.command.rawValue
+        )
+        hasRetried = true
+        invalidateCachedTarget(reason: "response_unavailable")
+        sleepFor(retryCooldown)
+        continue
+      }
+      return response
+    }
+  }
+
+  /// The dispatched snapshot recovery loop: read-only retry + XCTest-recorded-failure invalidation,
+  /// matching what `executeOnMainSafely` gives the generic path. `perform` runs the capture and its
+  /// own bounded main-thread work.
+  func executeDispatchedWithRecovery(
+    command: Command,
+    perform: () throws -> Response
+  ) throws -> Response {
+    var hasRetried = false
+    while true {
+      let failureCountBefore = try runMainThreadWork(
+        "recorded_failure_count",
+        timeout: mainThreadExecutionTimeout,
+        timeoutError: mainThreadExecutionTimeoutError
+      ) {
+        self.currentXCTestFailureCount()
+      }
+      let response = try perform()
+      // Recovered independently — re-entering main for bookkeeping would queue behind the still-
+      // abandoned XCTest query and re-stall the command (#1244), so skip it until that work drains.
+      if hasAbandonedMainThreadWork() {
+        NSLog(
+          "AGENT_DEVICE_RUNNER_DISPATCH_RECOVERY_SKIPPED_XCTEST_OCCUPIED command=%@",
+          command.command.rawValue
+        )
+        return response
+      }
+      let recordedFailureResponse = try runMainThreadWork(
+        "recorded_failure_count",
+        timeout: mainThreadExecutionTimeout,
+        timeoutError: mainThreadExecutionTimeoutError
+      ) {
+        self.didRecordXCTestFailure(since: failureCountBefore)
+          ? self.xctestRecordedFailureResponse(command: command, response: response)
+          : nil
+      }
+      if let recordedFailureResponse {
+        try runMainThreadWork(
+          "target_invalidation",
+          timeout: mainThreadExecutionTimeout,
+          timeoutError: mainThreadExecutionTimeoutError
+        ) {
+          self.invalidateCachedTarget(reason: "xctest_recorded_failure")
+        }
+        return recordedFailureResponse
+      }
+      if !hasRetried, shouldRetryCommand(command), shouldRetryResponse(response) {
+        NSLog(
+          "AGENT_DEVICE_RUNNER_RETRY command=%@ reason=response_unavailable",
+          command.command.rawValue
+        )
+        hasRetried = true
+        try runMainThreadWork(
+          "target_invalidation",
+          timeout: mainThreadExecutionTimeout,
+          timeoutError: mainThreadExecutionTimeoutError
+        ) {
+          self.invalidateCachedTarget(reason: "response_unavailable")
+          self.sleepFor(self.retryCooldown)
+        }
+        continue
+      }
+      return response
+    }
+  }
+
+  private func executeOnMain(
+    command: Command,
+    alertDeadline: Date?,
+    routeToSpringboard: Bool
+  ) throws -> Response {
+    let preparation = prepareActiveCommandContext(
+      command: command,
+      routeToSpringboard: routeToSpringboard
+    )
+    let activeApp: XCUIApplication
+    switch preparation {
+    case .response(let response):
+      return response
+    case .context(let context):
+      activeApp = context.app
+    }
+
+    switch command.command {
+    case .status:
+      return executeStatus(command: command)
+    case .targetReset:
+      return resetTargetAfterExternalRelaunch()
+    case .shutdown:
+      stopRecordingIfNeeded()
+      return Response(ok: true, data: DataPayload(message: "shutdown"))
+    case .recordStart:
+      guard
+        let requestedOutPath = command.outPath?.trimmingCharacters(in: .whitespacesAndNewlines),
+        !requestedOutPath.isEmpty
+      else {
+        return Response(ok: false, error: ErrorPayload(message: "recordStart requires outPath"))
+      }
+      let hasAppBundleId = !(command.appBundleId?
+        .trimmingCharacters(in: .whitespacesAndNewlines)
+        .isEmpty ?? true)
+      guard hasAppBundleId else {
+        return Response(ok: false, error: ErrorPayload(message: "recordStart requires appBundleId"))
+      }
+      if activeRecording != nil {
+        return Response(ok: false, error: ErrorPayload(message: "recording already in progress"))
+      }
+      if let requestedFps = command.fps, (requestedFps < minRecordingFps || requestedFps > maxRecordingFps) {
+        return Response(ok: false, error: ErrorPayload(message: "recordStart fps must be between \(minRecordingFps) and \(maxRecordingFps)"))
+      }
+      do {
+        let resolvedOutPath = resolveRecordingOutPath(requestedOutPath)
+        let fpsLabel = command.fps.map(String.init) ?? String(RunnerTests.defaultRecordingFps)
+        NSLog(
+          "AGENT_DEVICE_RUNNER_RECORD_START requestedOutPath=%@ resolvedOutPath=%@ fps=%@",
+          requestedOutPath,
+          resolvedOutPath,
+          fpsLabel
+        )
+        let recorder = ScreenRecorder(
+          outputPath: resolvedOutPath,
+          fps: command.fps.map { Int32($0) }
+        )
+        try recorder.start { [weak self] in
+          guard let self else { return .failure(.unresolvedScreen) }
+          return self.captureRunnerFrameResult(app: activeApp)
+        }
+        activeRecording = recorder
+        return Response(ok: true, data: DataPayload(message: "recording started"))
+      } catch {
+        activeRecording = nil
+        return Response(ok: false, error: Self.recordingStartErrorPayload(for: error))
+      }
+    case .recordStop:
+      guard let recorder = activeRecording else {
+        // The runner protocol is the durable cleanup primitive. A daemon may crash after the
+        // native stop succeeds but before it commits the resource transition, so exact-owner
+        // recovery must be able to repeat this command safely. Public `record stop` still owns
+        // its user-facing no-active validation through the daemon session manifest.
+        return Response(ok: true, data: DataPayload(message: "recording already stopped"))
+      }
+      do {
+        try recorder.stop()
+        activeRecording = nil
+        return Response(ok: true, data: DataPayload(message: "recording stopped"))
+      } catch {
+        activeRecording = nil
+        return Response(ok: false, error: ErrorPayload(message: "failed to stop recording: \(error.localizedDescription)"))
+      }
+    case .uptime:
+      return executeUptime()
+    case .activate:
+      guard
+        let bundleId = command.appBundleId?.trimmingCharacters(in: .whitespacesAndNewlines),
+        !bundleId.isEmpty
+      else {
+        return Response(ok: false, error: ErrorPayload(message: "activate requires appBundleId"))
+      }
+      // prepareActiveCommandContext already activated this bundle. Keep this case as the
+      // explicit acknowledgement after that preflight, not as a second activation.
+      return Response(ok: true, data: DataPayload(message: "app activated"))
+    case .terminate:
+      guard
+        let bundleId = command.appBundleId?.trimmingCharacters(in: .whitespacesAndNewlines),
+        !bundleId.isEmpty
+      else {
+        return Response(ok: false, error: ErrorPayload(message: "terminate requires appBundleId"))
+      }
+      XCUIApplication(bundleIdentifier: bundleId).terminate()
+      if currentBundleId == bundleId {
+        invalidateCachedTarget(reason: "target_terminated")
+      }
+      return Response(ok: true, data: DataPayload(message: "app terminated"))
+    default:
+      break
+    }
+    return try executeOnMainPrepared(
+      command: command,
+      activeApp: activeApp,
+      alertDeadline: alertDeadline
+    )
+  }
+
+  func prepareActiveCommandContext(
+    command: Command,
+    routeToSpringboard: Bool = false
+  ) -> ActiveCommandPreparation {
+    var activeApp = currentApp ?? app
+    var systemSurface: SystemSurfaceHost? = nil
+    if routeToSpringboard {
+      activeApp = springboard
+    } else if shouldSkipAppActivationPreflight(command) {
+      activeApp = resolveAppWithoutActivation(command: command)
+    } else if let presented = presentedSystemSurfaceHost() {
+      // Serve and drive the presented surface IN PLACE: never activate it (that cancels what it
+      // presents) and never adopt it as the cached session target, so once it is gone the next
+      // command resolves back to the still-bound session app (#2438).
+      activeApp = presented.app
+      systemSurface = presented.host
+      if isInteractionCommand(command.command) {
+        applyInteractionStabilizationIfNeeded()
+      }
+    } else if !isRunnerLifecycleCommand(command.command) {
+      let normalizedBundleId = command.appBundleId?
+        .trimmingCharacters(in: .whitespacesAndNewlines)
+      let requestedBundleId = (normalizedBundleId?.isEmpty == true) ? nil : normalizedBundleId
+      if let bundleId = requestedBundleId {
+        if currentBundleId != bundleId || currentApp == nil {
+          _ = activateTarget(bundleId: bundleId, reason: "bundle_changed")
+        } else {
+          refreshCachedTargetIfProcessChanged(bundleId: bundleId)
+        }
+      } else {
+        // Do not reuse stale bundle targets when the caller does not explicitly request one.
+        invalidateCachedTarget(reason: "missing_app_bundle")
+      }
+
+      activeApp = currentApp ?? app
+      if let bundleId = requestedBundleId, targetNeedsActivation(activeApp) {
+        activeApp = activateTarget(bundleId: bundleId, reason: "stale_target")
+      } else if requestedBundleId == nil, targetNeedsActivation(activeApp) {
+        ensureRunnerHostAppActive(reason: "missing_app_bundle")
+        activeApp = app
+      }
+
+      let skipExistenceWait = canUseFastForegroundAppGuard(
+        activeApp: activeApp,
+        requestedBundleId: requestedBundleId
+      )
+      if !skipExistenceWait && !activeApp.waitForExistence(timeout: appExistenceTimeout) {
+        if let bundleId = requestedBundleId {
+          activeApp = activateTarget(bundleId: bundleId, reason: "missing_after_wait")
+          guard activeApp.waitForExistence(timeout: appExistenceTimeout) else {
+            return .response(Response(ok: false, error: .targetAppUnavailable(bundleId: bundleId)))
+          }
+        } else {
+          return .response(Response(ok: false, error: .targetAppUnavailable(bundleId: nil)))
+        }
+      }
+
+      if isInteractionCommand(command.command) {
+        if let bundleId = requestedBundleId, activeApp.state != .runningForeground {
+          activeApp = activateTarget(bundleId: bundleId, reason: "interaction_foreground_guard")
+        } else if requestedBundleId == nil, activeApp.state != .runningForeground {
+          ensureRunnerHostAppActive(reason: "interaction_missing_app_bundle")
+          activeApp = app
+        }
+        let skipInteractionExistenceWait = canUseFastForegroundAppGuard(
+          activeApp: activeApp,
+          requestedBundleId: requestedBundleId
+        )
+        if !skipInteractionExistenceWait && !activeApp.waitForExistence(timeout: 2) {
+          return .response(
+            Response(ok: false, error: .targetAppUnavailable(bundleId: requestedBundleId))
+          )
+        }
+        applyInteractionStabilizationIfNeeded()
+      }
+    }
+    return .context(ActiveCommandContext(app: activeApp, systemSurface: systemSurface))
+  }
+
+  /// A registered system surface host that is genuinely on screen, or nil. Presence is foreground
+  /// state, not tree content: a torn-down host still serves a rich tree, and it can only be
+  /// foreground-with-a-stale-tree if something activated it, which the open guard refuses. `state`
+  /// never activates and is cheap when the host is absent. See docs/adr/0004.
+  private func presentedSystemSurfaceHost() -> (host: SystemSurfaceHost, app: XCUIApplication)? {
+#if os(iOS)
+    for host in SystemSurfaceHostRegistry.hosts {
+      let candidate = XCUIApplication(bundleIdentifier: host.bundleId)
+      if candidate.state == .runningForeground {
+        return (host, candidate)
+      }
+    }
+    return nil
+#else
+    return nil
+#endif
+  }
+
+  func currentXCTestFailureCount() -> Int {
+    return testRun?.failureCount ?? 0
+  }
+
+  func didRecordXCTestFailure(since failureCountBefore: Int) -> Bool {
+    return currentXCTestFailureCount() > failureCountBefore
+  }
+
+  func xctestRecordedFailureResponse(command: Command, response: Response) -> Response? {
+    guard response.ok else { return nil }
+    if response.data?.runnerFatal == true {
+      return nil
+    }
+    guard !isReadOnlyCommand(command), !isRunnerLifecycleCommand(command.command) else {
+      return nil
+    }
+    return Response(
+      ok: false,
+      error: ErrorPayload(
+        code: "XCTEST_RECORDED_FAILURE",
+        message: "XCTest recorded a failure while executing \(command.command.rawValue); the action may not have been performed.",
+        hint: "The iOS runner session was invalidated. Re-observe with a fresh snapshot before retrying; if the accessibility tree is unavailable, use screenshot plus coordinate commands instead of retrying the tap blindly."
+      )
+    )
+  }
+
+  func shouldSkipAppActivationPreflight(_ command: Command) -> Bool {
+#if os(iOS)
+    if command.command == .alert {
+      return true
+    }
+    // A hardware Action Button press belongs to the system, not to the session app: the Shortcut or
+    // App Intent behind it is expected to run whether that app is foregrounded, backgrounded, or
+    // terminated, and activating first would foreground exactly what the press should leave alone.
+    // The press keeps its recorded-failure conversion, which `isLifecycle` would have removed
+    // (#2699, #2702 review).
+    if command.command == .actionButton {
+      return true
+    }
+    // Coordinate-only synthesized taps can run after an AX-fatal foreground screen because they do not
+    // need app activation, window lookup, keyboard lookup, or element resolution. Selector/text
+    // interactions intentionally stay on the normal AX path because they need an element query.
+    // Scroll/drag/sequence keep the normal foreground guard and stabilization path.
+    guard command.text == nil, command.selectorKey == nil else { return false }
+    guard hasCachedTargetForActivationSkip(command: command) else { return false }
+    return isCoordinateOnlyTap(command)
+#else
+    return false
+#endif
+  }
+
+  func shouldRouteToSpringboardBlockingSystemModal(
+    _ command: Command
+  ) -> Bool {
+#if os(iOS)
+    guard isCoordinateOnlyTap(command) else {
+      return false
+    }
+    #if AGENT_DEVICE_RUNNER_UNIT_TESTS
+    if let override = blockingSystemModalPresenceOverrideForTesting {
+      return override
+    }
+    #endif
+    let probeDeadline = Date().addingTimeInterval(systemModalProbeBudget)
+    return boundedBlockingSystemAlertSnapshot(
+      deadline: probeDeadline
+    ) != nil
+#else
+    return false
+#endif
+  }
+
+  private func isCoordinateOnlyTap(_ command: Command) -> Bool {
+    return command.command == .tap
+      && command.text == nil
+      && command.selectorKey == nil
+      && command.x != nil
+      && command.y != nil
+  }
+
+  private func hasCachedTargetForActivationSkip(command: Command) -> Bool {
+    guard let currentApp, currentApp.state == .runningForeground else { return false }
+    guard let bundleId = command.appBundleId?.trimmingCharacters(in: .whitespacesAndNewlines),
+      !bundleId.isEmpty
+    else {
+      return true
+    }
+    return currentBundleId == bundleId
+  }
+
+  func resolveAppWithoutActivation(command: Command) -> XCUIApplication {
+    guard let bundleId = command.appBundleId?
+      .trimmingCharacters(in: .whitespacesAndNewlines),
+      !bundleId.isEmpty
+    else {
+      return currentApp ?? app
+    }
+    if currentBundleId == bundleId, let currentApp {
+      return currentApp
+    }
+    return XCUIApplication(bundleIdentifier: bundleId)
+  }
+}
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
index c1aa92ca27..77bdd1a17f 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
@@ -2,827 +2,6 @@ import XCTest
 import AgentDeviceSnapshotPresentation
 
 extension RunnerTests {
-  // MARK: - Main Thread Dispatch
-
-  private func currentUptimeMs() -> Double {
-    ProcessInfo.processInfo.systemUptime * 1000
-  }
-
-  private func measureGesture(_ action: () -> Void) -> (gestureStartUptimeMs: Double, gestureEndUptimeMs: Double) {
-    let gestureStartUptimeMs = currentUptimeMs()
-    action()
-    return (gestureStartUptimeMs, currentUptimeMs())
-  }
-
-  func synthesizedSwipeFallbackHoldDuration(durationMs: Double) -> TimeInterval {
-    min(max((durationMs / 5.0) / 1000.0, 0.016), 0.120)
-  }
-
-  func coordinateDragHoldDuration() -> TimeInterval {
-    0.050
-  }
-
-  func unsupportedResponse(for outcome: RunnerInteractionOutcome) -> Response? {
-    switch outcome {
-    case .performed:
-      return nil
-    case .unsupported(let message, let hint):
-      return Response(
-        ok: false,
-        error: ErrorPayload(code: "UNSUPPORTED_OPERATION", message: message, hint: hint)
-      )
-    }
-  }
-
-  /// Optional visualization frame returned with a gesture response.
-  enum GestureFrame {
-    case none
-    case touch(TouchVisualizationFrame?)
-    case drag(DragVisualizationFrame)
-  }
-
-  struct GestureFallback {
-    let strategy: String
-    let message: String
-    let hint: String?
-  }
-
-  private func gestureFallback(strategy: String, from outcome: RunnerInteractionOutcome) -> GestureFallback? {
-    switch outcome {
-    case .performed:
-      return nil
-    case .unsupported(let message, let hint):
-      return GestureFallback(strategy: strategy, message: message, hint: hint)
-    }
-  }
-
-
-  /// Runs a gesture action with uniform timing capture. Touch gestures pass `idleTimeout: true`
-  /// (the default) to run inside the scroll idle-timeout + quiescence-skip wrapper; synthesis
-  /// pointer-plan gestures pass `false` because RunnerSynthesizedGesture governs their
-  /// own timing. Returns the captured timing and the action's outcome.
-  ///
-  /// NOTE: a new SYNTHESIS gesture must pass `idleTimeout: false` — the default `true` would wrap
-  /// it in the scroll idle-timeout/quiescence-skip path and change its runtime behavior.
-  func performGesture(
-    _ app: XCUIApplication,
-    idleTimeout: Bool = true,
-    _ action: () -> RunnerInteractionOutcome
-  ) -> (timing: (gestureStartUptimeMs: Double, gestureEndUptimeMs: Double), outcome: RunnerInteractionOutcome) {
-    var outcome = RunnerInteractionOutcome.performed
-    let timing = measureGesture {
-      if idleTimeout {
-        withBoundedInteractionIdleTimeoutIfSupported(app, waits: .bothSkipped) {
-          outcome = action()
-        }
-      } else {
-        outcome = action()
-      }
-    }
-    return (timing, outcome)
-  }
-
-  /// Single factory for the success payload every gesture returns (message + gesture timing +
-  /// an optional touch/drag visualization frame), so the field shape lives in one place.
-  func gestureResponse(
-    message: String,
-    timing: (gestureStartUptimeMs: Double, gestureEndUptimeMs: Double),
-    frame: GestureFrame = .none,
-    fallback: GestureFallback? = nil,
-    maestroNonHittableCoordinateFallbackUsed: Bool? = nil
-  ) -> Response {
-    let data: DataPayload
-    switch frame {
-    case .none:
-      data = DataPayload(
-        message: message,
-        gestureStartUptimeMs: timing.gestureStartUptimeMs,
-        gestureEndUptimeMs: timing.gestureEndUptimeMs,
-        gestureFallback: fallback?.strategy,
-        gestureFallbackMessage: fallback?.message,
-        gestureFallbackHint: fallback?.hint,
-        maestroNonHittableCoordinateFallbackUsed: maestroNonHittableCoordinateFallbackUsed
-      )
-    case .touch(let f):
-      data = DataPayload(
-        message: message,
-        gestureStartUptimeMs: timing.gestureStartUptimeMs,
-        gestureEndUptimeMs: timing.gestureEndUptimeMs,
-        x: f?.x,
-        y: f?.y,
-        referenceWidth: f?.referenceWidth,
-        referenceHeight: f?.referenceHeight,
-        gestureFallback: fallback?.strategy,
-        gestureFallbackMessage: fallback?.message,
-        gestureFallbackHint: fallback?.hint,
-        maestroNonHittableCoordinateFallbackUsed: maestroNonHittableCoordinateFallbackUsed
-      )
-    case .drag(let f):
-      data = DataPayload(
-        message: message,
-        gestureStartUptimeMs: timing.gestureStartUptimeMs,
-        gestureEndUptimeMs: timing.gestureEndUptimeMs,
-        x: f.x,
-        y: f.y,
-        x2: f.x2,
-        y2: f.y2,
-        referenceWidth: f.referenceWidth,
-        referenceHeight: f.referenceHeight,
-        gestureFallback: fallback?.strategy,
-        gestureFallbackMessage: fallback?.message,
-        gestureFallbackHint: fallback?.hint
-      )
-    }
-    return Response(ok: true, data: data)
-  }
-
-  /// Gesture plans already return canonical centroid endpoints from the portable runtime.
-  /// Keep runner timing/fallback diagnostics, but do not leak the coordinate-drag adapter's
-  /// visualization frame into only the fast-fling response shape.
-  func canonicalPlannedGestureResponse(_ response: Response) -> Response {
-    guard response.ok, let data = response.data else { return response }
-    return Response(
-      ok: true,
-      data: DataPayload(
-        message: data.message,
-        gestureStartUptimeMs: data.gestureStartUptimeMs,
-        gestureEndUptimeMs: data.gestureEndUptimeMs,
-        gestureFallback: data.gestureFallback,
-        gestureFallbackMessage: data.gestureFallbackMessage,
-        gestureFallbackHint: data.gestureFallbackHint
-      )
-    )
-  }
-
-  private func plannedGestureResponse(
-    plan: RunnerGesturePlan,
-    timing: (gestureStartUptimeMs: Double, gestureEndUptimeMs: Double),
-    outcome: RunnerInteractionOutcome
-  ) -> Response {
-    if let response = unsupportedResponse(for: outcome) {
-      return response
-    }
-    return gestureResponse(message: plan.intent, timing: timing)
-  }
-
-  func executeAccepted(command: Command) throws -> Response {
-    commandJournal.start(command: command)
-    pendingTargetActivation = nil
-    do {
-      let response = try executeDispatched(command: command)
-      commandJournal.finish(command: command, response: response)
-      guard let fact = pendingTargetActivation else { return response }
-      // Stamped after `finish`, like the uptime anchor: a journal-replayed result carries no
-      // activation fact, because the command that paid for it is the one being replayed, not one
-      // that just repaired foreground (#2682).
-      pendingTargetActivation = nil
-      return response.stampingTargetActivation(fact)
-    } catch {
-      pendingTargetActivation = nil
-      commandJournal.fail(command: command, error: error)
-      throw error
-    }
-  }
-
-  func executeStatus(command: Command) -> Response {
-    guard
-      let statusCommandId = command.statusCommandId?.trimmedNonEmpty
-    else {
-      return Response(
-        ok: false,
-        error: ErrorPayload(
-          code: "INVALID_ARGS",
-          message: "status requires statusCommandId",
-          hint: "Set statusCommandId to the commandId of the runner command to inspect."
-        )
-      )
-    }
-    return Response(ok: true, data: commandJournal.status(normalizedCommandId: statusCommandId))
-  }
-
-  func executeUptime() -> Response {
-    // Placeholder value: the transport layer (jsonResponse) overwrites currentUptimeMs with a
-    // fresher send-time stamp on every ok response; kept so direct callers still get a value.
-    Response(
-      ok: true,
-      data: DataPayload(currentUptimeMs: currentUptimeMs())
-    )
-  }
-
-  struct ActiveCommandContext {
-    let app: XCUIApplication
-    /// Set when `app` is a system surface served in place over the still-bound session app (#2438).
-    var systemSurface: SystemSurfaceHost? = nil
-  }
-
-  enum ActiveCommandPreparation {
-    case response(Response)
-    case context(ActiveCommandContext)
-  }
-
-  private func runnerBusyResponse(command: Command, abandonedForSeconds: TimeInterval) -> Response {
-    NSLog(
-      "AGENT_DEVICE_RUNNER_BUSY command=%@ commandId=%@ abandonedForSeconds=%.1f",
-      command.command.rawValue,
-      command.commandId ?? "",
-      abandonedForSeconds
-    )
-    return Response(
-      ok: false,
-      error: ErrorPayload(
-        code: "RUNNER_BUSY",
-        message:
-          "The iOS runner is still finishing a previous command that exceeded its execution watchdog (usually an accessibility capture on a heavy or animating screen).",
-        hint:
-          "Wait a few seconds and retry. If snapshots keep failing on this screen, use screenshot as visual truth and interact by coordinates, or navigate to another screen."
-      )
-    )
-  }
-
-  private func runnerWedgedResponse(command: Command, abandonedForSeconds: TimeInterval) -> Response {
-    NSLog(
-      "AGENT_DEVICE_RUNNER_WEDGED command=%@ commandId=%@ abandonedForSeconds=%.1f",
-      command.command.rawValue,
-      command.commandId ?? "",
-      abandonedForSeconds
-    )
-    return Response(
-      ok: false,
-      error: ErrorPayload(
-        code: "RUNNER_WEDGED",
-        message:
-          "The iOS runner main thread has been stuck in abandoned work for \(Int(abandonedForSeconds)) seconds and cannot recover on its own.",
-        hint:
-          "The runner session will be restarted. Retry the command after the restart; if this screen keeps wedging captures, use screenshot as visual truth and interact by coordinates."
-      )
-    )
-  }
-
-  private func runnerUnavailableResponse(command: Command) -> Response? {
-    switch currentMainThreadBusyState() {
-    case .idle:
-      return nil
-    case .busy(let abandonedForSeconds):
-      return runnerBusyResponse(command: command, abandonedForSeconds: abandonedForSeconds)
-    case .wedged(let abandonedForSeconds):
-      return runnerWedgedResponse(command: command, abandonedForSeconds: abandonedForSeconds)
-    }
-  }
-
-  func executeDispatched(command: Command) throws -> Response {
-    // XCTest work cannot be cancelled mid-flight: once the watchdog abandons a main-queue
-    // block, queueing more main-thread commands behind it only buries the runner deeper.
-    // Refuse fast instead so the daemon backs off while the abandoned work drains; past the
-    // wedge threshold, escalate so the daemon recycles this runner (#1105).
-    if let unavailable = runnerUnavailableResponse(command: command) {
-      return unavailable
-    }
-    let alertDeadline = command.command == .alert
-      ? Date().addingTimeInterval(Self.alertCommandTimeout(timeoutMs: command.timeoutMs))
-      : nil
-    // Resolve this before the command's outer main-thread block. If the bounded probe abandons
-    // slow XCTest enumeration, return the established recoverable response instead of queueing
-    // command preparation behind work that may outlive the 30-second command watchdog.
-    let routeToSpringboard = shouldRouteToSpringboardBlockingSystemModal(command)
-    if let unavailable = runnerUnavailableResponse(command: command) {
-      return unavailable
-    }
-    if command.command == .snapshot {
-      return try executeSnapshotDispatched(command: command)
-    }
-    if command.command == .alert, let deadline = alertDeadline {
-      return try runMainThreadWork(
-        "command_execution",
-        timeout: max(0.001, deadline.timeIntervalSinceNow),
-        timeoutError: mainThreadExecutionTimeoutError
-      ) {
-        try self.executeOnMainSafely(
-          command: command,
-          alertDeadline: deadline,
-          routeToSpringboard: routeToSpringboard
-        )
-      }
-    }
-    return try runMainThreadWork(
-      "command_execution",
-      timeout: mainThreadExecutionTimeout,
-      timeoutError: mainThreadExecutionTimeoutError
-    ) {
-      try self.executeOnMainSafely(command: command, routeToSpringboard: routeToSpringboard)
-    }
-  }
-
-  // MARK: - Command Handling
-
-  private func executeOnMainSafely(
-    command: Command,
-    alertDeadline: Date? = nil,
-    routeToSpringboard: Bool
-  ) throws -> Response {
-    var hasRetried = false
-    while true {
-      var response: Response?
-      var swiftError: Error?
-      let failureCountBefore = currentXCTestFailureCount()
-      let exceptionMessage = RunnerObjCExceptionCatcher.catchException({
-        do {
-          response = try self.executeOnMain(
-            command: command,
-            alertDeadline: alertDeadline,
-            routeToSpringboard: routeToSpringboard
-          )
-        } catch {
-          swiftError = error
-        }
-      })
-
-      if let exceptionMessage {
-        invalidateCachedTarget(reason: "objc_exception")
-        if !hasRetried, shouldRetryException(command, message: exceptionMessage) {
-          NSLog(
-            "AGENT_DEVICE_RUNNER_RETRY command=%@ reason=objc_exception",
-            command.command.rawValue
-          )
-          hasRetried = true
-          sleepFor(retryCooldown)
-          continue
-        }
-        throw NSError(
-          domain: RunnerErrorDomain.exception,
-          code: RunnerErrorCode.objcException,
-          userInfo: [NSLocalizedDescriptionKey: exceptionMessage]
-        )
-      }
-      if let swiftError {
-        throw swiftError
-      }
-      guard let response else {
-        throw NSError(
-          domain: RunnerErrorDomain.general,
-          code: RunnerErrorCode.commandReturnedNoResponse,
-          userInfo: [NSLocalizedDescriptionKey: "command returned no response"]
-        )
-      }
-#if AGENT_DEVICE_RUNNER_UNIT_TESTS
-      // #1605 merge gate: the REAL gesture already executed above; recording a
-      // production-shaped issue here makes the per-command failure-count
-      // conversion below fire exactly as in the field (bsky-24: activation
-      // lands, bookkeeping records a failure). Compiled out of production.
-      if consumeInjectedTapRecordedFailureForTesting(command: command.command) {
-        record(
-          XCTIssue(
-            type: .assertionFailure,
-            compactDescription: "Injected tap recorded-failure (#1605 corroboration merge gate)"
-          )
-        )
-      }
-#endif
-      if didRecordXCTestFailure(since: failureCountBefore),
-        let failureResponse = xctestRecordedFailureResponse(command: command, response: response)
-      {
-        invalidateCachedTarget(reason: "xctest_recorded_failure")
-        return failureResponse
-      }
-      if !hasRetried, shouldRetryCommand(command), shouldRetryResponse(response) {
-        NSLog(
-          "AGENT_DEVICE_RUNNER_RETRY command=%@ reason=response_unavailable",
-          command.command.rawValue
-        )
-        hasRetried = true
-        invalidateCachedTarget(reason: "response_unavailable")
-        sleepFor(retryCooldown)
-        continue
-      }
-      return response
-    }
-  }
-
-  private func executeSnapshotDispatched(command: Command) throws -> Response {
-    try executeDispatchedWithRecovery(command: command) {
-      try self.executeSnapshotDispatchedOnce(command: command)
-    }
-  }
-
-  /// The dispatched snapshot recovery loop: read-only retry + XCTest-recorded-failure invalidation,
-  /// matching what `executeOnMainSafely` gives the generic path. `perform` runs the capture and its
-  /// own bounded main-thread work.
-  func executeDispatchedWithRecovery(
-    command: Command,
-    perform: () throws -> Response
-  ) throws -> Response {
-    var hasRetried = false
-    while true {
-      let failureCountBefore = try runMainThreadWork(
-        "recorded_failure_count",
-        timeout: mainThreadExecutionTimeout,
-        timeoutError: mainThreadExecutionTimeoutError
-      ) {
-        self.currentXCTestFailureCount()
-      }
-      let response = try perform()
-      // Recovered independently — re-entering main for bookkeeping would queue behind the still-
-      // abandoned XCTest query and re-stall the command (#1244), so skip it until that work drains.
-      if hasAbandonedMainThreadWork() {
-        NSLog(
-          "AGENT_DEVICE_RUNNER_DISPATCH_RECOVERY_SKIPPED_XCTEST_OCCUPIED command=%@",
-          command.command.rawValue
-        )
-        return response
-      }
-      let recordedFailureResponse = try runMainThreadWork(
-        "recorded_failure_count",
-        timeout: mainThreadExecutionTimeout,
-        timeoutError: mainThreadExecutionTimeoutError
-      ) {
-        self.didRecordXCTestFailure(since: failureCountBefore)
-          ? self.xctestRecordedFailureResponse(command: command, response: response)
-          : nil
-      }
-      if let recordedFailureResponse {
-        try runMainThreadWork(
-          "target_invalidation",
-          timeout: mainThreadExecutionTimeout,
-          timeoutError: mainThreadExecutionTimeoutError
-        ) {
-          self.invalidateCachedTarget(reason: "xctest_recorded_failure")
-        }
-        return recordedFailureResponse
-      }
-      if !hasRetried, shouldRetryCommand(command), shouldRetryResponse(response) {
-        NSLog(
-          "AGENT_DEVICE_RUNNER_RETRY command=%@ reason=response_unavailable",
-          command.command.rawValue
-        )
-        hasRetried = true
-        try runMainThreadWork(
-          "target_invalidation",
-          timeout: mainThreadExecutionTimeout,
-          timeoutError: mainThreadExecutionTimeoutError
-        ) {
-          self.invalidateCachedTarget(reason: "response_unavailable")
-          self.sleepFor(self.retryCooldown)
-        }
-        continue
-      }
-      return response
-    }
-  }
-
-  private func executeSnapshotDispatchedOnce(command: Command) throws -> Response {
-    let preparation = try runMainThreadWork(
-      "command_preparation",
-      timeout: mainThreadExecutionTimeout,
-      timeoutError: mainThreadExecutionTimeoutError
-    ) {
-      try self.prepareActiveCommandContextSafely(command: command, routeToSpringboard: false)
-    }
-    switch preparation {
-    case .response(let response):
-      return response
-    case .context(let context):
-      return try executeSnapshotPrepared(
-        command: command,
-        activeApp: context.app,
-        systemSurface: context.systemSurface
-      )
-    }
-  }
-
-  /// Pure command→options projection, extracted so the runner unit bundle can
-  /// prove the decoded wire field actually reaches presentation options (#1634 P2).
-  static func presentationOptions(from command: Command) -> PresentationOptions {
-    let customActions = command.customActions ?? false
-    return PresentationOptions(
-      interactiveOnly: command.interactiveOnly ?? false,
-      depth: command.depth,
-      scope: command.scope,
-      raw: command.raw ?? false,
-      // Custom actions are only readable through the private AX client, so
-      // asking for them pins that backend rather than silently returning a
-      // capture that structurally cannot carry them. An explicit pin wins.
-      preferredBackend: command.preferredBackend
-        ?? (customActions ? SnapshotBackendKind.privateAX.rawValue : nil),
-      customActions: customActions
-    )
-  }
-
-  private func executeSnapshotPrepared(
-    command: Command,
-    activeApp: XCUIApplication,
-    systemSurface: SystemSurfaceHost?
-  ) throws -> Response {
-    let options = Self.presentationOptions(from: command)
-    do {
-      var payload: DataPayload
-      if options.raw {
-        payload = try snapshotRaw(app: activeApp, options: options)
-      } else {
-        payload = try snapshotFast(app: activeApp, options: options)
-      }
-      if let systemSurface {
-        payload.systemSurface = SystemSurfaceProvenancePayload(
-          bundleId: systemSurface.bundleId,
-          kind: systemSurface.kind.rawValue
-        )
-      }
-      setNeedsPostSnapshotInteractionDelay()
-      return Response(ok: true, data: payload)
-    } catch let failure as SnapshotCaptureFailure {
-      invalidateCachedTargetAfterSnapshotFailure()
-      return Response(
-        ok: false,
-        error: ErrorPayload(
-          code: failure.code,
-          message: failure.message,
-          hint: failure.hint
-        )
-      )
-    }
-  }
-
-  func setNeedsPostSnapshotInteractionDelay() {
-    guard !hasAbandonedMainThreadWork() else {
-      NSLog("AGENT_DEVICE_RUNNER_POST_SNAPSHOT_DELAY_MARK_SKIPPED_XCTEST_OCCUPIED")
-      return
-    }
-    do {
-      try runMainThreadWork(
-        "post_snapshot_delay_mark",
-        timeout: 1,
-        timeoutError: mainThreadExecutionTimeoutError
-      ) {
-        self.needsPostSnapshotInteractionDelay = true
-      }
-    } catch {
-      NSLog("AGENT_DEVICE_RUNNER_POST_SNAPSHOT_DELAY_MARK_FAILED=%@", String(describing: error))
-    }
-  }
-
-  func invalidateCachedTargetAfterSnapshotFailure() {
-    // Abandoned work ahead of this hop cannot be cancelled: queue the drop behind it without
-    // waiting, so the failed capture answers now and the next command still finds the target gone.
-    guard !hasAbandonedMainThreadWork() else {
-      NSLog("AGENT_DEVICE_RUNNER_SNAPSHOT_INVALIDATION_DEFERRED_XCTEST_OCCUPIED")
-      DispatchQueue.main.async {
-        self.invalidateCachedTarget(reason: "ax_snapshot_failure")
-      }
-      return
-    }
-    do {
-      try runMainThreadWork(
-        "target_invalidation",
-        timeout: 1,
-        timeoutError: mainThreadExecutionTimeoutError
-      ) {
-        self.invalidateCachedTarget(reason: "ax_snapshot_failure")
-      }
-    } catch {
-      NSLog("AGENT_DEVICE_RUNNER_SNAPSHOT_INVALIDATION_FAILED=%@", String(describing: error))
-    }
-  }
-
-  private func prepareActiveCommandContextSafely(
-    command: Command,
-    routeToSpringboard: Bool
-  ) throws -> ActiveCommandPreparation {
-    var preparation: ActiveCommandPreparation?
-    let exceptionMessage = RunnerObjCExceptionCatcher.catchException({
-      preparation = self.prepareActiveCommandContext(
-        command: command,
-        routeToSpringboard: routeToSpringboard
-      )
-    })
-    if let exceptionMessage {
-      throw NSError(
-        domain: RunnerErrorDomain.exception,
-        code: RunnerErrorCode.objcException,
-        userInfo: [NSLocalizedDescriptionKey: exceptionMessage]
-      )
-    }
-    guard let preparation else {
-      throw NSError(
-        domain: RunnerErrorDomain.general,
-        code: RunnerErrorCode.commandReturnedNoResponse,
-        userInfo: [NSLocalizedDescriptionKey: "snapshot preflight returned no response"]
-      )
-    }
-    return preparation
-  }
-
-  private func executeOnMain(
-    command: Command,
-    alertDeadline: Date?,
-    routeToSpringboard: Bool
-  ) throws -> Response {
-    let preparation = prepareActiveCommandContext(
-      command: command,
-      routeToSpringboard: routeToSpringboard
-    )
-    let activeApp: XCUIApplication
-    switch preparation {
-    case .response(let response):
-      return response
-    case .context(let context):
-      activeApp = context.app
-    }
-
-    switch command.command {
-    case .status:
-      return executeStatus(command: command)
-    case .targetReset:
-      return resetTargetAfterExternalRelaunch()
-    case .shutdown:
-      stopRecordingIfNeeded()
-      return Response(ok: true, data: DataPayload(message: "shutdown"))
-    case .recordStart:
-      guard
-        let requestedOutPath = command.outPath?.trimmingCharacters(in: .whitespacesAndNewlines),
-        !requestedOutPath.isEmpty
-      else {
-        return Response(ok: false, error: ErrorPayload(message: "recordStart requires outPath"))
-      }
-      let hasAppBundleId = !(command.appBundleId?
-        .trimmingCharacters(in: .whitespacesAndNewlines)
-        .isEmpty ?? true)
-      guard hasAppBundleId else {
-        return Response(ok: false, error: ErrorPayload(message: "recordStart requires appBundleId"))
-      }
-      if activeRecording != nil {
-        return Response(ok: false, error: ErrorPayload(message: "recording already in progress"))
-      }
-      if let requestedFps = command.fps, (requestedFps < minRecordingFps || requestedFps > maxRecordingFps) {
-        return Response(ok: false, error: ErrorPayload(message: "recordStart fps must be between \(minRecordingFps) and \(maxRecordingFps)"))
-      }
-      do {
-        let resolvedOutPath = resolveRecordingOutPath(requestedOutPath)
-        let fpsLabel = command.fps.map(String.init) ?? String(RunnerTests.defaultRecordingFps)
-        NSLog(
-          "AGENT_DEVICE_RUNNER_RECORD_START requestedOutPath=%@ resolvedOutPath=%@ fps=%@",
-          requestedOutPath,
-          resolvedOutPath,
-          fpsLabel
-        )
-        let recorder = ScreenRecorder(
-          outputPath: resolvedOutPath,
-          fps: command.fps.map { Int32($0) }
-        )
-        try recorder.start { [weak self] in
-          guard let self else { return .failure(.unresolvedScreen) }
-          return self.captureRunnerFrameResult(app: activeApp)
-        }
-        activeRecording = recorder
-        return Response(ok: true, data: DataPayload(message: "recording started"))
-      } catch {
-        activeRecording = nil
-        return Response(ok: false, error: Self.recordingStartErrorPayload(for: error))
-      }
-    case .recordStop:
-      guard let recorder = activeRecording else {
-        // The runner protocol is the durable cleanup primitive. A daemon may crash after the
-        // native stop succeeds but before it commits the resource transition, so exact-owner
-        // recovery must be able to repeat this command safely. Public `record stop` still owns
-        // its user-facing no-active validation through the daemon session manifest.
-        return Response(ok: true, data: DataPayload(message: "recording already stopped"))
-      }
-      do {
-        try recorder.stop()
-        activeRecording = nil
-        return Response(ok: true, data: DataPayload(message: "recording stopped"))
-      } catch {
-        activeRecording = nil
-        return Response(ok: false, error: ErrorPayload(message: "failed to stop recording: \(error.localizedDescription)"))
-      }
-    case .uptime:
-      return executeUptime()
-    case .activate:
-      guard
-        let bundleId = command.appBundleId?.trimmingCharacters(in: .whitespacesAndNewlines),
-        !bundleId.isEmpty
-      else {
-        return Response(ok: false, error: ErrorPayload(message: "activate requires appBundleId"))
-      }
-      // prepareActiveCommandContext already activated this bundle. Keep this case as the
-      // explicit acknowledgement after that preflight, not as a second activation.
-      return Response(ok: true, data: DataPayload(message: "app activated"))
-    case .terminate:
-      guard
-        let bundleId = command.appBundleId?.trimmingCharacters(in: .whitespacesAndNewlines),
-        !bundleId.isEmpty
-      else {
-        return Response(ok: false, error: ErrorPayload(message: "terminate requires appBundleId"))
-      }
-      XCUIApplication(bundleIdentifier: bundleId).terminate()
-      if currentBundleId == bundleId {
-        invalidateCachedTarget(reason: "target_terminated")
-      }
-      return Response(ok: true, data: DataPayload(message: "app terminated"))
-    default:
-      break
-    }
-    return try executeOnMainPrepared(
-      command: command,
-      activeApp: activeApp,
-      alertDeadline: alertDeadline
-    )
-  }
-
-  func prepareActiveCommandContext(
-    command: Command,
-    routeToSpringboard: Bool = false
-  ) -> ActiveCommandPreparation {
-    var activeApp = currentApp ?? app
-    var systemSurface: SystemSurfaceHost? = nil
-    if routeToSpringboard {
-      activeApp = springboard
-    } else if shouldSkipAppActivationPreflight(command) {
-      activeApp = resolveAppWithoutActivation(command: command)
-    } else if let presented = presentedSystemSurfaceHost() {
-      // Serve and drive the presented surface IN PLACE: never activate it (that cancels what it
-      // presents) and never adopt it as the cached session target, so once it is gone the next
-      // command resolves back to the still-bound session app (#2438).
-      activeApp = presented.app
-      systemSurface = presented.host
-      if isInteractionCommand(command.command) {
-        applyInteractionStabilizationIfNeeded()
-      }
-    } else if !isRunnerLifecycleCommand(command.command) {
-      let normalizedBundleId = command.appBundleId?
-        .trimmingCharacters(in: .whitespacesAndNewlines)
-      let requestedBundleId = (normalizedBundleId?.isEmpty == true) ? nil : normalizedBundleId
-      if let bundleId = requestedBundleId {
-        if currentBundleId != bundleId || currentApp == nil {
-          _ = activateTarget(bundleId: bundleId, reason: "bundle_changed")
-        } else {
-          refreshCachedTargetIfProcessChanged(bundleId: bundleId)
-        }
-      } else {
-        // Do not reuse stale bundle targets when the caller does not explicitly request one.
-        invalidateCachedTarget(reason: "missing_app_bundle")
-      }
-
-      activeApp = currentApp ?? app
-      if let bundleId = requestedBundleId, targetNeedsActivation(activeApp) {
-        activeApp = activateTarget(bundleId: bundleId, reason: "stale_target")
-      } else if requestedBundleId == nil, targetNeedsActivation(activeApp) {
-        ensureRunnerHostAppActive(reason: "missing_app_bundle")
-        activeApp = app
-      }
-
-      let skipExistenceWait = canUseFastForegroundAppGuard(
-        activeApp: activeApp,
-        requestedBundleId: requestedBundleId
-      )
-      if !skipExistenceWait && !activeApp.waitForExistence(timeout: appExistenceTimeout) {
-        if let bundleId = requestedBundleId {
-          activeApp = activateTarget(bundleId: bundleId, reason: "missing_after_wait")
-          guard activeApp.waitForExistence(timeout: appExistenceTimeout) else {
-            return .response(Response(ok: false, error: .targetAppUnavailable(bundleId: bundleId)))
-          }
-        } else {
-          return .response(Response(ok: false, error: .targetAppUnavailable(bundleId: nil)))
-        }
-      }
-
-      if isInteractionCommand(command.command) {
-        if let bundleId = requestedBundleId, activeApp.state != .runningForeground {
-          activeApp = activateTarget(bundleId: bundleId, reason: "interaction_foreground_guard")
-        } else if requestedBundleId == nil, activeApp.state != .runningForeground {
-          ensureRunnerHostAppActive(reason: "interaction_missing_app_bundle")
-          activeApp = app
-        }
-        let skipInteractionExistenceWait = canUseFastForegroundAppGuard(
-          activeApp: activeApp,
-          requestedBundleId: requestedBundleId
-        )
-        if !skipInteractionExistenceWait && !activeApp.waitForExistence(timeout: 2) {
-          return .response(
-            Response(ok: false, error: .targetAppUnavailable(bundleId: requestedBundleId))
-          )
-        }
-        applyInteractionStabilizationIfNeeded()
-      }
-    }
-    return .context(ActiveCommandContext(app: activeApp, systemSurface: systemSurface))
-  }
-
-  /// A registered system surface host that is genuinely on screen, or nil. Presence is foreground
-  /// state, not tree content: a torn-down host still serves a rich tree, and it can only be
-  /// foreground-with-a-stale-tree if something activated it, which the open guard refuses. `state`
-  /// never activates and is cheap when the host is absent. See docs/adr/0004.
-  private func presentedSystemSurfaceHost() -> (host: SystemSurfaceHost, app: XCUIApplication)? {
-#if os(iOS)
-    for host in SystemSurfaceHostRegistry.hosts {
-      let candidate = XCUIApplication(bundleIdentifier: host.bundleId)
-      if candidate.state == .runningForeground {
-        return (host, candidate)
-      }
-    }
-    return nil
-#else
-    return nil
-#endif
-  }
-
   func executeOnMainPrepared(
     command: Command,
     activeApp: XCUIApplication,
@@ -1456,528 +635,4 @@ extension RunnerTests {
       return executeSequence(command: command, activeApp: activeApp)
     }
   }
-
-  private func invalidScrollDirectionResponse(commandName: String) -> Response {
-    Response(
-      ok: false,
-      error: ErrorPayload(
-        code: "INVALID_ARGS",
-        message: "\(commandName) requires direction up|down|left|right"
-      )
-    )
-  }
-
-  private func scrollDurationIsValid(_ durationMs: Double?) -> Bool {
-    guard let durationMs else { return true }
-    return durationMs.isFinite && durationMs >= 0 && durationMs <= 10000
-  }
-
-  private func invalidScrollDurationResponse(commandName: String) -> Response {
-    return Response(
-      ok: false,
-      error: ErrorPayload(
-        code: "INVALID_ARGS",
-        message: "\(commandName) durationMs must be between 0 and 10000"
-      )
-    )
-  }
-
-  private func executeScrollDragGesture(
-    activeApp: XCUIApplication,
-    x: Double,
-    y: Double,
-    x2: Double,
-    y2: Double,
-    durationMs: Double,
-    message: String,
-    context: SynthesizedCoordinateContext,
-    releaseBehavior: ScrollReleaseBehavior?
-  ) -> Response {
-#if os(iOS)
-    return executeDragGesture(
-      activeApp: activeApp,
-      x: x,
-      y: y,
-      x2: x2,
-      y2: y2,
-      durationMs: durationMs,
-      message: message,
-      synthesizedContext: context,
-      synthesized: (profile: scrollDragProfile(releaseBehavior: releaseBehavior), policyKind: .scroll)
-    )
-#else
-    return executeDragGesture(
-      activeApp: activeApp,
-      x: x,
-      y: y,
-      x2: x2,
-      y2: y2,
-      durationMs: durationMs,
-      message: message
-    )
-#endif
-  }
-
-  /// Shared coordinate drag execution. Callers that pass `synthesized` take the iOS synthesized
-  /// lane with that profile and fallback policy; the rest perform an XCTest coordinate drag.
-  private func executeDragGesture(
-    activeApp: XCUIApplication,
-    x: Double,
-    y: Double,
-    x2: Double,
-    y2: Double,
-    durationMs: Double?,
-    message: String,
-    synthesizedContext: SynthesizedCoordinateContext? = nil,
-    synthesized: (profile: SynthesizedDragProfile, policyKind: SynthesizedGesturePolicyKind)? = nil
-  ) -> Response {
-    let durationMs = durationMs ?? runnerDefaultDragDurationMs
-    let commandName = dragCommandName(message: message)
-    guard x.isFinite, y.isFinite, x2.isFinite, y2.isFinite else {
-      return Response(
-        ok: false,
-        error: ErrorPayload(code: "INVALID_ARGS", message: "\(commandName) requires finite coordinates")
-      )
-    }
-    if let synthesized, let synthesizedResponse = executeSynthesizedDragGesture(
-      activeApp: activeApp,
-      x: x,
-      y: y,
-      x2: x2,
-      y2: y2,
-      durationMs: durationMs,
-      message: message,
-      context: synthesizedContext,
-      policyKind: synthesized.policyKind,
-      profile: synthesized.profile
-    ) {
-      return synthesizedResponse
-    }
-    let dragPoints = keyboardAvoidingDragPoints(app: activeApp, x: x, y: y, x2: x2, y2: y2)
-    let dragFrame = resolvedDragVisualizationFrame(
-      app: activeApp,
-      x: dragPoints.x,
-      y: dragPoints.y,
-      x2: dragPoints.x2,
-      y2: dragPoints.y2
-    )
-    let holdDuration = synthesized == nil
-      ? coordinateDragHoldDuration()
-      : synthesizedSwipeFallbackHoldDuration(durationMs: durationMs)
-    let (timing, outcome) = performGesture(activeApp) {
-      dragAt(
-        app: activeApp,
-        x: dragPoints.x,
-        y: dragPoints.y,
-        x2: dragPoints.x2,
-        y2: dragPoints.y2,
-        holdDuration: holdDuration
-      )
-    }
-    if let response = unsupportedResponse(for: outcome) {
-      return response
-    }
-    return gestureResponse(message: message, timing: timing, frame: .drag(dragFrame))
-  }
-
-  private func executeSynthesizedDragGesture(
-    activeApp: XCUIApplication,
-    x: Double,
-    y: Double,
-    x2: Double,
-    y2: Double,
-    durationMs: Double,
-    message: String,
-    context: SynthesizedCoordinateContext?,
-    policyKind: SynthesizedGesturePolicyKind,
-    profile: SynthesizedDragProfile
-  ) -> Response? {
-#if os(iOS)
-    let policy = synthesizedGesturePolicy(policyKind)
-    let context = context ?? synthesizedCoordinateContext(app: activeApp, policy: policy)
-    guard let plan = axFreeSynthesizedDragPlan(
-      app: activeApp,
-      x: x,
-      y: y,
-      x2: x2,
-      y2: y2,
-      context: context
-    )
-    else {
-      if context?.allowsXCTestCoordinateFallback == true {
-        logSynthesizedGesturePolicyDecision(kind: policyKind, context: context, fallbackAttempted: true)
-        return executeCoordinateDragFallback(
-          activeApp: activeApp,
-          x: x,
-          y: y,
-          x2: x2,
-          y2: y2,
-          durationMs: durationMs,
-          message: message,
-          fallback: nil
-        )
-      }
-      logSynthesizedGesturePolicyDecision(kind: policyKind, context: context, fallbackAttempted: false)
-      return Response(
-        ok: false,
-        error: ErrorPayload(
-          code: "INVALID_ARGS",
-          message: "\(dragCommandName(message: message)) could not resolve a finite synthesized coordinate frame"
-        )
-      )
-    }
-    let durationMs = min(max(durationMs, 16), 10000)
-    let dragFrame = axFreeDragVisualizationFrame(
-      x: plan.points.x,
-      y: plan.points.y,
-      x2: plan.points.x2,
-      y2: plan.points.y2,
-      referenceFrame: plan.referenceFrame
-    )
-    let (timing, outcome) = performGesture(activeApp, idleTimeout: false) {
-      synthesizedDragAt(
-        app: activeApp,
-        x: plan.points.x,
-        y: plan.points.y,
-        x2: plan.points.x2,
-        y2: plan.points.y2,
-        durationMs: durationMs,
-        profile: profile,
-        context: plan.context
-      )
-    }
-    if case .performed = outcome {
-      logSynthesizedGesturePolicyDecision(kind: policyKind, context: plan.context, fallbackAttempted: false)
-      return gestureResponse(message: message, timing: timing, frame: .drag(dragFrame))
-    }
-    if plan.context.allowsXCTestCoordinateFallback {
-      logSynthesizedGesturePolicyDecision(kind: policyKind, context: plan.context, fallbackAttempted: true)
-      return executeCoordinateDragFallback(
-        activeApp: activeApp,
-        x: plan.points.x,
-        y: plan.points.y,
-        x2: plan.points.x2,
-        y2: plan.points.y2,
-        durationMs: durationMs,
-        message: message,
-        fallback: gestureFallback(strategy: "xctest-coordinate-drag", from: outcome)
-      )
-    }
-    logSynthesizedGesturePolicyDecision(kind: policyKind, context: plan.context, fallbackAttempted: false)
-    return unsupportedResponse(for: outcome)
-#else
-    return nil
-#endif
-  }
-
-  private func executeCoordinateDragFallback(
-    activeApp: XCUIApplication,
-    x: Double,
-    y: Double,
-    x2: Double,
-    y2: Double,
-    durationMs: Double,
-    message: String,
-    fallback: GestureFallback?
-  ) -> Response {
-    let dragPoints = keyboardAvoidingDragPoints(app: activeApp, x: x, y: y, x2: x2, y2: y2)
-    let dragFrame = resolvedDragVisualizationFrame(
-      app: activeApp,
-      x: dragPoints.x,
-      y: dragPoints.y,
-      x2: dragPoints.x2,
-      y2: dragPoints.y2
-    )
-    let holdDuration = synthesizedSwipeFallbackHoldDuration(durationMs: durationMs)
-    let (timing, outcome) = performGesture(activeApp) {
-      dragAt(
-        app: activeApp,
-        x: dragPoints.x,
-        y: dragPoints.y,
-        x2: dragPoints.x2,
-        y2: dragPoints.y2,
-        holdDuration: holdDuration
-      )
-    }
-    if let response = unsupportedResponse(for: outcome) {
-      return response
-    }
-    return gestureResponse(
-      message: message,
-      timing: timing,
-      frame: .drag(dragFrame),
-      fallback: fallback
-    )
-  }
-
-  /// Adds the #2500 avoidance evidence to a scroll response. Only the frame resolver knows whether
-  /// it trimmed the swipe for a keyboard, and only `scroll` has this evidence to carry, so it is
-  /// attached where the frame was resolved rather than threaded through every gesture response.
-  /// The refusal a keyboard forces. It performs no gesture: swiping into the keys would leave the
-  /// surface where it was, which the daemon's no-progress fingerprint reads as a stuck container
-  /// (#2499) and an agent reads as a broken scroll. The TS owner maps the code to the
-  /// `scroll_keyboard_occludes_surface` reason and the "dismiss the keyboard" hint.
-  private func scrollKeyboardOccludedResponse(
-    direction: String,
-    keyboardMinY: Double,
-    visibleHeight: Double
-  ) -> Response {
-    return Response(
-      ok: false,
-      error: ErrorPayload(
-        code: ScrollViewportPolicy.occlusionRunnerCode,
-        message: String(
-          format:
-            "scroll %@ refused: the keyboard leaves %.0fpt of visible surface above it, too little to swipe",
-          direction,
-          visibleHeight
-        )
-      )
-    )
-  }
-
-  private func dragCommandName(message: String) -> String {
-    return message == "scrolled" ? "scroll" : "drag"
-  }
-
-  func currentXCTestFailureCount() -> Int {
-    return testRun?.failureCount ?? 0
-  }
-
-  func didRecordXCTestFailure(since failureCountBefore: Int) -> Bool {
-    return currentXCTestFailureCount() > failureCountBefore
-  }
-
-  func xctestRecordedFailureResponse(command: Command, response: Response) -> Response? {
-    guard response.ok else { return nil }
-    if response.data?.runnerFatal == true {
-      return nil
-    }
-    guard !isReadOnlyCommand(command), !isRunnerLifecycleCommand(command.command) else {
-      return nil
-    }
-    return Response(
-      ok: false,
-      error: ErrorPayload(
-        code: "XCTEST_RECORDED_FAILURE",
-        message: "XCTest recorded a failure while executing \(command.command.rawValue); the action may not have been performed.",
-        hint: "The iOS runner session was invalidated. Re-observe with a fresh snapshot before retrying; if the accessibility tree is unavailable, use screenshot plus coordinate commands instead of retrying the tap blindly."
-      )
-    )
-  }
-
-  func shouldSkipAppActivationPreflight(_ command: Command) -> Bool {
-#if os(iOS)
-    if command.command == .alert {
-      return true
-    }
-    // A hardware Action Button press belongs to the system, not to the session app: the Shortcut or
-    // App Intent behind it is expected to run whether that app is foregrounded, backgrounded, or
-    // terminated, and activating first would foreground exactly what the press should leave alone.
-    // The press keeps its recorded-failure conversion, which `isLifecycle` would have removed
-    // (#2699, #2702 review).
-    if command.command == .actionButton {
-      return true
-    }
-    // Coordinate-only synthesized taps can run after an AX-fatal foreground screen because they do not
-    // need app activation, window lookup, keyboard lookup, or element resolution. Selector/text
-    // interactions intentionally stay on the normal AX path because they need an element query.
-    // Scroll/drag/sequence keep the normal foreground guard and stabilization path.
-    guard command.text == nil, command.selectorKey == nil else { return false }
-    guard hasCachedTargetForActivationSkip(command: command) else { return false }
-    return isCoordinateOnlyTap(command)
-#else
-    return false
-#endif
-  }
-
-  func shouldRouteToSpringboardBlockingSystemModal(
-    _ command: Command
-  ) -> Bool {
-#if os(iOS)
-    guard isCoordinateOnlyTap(command) else {
-      return false
-    }
-    #if AGENT_DEVICE_RUNNER_UNIT_TESTS
-    if let override = blockingSystemModalPresenceOverrideForTesting {
-      return override
-    }
-    #endif
-    let probeDeadline = Date().addingTimeInterval(systemModalProbeBudget)
-    return boundedBlockingSystemAlertSnapshot(
-      deadline: probeDeadline
-    ) != nil
-#else
-    return false
-#endif
-  }
-
-  private func isCoordinateOnlyTap(_ command: Command) -> Bool {
-    return command.command == .tap
-      && command.text == nil
-      && command.selectorKey == nil
-      && command.x != nil
-      && command.y != nil
-  }
-
-  private func hasCachedTargetForActivationSkip(command: Command) -> Bool {
-    guard let currentApp, currentApp.state == .runningForeground else { return false }
-    guard let bundleId = command.appBundleId?.trimmingCharacters(in: .whitespacesAndNewlines),
-      !bundleId.isEmpty
-    else {
-      return true
-    }
-    return currentBundleId == bundleId
-  }
-
-  private func resolveAppWithoutActivation(command: Command) -> XCUIApplication {
-    guard let bundleId = command.appBundleId?
-      .trimmingCharacters(in: .whitespacesAndNewlines),
-      !bundleId.isEmpty
-    else {
-      return currentApp ?? app
-    }
-    if currentBundleId == bundleId, let currentApp {
-      return currentApp
-    }
-    return XCUIApplication(bundleIdentifier: bundleId)
-  }
-
-  func executeTypeCommand(activeApp: XCUIApplication, command: Command) -> Response {
-    guard let text = command.text else {
-      return Response(ok: false, error: ErrorPayload(message: "type requires text"))
-    }
-    let delaySeconds = Double(max(command.delayMs ?? 0, 0)) / 1000.0
-    let textEntryMode = resolveTextEntryMode(command)
-    let target: TextEntryTarget
-    var resolvedCoordinateContext: SynthesizedCoordinateContext?
-    // The shared runtime has already resolved this node as non-hittable and
-    // deliberately selected Maestro's coordinate compatibility route.
-    let maestroNonHittableCoordinateFallbackUsed: Bool? =
-      command.allowNonHittableCoordinateFallback == true && command.x != nil && command.y != nil
-      ? true
-      : nil
-    let focusStartedAt = Date()
-#if os(iOS)
-    let xCTestChannelPenalized = isSnapshotXCTestChannelPenalized(bundleId: currentBundleId)
-    var resolvedCoordinateTarget: TextEntryTarget?
-    if Self.shouldUseResolvedCoordinateTextEntryRoute(
-      repairMode: textEntryMode,
-      hasX: command.x != nil,
-      hasY: command.y != nil,
-      xCTestChannelPenalized: xCTestChannelPenalized
-    ), let x = command.x, let y = command.y {
-      let policyKind = SynthesizedGesturePolicyKind.coordinateTap
-      let context = synthesizedCoordinateContext(
-        app: activeApp,
-        policy: synthesizedGesturePolicy(policyKind)
-      )
-      let (_, outcome) = performGesture(activeApp, idleTimeout: false) {
-        synthesizedTapAt(app: activeApp, x: x, y: y, context: context)
-      }
-      if Self.shouldFallbackFromSynthesizedTextEntryFocus(outcome) {
-        logSynthesizedGesturePolicyDecision(
-          kind: policyKind,
-          context: context,
-          fallbackAttempted: true
-        )
-      } else {
-        logSynthesizedGesturePolicyDecision(
-          kind: policyKind,
-          context: context,
-          fallbackAttempted: false
-        )
-        resolvedCoordinateContext = context
-        resolvedCoordinateTarget = TextEntryTarget(
-          element: nil,
-          refreshPoint: CGPoint(x: x, y: y),
-          prefersFocusedElement: false
-        )
-      }
-    }
-#else
-    let xCTestChannelPenalized = false
-    let resolvedCoordinateTarget: TextEntryTarget? = nil
-#endif
-    if let resolvedCoordinateTarget {
-      target = resolvedCoordinateTarget
-    } else {
-      target = focusTextInputForTextEntry(app: activeApp, x: command.x, y: command.y)
-    }
-    NSLog(
-      "AGENT_DEVICE_RUNNER_TEXT_ENTRY_PHASE commandId=%@ phase=focus durationMs=%.1f chars=%d mode=%@",
-      command.commandId ?? "",
-      Date().timeIntervalSince(focusStartedAt) * 1000.0,
-      text.count,
-      textEntryModeName(textEntryMode)
-    )
-    if textEntryMode == .replacement {
-#if os(iOS)
-      let canReplaceResolvedFirstResponder = Self.shouldUseSynthesizedFirstResponderReplacement(
-        hasResolvedElement: target.element != nil,
-        hasRefreshPoint: target.refreshPoint != nil,
-        xCTestChannelPenalized: xCTestChannelPenalized
-      )
-#else
-      let canReplaceResolvedFirstResponder = false
-#endif
-      guard target.element != nil || canReplaceResolvedFirstResponder else {
-        let message =
-          (command.x != nil && command.y != nil)
-          ? "no text input found at the provided coordinates to clear"
-          : "no focused text input to clear"
-        return Response(ok: false, error: ErrorPayload(message: message))
-      }
-    }
-    let textResult = typeTextReliably(
-      app: activeApp,
-      target: target,
-      text: text,
-      delaySeconds: delaySeconds,
-      repairMode: textEntryMode,
-      xCTestChannelPenalized: xCTestChannelPenalized,
-      synthesizer: PrivateXCTestTextEntrySynthesizer(),
-      commandId: command.commandId
-    )
-    if let failure = textResult.failure {
-      return Response(
-        ok: false,
-        error: ErrorPayload(code: failure.rawValue, message: failure.message, hint: failure.hint)
-      )
-    }
-    if textResult.verified == false {
-      let expected = textResult.expectedText ?? ""
-      let observed = textResult.observedText ?? ""
-      return Response(
-        ok: false,
-        error: ErrorPayload(
-          code: "TEXT_ENTRY_MISMATCH",
-          message: "text entry verification failed: expected \"\(expected)\", observed \"\(observed)\""
-        )
-      )
-    }
-    let point = target.refreshPoint
-    let frame: CGRect
-    if let resolvedCoordinateContext {
-      frame = resolvedCoordinateContext.referenceFrame
-    } else if point != nil {
-      frame = activeApp.frame
-    } else {
-      // Bare `type` has no coordinate response to normalize. Avoid serializing the
-      // application AX tree only to emit unused reference dimensions.
-      frame = .zero
-    }
-    return Response(
-      ok: true,
-      data: DataPayload(
-        message: textResult.repaired ? "typed after repair" : "typed",
-        x: point.map { Double($0.x) },
-        y: point.map { Double($0.y) },
-        referenceWidth: frame.isEmpty ? nil : Double(frame.width),
-        referenceHeight: frame.isEmpty ? nil : Double(frame.height),
-        maestroNonHittableCoordinateFallbackUsed: maestroNonHittableCoordinateFallbackUsed,
-        textEntryRoute: textResult.textEntryRoute
-      )
-    )
-  }
 }
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+GestureExecution.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+GestureExecution.swift
new file mode 100644
index 0000000000..46d14d17f7
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+GestureExecution.swift
@@ -0,0 +1,165 @@
+import XCTest
+import AgentDeviceSnapshotPresentation
+
+extension RunnerTests {
+  func currentUptimeMs() -> Double {
+    ProcessInfo.processInfo.systemUptime * 1000
+  }
+
+  func measureGesture(_ action: () -> Void) -> (gestureStartUptimeMs: Double, gestureEndUptimeMs: Double) {
+    let gestureStartUptimeMs = currentUptimeMs()
+    action()
+    return (gestureStartUptimeMs, currentUptimeMs())
+  }
+
+  func synthesizedSwipeFallbackHoldDuration(durationMs: Double) -> TimeInterval {
+    min(max((durationMs / 5.0) / 1000.0, 0.016), 0.120)
+  }
+
+  func coordinateDragHoldDuration() -> TimeInterval {
+    0.050
+  }
+
+  func unsupportedResponse(for outcome: RunnerInteractionOutcome) -> Response? {
+    switch outcome {
+    case .performed:
+      return nil
+    case .unsupported(let message, let hint):
+      return Response(
+        ok: false,
+        error: ErrorPayload(code: "UNSUPPORTED_OPERATION", message: message, hint: hint)
+      )
+    }
+  }
+
+  /// Optional visualization frame returned with a gesture response.
+  enum GestureFrame {
+    case none
+    case touch(TouchVisualizationFrame?)
+    case drag(DragVisualizationFrame)
+  }
+
+  struct GestureFallback {
+    let strategy: String
+    let message: String
+    let hint: String?
+  }
+
+  func gestureFallback(strategy: String, from outcome: RunnerInteractionOutcome) -> GestureFallback? {
+    switch outcome {
+    case .performed:
+      return nil
+    case .unsupported(let message, let hint):
+      return GestureFallback(strategy: strategy, message: message, hint: hint)
+    }
+  }
+
+
+  /// Runs a gesture action with uniform timing capture. Touch gestures pass `idleTimeout: true`
+  /// (the default) to run inside the scroll idle-timeout + quiescence-skip wrapper; synthesis
+  /// pointer-plan gestures pass `false` because RunnerSynthesizedGesture governs their
+  /// own timing. Returns the captured timing and the action's outcome.
+  ///
+  /// NOTE: a new SYNTHESIS gesture must pass `idleTimeout: false` — the default `true` would wrap
+  /// it in the scroll idle-timeout/quiescence-skip path and change its runtime behavior.
+  func performGesture(
+    _ app: XCUIApplication,
+    idleTimeout: Bool = true,
+    _ action: () -> RunnerInteractionOutcome
+  ) -> (timing: (gestureStartUptimeMs: Double, gestureEndUptimeMs: Double), outcome: RunnerInteractionOutcome) {
+    var outcome = RunnerInteractionOutcome.performed
+    let timing = measureGesture {
+      if idleTimeout {
+        withBoundedInteractionIdleTimeoutIfSupported(app, waits: .bothSkipped) {
+          outcome = action()
+        }
+      } else {
+        outcome = action()
+      }
+    }
+    return (timing, outcome)
+  }
+
+  /// Single factory for the success payload every gesture returns (message + gesture timing +
+  /// an optional touch/drag visualization frame), so the field shape lives in one place.
+  func gestureResponse(
+    message: String,
+    timing: (gestureStartUptimeMs: Double, gestureEndUptimeMs: Double),
+    frame: GestureFrame = .none,
+    fallback: GestureFallback? = nil,
+    maestroNonHittableCoordinateFallbackUsed: Bool? = nil
+  ) -> Response {
+    let data: DataPayload
+    switch frame {
+    case .none:
+      data = DataPayload(
+        message: message,
+        gestureStartUptimeMs: timing.gestureStartUptimeMs,
+        gestureEndUptimeMs: timing.gestureEndUptimeMs,
+        gestureFallback: fallback?.strategy,
+        gestureFallbackMessage: fallback?.message,
+        gestureFallbackHint: fallback?.hint,
+        maestroNonHittableCoordinateFallbackUsed: maestroNonHittableCoordinateFallbackUsed
+      )
+    case .touch(let f):
+      data = DataPayload(
+        message: message,
+        gestureStartUptimeMs: timing.gestureStartUptimeMs,
+        gestureEndUptimeMs: timing.gestureEndUptimeMs,
+        x: f?.x,
+        y: f?.y,
+        referenceWidth: f?.referenceWidth,
+        referenceHeight: f?.referenceHeight,
+        gestureFallback: fallback?.strategy,
+        gestureFallbackMessage: fallback?.message,
+        gestureFallbackHint: fallback?.hint,
+        maestroNonHittableCoordinateFallbackUsed: maestroNonHittableCoordinateFallbackUsed
+      )
+    case .drag(let f):
+      data = DataPayload(
+        message: message,
+        gestureStartUptimeMs: timing.gestureStartUptimeMs,
+        gestureEndUptimeMs: timing.gestureEndUptimeMs,
+        x: f.x,
+        y: f.y,
+        x2: f.x2,
+        y2: f.y2,
+        referenceWidth: f.referenceWidth,
+        referenceHeight: f.referenceHeight,
+        gestureFallback: fallback?.strategy,
+        gestureFallbackMessage: fallback?.message,
+        gestureFallbackHint: fallback?.hint
+      )
+    }
+    return Response(ok: true, data: data)
+  }
+
+  /// Gesture plans already return canonical centroid endpoints from the portable runtime.
+  /// Keep runner timing/fallback diagnostics, but do not leak the coordinate-drag adapter's
+  /// visualization frame into only the fast-fling response shape.
+  func canonicalPlannedGestureResponse(_ response: Response) -> Response {
+    guard response.ok, let data = response.data else { return response }
+    return Response(
+      ok: true,
+      data: DataPayload(
+        message: data.message,
+        gestureStartUptimeMs: data.gestureStartUptimeMs,
+        gestureEndUptimeMs: data.gestureEndUptimeMs,
+        gestureFallback: data.gestureFallback,
+        gestureFallbackMessage: data.gestureFallbackMessage,
+        gestureFallbackHint: data.gestureFallbackHint
+      )
+    )
+  }
+
+  func plannedGestureResponse(
+    plan: RunnerGesturePlan,
+    timing: (gestureStartUptimeMs: Double, gestureEndUptimeMs: Double),
+    outcome: RunnerInteractionOutcome
+  ) -> Response {
+    if let response = unsupportedResponse(for: outcome) {
+      return response
+    }
+    return gestureResponse(message: plan.intent, timing: timing)
+  }
+}
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+ScrollDragExecution.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+ScrollDragExecution.swift
new file mode 100644
index 0000000000..022a23d61c
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+ScrollDragExecution.swift
@@ -0,0 +1,287 @@
+import XCTest
+import AgentDeviceSnapshotPresentation
+
+extension RunnerTests {
+  func invalidScrollDirectionResponse(commandName: String) -> Response {
+    Response(
+      ok: false,
+      error: ErrorPayload(
+        code: "INVALID_ARGS",
+        message: "\(commandName) requires direction up|down|left|right"
+      )
+    )
+  }
+
+  func scrollDurationIsValid(_ durationMs: Double?) -> Bool {
+    guard let durationMs else { return true }
+    return durationMs.isFinite && durationMs >= 0 && durationMs <= 10000
+  }
+
+  func invalidScrollDurationResponse(commandName: String) -> Response {
+    return Response(
+      ok: false,
+      error: ErrorPayload(
+        code: "INVALID_ARGS",
+        message: "\(commandName) durationMs must be between 0 and 10000"
+      )
+    )
+  }
+
+  func executeScrollDragGesture(
+    activeApp: XCUIApplication,
+    x: Double,
+    y: Double,
+    x2: Double,
+    y2: Double,
+    durationMs: Double,
+    message: String,
+    context: SynthesizedCoordinateContext,
+    releaseBehavior: ScrollReleaseBehavior?
+  ) -> Response {
+#if os(iOS)
+    return executeDragGesture(
+      activeApp: activeApp,
+      x: x,
+      y: y,
+      x2: x2,
+      y2: y2,
+      durationMs: durationMs,
+      message: message,
+      synthesizedContext: context,
+      synthesized: (profile: scrollDragProfile(releaseBehavior: releaseBehavior), policyKind: .scroll)
+    )
+#else
+    return executeDragGesture(
+      activeApp: activeApp,
+      x: x,
+      y: y,
+      x2: x2,
+      y2: y2,
+      durationMs: durationMs,
+      message: message
+    )
+#endif
+  }
+
+  /// Shared coordinate drag execution. Callers that pass `synthesized` take the iOS synthesized
+  /// lane with that profile and fallback policy; the rest perform an XCTest coordinate drag.
+  func executeDragGesture(
+    activeApp: XCUIApplication,
+    x: Double,
+    y: Double,
+    x2: Double,
+    y2: Double,
+    durationMs: Double?,
+    message: String,
+    synthesizedContext: SynthesizedCoordinateContext? = nil,
+    synthesized: (profile: SynthesizedDragProfile, policyKind: SynthesizedGesturePolicyKind)? = nil
+  ) -> Response {
+    let durationMs = durationMs ?? runnerDefaultDragDurationMs
+    let commandName = dragCommandName(message: message)
+    guard x.isFinite, y.isFinite, x2.isFinite, y2.isFinite else {
+      return Response(
+        ok: false,
+        error: ErrorPayload(code: "INVALID_ARGS", message: "\(commandName) requires finite coordinates")
+      )
+    }
+    if let synthesized, let synthesizedResponse = executeSynthesizedDragGesture(
+      activeApp: activeApp,
+      x: x,
+      y: y,
+      x2: x2,
+      y2: y2,
+      durationMs: durationMs,
+      message: message,
+      context: synthesizedContext,
+      policyKind: synthesized.policyKind,
+      profile: synthesized.profile
+    ) {
+      return synthesizedResponse
+    }
+    let dragPoints = keyboardAvoidingDragPoints(app: activeApp, x: x, y: y, x2: x2, y2: y2)
+    let dragFrame = resolvedDragVisualizationFrame(
+      app: activeApp,
+      x: dragPoints.x,
+      y: dragPoints.y,
+      x2: dragPoints.x2,
+      y2: dragPoints.y2
+    )
+    let holdDuration = synthesized == nil
+      ? coordinateDragHoldDuration()
+      : synthesizedSwipeFallbackHoldDuration(durationMs: durationMs)
+    let (timing, outcome) = performGesture(activeApp) {
+      dragAt(
+        app: activeApp,
+        x: dragPoints.x,
+        y: dragPoints.y,
+        x2: dragPoints.x2,
+        y2: dragPoints.y2,
+        holdDuration: holdDuration
+      )
+    }
+    if let response = unsupportedResponse(for: outcome) {
+      return response
+    }
+    return gestureResponse(message: message, timing: timing, frame: .drag(dragFrame))
+  }
+
+  private func executeSynthesizedDragGesture(
+    activeApp: XCUIApplication,
+    x: Double,
+    y: Double,
+    x2: Double,
+    y2: Double,
+    durationMs: Double,
+    message: String,
+    context: SynthesizedCoordinateContext?,
+    policyKind: SynthesizedGesturePolicyKind,
+    profile: SynthesizedDragProfile
+  ) -> Response? {
+#if os(iOS)
+    let policy = synthesizedGesturePolicy(policyKind)
+    let context = context ?? synthesizedCoordinateContext(app: activeApp, policy: policy)
+    guard let plan = axFreeSynthesizedDragPlan(
+      app: activeApp,
+      x: x,
+      y: y,
+      x2: x2,
+      y2: y2,
+      context: context
+    )
+    else {
+      if context?.allowsXCTestCoordinateFallback == true {
+        logSynthesizedGesturePolicyDecision(kind: policyKind, context: context, fallbackAttempted: true)
+        return executeCoordinateDragFallback(
+          activeApp: activeApp,
+          x: x,
+          y: y,
+          x2: x2,
+          y2: y2,
+          durationMs: durationMs,
+          message: message,
+          fallback: nil
+        )
+      }
+      logSynthesizedGesturePolicyDecision(kind: policyKind, context: context, fallbackAttempted: false)
+      return Response(
+        ok: false,
+        error: ErrorPayload(
+          code: "INVALID_ARGS",
+          message: "\(dragCommandName(message: message)) could not resolve a finite synthesized coordinate frame"
+        )
+      )
+    }
+    let durationMs = min(max(durationMs, 16), 10000)
+    let dragFrame = axFreeDragVisualizationFrame(
+      x: plan.points.x,
+      y: plan.points.y,
+      x2: plan.points.x2,
+      y2: plan.points.y2,
+      referenceFrame: plan.referenceFrame
+    )
+    let (timing, outcome) = performGesture(activeApp, idleTimeout: false) {
+      synthesizedDragAt(
+        app: activeApp,
+        x: plan.points.x,
+        y: plan.points.y,
+        x2: plan.points.x2,
+        y2: plan.points.y2,
+        durationMs: durationMs,
+        profile: profile,
+        context: plan.context
+      )
+    }
+    if case .performed = outcome {
+      logSynthesizedGesturePolicyDecision(kind: policyKind, context: plan.context, fallbackAttempted: false)
+      return gestureResponse(message: message, timing: timing, frame: .drag(dragFrame))
+    }
+    if plan.context.allowsXCTestCoordinateFallback {
+      logSynthesizedGesturePolicyDecision(kind: policyKind, context: plan.context, fallbackAttempted: true)
+      return executeCoordinateDragFallback(
+        activeApp: activeApp,
+        x: plan.points.x,
+        y: plan.points.y,
+        x2: plan.points.x2,
+        y2: plan.points.y2,
+        durationMs: durationMs,
+        message: message,
+        fallback: gestureFallback(strategy: "xctest-coordinate-drag", from: outcome)
+      )
+    }
+    logSynthesizedGesturePolicyDecision(kind: policyKind, context: plan.context, fallbackAttempted: false)
+    return unsupportedResponse(for: outcome)
+#else
+    return nil
+#endif
+  }
+
+  private func executeCoordinateDragFallback(
+    activeApp: XCUIApplication,
+    x: Double,
+    y: Double,
+    x2: Double,
+    y2: Double,
+    durationMs: Double,
+    message: String,
+    fallback: GestureFallback?
+  ) -> Response {
+    let dragPoints = keyboardAvoidingDragPoints(app: activeApp, x: x, y: y, x2: x2, y2: y2)
+    let dragFrame = resolvedDragVisualizationFrame(
+      app: activeApp,
+      x: dragPoints.x,
+      y: dragPoints.y,
+      x2: dragPoints.x2,
+      y2: dragPoints.y2
+    )
+    let holdDuration = synthesizedSwipeFallbackHoldDuration(durationMs: durationMs)
+    let (timing, outcome) = performGesture(activeApp) {
+      dragAt(
+        app: activeApp,
+        x: dragPoints.x,
+        y: dragPoints.y,
+        x2: dragPoints.x2,
+        y2: dragPoints.y2,
+        holdDuration: holdDuration
+      )
+    }
+    if let response = unsupportedResponse(for: outcome) {
+      return response
+    }
+    return gestureResponse(
+      message: message,
+      timing: timing,
+      frame: .drag(dragFrame),
+      fallback: fallback
+    )
+  }
+
+  /// Adds the #2500 avoidance evidence to a scroll response. Only the frame resolver knows whether
+  /// it trimmed the swipe for a keyboard, and only `scroll` has this evidence to carry, so it is
+  /// attached where the frame was resolved rather than threaded through every gesture response.
+  /// The refusal a keyboard forces. It performs no gesture: swiping into the keys would leave the
+  /// surface where it was, which the daemon's no-progress fingerprint reads as a stuck container
+  /// (#2499) and an agent reads as a broken scroll. The TS owner maps the code to the
+  /// `scroll_keyboard_occludes_surface` reason and the "dismiss the keyboard" hint.
+  func scrollKeyboardOccludedResponse(
+    direction: String,
+    keyboardMinY: Double,
+    visibleHeight: Double
+  ) -> Response {
+    return Response(
+      ok: false,
+      error: ErrorPayload(
+        code: ScrollViewportPolicy.occlusionRunnerCode,
+        message: String(
+          format:
+            "scroll %@ refused: the keyboard leaves %.0fpt of visible surface above it, too little to swipe",
+          direction,
+          visibleHeight
+        )
+      )
+    )
+  }
+
+  private func dragCommandName(message: String) -> String {
+    return message == "scrolled" ? "scroll" : "drag"
+  }
+}
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotExecution.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotExecution.swift
new file mode 100644
index 0000000000..d17d79eeba
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotExecution.swift
@@ -0,0 +1,151 @@
+import XCTest
+import AgentDeviceSnapshotPresentation
+
+extension RunnerTests {
+  func executeSnapshotDispatched(command: Command) throws -> Response {
+    try executeDispatchedWithRecovery(command: command) {
+      try self.executeSnapshotDispatchedOnce(command: command)
+    }
+  }
+
+  private func executeSnapshotDispatchedOnce(command: Command) throws -> Response {
+    let preparation = try runMainThreadWork(
+      "command_preparation",
+      timeout: mainThreadExecutionTimeout,
+      timeoutError: mainThreadExecutionTimeoutError
+    ) {
+      try self.prepareActiveCommandContextSafely(command: command, routeToSpringboard: false)
+    }
+    switch preparation {
+    case .response(let response):
+      return response
+    case .context(let context):
+      return try executeSnapshotPrepared(
+        command: command,
+        activeApp: context.app,
+        systemSurface: context.systemSurface
+      )
+    }
+  }
+
+  private func prepareActiveCommandContextSafely(
+    command: Command,
+    routeToSpringboard: Bool
+  ) throws -> ActiveCommandPreparation {
+    var preparation: ActiveCommandPreparation?
+    let exceptionMessage = RunnerObjCExceptionCatcher.catchException({
+      preparation = self.prepareActiveCommandContext(
+        command: command,
+        routeToSpringboard: routeToSpringboard
+      )
+    })
+    if let exceptionMessage {
+      throw NSError(
+        domain: RunnerErrorDomain.exception,
+        code: RunnerErrorCode.objcException,
+        userInfo: [NSLocalizedDescriptionKey: exceptionMessage]
+      )
+    }
+    guard let preparation else {
+      throw NSError(
+        domain: RunnerErrorDomain.general,
+        code: RunnerErrorCode.commandReturnedNoResponse,
+        userInfo: [NSLocalizedDescriptionKey: "snapshot preflight returned no response"]
+      )
+    }
+    return preparation
+  }
+
+  /// Pure command→options projection, extracted so the runner unit bundle can
+  /// prove the decoded wire field actually reaches presentation options (#1634 P2).
+  static func presentationOptions(from command: Command) -> PresentationOptions {
+    let customActions = command.customActions ?? false
+    return PresentationOptions(
+      interactiveOnly: command.interactiveOnly ?? false,
+      depth: command.depth,
+      scope: command.scope,
+      raw: command.raw ?? false,
+      // Custom actions are only readable through the private AX client, so
+      // asking for them pins that backend rather than silently returning a
+      // capture that structurally cannot carry them. An explicit pin wins.
+      preferredBackend: command.preferredBackend
+        ?? (customActions ? SnapshotBackendKind.privateAX.rawValue : nil),
+      customActions: customActions
+    )
+  }
+
+  private func executeSnapshotPrepared(
+    command: Command,
+    activeApp: XCUIApplication,
+    systemSurface: SystemSurfaceHost?
+  ) throws -> Response {
+    let options = Self.presentationOptions(from: command)
+    do {
+      var payload: DataPayload
+      if options.raw {
+        payload = try snapshotRaw(app: activeApp, options: options)
+      } else {
+        payload = try snapshotFast(app: activeApp, options: options)
+      }
+      if let systemSurface {
+        payload.systemSurface = SystemSurfaceProvenancePayload(
+          bundleId: systemSurface.bundleId,
+          kind: systemSurface.kind.rawValue
+        )
+      }
+      setNeedsPostSnapshotInteractionDelay()
+      return Response(ok: true, data: payload)
+    } catch let failure as SnapshotCaptureFailure {
+      invalidateCachedTargetAfterSnapshotFailure()
+      return Response(
+        ok: false,
+        error: ErrorPayload(
+          code: failure.code,
+          message: failure.message,
+          hint: failure.hint
+        )
+      )
+    }
+  }
+
+  func setNeedsPostSnapshotInteractionDelay() {
+    guard !hasAbandonedMainThreadWork() else {
+      NSLog("AGENT_DEVICE_RUNNER_POST_SNAPSHOT_DELAY_MARK_SKIPPED_XCTEST_OCCUPIED")
+      return
+    }
+    do {
+      try runMainThreadWork(
+        "post_snapshot_delay_mark",
+        timeout: 1,
+        timeoutError: mainThreadExecutionTimeoutError
+      ) {
+        self.needsPostSnapshotInteractionDelay = true
+      }
+    } catch {
+      NSLog("AGENT_DEVICE_RUNNER_POST_SNAPSHOT_DELAY_MARK_FAILED=%@", String(describing: error))
+    }
+  }
+
+  func invalidateCachedTargetAfterSnapshotFailure() {
+    // Abandoned work ahead of this hop cannot be cancelled: queue the drop behind it without
+    // waiting, so the failed capture answers now and the next command still finds the target gone.
+    guard !hasAbandonedMainThreadWork() else {
+      NSLog("AGENT_DEVICE_RUNNER_SNAPSHOT_INVALIDATION_DEFERRED_XCTEST_OCCUPIED")
+      DispatchQueue.main.async {
+        self.invalidateCachedTarget(reason: "ax_snapshot_failure")
+      }
+      return
+    }
+    do {
+      try runMainThreadWork(
+        "target_invalidation",
+        timeout: 1,
+        timeoutError: mainThreadExecutionTimeoutError
+      ) {
+        self.invalidateCachedTarget(reason: "ax_snapshot_failure")
+      }
+    } catch {
+      NSLog("AGENT_DEVICE_RUNNER_SNAPSHOT_INVALIDATION_FAILED=%@", String(describing: error))
+    }
+  }
+}
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+TypeExecution.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+TypeExecution.swift
new file mode 100644
index 0000000000..2150047869
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+TypeExecution.swift
@@ -0,0 +1,142 @@
+import XCTest
+import AgentDeviceSnapshotPresentation
+
+extension RunnerTests {
+  func executeTypeCommand(activeApp: XCUIApplication, command: Command) -> Response {
+    guard let text = command.text else {
+      return Response(ok: false, error: ErrorPayload(message: "type requires text"))
+    }
+    let delaySeconds = Double(max(command.delayMs ?? 0, 0)) / 1000.0
+    let textEntryMode = resolveTextEntryMode(command)
+    let target: TextEntryTarget
+    var resolvedCoordinateContext: SynthesizedCoordinateContext?
+    // The shared runtime has already resolved this node as non-hittable and
+    // deliberately selected Maestro's coordinate compatibility route.
+    let maestroNonHittableCoordinateFallbackUsed: Bool? =
+      command.allowNonHittableCoordinateFallback == true && command.x != nil && command.y != nil
+      ? true
+      : nil
+    let focusStartedAt = Date()
+#if os(iOS)
+    let xCTestChannelPenalized = isSnapshotXCTestChannelPenalized(bundleId: currentBundleId)
+    var resolvedCoordinateTarget: TextEntryTarget?
+    if Self.shouldUseResolvedCoordinateTextEntryRoute(
+      repairMode: textEntryMode,
+      hasX: command.x != nil,
+      hasY: command.y != nil,
+      xCTestChannelPenalized: xCTestChannelPenalized
+    ), let x = command.x, let y = command.y {
+      let policyKind = SynthesizedGesturePolicyKind.coordinateTap
+      let context = synthesizedCoordinateContext(
+        app: activeApp,
+        policy: synthesizedGesturePolicy(policyKind)
+      )
+      let (_, outcome) = performGesture(activeApp, idleTimeout: false) {
+        synthesizedTapAt(app: activeApp, x: x, y: y, context: context)
+      }
+      if Self.shouldFallbackFromSynthesizedTextEntryFocus(outcome) {
+        logSynthesizedGesturePolicyDecision(
+          kind: policyKind,
+          context: context,
+          fallbackAttempted: true
+        )
+      } else {
+        logSynthesizedGesturePolicyDecision(
+          kind: policyKind,
+          context: context,
+          fallbackAttempted: false
+        )
+        resolvedCoordinateContext = context
+        resolvedCoordinateTarget = TextEntryTarget(
+          element: nil,
+          refreshPoint: CGPoint(x: x, y: y),
+          prefersFocusedElement: false
+        )
+      }
+    }
+#else
+    let xCTestChannelPenalized = false
+    let resolvedCoordinateTarget: TextEntryTarget? = nil
+#endif
+    if let resolvedCoordinateTarget {
+      target = resolvedCoordinateTarget
+    } else {
+      target = focusTextInputForTextEntry(app: activeApp, x: command.x, y: command.y)
+    }
+    NSLog(
+      "AGENT_DEVICE_RUNNER_TEXT_ENTRY_PHASE commandId=%@ phase=focus durationMs=%.1f chars=%d mode=%@",
+      command.commandId ?? "",
+      Date().timeIntervalSince(focusStartedAt) * 1000.0,
+      text.count,
+      textEntryModeName(textEntryMode)
+    )
+    if textEntryMode == .replacement {
+#if os(iOS)
+      let canReplaceResolvedFirstResponder = Self.shouldUseSynthesizedFirstResponderReplacement(
+        hasResolvedElement: target.element != nil,
+        hasRefreshPoint: target.refreshPoint != nil,
+        xCTestChannelPenalized: xCTestChannelPenalized
+      )
+#else
+      let canReplaceResolvedFirstResponder = false
+#endif
+      guard target.element != nil || canReplaceResolvedFirstResponder else {
+        let message =
+          (command.x != nil && command.y != nil)
+          ? "no text input found at the provided coordinates to clear"
+          : "no focused text input to clear"
+        return Response(ok: false, error: ErrorPayload(message: message))
+      }
+    }
+    let textResult = typeTextReliably(
+      app: activeApp,
+      target: target,
+      text: text,
+      delaySeconds: delaySeconds,
+      repairMode: textEntryMode,
+      xCTestChannelPenalized: xCTestChannelPenalized,
+      synthesizer: PrivateXCTestTextEntrySynthesizer(),
+      commandId: command.commandId
+    )
+    if let failure = textResult.failure {
+      return Response(
+        ok: false,
+        error: ErrorPayload(code: failure.rawValue, message: failure.message, hint: failure.hint)
+      )
+    }
+    if textResult.verified == false {
+      let expected = textResult.expectedText ?? ""
+      let observed = textResult.observedText ?? ""
+      return Response(
+        ok: false,
+        error: ErrorPayload(
+          code: "TEXT_ENTRY_MISMATCH",
+          message: "text entry verification failed: expected \"\(expected)\", observed \"\(observed)\""
+        )
+      )
+    }
+    let point = target.refreshPoint
+    let frame: CGRect
+    if let resolvedCoordinateContext {
+      frame = resolvedCoordinateContext.referenceFrame
+    } else if point != nil {
+      frame = activeApp.frame
+    } else {
+      // Bare `type` has no coordinate response to normalize. Avoid serializing the
+      // application AX tree only to emit unused reference dimensions.
+      frame = .zero
+    }
+    return Response(
+      ok: true,
+      data: DataPayload(
+        message: textResult.repaired ? "typed after repair" : "typed",
+        x: point.map { Double($0.x) },
+        y: point.map { Double($0.y) },
+        referenceWidth: frame.isEmpty ? nil : Double(frame.width),
+        referenceHeight: frame.isEmpty ? nil : Double(frame.height),
+        maestroNonHittableCoordinateFallbackUsed: maestroNonHittableCoordinateFallbackUsed,
+        textEntryRoute: textResult.textEntryRoute
+      )
+    )
+  }
+}
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+CommandDispatchTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+CommandDispatchTests.swift
new file mode 100644
index 0000000000..dee860248e
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+CommandDispatchTests.swift
@@ -0,0 +1,409 @@
+import XCTest
+import AgentDeviceSnapshotPresentation
+
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS
+extension RunnerTests {
+  func testInjectedTapRecordedFailureGateIsTapOnlyAndCountGated() {
+    // The seam's recording side cannot run in-bundle (a real XCTIssue would
+    // fail this very test run — same constraint the record(_:) suppression
+    // tests document); the live daemon proof covers it. This pins the gate.
+    XCTAssertFalse(RunnerTests.shouldInjectTapRecordedFailure(command: .tap, remaining: 0))
+    XCTAssertTrue(RunnerTests.shouldInjectTapRecordedFailure(command: .tap, remaining: 1))
+    XCTAssertFalse(RunnerTests.shouldInjectTapRecordedFailure(command: .type, remaining: 1))
+    XCTAssertFalse(RunnerTests.shouldInjectTapRecordedFailure(command: .snapshot, remaining: 1))
+  }
+
+  func testXCTestRecordedFailureResponseFailsMutatingSuccesses() throws {
+    let command = try runnerCommandFixture(#"{"command":"tap","commandId":"tap-1"}"#)
+    let response = Response(ok: true, data: DataPayload(message: "tapped"))
+
+    let failureResponse = xctestRecordedFailureResponse(command: command, response: response)
+
+    XCTAssertEqual(failureResponse?.ok, false)
+    XCTAssertEqual(failureResponse?.error?.code, "XCTEST_RECORDED_FAILURE")
+    XCTAssertEqual(
+      failureResponse?.error?.message,
+      "XCTest recorded a failure while executing tap; the action may not have been performed."
+    )
+  }
+
+  func testXCTestRecordedFailureResponseFailsActionButtonSuccess() throws {
+    // The Action Button press carries no settle and no post-action observation, so this conversion is
+    // the only evidence the press landed. That is why the press is not classified runner-lifecycle:
+    // `isLifecycle` would silence the conversion here (#2699, #2702 review).
+    let command = try runnerCommandFixture(#"{"command":"actionButton","commandId":"action-button-1"}"#)
+    let response = Response(ok: true, data: DataPayload(message: "actionButton"))
+
+    let failureResponse = xctestRecordedFailureResponse(command: command, response: response)
+
+    XCTAssertEqual(failureResponse?.ok, false)
+    XCTAssertEqual(failureResponse?.error?.code, "XCTEST_RECORDED_FAILURE")
+    XCTAssertEqual(
+      failureResponse?.error?.message,
+      "XCTest recorded a failure while executing actionButton; the action may not have been performed."
+    )
+  }
+
+  func testXCTestRecordedFailureResponseDoesNotWrapReadOnlyOrRunnerFatalResponses() throws {
+    let snapshotCommand = try runnerCommandFixture(#"{"command":"snapshot","commandId":"snapshot-1"}"#)
+    let tapCommand = try runnerCommandFixture(#"{"command":"tap","commandId":"tap-1"}"#)
+    let runnerFatalResponse = Response(
+      ok: true,
+      data: DataPayload(runnerFatal: true, runnerFatalReason: "ax_snapshot_unavailable")
+    )
+
+    XCTAssertNil(
+      xctestRecordedFailureResponse(
+        command: snapshotCommand,
+        response: Response(ok: true, data: DataPayload(nodes: [], truncated: false))
+      )
+    )
+    XCTAssertNil(xctestRecordedFailureResponse(command: tapCommand, response: runnerFatalResponse))
+  }
+
+  // Simulator-only from here to the matching #endif: these launch the host app, route through
+  // SpringBoard, or assert the iOS-only alert/system-modal branches. Tests outside the
+  // `os(iOS)` regions in this file are pure runner decisions and also run on the macOS host
+  // lane (ci.yml) — see the classification convention in RunnerTests.swift.
+#if os(iOS)
+  func testMissingBundleCommandInvalidatesCompleteCachedTargetState() throws {
+    app.launch()
+    currentApp = app
+    currentBundleId = "com.example.stale-target"
+    currentAppProcessIdentifier = 42
+    snapshotXCTestPenaltyWarmupExemptionPending = true
+    defer {
+      invalidateCachedTarget(reason: "unit_test_cleanup")
+      app.terminate()
+    }
+    let command = try runnerCommandFixture(
+      #"{"command":"snapshot","commandId":"snapshot-without-bundle"}"#
+    )
+
+    _ = prepareActiveCommandContext(command: command)
+
+    XCTAssertNil(currentApp)
+    XCTAssertNil(currentBundleId)
+    XCTAssertNil(currentAppProcessIdentifier)
+    XCTAssertFalse(snapshotXCTestPenaltyWarmupExemptionPending)
+  }
+
+  func testSkipAppActivationPreflightIncludesForegroundCachedCoordinateOnlyTaps() throws {
+    app.launch()
+    currentApp = app
+    currentBundleId = nil
+    defer {
+      currentApp = nil
+      currentBundleId = nil
+      app.terminate()
+    }
+    let tap = try runnerCommandFixture(
+      #"{"command":"tap","commandId":"tap-1","x":10,"y":20}"#
+    )
+
+    XCTAssertTrue(shouldSkipAppActivationPreflight(tap))
+  }
+
+  func testSkipAppActivationPreflightRejectsMissingChangedAndBackgroundTargets() throws {
+    let coordinateTap = try runnerCommandFixture(
+      #"{"command":"tap","commandId":"tap-1","x":10,"y":20}"#
+    )
+    currentApp = nil
+    currentBundleId = nil
+    XCTAssertFalse(shouldSkipAppActivationPreflight(coordinateTap))
+
+    app.launch()
+    currentApp = app
+    currentBundleId = "com.example.current"
+    defer {
+      currentApp = nil
+      currentBundleId = nil
+      app.terminate()
+    }
+    let changedBundleTap = try runnerCommandFixture(
+      #"{"command":"tap","commandId":"tap-2","appBundleId":"com.example.other","x":10,"y":20}"#
+    )
+
+    XCTAssertFalse(shouldSkipAppActivationPreflight(changedBundleTap))
+
+    app.terminate()
+    currentApp = app
+    currentBundleId = nil
+
+    XCTAssertFalse(shouldSkipAppActivationPreflight(coordinateTap))
+  }
+
+  func testActionButtonPressSkipsAppActivationPreflightWithoutBeingRunnerLifecycle() throws {
+    currentApp = nil
+    currentBundleId = nil
+    let press = try runnerCommandFixture(#"{"command":"actionButton","commandId":"action-button-1"}"#)
+
+    // The skip is its own decision, reached without the lifecycle flag that would also drop the
+    // recorded-failure conversion; no cached target and no foreground app is required for it.
+    XCTAssertFalse(isRunnerLifecycleCommand(.actionButton))
+    XCTAssertTrue(shouldSkipAppActivationPreflight(press))
+  }
+
+  func testPrepareActiveCommandContextRoutesBlockingSystemModalToSpringboard() throws {
+    blockingSystemModalPresenceOverrideForTesting = true
+    currentApp = nil
+    currentBundleId = nil
+    defer {
+      blockingSystemModalPresenceOverrideForTesting = nil
+      currentApp = nil
+      currentBundleId = nil
+    }
+    let tap = try runnerCommandFixture(
+      #"{"command":"tap","commandId":"tap-1","x":10,"y":20}"#
+    )
+
+    let preparation = prepareActiveCommandContext(
+      command: tap,
+      routeToSpringboard: shouldRouteToSpringboardBlockingSystemModal(tap)
+    )
+
+    guard case .context(let context) = preparation else {
+      XCTFail("expected command context")
+      return
+    }
+    XCTAssertTrue(context.app === springboard)
+  }
+
+  func testExecuteDispatchedReturnsBusyBeforeBlockingSystemModalProbeDrains() throws {
+    app.launch()
+    currentApp = app
+    currentBundleId = nil
+    defer {
+      currentApp = nil
+      currentBundleId = nil
+      systemModalProbeOverrideForTesting = nil
+      clearSnapshotXCTestChannelPenalty(reason: "test-cleanup")
+      app.terminate()
+    }
+
+    final class ResultBox {
+      var response: Response?
+      var error: Error?
+      var commandRecoveredBeforeRelease = false
+      var wasBusyBeforeRelease = false
+      var hadAbandonedProbeBeforeRelease = false
+      var drained = false
+    }
+    let box = ResultBox()
+    let probeStarted = expectation(description: "system-modal routing probe started")
+    let verificationFinished = expectation(description: "command recovery and modal probe drain verified")
+    let probeReleaseGate = DispatchSemaphore(value: 0)
+    let commandFinishedGate = DispatchSemaphore(value: 0)
+    systemModalProbeOverrideForTesting = { _ in
+      probeStarted.fulfill()
+      _ = probeReleaseGate.wait(timeout: .now() + 15)
+      return DataPayload(message: "late system modal")
+    }
+
+    let command = try runnerCommandFixture(
+      #"{"command":"tap","commandId":"bounded-modal-routing","x":10,"y":20}"#
+    )
+    DispatchQueue(label: "agent-device.runner.tests.modal-routing-probe").async {
+      do {
+        box.response = try self.executeDispatched(command: command)
+      } catch {
+        box.error = error
+      }
+      commandFinishedGate.signal()
+    }
+    DispatchQueue(label: "agent-device.runner.tests.modal-routing-probe-verifier").async {
+      let commandWait = commandFinishedGate.wait(
+        timeout: .now() + self.systemModalProbeBudget + 3
+      )
+      box.commandRecoveredBeforeRelease = commandWait == .success
+        && box.error == nil
+        && box.response?.error?.code == "RUNNER_BUSY"
+      if case .busy = self.currentMainThreadBusyState() {
+        box.wasBusyBeforeRelease = true
+      }
+      box.hadAbandonedProbeBeforeRelease = self.hasAbandonedMainThreadWork()
+
+      // The XCTest main thread is blocked inside the injected probe, so this verifier owns the
+      // ordered release after recording the command result and abandoned-work state above.
+      probeReleaseGate.signal()
+      let deadline = Date().addingTimeInterval(5)
+      while self.hasAbandonedMainThreadWork(), Date() < deadline {
+        self.sleepFor(0.002)
+      }
+      box.drained = !self.hasAbandonedMainThreadWork()
+      verificationFinished.fulfill()
+    }
+
+    wait(for: [probeStarted, verificationFinished], timeout: 15)
+    XCTAssertTrue(
+      box.commandRecoveredBeforeRelease,
+      "the public coordinate tap must return RUNNER_BUSY before the blocked modal probe drains"
+    )
+    XCTAssertTrue(box.wasBusyBeforeRelease)
+    XCTAssertTrue(box.hadAbandonedProbeBeforeRelease)
+    XCTAssertTrue(box.drained)
+    guard case .idle = currentMainThreadBusyState() else {
+      return XCTFail("expected the runner to become idle after the routing probe drained")
+    }
+    XCTAssertFalse(hasAbandonedMainThreadWork())
+  }
+
+  func testSkipAppActivationPreflightRejectsSelectorAndMixedSequenceGestures() throws {
+    app.launch()
+    currentApp = app
+    currentBundleId = nil
+    defer {
+      currentApp = nil
+      currentBundleId = nil
+      app.terminate()
+    }
+    let selectorTap = try runnerCommandFixture(
+      #"{"command":"tap","commandId":"tap-1","selectorKey":"label","selectorValue":"Search","synthesized":true}"#
+    )
+    let standardDrag = try runnerCommandFixture(
+      #"{"command":"drag","commandId":"drag-1","x":10,"y":20,"x2":30,"y2":40}"#
+    )
+    let mixedSequence = try runnerCommandFixture(
+      """
+      {"command":"sequence","commandId":"seq-1","steps":[
+        {"kind":"tap","x":10,"y":20,"synthesized":true},
+        {"kind":"doubleTap","x":30,"y":40}
+      ]}
+      """
+    )
+
+    XCTAssertFalse(shouldSkipAppActivationPreflight(selectorTap))
+    XCTAssertFalse(shouldSkipAppActivationPreflight(standardDrag))
+    XCTAssertFalse(shouldSkipAppActivationPreflight(mixedSequence))
+  }
+
+  // Launches nothing, but still simulator-only: `shouldSkipAppActivationPreflight` is
+  // `#if os(iOS) …guards… #else return false #endif`, so on macOS this asserts a compile-time
+  // literal and no edit to the iOS body could make it red. Its five siblings above and below
+  // are gated for the same reason.
+  func testSkipAppActivationPreflightRequiresCachedForegroundTarget() throws {
+    currentApp = nil
+    currentBundleId = nil
+    let scroll = try runnerCommandFixture(
+      #"{"command":"scroll","commandId":"scroll-1","direction":"down","pixels":400}"#
+    )
+
+    XCTAssertFalse(shouldSkipAppActivationPreflight(scroll))
+  }
+
+  func testSkipAppActivationPreflightKeepsDragScrollAndSequenceOnForegroundGuard() throws {
+    app.launch()
+    currentApp = app
+    currentBundleId = nil
+    defer {
+      currentApp = nil
+      currentBundleId = nil
+      app.terminate()
+    }
+    let drag = try runnerCommandFixture(
+      #"{"command":"drag","commandId":"drag-1","x":10,"y":20,"x2":30,"y2":40}"#
+    )
+    let scroll = try runnerCommandFixture(
+      #"{"command":"scroll","commandId":"scroll-1","direction":"down","pixels":400}"#
+    )
+    let sequence = try runnerCommandFixture(
+      """
+      {"command":"sequence","commandId":"seq-1","steps":[
+        {"kind":"tap","x":10,"y":20,"synthesized":true},
+        {"kind":"longPress","x":10,"y":200,"durationMs":300}
+      ]}
+      """
+    )
+
+    XCTAssertFalse(shouldSkipAppActivationPreflight(drag))
+    XCTAssertFalse(shouldSkipAppActivationPreflight(scroll))
+    XCTAssertFalse(shouldSkipAppActivationPreflight(sequence))
+  }
+
+  func testSkipAppActivationPreflightIncludesAlertCommands() throws {
+    let alert = try runnerCommandFixture(
+      #"{"command":"alert","commandId":"alert-1","action":"get"}"#
+    )
+
+    XCTAssertTrue(shouldSkipAppActivationPreflight(alert))
+  }
+#endif
+
+  func testDispatchReturnsBusyBeforeQueueingMainThreadWork() throws {
+    let command = try runnerCommandFixture(#"{"command":"snapshot","commandId":"snapshot-busy"}"#)
+    abandonedMainThreadWorkCount = 1
+    abandonedMainThreadWorkSince = Date(timeIntervalSinceNow: -2)
+    defer {
+      abandonedMainThreadWorkCount = 0
+      abandonedMainThreadWorkSince = nil
+    }
+
+    let response = try execute(command: command)
+
+    XCTAssertFalse(response.ok)
+    XCTAssertEqual(response.error?.code, "RUNNER_BUSY")
+    XCTAssertTrue(response.error?.message.contains("previous command") == true)
+  }
+
+  func testDispatchReturnsWedgedBeforeQueueingMainThreadWork() throws {
+    let command = try runnerCommandFixture(#"{"command":"snapshot","commandId":"snapshot-wedged"}"#)
+    abandonedMainThreadWorkCount = 1
+    abandonedMainThreadWorkSince = Date(timeIntervalSinceNow: -(mainThreadWedgeThreshold + 1))
+    defer {
+      abandonedMainThreadWorkCount = 0
+      abandonedMainThreadWorkSince = nil
+    }
+
+    let response = try execute(command: command)
+
+    XCTAssertFalse(response.ok)
+    XCTAssertEqual(response.error?.code, "RUNNER_WEDGED")
+    XCTAssertTrue(response.error?.hint?.contains("runner session will be restarted") == true)
+  }
+
+  func testDispatchRecoverySkipsBookkeepingWhileXCTestChannelOccupied() {
+    // The #1244 recovery shape: the modal probe abandoned an XCTest query that is still grinding on
+    // main, the capture recovered independently, and its response is ready. The recovery loop must
+    // return it without re-entering the main queue for recorded-failure/retry bookkeeping (that hop
+    // would block behind the abandoned query and re-stall the command), and a later command must
+    // still see the runner busy until the abandoned work drains. Removing the guard regresses this.
+    let command = try! JSONDecoder().decode(
+      Command.self,
+      from: Data(#"{"command":"snapshot","commandId":"recovery-guard"}"#.utf8)
+    )
+    let recovered = Response(ok: false, error: .targetAppUnavailable(bundleId: nil))
+
+    setAbandonedMainThreadWork(1)
+    defer { setAbandonedMainThreadWork(0) }
+    guard case .busy = currentMainThreadBusyState() else {
+      return XCTFail("expected RUNNER_BUSY while abandoned XCTest work is outstanding")
+    }
+
+    var occupiedCalls = 0
+    let occupied = try! executeDispatchedWithRecovery(command: command) {
+      occupiedCalls += 1
+      return recovered
+    }
+    XCTAssertEqual(occupiedCalls, 1, "recovered response must not retry behind abandoned XCTest work")
+    XCTAssertEqual(occupied.ok, false)
+
+    setAbandonedMainThreadWork(0)
+    guard case .idle = currentMainThreadBusyState() else {
+      return XCTFail("runner should be idle once the abandoned work drained")
+    }
+    var drainedCalls = 0
+    _ = try! executeDispatchedWithRecovery(command: command) {
+      drainedCalls += 1
+      return recovered
+    }
+    XCTAssertEqual(drainedCalls, 2, "with the channel free the read-only retry runs once")
+  }
+
+  private func setAbandonedMainThreadWork(_ count: Int) {
+    mainThreadWorkLock.lock()
+    abandonedMainThreadWorkCount = count
+    abandonedMainThreadWorkSince = count > 0 ? Date(timeIntervalSinceNow: -1) : nil
+    mainThreadWorkLock.unlock()
+  }
+}
+#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+CommandExecutionTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+CommandExecutionTests.swift
index b763b9e07e..33d3a82a25 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+CommandExecutionTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+CommandExecutionTests.swift
@@ -4,21 +4,6 @@ import AgentDeviceSnapshotPresentation
 #if AGENT_DEVICE_RUNNER_UNIT_TESTS && os(iOS)
 import ObjectiveC.runtime
 
-private final class RunnerSynthesizedSwipeFailureStub: NSObject {
-  @objc(synthesizeSwipeWithApplication:resolvedWindow:x:y:x2:y2:durationMs:)
-  class func synthesizeSwipe(
-    application: XCUIApplication,
-    resolvedWindow: Any?,
-    x: Double,
-    y: Double,
-    x2: Double,
-    y2: Double,
-    durationMs: Double
-  ) -> String? {
-    "forced private synthesis failure"
-  }
-}
-
 private final class RunnerSynthesizedTapFailureStub: NSObject {
   @objc(synthesizeTapWithApplication:resolvedWindow:x:y:)
   class func synthesizeTap(application: XCUIApplication, resolvedWindow: Any?, x: Double, y: Double) -> String? {
@@ -29,119 +14,7 @@ private final class RunnerSynthesizedTapFailureStub: NSObject {
 
 #if AGENT_DEVICE_RUNNER_UNIT_TESTS
 extension RunnerTests {
-  func testGestureResponseIncludesSynthesizedTapFallbackDiagnostics() {
-    let response = gestureResponse(
-      message: "tapped",
-      timing: (gestureStartUptimeMs: 1, gestureEndUptimeMs: 2),
-      fallback: GestureFallback(
-        strategy: "xctest-coordinate-tap",
-        message: "Runner synthesized coordinate tap is unavailable",
-        hint: "Using XCTest coordinate tap fallback."
-      )
-    )
-
-    XCTAssertEqual(response.ok, true)
-    XCTAssertEqual(response.data?.gestureFallback, "xctest-coordinate-tap")
-    XCTAssertEqual(
-      response.data?.gestureFallbackMessage,
-      "Runner synthesized coordinate tap is unavailable"
-    )
-    XCTAssertEqual(response.data?.gestureFallbackHint, "Using XCTest coordinate tap fallback.")
-  }
-
-  func testGestureResponseIncludesMaestroNonHittableFallbackUsage() {
-    let response = gestureResponse(
-      message: "tapped via non-hittable coordinate fallback",
-      timing: (gestureStartUptimeMs: 1, gestureEndUptimeMs: 2),
-      frame: .touch(nil),
-      maestroNonHittableCoordinateFallbackUsed: true
-    )
-
-    XCTAssertEqual(response.data?.maestroNonHittableCoordinateFallbackUsed, true)
-  }
-
-  func testCanonicalPlannedGestureResponseOmitsDragFrameAndPreservesDiagnostics() {
-    let response = gestureResponse(
-      message: "fling",
-      timing: (gestureStartUptimeMs: 1, gestureEndUptimeMs: 2),
-      frame: .drag(
-        DragVisualizationFrame(
-          x: 160,
-          y: 150,
-          x2: 40,
-          y2: 150,
-          referenceWidth: 200,
-          referenceHeight: 300
-        )
-      ),
-      fallback: GestureFallback(
-        strategy: "xctest-coordinate-drag",
-        message: "Private synthesis unavailable",
-        hint: "Using XCTest coordinate fallback."
-      )
-    )
-
-    let canonical = canonicalPlannedGestureResponse(response)
-
-    XCTAssertEqual(canonical.data?.gestureStartUptimeMs, 1)
-    XCTAssertEqual(canonical.data?.gestureEndUptimeMs, 2)
-    XCTAssertEqual(canonical.data?.gestureFallback, "xctest-coordinate-drag")
-    XCTAssertEqual(canonical.data?.gestureFallbackMessage, "Private synthesis unavailable")
-    XCTAssertEqual(canonical.data?.gestureFallbackHint, "Using XCTest coordinate fallback.")
-    XCTAssertNil(canonical.data?.x)
-    XCTAssertNil(canonical.data?.y)
-    XCTAssertNil(canonical.data?.x2)
-    XCTAssertNil(canonical.data?.y2)
-    XCTAssertNil(canonical.data?.referenceWidth)
-    XCTAssertNil(canonical.data?.referenceHeight)
-  }
-
 #if os(iOS)
-  func testSinglePointerFlingFallsBackToXCTestCoordinateDragWhenPrivateSynthesisFails() throws {
-    let selector = NSSelectorFromString(
-      "synthesizeSwipeWithApplication:resolvedWindow:x:y:x2:y2:durationMs:"
-    )
-    guard
-      let synthesizedSwipeMethod = class_getClassMethod(RunnerSynthesizedGesture.self, selector),
-      let failureStubMethod = class_getClassMethod(RunnerSynthesizedSwipeFailureStub.self, selector)
-    else {
-      XCTFail("unable to install synthesized swipe failure stub")
-      return
-    }
-    let originalImplementation = method_getImplementation(synthesizedSwipeMethod)
-    method_setImplementation(
-      synthesizedSwipeMethod,
-      method_getImplementation(failureStubMethod)
-    )
-    app.launch()
-    runnerAccessibilityHealth = .healthy
-    defer {
-      method_setImplementation(synthesizedSwipeMethod, originalImplementation)
-      invalidateCachedTarget(reason: "unit_test_cleanup")
-      app.terminate()
-    }
-    let command = try runnerCommandFixture(
-      """
-      {"command":"gesture","commandId":"gesture-fling-fallback","gesturePlan":{"topology":"single","intent":"fling","executionProfile":"endpoint-hold","durationMs":100,"viewport":{"x":0,"y":0,"width":200,"height":300},"pointers":[{"pointerId":0,"samples":[{"offsetMs":0,"point":{"x":160,"y":150}},{"offsetMs":100,"point":{"x":40,"y":150}}]}]}}
-      """
-    )
-
-    let response = try executeOnMainPrepared(command: command, activeApp: app)
-
-    XCTAssertTrue(response.ok)
-    XCTAssertEqual(response.data?.message, "fling")
-    XCTAssertEqual(response.data?.gestureFallback, "xctest-coordinate-drag")
-    XCTAssertEqual(response.data?.gestureFallbackMessage, "forced private synthesis failure")
-    XCTAssertEqual(
-      response.data?.gestureFallbackHint,
-      "Private XCTest event synthesis is required for AX-free coordinate drag on iOS; update Xcode if this persists."
-    )
-    XCTAssertNil(response.data?.x)
-    XCTAssertNil(response.data?.y)
-    XCTAssertNil(response.data?.x2)
-    XCTAssertNil(response.data?.y2)
-  }
-
   func testSelectorTapFallsBackToXCTestCoordinateWhenPrivateSynthesisFails() throws {
     let selector = NSSelectorFromString("synthesizeTapWithApplication:resolvedWindow:x:y:")
     guard
@@ -232,473 +105,5 @@ extension RunnerTests {
     )
   }
 #endif
-
-  func testInjectedTapRecordedFailureGateIsTapOnlyAndCountGated() {
-    // The seam's recording side cannot run in-bundle (a real XCTIssue would
-    // fail this very test run — same constraint the record(_:) suppression
-    // tests document); the live daemon proof covers it. This pins the gate.
-    XCTAssertFalse(RunnerTests.shouldInjectTapRecordedFailure(command: .tap, remaining: 0))
-    XCTAssertTrue(RunnerTests.shouldInjectTapRecordedFailure(command: .tap, remaining: 1))
-    XCTAssertFalse(RunnerTests.shouldInjectTapRecordedFailure(command: .type, remaining: 1))
-    XCTAssertFalse(RunnerTests.shouldInjectTapRecordedFailure(command: .snapshot, remaining: 1))
-  }
-
-  func testXCTestRecordedFailureResponseFailsMutatingSuccesses() throws {
-    let command = try runnerCommandFixture(#"{"command":"tap","commandId":"tap-1"}"#)
-    let response = Response(ok: true, data: DataPayload(message: "tapped"))
-
-    let failureResponse = xctestRecordedFailureResponse(command: command, response: response)
-
-    XCTAssertEqual(failureResponse?.ok, false)
-    XCTAssertEqual(failureResponse?.error?.code, "XCTEST_RECORDED_FAILURE")
-    XCTAssertEqual(
-      failureResponse?.error?.message,
-      "XCTest recorded a failure while executing tap; the action may not have been performed."
-    )
-  }
-
-  func testXCTestRecordedFailureResponseFailsActionButtonSuccess() throws {
-    // The Action Button press carries no settle and no post-action observation, so this conversion is
-    // the only evidence the press landed. That is why the press is not classified runner-lifecycle:
-    // `isLifecycle` would silence the conversion here (#2699, #2702 review).
-    let command = try runnerCommandFixture(#"{"command":"actionButton","commandId":"action-button-1"}"#)
-    let response = Response(ok: true, data: DataPayload(message: "actionButton"))
-
-    let failureResponse = xctestRecordedFailureResponse(command: command, response: response)
-
-    XCTAssertEqual(failureResponse?.ok, false)
-    XCTAssertEqual(failureResponse?.error?.code, "XCTEST_RECORDED_FAILURE")
-    XCTAssertEqual(
-      failureResponse?.error?.message,
-      "XCTest recorded a failure while executing actionButton; the action may not have been performed."
-    )
-  }
-
-  func testXCTestRecordedFailureResponseDoesNotWrapReadOnlyOrRunnerFatalResponses() throws {
-    let snapshotCommand = try runnerCommandFixture(#"{"command":"snapshot","commandId":"snapshot-1"}"#)
-    let tapCommand = try runnerCommandFixture(#"{"command":"tap","commandId":"tap-1"}"#)
-    let runnerFatalResponse = Response(
-      ok: true,
-      data: DataPayload(runnerFatal: true, runnerFatalReason: "ax_snapshot_unavailable")
-    )
-
-    XCTAssertNil(
-      xctestRecordedFailureResponse(
-        command: snapshotCommand,
-        response: Response(ok: true, data: DataPayload(nodes: [], truncated: false))
-      )
-    )
-    XCTAssertNil(xctestRecordedFailureResponse(command: tapCommand, response: runnerFatalResponse))
-  }
-
-  // Simulator-only from here to the matching #endif: these launch the host app, route through
-  // SpringBoard, or assert the iOS-only alert/system-modal branches. Tests outside the
-  // `os(iOS)` regions in this file are pure runner decisions and also run on the macOS host
-  // lane (ci.yml) — see the classification convention in RunnerTests.swift.
-#if os(iOS)
-  func testMissingBundleCommandInvalidatesCompleteCachedTargetState() throws {
-    app.launch()
-    currentApp = app
-    currentBundleId = "com.example.stale-target"
-    currentAppProcessIdentifier = 42
-    snapshotXCTestPenaltyWarmupExemptionPending = true
-    defer {
-      invalidateCachedTarget(reason: "unit_test_cleanup")
-      app.terminate()
-    }
-    let command = try runnerCommandFixture(
-      #"{"command":"snapshot","commandId":"snapshot-without-bundle"}"#
-    )
-
-    _ = prepareActiveCommandContext(command: command)
-
-    XCTAssertNil(currentApp)
-    XCTAssertNil(currentBundleId)
-    XCTAssertNil(currentAppProcessIdentifier)
-    XCTAssertFalse(snapshotXCTestPenaltyWarmupExemptionPending)
-  }
-
-  func testSkipAppActivationPreflightIncludesForegroundCachedCoordinateOnlyTaps() throws {
-    app.launch()
-    currentApp = app
-    currentBundleId = nil
-    defer {
-      currentApp = nil
-      currentBundleId = nil
-      app.terminate()
-    }
-    let tap = try runnerCommandFixture(
-      #"{"command":"tap","commandId":"tap-1","x":10,"y":20}"#
-    )
-
-    XCTAssertTrue(shouldSkipAppActivationPreflight(tap))
-  }
-
-  func testSkipAppActivationPreflightRejectsMissingChangedAndBackgroundTargets() throws {
-    let coordinateTap = try runnerCommandFixture(
-      #"{"command":"tap","commandId":"tap-1","x":10,"y":20}"#
-    )
-    currentApp = nil
-    currentBundleId = nil
-    XCTAssertFalse(shouldSkipAppActivationPreflight(coordinateTap))
-
-    app.launch()
-    currentApp = app
-    currentBundleId = "com.example.current"
-    defer {
-      currentApp = nil
-      currentBundleId = nil
-      app.terminate()
-    }
-    let changedBundleTap = try runnerCommandFixture(
-      #"{"command":"tap","commandId":"tap-2","appBundleId":"com.example.other","x":10,"y":20}"#
-    )
-
-    XCTAssertFalse(shouldSkipAppActivationPreflight(changedBundleTap))
-
-    app.terminate()
-    currentApp = app
-    currentBundleId = nil
-
-    XCTAssertFalse(shouldSkipAppActivationPreflight(coordinateTap))
-  }
-
-  func testActionButtonPressSkipsAppActivationPreflightWithoutBeingRunnerLifecycle() throws {
-    currentApp = nil
-    currentBundleId = nil
-    let press = try runnerCommandFixture(#"{"command":"actionButton","commandId":"action-button-1"}"#)
-
-    // The skip is its own decision, reached without the lifecycle flag that would also drop the
-    // recorded-failure conversion; no cached target and no foreground app is required for it.
-    XCTAssertFalse(isRunnerLifecycleCommand(.actionButton))
-    XCTAssertTrue(shouldSkipAppActivationPreflight(press))
-  }
-
-  func testPrepareActiveCommandContextRoutesBlockingSystemModalToSpringboard() throws {
-    blockingSystemModalPresenceOverrideForTesting = true
-    currentApp = nil
-    currentBundleId = nil
-    defer {
-      blockingSystemModalPresenceOverrideForTesting = nil
-      currentApp = nil
-      currentBundleId = nil
-    }
-    let tap = try runnerCommandFixture(
-      #"{"command":"tap","commandId":"tap-1","x":10,"y":20}"#
-    )
-
-    let preparation = prepareActiveCommandContext(
-      command: tap,
-      routeToSpringboard: shouldRouteToSpringboardBlockingSystemModal(tap)
-    )
-
-    guard case .context(let context) = preparation else {
-      XCTFail("expected command context")
-      return
-    }
-    XCTAssertTrue(context.app === springboard)
-  }
-
-  func testExecuteDispatchedReturnsBusyBeforeBlockingSystemModalProbeDrains() throws {
-    app.launch()
-    currentApp = app
-    currentBundleId = nil
-    defer {
-      currentApp = nil
-      currentBundleId = nil
-      systemModalProbeOverrideForTesting = nil
-      clearSnapshotXCTestChannelPenalty(reason: "test-cleanup")
-      app.terminate()
-    }
-
-    final class ResultBox {
-      var response: Response?
-      var error: Error?
-      var commandRecoveredBeforeRelease = false
-      var wasBusyBeforeRelease = false
-      var hadAbandonedProbeBeforeRelease = false
-      var drained = false
-    }
-    let box = ResultBox()
-    let probeStarted = expectation(description: "system-modal routing probe started")
-    let verificationFinished = expectation(description: "command recovery and modal probe drain verified")
-    let probeReleaseGate = DispatchSemaphore(value: 0)
-    let commandFinishedGate = DispatchSemaphore(value: 0)
-    systemModalProbeOverrideForTesting = { _ in
-      probeStarted.fulfill()
-      _ = probeReleaseGate.wait(timeout: .now() + 15)
-      return DataPayload(message: "late system modal")
-    }
-
-    let command = try runnerCommandFixture(
-      #"{"command":"tap","commandId":"bounded-modal-routing","x":10,"y":20}"#
-    )
-    DispatchQueue(label: "agent-device.runner.tests.modal-routing-probe").async {
-      do {
-        box.response = try self.executeDispatched(command: command)
-      } catch {
-        box.error = error
-      }
-      commandFinishedGate.signal()
-    }
-    DispatchQueue(label: "agent-device.runner.tests.modal-routing-probe-verifier").async {
-      let commandWait = commandFinishedGate.wait(
-        timeout: .now() + self.systemModalProbeBudget + 3
-      )
-      box.commandRecoveredBeforeRelease = commandWait == .success
-        && box.error == nil
-        && box.response?.error?.code == "RUNNER_BUSY"
-      if case .busy = self.currentMainThreadBusyState() {
-        box.wasBusyBeforeRelease = true
-      }
-      box.hadAbandonedProbeBeforeRelease = self.hasAbandonedMainThreadWork()
-
-      // The XCTest main thread is blocked inside the injected probe, so this verifier owns the
-      // ordered release after recording the command result and abandoned-work state above.
-      probeReleaseGate.signal()
-      let deadline = Date().addingTimeInterval(5)
-      while self.hasAbandonedMainThreadWork(), Date() < deadline {
-        self.sleepFor(0.002)
-      }
-      box.drained = !self.hasAbandonedMainThreadWork()
-      verificationFinished.fulfill()
-    }
-
-    wait(for: [probeStarted, verificationFinished], timeout: 15)
-    XCTAssertTrue(
-      box.commandRecoveredBeforeRelease,
-      "the public coordinate tap must return RUNNER_BUSY before the blocked modal probe drains"
-    )
-    XCTAssertTrue(box.wasBusyBeforeRelease)
-    XCTAssertTrue(box.hadAbandonedProbeBeforeRelease)
-    XCTAssertTrue(box.drained)
-    guard case .idle = currentMainThreadBusyState() else {
-      return XCTFail("expected the runner to become idle after the routing probe drained")
-    }
-    XCTAssertFalse(hasAbandonedMainThreadWork())
-  }
-
-  func testSkipAppActivationPreflightRejectsSelectorAndMixedSequenceGestures() throws {
-    app.launch()
-    currentApp = app
-    currentBundleId = nil
-    defer {
-      currentApp = nil
-      currentBundleId = nil
-      app.terminate()
-    }
-    let selectorTap = try runnerCommandFixture(
-      #"{"command":"tap","commandId":"tap-1","selectorKey":"label","selectorValue":"Search","synthesized":true}"#
-    )
-    let standardDrag = try runnerCommandFixture(
-      #"{"command":"drag","commandId":"drag-1","x":10,"y":20,"x2":30,"y2":40}"#
-    )
-    let mixedSequence = try runnerCommandFixture(
-      """
-      {"command":"sequence","commandId":"seq-1","steps":[
-        {"kind":"tap","x":10,"y":20,"synthesized":true},
-        {"kind":"doubleTap","x":30,"y":40}
-      ]}
-      """
-    )
-
-    XCTAssertFalse(shouldSkipAppActivationPreflight(selectorTap))
-    XCTAssertFalse(shouldSkipAppActivationPreflight(standardDrag))
-    XCTAssertFalse(shouldSkipAppActivationPreflight(mixedSequence))
-  }
-
-  // Launches nothing, but still simulator-only: `shouldSkipAppActivationPreflight` is
-  // `#if os(iOS) …guards… #else return false #endif`, so on macOS this asserts a compile-time
-  // literal and no edit to the iOS body could make it red. Its five siblings above and below
-  // are gated for the same reason.
-  func testSkipAppActivationPreflightRequiresCachedForegroundTarget() throws {
-    currentApp = nil
-    currentBundleId = nil
-    let scroll = try runnerCommandFixture(
-      #"{"command":"scroll","commandId":"scroll-1","direction":"down","pixels":400}"#
-    )
-
-    XCTAssertFalse(shouldSkipAppActivationPreflight(scroll))
-  }
-
-  func testSkipAppActivationPreflightKeepsDragScrollAndSequenceOnForegroundGuard() throws {
-    app.launch()
-    currentApp = app
-    currentBundleId = nil
-    defer {
-      currentApp = nil
-      currentBundleId = nil
-      app.terminate()
-    }
-    let drag = try runnerCommandFixture(
-      #"{"command":"drag","commandId":"drag-1","x":10,"y":20,"x2":30,"y2":40}"#
-    )
-    let scroll = try runnerCommandFixture(
-      #"{"command":"scroll","commandId":"scroll-1","direction":"down","pixels":400}"#
-    )
-    let sequence = try runnerCommandFixture(
-      """
-      {"command":"sequence","commandId":"seq-1","steps":[
-        {"kind":"tap","x":10,"y":20,"synthesized":true},
-        {"kind":"longPress","x":10,"y":200,"durationMs":300}
-      ]}
-      """
-    )
-
-    XCTAssertFalse(shouldSkipAppActivationPreflight(drag))
-    XCTAssertFalse(shouldSkipAppActivationPreflight(scroll))
-    XCTAssertFalse(shouldSkipAppActivationPreflight(sequence))
-  }
-
-  func testSkipAppActivationPreflightIncludesAlertCommands() throws {
-    let alert = try runnerCommandFixture(
-      #"{"command":"alert","commandId":"alert-1","action":"get"}"#
-    )
-
-    XCTAssertTrue(shouldSkipAppActivationPreflight(alert))
-  }
-#endif
-
-  func testDispatchReturnsBusyBeforeQueueingMainThreadWork() throws {
-    let command = try runnerCommandFixture(#"{"command":"snapshot","commandId":"snapshot-busy"}"#)
-    abandonedMainThreadWorkCount = 1
-    abandonedMainThreadWorkSince = Date(timeIntervalSinceNow: -2)
-    defer {
-      abandonedMainThreadWorkCount = 0
-      abandonedMainThreadWorkSince = nil
-    }
-
-    let response = try execute(command: command)
-
-    XCTAssertFalse(response.ok)
-    XCTAssertEqual(response.error?.code, "RUNNER_BUSY")
-    XCTAssertTrue(response.error?.message.contains("previous command") == true)
-  }
-
-  func testDispatchReturnsWedgedBeforeQueueingMainThreadWork() throws {
-    let command = try runnerCommandFixture(#"{"command":"snapshot","commandId":"snapshot-wedged"}"#)
-    abandonedMainThreadWorkCount = 1
-    abandonedMainThreadWorkSince = Date(timeIntervalSinceNow: -(mainThreadWedgeThreshold + 1))
-    defer {
-      abandonedMainThreadWorkCount = 0
-      abandonedMainThreadWorkSince = nil
-    }
-
-    let response = try execute(command: command)
-
-    XCTAssertFalse(response.ok)
-    XCTAssertEqual(response.error?.code, "RUNNER_WEDGED")
-    XCTAssertTrue(response.error?.hint?.contains("runner session will be restarted") == true)
-  }
-
-  func testPostSnapshotDelayMarkDoesNotQueueBehindAbandonedMainThreadWork() {
-    abandonedMainThreadWorkCount = 1
-    defer {
-      abandonedMainThreadWorkCount = 0
-      needsPostSnapshotInteractionDelay = false
-    }
-
-    let finished = expectation(description: "off-main caller finished")
-    DispatchQueue(label: "agent-device.runner.tests.post-snapshot-delay").async {
-      self.setNeedsPostSnapshotInteractionDelay()
-      finished.fulfill()
-    }
-
-    wait(for: [finished], timeout: 1)
-    mainThreadWorkLock.lock()
-    let abandonedWorkCount = abandonedMainThreadWorkCount
-    mainThreadWorkLock.unlock()
-    XCTAssertEqual(abandonedWorkCount, 1, "the skipped mark must not add an abandoned unit")
-    XCTAssertFalse(needsPostSnapshotInteractionDelay)
-  }
-
-  func testSnapshotFailureInvalidationQueuesBehindAbandonedMainThreadWorkWithoutWaiting() {
-    currentBundleId = "com.example.stale-target"
-    defer { currentBundleId = nil }
-
-    final class ResultBox {
-      var elapsed: TimeInterval?
-      var bundleStillCachedWhileBlocked: Bool?
-      var abandonedWhileBlocked: Int?
-    }
-    let box = ResultBox()
-    let mainBlocked = DispatchSemaphore(value: 0)
-    let releaseMain = DispatchSemaphore(value: 0)
-    let finished = expectation(description: "invalidation returned while main was blocked")
-
-    DispatchQueue(label: "agent-device.runner.tests.snapshot-invalidation").async {
-      _ = try? self.runMainThreadWork(
-        "command_execution",
-        timeout: 0,
-        timeoutError: self.mainThreadExecutionTimeoutError
-      ) {
-        mainBlocked.signal()
-        _ = releaseMain.wait(timeout: .now() + 5)
-        return true
-      }
-      _ = mainBlocked.wait(timeout: .now() + 2)
-      let startedAt = Date()
-      self.invalidateCachedTargetAfterSnapshotFailure()
-      box.elapsed = Date().timeIntervalSince(startedAt)
-      box.bundleStillCachedWhileBlocked = self.currentBundleId != nil
-      self.mainThreadWorkLock.lock()
-      box.abandonedWhileBlocked = self.abandonedMainThreadWorkCount
-      self.mainThreadWorkLock.unlock()
-      releaseMain.signal()
-      finished.fulfill()
-    }
-
-    wait(for: [finished], timeout: 8)
-    let drainDeadline = Date().addingTimeInterval(2)
-    while hasAbandonedMainThreadWork() || currentBundleId != nil, Date() < drainDeadline {
-      sleepFor(0.005)
-    }
-
-    XCTAssertLessThan(
-      box.elapsed ?? .infinity,
-      0.5,
-      "the failed capture must not wait behind abandoned main-thread work"
-    )
-    XCTAssertEqual(
-      box.bundleStillCachedWhileBlocked,
-      true,
-      "the drop must queue behind the blocked main thread, not run early"
-    )
-    XCTAssertEqual(box.abandonedWhileBlocked, 1, "the deferred drop must not add an abandoned unit")
-    XCTAssertFalse(hasAbandonedMainThreadWork())
-    XCTAssertNil(currentBundleId, "the drop must run once the main thread frees")
-  }
-
-  /// Routes `command` through the transport's inline and queued paths. The calling test's main
-  /// thread serves the command's main-thread work while it waits.
-  func execute(command: Command) throws -> Response {
-    dispatchPrecondition(condition: .onQueue(.main))
-    if let response = inlineResponse(for: command) {
-      return response
-    }
-    final class ResultBox {
-      var result: Result<Response, Error>?
-    }
-    let box = ResultBox()
-    let executed = XCTestExpectation(description: "\(command.command.rawValue) executed off main")
-    enqueueAccepted(command: command) { result in
-      box.result = result
-      executed.fulfill()
-    }
-    guard XCTWaiter.wait(for: [executed], timeout: mainThreadExecutionTimeout + 5) == .completed,
-      let result = box.result
-    else {
-      throw NSError(
-        domain: RunnerErrorDomain.general,
-        code: RunnerErrorCode.commandReturnedNoResponse,
-        userInfo: [NSLocalizedDescriptionKey: "command did not finish on the command queue"]
-      )
-    }
-    return try result.get()
-  }
-
-  func runnerCommandFixture(_ json: String) throws -> Command {
-    try JSONDecoder().decode(Command.self, from: Data(json.utf8))
-  }
 }
 #endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+GestureExecutionTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+GestureExecutionTests.swift
new file mode 100644
index 0000000000..d5c517cf45
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+GestureExecutionTests.swift
@@ -0,0 +1,73 @@
+import XCTest
+import AgentDeviceSnapshotPresentation
+
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS
+extension RunnerTests {
+  func testGestureResponseIncludesSynthesizedTapFallbackDiagnostics() {
+    let response = gestureResponse(
+      message: "tapped",
+      timing: (gestureStartUptimeMs: 1, gestureEndUptimeMs: 2),
+      fallback: GestureFallback(
+        strategy: "xctest-coordinate-tap",
+        message: "Runner synthesized coordinate tap is unavailable",
+        hint: "Using XCTest coordinate tap fallback."
+      )
+    )
+
+    XCTAssertEqual(response.ok, true)
+    XCTAssertEqual(response.data?.gestureFallback, "xctest-coordinate-tap")
+    XCTAssertEqual(
+      response.data?.gestureFallbackMessage,
+      "Runner synthesized coordinate tap is unavailable"
+    )
+    XCTAssertEqual(response.data?.gestureFallbackHint, "Using XCTest coordinate tap fallback.")
+  }
+
+  func testGestureResponseIncludesMaestroNonHittableFallbackUsage() {
+    let response = gestureResponse(
+      message: "tapped via non-hittable coordinate fallback",
+      timing: (gestureStartUptimeMs: 1, gestureEndUptimeMs: 2),
+      frame: .touch(nil),
+      maestroNonHittableCoordinateFallbackUsed: true
+    )
+
+    XCTAssertEqual(response.data?.maestroNonHittableCoordinateFallbackUsed, true)
+  }
+
+  func testCanonicalPlannedGestureResponseOmitsDragFrameAndPreservesDiagnostics() {
+    let response = gestureResponse(
+      message: "fling",
+      timing: (gestureStartUptimeMs: 1, gestureEndUptimeMs: 2),
+      frame: .drag(
+        DragVisualizationFrame(
+          x: 160,
+          y: 150,
+          x2: 40,
+          y2: 150,
+          referenceWidth: 200,
+          referenceHeight: 300
+        )
+      ),
+      fallback: GestureFallback(
+        strategy: "xctest-coordinate-drag",
+        message: "Private synthesis unavailable",
+        hint: "Using XCTest coordinate fallback."
+      )
+    )
+
+    let canonical = canonicalPlannedGestureResponse(response)
+
+    XCTAssertEqual(canonical.data?.gestureStartUptimeMs, 1)
+    XCTAssertEqual(canonical.data?.gestureEndUptimeMs, 2)
+    XCTAssertEqual(canonical.data?.gestureFallback, "xctest-coordinate-drag")
+    XCTAssertEqual(canonical.data?.gestureFallbackMessage, "Private synthesis unavailable")
+    XCTAssertEqual(canonical.data?.gestureFallbackHint, "Using XCTest coordinate fallback.")
+    XCTAssertNil(canonical.data?.x)
+    XCTAssertNil(canonical.data?.y)
+    XCTAssertNil(canonical.data?.x2)
+    XCTAssertNil(canonical.data?.y2)
+    XCTAssertNil(canonical.data?.referenceWidth)
+    XCTAssertNil(canonical.data?.referenceHeight)
+  }
+}
+#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+ModelsTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+ModelsTests.swift
index d0079bf728..eab82171dc 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+ModelsTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+ModelsTests.swift
@@ -28,5 +28,9 @@ extension RunnerTests {
       "runner app is not available"
     )
   }
+
+  func runnerCommandFixture(_ json: String) throws -> Command {
+    try JSONDecoder().decode(Command.self, from: Data(json.utf8))
+  }
 }
 #endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+ScrollDragExecutionTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+ScrollDragExecutionTests.swift
new file mode 100644
index 0000000000..440f19fe90
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+ScrollDragExecutionTests.swift
@@ -0,0 +1,72 @@
+import XCTest
+import AgentDeviceSnapshotPresentation
+
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS && os(iOS)
+import ObjectiveC.runtime
+
+private final class RunnerSynthesizedSwipeFailureStub: NSObject {
+  @objc(synthesizeSwipeWithApplication:resolvedWindow:x:y:x2:y2:durationMs:)
+  class func synthesizeSwipe(
+    application: XCUIApplication,
+    resolvedWindow: Any?,
+    x: Double,
+    y: Double,
+    x2: Double,
+    y2: Double,
+    durationMs: Double
+  ) -> String? {
+    "forced private synthesis failure"
+  }
+}
+#endif
+
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS
+extension RunnerTests {
+#if os(iOS)
+  func testSinglePointerFlingFallsBackToXCTestCoordinateDragWhenPrivateSynthesisFails() throws {
+    let selector = NSSelectorFromString(
+      "synthesizeSwipeWithApplication:resolvedWindow:x:y:x2:y2:durationMs:"
+    )
+    guard
+      let synthesizedSwipeMethod = class_getClassMethod(RunnerSynthesizedGesture.self, selector),
+      let failureStubMethod = class_getClassMethod(RunnerSynthesizedSwipeFailureStub.self, selector)
+    else {
+      XCTFail("unable to install synthesized swipe failure stub")
+      return
+    }
+    let originalImplementation = method_getImplementation(synthesizedSwipeMethod)
+    method_setImplementation(
+      synthesizedSwipeMethod,
+      method_getImplementation(failureStubMethod)
+    )
+    app.launch()
+    runnerAccessibilityHealth = .healthy
+    defer {
+      method_setImplementation(synthesizedSwipeMethod, originalImplementation)
+      invalidateCachedTarget(reason: "unit_test_cleanup")
+      app.terminate()
+    }
+    let command = try runnerCommandFixture(
+      """
+      {"command":"gesture","commandId":"gesture-fling-fallback","gesturePlan":{"topology":"single","intent":"fling","executionProfile":"endpoint-hold","durationMs":100,"viewport":{"x":0,"y":0,"width":200,"height":300},"pointers":[{"pointerId":0,"samples":[{"offsetMs":0,"point":{"x":160,"y":150}},{"offsetMs":100,"point":{"x":40,"y":150}}]}]}}
+      """
+    )
+
+    let response = try executeOnMainPrepared(command: command, activeApp: app)
+
+    XCTAssertTrue(response.ok)
+    XCTAssertEqual(response.data?.message, "fling")
+    XCTAssertEqual(response.data?.gestureFallback, "xctest-coordinate-drag")
+    XCTAssertEqual(response.data?.gestureFallbackMessage, "forced private synthesis failure")
+    XCTAssertEqual(
+      response.data?.gestureFallbackHint,
+      "Private XCTest event synthesis is required for AX-free coordinate drag on iOS; update Xcode if this persists."
+    )
+    XCTAssertNil(response.data?.x)
+    XCTAssertNil(response.data?.y)
+    XCTAssertNil(response.data?.x2)
+    XCTAssertNil(response.data?.y2)
+  }
+#endif
+}
+#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotExecutionTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotExecutionTests.swift
new file mode 100644
index 0000000000..fa637a853b
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotExecutionTests.swift
@@ -0,0 +1,84 @@
+import XCTest
+import AgentDeviceSnapshotPresentation
+
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS
+extension RunnerTests {
+  func testPostSnapshotDelayMarkDoesNotQueueBehindAbandonedMainThreadWork() {
+    abandonedMainThreadWorkCount = 1
+    defer {
+      abandonedMainThreadWorkCount = 0
+      needsPostSnapshotInteractionDelay = false
+    }
+
+    let finished = expectation(description: "off-main caller finished")
+    DispatchQueue(label: "agent-device.runner.tests.post-snapshot-delay").async {
+      self.setNeedsPostSnapshotInteractionDelay()
+      finished.fulfill()
+    }
+
+    wait(for: [finished], timeout: 1)
+    mainThreadWorkLock.lock()
+    let abandonedWorkCount = abandonedMainThreadWorkCount
+    mainThreadWorkLock.unlock()
+    XCTAssertEqual(abandonedWorkCount, 1, "the skipped mark must not add an abandoned unit")
+    XCTAssertFalse(needsPostSnapshotInteractionDelay)
+  }
+
+  func testSnapshotFailureInvalidationQueuesBehindAbandonedMainThreadWorkWithoutWaiting() {
+    currentBundleId = "com.example.stale-target"
+    defer { currentBundleId = nil }
+
+    final class ResultBox {
+      var elapsed: TimeInterval?
+      var bundleStillCachedWhileBlocked: Bool?
+      var abandonedWhileBlocked: Int?
+    }
+    let box = ResultBox()
+    let mainBlocked = DispatchSemaphore(value: 0)
+    let releaseMain = DispatchSemaphore(value: 0)
+    let finished = expectation(description: "invalidation returned while main was blocked")
+
+    DispatchQueue(label: "agent-device.runner.tests.snapshot-invalidation").async {
+      _ = try? self.runMainThreadWork(
+        "command_execution",
+        timeout: 0,
+        timeoutError: self.mainThreadExecutionTimeoutError
+      ) {
+        mainBlocked.signal()
+        _ = releaseMain.wait(timeout: .now() + 5)
+        return true
+      }
+      _ = mainBlocked.wait(timeout: .now() + 2)
+      let startedAt = Date()
+      self.invalidateCachedTargetAfterSnapshotFailure()
+      box.elapsed = Date().timeIntervalSince(startedAt)
+      box.bundleStillCachedWhileBlocked = self.currentBundleId != nil
+      self.mainThreadWorkLock.lock()
+      box.abandonedWhileBlocked = self.abandonedMainThreadWorkCount
+      self.mainThreadWorkLock.unlock()
+      releaseMain.signal()
+      finished.fulfill()
+    }
+
+    wait(for: [finished], timeout: 8)
+    let drainDeadline = Date().addingTimeInterval(2)
+    while hasAbandonedMainThreadWork() || currentBundleId != nil, Date() < drainDeadline {
+      sleepFor(0.005)
+    }
+
+    XCTAssertLessThan(
+      box.elapsed ?? .infinity,
+      0.5,
+      "the failed capture must not wait behind abandoned main-thread work"
+    )
+    XCTAssertEqual(
+      box.bundleStillCachedWhileBlocked,
+      true,
+      "the drop must queue behind the blocked main thread, not run early"
+    )
+    XCTAssertEqual(box.abandonedWhileBlocked, 1, "the deferred drop must not add an abandoned unit")
+    XCTAssertFalse(hasAbandonedMainThreadWork())
+    XCTAssertNil(currentBundleId, "the drop must run once the main thread frees")
+  }
+}
+#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotTests.swift
index 527da828fb..83ac2f5a00 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotTests.swift
@@ -196,50 +196,5 @@ extension RunnerTests {
     }
   }
 #endif
-
-  func testDispatchRecoverySkipsBookkeepingWhileXCTestChannelOccupied() {
-    // The #1244 recovery shape: the modal probe abandoned an XCTest query that is still grinding on
-    // main, the capture recovered independently, and its response is ready. The recovery loop must
-    // return it without re-entering the main queue for recorded-failure/retry bookkeeping (that hop
-    // would block behind the abandoned query and re-stall the command), and a later command must
-    // still see the runner busy until the abandoned work drains. Removing the guard regresses this.
-    let command = try! JSONDecoder().decode(
-      Command.self,
-      from: Data(#"{"command":"snapshot","commandId":"recovery-guard"}"#.utf8)
-    )
-    let recovered = Response(ok: false, error: .targetAppUnavailable(bundleId: nil))
-
-    setAbandonedMainThreadWork(1)
-    defer { setAbandonedMainThreadWork(0) }
-    guard case .busy = currentMainThreadBusyState() else {
-      return XCTFail("expected RUNNER_BUSY while abandoned XCTest work is outstanding")
-    }
-
-    var occupiedCalls = 0
-    let occupied = try! executeDispatchedWithRecovery(command: command) {
-      occupiedCalls += 1
-      return recovered
-    }
-    XCTAssertEqual(occupiedCalls, 1, "recovered response must not retry behind abandoned XCTest work")
-    XCTAssertEqual(occupied.ok, false)
-
-    setAbandonedMainThreadWork(0)
-    guard case .idle = currentMainThreadBusyState() else {
-      return XCTFail("runner should be idle once the abandoned work drained")
-    }
-    var drainedCalls = 0
-    _ = try! executeDispatchedWithRecovery(command: command) {
-      drainedCalls += 1
-      return recovered
-    }
-    XCTAssertEqual(drainedCalls, 2, "with the channel free the read-only retry runs once")
-  }
-
-  private func setAbandonedMainThreadWork(_ count: Int) {
-    mainThreadWorkLock.lock()
-    abandonedMainThreadWorkCount = count
-    abandonedMainThreadWorkSince = count > 0 ? Date(timeIntervalSinceNow: -1) : nil
-    mainThreadWorkLock.unlock()
-  }
 }
 #endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+TransportTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+TransportTests.swift
index 42c0f53875..ffa3d56d36 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+TransportTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+TransportTests.swift
@@ -39,5 +39,33 @@ extension RunnerTests {
     XCTAssertFalse(inFlightCommandIds.contains("snapshot-coalesce"))
     XCTAssertNil(inFlightCommandWaiters["snapshot-coalesce"])
   }
+
+  /// Routes `command` through the transport's inline and queued paths. The calling test's main
+  /// thread serves the command's main-thread work while it waits.
+  func execute(command: Command) throws -> Response {
+    dispatchPrecondition(condition: .onQueue(.main))
+    if let response = inlineResponse(for: command) {
+      return response
+    }
+    final class ResultBox {
+      var result: Result<Response, Error>?
+    }
+    let box = ResultBox()
+    let executed = XCTestExpectation(description: "\(command.command.rawValue) executed off main")
+    enqueueAccepted(command: command) { result in
+      box.result = result
+      executed.fulfill()
+    }
+    guard XCTWaiter.wait(for: [executed], timeout: mainThreadExecutionTimeout + 5) == .completed,
+      let result = box.result
+    else {
+      throw NSError(
+        domain: RunnerErrorDomain.general,
+        code: RunnerErrorCode.commandReturnedNoResponse,
+        userInfo: [NSLocalizedDescriptionKey: "command did not finish on the command queue"]
+      )
+    }
+    return try result.get()
+  }
 }
 #endif
diff --git a/apple/runner/README.md b/apple/runner/README.md
index d899f9cfce..8c087f4a61 100644
--- a/apple/runner/README.md
+++ b/apple/runner/README.md
@@ -26,7 +26,12 @@ Protocol and maintenance references:
 - `RunnerTests+Models.swift`: wire protocol models (`Command`, `Response`, snapshot payload models).
 - `RunnerTests+Environment.swift`: environment and CLI argument helpers (`RunnerEnv`).
 - `RunnerTests+Transport.swift`: TCP request handling and HTTP parsing/encoding.
-- `RunnerTests+CommandExecution.swift`: command dispatch (`execute*`) and command switch.
+- `RunnerTests+CommandDispatch.swift`: the dispatch entry (`executeAccepted`, `executeDispatched`),
+  its recovery loops, target preparation, and recorded-failure conversion.
+- `RunnerTests+CommandExecution.swift`: the prepared-command switch (`executeOnMainPrepared`).
+- `RunnerTests+GestureExecution.swift`, `RunnerTests+ScrollDragExecution.swift`,
+  `RunnerTests+TypeExecution.swift`, `RunnerTests+SnapshotExecution.swift`: per-family command
+  execution.
 - `RunnerTests+Lifecycle.swift`: activation/retry/stabilization and recording lifecycle helpers.
 - `RunnerTests+Interaction.swift`: tap/drag/swipe/type/home/rotate/app-switcher helpers.
 - `RunnerTests+Navigation.swift`: back/navigation-control helpers.

From e7170c46b1fd2140b0f03b7ae6d68a7766b120ef Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 24 Sep 2026 07:45:26 +0200
Subject: [PATCH 072/132] test(ios): stop cold-host timing from failing the
 occupancy test (#2847)

testAbandonedTreeCaptureSkipsQuerySweepAndHonorsWarmupExemption runs first in
the targeted XCTest lane and absorbed a cold host twice over:

- A cold viewport read overran its 1 s cap before the tree capture the test
  targets, so the abandonment reason read "preparing tree snapshot" (4 CI
  failures at line 106). The test now pays that read uncapped before the timed
  section; the production cap is unchanged.
- The blocking stub's own 20 s timeout could release the main thread before
  the test read the abandoned-work count, reading Optional(0) (2 CI failures at
  line 111). It is now a named leak guard far past the plan deadline, so only
  the test's release ends the block.
---
 ...RunnerTests+SnapshotCapturePlanOccupancyTests.swift | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotCapturePlanOccupancyTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotCapturePlanOccupancyTests.swift
index afb15147d2..c4c92d80c7 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotCapturePlanOccupancyTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotCapturePlanOccupancyTests.swift
@@ -15,9 +15,13 @@ private enum RunnerBlockingSnapshotGate {
 /// read the AX server gave up on. The swap is process-wide while installed, which serial XCTest
 /// execution tolerates.
 private final class RunnerBlockingSnapshotStub: NSObject {
+  /// Far past the plan deadline, so only the test's own release ends the block; it only stops a
+  /// stuck test from holding the main thread.
+  private static let leakGuard: TimeInterval = 75
+
   @objc(snapshotWithError:)
   func snapshot() throws -> XCUIElementSnapshot {
-    _ = RunnerBlockingSnapshotGate.release.wait(timeout: .now() + 20)
+    _ = RunnerBlockingSnapshotGate.release.wait(timeout: .now() + Self.leakGuard)
     throw NSError(
       domain: "AgentDeviceRunner.tests",
       code: 1,
@@ -50,6 +54,10 @@ extension RunnerTests {
     // resolution is slow, and it must not be the block the plan abandons.
     XCTAssertTrue(app.wait(for: .runningForeground, timeout: 10))
     XCTAssertFalse(app.frame.isEmpty)
+    // The traversal context reads the viewport under a 1 s cap; a cold first read can overrun it
+    // and abandon the wrong block, so pay it here, uncapped.
+    _ = safeSnapshotViewport(app: app)
+    _ = capturedInterfaceOrientation(app: app)
     currentApp = app
     currentBundleId = "com.callstack.agentdevice.runner.tree-capture-test"
     snapshotXCTestPenaltyWarmupExemptionPending = true

From 4cdd1c923cc40fbb1516817711eb647afbca8e4a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 24 Sep 2026 07:47:59 +0200
Subject: [PATCH 073/132] fix(interaction): report an unsettled post-gesture
 surface instead of a definite miss (#2839)

* fix(interaction): report an unsettled post-gesture surface instead of a definite miss

Post-gesture stabilization returned the latest capture of a still-moving
surface when its budget expired, keeping the timeout only as a log
diagnostic. `is visible` then answered a plain `selector_not_found` and
`is absent` passed on a list that was still decelerating.

When the last poll pair disagrees, the resolved capture stamps
`unsettledGesture` on the tree, the one carrier. Selector reads (mutating
`find` now keeps the captured tree) disclose it through one tree-fact
helper shared with `targetActivation`, which now also lands on
`error.details`; `snapshot` derives the warning in its builder; `is absent`
refuses with `observation: "unsettled"`, `wait absent` keeps polling, and
the session cache does not serve an unsettled tree.

* test(ios-e2e): re-read an unsettled miss instead of scrolling past it

The live scroll search now re-probes the same window once when a miss
carries `unsettledGesture`, and its failure lists every probe and scroll.
---
 CHANGELOG.md                                  |  8 +++
 .../capture-kit/src/post-gesture-stability.ts | 42 +++++++++++++--
 packages/kernel/src/snapshot.ts               |  5 ++
 .../src/absence-observation-errors.ts         |  6 +--
 packages/selectors/src/absence-observation.ts | 25 +++++++--
 src/commands/capture/runtime/snapshot.test.ts | 17 ++++++
 src/commands/capture/runtime/snapshot.ts      |  4 ++
 src/commands/interaction/metadata.ts          |  2 +-
 .../interaction/runtime/wait-absent.test.ts   | 17 ++++++
 .../interaction/runtime/wait-absent.ts        |  7 ++-
 src/daemon/__tests__/is-runtime.test.ts       | 54 ++++++++++++++++++-
 .../post-gesture-no-effect-claim.test.ts      |  2 +-
 .../post-gesture-stabilization.test.ts        | 37 +++++++++++++
 src/daemon/capture-disclosure.ts              | 46 +++++++++++-----
 src/daemon/deferred-interaction-outcome.ts    | 33 ++++++------
 src/daemon/gesture-no-effect.ts               | 17 +-----
 .../find-target-activation-disclosure.test.ts | 38 ++++++++++++-
 .../internal/find-target-capture.ts           | 26 ++-------
 src/daemon/selector-capture-runtime.ts        |  2 +-
 ...os-simulator-e2e-visibility-scroll.test.ts | 42 +++++++++++++++
 .../ios-simulator-e2e/live-assertions.ts      | 33 ++++++------
 website/docs/docs/commands.md                 |  5 +-
 22 files changed, 365 insertions(+), 103 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2cdcb0b8eb..187b1f3762 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+- Fixed (mobile): a read taken right after a `scroll`, `swipe`, or `gesture swipe` no longer reports
+  a definite miss when the surface never settled. When post-gesture stabilization ran out of budget
+  on a surface still moving, `is visible` answered a plain `selector_not_found` and `is absent`
+  passed. That capture now carries `unsettledGesture`: `is`, `get`, `find`, and `wait` report it (in
+  `error.details` or `data`) with an appended warning, `snapshot` appends the warning, `is absent`
+  refuses with `observation: "unsettled"`, `wait absent` keeps polling, and the next read captures
+  afresh. Click, press, and fill by selector do not disclose it yet. A failed read now also carries
+  `targetActivation` in `error.details`, the same place as `unsettledGesture`.
 - Fixed (ios): `open` on a local Simulator now waits for the launched app's discovery before it
   decides whether the app is observable. On a loaded host `simctl spawn launchctl list` outlasts one
   1.5 s discovery wait slice, and the launch observation read that slice as an unobservable app, so
diff --git a/packages/capture-kit/src/post-gesture-stability.ts b/packages/capture-kit/src/post-gesture-stability.ts
index cad874f7c8..438a674bbb 100644
--- a/packages/capture-kit/src/post-gesture-stability.ts
+++ b/packages/capture-kit/src/post-gesture-stability.ts
@@ -1,5 +1,6 @@
 import { emitDiagnostic } from '@agent-device/host-kit/diagnostics';
 import { sleep } from '@agent-device/host-kit/retry';
+import type { PostGestureAction } from '@agent-device/kernel/snapshot';
 
 /**
  * Pure post-gesture stability mechanics: the quiet-window polling loop and the
@@ -58,6 +59,8 @@ export type PostGestureStabilityHooks<T, S extends readonly unknown[]> = {
 
 export type PostGestureStabilityOutcome<T> = {
   value: T;
+  /** Present when the deadline expired while the last two captures still disagreed. */
+  unsettledGesture?: PostGestureAction;
   /**
    * Present ONLY when the accept-stale verdict is corroborated by full-surface
    * evidence (`surfacesIdentical`). The bare verdict is NOT enough — it is
@@ -66,9 +69,33 @@ export type PostGestureStabilityOutcome<T> = {
    * Callers surface this to the agent: a diagnostics-only signal let one
    * benchmark run burn 40 calls re-issuing scrolls that moved nothing (#1600).
    */
-  gestureNoEffect?: { action: string; positionals: string[] };
+  gestureNoEffect?: PostGestureAction;
 };
 
+function describePostGestureAction(gesture: PostGestureAction): string {
+  return [gesture.action, ...gesture.positionals].join(' ').trim();
+}
+
+/**
+ * The agent-facing wording for a proven no-effect gesture. Names the exact
+ * gesture, admits the honest ambiguity (at-edge is a legitimate no-op the
+ * platform cannot distinguish), and hands over the one escape hatch that
+ * moved a stuck list when synthesized scrolls did not (#1600, element-18:
+ * raw `swipe` worked where scroll/fling/pan all silently no-opped).
+ */
+export function formatGestureNoEffectWarning(action: string, positionals: string[]): string {
+  return (
+    `${describePostGestureAction({ action, positionals })} produced no visible change: the tree still matches its pre-gesture state. ` +
+    'Either the container is already at its edge, or it ignores synthesized scrolls — ' +
+    'a raw drag moves such lists: swipe x1 y1 x2 y2 (start inside the list).'
+  );
+}
+
+/** A miss on a tree read while a gesture's surface was still changing is not proof of absence. */
+export function formatGestureUnsettledWarning(gesture: PostGestureAction): string {
+  return `The surface was still changing after ${describePostGestureAction(gesture)} when this was read, so an element missing from it may still be on screen. Read again before treating it as absent.`;
+}
+
 /**
  * Verdict for a quiet match that has already been observed. `'ambiguous'`
  * baseline evidence (no comparable content) falls through to `trust`, same as
@@ -114,12 +141,16 @@ export async function runPostGestureStabilityLoop<T, S extends readonly unknown[
   // Extended past STABILIZATION_DEADLINE_MS only when the distrust verdict
   // fires below; the ordinary (non-distrust) timeout path is unaffected.
   let effectiveDeadlineMs = STABILIZATION_DEADLINE_MS;
+  // A rebase or a distrust verdict keeps polling on a pair that DID agree, so
+  // the deadline can expire on a surface that is already at rest.
+  let lastPairAgreed = false;
 
   while (attempts < STABILIZATION_MIN_ATTEMPTS || Date.now() - startedAt < effectiveDeadlineMs) {
     await sleep(STABILIZATION_INTERVAL_MS);
     attempts += 1;
     const current = await captureSurface(hooks);
-    if (hooks.signaturesStable(previous.signature, current.signature)) {
+    lastPairAgreed = hooks.signaturesStable(previous.signature, current.signature);
+    if (lastPairAgreed) {
       const elapsedMs = Date.now() - startedAt;
       // A capture plan may fall back or be pre-empted by the XCTest-channel
       // penalty at any time, so the backend can change mid-poll. Backends do
@@ -164,9 +195,14 @@ export async function runPostGestureStabilityLoop<T, S extends readonly unknown[
       action: pending.action,
       attempts,
       durationMs: Date.now() - startedAt,
+      lastPairAgreed,
     },
   });
-  return { value: previous.value };
+  if (lastPairAgreed) return { value: previous.value };
+  return {
+    value: previous.value,
+    unsettledGesture: { action: pending.action, positionals: pending.positionals },
+  };
 }
 
 type CapturedSurface<T, S> = {
diff --git a/packages/kernel/src/snapshot.ts b/packages/kernel/src/snapshot.ts
index b8ec116309..33eeafed20 100644
--- a/packages/kernel/src/snapshot.ts
+++ b/packages/kernel/src/snapshot.ts
@@ -500,8 +500,13 @@ export type SnapshotState = {
    * the foreground instead (#2682). Consumers that surface this tree disclose the repair.
    */
   targetActivation?: IosTargetActivation;
+  /** The gesture whose surface was still changing when stabilization gave up on this capture. */
+  unsettledGesture?: PostGestureAction;
 } & SnapshotStateProvenance;
 
+/** The gesture a post-gesture outcome fact names: the command and its positionals. */
+export type PostGestureAction = { action: string; positionals: string[] };
+
 export type SnapshotUnchanged = {
   ageMs: number;
   nodeCount: number;
diff --git a/packages/selectors/src/absence-observation-errors.ts b/packages/selectors/src/absence-observation-errors.ts
index 24f977fe83..196f0d0737 100644
--- a/packages/selectors/src/absence-observation-errors.ts
+++ b/packages/selectors/src/absence-observation-errors.ts
@@ -1,6 +1,8 @@
 import { asAppError, AppError } from '@agent-device/kernel/errors';
 import { INTERACTION_ERROR_REASONS } from './interaction-error.ts';
 import {
+  UNPROVABLE_ABSENCE_CAUSES,
+  type UnprovableAbsenceKind,
   absenceCaptureOptionMessage,
   type AbsenceCaptureOption,
   type AbsenceObservation,
@@ -47,9 +49,7 @@ export function absenceObservationError(
   }
   return new AppError(
     'COMMAND_FAILED',
-    `${command} absent could not prove absence for selector ${selector}: ${
-      observation.kind === 'sparse' ? 'capture was sparse' : 'capture was truncated'
-    }`,
+    `${command} absent could not prove absence for selector ${selector}: ${UNPROVABLE_ABSENCE_CAUSES[observation.kind as UnprovableAbsenceKind]}`,
     {
       ...details,
       hint: 'Retry after the accessibility capture is complete.',
diff --git a/packages/selectors/src/absence-observation.ts b/packages/selectors/src/absence-observation.ts
index ac2f811966..02964761ef 100644
--- a/packages/selectors/src/absence-observation.ts
+++ b/packages/selectors/src/absence-observation.ts
@@ -32,7 +32,21 @@ export type AbsenceObservation =
   | { kind: 'absent'; matches: 0 }
   | { kind: 'present'; matches: number; firstMatch: AbsenceFirstMatch }
   | { kind: 'sparse'; matches: number; firstMatch?: AbsenceFirstMatch; quality: SparseQuality }
-  | { kind: 'truncated'; matches: number; firstMatch?: AbsenceFirstMatch };
+  | { kind: 'truncated'; matches: number; firstMatch?: AbsenceFirstMatch }
+  | { kind: 'unsettled'; matches: 0 };
+
+/** Why a capture with no match still cannot prove absence. */
+export const UNPROVABLE_ABSENCE_CAUSES = {
+  sparse: 'capture was sparse',
+  truncated: 'capture was truncated',
+  unsettled: 'the surface was still changing after a gesture',
+} as const;
+
+export type UnprovableAbsenceKind = keyof typeof UNPROVABLE_ABSENCE_CAUSES;
+
+export function isUnprovableAbsence(kind: unknown): kind is UnprovableAbsenceKind {
+  return typeof kind === 'string' && Object.hasOwn(UNPROVABLE_ABSENCE_CAUSES, kind);
+}
 
 export type AbsenceCaptureOption = 'depth' | 'scope';
 
@@ -56,7 +70,10 @@ export function absenceCaptureOptionMessage(
 }
 
 export function classifyAbsenceObservation(
-  snapshot: Pick<SnapshotState, 'backend' | 'nodes' | 'snapshotQuality' | 'truncated'>,
+  snapshot: Pick<
+    SnapshotState,
+    'backend' | 'nodes' | 'snapshotQuality' | 'truncated' | 'unsettledGesture'
+  >,
   matches: readonly SnapshotNode[],
 ): AbsenceObservation {
   const firstMatch = matches[0] ? stableFirstMatch(matches[0]) : undefined;
@@ -82,7 +99,9 @@ export function classifyAbsenceObservation(
       },
     };
   }
-  if (matchCount === 0) return { kind: 'absent', matches: 0 };
+  if (matchCount === 0) {
+    return { kind: snapshot.unsettledGesture ? 'unsettled' : 'absent', matches: 0 };
+  }
   return { kind: 'present', matches: matchCount, firstMatch: firstMatch! };
 }
 
diff --git a/src/commands/capture/runtime/snapshot.test.ts b/src/commands/capture/runtime/snapshot.test.ts
index 378c3596a1..d24f27a490 100644
--- a/src/commands/capture/runtime/snapshot.test.ts
+++ b/src/commands/capture/runtime/snapshot.test.ts
@@ -13,6 +13,7 @@ import {
   type CommandSessionStore,
 } from '../../../runtime.ts';
 import { makeSnapshotState } from '@agent-device/selectors/snapshot-geometry-fixtures';
+import { formatGestureUnsettledWarning } from '@agent-device/capture-kit/post-gesture-stability';
 
 test('runtime snapshot captures nodes and updates the session baseline', async () => {
   let stored: Parameters<CommandSessionStore['set']>[0] | undefined;
@@ -786,3 +787,19 @@ test('runtime snapshot leaves the keyboard band off when the backend measured no
 
   assert.equal('keyboard' in result, false);
 });
+
+test('runtime snapshot warns when its tree was read on a surface still moving after a gesture', async () => {
+  const gesture = { action: 'scroll', positionals: ['down'] };
+  const device = createSnapshotOnlyDevice({
+    snapshot: {
+      ...makeSnapshotState([{ index: 0, depth: 0, type: 'Window', label: 'Home' }], {
+        backend: 'xctest',
+      }),
+      unsettledGesture: gesture,
+    },
+  });
+
+  const result = await device.capture.snapshot({ session: 'default' });
+
+  assert.deepEqual(result.warnings, [formatGestureUnsettledWarning(gesture)]);
+});
diff --git a/src/commands/capture/runtime/snapshot.ts b/src/commands/capture/runtime/snapshot.ts
index bfa2a8c4ea..21f058fe53 100644
--- a/src/commands/capture/runtime/snapshot.ts
+++ b/src/commands/capture/runtime/snapshot.ts
@@ -26,6 +26,7 @@ import {
   renderSnapshotQualityWarnings,
   truncatedCaptureWarning,
 } from '@agent-device/capture-kit/quality-warnings';
+import { formatGestureUnsettledWarning } from '@agent-device/capture-kit/post-gesture-stability';
 import { buildSnapshotVisibility } from '@agent-device/capture-kit/snapshot-visibility';
 import { ANDROID_SYSTEM_SURFACE_DISCLOSURE } from '@agent-device/contracts/android-system-surface-disclosure';
 import { formatReactNativeOverlayWarning } from '../../react-native/overlay.ts';
@@ -260,6 +261,9 @@ function buildSnapshotWarnings(params: {
     );
   }
   warnings.push(...truncatedCaptureWarning(snapshotTruncationForResult(params.snapshot)));
+  if (params.snapshot.unsettledGesture) {
+    warnings.push(formatGestureUnsettledWarning(params.snapshot.unsettledGesture));
+  }
   warnings.push(...buildEmptyAndroidInteractiveWarnings(params));
   if (!params.annotations.quality) {
     // Legacy runners without a structured verdict keep the old daemon-side heuristics.
diff --git a/src/commands/interaction/metadata.ts b/src/commands/interaction/metadata.ts
index b497ceb4eb..6faba1ad95 100644
--- a/src/commands/interaction/metadata.ts
+++ b/src/commands/interaction/metadata.ts
@@ -70,7 +70,7 @@ const interactionCommandDescriptions = {
   scroll:
     'Scroll in a direction, or toward the top/bottom edge of scrollable content. Set until to a selector to reach an off-screen target in one command rather than a scroll-and-check loop. The optional amount is the finger-path fraction of the viewport axis, honored up to 0.8 of it; directional scrolls reduce release momentum, while app scroll physics determine the final content offset. A visible keyboard shortens the swiped band instead of being dismissed; when too little is left, the command refuses with scroll_keyboard_occludes_surface. A directional scroll also reports the movement it observed as movement: moved, at-edge, unchanged, or unobserved when the two reads could not back a claim either way; an unchanged surface inside a container that still hides content in that direction refuses with scroll_no_progress rather than repeating the requested distance. The movement field is absent where a tier verifies per pass (top/bottom, until), where the runtime cannot read a screen, or where a settle observation or a replay already owns that observation.',
   get: 'Read text or accessibility attributes from a snapshot ref or selector without changing the app. Use format text for visible content or attrs for the element attribute map.',
-  is: 'Check whether a selector satisfies a UI predicate such as visible, hidden, exists, absent, editable, selected, focused, or text. `absent` passes only when one readable, complete, unscoped, full-depth accessibility capture has zero matches. Use wait when the condition may appear asynchronously.',
+  is: 'Check whether a selector satisfies a UI predicate such as visible, hidden, exists, absent, editable, selected, focused, or text. `absent` passes only when one readable, complete, settled, unscoped, full-depth accessibility capture has zero matches. Use wait when the condition may appear asynchronously.',
   find: 'Find by text/label/value/role/id and run action',
   gesture:
     'Perform a structured pan, fling, swipe, pinch, rotate, transform, or drag gesture. Select the gesture kind, then provide only the inputs that apply to that kind.',
diff --git a/src/commands/interaction/runtime/wait-absent.test.ts b/src/commands/interaction/runtime/wait-absent.test.ts
index c9d3f833a8..2c5bf6f35f 100644
--- a/src/commands/interaction/runtime/wait-absent.test.ts
+++ b/src/commands/interaction/runtime/wait-absent.test.ts
@@ -141,6 +141,23 @@ test('wait absent rides out sparse and truncated captures without counting them
   assert.equal(result.waitedMs >= 600, true);
 });
 
+test('wait absent does not take a miss on a surface still moving after a gesture as absence', async () => {
+  const unsettled = {
+    snapshot: {
+      ...makeSnapshotState([]),
+      unsettledGesture: { action: 'scroll', positionals: ['down'] },
+    },
+  };
+  const device = absentDevice([unsettled, snapshot('Removed')]);
+
+  await assert.rejects(waitAbsent(device, 500), (error: unknown) => {
+    assert.ok(error instanceof AppError);
+    assert.equal(error.details?.reason, 'wait_target_present');
+    assert.equal(error.details?.readableCaptures, 1);
+    return true;
+  });
+});
+
 test('wait absent excludes sparse and truncated polls from deadline readable-capture evidence', async () => {
   const sparse = snapshot(undefined, {
     snapshotQuality: { state: 'sparse', backend: 'private-ax', reasonCode: 'sparse-tree' },
diff --git a/src/commands/interaction/runtime/wait-absent.ts b/src/commands/interaction/runtime/wait-absent.ts
index 65ec917126..afcd08970f 100644
--- a/src/commands/interaction/runtime/wait-absent.ts
+++ b/src/commands/interaction/runtime/wait-absent.ts
@@ -3,6 +3,7 @@ import { isUnreadableCaptureContentError } from '@agent-device/contracts/android
 import { AppError } from '@agent-device/kernel/errors';
 import {
   absenceCaptureOptionRefusal,
+  isUnprovableAbsence,
   type AbsenceObservation,
 } from '@agent-device/selectors/absence-observation';
 import {
@@ -63,7 +64,7 @@ export async function waitForAbsent<Runtime extends SelectorWaitRuntime>(
           selectorExpression,
           runtime.backend.platform,
         );
-        if (observation.kind === 'sparse' || observation.kind === 'truncated') {
+        if (isUnprovableAbsence(observation.kind)) {
           throw absenceObservationError(selectorExpression, observation, 'wait');
         }
         return observation;
@@ -130,8 +131,6 @@ function isWaitAbsentUnreadableError(error: unknown): boolean {
   return (
     details?.command === 'wait' &&
     details.predicate === 'absent' &&
-    (details.observation === 'sparse' ||
-      details.observation === 'truncated' ||
-      details.observation === 'unreadable')
+    (isUnprovableAbsence(details.observation) || details.observation === 'unreadable')
   );
 }
diff --git a/src/daemon/__tests__/is-runtime.test.ts b/src/daemon/__tests__/is-runtime.test.ts
index 6e044371fd..722948d9ab 100644
--- a/src/daemon/__tests__/is-runtime.test.ts
+++ b/src/daemon/__tests__/is-runtime.test.ts
@@ -1,4 +1,4 @@
-import { beforeEach, expect, test, vi } from 'vitest';
+import { afterEach, beforeEach, expect, test, vi } from 'vitest';
 import type { SnapshotResult } from '@agent-device/contracts/snapshot-runtime';
 import { buildSnapshotPresentationKey } from '@agent-device/kernel/snapshot';
 import { ANDROID_EMULATOR, IOS_SIMULATOR } from '../../__tests__/test-utils/device-fixtures.ts';
@@ -12,6 +12,8 @@ import { withTestDeviceInventory } from '../../__tests__/test-utils/device-inven
 import { makeSnapshotState } from '@agent-device/selectors/snapshot-geometry-fixtures';
 import type { DaemonRequest } from '../daemon-request.ts';
 import { selectorCaptureFixture } from './selector-capture-fixture.ts';
+import { markDeferredInteractionOutcome } from '../deferred-interaction-outcome.ts';
+import { formatGestureUnsettledWarning } from '@agent-device/capture-kit/post-gesture-stability';
 
 const { mockRunAppleRunnerCommand } = vi.hoisted(() => ({ mockRunAppleRunnerCommand: vi.fn() }));
 
@@ -28,6 +30,10 @@ beforeEach(() => {
   mockRunAppleRunnerCommand.mockResolvedValue({});
 });
 
+afterEach(() => {
+  vi.useRealTimers();
+});
+
 // `is` answers every one of its eight predicates from the resolved capture — `isCommand` never
 // reaches `backend.readText`. So its whole platform execution is the request-bound capture, and
 // these cases bind at `inspectFacts` / `bindDevice`, never at `-device/device-selection/dispatch-resolve`.
@@ -416,3 +422,49 @@ test('a failing predicate answers COMMAND_FAILED from the bound capture', async
   // The bound capture is what answered it.
   expect(fixture.captures.length).toBeGreaterThan(0);
 });
+
+test('a miss on a surface that never settled carries the unsettled fact, and the re-read captures afresh', async () => {
+  vi.useFakeTimers();
+  // Every capture shows the row at a new offset, so no two consecutive reads agree.
+  const fixture = selectorCaptureFixture({
+    snapshot: (_input, index) => ({
+      nodes: [
+        {
+          index: 0,
+          type: 'Cell',
+          identifier: 'row',
+          rect: { x: 0, y: 200 - index * 37, width: 390, height: 60 },
+        },
+      ],
+      backend: 'xctest',
+      producer: 'apple-runner',
+    }),
+  });
+  const sessionStore = makeSessionStore();
+  const session = makeIosAppSession('is-unsettled');
+  markDeferredInteractionOutcome({ session, command: 'scroll', positionals: [], flags: {} });
+  sessionStore.set('is-unsettled', session);
+  const isVisible = () =>
+    dispatchIsViaRuntime({
+      req: isRequest('is-unsettled', ['visible', 'id=target']),
+      sessionName: 'is-unsettled',
+      sessionStore,
+      inspectFacts: fixture.inspectFacts,
+      bindDevice: fixture.bindDevice,
+    });
+  const pending = isVisible();
+  // Just past the 1.5s stabilization deadline, so the re-read lands inside the cache window.
+  await vi.advanceTimersByTimeAsync(1_700);
+  const gesture = { action: 'scroll', positionals: [] };
+
+  const response = await pending;
+  expect(response?.ok === false && response.error.details).toMatchObject({
+    reason: 'selector_not_found',
+    unsettledGesture: gesture,
+    hint: expect.stringContaining(formatGestureUnsettledWarning(gesture)),
+  });
+  const captures = fixture.captures.length;
+  const reread = await isVisible();
+  expect(fixture.captures.length).toBe(captures + 1);
+  expect(reread?.ok === false && reread.error.details?.unsettledGesture).toBeUndefined();
+});
diff --git a/src/daemon/__tests__/post-gesture-no-effect-claim.test.ts b/src/daemon/__tests__/post-gesture-no-effect-claim.test.ts
index 6314be67f5..bfe0ddca12 100644
--- a/src/daemon/__tests__/post-gesture-no-effect-claim.test.ts
+++ b/src/daemon/__tests__/post-gesture-no-effect-claim.test.ts
@@ -17,7 +17,7 @@ import {
   capturePostGestureStabilizedResult,
   markDeferredInteractionOutcome,
 } from '../deferred-interaction-outcome.ts';
-import { formatGestureNoEffectWarning } from '../gesture-no-effect.ts';
+import { formatGestureNoEffectWarning } from '@agent-device/capture-kit/post-gesture-stability';
 import type { SessionState } from '../session-state.ts';
 import {
   chromeWithListSnapshot,
diff --git a/src/daemon/__tests__/post-gesture-stabilization.test.ts b/src/daemon/__tests__/post-gesture-stabilization.test.ts
index 18f532a523..d8c99751f8 100644
--- a/src/daemon/__tests__/post-gesture-stabilization.test.ts
+++ b/src/daemon/__tests__/post-gesture-stabilization.test.ts
@@ -330,6 +330,43 @@ test('capturePostGestureStabilizedResult keeps the ordinary never-quiet timeout
   );
 });
 
+test('a deadline that expires right after a rebased quiet pair is not reported as unsettled', async () => {
+  vi.useFakeTimers();
+  const session = makeSession('ios');
+  session.snapshot = makeSnapshotState(pickupSnapshot(500).nodes, {
+    snapshotQuality: { state: 'healthy', backend: 'tree' },
+  });
+  markPostGestureStabilization(session, 'scroll');
+  // Moving on the baseline backend until the final poll pair, which agrees on another backend:
+  // the loop rebases on it and then runs out of time with the surface at rest.
+  let call = 0;
+  const capture = vi.fn(async () => {
+    call += 1;
+    return call >= 8
+      ? makeSnapshotState(pickupSnapshot(640).nodes, {
+          snapshotQuality: { state: 'healthy', backend: 'private-ax' },
+        })
+      : makeSnapshotState(pickupSnapshot(100 + call * 40).nodes, {
+          snapshotQuality: { state: 'healthy', backend: 'tree' },
+        });
+  });
+
+  const resultPromise = withDiagnosticsScope({}, async () => ({
+    result: await capturePostGestureStabilizedResult({
+      session,
+      capture,
+      readSnapshot: (snapshot) => snapshot,
+    }),
+    rebased: countDiagnosticEventsByPhase(['post_gesture_snapshot_baseline_rebased']),
+    timeouts: countDiagnosticEventsByPhase(['post_gesture_snapshot_stabilization_timeout']),
+  }));
+  await vi.advanceTimersByTimeAsync(1_700);
+  const { result, rebased, timeouts } = await resultPromise;
+
+  assert.deepEqual([rebased, timeouts], [1, 1]);
+  assert.equal(result.unsettledGesture, undefined);
+});
+
 test('capturePostGestureStabilizedResult catches a frozen target even when the baseline came from a broader-scope capture than the post-gesture reads (iOS, live regression)', async () => {
   // Live shape (checkout-form.ad): the pre-gesture baseline is whatever
   // `session.snapshot` held from an earlier broad capture (e.g. a text-search
diff --git a/src/daemon/capture-disclosure.ts b/src/daemon/capture-disclosure.ts
index 87aa1bb3fd..1e594f1613 100644
--- a/src/daemon/capture-disclosure.ts
+++ b/src/daemon/capture-disclosure.ts
@@ -2,12 +2,13 @@ import type { SnapshotState } from '@agent-device/kernel/snapshot';
 import { systemSurfaceDisclosure } from '@agent-device/contracts/android-system-surface-disclosure';
 import { iosSystemSurfaceDisclosure } from '@agent-device/contracts/ios-system-surface';
 import { iosTargetActivationDisclosure } from '@agent-device/contracts/ios-target-activation';
+import { formatGestureUnsettledWarning } from '@agent-device/capture-kit/post-gesture-stability';
 import type { DaemonResponse } from './daemon-request.ts';
 
-/** The capture provenance a response must be disclosed against (#2438, #2682). */
+/** The capture provenance a response must be disclosed against (#2438, #2682, unsettled gestures). */
 export type CaptureProvenance = Pick<
   SnapshotState,
-  'systemSurfaceOnly' | 'iosSystemSurfaceBundleId' | 'targetActivation'
+  'systemSurfaceOnly' | 'iosSystemSurfaceBundleId' | 'targetActivation' | 'unsettledGesture'
 >;
 
 /**
@@ -58,20 +59,36 @@ export function withSystemSurfaceDisclosure(
 }
 
 /**
- * Disclose a foreground repair the consumed capture carried (#2682). The fact applies to the whole
- * tree, so it travels as response-level metadata and its sentence is APPENDED — an earlier warning
- * (staleness, quality, an occluding surface) is never replaced. The typed fact lands even when the
- * sentence was already carried: the field is this response's own claim, independent of who spoke.
+ * Disclose a fact about the whole answered tree (#2682 foreground repair, an unsettled gesture). Its
+ * sentence is APPENDED, never replacing an earlier warning, and the typed fact lands on either
+ * outcome (`data` or `error.details`) even when the sentence was already carried.
  */
+function withTreeFactDisclosure<K extends 'targetActivation' | 'unsettledGesture'>(
+  response: DaemonResponse,
+  key: K,
+  fact: CaptureProvenance[K],
+  sentence: (fact: NonNullable<CaptureProvenance[K]>) => string,
+): DaemonResponse {
+  if (!fact) return response;
+  const disclosed = appendDisclosure(response, sentence(fact), 'warnings');
+  return disclosed.ok
+    ? { ...disclosed, data: { ...disclosed.data, [key]: fact } }
+    : {
+        ...disclosed,
+        error: { ...disclosed.error, details: { ...disclosed.error.details, [key]: fact } },
+      };
+}
+
 export function withTargetActivationDisclosure(
   response: DaemonResponse,
   snapshot: CaptureProvenance | undefined,
 ): DaemonResponse {
-  const fact = snapshot?.targetActivation;
-  if (!fact) return response;
-  const disclosed = appendDisclosure(response, iosTargetActivationDisclosure(fact), 'warnings');
-  if (!disclosed.ok) return disclosed;
-  return { ...disclosed, data: { ...disclosed.data, targetActivation: fact } };
+  return withTreeFactDisclosure(
+    response,
+    'targetActivation',
+    snapshot?.targetActivation,
+    iosTargetActivationDisclosure,
+  );
 }
 
 /**
@@ -87,7 +104,12 @@ export function withCaptureDisclosures(params: {
 }): DaemonResponse {
   const { response, consumedTree, activationProof } = params;
   return withTargetActivationDisclosure(
-    withSystemSurfaceDisclosure(response, consumedTree),
+    withTreeFactDisclosure(
+      withSystemSurfaceDisclosure(response, consumedTree),
+      'unsettledGesture',
+      consumedTree?.unsettledGesture,
+      formatGestureUnsettledWarning,
+    ),
     activationProof?.state,
   );
 }
diff --git a/src/daemon/deferred-interaction-outcome.ts b/src/daemon/deferred-interaction-outcome.ts
index 79e6cc4d87..23208ad04a 100644
--- a/src/daemon/deferred-interaction-outcome.ts
+++ b/src/daemon/deferred-interaction-outcome.ts
@@ -30,7 +30,10 @@ import {
   snapshotSurfaceComparisonKey,
   type InteractionRetryTap,
 } from './interaction-outcome-policy.ts';
-import { runPostGestureStabilityLoop } from '@agent-device/capture-kit/post-gesture-stability';
+import {
+  runPostGestureStabilityLoop,
+  type PostGestureStabilityOutcome,
+} from '@agent-device/capture-kit/post-gesture-stability';
 import type { SessionState } from './session-state.ts';
 
 /**
@@ -262,10 +265,7 @@ async function captureInteractionOutcomeAwareSnapshot(
     });
   }
 
-  return {
-    snapshot: latest.snapshot,
-    ...withGestureNoEffectWarning(latest.annotations, stabilized.gestureNoEffect),
-  };
+  return resolvedPostGestureCapture(stabilized);
 }
 
 async function waitForDelayedInteractionSurfaceChange(
@@ -294,11 +294,7 @@ async function capturePostGestureAwareSnapshot(
     capture: async () => await capturePostActionSnapshotAttempt(params),
     readSnapshot: (attempt) => attempt.snapshot,
   });
-  const latest = stabilized.value;
-  return {
-    snapshot: latest.snapshot,
-    ...withGestureNoEffectWarning(latest.annotations, stabilized.gestureNoEffect),
-  };
+  return resolvedPostGestureCapture(stabilized);
 }
 
 async function capturePostActionSnapshotAttempt(
@@ -311,12 +307,6 @@ async function capturePostActionSnapshotAttempt(
   return await params.capture();
 }
 
-export type PostGestureStabilizedResult<T> = {
-  value: T;
-  /** See `PostGestureStabilityOutcome` in post-gesture-stability.ts (#1600/#1601). */
-  gestureNoEffect?: { action: string; positionals: string[] };
-};
-
 /**
  * Session-aware adapter over the pure stability loop
  * (`post-gesture-stability.ts`): reads the pending record, supplies the
@@ -329,7 +319,7 @@ export async function capturePostGestureStabilizedResult<T>(params: {
   capture: () => Promise<T>;
   readSnapshot: (result: T) => SnapshotState;
   initial?: T;
-}): Promise<PostGestureStabilizedResult<T>> {
+}): Promise<PostGestureStabilityOutcome<T>> {
   const { session, capture, readSnapshot } = params;
   const pending = session?.postGestureStabilization;
   if (!session || !supportsPostGestureStabilization(session.device) || !pending) {
@@ -364,6 +354,15 @@ export async function capturePostGestureStabilizedResult<T>(params: {
   return outcome;
 }
 
+/** The stabilized attempt as a capture result: the tree carries an unsettled outcome as its own fact. */
+function resolvedPostGestureCapture(
+  stabilized: PostGestureStabilityOutcome<DeferredOutcomeSnapshotAttempt>,
+): DeferredOutcomeCaptureResult {
+  const { snapshot, annotations } = stabilized.value;
+  if (stabilized.unsettledGesture) snapshot.unsettledGesture = stabilized.unsettledGesture;
+  return { snapshot, ...withGestureNoEffectWarning(annotations, stabilized.gestureNoEffect) };
+}
+
 function isPostGestureStabilizingAction(
   action: string,
   positionals: string[],
diff --git a/src/daemon/gesture-no-effect.ts b/src/daemon/gesture-no-effect.ts
index ea7924ee3b..38ce4d9cb3 100644
--- a/src/daemon/gesture-no-effect.ts
+++ b/src/daemon/gesture-no-effect.ts
@@ -1,20 +1,5 @@
 import type { SnapshotCaptureAnnotations } from '@agent-device/contracts/capture';
-
-/**
- * The agent-facing wording for a proven no-effect gesture. Names the exact
- * gesture, admits the honest ambiguity (at-edge is a legitimate no-op the
- * platform cannot distinguish), and hands over the one escape hatch that
- * moved a stuck list when synthesized scrolls did not (#1600, element-18:
- * raw `swipe` worked where scroll/fling/pan all silently no-opped).
- */
-export function formatGestureNoEffectWarning(action: string, positionals: string[]): string {
-  const gesture = [action, ...positionals].join(' ').trim();
-  return (
-    `${gesture} produced no visible change: the tree still matches its pre-gesture state. ` +
-    'Either the container is already at its edge, or it ignores synthesized scrolls — ' +
-    'a raw drag moves such lists: swipe x1 y1 x2 y2 (start inside the list).'
-  );
-}
+import { formatGestureNoEffectWarning } from '@agent-device/capture-kit/post-gesture-stability';
 
 /**
  * #1600: a proven no-effect gesture must reach the agent inside the very
diff --git a/src/daemon/interaction/internal/__tests__/find-target-activation-disclosure.test.ts b/src/daemon/interaction/internal/__tests__/find-target-activation-disclosure.test.ts
index 0e37269b9a..fdce22ef13 100644
--- a/src/daemon/interaction/internal/__tests__/find-target-activation-disclosure.test.ts
+++ b/src/daemon/interaction/internal/__tests__/find-target-activation-disclosure.test.ts
@@ -7,6 +7,8 @@ import type { DaemonResponse } from '../../../daemon-request.ts';
 import { legacyDispatchCapture } from '../../../__tests__/legacy-snapshot-capture-fixture.ts';
 import { getRuntimeBindings } from '../../../__tests__/interaction-get-runtime-fixture.ts';
 import { handleFindCommands } from '../../index.ts';
+import { markDeferredInteractionOutcome } from '../../../deferred-interaction-outcome.ts';
+import { formatGestureUnsettledWarning } from '@agent-device/capture-kit/post-gesture-stability';
 
 vi.mock('../../../snapshot-interactor-capture.ts', async () => {
   const fixture = await import('../../../__tests__/legacy-snapshot-capture-fixture.ts');
@@ -71,9 +73,12 @@ beforeEach(() => {
   legacyDispatchCapture.mockReset();
 });
 
-async function findClick(captures: Record<string, unknown>[]) {
+async function findClick(captures: Record<string, unknown>[], afterScroll = false) {
   const sessionStore = makeSessionStore();
-  sessionStore.set('default', makeIosSession('default', { appBundleId: 'com.example.app' }));
+  const session = makeIosSession('default', { appBundleId: 'com.example.app' });
+  if (afterScroll)
+    markDeferredInteractionOutcome({ session, command: 'scroll', positionals: [], flags: {} });
+  sessionStore.set('default', session);
   let call = 0;
   legacyDispatchCapture.mockImplementation(
     async () => captures[Math.min(call++, captures.length - 1)],
@@ -123,3 +128,32 @@ test('a find that stayed sparse reports the repair on the failure it returns', a
   const hint = String(response.error.details?.hint ?? '');
   expect(hint).toContain(iosTargetActivationDisclosure(FACT));
 });
+
+/** The tree a mutating find resolves against carries every provenance fact, not a hand-picked few. */
+test('a find that misses on a surface still moving after a scroll reports the unsettled fact', async () => {
+  const moving = Array.from({ length: 40 }, (_, call) => ({
+    ...RECOVERED_TREE,
+    nodes: [
+      RECOVERED_TREE.nodes[0],
+      { ...RECOVERED_TREE.nodes[1], label: 'Wi-Fi', rect: { ...SCREEN, y: 600 - call * 37 } },
+    ],
+  }));
+  const realSetTimeout = globalThis.setTimeout;
+  vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'Date'] });
+  let done = false;
+  const pending = findClick(moving, true).finally(() => (done = true));
+  // The route awaits real I/O between polls, so the faked clock advances while the test yields.
+  while (!done) {
+    await vi.advanceTimersByTimeAsync(50);
+    await new Promise((resolve) => realSetTimeout(resolve, 1));
+  }
+  const { response } = await pending;
+  vi.useRealTimers();
+
+  expect(response?.ok === false && response.error.details).toMatchObject({
+    unsettledGesture: { action: 'scroll', positionals: [] },
+    hint: expect.stringContaining(
+      formatGestureUnsettledWarning({ action: 'scroll', positionals: [] }),
+    ),
+  });
+});
diff --git a/src/daemon/interaction/internal/find-target-capture.ts b/src/daemon/interaction/internal/find-target-capture.ts
index ba42c27bee..f1698f340d 100644
--- a/src/daemon/interaction/internal/find-target-capture.ts
+++ b/src/daemon/interaction/internal/find-target-capture.ts
@@ -1,11 +1,7 @@
 import type { FindLocator } from '@agent-device/selectors';
 import type { BoundSelectorCapture } from '../../selector-capture-binding.ts';
-import type {
-  SnapshotKeyboardBandFact,
-  SnapshotQualityVerdict,
-  SnapshotState,
-} from '@agent-device/kernel/snapshot';
-import type { RequestActivationProof } from '../../capture-disclosure.ts';
+import type { SnapshotQualityVerdict, SnapshotState } from '@agent-device/kernel/snapshot';
+import type { CaptureProvenance, RequestActivationProof } from '../../capture-disclosure.ts';
 import { createSelectorCaptureRuntime } from '../../selector-capture-runtime.ts';
 import { SessionStore } from '../../session-store.ts';
 import type { DaemonRequest, DaemonResponse } from '../../daemon-request.ts';
@@ -13,14 +9,8 @@ import type { SessionState } from '../../session-state.ts';
 import { errorResponse } from '@agent-device/kernel/contracts';
 
 /** The tree a mutating find resolves its target against, plus what the capture disclosed. */
-export type FindTargetTree = {
-  nodes: SnapshotState['nodes'];
-  snapshotQuality?: SnapshotQualityVerdict;
-  systemSurfaceOnly?: boolean;
-  iosSystemSurfaceBundleId?: string;
-  /** The keyboard band this capture's producer measured, when it measured one (#2660). */
-  keyboard?: SnapshotKeyboardBandFact;
-};
+export type FindTargetTree = CaptureProvenance &
+  Pick<SnapshotState, 'nodes' | 'snapshotQuality' | 'keyboard'>;
 
 /**
  * Find's target capture. A mutating find (click/fill/focus/type) resolves its target from its
@@ -75,13 +65,7 @@ export function createFindTargetCapture(
         },
       },
     });
-    return {
-      nodes: snapshot.nodes,
-      snapshotQuality: snapshot.snapshotQuality,
-      systemSurfaceOnly: snapshot.systemSurfaceOnly,
-      iosSystemSurfaceBundleId: snapshot.iosSystemSurfaceBundleId,
-      ...(snapshot.keyboard ? { keyboard: snapshot.keyboard } : {}),
-    };
+    return snapshot;
   };
 }
 
diff --git a/src/daemon/selector-capture-runtime.ts b/src/daemon/selector-capture-runtime.ts
index 5f7c9c7e61..1b24f5510a 100644
--- a/src/daemon/selector-capture-runtime.ts
+++ b/src/daemon/selector-capture-runtime.ts
@@ -273,7 +273,7 @@ function canUseSessionSnapshotCache(
   if (request.cache?.useSessionSnapshot !== true) return false;
   if (getActiveAndroidSnapshotFreshness(session)) return false;
   if (shouldBypassForPostGestureStabilization(session, request)) return false;
-  return true;
+  return session.snapshot?.unsettledGesture === undefined;
 }
 
 function isFreshSelectorSnapshot(snapshot: SnapshotState, timestamp: number): boolean {
diff --git a/test/integration/ios-simulator-e2e-visibility-scroll.test.ts b/test/integration/ios-simulator-e2e-visibility-scroll.test.ts
index 4824634682..fd79c11b4d 100644
--- a/test/integration/ios-simulator-e2e-visibility-scroll.test.ts
+++ b/test/integration/ios-simulator-e2e-visibility-scroll.test.ts
@@ -52,3 +52,45 @@ test('a stalled capture retries without scrolling or consuming an attempt', asyn
   assert.deepEqual(probeAttempts, [1, 1]);
   assert.deepEqual(scrollAttempts, []);
 });
+
+/**
+ * The CI failure shape: the element is on screen only at offset 1, and the first read after each
+ * scroll lands on a surface still moving, so it misses with `unsettledGesture`.
+ */
+function listWithUnsettledFirstReads(visibleAt?: number) {
+  let offset = 0;
+  let moving = false;
+  const probes: number[] = [];
+  const scrolls: number[] = [];
+  const probe = async (attempt: number) => {
+    probes.push(attempt);
+    const unsettled = moving;
+    moving = false;
+    if (!unsettled && offset === visibleAt) return result(0);
+    return result(1, unsettled ? { unsettledGesture: { action: 'scroll', positionals: [] } } : {});
+  };
+  const scroll = async (attempt: number) => {
+    scrolls.push(attempt);
+    offset += 1;
+    moving = true;
+  };
+  return { probes, scrolls, probe, scroll };
+}
+
+test('an unsettled miss after the scroll that reached the element is re-read at the same offset', async () => {
+  const list = listWithUnsettledFirstReads(1);
+
+  await searchForVisibleElement('id="target"', list.probe, list.scroll);
+
+  assert.deepEqual([list.probes, list.scrolls], [[1, 2, 2], [1]]);
+});
+
+test('a real absence still fails after the forward scrolls, naming every step', async () => {
+  const list = listWithUnsettledFirstReads();
+
+  await assert.rejects(
+    searchForVisibleElement('id="target"', list.probe, list.scroll),
+    /scroll after attempt 3: [\s\S]*probe 4:/,
+  );
+  assert.deepEqual(list.scrolls, [1, 2, 3]);
+});
diff --git a/test/integration/ios-simulator-e2e/live-assertions.ts b/test/integration/ios-simulator-e2e/live-assertions.ts
index f01d909243..af9cdbf757 100644
--- a/test/integration/ios-simulator-e2e/live-assertions.ts
+++ b/test/integration/ios-simulator-e2e/live-assertions.ts
@@ -41,9 +41,10 @@ export function snapshotNodes(result: { json?: any }): LiveSnapshotNode[] {
 }
 
 const SCROLL_SEARCH_ATTEMPTS = 4;
-// A stalled capture says nothing about where the element is, so it must not consume the scroll
-// budget outright; a couple of retries absorb a slow runner without masking a real absence.
-const SCROLL_SEARCH_STALL_RETRIES = 2;
+// A stalled capture, or one taken while the last scroll was still moving, says nothing about where
+// the element is, so re-reading it must not consume a scroll. A couple of re-reads per scroll absorb
+// a slow runner without masking a real absence.
+const SCROLL_SEARCH_REREADS = 2;
 
 export async function assertElementTextAfterScrolling(
   context: LiveContext,
@@ -64,7 +65,7 @@ export async function assertElementTextAfterScrolling(
         'scroll',
         'down',
         '0.75',
-      ]).then(() => undefined),
+      ]).then((result) => result.json?.data),
   );
   await assertElementText(context, selector, expected);
 }
@@ -78,31 +79,31 @@ export async function assertElementTextAfterScrolling(
 export async function searchForVisibleElement(
   selector: string,
   probeVisibility: (attempt: number) => Promise<CliJsonResult>,
-  scrollAfterAttempt: (attempt: number) => Promise<void>,
+  scrollAfterAttempt: (attempt: number) => Promise<unknown>,
 ): Promise<void> {
-  let stallRetriesLeft = SCROLL_SEARCH_STALL_RETRIES;
-  let lastFailure: CliJsonResult | undefined;
+  let rereadsLeft = SCROLL_SEARCH_REREADS;
+  const history: string[] = [];
 
   for (let attempt = 1; attempt <= SCROLL_SEARCH_ATTEMPTS;) {
     const probe = await probeVisibility(attempt);
+    history.push(`probe ${attempt}: ${JSON.stringify(probe.json ?? { status: probe.status })}`);
     if (probe.status === 0) return;
-    lastFailure = probe;
 
-    // The snapshot never came back, so the surface was never read. Scrolling here would move the
-    // surface for a reason unrelated to visibility and spend an attempt on no evidence.
-    if (probe.json?.error?.details?.captureStalled === true && stallRetriesLeft > 0) {
-      stallRetriesLeft -= 1;
+    const details = probe.json?.error?.details;
+    const readNothing = details?.captureStalled === true || details?.unsettledGesture !== undefined;
+    if (readNothing && rereadsLeft > 0) {
+      rereadsLeft -= 1;
       continue;
     }
 
     attempt += 1;
     if (attempt <= SCROLL_SEARCH_ATTEMPTS) {
-      await scrollAfterAttempt(attempt - 1);
+      const scrolled = await scrollAfterAttempt(attempt - 1);
+      history.push(`scroll after attempt ${attempt - 1}: ${JSON.stringify(scrolled ?? null)}`);
+      rereadsLeft = SCROLL_SEARCH_REREADS;
     }
   }
-  assert.fail(
-    `${selector} did not become visible after scrolling\nlast visibility probe: ${JSON.stringify(lastFailure?.json ?? null)}`,
-  );
+  assert.fail(`${selector} did not become visible after scrolling\n${history.join('\n')}`);
 }
 
 function requireNode(
diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md
index 8e1c4643f4..ad3175a063 100644
--- a/website/docs/docs/commands.md
+++ b/website/docs/docs/commands.md
@@ -557,7 +557,8 @@ agent-device is text 'id="greeting"' "Welcome back"
 - Supported predicates are `visible`, `hidden`, `exists`, `absent`, `editable`, `selected`, `focused`, and `text`.
 - `is visible` checks whether the resolved element is present in the current visible snapshot viewport. A node without its own rect still passes when a visible ancestor within the viewport provides the on-screen geometry.
 - `is exists` only checks whether the selector matches in the current snapshot.
-- `is absent` passes only when the selector has zero matches in one readable, complete, unscoped, full-depth accessibility capture. It does not mean hidden; `--scope` and `--depth` are rejected, and sparse, unreadable, or truncated captures fail closed.
+- `is absent` passes only when the selector has zero matches in one readable, complete, settled, unscoped, full-depth accessibility capture. It does not mean hidden; `--scope` and `--depth` are rejected, and sparse, unreadable, truncated, or unsettled captures fail closed.
+- A read that answers from the first capture after a `scroll`, `swipe`, or `gesture swipe` waits for two consecutive captures to agree. When the surface is still changing when that budget runs out, `is`, `get`, `find`, and `wait` carry `unsettledGesture` (`{ "action", "positionals" }`) in `error.details` or `data` and append a warning, and `snapshot` appends the warning. A miss on that capture is not proof of absence: read again. `is absent` refuses it with `observation: "unsettled"`, and `wait absent` keeps polling.
 - `wait text` is a text-presence wait, not a hittability assertion.
 - Strict `wait absent` is not exported to Maestro's lenient `notVisible` condition; Maestro export reports it as unsupported unless an exact zero-candidate primitive becomes available.
 - `is text <selector> <value>` compares the resolved element text against the expected value.
@@ -817,7 +818,7 @@ state the session app was found in and why the runner activated it:
   tripped before dispatching.
 - The disclosure rides capture-consuming commands — `snapshot`, `find`, `get`, `is`, `wait`, and an
   interaction whose target tree was captured for it — at every response level, including
-  `--level digest`. It is disclosed only for the command that paid for the repair: a read answered
+  `--level digest`. On a failure the typed fact is in `error.details` and the sentence in its hint. It is disclosed only for the command that paid for the repair: a read answered
   from a cached or stored tree did no device work and reports no repair of its own.
 - In text mode the CLI prints every response warning as a `Warning:` line after the command's own
   output, for every command — not only `snapshot`. Four commands declare their stdout to be the

From fd8277e3919fb4c3eadcb3f20555842cd1c367bf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 24 Sep 2026 07:48:31 +0200
Subject: [PATCH 074/132] refactor(platform-apple): dedupe xctrace logic behind
 perf-xctrace and split perf.ts (#2823)

* refactor(platform-apple): dedupe xctrace recording, export and trace checks behind perf-xctrace

perf.ts now delegates timed xctrace recording, table export and the
trace-has-data check to perf-xctrace.ts, which owns one record-argv
builder, one retry loop, one export implementation and one data check.
Process-target resolution moves to perf-target.ts so perf-xctrace no
longer imports perf.ts, bringing perf.ts under 1,000 lines.

perf.ts and perf-frame.ts share one xctrace XML reference resolver in
perf-xml.ts. physical-device-coredevice.ts reads device details through
the shared devicectl --json-output helper, which now carries the failure
payload and cleans up its temp file when the command throws.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* refactor(platform-apple): tighten the xctrace record retry loop and shared process-name reader

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(platform-apple): keep perf-target resolution lazy behind the perf facade

perf-facade.ts, perf.ts, and perf-xctrace.ts all statically imported the
newly split perf-target.ts, adding it as a genuinely new eager module to
the facade's closure. Load it on demand at each call site instead, the
same pattern already used by simctl-facade.ts and
runner-operations-facade.ts, keeping the facade's process-target path
implementation-lazy.

* refactor(platform-apple): drop the unimported perf-target forwarders from the perf facade

readAppleProcessSamples, resolveAppleExecutable and resolveIosDevicePerfTarget
had no importer through @agent-device/platform-apple/perf; perf.ts and
perf-xctrace.ts load perf-target.ts directly. The package is private and the
async forwarders were added on this unreleased branch, so remove them and
their .fallowrc.json entries instead of keeping them alive by allowlist.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .fallowrc.json                                |   3 -
 .../src/core/__tests__/perf-target.test.ts    |  26 +
 .../src/core/__tests__/perf.test.ts           |  24 -
 packages/platform-apple/src/core/devicectl.ts |  41 +-
 .../src/core/display-inventory.ts             |   6 +-
 .../platform-apple/src/core/perf-frame.ts     |  42 +-
 .../platform-apple/src/core/perf-target.ts    | 182 +++++++
 .../platform-apple/src/core/perf-xctrace.ts   | 249 ++++++---
 packages/platform-apple/src/core/perf-xml.ts  |  49 +-
 packages/platform-apple/src/core/perf.ts      | 503 ++----------------
 .../src/core/physical-device-coredevice.ts    | 124 ++---
 packages/platform-apple/src/perf-facade.ts    |   7 +-
 12 files changed, 557 insertions(+), 699 deletions(-)
 create mode 100644 packages/platform-apple/src/core/__tests__/perf-target.test.ts
 create mode 100644 packages/platform-apple/src/core/perf-target.ts

diff --git a/.fallowrc.json b/.fallowrc.json
index 117ad4dcb4..7c3e938e4d 100644
--- a/.fallowrc.json
+++ b/.fallowrc.json
@@ -115,9 +115,6 @@
         "isRetryableIosDeviceTraceRecordFailure",
         "resolveIosDevicePerfHint",
         "captureAppleMemorySnapshot",
-        "readAppleProcessSamples",
-        "resolveAppleExecutable",
-        "resolveIosDevicePerfTarget",
         "sampleAppleFramePerf",
         "sampleAppleMemoryPerf",
         "cleanupAppleXctracePerfCapture",
diff --git a/packages/platform-apple/src/core/__tests__/perf-target.test.ts b/packages/platform-apple/src/core/__tests__/perf-target.test.ts
new file mode 100644
index 0000000000..9ffdc72b9f
--- /dev/null
+++ b/packages/platform-apple/src/core/__tests__/perf-target.test.ts
@@ -0,0 +1,26 @@
+import { test } from 'vitest';
+import assert from 'node:assert/strict';
+import { parseApplePsOutput } from '../perf-target.ts';
+
+test('parseApplePsOutput reads pid cpu rss and command columns', () => {
+  const rows = parseApplePsOutput(
+    ['123 12.5 45678 /Applications/Test.app/Contents/MacOS/Test --flag', '456 0.0 2048 Test'].join(
+      '\n',
+    ),
+  );
+
+  assert.deepEqual(rows, [
+    {
+      pid: 123,
+      cpuPercent: 12.5,
+      rssKb: 45678,
+      command: '/Applications/Test.app/Contents/MacOS/Test --flag',
+    },
+    {
+      pid: 456,
+      cpuPercent: 0,
+      rssKb: 2048,
+      command: 'Test',
+    },
+  ]);
+});
diff --git a/packages/platform-apple/src/core/__tests__/perf.test.ts b/packages/platform-apple/src/core/__tests__/perf.test.ts
index 87f1b9fa44..0012fca1e2 100644
--- a/packages/platform-apple/src/core/__tests__/perf.test.ts
+++ b/packages/platform-apple/src/core/__tests__/perf.test.ts
@@ -16,7 +16,6 @@ vi.mock('@agent-device/host-kit/command', async (importOriginal) => {
 import {
   buildAppleMemorySnapshotSupport,
   captureAppleMemorySnapshot,
-  parseApplePsOutput,
   sampleAppleFramePerf,
   sampleAppleMemoryPerf,
 } from '../perf.ts';
@@ -115,29 +114,6 @@ test('buildAppleMemorySnapshotSupport never emits the internal apple platform',
   }
 });
 
-test('parseApplePsOutput reads pid cpu rss and command columns', () => {
-  const rows = parseApplePsOutput(
-    ['123 12.5 45678 /Applications/Test.app/Contents/MacOS/Test --flag', '456 0.0 2048 Test'].join(
-      '\n',
-    ),
-  );
-
-  assert.deepEqual(rows, [
-    {
-      pid: 123,
-      cpuPercent: 12.5,
-      rssKb: 45678,
-      command: '/Applications/Test.app/Contents/MacOS/Test --flag',
-    },
-    {
-      pid: 456,
-      cpuPercent: 0,
-      rssKb: 2048,
-      command: 'Test',
-    },
-  ]);
-});
-
 test('parseAppleFramePerfSample summarizes app hitches and worst windows', () => {
   const sample = parseAppleFramePerfSample({
     hitchesXml: makeAppleHitchesXml(),
diff --git a/packages/platform-apple/src/core/devicectl.ts b/packages/platform-apple/src/core/devicectl.ts
index d1a921ff7c..3403b37068 100644
--- a/packages/platform-apple/src/core/devicectl.ts
+++ b/packages/platform-apple/src/core/devicectl.ts
@@ -184,7 +184,9 @@ export type IosDevicectlJsonOutcome =
       ok: false;
       reason: IosDevicectlJsonFailureReason;
       args: string[];
-      result?: ExecResult;
+      result: ExecResult;
+      /** The JSON a failed command still wrote, when it was readable. */
+      payload?: unknown;
       cause?: string;
     };
 
@@ -210,28 +212,35 @@ export async function runIosDevicectlJsonRequest(options: {
     `${options.jsonPrefix}-${hostProcessId()}-${Date.now()}-${Math.random().toString(36).slice(2)}.json`,
   );
   const args = [...options.args, '--json-output', jsonPath];
-  const result = await runXcrun(args, {
-    allowFailure: true,
-    signal: options.signal,
-    timeoutMs: options.timeoutMs ?? IOS_DEVICECTL_TIMEOUT_MS,
-  });
-
   try {
+    const result = await runXcrun(args, {
+      allowFailure: true,
+      signal: options.signal,
+      timeoutMs: options.timeoutMs ?? IOS_DEVICECTL_TIMEOUT_MS,
+    });
     if (result.exitCode !== 0) {
-      if (options.tolerateFailurePayload) {
-        const failurePayload = await readJsonFile(jsonPath).catch(() => undefined);
-        if (failurePayload !== undefined && options.tolerateFailurePayload(failurePayload)) {
-          return { ok: true, payload: failurePayload };
-        }
+      const failurePayload = await readJsonFile(jsonPath).catch(() => undefined);
+      if (failurePayload !== undefined && options.tolerateFailurePayload?.(failurePayload)) {
+        return { ok: true, payload: failurePayload };
       }
-      return { ok: false, reason: 'command-failed', args, result };
+      return { ok: false, reason: 'command-failed', args, result, payload: failurePayload };
     }
+    return await readIosDevicectlJsonPayload(jsonPath, args, result);
+  } finally {
+    await unlinkHostFile(jsonPath).catch(() => {});
+  }
+}
+
+async function readIosDevicectlJsonPayload(
+  jsonPath: string,
+  args: string[],
+  result: ExecResult,
+): Promise<IosDevicectlJsonOutcome> {
+  try {
     return { ok: true, payload: await readJsonFile(jsonPath) };
   } catch (error) {
     if (error instanceof AppError) throw error;
     return { ok: false, reason: 'unreadable-json', args, result, cause: String(error) };
-  } finally {
-    await unlinkHostFile(jsonPath).catch(() => {});
   }
 }
 
@@ -251,7 +260,7 @@ async function runIosDevicectlJsonCommand(
   const outcome = await runIosDevicectlJsonRequest(options);
   if (outcome.ok) return outcome.payload;
 
-  if (outcome.reason === 'command-failed' && outcome.result) {
+  if (outcome.reason === 'command-failed') {
     const { stdout, stderr } = outcome.result;
     throw new AppError(
       'COMMAND_FAILED',
diff --git a/packages/platform-apple/src/core/display-inventory.ts b/packages/platform-apple/src/core/display-inventory.ts
index 3e72731e74..ab995efa04 100644
--- a/packages/platform-apple/src/core/display-inventory.ts
+++ b/packages/platform-apple/src/core/display-inventory.ts
@@ -103,11 +103,7 @@ export async function queryAppleDisplayInventory(
       signal: options.signal,
     });
     if (!outcome.ok) {
-      emitUnresolvedDiagnostic(
-        device,
-        outcome.reason,
-        outcome.result ? outcome.result.stderr.trim() : (outcome.cause ?? ''),
-      );
+      emitUnresolvedDiagnostic(device, outcome.reason, outcome.result.stderr.trim());
       return unresolvedInventory();
     }
     const displays = parseCoreDeviceDisplays(outcome.payload);
diff --git a/packages/platform-apple/src/core/perf-frame.ts b/packages/platform-apple/src/core/perf-frame.ts
index dc8cbda192..ce2914af79 100644
--- a/packages/platform-apple/src/core/perf-frame.ts
+++ b/packages/platform-apple/src/core/perf-frame.ts
@@ -3,10 +3,11 @@ import { roundOneDecimal, roundPercent } from '@agent-device/kernel/numeric';
 import { parseXmlDocumentSync, type XmlNode } from '@agent-device/xml';
 import {
   findAllXmlNodes,
-  findFirstXmlNode,
-  parseDirectXmlNumber,
   readSchemaColumns,
+  rememberXmlReferences,
   resolveXmlNumber,
+  resolveXmlProcess,
+  type XmlReference,
 } from './perf-xml.ts';
 
 const MAX_WORST_WINDOWS = 3;
@@ -54,11 +55,6 @@ type AppleHitchSchemaIndexes = {
   isSystem: number;
 };
 
-type XmlReference = {
-  numberValue?: number | null;
-  process?: { pid?: number; name?: string } | null;
-};
-
 export function parseAppleFramePerfSample(options: {
   hitchesXml: string;
   frameLifetimesXml: string;
@@ -236,17 +232,6 @@ function parseTable(xml: string, schemaName: string): { rows: XmlNode[]; schema:
   };
 }
 
-function rememberXmlReferences(elements: XmlNode[], references: Map<string, XmlReference>): void {
-  for (const element of elements) {
-    rememberXmlReferences(element.children, references);
-    if (!element.attributes.id) continue;
-    references.set(element.attributes.id, {
-      numberValue: parseDirectXmlNumber(element),
-      process: readDirectProcess(element),
-    });
-  }
-}
-
 function resolveXmlBoolean(
   element: XmlNode | undefined,
   references: Map<string, XmlReference>,
@@ -255,24 +240,3 @@ function resolveXmlBoolean(
   if (value === null) return null;
   return value !== 0;
 }
-
-function resolveXmlProcess(
-  element: XmlNode | undefined,
-  references: Map<string, XmlReference>,
-): { pid?: number; name?: string } | null {
-  if (!element) return null;
-  if (element.attributes.ref) return references.get(element.attributes.ref)?.process ?? null;
-  return readDirectProcess(element);
-}
-
-function readDirectProcess(element: XmlNode | undefined): { pid?: number; name?: string } | null {
-  if (!element || element.children.some((child) => child.name === 'sentinel')) return null;
-  const pidNode = findFirstXmlNode(element.children, (child) => child.name === 'pid');
-  const pid = parseDirectXmlNumber(pidNode);
-  const name = (element.attributes.fmt ?? '').replace(/\s+\(\d+\)$/, '').trim();
-  if (pid === null && name.length === 0) return null;
-  return {
-    pid: pid ?? undefined,
-    name: name.length > 0 ? name : undefined,
-  };
-}
diff --git a/packages/platform-apple/src/core/perf-target.ts b/packages/platform-apple/src/core/perf-target.ts
new file mode 100644
index 0000000000..facc6e8650
--- /dev/null
+++ b/packages/platform-apple/src/core/perf-target.ts
@@ -0,0 +1,182 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isMacOs, type DeviceInfo } from '@agent-device/kernel/device';
+import { AppError } from '@agent-device/kernel/errors';
+import { requireExecSuccess, type ExecResult } from '@agent-device/host-kit/command';
+import { splitNonEmptyTrimmedLines } from '@agent-device/kernel/record';
+import type { IosDeviceProcessInfo } from './app-info.ts';
+import { resolveIosPhysicalDeviceControl } from './physical-device-control.ts';
+import { readInfoPlistString } from './plist.ts';
+import { buildSimctlArgsForDevice } from './simctl.ts';
+import { runAppleToolCommand, runXcrun } from './tool-provider.ts';
+
+const APPLE_PERF_TIMEOUT_MS = 15_000;
+
+export type AppleProcessSample = {
+  pid: number;
+  cpuPercent: number;
+  rssKb: number;
+  command: string;
+};
+
+export function parseApplePsOutput(stdout: string): AppleProcessSample[] {
+  const rows: AppleProcessSample[] = [];
+  for (const line of splitNonEmptyTrimmedLines(stdout)) {
+    const match = line.match(/^(\d+)\s+([0-9]+(?:\.[0-9]+)?)\s+(\d+)\s+(.+)$/);
+    if (!match) continue;
+    const [pidText, cpuText, rssText, commandText] = match.slice(1);
+    if (
+      pidText === undefined ||
+      cpuText === undefined ||
+      rssText === undefined ||
+      commandText === undefined
+    ) {
+      continue;
+    }
+    const pid = Number(pidText);
+    const cpuPercent = Number(cpuText);
+    const rssKb = Number(rssText);
+    const command = commandText.trim();
+    if (!Number.isFinite(pid) || !Number.isFinite(cpuPercent) || !Number.isFinite(rssKb)) {
+      continue;
+    }
+    rows.push({ pid, cpuPercent, rssKb, command });
+  }
+  return rows;
+}
+
+export async function resolveAppleExecutable(
+  device: DeviceInfo,
+  appBundleId: string,
+): Promise<{ executableName: string; executablePath?: string }> {
+  const appPath = isMacOs(device)
+    ? await resolveMacOsBundlePath(appBundleId)
+    : await resolveIosSimulatorAppContainer(device, appBundleId);
+  const infoPlistPath = isMacOs(device)
+    ? path.join(appPath, 'Contents', 'Info.plist')
+    : path.join(appPath, 'Info.plist');
+  const executableName = await readInfoPlistString(infoPlistPath, 'CFBundleExecutable');
+  if (!executableName) {
+    throw new AppError('COMMAND_FAILED', `Failed to resolve executable for ${appBundleId}`, {
+      appBundleId,
+      appPath,
+    });
+  }
+
+  return {
+    executableName,
+    executablePath: isMacOs(device)
+      ? path.join(appPath, 'Contents', 'MacOS', executableName)
+      : path.join(appPath, executableName),
+  };
+}
+
+export async function resolveIosDevicePerfTarget(
+  device: DeviceInfo,
+  appBundleId: string,
+): Promise<IosDeviceProcessInfo[]> {
+  const { appBundleUrl, processes } = await resolveIosPhysicalDeviceControl(
+    device,
+  ).resolveAppProcesses(device, appBundleId);
+  const appBundlePath = fileURLToPath(appBundleUrl);
+  if (processes.length === 0) {
+    throw new AppError('COMMAND_FAILED', `No running process found for ${appBundleId}`, {
+      appBundleId,
+      deviceId: device.id,
+      appBundlePath,
+      hint: 'Run open <app> for this session again to ensure the iOS app is active, then retry perf.',
+    });
+  }
+
+  return processes;
+}
+
+async function resolveMacOsBundlePath(appBundleId: string): Promise<string> {
+  const query = `kMDItemCFBundleIdentifier == "${appBundleId.replaceAll('"', String.raw`\"`)}"`;
+  const result = requireExecSuccess(
+    await runAppleToolCommand('mdfind', [query], {
+      allowFailure: true,
+      timeoutMs: APPLE_PERF_TIMEOUT_MS,
+    }),
+    `Failed to resolve macOS app bundle for ${appBundleId}`,
+    { appBundleId },
+  );
+
+  const bundlePath = result.stdout
+    .split('\n')
+    .map((entry) => entry.trim())
+    .find((entry) => entry.endsWith('.app'));
+  if (!bundlePath) {
+    throw new AppError('APP_NOT_INSTALLED', `No macOS app found for ${appBundleId}`, {
+      appBundleId,
+    });
+  }
+  return bundlePath;
+}
+
+async function resolveIosSimulatorAppContainer(
+  device: DeviceInfo,
+  appBundleId: string,
+): Promise<string> {
+  const args = buildSimctlArgsForDevice(device, [
+    'get_app_container',
+    device.id,
+    appBundleId,
+    'app',
+  ]);
+  const result = requireExecSuccess(
+    await runXcrun(args, {
+      allowFailure: true,
+      timeoutMs: APPLE_PERF_TIMEOUT_MS,
+    }),
+    `Failed to resolve iOS simulator app container for ${appBundleId}`,
+    {
+      appBundleId,
+      hint: 'Ensure the iOS simulator app is installed and booted, then retry perf.',
+    },
+  );
+  const appPath = result.stdout.trim();
+  if (appPath.length === 0) {
+    throw new AppError(
+      'APP_NOT_INSTALLED',
+      `No iOS simulator app container found for ${appBundleId}`,
+      {
+        appBundleId,
+      },
+    );
+  }
+  return appPath;
+}
+
+export async function readAppleProcessSamples(
+  device: DeviceInfo,
+  executable: { executableName: string; executablePath?: string },
+): Promise<AppleProcessSample[]> {
+  const args = isMacOs(device)
+    ? ['-axo', 'pid=,%cpu=,rss=,command=']
+    : buildSimctlArgsForDevice(device, [
+        'spawn',
+        device.id,
+        'ps',
+        '-axo',
+        'pid=,%cpu=,rss=,command=',
+      ]);
+  const result = isMacOs(device)
+    ? await runAppleToolCommand('ps', args, { timeoutMs: APPLE_PERF_TIMEOUT_MS })
+    : await runAppleSimulatorProcessCommand(args);
+  const { matchesAppleExecutableProcess } = await import('./perf-process-identity.ts');
+  return parseApplePsOutput(result.stdout).filter((processInfo) =>
+    matchesAppleExecutableProcess(processInfo.command, executable),
+  );
+}
+
+async function runAppleSimulatorProcessCommand(args: string[]): Promise<ExecResult> {
+  const result = await runXcrun(args, {
+    allowFailure: true,
+    timeoutMs: APPLE_PERF_TIMEOUT_MS,
+  });
+  if (result.exitCode === 0) return result;
+  return await runAppleToolCommand('ps', ['-axo', 'pid=,%cpu=,rss=,command='], {
+    timeoutMs: APPLE_PERF_TIMEOUT_MS,
+  });
+}
diff --git a/packages/platform-apple/src/core/perf-xctrace.ts b/packages/platform-apple/src/core/perf-xctrace.ts
index 87a622f1ab..44602afbc4 100644
--- a/packages/platform-apple/src/core/perf-xctrace.ts
+++ b/packages/platform-apple/src/core/perf-xctrace.ts
@@ -33,16 +33,11 @@ import {
   parseAppleTimeProfileSummary,
   type AppleTimeProfileFunction,
 } from './perf-time-profile.ts';
-import {
-  isRetryableIosDeviceTraceRecordFailure,
-  prepareAppleTraceRecordRetry,
-  readAppleProcessSamples,
-  resolveAppleExecutable,
-  resolveIosDevicePerfHint,
-  resolveIosDevicePerfTarget,
-} from './perf.ts';
+import { IOS_DEVICECTL_DEFAULT_HINT, resolveIosDevicectlHint } from './devicectl.ts';
 import { runXcrun } from './tool-provider.ts';
 
+// Physical device tracing can take materially longer to initialize than the 1s sample window.
+const IOS_DEVICE_PERF_RECORD_TIMEOUT_MS = 60_000;
 const IOS_DEVICE_PERF_EXPORT_TIMEOUT_MS = 15_000;
 const IOS_DEVICE_TRACE_RECORD_MAX_ATTEMPTS = 3;
 const IOS_DEVICE_TRACE_RECORD_RETRY_DELAY_MS = 1_500;
@@ -52,6 +47,16 @@ const APPLE_XCTRACE_STOP_FORCE_TIMEOUT_MS = 5_000;
 
 export type AppleXctracePerfMode = 'cpu-profile' | 'trace';
 
+type AppleXctraceRecordTarget = number[] | 'all-processes';
+
+type AppleXctraceRecordAttempt<T> = { recorded: T } | { failure: ExecResult };
+
+export type AppleXctraceTimedRecord = {
+  startedAt: string;
+  endedAt: string;
+  capturedAtMs: number;
+};
+
 export type AppleXctracePerfCapture = {
   kind: 'xctrace';
   mode: AppleXctracePerfMode;
@@ -112,15 +117,24 @@ export async function startAppleXctracePerfCapture(params: {
   const args = buildAppleXctraceRecordArgs({
     device: params.device,
     template: params.template,
-    targetPids: target.pids,
+    target: target.pids,
     outPath: params.outPath,
   });
   const startedAt = new Date().toISOString();
-  const background = await startAppleXctraceRecordWithRetry(args, params.outPath, {
-    device: params.device,
-    appBundleId: params.appBundleId,
-    failureMessage: `Failed to start Apple xctrace ${params.mode} capture for ${params.appBundleId}`,
-  });
+  const background = await recordAppleXctraceWithRetry(
+    args,
+    params.outPath,
+    {
+      device: params.device,
+      appBundleId: params.appBundleId,
+      failureMessage: `Failed to start Apple xctrace ${params.mode} capture for ${params.appBundleId}`,
+    },
+    async (): Promise<AppleXctraceRecordAttempt<ExecBackgroundResult>> => {
+      const recorded = runCmdBackground('xcrun', args, { allowFailure: true });
+      const immediate = await waitForImmediateAppleXctraceExit(recorded.wait);
+      return immediate ? { failure: immediate } : { recorded };
+    },
+  );
   return {
     kind: 'xctrace',
     mode: params.mode,
@@ -160,6 +174,8 @@ export async function stopAppleXctracePerfCapture(
     });
   }
   await assertTracePathHasData(outPath, {
+    message: 'xctrace produced no trace data',
+    hint: 'Keep the Apple device unlocked and connected, keep the app active, then retry perf.',
     appBundleId: capture.appBundleId,
     deviceId: capture.deviceId,
     stdout: result.stdout,
@@ -196,30 +212,20 @@ export async function writeAppleXctracePerfReport(params: {
   const tocPath = path.join(tempDir, 'trace-toc.xml');
   const timeProfilePath = path.join(tempDir, 'time-profile.xml');
   try {
-    const exportArgs = [
-      'xctrace',
-      'export',
-      '--input',
-      params.tracePath,
-      '--toc',
-      '--output',
-      tocPath,
-    ];
-    requireExecSuccess(
-      await runXcrun(exportArgs, {
-        allowFailure: true,
-        timeoutMs: IOS_DEVICE_PERF_EXPORT_TIMEOUT_MS,
-      }),
-      'Failed to export Apple xctrace report metadata',
-      (exportResult) => ({
-        cmd: 'xcrun',
-        args: exportArgs,
-        tracePath: params.tracePath,
-        hint: resolveIosDevicePerfHint(exportResult.stdout, exportResult.stderr),
-      }),
-    );
-    const tocXml = await readHostTextFile(tocPath);
-    const timeProfileXml = await exportAppleTimeProfile(params.tracePath, timeProfilePath);
+    const tocXml = await exportAppleXctraceData({
+      tracePath: params.tracePath,
+      outPath: tocPath,
+      query: 'toc',
+      failureMessage: 'Failed to export Apple xctrace report metadata',
+      failureDetails: { tracePath: params.tracePath },
+    });
+    const timeProfileXml = await exportAppleXctraceData({
+      tracePath: params.tracePath,
+      outPath: timeProfilePath,
+      query: { schema: 'time-profile' },
+      failureMessage: 'Failed to export Apple xctrace Time Profiler samples',
+      failureDetails: { tracePath: params.tracePath },
+    });
     const report = buildAppleXctracePerfReport({
       ...params,
       tocXml,
@@ -240,31 +246,91 @@ export async function writeAppleXctracePerfReport(params: {
   }
 }
 
-async function exportAppleTimeProfile(tracePath: string, outPath: string): Promise<string> {
+export async function recordAppleXctraceTimedTrace(params: {
+  device: DeviceInfo;
+  appBundleId: string;
+  tracePath: string;
+  template: string;
+  timeLimit: string;
+  target: AppleXctraceRecordTarget;
+  requireTraceData?: boolean;
+  failureMessage: string;
+}): Promise<AppleXctraceTimedRecord> {
+  const args = buildAppleXctraceRecordArgs({
+    device: params.device,
+    template: params.template,
+    target: params.target,
+    timeLimit: params.timeLimit,
+    outPath: params.tracePath,
+  });
+  const { result, ...record } = await recordAppleXctraceWithRetry(
+    args,
+    params.tracePath,
+    params,
+    async (): Promise<
+      AppleXctraceRecordAttempt<AppleXctraceTimedRecord & { result: ExecResult }>
+    > => {
+      const startedAt = new Date().toISOString();
+      const result = await runXcrun(args, {
+        allowFailure: true,
+        timeoutMs: IOS_DEVICE_PERF_RECORD_TIMEOUT_MS,
+      });
+      if (result.exitCode !== 0) return { failure: result };
+      return {
+        recorded: {
+          result,
+          startedAt,
+          endedAt: new Date().toISOString(),
+          capturedAtMs: Date.now(),
+        },
+      };
+    },
+  );
+  if (params.requireTraceData) {
+    await assertTracePathHasData(params.tracePath, {
+      message: `${params.failureMessage}: xctrace produced no trace data`,
+      hint: 'Keep the iOS device unlocked and connected by cable, keep the app active, then retry perf.',
+      appBundleId: params.appBundleId,
+      deviceId: params.device.id,
+      stdout: result.stdout,
+      stderr: result.stderr,
+    });
+  }
+  return record;
+}
+
+export async function exportAppleXctraceData(params: {
+  tracePath: string;
+  outPath: string;
+  query: 'toc' | { schema: string };
+  failureMessage: string;
+  failureDetails: Record<string, unknown>;
+}): Promise<string> {
   const exportArgs = [
     'xctrace',
     'export',
     '--input',
-    tracePath,
-    '--xpath',
-    '/trace-toc/run/data/table[@schema="time-profile"]',
+    params.tracePath,
+    ...(params.query === 'toc'
+      ? ['--toc']
+      : ['--xpath', `/trace-toc/run/data/table[@schema="${params.query.schema}"]`]),
     '--output',
-    outPath,
+    params.outPath,
   ];
   requireExecSuccess(
     await runXcrun(exportArgs, {
       allowFailure: true,
       timeoutMs: IOS_DEVICE_PERF_EXPORT_TIMEOUT_MS,
     }),
-    'Failed to export Apple xctrace Time Profiler samples',
+    params.failureMessage,
     (exportResult) => ({
       cmd: 'xcrun',
       args: exportArgs,
-      tracePath,
+      ...params.failureDetails,
       hint: resolveIosDevicePerfHint(exportResult.stdout, exportResult.stderr),
     }),
   );
-  return await readHostTextFile(outPath);
+  return await readHostTextFile(params.outPath);
 }
 
 async function resolveAppleXctracePerfTarget(
@@ -277,6 +343,8 @@ async function resolveAppleXctracePerfTarget(
       hint: 'Android native profiling belongs to the Android perf rollout and is not implemented under Apple xctrace.',
     });
   }
+  const { readAppleProcessSamples, resolveAppleExecutable, resolveIosDevicePerfTarget } =
+    await import('./perf-target.ts');
   if (isIosFamily(device) && device.kind === 'device') {
     const processes = await resolveIosDevicePerfTarget(device, appBundleId);
     return {
@@ -305,7 +373,8 @@ async function resolveAppleXctracePerfTarget(
 function buildAppleXctraceRecordArgs(params: {
   device: DeviceInfo;
   template: string;
-  targetPids: number[];
+  target: AppleXctraceRecordTarget;
+  timeLimit?: string;
   outPath: string;
 }): string[] {
   return [
@@ -314,7 +383,10 @@ function buildAppleXctraceRecordArgs(params: {
     '--template',
     params.template,
     ...(isIosFamily(params.device) ? ['--device', params.device.id] : []),
-    ...params.targetPids.flatMap((pid) => ['--attach', String(pid)]),
+    ...(params.target === 'all-processes'
+      ? ['--all-processes']
+      : params.target.flatMap((pid) => ['--attach', String(pid)])),
+    ...(params.timeLimit ? ['--time-limit', params.timeLimit] : []),
     '--output',
     params.outPath,
     '--quiet',
@@ -322,7 +394,7 @@ function buildAppleXctraceRecordArgs(params: {
   ];
 }
 
-async function startAppleXctraceRecordWithRetry(
+async function recordAppleXctraceWithRetry<T>(
   args: string[],
   tracePath: string,
   context: {
@@ -330,31 +402,51 @@ async function startAppleXctraceRecordWithRetry(
     appBundleId: string;
     failureMessage: string;
   },
-): Promise<ExecBackgroundResult> {
-  let lastImmediateFailure: ExecResult | undefined;
-  for (let attempt = 1; attempt <= IOS_DEVICE_TRACE_RECORD_MAX_ATTEMPTS; attempt += 1) {
-    await prepareAppleTraceRecordRetry(tracePath, attempt, IOS_DEVICE_TRACE_RECORD_RETRY_DELAY_MS);
-    const background = runCmdBackground('xcrun', args, { allowFailure: true });
-    const immediate = await waitForImmediateAppleXctraceExit(background.wait);
-    if (!immediate) return background;
-    lastImmediateFailure = immediate;
-    if (!isRetryableIosDeviceTraceRecordFailure(immediate)) break;
+  attemptRecord: () => Promise<AppleXctraceRecordAttempt<T>>,
+): Promise<T> {
+  for (let attempt = 1; ; attempt += 1) {
+    await prepareAppleTraceRecordRetry(tracePath, attempt);
+    const outcome = await attemptRecord();
+    if ('recorded' in outcome) return outcome.recorded;
+    if (
+      attempt < IOS_DEVICE_TRACE_RECORD_MAX_ATTEMPTS &&
+      isRetryableIosDeviceTraceRecordFailure(outcome.failure)
+    ) {
+      continue;
+    }
+    const { failure } = outcome;
+    throw new AppError(
+      'COMMAND_FAILED',
+      context.failureMessage,
+      execFailureDetails(failure, {
+        cmd: 'xcrun',
+        args,
+        appBundleId: context.appBundleId,
+        deviceId: context.device.id,
+        hint: resolveIosDevicePerfHint(failure.stdout, failure.stderr),
+      }),
+    );
   }
+}
 
-  const failure = lastImmediateFailure ?? { stdout: '', stderr: '', exitCode: 1 };
-  throw new AppError(
-    'COMMAND_FAILED',
-    context.failureMessage,
-    execFailureDetails(failure, {
-      cmd: 'xcrun',
-      args,
-      appBundleId: context.appBundleId,
-      deviceId: context.device.id,
-      hint: resolveIosDevicePerfHint(failure.stdout, failure.stderr),
-    }),
+export function isRetryableIosDeviceTraceRecordFailure(result: {
+  stdout: string;
+  stderr: string;
+}): boolean {
+  const text = `${result.stdout}\n${result.stderr}`.toLowerCase();
+  return (
+    text.includes('_lockkperf') ||
+    text.includes('could not lock kperf') ||
+    text.includes('likely another session just started')
   );
 }
 
+async function prepareAppleTraceRecordRetry(tracePath: string, attempt: number): Promise<void> {
+  if (attempt <= 1) return;
+  await removeHostPath(tracePath).catch(() => {});
+  await new Promise((resolve) => setTimeout(resolve, IOS_DEVICE_TRACE_RECORD_RETRY_DELAY_MS));
+}
+
 async function waitForImmediateAppleXctraceExit(
   wait: Promise<ExecResult>,
 ): Promise<ExecResult | undefined> {
@@ -415,6 +507,8 @@ async function waitForAppleXctraceExit(
 async function assertTracePathHasData(
   tracePath: string,
   context: {
+    message: string;
+    hint: string;
     appBundleId?: string;
     deviceId?: string;
     stdout: string;
@@ -427,13 +521,13 @@ async function assertTracePathHasData(
       ? (await readHostDirectory(tracePath).catch(() => [])).length > 0
       : (stat?.size ?? 0) > 0;
   if (hasTrace) return;
-  throw new AppError('COMMAND_FAILED', 'xctrace produced no trace data', {
+  throw new AppError('COMMAND_FAILED', context.message, {
     tracePath,
     appBundleId: context.appBundleId,
     deviceId: context.deviceId,
     stdout: context.stdout,
     stderr: context.stderr,
-    hint: 'Keep the Apple device unlocked and connected, keep the app active, then retry perf.',
+    hint: context.hint,
   });
 }
 
@@ -468,3 +562,16 @@ function buildAppleXctracePerfReport(params: {
     },
   };
 }
+
+export function resolveIosDevicePerfHint(stdout: string, stderr: string): string {
+  const devicectlHint = resolveIosDevicectlHint(stdout, stderr);
+  if (devicectlHint) return devicectlHint;
+  const text = `${stdout}\n${stderr}`.toLowerCase();
+  if (text.includes('no device matched') || text.includes('failed to find device')) {
+    return IOS_DEVICECTL_DEFAULT_HINT;
+  }
+  if (text.includes('timed out')) {
+    return 'Keep the iOS device unlocked and connected by cable, keep the app active, then retry perf.';
+  }
+  return 'Ensure the iOS device is unlocked, trusted, visible to xctrace, and the target app stays active while perf samples it.';
+}
diff --git a/packages/platform-apple/src/core/perf-xml.ts b/packages/platform-apple/src/core/perf-xml.ts
index 3b27494fe2..a4a8821d68 100644
--- a/packages/platform-apple/src/core/perf-xml.ts
+++ b/packages/platform-apple/src/core/perf-xml.ts
@@ -1,6 +1,6 @@
 import type { XmlNode } from '@agent-device/xml';
 
-export function findFirstXmlNode(
+function findFirstXmlNode(
   nodes: XmlNode[],
   predicate: (node: XmlNode) => boolean,
 ): XmlNode | undefined {
@@ -40,7 +40,7 @@ export function readSchemaColumns(document: XmlNode[], schemaName: string): stri
     .map((column) => readFirstChildText(column, 'mnemonic') ?? '');
 }
 
-export function parseDirectXmlNumber(element: XmlNode | undefined): number | null {
+function parseDirectXmlNumber(element: XmlNode | undefined): number | null {
   if (!element || element.children.some((child) => child.name === 'sentinel')) return null;
   if (!element.text) return null;
   const value = Number(element.text);
@@ -56,6 +56,51 @@ export function resolveXmlNumber(
   return parseDirectXmlNumber(element);
 }
 
+type XmlProcess = { pid?: number; name?: string };
+
+export type XmlReference = {
+  numberValue?: number | null;
+  process?: XmlProcess | null;
+};
+
+export function rememberXmlReferences(
+  elements: XmlNode[],
+  references: Map<string, XmlReference>,
+): void {
+  for (const element of elements) {
+    rememberXmlReferences(element.children, references);
+    if (!element.attributes.id) continue;
+    references.set(element.attributes.id, {
+      numberValue: parseDirectXmlNumber(element),
+      process: readDirectXmlProcess(element),
+    });
+  }
+}
+
+export function resolveXmlProcess(
+  element: XmlNode | undefined,
+  references: Map<string, XmlReference>,
+): XmlProcess | null {
+  if (!element) return null;
+  if (element.attributes.ref) return references.get(element.attributes.ref)?.process ?? null;
+  return readDirectXmlProcess(element);
+}
+
+function readDirectXmlProcess(element: XmlNode | undefined): XmlProcess | null {
+  if (!element || element.children.some((child) => child.name === 'sentinel')) return null;
+  const pidNode = findFirstXmlNode(element.children, (child) => child.name === 'pid');
+  const pid = parseDirectXmlNumber(pidNode);
+  const name = (element.attributes.fmt ?? '')
+    .trim()
+    .replace(/\s+\(\d+\)$/, '')
+    .trim();
+  if (pid === null && name.length === 0) return null;
+  return {
+    pid: pid ?? undefined,
+    name: name.length > 0 ? name : undefined,
+  };
+}
+
 export function indexXmlNodesById(document: XmlNode[]): Map<string, XmlNode> {
   return new Map(
     findAllXmlNodes(document, (node) => Boolean(node.attributes.id)).flatMap((node) => {
diff --git a/packages/platform-apple/src/core/perf.ts b/packages/platform-apple/src/core/perf.ts
index 5b68e16eb8..fb2b7489fa 100644
--- a/packages/platform-apple/src/core/perf.ts
+++ b/packages/platform-apple/src/core/perf.ts
@@ -8,35 +8,28 @@ import {
   type PublicPlatform,
 } from '@agent-device/kernel/device';
 import { AppError } from '@agent-device/kernel/errors';
-import { parseXmlDocumentSync, type XmlNode } from '@agent-device/xml';
-import {
-  execFailureDetails,
-  requireExecSuccess,
-  type ExecResult,
-} from '@agent-device/host-kit/command';
-import { splitNonEmptyTrimmedLines } from '@agent-device/kernel/record';
+import { parseXmlDocumentSync } from '@agent-device/xml';
+import { execFailureDetails, type ExecResult } from '@agent-device/host-kit/command';
 import { uniqueStrings } from '@agent-device/kernel/collections';
 import {
   ensureHostDirectory,
   hostFileStat,
   makeHostTemporaryDirectory,
-  readHostDirectory,
-  readHostTextFile,
   removeHostPath,
 } from '@agent-device/host-kit/host-file';
-import { IOS_DEVICECTL_DEFAULT_HINT, resolveIosDevicectlHint } from './devicectl.ts';
 import type { IosDeviceProcessInfo } from './app-info.ts';
-import { resolveIosPhysicalDeviceControl } from './physical-device-control.ts';
-import { readInfoPlistString } from './plist.ts';
 import { buildSimctlArgsForDevice } from './simctl.ts';
 import { runAppleToolCommand, runXcrun } from './tool-provider.ts';
 import {
   findAllXmlNodes,
-  findFirstXmlNode,
-  parseDirectXmlNumber,
   readSchemaColumns,
+  rememberXmlReferences,
   resolveXmlNumber,
+  resolveXmlProcess,
+  type XmlReference,
 } from './perf-xml.ts';
+import type { AppleProcessSample } from './perf-target.ts';
+import { exportAppleXctraceData, recordAppleXctraceTimedTrace } from './perf-xctrace.ts';
 import {
   APPLE_FRAME_SAMPLE_DESCRIPTION,
   APPLE_FRAME_SAMPLE_METHOD,
@@ -48,15 +41,9 @@ const APPLE_MEMORY_SAMPLE_METHOD = 'ps-process-snapshot';
 const IOS_DEVICE_MEMORY_SAMPLE_METHOD = 'xctrace-activity-monitor';
 const APPLE_MEMGRAPH_SNAPSHOT_METHOD = 'leaks-output-graph';
 
-const APPLE_PERF_TIMEOUT_MS = 15_000;
 const APPLE_MEMORY_SNAPSHOT_TIMEOUT_MS = 120_000;
-// Physical device tracing can take materially longer to initialize than the 1s sample window.
-const IOS_DEVICE_PERF_RECORD_TIMEOUT_MS = 60_000;
-const IOS_DEVICE_PERF_EXPORT_TIMEOUT_MS = 15_000;
 const IOS_DEVICE_PERF_TRACE_DURATION = '1s';
 const IOS_DEVICE_FRAME_TRACE_DURATION = '2s';
-const IOS_DEVICE_TRACE_RECORD_MAX_ATTEMPTS = 3;
-const IOS_DEVICE_TRACE_RECORD_RETRY_DELAY_MS = 1_500;
 
 export type AppleMemoryPerfSample = {
   residentMemoryKb: number;
@@ -86,13 +73,6 @@ export type AppleMemorySnapshotResult =
       support: ReturnType<typeof buildAppleMemorySnapshotSupport>;
     };
 
-export type AppleProcessSample = {
-  pid: number;
-  cpuPercent: number;
-  rssKb: number;
-  command: string;
-};
-
 type IosDevicePerfProcessSample = {
   pid: number;
   processName: string;
@@ -112,16 +92,6 @@ type IosDeviceFramePerfCapture = {
   displayInfoXml?: string;
 };
 
-type IosDeviceTraceRecord = {
-  startedAt: string;
-  endedAt: string;
-  capturedAtMs: number;
-};
-
-type IosDeviceTraceRecordAttempt = IosDeviceTraceRecord & {
-  result: ExecResult;
-};
-
 export async function sampleAppleMemoryPerf(
   device: DeviceInfo,
   appBundleId: string,
@@ -130,6 +100,7 @@ export async function sampleAppleMemoryPerf(
     return await sampleIosDeviceMemoryPerf(device, appBundleId);
   }
 
+  const { readAppleProcessSamples, resolveAppleExecutable } = await import('./perf-target.ts');
   const executable = await resolveAppleExecutable(device, appBundleId);
   const processes = await readAppleProcessSamples(device, executable);
   if (processes.length === 0) {
@@ -315,6 +286,7 @@ export async function sampleAppleFramePerf(
     );
   }
 
+  const { resolveIosDevicePerfTarget } = await import('./perf-target.ts');
   const processes = await resolveIosDevicePerfTarget(device, appBundleId);
   const capture = await captureIosDeviceFramePerf(device, appBundleId, processes);
   return parseAppleFramePerfSample({
@@ -427,246 +399,43 @@ async function captureIosDeviceFramePerf(
 ): Promise<IosDeviceFramePerfCapture> {
   const tempDir = await makeHostTemporaryDirectory('agent-device-ios-frame-perf-');
   const tracePath = path.join(tempDir, 'animation-hitches.trace');
-  const hitchesPath = path.join(tempDir, 'hitches.xml');
-  const frameLifetimesPath = path.join(tempDir, 'frame-lifetimes.xml');
-  const displayInfoPath = path.join(tempDir, 'display-info.xml');
   try {
-    const record = await recordIosDeviceTrace({
+    const record = await recordAppleXctraceTimedTrace({
       device,
       appBundleId,
       tracePath,
       template: 'Animation Hitches',
-      duration: IOS_DEVICE_FRAME_TRACE_DURATION,
-      targetPids: processes.map((processInfo) => processInfo.pid),
-      validateTraceOutput: true,
+      timeLimit: IOS_DEVICE_FRAME_TRACE_DURATION,
+      target: processes.map((processInfo) => processInfo.pid),
+      requireTraceData: true,
       failureMessage: `Failed to record iOS frame-health sample for ${appBundleId}`,
     });
-    await exportIosDevicePerfTable(device, appBundleId, tracePath, 'hitches', hitchesPath);
-    await exportIosDevicePerfTable(
-      device,
-      appBundleId,
-      tracePath,
-      'hitches-frame-lifetimes',
-      frameLifetimesPath,
-    );
-    const hasDisplayInfo = await exportOptionalIosDevicePerfTable(
-      device,
-      appBundleId,
-      tracePath,
-      'device-display-info',
-      displayInfoPath,
-    );
+    const context = { device, appBundleId, tracePath, tempDir };
     return {
       windowStartedAt: record.startedAt,
       windowEndedAt: record.endedAt,
-      hitchesXml: await readHostTextFile(hitchesPath),
-      frameLifetimesXml: await readHostTextFile(frameLifetimesPath),
-      displayInfoXml: hasDisplayInfo ? await readHostTextFile(displayInfoPath) : undefined,
+      hitchesXml: await exportIosDevicePerfTable(context, 'hitches'),
+      frameLifetimesXml: await exportIosDevicePerfTable(context, 'hitches-frame-lifetimes'),
+      displayInfoXml: await exportIosDevicePerfTable(context, 'device-display-info').catch(
+        () => undefined,
+      ),
     };
   } finally {
     await removeHostPath(tempDir).catch(() => {});
   }
 }
 
-async function recordIosDeviceTrace(params: {
-  device: DeviceInfo;
-  appBundleId: string;
-  tracePath: string;
-  template: 'Activity Monitor' | 'Animation Hitches';
-  duration: string;
-  targetPids?: number[];
-  allProcesses?: boolean;
-  validateTraceOutput?: boolean;
-  failureMessage: string;
-}): Promise<IosDeviceTraceRecord> {
-  const { device, appBundleId, tracePath, template, duration } = params;
-  const targetArgs = params.allProcesses
-    ? ['--all-processes']
-    : (params.targetPids ?? []).flatMap((pid) => ['--attach', String(pid)]);
-  const recordArgs = [
-    'xctrace',
-    'record',
-    '--template',
-    template,
-    '--device',
-    device.id,
-    ...targetArgs,
-    '--time-limit',
-    duration,
-    '--output',
-    tracePath,
-    '--quiet',
-    '--no-prompt',
-  ];
-  const record = await runIosDeviceTraceRecord(recordArgs, params.tracePath);
-  if (record.result.exitCode === 0) {
-    if (params.validateTraceOutput) {
-      await assertUsableTraceOutput(params, record.result.stdout, record.result.stderr);
-    }
-    return {
-      startedAt: record.startedAt,
-      endedAt: record.endedAt,
-      capturedAtMs: record.capturedAtMs,
-    };
-  }
-  throw new AppError(
-    'COMMAND_FAILED',
-    params.failureMessage,
-    execFailureDetails(record.result, {
-      cmd: 'xcrun',
-      args: recordArgs,
-      appBundleId,
-      deviceId: device.id,
-      hint: resolveIosDevicePerfHint(record.result.stdout, record.result.stderr),
-    }),
-  );
-}
-
-async function runIosDeviceTraceRecord(
-  recordArgs: string[],
-  tracePath: string,
-): Promise<IosDeviceTraceRecordAttempt> {
-  let lastAttempt: IosDeviceTraceRecordAttempt | undefined;
-  for (let attempt = 1; attempt <= IOS_DEVICE_TRACE_RECORD_MAX_ATTEMPTS; attempt += 1) {
-    await prepareAppleTraceRecordRetry(tracePath, attempt, IOS_DEVICE_TRACE_RECORD_RETRY_DELAY_MS);
-    const startedAt = new Date().toISOString();
-    const result = await runXcrun(recordArgs, {
-      allowFailure: true,
-      timeoutMs: IOS_DEVICE_PERF_RECORD_TIMEOUT_MS,
-    });
-    lastAttempt = {
-      result,
-      startedAt,
-      endedAt: new Date().toISOString(),
-      capturedAtMs: Date.now(),
-    };
-    if (result.exitCode === 0 || !isRetryableIosDeviceTraceRecordFailure(result)) {
-      return lastAttempt;
-    }
-  }
-  return lastAttempt as IosDeviceTraceRecordAttempt;
-}
-
-export function isRetryableIosDeviceTraceRecordFailure(result: {
-  stdout: string;
-  stderr: string;
-}): boolean {
-  const text = `${result.stdout}\n${result.stderr}`.toLowerCase();
-  return (
-    text.includes('_lockkperf') ||
-    text.includes('could not lock kperf') ||
-    text.includes('likely another session just started')
-  );
-}
-
-export async function prepareAppleTraceRecordRetry(
-  tracePath: string,
-  attempt: number,
-  retryDelayMs: number,
-): Promise<void> {
-  if (attempt <= 1) return;
-  await removeHostPath(tracePath).catch(() => {});
-  await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
-}
-
-async function assertUsableTraceOutput(
-  params: {
-    device: DeviceInfo;
-    appBundleId: string;
-    tracePath: string;
-    failureMessage: string;
-  },
-  stdout: string,
-  stderr: string,
-): Promise<void> {
-  const stat = await hostFileStat(params.tracePath).catch(() => null);
-  const hasTrace =
-    stat?.isDirectory() === true
-      ? (await readHostDirectory(params.tracePath).catch(() => [])).length > 0
-      : (stat?.size ?? 0) > 0;
-  if (hasTrace) return;
-  throw new AppError('COMMAND_FAILED', `${params.failureMessage}: xctrace produced no trace data`, {
-    tracePath: params.tracePath,
-    appBundleId: params.appBundleId,
-    deviceId: params.device.id,
-    stdout,
-    stderr,
-    hint: 'Keep the iOS device unlocked and connected by cable, keep the app active, then retry perf.',
-  });
-}
-
 async function exportIosDevicePerfTable(
-  device: DeviceInfo,
-  appBundleId: string,
-  tracePath: string,
-  schema: string,
-  outputPath: string,
-): Promise<void> {
-  const exportArgs = [
-    'xctrace',
-    'export',
-    '--input',
-    tracePath,
-    '--xpath',
-    `/trace-toc/run/data/table[@schema="${schema}"]`,
-    '--output',
-    outputPath,
-  ];
-  requireExecSuccess(
-    await runXcrun(exportArgs, {
-      allowFailure: true,
-      timeoutMs: IOS_DEVICE_PERF_EXPORT_TIMEOUT_MS,
-    }),
-    `Failed to export iOS device ${schema} data`,
-    (exportResult) => ({
-      cmd: 'xcrun',
-      args: exportArgs,
-      appBundleId,
-      deviceId: device.id,
-      hint: resolveIosDevicePerfHint(exportResult.stdout, exportResult.stderr),
-    }),
-  );
-}
-
-async function exportOptionalIosDevicePerfTable(
-  device: DeviceInfo,
-  appBundleId: string,
-  tracePath: string,
+  context: { device: DeviceInfo; appBundleId: string; tracePath: string; tempDir: string },
   schema: string,
-  outputPath: string,
-): Promise<boolean> {
-  try {
-    await exportIosDevicePerfTable(device, appBundleId, tracePath, schema, outputPath);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-export function parseApplePsOutput(stdout: string): AppleProcessSample[] {
-  const rows: AppleProcessSample[] = [];
-  for (const line of splitNonEmptyTrimmedLines(stdout)) {
-    const match = line.match(/^(\d+)\s+([0-9]+(?:\.[0-9]+)?)\s+(\d+)\s+(.+)$/);
-    if (!match) continue;
-    const [pidText, cpuText, rssText, commandText] = match.slice(1);
-    if (
-      pidText === undefined ||
-      cpuText === undefined ||
-      rssText === undefined ||
-      commandText === undefined
-    ) {
-      continue;
-    }
-    const pid = Number(pidText);
-    const cpuPercent = Number(cpuText);
-    const rssKb = Number(rssText);
-    const command = commandText.trim();
-    if (!Number.isFinite(pid) || !Number.isFinite(cpuPercent) || !Number.isFinite(rssKb)) {
-      continue;
-    }
-    rows.push({ pid, cpuPercent, rssKb, command });
-  }
-  return rows;
+): Promise<string> {
+  return await exportAppleXctraceData({
+    tracePath: context.tracePath,
+    outPath: path.join(context.tempDir, `${schema}.xml`),
+    query: { schema },
+    failureMessage: `Failed to export iOS device ${schema} data`,
+    failureDetails: { appBundleId: context.appBundleId, deviceId: context.device.id },
+  });
 }
 
 async function parseIosDevicePerfTable(xml: string): Promise<IosDevicePerfProcessSample[]> {
@@ -690,36 +459,14 @@ async function parseIosDevicePerfTable(xml: string): Promise<IosDevicePerfProces
 
   const rows = findAllXmlNodes(document, (node) => node.name === 'row');
   const samples: IosDevicePerfProcessSample[] = [];
-  const references = new Map<
-    string,
-    {
-      numberValue?: number | null;
-      processName?: string | null;
-    }
-  >();
+  const references = new Map<string, XmlReference>();
   for (const row of rows) {
     const elements = row.children;
     if (elements.length === 0) continue;
-    for (const element of elements) {
-      const nestedPid = findFirstXmlNode(
-        element.children,
-        (child) => child.name === 'pid' && typeof child.attributes.id === 'string',
-      );
-      if (nestedPid?.attributes.id) {
-        const pidValue = Number(nestedPid.text);
-        references.set(nestedPid.attributes.id, {
-          numberValue: Number.isFinite(pidValue) ? pidValue : null,
-        });
-      }
-      if (!element.attributes.id) continue;
-      references.set(element.attributes.id, {
-        numberValue: parseDirectXmlNumber(element),
-        processName: readDirectProcessNameFromXml(element),
-      });
-    }
+    rememberXmlReferences(elements, references);
 
     const pid = resolveXmlNumber(elements[pidIndex], references);
-    const processName = resolveProcessName(elements[processIndex], references);
+    const processName = resolveXmlProcess(elements[processIndex], references)?.name;
     if (pid === null || !Number.isFinite(pid) || !processName) continue;
     samples.push({
       pid,
@@ -730,36 +477,11 @@ async function parseIosDevicePerfTable(xml: string): Promise<IosDevicePerfProces
   return samples;
 }
 
-export async function resolveAppleExecutable(
-  device: DeviceInfo,
-  appBundleId: string,
-): Promise<{ executableName: string; executablePath?: string }> {
-  const appPath = isMacOs(device)
-    ? await resolveMacOsBundlePath(appBundleId)
-    : await resolveIosSimulatorAppContainer(device, appBundleId);
-  const infoPlistPath = isMacOs(device)
-    ? path.join(appPath, 'Contents', 'Info.plist')
-    : path.join(appPath, 'Info.plist');
-  const executableName = await readInfoPlistString(infoPlistPath, 'CFBundleExecutable');
-  if (!executableName) {
-    throw new AppError('COMMAND_FAILED', `Failed to resolve executable for ${appBundleId}`, {
-      appBundleId,
-      appPath,
-    });
-  }
-
-  return {
-    executableName,
-    executablePath: isMacOs(device)
-      ? path.join(appPath, 'Contents', 'MacOS', executableName)
-      : path.join(appPath, executableName),
-  };
-}
-
 async function sampleIosDeviceMemoryPerf(
   device: DeviceInfo,
   appBundleId: string,
 ): Promise<AppleMemoryPerfSample> {
+  const { resolveIosDevicePerfTarget } = await import('./perf-target.ts');
   const processes = await resolveIosDevicePerfTarget(device, appBundleId);
   const capture = await captureIosDevicePerfTable(device, appBundleId);
   const snapshot = summarizeIosDeviceMemorySnapshot(
@@ -784,53 +506,28 @@ async function sampleIosDeviceMemoryPerf(
   });
 }
 
-export async function resolveIosDevicePerfTarget(
-  device: DeviceInfo,
-  appBundleId: string,
-): Promise<IosDeviceProcessInfo[]> {
-  const { appBundleUrl, processes } = await resolveIosPhysicalDeviceControl(
-    device,
-  ).resolveAppProcesses(device, appBundleId);
-  const appBundlePath = fileURLToPath(appBundleUrl);
-  if (processes.length === 0) {
-    throw new AppError('COMMAND_FAILED', `No running process found for ${appBundleId}`, {
-      appBundleId,
-      deviceId: device.id,
-      appBundlePath,
-      hint: 'Run open <app> for this session again to ensure the iOS app is active, then retry perf.',
-    });
-  }
-
-  return processes;
-}
-
 async function captureIosDevicePerfTable(
   device: DeviceInfo,
   appBundleId: string,
 ): Promise<IosDevicePerfCapture> {
   const tempDir = await makeHostTemporaryDirectory('agent-device-ios-perf-');
   const tracePath = path.join(tempDir, 'sample.trace');
-  const exportPath = path.join(tempDir, 'activity-monitor-process-live.xml');
   try {
-    const record = await recordIosDeviceTrace({
+    const record = await recordAppleXctraceTimedTrace({
       device,
       appBundleId,
       tracePath,
       template: 'Activity Monitor',
-      duration: IOS_DEVICE_PERF_TRACE_DURATION,
-      allProcesses: true,
+      timeLimit: IOS_DEVICE_PERF_TRACE_DURATION,
+      target: 'all-processes',
       failureMessage: `Failed to record iOS device Activity Monitor sample for ${appBundleId}`,
     });
-    await exportIosDevicePerfTable(
-      device,
-      appBundleId,
-      tracePath,
-      'activity-monitor-process-live',
-      exportPath,
-    );
     return {
       capturedAtMs: record.capturedAtMs,
-      xml: await readHostTextFile(exportPath),
+      xml: await exportIosDevicePerfTable(
+        { device, appBundleId, tracePath, tempDir },
+        'activity-monitor-process-live',
+      ),
     };
   } finally {
     await removeHostPath(tempDir).catch(() => {});
@@ -891,85 +588,6 @@ function summarizeIosDeviceMemorySnapshot(
   };
 }
 
-async function resolveMacOsBundlePath(appBundleId: string): Promise<string> {
-  const query = `kMDItemCFBundleIdentifier == "${appBundleId.replaceAll('"', String.raw`\"`)}"`;
-  const result = requireExecSuccess(
-    await runAppleToolCommand('mdfind', [query], {
-      allowFailure: true,
-      timeoutMs: APPLE_PERF_TIMEOUT_MS,
-    }),
-    `Failed to resolve macOS app bundle for ${appBundleId}`,
-    { appBundleId },
-  );
-
-  const bundlePath = result.stdout
-    .split('\n')
-    .map((entry) => entry.trim())
-    .find((entry) => entry.endsWith('.app'));
-  if (!bundlePath) {
-    throw new AppError('APP_NOT_INSTALLED', `No macOS app found for ${appBundleId}`, {
-      appBundleId,
-    });
-  }
-  return bundlePath;
-}
-
-async function resolveIosSimulatorAppContainer(
-  device: DeviceInfo,
-  appBundleId: string,
-): Promise<string> {
-  const args = buildSimctlArgsForDevice(device, [
-    'get_app_container',
-    device.id,
-    appBundleId,
-    'app',
-  ]);
-  const result = requireExecSuccess(
-    await runXcrun(args, {
-      allowFailure: true,
-      timeoutMs: APPLE_PERF_TIMEOUT_MS,
-    }),
-    `Failed to resolve iOS simulator app container for ${appBundleId}`,
-    {
-      appBundleId,
-      hint: 'Ensure the iOS simulator app is installed and booted, then retry perf.',
-    },
-  );
-  const appPath = result.stdout.trim();
-  if (appPath.length === 0) {
-    throw new AppError(
-      'APP_NOT_INSTALLED',
-      `No iOS simulator app container found for ${appBundleId}`,
-      {
-        appBundleId,
-      },
-    );
-  }
-  return appPath;
-}
-
-export async function readAppleProcessSamples(
-  device: DeviceInfo,
-  executable: { executableName: string; executablePath?: string },
-): Promise<AppleProcessSample[]> {
-  const args = isMacOs(device)
-    ? ['-axo', 'pid=,%cpu=,rss=,command=']
-    : buildSimctlArgsForDevice(device, [
-        'spawn',
-        device.id,
-        'ps',
-        '-axo',
-        'pid=,%cpu=,rss=,command=',
-      ]);
-  const result = isMacOs(device)
-    ? await runAppleToolCommand('ps', args, { timeoutMs: APPLE_PERF_TIMEOUT_MS })
-    : await runAppleSimulatorProcessCommand(args);
-  const { matchesAppleExecutableProcess } = await import('./perf-process-identity.ts');
-  return parseApplePsOutput(result.stdout).filter((processInfo) =>
-    matchesAppleExecutableProcess(processInfo.command, executable),
-  );
-}
-
 function readProcessCommandToken(command: string): string {
   const [token = ''] = command.trim().split(/\s+/, 1);
   return token;
@@ -980,6 +598,7 @@ async function resolveAppleMemorySnapshotProcess(
   appBundleId: string,
   executable: { executableName: string; executablePath?: string },
 ): Promise<AppleProcessSample> {
+  const { readAppleProcessSamples } = await import('./perf-target.ts');
   const processes = await readAppleProcessSamples(device, executable);
   const processInfo = processes.sort((left, right) => right.rssKb - left.rssKb)[0];
   if (processInfo) return processInfo;
@@ -999,6 +618,7 @@ async function resolveAppleMemorySnapshotTarget(
   | Extract<AppleMemorySnapshotResult, { available: false }>
 > {
   try {
+    const { resolveAppleExecutable } = await import('./perf-target.ts');
     const executable = await resolveAppleExecutable(device, appBundleId);
     return {
       available: true,
@@ -1049,17 +669,6 @@ function resolveAppleMemorySnapshotHint(
   return 'Keep the app process running and retry perf memory snapshot with --debug if the failure persists.';
 }
 
-async function runAppleSimulatorProcessCommand(args: string[]): Promise<ExecResult> {
-  const result = await runXcrun(args, {
-    allowFailure: true,
-    timeoutMs: APPLE_PERF_TIMEOUT_MS,
-  });
-  if (result.exitCode === 0) return result;
-  return await runAppleToolCommand('ps', ['-axo', 'pid=,%cpu=,rss=,command='], {
-    timeoutMs: APPLE_PERF_TIMEOUT_MS,
-  });
-}
-
 function buildAppleMemoryPerfSample(args: {
   residentMemoryKb: number;
   measuredAt: string;
@@ -1074,36 +683,6 @@ function buildAppleMemoryPerfSample(args: {
   };
 }
 
-function readDirectProcessNameFromXml(element: XmlNode | undefined): string | null {
-  const fmt = element?.attributes.fmt?.trim() ?? '';
-  if (!fmt) return null;
-  return fmt.replace(/\s+\(\d+\)$/, '').trim();
-}
-
-function resolveProcessName(
-  element: XmlNode | undefined,
-  references: Map<string, { processName?: string | null }>,
-): string | null {
-  if (!element) return null;
-  if (element.attributes.ref) {
-    return references.get(element.attributes.ref)?.processName ?? null;
-  }
-  return readDirectProcessNameFromXml(element);
-}
-
-export function resolveIosDevicePerfHint(stdout: string, stderr: string): string {
-  const devicectlHint = resolveIosDevicectlHint(stdout, stderr);
-  if (devicectlHint) return devicectlHint;
-  const text = `${stdout}\n${stderr}`.toLowerCase();
-  if (text.includes('no device matched') || text.includes('failed to find device')) {
-    return IOS_DEVICECTL_DEFAULT_HINT;
-  }
-  if (text.includes('timed out')) {
-    return 'Keep the iOS device unlocked and connected by cable, keep the app active, then retry perf.';
-  }
-  return 'Ensure the iOS device is unlocked, trusted, visible to xctrace, and the target app stays active while perf samples it.';
-}
-
 function maxNullableNumber(left: number | null, right: number | null): number | null {
   if (left === null) return right;
   if (right === null) return left;
diff --git a/packages/platform-apple/src/core/physical-device-coredevice.ts b/packages/platform-apple/src/core/physical-device-coredevice.ts
index bc00fa9dc4..ec983782cb 100644
--- a/packages/platform-apple/src/core/physical-device-coredevice.ts
+++ b/packages/platform-apple/src/core/physical-device-coredevice.ts
@@ -1,25 +1,18 @@
-import path from 'node:path';
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import { AppError } from '@agent-device/kernel/errors';
-import { execFailureDetails } from '@agent-device/host-kit/command';
-import {
-  hostTemporaryDirectory,
-  readHostTextFile,
-  removeHostPath,
-} from '@agent-device/host-kit/host-file';
-import { hostProcessId } from '@agent-device/host-kit/process';
+import { execFailureDetails, type ExecResult } from '@agent-device/host-kit/command';
 import {
   IOS_DEVICE_DEVELOPER_DISK_IMAGE_HINT,
   IOS_DEVICE_DEVELOPER_MODE_OFF_HINT,
   IOS_DEVICECTL_DEFAULT_HINT,
   resolveIosDevicectlHint,
   runIosDevicectl,
+  runIosDevicectlJsonRequest,
 } from './devicectl.ts';
 import {
   IOS_DEVICE_READY_COMMAND_TIMEOUT_BUFFER_MS,
   IOS_DEVICE_READY_TIMEOUT_MS,
 } from './physical-device-constants.ts';
-import { runXcrun } from './tool-provider.ts';
 
 const IOS_RUNNER_DEVICE_INFO_TIMEOUT_MS = 10_000;
 
@@ -50,18 +43,17 @@ export async function ensureCoreDeviceReady(
       IOS_DEVICE_READY_COMMAND_TIMEOUT_BUFFER_MS,
       signal,
     );
-    const { result, parsed } = probe;
-    if (result.exitCode === 0) {
-      if (!parsed.parsed) {
-        throw new AppError('COMMAND_FAILED', 'iOS device readiness probe failed', {
-          kind: 'probe_inconclusive',
-          deviceId: device.id,
-          stdout: result.stdout,
-          stderr: result.stderr,
-          hint: 'CoreDevice returned success but readiness JSON output was missing or invalid. Retry; if it persists restart Xcode and the iOS device.',
-        });
-      }
-      const tunnelState = parsed.tunnelState?.toLowerCase();
+    if (probe.status === 'unreadable') {
+      throw new AppError('COMMAND_FAILED', 'iOS device readiness probe failed', {
+        kind: 'probe_inconclusive',
+        deviceId: device.id,
+        stdout: probe.result.stdout,
+        stderr: probe.result.stderr,
+        hint: 'CoreDevice returned success but readiness JSON output was missing or invalid. Retry; if it persists restart Xcode and the iOS device.',
+      });
+    }
+    if (probe.status === 'reported') {
+      const tunnelState = probe.details.tunnelState?.toLowerCase();
       if (tunnelState === 'connecting') {
         throw new AppError('COMMAND_FAILED', 'iOS device is not ready for automation', {
           kind: 'not_ready',
@@ -75,11 +67,11 @@ export async function ensureCoreDeviceReady(
     throw new AppError(
       'COMMAND_FAILED',
       'iOS device is not ready for automation',
-      execFailureDetails(result, {
+      execFailureDetails(probe.result, {
         kind: 'not_ready',
         deviceId: device.id,
-        tunnelState: parsed.tunnelState,
-        hint: resolveIosReadyHint(result.stdout, result.stderr),
+        tunnelState: probe.details.tunnelState,
+        hint: resolveIosReadyHint(probe.result.stdout, probe.result.stderr),
       }),
     );
   } catch (error) {
@@ -159,66 +151,54 @@ async function readIosDeviceDetails(
   const timeoutMs = Math.max(1, Math.min(IOS_RUNNER_DEVICE_INFO_TIMEOUT_MS, timeoutBudgetMs));
   try {
     const probe = await runCoreDeviceDetails(device.id, timeoutMs, 0, signal);
-    if (probe.result.exitCode !== 0 || !probe.parsed.parsed) return null;
-    if (probe.parsed.outcome && probe.parsed.outcome !== 'success') return null;
-    const { parsed } = probe;
-    const { parsed: _parsed, ...details } = parsed;
-    return details;
+    if (probe.status !== 'reported') return null;
+    if (probe.details.outcome && probe.details.outcome !== 'success') return null;
+    return probe.details;
   } catch {
     return null;
   }
 }
 
+/**
+ * `reported` when the command succeeded with a readable payload, `unreadable` when it succeeded
+ * without one, and `failed` when it exited non-zero, carrying whatever its failure payload reported.
+ */
+type CoreDeviceDetailsProbe =
+  | { status: 'reported'; details: IosDeviceDetails }
+  | { status: 'unreadable'; result: ExecResult }
+  | { status: 'failed'; result: ExecResult; details: IosDeviceDetails };
+
 async function runCoreDeviceDetails(
   deviceId: string,
   timeoutMs: number,
   commandTimeoutBufferMs = 0,
   signal?: AbortSignal,
-): Promise<{
-  result: Awaited<ReturnType<typeof runXcrun>>;
-  parsed: { parsed: boolean } & IosDeviceDetails;
-}> {
-  const jsonPath = path.join(
-    hostTemporaryDirectory(),
-    `agent-device-coredevice-info-${hostProcessId()}-${Date.now()}-${Math.random().toString(36).slice(2)}.json`,
-  );
+): Promise<CoreDeviceDetailsProbe> {
   const timeoutSeconds = Math.max(1, Math.ceil(timeoutMs / 1000));
-  try {
-    const result = await runXcrun(
-      [
-        'devicectl',
-        'device',
-        'info',
-        'details',
-        '--device',
-        deviceId,
-        '--json-output',
-        jsonPath,
-        '--timeout',
-        String(timeoutSeconds),
-      ],
-      {
-        allowFailure: true,
-        signal,
-        timeoutMs: timeoutMs + commandTimeoutBufferMs,
-      },
-    );
-    return { result, parsed: await readCoreDeviceDetails(jsonPath) };
-  } finally {
-    await removeHostPath(jsonPath).catch(() => {});
-  }
-}
-
-async function readCoreDeviceDetails(
-  jsonPath: string,
-): Promise<{ parsed: boolean } & IosDeviceDetails> {
-  try {
-    const payload = JSON.parse(await readHostTextFile(jsonPath)) as unknown;
-    const details = parseIosDeviceDetailsPayload(payload);
-    return { parsed: true, ...details };
-  } catch {
-    return { parsed: false };
+  const outcome = await runIosDevicectlJsonRequest({
+    jsonPrefix: 'agent-device-coredevice-info',
+    args: [
+      'devicectl',
+      'device',
+      'info',
+      'details',
+      '--device',
+      deviceId,
+      '--timeout',
+      String(timeoutSeconds),
+    ],
+    signal,
+    timeoutMs: timeoutMs + commandTimeoutBufferMs,
+  });
+  if (outcome.ok) {
+    return { status: 'reported', details: parseIosDeviceDetailsPayload(outcome.payload) };
   }
+  if (outcome.reason === 'unreadable-json') return { status: 'unreadable', result: outcome.result };
+  return {
+    status: 'failed',
+    result: outcome.result,
+    details: parseIosDeviceDetailsPayload(outcome.payload),
+  };
 }
 
 /**
diff --git a/packages/platform-apple/src/perf-facade.ts b/packages/platform-apple/src/perf-facade.ts
index a3afca34b1..5f29dc1adb 100644
--- a/packages/platform-apple/src/perf-facade.ts
+++ b/packages/platform-apple/src/perf-facade.ts
@@ -3,16 +3,13 @@ export {
   buildAppleMemorySamplingMetadata,
   buildAppleMemorySnapshotSupport,
   captureAppleMemorySnapshot,
-  isRetryableIosDeviceTraceRecordFailure,
-  readAppleProcessSamples,
-  resolveAppleExecutable,
-  resolveIosDevicePerfTarget,
-  resolveIosDevicePerfHint,
   sampleAppleFramePerf,
   sampleAppleMemoryPerf,
 } from './core/perf.ts';
 export {
   cleanupAppleXctracePerfCapture,
+  isRetryableIosDeviceTraceRecordFailure,
+  resolveIosDevicePerfHint,
   startAppleXctracePerfCapture,
   stopAppleXctracePerfCapture,
   writeAppleXctracePerfReport,

From eabe1192330c10fb3e0d4003f9b709328c8e97ca Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 24 Sep 2026 09:05:52 +0200
Subject: [PATCH 075/132] fix(ios-runner): keep snapshot-plan target state on
 main and bound the query sweep by its slice (#2836)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(ios): take snapshot target identity on main and hop plan state writes

The capture plan runs on the command queue but read currentBundleId,
currentAppProcessIdentifier and the penalty warm-up exemption, and wrote
runnerAccessibilityHealth and invalidated the cached target directly.

Snapshot preparation now takes a SnapshotCaptureTarget on main (app,
bundle id, pid, consumed warm-up exemption) and the plan, the modal
probe penalty, the XCTest penalty recorder and the private AX tier read
only that copy. Health writes and the fail-closed invalidation go through
applyMainOwnedSnapshotState, the abandoned-work-guarded main hop that
invalidateCachedTargetAfterSnapshotFailure now also uses.

Fixes #2781

* fix(ios): bound the query sweep by its tier slice deadline

A non-interactive query sweep used Date.distantFuture as its own
deadline, so only the up-to-20 s plan deadline bounded it while the
caller abandoned the tier after its 1 s slice. XCTest queries cannot be
cancelled, so the sweep kept the main thread busy and later commands got
RUNNER_BUSY.

The caller now derives one slice deadline (querySweepSliceDeadline) for
both its wait and the sweep, for interactive and non-interactive
requests alike. Neither the element queries nor the per-element reads
start with less than flatInteractiveQueryBudget left before that
deadline (querySweepCanStartQuery).

Fixes #2783

* fix(ios): spend the penalty warm-up exemption only in a capture plan that runs

Taking the snapshot target on main consumed the exemption during command
preparation, so a snapshot answered by the blocking system-modal probe, or
an abandoned preparation that ran late, spent it without running a plan.
The exemption now lives in a lock-owned type that lifecycle code arms on
main and runSnapshotCapturePlan consumes at its start.

* test(ios): pin the non-interactive query sweep to its tier slice through the plan

Swizzles XCUIElementQuery.allElementsBoundByIndex with a slow query and runs
a non-interactive [.querySweep] plan with a 20 s plan deadline. The sweep
must not be abandoned, and no query may start after the plan answers, so
passing the plan deadline to the sweep in either loop turns it red.

* test(ios): pin the query-sweep tier timeout and the tap routing identity to main

Two regressions #2781 still leaves open, both red on this head:

A query sweep that stops at its own slice deadline is a tier timeout, but
the plan classified its payload by node count, so a partial sweep that beat
the sparse threshold armed no XCTest-channel penalty and no later capture
of the same screen was deferred.

The coordinate tap's system-modal routing probe armed its penalty with
currentBundleId read on the command queue, while main owned that state and
could still be clearing or rebinding it.

* fix(ios): count a query sweep that ends on its slice deadline as a tier timeout

The sweep tier stopped starting queries at its slice deadline, but the plan
classified only what it collected. sparsePayloadReason accepts anything above
the sparse node threshold, so a partial flat sweep became a `recovered`
capture: no XCTest-channel penalty was armed, private AX never ran, and every
later capture of that screen paid for the full sweep again.

`runFlatInteractiveQueries` now returns a typed `SnapshotTierOutcome`, the
sweep tier carries it into the attempt, and the plan rejects a
`.deadlineExhausted` tier through `snapshotTierRejectionReason` — keeping its
payload only as the fallback, arming the penalty through the existing tier
timeout reason, and letting the next backend answer.

* fix(ios): take the system-modal probe's target identity on main

The coordinate tap resolved its system-modal routing on the command queue and
armed an abandoned probe's penalty with `currentBundleId` read there, while
`applyMainOwnedSnapshotState` and the lifecycle code write that identity
through `DispatchQueue.main.async`. A tap could penalize a target main was
still clearing or rebinding.

The probe now takes a `SnapshotProbePenaltyTarget`: a capture hands over the
identity it already took on main, and the tap route hands over nothing and lets
the probe's own main-side block capture the identity main holds once its work
starts. No off-main path reads target identity any more.

* test(ios): place this PR's runner tests in main's split UnitTests files

main (#2854, #2855) moved the runner's inline unit tests into UnitTests/ and
split RunnerTests+CommandExecution.swift along command families. Rebase conflicts
dropped this PR's edits from the inline blocks the rebase kept on main; relocate
them into the file main now owns for each family:

- RunnerTests+SnapshotTests.swift: the query-sweep slice-deadline and
  fail-closed-invalidation tests, and the bounded-modal-probe helper now takes a
  SnapshotCaptureTarget.
- RunnerTests+SnapshotCapturePlanTests.swift: the tier-timeout rejection pair and
  the private-AX depth helper now builds a SnapshotCaptureTarget.
- RunnerTests+SnapshotTimingTests.swift: the deadline-exhausted tier penalty test.
---
 .github/workflows/ios.yml                     |   4 +
 .../RunnerTests+AXSnapshotFallback.swift      |  28 +-
 .../RunnerTests+CommandDispatch.swift         |   7 +-
 .../RunnerTests+Lifecycle.swift               |   4 +-
 .../RunnerTests+Snapshot.swift                | 106 +++++---
 .../RunnerTests+SnapshotAcquisition.swift     |  33 ++-
 .../RunnerTests+SnapshotCapturePlan.swift     | 111 +++++---
 .../RunnerTests+SnapshotCaptureTarget.swift   | 106 ++++++++
 .../RunnerTests+SnapshotExecution.swift       |  47 ++--
 .../RunnerTests+SnapshotTiming.swift          |  49 +++-
 .../RunnerTests.swift                         |   4 +-
 ...nnerTests+AXRecoveryConformanceTests.swift |   6 +-
 .../RunnerTests+AXSnapshotFallbackTests.swift |  13 +-
 .../RunnerTests+CommandDispatchTests.swift    |  77 +++++-
 .../RunnerTests+LifecycleCacheTests.swift     |  14 +-
 ...ts+SnapshotCapturePlanOccupancyTests.swift | 241 +++++++++++++++++-
 ...RunnerTests+SnapshotCapturePlanTests.swift |  33 ++-
 ...nnerTests+SnapshotCaptureTargetTests.swift | 104 ++++++++
 .../UnitTests/RunnerTests+SnapshotTests.swift | 164 +++++++++++-
 .../RunnerTests+SnapshotTimingTests.swift     |  45 ++++
 20 files changed, 1048 insertions(+), 148 deletions(-)
 create mode 100644 apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotCaptureTarget.swift
 create mode 100644 apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotCaptureTargetTests.swift

diff --git a/.github/workflows/ios.yml b/.github/workflows/ios.yml
index 4bc494a504..00dc9df934 100644
--- a/.github/workflows/ios.yml
+++ b/.github/workflows/ios.yml
@@ -256,6 +256,10 @@ jobs:
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testActionNamesAreCappedPerElementAndReported \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testHungCustomActionReadIsContainedAndRecovers \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testAbandonedTreeCaptureSkipsQuerySweepAndHonorsWarmupExemption \
+            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testNonInteractiveQuerySweepStopsAtTheSliceItsCallerWaitsFor \
+            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testQuerySweepThatEndsOnItsSliceDeadlinePenalizesChannelAndReachesPrivateAX \
+            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testCoordinateTapRoutingPenalizesTheIdentityMainSettledOnWhileTheWriteWasPending \
+            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testBlockingModalSnapshotLeavesWarmupExemptionForTheFirstCapturePlan \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testPrivateAXPinnedRegularDepthReachesAcquisitionAndPresentation 2>&1 | tee /tmp/agent-device-runner-regressions.log
           node --input-type=module -e '
             import { readFileSync } from "node:fs";
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+AXSnapshotFallback.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+AXSnapshotFallback.swift
index ed79919b17..13244aeaf2 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+AXSnapshotFallback.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+AXSnapshotFallback.swift
@@ -110,14 +110,16 @@ extension RunnerTests {
   /// remembered depth deliberately does NOT refresh the TTL, so expiry re-probes the full
   /// requested depth once per window instead of capping this screen class forever.
   func recordPrivateAXAcceptedDepth(
+    bundleId: String?,
+    processIdentifier: Int?,
     exactDepthRequested: Bool,
     effectiveDepth: Int,
     attemptDepths: [Int]
   ) {
     guard !exactDepthRequested, effectiveDepth != attemptDepths.first else { return }
     rememberPrivateAXAcceptedDepth(
-      bundleId: currentBundleId,
-      processIdentifier: currentAppProcessIdentifier,
+      bundleId: bundleId,
+      processIdentifier: processIdentifier,
       depth: effectiveDepth
     )
   }
@@ -160,11 +162,12 @@ extension RunnerTests {
   }
 
   func privateAXSnapshotAcquisition(
-    app: XCUIApplication,
+    target: SnapshotCaptureTarget,
     hint: CaptureHint,
     deadline: Date = .distantFuture
   ) -> SnapshotAcquisition? {
     #if os(iOS) && targetEnvironment(simulator)
+      let app = target.app
       let requestedDepth = hint.rawTraversalDepth ?? 64
       // An explicit --depth request is honored as asked: no accepted-depth
       // memory, no frontier extension past it.
@@ -173,8 +176,8 @@ extension RunnerTests {
         exactDepthRequested
         ? nil
         : rememberedPrivateAXAcceptedDepth(
-          bundleId: currentBundleId,
-          processIdentifier: currentAppProcessIdentifier
+          bundleId: target.bundleId,
+          processIdentifier: target.processIdentifier
         )
       let attemptDepths = Self.privateAXAttemptDepths(
         requestedDepth: requestedDepth,
@@ -202,6 +205,8 @@ extension RunnerTests {
         return nil
       }
       recordPrivateAXAcceptedDepth(
+        bundleId: target.bundleId,
+        processIdentifier: target.processIdentifier,
         exactDepthRequested: exactDepthRequested,
         effectiveDepth: effectiveDepth,
         attemptDepths: attemptDepths
@@ -212,7 +217,11 @@ extension RunnerTests {
       }
 
       let rootFrame = privateAXRect(root["frame"])
-      let geometry = privateAXSnapshotGeometry(app: app, rootFrame: rootFrame)
+      let geometry = privateAXSnapshotGeometry(
+        app: app,
+        bundleId: target.bundleId,
+        rootFrame: rootFrame
+      )
       let viewport = geometry.viewport
       let nodes = privateAXAcquisition(
         rawRoot: root,
@@ -262,8 +271,8 @@ extension RunnerTests {
   /// grinding on this screen class. Under penalty it reliably burns its full timeout and
   /// falls back anyway (~1s added to every private AX capture on the Bluesky bench feed),
   /// so honor the penalty here the same way capture plans do.
-  func shouldReadPrivateAXViewportViaXCTest() -> Bool {
-    !hasAbandonedMainThreadWork() && !isSnapshotXCTestChannelPenalized(bundleId: currentBundleId)
+  func shouldReadPrivateAXViewportViaXCTest(bundleId: String?) -> Bool {
+    !hasAbandonedMainThreadWork() && !isSnapshotXCTestChannelPenalized(bundleId: bundleId)
   }
 
   /// The geometry this tier may anchor a rotation on. The bridge's own root frame is one more
@@ -272,10 +281,11 @@ extension RunnerTests {
   /// consumers already treat as geometry they cannot measure (#2612).
   private func privateAXSnapshotGeometry(
     app: XCUIApplication,
+    bundleId: String?,
     rootFrame: CGRect
   ) -> (viewport: CGRect, interfaceOrientation: Int) {
     let fallback = rootFrame.isEmpty ? CGRect.infinite : rootFrame
-    guard shouldReadPrivateAXViewportViaXCTest() else {
+    guard shouldReadPrivateAXViewportViaXCTest(bundleId: bundleId) else {
       return (fallback, RunnerInterfaceOrientation.unknown)
     }
     do {
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandDispatch.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandDispatch.swift
index a791984dc1..16b2dfccd2 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandDispatch.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandDispatch.swift
@@ -579,8 +579,13 @@ extension RunnerTests {
     }
     #endif
     let probeDeadline = Date().addingTimeInterval(systemModalProbeBudget)
+    // Routing runs on the command queue, so this hands the probe a target rather than a bundle id it
+    // read across the main boundary: the penalty an abandoned probe arms carries the identity main
+    // holds once the probe starts, not one whose write was still queued behind the block that
+    // occupied main (#2781).
     return boundedBlockingSystemAlertSnapshot(
-      deadline: probeDeadline
+      deadline: probeDeadline,
+      penaltyTarget: .mainOwnedTarget
     ) != nil
 #else
     return false
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Lifecycle.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Lifecycle.swift
index 0314cbab9b..8d378a59e5 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Lifecycle.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Lifecycle.swift
@@ -202,7 +202,7 @@ extension RunnerTests {
   /// markers. Every site that binds, rebinds, or drops the target runs this.
   func resetTargetBoundState() {
     clearRememberedTextEntryTap()
-    snapshotXCTestPenaltyWarmupExemptionPending = false
+    snapshotXCTestPenaltyWarmupExemption.isPending = false
     lastLoggedFastAppGuardLine = nil
     lastLoggedGesturePolicyLines.removeAll()
   }
@@ -247,7 +247,7 @@ extension RunnerTests {
     resetTargetBoundState()
     clearSnapshotXCTestChannelPenalty(reason: "target_process_changed")
     clearPrivateAXAcceptedDepth(reason: "target_process_changed")
-    snapshotXCTestPenaltyWarmupExemptionPending = true
+    snapshotXCTestPenaltyWarmupExemption.isPending = true
     beginFirstInteractionStabilization()
   }
 
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Snapshot.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Snapshot.swift
index 14fe138387..3d469bf868 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Snapshot.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Snapshot.swift
@@ -132,6 +132,20 @@ extension RunnerTests {
   ]
 
   static let flatInteractiveFallbackBudget: TimeInterval = 1.0
+  /// The least slice time a sweep query may start with. XCTest cannot cancel a query, so one that
+  /// starts later outlives the slice its caller waits for and holds the main thread (#2783).
+  static let flatInteractiveQueryBudget: TimeInterval = 0.1
+
+  /// The deadline the query-sweep tier's caller waits for: one slice, clamped to the plan deadline.
+  /// Interactive and non-interactive requests share it, since the caller discards a later result.
+  static func querySweepSliceDeadline(startedAt: Date, planDeadline: Date) -> Date {
+    min(startedAt.addingTimeInterval(flatInteractiveFallbackBudget), planDeadline)
+  }
+
+  /// Whether a sweep query started at `now` can still finish before the slice `deadline`.
+  static func querySweepCanStartQuery(deadline: Date, now: Date) -> Bool {
+    deadline.timeIntervalSince(now) >= flatInteractiveQueryBudget
+  }
 
   /// What one capture may spend reading the keyboard band before it gives up on the fact and lets the
   /// tap guard fall back to the tree rule. The scroll path pays this query per gesture and stays well
@@ -145,14 +159,17 @@ extension RunnerTests {
   // `boundedBlockingSystemAlertSnapshot`'s probe closure (see `systemModalProbeOverrideForTesting`
   // in RunnerTests.swift), so reverting this entry point to bypass the bounded probe fails the
   // regression test.
-  func snapshotFast(app: XCUIApplication, options: PresentationOptions) throws -> DataPayload {
+  func snapshotFast(target: SnapshotCaptureTarget, options: PresentationOptions) throws -> DataPayload {
     let deadline = Date().addingTimeInterval(Self.snapshotPlanBudget)
-    if let blocking = boundedBlockingSystemAlertSnapshot(deadline: deadline) {
+    if let blocking = boundedBlockingSystemAlertSnapshot(
+      deadline: deadline,
+      penaltyTarget: .prepared(bundleId: target.bundleId)
+    ) {
       return blocking
     }
     return try runSnapshotCapturePlan(
       Self.regularVisiblePlan,
-      app: app,
+      target: target,
       options: options,
       terminal: .sparseWithFatalOnAXFailure,
       deadline: deadline
@@ -267,14 +284,17 @@ extension RunnerTests {
   }
 
   // See `snapshotFast` above: the single production entry point, no unit-test overload.
-  func snapshotRaw(app: XCUIApplication, options: PresentationOptions) throws -> DataPayload {
+  func snapshotRaw(target: SnapshotCaptureTarget, options: PresentationOptions) throws -> DataPayload {
     let deadline = Date().addingTimeInterval(Self.snapshotPlanBudget)
-    if let blocking = boundedBlockingSystemAlertSnapshot(deadline: deadline) {
+    if let blocking = boundedBlockingSystemAlertSnapshot(
+      deadline: deadline,
+      penaltyTarget: .prepared(bundleId: target.bundleId)
+    ) {
       return blocking
     }
     return try runSnapshotCapturePlan(
       Self.rawDiagnosticPlan,
-      app: app,
+      target: target,
       options: options,
       terminal: .throwOnAXFailure,
       deadline: deadline
@@ -283,8 +303,15 @@ extension RunnerTests {
 
   /// Runs the pre-plan SpringBoard system-modal probe as a bounded capture tier sharing the plan
   /// deadline, so a slow alert enumeration cannot bypass the snapshot timeout and stall (#1244).
-  func boundedBlockingSystemAlertSnapshot(deadline: Date) -> DataPayload? {
-    boundedBlockingSystemAlertSnapshotBody(deadline: deadline) { probeDeadline in
+  /// An abandoned probe penalizes the XCTest channel for `penaltyTarget`.
+  func boundedBlockingSystemAlertSnapshot(
+    deadline: Date,
+    penaltyTarget: SnapshotProbePenaltyTarget
+  ) -> DataPayload? {
+    boundedBlockingSystemAlertSnapshotBody(
+      deadline: deadline,
+      penaltyTarget: penaltyTarget
+    ) { probeDeadline in
       #if AGENT_DEVICE_RUNNER_UNIT_TESTS
       if let override = self.systemModalProbeOverrideForTesting {
         return override(probeDeadline)
@@ -301,6 +328,7 @@ extension RunnerTests {
   /// production runs and what the unit tests exercise.
   private func boundedBlockingSystemAlertSnapshotBody(
     deadline: Date,
+    penaltyTarget: SnapshotProbePenaltyTarget,
     probe: @escaping (Date) -> DataPayload?
   ) -> DataPayload? {
     #if os(macOS)
@@ -316,6 +344,7 @@ extension RunnerTests {
     }
     let probeDeadline = Date().addingTimeInterval(slice)
     let startedAt = Date()
+    let penaltyIdentity = SnapshotProbePenaltyIdentity(penaltyTarget)
     do {
       return try runMainThreadWork(
         "system_modal_probe",
@@ -329,12 +358,13 @@ extension RunnerTests {
         },
         onAbandoned: {
           self.penalizeSnapshotXCTestChannel(
-            bundleId: self.currentBundleId,
+            bundleId: penaltyIdentity.penalizedBundleId,
             reason: "system_modal_probe_timeout"
           )
         }
       ) {
-        probe(probeDeadline)
+        penaltyIdentity.captureFromMain(bundleId: self.currentBundleId)
+        return probe(probeDeadline)
       }
     } catch {
       NSLog(
@@ -413,37 +443,34 @@ extension RunnerTests {
   func querySweepSnapshotAcquisition(
     app: XCUIApplication,
     hint: CaptureHint,
-    planDeadline: Date = .distantFuture
-  ) -> SnapshotAcquisition {
+    sliceDeadline deadline: Date
+  ) -> (acquisition: SnapshotAcquisition, outcome: SnapshotTierOutcome) {
     var nodes: [RawAXNode] = [
       interactiveRootNode(rect: .zero)
     ]
     if hint.rawTraversalDepth == 0 || hint.regularPresentedDepth == 0 {
-      return SnapshotAcquisition(
-        hint: hint,
-        nodes: nodes,
-        truncated: false,
-        effectiveDepth: nil,
-        viewport: .infinite,
-        interfaceOrientation: RunnerInterfaceOrientation.unknown
+      return (
+        SnapshotAcquisition(
+          hint: hint,
+          nodes: nodes,
+          truncated: false,
+          effectiveDepth: nil,
+          viewport: .infinite,
+          interfaceOrientation: RunnerInterfaceOrientation.unknown
+        ),
+        .completed
       )
     }
 
-    // Bounded by both its own sweep budget and the umbrella capture-plan deadline, so a
-    // chained recovery tier can never push the plan past the main-thread watchdog (#1105).
-    let sweepDeadline = hint.interactiveOnly
-      ? Date().addingTimeInterval(Self.flatInteractiveFallbackBudget)
-      : Date.distantFuture
-    let deadline = min(sweepDeadline, planDeadline)
     let viewport = safeSnapshotViewport(app: app)
     var seen = Set<String>()
     var candidates: [RawAXNode] = []
     let flatElements = flatInteractiveElements(app: app, deadline: deadline)
-    var truncated = flatElements.truncated
+    var outcome = flatElements.outcome
     for element in flatElements.elements {
-      if Date() >= deadline {
+      if !Self.querySweepCanStartQuery(deadline: deadline, now: Date()) {
         NSLog("AGENT_DEVICE_RUNNER_SNAPSHOT_FLAT_FALLBACK_DEADLINE")
-        truncated = true
+        outcome = .deadlineExhausted
         break
       }
       guard let node = flatSnapshotNode(element: element, index: 0, parentIndex: 0) else {
@@ -491,20 +518,25 @@ extension RunnerTests {
         )
       )
     }
-    return SnapshotAcquisition(
-      hint: hint,
-      nodes: nodes,
-      truncated: truncated,
-      effectiveDepth: nil,
-      viewport: viewport,
-      interfaceOrientation: RunnerInterfaceOrientation.unknown
+    return (
+      SnapshotAcquisition(
+        hint: hint,
+        nodes: nodes,
+        truncated: outcome == .deadlineExhausted,
+        effectiveDepth: nil,
+        viewport: viewport,
+        interfaceOrientation: RunnerInterfaceOrientation.unknown
+      ),
+      outcome
     )
   }
 
   func snapshotAccessibilityUnavailable(failure: SnapshotCaptureFailure) -> DataPayload {
     NSLog("AGENT_DEVICE_RUNNER_SNAPSHOT_AX_UNAVAILABLE=%@", failure.message)
-    runnerAccessibilityHealth = .unavailable
-    invalidateCachedTarget(reason: Self.axSnapshotUnavailableReason)
+    applyMainOwnedSnapshotState("ax_unavailable_invalidation") {
+      self.runnerAccessibilityHealth = .unavailable
+      self.invalidateCachedTarget(reason: Self.axSnapshotUnavailableReason)
+    }
     // This is a planned terminal result, so it carries the structured verdict like every other
     // planned snapshot — downstream sparse handling keys off the verdict, not node shapes.
     return sparseTruncatedSnapshotPayload(
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotAcquisition.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotAcquisition.swift
index 2c1d834786..26572f56fa 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotAcquisition.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotAcquisition.swift
@@ -464,7 +464,7 @@ extension RunnerTests {
   func flatInteractiveElements(
     app: XCUIApplication,
     deadline: Date
-  ) -> (elements: [XCUIElement], truncated: Bool) {
+  ) -> (elements: [XCUIElement], outcome: SnapshotTierOutcome) {
     let queries: [XCUIElementQuery] = [
       app.buttons,
       app.links,
@@ -487,23 +487,36 @@ extension RunnerTests {
       app.images
     ]
 
-    var elements: [XCUIElement] = []
-    var truncated = false
+    return Self.runFlatInteractiveQueries(queries, deadline: deadline) { query in
+      self.snapshotElementsQuery {
+        query.allElementsBoundByIndex
+      }
+    }
+  }
+
+  /// Runs sweep queries in order until one reports AX unavailable, or until the next one could not
+  /// finish before `deadline` (`querySweepCanStartQuery`). A sweep stopped by the deadline reports
+  /// `.deadlineExhausted` rather than a truncation flag: what it collected is a partial tree, and
+  /// only the caller that owns the tier decides whether that counts as an answer (#2781).
+  static func runFlatInteractiveQueries<Query, Element>(
+    _ queries: [Query],
+    deadline: Date,
+    now: () -> Date = { Date() },
+    run: (Query) -> (elements: [Element], axUnavailable: Bool)
+  ) -> (elements: [Element], outcome: SnapshotTierOutcome) {
+    var elements: [Element] = []
     for query in queries {
-      if Date() >= deadline {
+      if !querySweepCanStartQuery(deadline: deadline, now: now()) {
         NSLog("AGENT_DEVICE_RUNNER_SNAPSHOT_FLAT_FALLBACK_DEADLINE")
-        truncated = true
-        break
-      }
-      let result = snapshotElementsQuery {
-        query.allElementsBoundByIndex
+        return (elements, .deadlineExhausted)
       }
+      let result = run(query)
       elements.append(contentsOf: result.elements)
       if result.axUnavailable {
         break
       }
     }
-    return (elements, truncated)
+    return (elements, .completed)
   }
 
   func snapshotElementsQuery(
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotCapturePlan.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotCapturePlan.swift
index b6e9946957..e7f3898652 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotCapturePlan.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotCapturePlan.swift
@@ -37,6 +37,16 @@ enum SnapshotXCTestChannelPlanState: Equatable {
   case boundedXCTestProbe
 }
 
+/// How one tier's bounded work ended. `deadlineExhausted` is a tier timeout: the tier stopped
+/// starting work it could not finish inside its own slice, so what it returns is a partial result
+/// it never completed collecting. The plan keeps that result only as the fallback and lets the next
+/// backend answer; a node count cannot tell the two apart, because a short sweep still collects
+/// more than the sparse threshold (#2781).
+enum SnapshotTierOutcome: Equatable {
+  case completed
+  case deadlineExhausted
+}
+
 struct EffectiveSnapshotCapturePlan {
   let plan: [SnapshotBackendKind]
   let xCTestChannelState: SnapshotXCTestChannelPlanState
@@ -142,12 +152,6 @@ extension RunnerTests {
     return penalized == bundleId
   }
 
-  func consumeSnapshotXCTestPenaltyWarmupExemption() -> Bool {
-    let pending = snapshotXCTestPenaltyWarmupExemptionPending
-    snapshotXCTestPenaltyWarmupExemptionPending = false
-    return pending
-  }
-
   /// The pre-seeded first-failure a penalized plan stamps into its verdict. The deferred case
   /// uses the dedicated 'deferred' code: the breaker pre-selected the backend, nothing new
   /// degraded on this capture, and the daemon keys warning suppression and the settle budget
@@ -260,7 +264,7 @@ extension RunnerTests {
 
   func runSnapshotCapturePlan(
     _ plan: [SnapshotBackendKind],
-    app: XCUIApplication,
+    target: SnapshotCaptureTarget,
     options: PresentationOptions,
     terminal: SnapshotCaptureTerminalPolicy,
     deadline: Date? = nil
@@ -270,7 +274,7 @@ extension RunnerTests {
     var axFailure: SnapshotCaptureFailure?
     // A caller may share the pre-plan system-modal probe's deadline; otherwise own the full budget (#1244).
     let deadline = deadline ?? Date().addingTimeInterval(Self.snapshotPlanBudget)
-    let suppressXCTestPenalty = consumeSnapshotXCTestPenaltyWarmupExemption()
+    let suppressXCTestPenalty = snapshotXCTestPenaltyWarmupExemption.consume()
 
     // Reorder is iOS-only because hostile screens can make XCTest tree/query work grind while
     // the app remains visually responsive. Simulators can avoid that channel through private AX;
@@ -281,7 +285,7 @@ extension RunnerTests {
     var xCTestChannelPenalized = false
     var xCTestChannelPenalizedByBreaker = false
 #if os(iOS)
-    xCTestChannelPenalizedByBreaker = isSnapshotXCTestChannelPenalized(bundleId: currentBundleId)
+    xCTestChannelPenalizedByBreaker = isSnapshotXCTestChannelPenalized(bundleId: target.bundleId)
     xCTestChannelPenalized = Self.snapshotXCTestChannelTreatedAsPenalized(
       penalized: xCTestChannelPenalizedByBreaker,
       preferredBackend: options.preferredBackend
@@ -305,9 +309,9 @@ extension RunnerTests {
     case .normal:
       break
     case .deferredToIndependentBackend:
-      NSLog("AGENT_DEVICE_RUNNER_SNAPSHOT_XCTEST_CHANNEL_DEFERRED bundle=%@", currentBundleId ?? "")
+      NSLog("AGENT_DEVICE_RUNNER_SNAPSHOT_XCTEST_CHANNEL_DEFERRED bundle=%@", target.bundleId ?? "")
     case .boundedXCTestProbe:
-      NSLog("AGENT_DEVICE_RUNNER_SNAPSHOT_XCTEST_CHANNEL_PROBE_BOUNDED bundle=%@", currentBundleId ?? "")
+      NSLog("AGENT_DEVICE_RUNNER_SNAPSHOT_XCTEST_CHANNEL_PROBE_BOUNDED bundle=%@", target.bundleId ?? "")
     }
 
     for kind in effectivePlan {
@@ -332,7 +336,7 @@ extension RunnerTests {
       }
       let attempt = try captureWithBackend(
         kind,
-        app: app,
+        target: target,
         options: options,
         deadline: deadline,
         treeCaptureSliceBudgetOverride: effective.treeCaptureSliceBudgetOverride
@@ -340,6 +344,7 @@ extension RunnerTests {
       recordXCTestSnapshotBackendAttemptIfNeeded(
         kind,
         attempt: attempt,
+        bundleId: target.bundleId,
         penaltySuppressed: suppressXCTestPenalty
       )
       if case let .failed(failure, phase: _) = attempt.outcome {
@@ -356,8 +361,19 @@ extension RunnerTests {
       }
       guard case let .captured(capture) = attempt.outcome else { continue }
 
-      if let sparseReason = Self.sparsePayloadReason(capture.qualityPayload ?? capture.payload) {
-        if firstFailure == nil { firstFailure = sparseReason }
+      if attempt.tierOutcome == .deadlineExhausted {
+        NSLog(
+          "AGENT_DEVICE_RUNNER_SNAPSHOT_TIER_DEADLINE_EXHAUSTED backend=%@ nodes=%d",
+          kind.rawValue,
+          Self.payloadNodeCount(capture.payload)
+        )
+      }
+      if let rejection = Self.snapshotTierRejectionReason(
+        outcome: attempt.tierOutcome,
+        kind: kind,
+        payload: capture.qualityPayload ?? capture.payload
+      ) {
+        if firstFailure == nil { firstFailure = rejection }
         if Self.payloadNodeCount(capture.payload) > Self.payloadNodeCount(best?.capture.payload) {
           best = (kind, capture)
         }
@@ -412,19 +428,21 @@ extension RunnerTests {
 
   private func captureWithBackend(
     _ kind: SnapshotBackendKind,
-    app: XCUIApplication,
+    target: SnapshotCaptureTarget,
     options: PresentationOptions,
     deadline: Date,
     treeCaptureSliceBudgetOverride: TimeInterval?
   ) throws -> SnapshotBackendAttempt {
+    let app = target.app
     let hint = SnapshotPresentation.captureHint(for: options)
     var timer = SnapshotPhaseTimer()
     let acquisition: SnapshotAcquisition?
+    let tierOutcome: SnapshotTierOutcome
     // The band is read inside the tree tier's own bounded work, so it has to be lifted out of the
     // acquisition phase and carried to the stamping step, where the payload is assembled (#2660).
     var keyboardBand: RunnerKeyboardBandFact?
     do {
-      acquisition = try timer.measure(.acquisition) {
+      let measured = try timer.measure(.acquisition) { () -> (SnapshotAcquisition?, SnapshotTierOutcome) in
         switch kind {
         case .recursiveTree:
           guard
@@ -435,10 +453,10 @@ extension RunnerTests {
               treeCaptureSliceBudgetOverride: treeCaptureSliceBudgetOverride
             )
           else {
-            return nil
+            return (nil, .completed)
           }
           keyboardBand = context.keyboardBand
-          return try self.runMainThreadWork(
+          let tree = try self.runMainThreadWork(
             "tree_processing",
             timeout: min(self.treeCaptureSliceBudget, max(0.5, deadline.timeIntervalSinceNow)),
             timeoutError: self.snapshotMainThreadTimeoutError("processing tree snapshot")
@@ -447,26 +465,34 @@ extension RunnerTests {
               ? try self.rawTreeSnapshotAcquisition(context: context, hint: hint)
               : try self.recursiveTreeSnapshotAcquisition(context: context, hint: hint)
           }
+          return (tree, .completed)
         case .querySweep:
-          return try self.runMainThreadWork(
+          let sliceDeadline = Self.querySweepSliceDeadline(startedAt: Date(), planDeadline: deadline)
+          let sweep = try self.runMainThreadWork(
             "query_sweep",
-            timeout: min(Self.flatInteractiveFallbackBudget, max(0.1, deadline.timeIntervalSinceNow)),
+            timeout: max(0.1, sliceDeadline.timeIntervalSinceNow),
             timeoutError: self.snapshotMainThreadTimeoutError("running query-sweep snapshot")
           ) {
             self.querySweepSnapshotAcquisition(
               app: app,
               hint: hint,
-              planDeadline: deadline
+              sliceDeadline: sliceDeadline
             )
           }
+          return (sweep.acquisition, sweep.outcome)
         case .privateAX:
-          return self.privateAXSnapshotAcquisition(
-            app: app,
-            hint: hint,
-            deadline: deadline
+          return (
+            self.privateAXSnapshotAcquisition(
+              target: target,
+              hint: hint,
+              deadline: deadline
+            ),
+            .completed
           )
         }
       }
+      acquisition = measured.0
+      tierOutcome = measured.1
     } catch let failure as SnapshotCaptureFailure {
       return SnapshotBackendAttempt(
         outcome: .failed(failure, phase: .acquisition),
@@ -476,7 +502,8 @@ extension RunnerTests {
     guard let acquisition else {
       return SnapshotBackendAttempt(
         outcome: .noCapture,
-        timing: timer.timing
+        timing: timer.timing,
+        tierOutcome: tierOutcome
       )
     }
 
@@ -511,12 +538,14 @@ extension RunnerTests {
     } catch let failure as SnapshotPresentationFailure {
       return SnapshotBackendAttempt(
         outcome: .failed(Self.snapshotCaptureFailure(for: failure), phase: .presentation),
-        timing: timer.timing
+        timing: timer.timing,
+        tierOutcome: tierOutcome
       )
     } catch let failure as SnapshotCaptureFailure {
       return SnapshotBackendAttempt(
         outcome: .failed(failure, phase: .presentation),
-        timing: timer.timing
+        timing: timer.timing,
+        tierOutcome: tierOutcome
       )
     }
 
@@ -525,7 +554,8 @@ extension RunnerTests {
     capture.keyboardBand = keyboardBand?.payload
     return SnapshotBackendAttempt(
       outcome: .captured(capture),
-      timing: timer.timing
+      timing: timer.timing,
+      tierOutcome: tierOutcome
     )
   }
 
@@ -546,6 +576,24 @@ extension RunnerTests {
 
   // MARK: Quality classifier (the single source of "is this snapshot degraded")
 
+  /// Why a captured tier may not end the plan, or nil when it may. A tier that stopped starting work
+  /// at its own deadline is rejected as a timeout whatever it collected: keeping its payload as the
+  /// fallback is right, accepting it is not, and a node count cannot tell a finished capture from a
+  /// sweep the slice cut short (#2781).
+  static func snapshotTierRejectionReason(
+    outcome: SnapshotTierOutcome,
+    kind: SnapshotBackendKind,
+    payload: DataPayload
+  ) -> (reason: String, code: String)? {
+    if outcome == .deadlineExhausted {
+      return (
+        "the \(kind.rawValue) backend spent its capture slice with the collection unfinished",
+        "budget"
+      )
+    }
+    return sparsePayloadReason(payload)
+  }
+
   /// Returns a degradation reason + machine code when the payload is too degraded to accept.
   static func sparsePayloadReason(_ payload: DataPayload) -> (reason: String, code: String)? {
     guard let nodes = payload.nodes, !nodes.isEmpty else {
@@ -635,7 +683,10 @@ extension RunnerTests {
     state: String,
     reason: (reason: String, code: String)?
   ) -> DataPayload {
-    runnerAccessibilityHealth = reason?.code == "ax-rejected" ? .unavailable : .healthy
+    let health: RunnerAccessibilityHealth = reason?.code == "ax-rejected" ? .unavailable : .healthy
+    applyMainOwnedSnapshotState("accessibility_health") {
+      self.runnerAccessibilityHealth = health
+    }
     let payload = capture.payload
     let quality = SnapshotQuality(
       state: state,
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotCaptureTarget.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotCaptureTarget.swift
new file mode 100644
index 0000000000..446db190f2
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotCaptureTarget.swift
@@ -0,0 +1,106 @@
+import XCTest
+
+// MARK: - Snapshot capture target (#2781)
+//
+// Target identity (`currentApp`, `currentBundleId`, `currentAppProcessIdentifier`) and
+// `runnerAccessibilityHealth` are owned by main-thread lifecycle code. A capture plan runs on the
+// command queue, so it reads the identity from a `SnapshotCaptureTarget` taken on main while the
+// command is prepared, and writes health or invalidates the target only through
+// `applyMainOwnedSnapshotState`.
+
+/// The target one capture plan reads, taken once on the main thread.
+struct SnapshotCaptureTarget {
+  let app: XCUIApplication
+  let bundleId: String?
+  let processIdentifier: Int?
+}
+
+/// What snapshot command preparation hands the off-main capture.
+enum SnapshotCommandPreparation {
+  case response(Response)
+  case capture(SnapshotCaptureTarget, systemSurface: SystemSurfaceHost?)
+}
+
+/// The target a bounded XCTest probe arms its abandonment penalty with.
+///
+/// The hook that arms the penalty fires on the command queue the moment the probe's slice is spent,
+/// while the probe's own work block may still be running on main. `currentBundleId` belongs to main,
+/// so it is never read across that boundary: a caller that already took the identity on main hands it
+/// over, and a caller that is on the command queue lets the probe's main-side block capture the
+/// identity main holds once the work actually starts (#2781).
+enum SnapshotProbePenaltyTarget: Equatable {
+  /// Identity a capture took on main when it prepared its target.
+  case prepared(bundleId: String?)
+  /// Read `currentBundleId` inside the probe's main-side block.
+  case mainOwnedTarget
+}
+
+/// One probe's penalty identity: written by the probe's main-side block, read by the command queue's
+/// abandonment hook through this lock.
+final class SnapshotProbePenaltyIdentity {
+  private let lock = NSLock()
+  private var bundleId: String?
+  private let readsMainOwnedTarget: Bool
+
+  init(_ target: SnapshotProbePenaltyTarget) {
+    readsMainOwnedTarget = target == .mainOwnedTarget
+    if case .prepared(let bundleId) = target {
+      self.bundleId = bundleId
+    }
+  }
+
+  /// Called on the main thread inside the probe's work block, before it enumerates anything, so the
+  /// identity is the one main had settled on rather than one a queued write is about to replace.
+  func captureFromMain(bundleId: String?) {
+    guard readsMainOwnedTarget else { return }
+    lock.lock()
+    self.bundleId = bundleId
+    lock.unlock()
+  }
+
+  var penalizedBundleId: String? {
+    lock.lock()
+    defer { lock.unlock() }
+    return bundleId
+  }
+}
+
+extension RunnerTests {
+  /// Main thread only: reads the lifecycle-owned target identity.
+  func takeSnapshotCaptureTarget(app: XCUIApplication) -> SnapshotCaptureTarget {
+    SnapshotCaptureTarget(
+      app: app,
+      bundleId: currentBundleId,
+      processIdentifier: currentAppProcessIdentifier
+    )
+  }
+
+  /// Runs `write` against main-owned runner state for a capture that may be on the command queue.
+  /// Abandoned work ahead of the hop cannot be cancelled, so behind it the write queues without
+  /// waiting: the capture answers now and the next command still observes the write.
+  func applyMainOwnedSnapshotState(_ operation: String, _ write: @escaping () -> Void) {
+    if Thread.isMainThread {
+      write()
+      return
+    }
+    guard !hasAbandonedMainThreadWork() else {
+      NSLog("AGENT_DEVICE_RUNNER_SNAPSHOT_STATE_DEFERRED_XCTEST_OCCUPIED operation=%@", operation)
+      DispatchQueue.main.async(execute: write)
+      return
+    }
+    do {
+      try runMainThreadWork(
+        operation,
+        timeout: 1,
+        timeoutError: mainThreadExecutionTimeoutError,
+        write
+      )
+    } catch {
+      NSLog(
+        "AGENT_DEVICE_RUNNER_SNAPSHOT_STATE_FAILED operation=%@ error=%@",
+        operation,
+        String(describing: error)
+      )
+    }
+  }
+}
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotExecution.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotExecution.swift
index d17d79eeba..ec0b2c8faa 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotExecution.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotExecution.swift
@@ -9,21 +9,29 @@ extension RunnerTests {
   }
 
   private func executeSnapshotDispatchedOnce(command: Command) throws -> Response {
-    let preparation = try runMainThreadWork(
+    let preparation: SnapshotCommandPreparation = try runMainThreadWork(
       "command_preparation",
       timeout: mainThreadExecutionTimeout,
       timeoutError: mainThreadExecutionTimeoutError
-    ) {
-      try self.prepareActiveCommandContextSafely(command: command, routeToSpringboard: false)
+    ) { () -> SnapshotCommandPreparation in
+      switch try self.prepareActiveCommandContextSafely(command: command, routeToSpringboard: false) {
+      case .response(let response):
+        return .response(response)
+      case .context(let context):
+        return .capture(
+          self.takeSnapshotCaptureTarget(app: context.app),
+          systemSurface: context.systemSurface
+        )
+      }
     }
     switch preparation {
     case .response(let response):
       return response
-    case .context(let context):
+    case .capture(let target, let systemSurface):
       return try executeSnapshotPrepared(
         command: command,
-        activeApp: context.app,
-        systemSurface: context.systemSurface
+        target: target,
+        systemSurface: systemSurface
       )
     }
   }
@@ -76,16 +84,16 @@ extension RunnerTests {
 
   private func executeSnapshotPrepared(
     command: Command,
-    activeApp: XCUIApplication,
+    target: SnapshotCaptureTarget,
     systemSurface: SystemSurfaceHost?
   ) throws -> Response {
     let options = Self.presentationOptions(from: command)
     do {
       var payload: DataPayload
       if options.raw {
-        payload = try snapshotRaw(app: activeApp, options: options)
+        payload = try snapshotRaw(target: target, options: options)
       } else {
-        payload = try snapshotFast(app: activeApp, options: options)
+        payload = try snapshotFast(target: target, options: options)
       }
       if let systemSurface {
         payload.systemSurface = SystemSurfaceProvenancePayload(
@@ -127,25 +135,8 @@ extension RunnerTests {
   }
 
   func invalidateCachedTargetAfterSnapshotFailure() {
-    // Abandoned work ahead of this hop cannot be cancelled: queue the drop behind it without
-    // waiting, so the failed capture answers now and the next command still finds the target gone.
-    guard !hasAbandonedMainThreadWork() else {
-      NSLog("AGENT_DEVICE_RUNNER_SNAPSHOT_INVALIDATION_DEFERRED_XCTEST_OCCUPIED")
-      DispatchQueue.main.async {
-        self.invalidateCachedTarget(reason: "ax_snapshot_failure")
-      }
-      return
-    }
-    do {
-      try runMainThreadWork(
-        "target_invalidation",
-        timeout: 1,
-        timeoutError: mainThreadExecutionTimeoutError
-      ) {
-        self.invalidateCachedTarget(reason: "ax_snapshot_failure")
-      }
-    } catch {
-      NSLog("AGENT_DEVICE_RUNNER_SNAPSHOT_INVALIDATION_FAILED=%@", String(describing: error))
+    applyMainOwnedSnapshotState("target_invalidation") {
+      self.invalidateCachedTarget(reason: "ax_snapshot_failure")
     }
   }
 }
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotTiming.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotTiming.swift
index 288e4cca5a..fd11051e0f 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotTiming.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotTiming.swift
@@ -57,6 +57,35 @@ struct SnapshotPhaseTimer {
   }
 }
 
+/// Keeps the first capture plan that runs against a fresh target process from penalizing the XCTest
+/// channel for a slow tier. Lifecycle code arms and disarms it on main; the capture plan consumes it
+/// on the command queue, so a snapshot that returns before running a plan leaves it pending.
+final class SnapshotXCTestPenaltyWarmupExemption {
+  private let lock = NSLock()
+  private var pending = false
+
+  var isPending: Bool {
+    get {
+      lock.lock()
+      defer { lock.unlock() }
+      return pending
+    }
+    set {
+      lock.lock()
+      pending = newValue
+      lock.unlock()
+    }
+  }
+
+  func consume() -> Bool {
+    lock.lock()
+    defer { lock.unlock() }
+    let wasPending = pending
+    pending = false
+    return wasPending
+  }
+}
+
 extension RunnerTests {
   struct SnapshotBackendAttempt {
     enum Outcome {
@@ -69,6 +98,20 @@ extension RunnerTests {
     /// or error text.
     let outcome: Outcome
     let timing: SnapshotCaptureTiming
+    /// Whether the tier finished collecting or stopped at its own deadline. A tier that stopped at
+    /// its deadline timed out even when it handed back a payload, so penalty and recovery policy
+    /// read this instead of classifying the payload (#2781).
+    let tierOutcome: SnapshotTierOutcome
+
+    init(
+      outcome: Outcome,
+      timing: SnapshotCaptureTiming,
+      tierOutcome: SnapshotTierOutcome = .completed
+    ) {
+      self.outcome = outcome
+      self.timing = timing
+      self.tierOutcome = tierOutcome
+    }
   }
 
   /// The penalty breaker observes only acquisition facts. Presentation is a separate phase and
@@ -84,6 +127,9 @@ extension RunnerTests {
     {
       return "\(kind.rawValue)_backend_timeout"
     }
+    if attempt.tierOutcome == .deadlineExhausted {
+      return "\(kind.rawValue)_backend_timeout"
+    }
     guard attempt.timing.acquisitionMs > slowThresholdMs else { return nil }
     return "slow_\(kind.rawValue)_capture_\(Int(attempt.timing.acquisitionMs))ms"
   }
@@ -91,6 +137,7 @@ extension RunnerTests {
   func recordXCTestSnapshotBackendAttemptIfNeeded(
     _ kind: SnapshotBackendKind,
     attempt: SnapshotBackendAttempt,
+    bundleId: String?,
     penaltySuppressed: Bool
   ) {
     guard !penaltySuppressed else { return }
@@ -102,7 +149,7 @@ extension RunnerTests {
       )
     else { return }
     penalizeSnapshotXCTestChannel(
-      bundleId: currentBundleId,
+      bundleId: bundleId,
       reason: reason
     )
   }
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift
index 0785df2b96..5574a47797 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift
@@ -52,6 +52,8 @@ final class RunnerTests: XCTestCase {
   let commandExecutionQueue = DispatchQueue(label: "agent-device.runner.commands")
   let app = XCUIApplication()
   lazy var springboard = XCUIApplication(bundleIdentifier: Self.springboardBundleId)
+  // Main-thread owned, like `runnerAccessibilityHealth`: an off-main capture plan reads them only
+  // through its `SnapshotCaptureTarget` and writes them only through `applyMainOwnedSnapshotState`.
   var currentApp: XCUIApplication?
   var currentBundleId: String?
   var currentAppProcessIdentifier: Int?
@@ -114,7 +116,7 @@ final class RunnerTests: XCTestCase {
   var snapshotXCTestChannelPenaltyBundleId: String?
   var snapshotXCTestChannelPenaltyUntil = Date.distantPast
   let snapshotXCTestChannelPenaltyDuration: TimeInterval = 120
-  var snapshotXCTestPenaltyWarmupExemptionPending = false
+  let snapshotXCTestPenaltyWarmupExemption = SnapshotXCTestPenaltyWarmupExemption()
   // Sticky per-bundle hint for the private AX depth ladder: deep RN screens reject the default
   // depth with kAXErrorIllegalArgument on EVERY capture, so once a shallower rung is accepted
   // later captures start there instead of re-paying the rejected deep request (~300ms per
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+AXRecoveryConformanceTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+AXRecoveryConformanceTests.swift
index 6e6364c310..cde158367b 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+AXRecoveryConformanceTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+AXRecoveryConformanceTests.swift
@@ -426,8 +426,6 @@ extension RunnerTests {
     XCTAssertFalse(fixture.hintCases.isEmpty)
     defer {
       clearPrivateAXAcceptedDepth(reason: "test-cleanup")
-      currentBundleId = nil
-      currentAppProcessIdentifier = nil
     }
     for hintCase in fixture.hintCases {
       clearPrivateAXAcceptedDepth(reason: "fixture-case")
@@ -440,8 +438,6 @@ extension RunnerTests {
         let target = try XCTUnwrap(step.target, name)
         let processIdentifier = try XCTUnwrap(
           Int(target.generation.filter(\.isNumber)), "\(name): generation must end in digits")
-        currentBundleId = target.id
-        currentAppProcessIdentifier = processIdentifier
         let explicit = step.explicitDepth ?? false
         let remembered =
           explicit
@@ -459,6 +455,8 @@ extension RunnerTests {
           XCTAssertEqual(capture.truncated, outcome.complete == false, "\(name): bounded")
           // The production path records only after a successful ladder, exactly like this.
           recordPrivateAXAcceptedDepth(
+            bundleId: target.id,
+            processIdentifier: processIdentifier,
             exactDepthRequested: explicit,
             effectiveDepth: capture.effectiveDepth,
             attemptDepths: capture.attemptDepths)
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+AXSnapshotFallbackTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+AXSnapshotFallbackTests.swift
index cbcad722a9..82f6bec10b 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+AXSnapshotFallbackTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+AXSnapshotFallbackTests.swift
@@ -125,23 +125,22 @@ extension RunnerTests {
   func testViewportReadSkippedWhileXCTestChannelPenalized() {
     // Pins the viewport fast path (#1587 review): every penalized private AX capture used to burn
     // the full 1s main-thread timeout on a doomed viewport read before falling back.
-    currentBundleId = "xyz.blueskyweb.app"
+    let bundleId = "xyz.blueskyweb.app"
     defer {
-      currentBundleId = nil
       clearSnapshotXCTestChannelPenalty(reason: "test-cleanup")
       abandonedMainThreadWorkCount = 0
     }
 
-    XCTAssertTrue(shouldReadPrivateAXViewportViaXCTest())
+    XCTAssertTrue(shouldReadPrivateAXViewportViaXCTest(bundleId: bundleId))
 
-    penalizeSnapshotXCTestChannel(bundleId: "xyz.blueskyweb.app", reason: "test")
-    XCTAssertFalse(shouldReadPrivateAXViewportViaXCTest())
+    penalizeSnapshotXCTestChannel(bundleId: bundleId, reason: "test")
+    XCTAssertFalse(shouldReadPrivateAXViewportViaXCTest(bundleId: bundleId))
 
     clearSnapshotXCTestChannelPenalty(reason: "test")
-    XCTAssertTrue(shouldReadPrivateAXViewportViaXCTest())
+    XCTAssertTrue(shouldReadPrivateAXViewportViaXCTest(bundleId: bundleId))
 
     abandonedMainThreadWorkCount = 1
-    XCTAssertFalse(shouldReadPrivateAXViewportViaXCTest())
+    XCTAssertFalse(shouldReadPrivateAXViewportViaXCTest(bundleId: bundleId))
   }
 
   /// The wire field must reach both capture options AND the backend pin: custom
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+CommandDispatchTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+CommandDispatchTests.swift
index dee860248e..e9b6c6a1b2 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+CommandDispatchTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+CommandDispatchTests.swift
@@ -71,7 +71,7 @@ extension RunnerTests {
     currentApp = app
     currentBundleId = "com.example.stale-target"
     currentAppProcessIdentifier = 42
-    snapshotXCTestPenaltyWarmupExemptionPending = true
+    snapshotXCTestPenaltyWarmupExemption.isPending = true
     defer {
       invalidateCachedTarget(reason: "unit_test_cleanup")
       app.terminate()
@@ -85,7 +85,7 @@ extension RunnerTests {
     XCTAssertNil(currentApp)
     XCTAssertNil(currentBundleId)
     XCTAssertNil(currentAppProcessIdentifier)
-    XCTAssertFalse(snapshotXCTestPenaltyWarmupExemptionPending)
+    XCTAssertFalse(snapshotXCTestPenaltyWarmupExemption.isPending)
   }
 
   func testSkipAppActivationPreflightIncludesForegroundCachedCoordinateOnlyTaps() throws {
@@ -248,6 +248,79 @@ extension RunnerTests {
     XCTAssertFalse(hasAbandonedMainThreadWork())
   }
 
+  /// A coordinate tap resolves its system-modal routing on the command queue while main may still be
+  /// clearing or rebinding the cached target. Target identity belongs to main, so an abandoned
+  /// routing probe must arm its penalty with the identity main settled on — never with the identity
+  /// the command queue read while that write was still pending (#2781).
+  func testCoordinateTapRoutingPenalizesTheIdentityMainSettledOnWhileTheWriteWasPending() throws {
+    app.launch()
+    XCTAssertTrue(app.wait(for: .runningForeground, timeout: 10))
+    let pendingBundleId = "com.example.routing-pending-stale"
+    let settledBundleId = "com.example.routing-pending-settled"
+    currentApp = app
+    currentBundleId = pendingBundleId
+    snapshotXCTestPenaltyWarmupExemption.isPending = false
+    clearSnapshotXCTestChannelPenalty(reason: "test-setup")
+    defer {
+      systemModalProbeOverrideForTesting = nil
+      clearSnapshotXCTestChannelPenalty(reason: "test-cleanup")
+      invalidateCachedTarget(reason: "unit_test_cleanup")
+      app.terminate()
+    }
+
+    // Occupy main and rebind the target inside that block: every identity read that arrives while it
+    // is queued sees a target that main is on its way to replacing.
+    let mainRelease = DispatchSemaphore(value: 0)
+    DispatchQueue.main.async {
+      _ = mainRelease.wait(timeout: .now() + 0.5)
+      self.currentBundleId = settledBundleId
+    }
+
+    let probeStarted = expectation(description: "system-modal routing probe started")
+    let probeReleaseGate = DispatchSemaphore(value: 0)
+    systemModalProbeOverrideForTesting = { _ in
+      probeStarted.fulfill()
+      // Outlives the probe's own slice, so the abandonment hook is what arms the penalty.
+      _ = probeReleaseGate.wait(timeout: .now() + 15)
+      return nil
+    }
+    let tap = try runnerCommandFixture(
+      #"{"command":"tap","commandId":"tap-pending-target-write","x":10,"y":20}"#
+    )
+
+    final class ResultBox {
+      var response: Response?
+      var penalizedPendingIdentity = false
+      var penalizedSettledIdentity = false
+    }
+    let box = ResultBox()
+    let tapFinished = expectation(description: "off-main tap returned")
+    DispatchQueue(label: "agent-device.runner.tests.tap-pending-target-write").async {
+      box.response = try? self.executeDispatched(command: tap)
+      box.penalizedPendingIdentity = self.isSnapshotXCTestChannelPenalized(bundleId: pendingBundleId)
+      box.penalizedSettledIdentity = self.isSnapshotXCTestChannelPenalized(bundleId: settledBundleId)
+      probeReleaseGate.signal()
+      tapFinished.fulfill()
+    }
+
+    wait(for: [probeStarted, tapFinished], timeout: 40)
+    mainRelease.signal()
+    let drainDeadline = Date().addingTimeInterval(5)
+    while hasAbandonedMainThreadWork(), Date() < drainDeadline {
+      sleepFor(0.002)
+    }
+
+    XCTAssertTrue(
+      box.penalizedSettledIdentity,
+      "the abandoned routing probe must penalize the target main settled on"
+    )
+    XCTAssertFalse(
+      box.penalizedPendingIdentity,
+      "the command queue may not key a penalty with an identity whose write was still pending on main"
+    )
+    XCTAssertFalse(hasAbandonedMainThreadWork())
+  }
+
   func testSkipAppActivationPreflightRejectsSelectorAndMixedSequenceGestures() throws {
     app.launch()
     currentApp = app
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+LifecycleCacheTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+LifecycleCacheTests.swift
index 1cf54a6b29..3c1aa5a21c 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+LifecycleCacheTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+LifecycleCacheTests.swift
@@ -101,10 +101,10 @@ extension RunnerTests {
   }
 
   func testSnapshotPenaltyWarmupExemptionIsConsumedOnce() {
-    snapshotXCTestPenaltyWarmupExemptionPending = true
+    snapshotXCTestPenaltyWarmupExemption.isPending = true
 
-    XCTAssertTrue(consumeSnapshotXCTestPenaltyWarmupExemption())
-    XCTAssertFalse(consumeSnapshotXCTestPenaltyWarmupExemption())
+    XCTAssertTrue(snapshotXCTestPenaltyWarmupExemption.consume())
+    XCTAssertFalse(snapshotXCTestPenaltyWarmupExemption.consume())
   }
 
   func testSnapshotPenaltyCanBeClearedAcrossTargetProcessReplacement() {
@@ -120,14 +120,14 @@ extension RunnerTests {
     currentApp = app
     currentBundleId = "com.example.app"
     currentAppProcessIdentifier = 42
-    snapshotXCTestPenaltyWarmupExemptionPending = true
+    snapshotXCTestPenaltyWarmupExemption.isPending = true
 
     invalidateCachedTarget(reason: "unit_test")
 
     XCTAssertNil(currentApp)
     XCTAssertNil(currentBundleId)
     XCTAssertNil(currentAppProcessIdentifier)
-    XCTAssertFalse(snapshotXCTestPenaltyWarmupExemptionPending)
+    XCTAssertFalse(snapshotXCTestPenaltyWarmupExemption.isPending)
   }
 
   func testTextEntryTapWitnessIsBoundToTargetIdentity() {
@@ -146,7 +146,7 @@ extension RunnerTests {
     currentApp = app
     currentBundleId = "com.example.app"
     currentAppProcessIdentifier = 42
-    snapshotXCTestPenaltyWarmupExemptionPending = true
+    snapshotXCTestPenaltyWarmupExemption.isPending = true
     firstInteractionReadyUptime = nil
     penalizeSnapshotXCTestChannel(bundleId: "com.example.app", reason: "test")
     XCTAssertTrue(isSnapshotXCTestChannelPenalized(bundleId: "com.example.app"))
@@ -157,7 +157,7 @@ extension RunnerTests {
     XCTAssertNil(currentApp)
     XCTAssertNil(currentBundleId)
     XCTAssertNil(currentAppProcessIdentifier)
-    XCTAssertFalse(snapshotXCTestPenaltyWarmupExemptionPending)
+    XCTAssertFalse(snapshotXCTestPenaltyWarmupExemption.isPending)
     XCTAssertFalse(isSnapshotXCTestChannelPenalized(bundleId: "com.example.app"))
     XCTAssertNotNil(firstInteractionReadyUptime)
   }
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotCapturePlanOccupancyTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotCapturePlanOccupancyTests.swift
index c4c92d80c7..edec6e8333 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotCapturePlanOccupancyTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotCapturePlanOccupancyTests.swift
@@ -30,6 +30,44 @@ private final class RunnerBlockingSnapshotStub: NSObject {
   }
 }
 
+/// Records when each `RunnerSlowSweepQueryStub` query started. The swizzled IMP cannot capture
+/// test-local state, so each run resets it.
+private enum RunnerSlowSweepQueryGate {
+  /// Shorter than `flatInteractiveQueryBudget`, so a sweep that stops at its slice deadline never
+  /// outlives the slice; a full sweep of these outlasts the slice, so one that ignores it does.
+  static let queryDuration: TimeInterval = 0.06
+  private static let lock = NSLock()
+  private static var starts: [Date] = []
+
+  static func reset() {
+    lock.lock()
+    starts = []
+    lock.unlock()
+  }
+
+  static func recordStart() {
+    lock.lock()
+    starts.append(Date())
+    lock.unlock()
+  }
+
+  static func recordedStarts() -> [Date] {
+    lock.lock()
+    defer { lock.unlock() }
+    return starts
+  }
+}
+
+/// Stands in for `-[XCUIElementQuery allElementsBoundByIndex]` so every query the sweep runs holds
+/// the main thread for a fixed time and finds nothing.
+private final class RunnerSlowSweepQueryStub: NSObject {
+  @objc var allElementsBoundByIndex: [XCUIElement] {
+    RunnerSlowSweepQueryGate.recordStart()
+    Thread.sleep(forTimeInterval: RunnerSlowSweepQueryGate.queryDuration)
+    return []
+  }
+}
+
 extension RunnerTests {
   /// The Bluesky feed shape: the tree XPC grinds past its slice. The plan must recover through
   /// private AX without queueing the query sweep behind the abandoned XPC, and a fresh process's
@@ -60,7 +98,8 @@ extension RunnerTests {
     _ = capturedInterfaceOrientation(app: app)
     currentApp = app
     currentBundleId = "com.callstack.agentdevice.runner.tree-capture-test"
-    snapshotXCTestPenaltyWarmupExemptionPending = true
+    snapshotXCTestPenaltyWarmupExemption.isPending = true
+    let captureTarget = takeSnapshotCaptureTarget(app: app)
     RunnerBlockingSnapshotGate.release = DispatchSemaphore(value: 0)
     let originalImplementation = method_getImplementation(snapshotMethod)
     method_setImplementation(snapshotMethod, method_getImplementation(stubMethod))
@@ -85,7 +124,7 @@ extension RunnerTests {
       do {
         box.payload = try self.runSnapshotCapturePlan(
           Self.regularVisiblePlan,
-          app: self.app,
+          target: captureTarget,
           options: PresentationOptions(interactiveOnly: false, depth: nil, scope: nil, raw: false),
           terminal: .sparseWithFatalOnAXFailure,
           deadline: Date().addingTimeInterval(12)
@@ -96,7 +135,7 @@ extension RunnerTests {
       self.mainThreadWorkLock.lock()
       box.abandonedAfterPlan = self.abandonedMainThreadWorkCount
       self.mainThreadWorkLock.unlock()
-      box.penalizedAfterPlan = self.isSnapshotXCTestChannelPenalized(bundleId: self.currentBundleId)
+      box.penalizedAfterPlan = self.isSnapshotXCTestChannelPenalized(bundleId: captureTarget.bundleId)
       RunnerBlockingSnapshotGate.release.signal()
       planned.fulfill()
     }
@@ -131,5 +170,201 @@ extension RunnerTests {
       return XCTFail("expected the runner idle once the tree XPC drained")
     }
   }
+
+  /// A non-interactive query sweep runs its queries on the main thread one at a time. It must stop
+  /// starting them at the slice deadline its caller waits for, not at the plan deadline, or it holds
+  /// the main thread after the plan has answered (#2783).
+  func testNonInteractiveQuerySweepStopsAtTheSliceItsCallerWaitsFor() throws {
+    let sweepQueryCount = 19
+    XCTAssertLessThan(RunnerSlowSweepQueryGate.queryDuration, Self.flatInteractiveQueryBudget)
+    XCTAssertGreaterThan(
+      RunnerSlowSweepQueryGate.queryDuration * Double(sweepQueryCount),
+      Self.flatInteractiveFallbackBudget
+    )
+    guard
+      let queryMethod = class_getInstanceMethod(
+        XCUIElementQuery.self,
+        #selector(getter: XCUIElementQuery.allElementsBoundByIndex)
+      ),
+      let stubMethod = class_getInstanceMethod(
+        RunnerSlowSweepQueryStub.self,
+        #selector(getter: RunnerSlowSweepQueryStub.allElementsBoundByIndex)
+      )
+    else {
+      XCTFail("unable to install the slow sweep query stub")
+      return
+    }
+    app.launchArguments = ["--agent-device-selector-read-regression"]
+    app.launch()
+    XCTAssertTrue(app.wait(for: .runningForeground, timeout: 10))
+    XCTAssertFalse(app.frame.isEmpty)
+    currentApp = app
+    currentBundleId = "com.callstack.agentdevice.runner.query-sweep-slice-test"
+    let captureTarget = takeSnapshotCaptureTarget(app: app)
+    RunnerSlowSweepQueryGate.reset()
+    let originalImplementation = method_getImplementation(queryMethod)
+    method_setImplementation(queryMethod, method_getImplementation(stubMethod))
+    defer {
+      method_setImplementation(queryMethod, originalImplementation)
+      clearSnapshotXCTestChannelPenalty(reason: "test-cleanup")
+      invalidateCachedTarget(reason: "unit_test_cleanup")
+      app.terminate()
+    }
+
+    final class ResultBox {
+      var payload: DataPayload?
+      var error: Error?
+      var returnedAt: Date?
+      var abandonedAtReturn: Bool?
+    }
+    let box = ResultBox()
+    let planned = expectation(description: "query-sweep plan answered")
+    DispatchQueue(label: "agent-device.runner.tests.query-sweep-slice").async {
+      do {
+        box.payload = try self.runSnapshotCapturePlan(
+          [.querySweep],
+          target: captureTarget,
+          options: PresentationOptions(interactiveOnly: false, depth: nil, scope: nil, raw: false),
+          terminal: .sparseWithFatalOnAXFailure,
+          deadline: Date().addingTimeInterval(20)
+        )
+      } catch {
+        box.error = error
+      }
+      box.returnedAt = Date()
+      box.abandonedAtReturn = self.hasAbandonedMainThreadWork()
+      planned.fulfill()
+    }
+
+    wait(for: [planned], timeout: 30)
+    let drainDeadline = Date().addingTimeInterval(3)
+    while hasAbandonedMainThreadWork(), Date() < drainDeadline {
+      sleepFor(0.005)
+    }
+    let starts = RunnerSlowSweepQueryGate.recordedStarts()
+
+    XCTAssertNil(box.error)
+    XCTAssertEqual(box.payload?.snapshotQuality?.backend, SnapshotBackendKind.querySweep.rawValue)
+    XCTAssertEqual(
+      box.abandonedAtReturn,
+      false,
+      "the sweep must finish inside the slice its caller waits for"
+    )
+    let returnedAt = try XCTUnwrap(box.returnedAt)
+    XCTAssertTrue(
+      starts.allSatisfy { $0 <= returnedAt },
+      "no sweep query may start after the plan answered"
+    )
+    XCTAssertLessThan(starts.count, sweepQueryCount, "the slice must cut the sweep short")
+    XCTAssertFalse(hasAbandonedMainThreadWork())
+  }
+
+  /// A query sweep that stops at its own slice deadline collected a partial tree, not an answer, so
+  /// it is a tier timeout: the plan must arm the XCTest-channel penalty and let private AX answer,
+  /// keeping the partial sweep only as the fallback. Accepting it because it carries more nodes than
+  /// the sparse threshold ships a hierarchy-free capture and leaves every later capture of the same
+  /// screen to pay for the full sweep again (#2781).
+  func testQuerySweepThatEndsOnItsSliceDeadlinePenalizesChannelAndReachesPrivateAX() throws {
+    guard
+      let queryMethod = class_getInstanceMethod(
+        XCUIElementQuery.self,
+        #selector(getter: XCUIElementQuery.allElementsBoundByIndex)
+      ),
+      let stubMethod = class_getInstanceMethod(
+        RunnerSlowSweepQueryStub.self,
+        #selector(getter: RunnerSlowSweepQueryStub.allElementsBoundByIndex)
+      )
+    else {
+      XCTFail("unable to install the slow sweep query stub")
+      return
+    }
+    app.launchArguments = ["--agent-device-selector-read-regression"]
+    app.launch()
+    XCTAssertTrue(app.wait(for: .runningForeground, timeout: 10))
+    currentApp = app
+    currentBundleId = "com.callstack.agentdevice.runner.query-sweep-timeout-test"
+    snapshotXCTestPenaltyWarmupExemption.isPending = false
+    clearSnapshotXCTestChannelPenalty(reason: "test-setup")
+    RunnerSlowSweepQueryGate.reset()
+    let captureTarget = takeSnapshotCaptureTarget(app: app)
+    let originalImplementation = method_getImplementation(queryMethod)
+    method_setImplementation(queryMethod, method_getImplementation(stubMethod))
+    defer {
+      method_setImplementation(queryMethod, originalImplementation)
+      clearSnapshotXCTestChannelPenalty(reason: "test-cleanup")
+      clearPrivateAXAcceptedDepth(reason: "test-cleanup")
+      invalidateCachedTarget(reason: "unit_test_cleanup")
+      app.terminate()
+    }
+
+    final class ResultBox {
+      var payload: DataPayload?
+      var error: Error?
+      var abandonedAtReturn = false
+      var penalizedAtReturn = false
+      var sweepStartsAfterFirstPlan = 0
+      var secondPayload: DataPayload?
+      var secondError: Error?
+    }
+    let box = ResultBox()
+    let planned = expectation(description: "slow-sweep plan answered")
+    DispatchQueue(label: "agent-device.runner.tests.query-sweep-timeout").async {
+      do {
+        box.payload = try self.runSnapshotCapturePlan(
+          [.querySweep, .privateAX],
+          target: captureTarget,
+          options: PresentationOptions(interactiveOnly: false, depth: nil, scope: nil, raw: false),
+          terminal: .sparseWithFatalOnAXFailure,
+          deadline: Date().addingTimeInterval(20)
+        )
+      } catch {
+        box.error = error
+      }
+      box.abandonedAtReturn = self.hasAbandonedMainThreadWork()
+      box.penalizedAtReturn = self.isSnapshotXCTestChannelPenalized(bundleId: captureTarget.bundleId)
+      box.sweepStartsAfterFirstPlan = RunnerSlowSweepQueryGate.recordedStarts().count
+      do {
+        box.secondPayload = try self.runSnapshotCapturePlan(
+          Self.regularVisiblePlan,
+          target: self.takeSnapshotCaptureTarget(app: self.app),
+          options: PresentationOptions(interactiveOnly: false, depth: nil, scope: nil, raw: false),
+          terminal: .sparseWithFatalOnAXFailure,
+          deadline: Date().addingTimeInterval(20)
+        )
+      } catch {
+        box.secondError = error
+      }
+      planned.fulfill()
+    }
+
+    wait(for: [planned], timeout: 60)
+    XCTAssertNil(box.error)
+    let quality = box.payload?.snapshotQuality
+    XCTAssertEqual(
+      quality?.backend,
+      SnapshotBackendKind.privateAX.rawValue,
+      "a sweep that ended on its slice deadline is a tier timeout, not an accepted capture"
+    )
+    XCTAssertEqual(quality?.state, "recovered")
+    XCTAssertGreaterThan(box.payload?.nodes?.count ?? 0, 1, "private AX answers with a real tree")
+    XCTAssertFalse(box.abandonedAtReturn, "the sweep must answer inside its own main-thread hop")
+    XCTAssertTrue(
+      box.penalizedAtReturn,
+      "the tier timeout must arm the XCTest-channel penalty for the captured target"
+    )
+
+    XCTAssertNil(box.secondError)
+    XCTAssertEqual(
+      box.secondPayload?.snapshotQuality?.backend,
+      SnapshotBackendKind.privateAX.rawValue,
+      "the armed penalty must defer the next plan's XCTest tiers, not re-run the sweep"
+    )
+    XCTAssertEqual(
+      RunnerSlowSweepQueryGate.recordedStarts().count,
+      box.sweepStartsAfterFirstPlan,
+      "the deferred plan may start no sweep query at all"
+    )
+    XCTAssertFalse(hasAbandonedMainThreadWork())
+  }
 }
 #endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotCapturePlanTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotCapturePlanTests.swift
index f0eae25e74..a2c709eeb9 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotCapturePlanTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotCapturePlanTests.swift
@@ -76,6 +76,37 @@ extension RunnerTests {
     XCTAssertNotNil(Self.sparsePayloadReason(DataPayload(nodes: [], truncated: false)))
   }
 
+  /// A sweep the slice cut short is rejected as a tier timeout even when what it collected clears
+  /// every bar the quality classifier has, while the identical payload from a sweep that ran all its
+  /// queries is accepted. The pair is the point: node count cannot see the deadline (#2781).
+  func testDeadlineExhaustedTierIsRejectedWhileItsIdenticalCompletedPayloadIsAccepted() {
+    let root = planTestNode(index: 0, type: "Application", label: "Example App", hittable: true)
+    let nodes: [PresentedNode] = [root] + (1..<13).map { index in
+      planTestNode(index: index, type: "Button", label: "Row \(index)", hittable: true, parentIndex: 0)
+    }
+    let payload = DataPayload(nodes: nodes, truncated: true)
+    XCTAssertNil(
+      Self.sparsePayloadReason(payload),
+      "this payload clears the classifier on its own, so only the tier outcome can reject it"
+    )
+    XCTAssertEqual(
+      Self.snapshotTierRejectionReason(
+        outcome: .deadlineExhausted,
+        kind: .querySweep,
+        payload: payload
+      )?.code,
+      "budget",
+      "a tier that spent its capture slice is a timeout whatever it collected"
+    )
+    XCTAssertNil(
+      Self.snapshotTierRejectionReason(
+        outcome: .completed,
+        kind: .querySweep,
+        payload: payload
+      )
+    )
+  }
+
   func testCollapsedLeafIndexesFlagsMergedContainersOnly() {
     let root = planTestNode(index: 0, type: "Application", label: "App")
     let merged = planTestNode(
@@ -460,7 +491,7 @@ extension RunnerTests {
     func capture(depth: Int?) throws -> DataPayload {
       try runSnapshotCapturePlan(
         Self.regularVisiblePlan,
-        app: app,
+        target: takeSnapshotCaptureTarget(app: app),
         options: PresentationOptions(
           interactiveOnly: false,
           depth: depth,
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotCaptureTargetTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotCaptureTargetTests.swift
new file mode 100644
index 0000000000..2139a30ccb
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotCaptureTargetTests.swift
@@ -0,0 +1,104 @@
+import XCTest
+import AgentDeviceSnapshotPresentation
+
+extension RunnerTests {
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS
+  func testSnapshotCaptureTargetKeepsPreparedIdentityAndLeavesWarmupExemptionPending() {
+    currentApp = app
+    currentBundleId = "com.example.prepared"
+    currentAppProcessIdentifier = 42
+    snapshotXCTestPenaltyWarmupExemption.isPending = true
+    defer { invalidateCachedTarget(reason: "unit_test_cleanup") }
+
+    let target = takeSnapshotCaptureTarget(app: app)
+    currentBundleId = "com.example.replaced"
+    currentAppProcessIdentifier = 43
+
+    XCTAssertTrue(target.app === app)
+    XCTAssertEqual(target.bundleId, "com.example.prepared")
+    XCTAssertEqual(target.processIdentifier, 42)
+    XCTAssertTrue(
+      snapshotXCTestPenaltyWarmupExemption.isPending,
+      "only a capture plan that runs may spend the exemption"
+    )
+  }
+
+#if os(iOS)
+  func testBlockingModalSnapshotLeavesWarmupExemptionForTheFirstCapturePlan() throws {
+    currentApp = app
+    currentBundleId = "com.example.fresh-process"
+    currentAppProcessIdentifier = 42
+    snapshotXCTestPenaltyWarmupExemption.isPending = true
+    systemModalProbeOverrideForTesting = { _ in DataPayload(message: "blocking system modal") }
+    defer {
+      systemModalProbeOverrideForTesting = nil
+      runnerAccessibilityHealth = .unknown
+      invalidateCachedTarget(reason: "unit_test_cleanup")
+    }
+    let options = PresentationOptions(interactiveOnly: false, depth: nil, scope: nil, raw: false)
+
+    let fast = try snapshotFast(target: takeSnapshotCaptureTarget(app: app), options: options)
+    let raw = try snapshotRaw(target: takeSnapshotCaptureTarget(app: app), options: options)
+
+    XCTAssertEqual(fast.message, "blocking system modal")
+    XCTAssertEqual(raw.message, "blocking system modal")
+    XCTAssertTrue(
+      snapshotXCTestPenaltyWarmupExemption.isPending,
+      "a snapshot answered by the modal probe runs no capture plan, so the exemption stays pending"
+    )
+
+    _ = try runSnapshotCapturePlan(
+      [],
+      target: takeSnapshotCaptureTarget(app: app),
+      options: options,
+      terminal: .sparseWithFatalOnAXFailure
+    )
+
+    XCTAssertFalse(
+      snapshotXCTestPenaltyWarmupExemption.isPending,
+      "the first capture plan that runs spends the exemption"
+    )
+  }
+#endif
+
+  func testProbePenaltyIdentityTakesTheIdentityItsCallerMayLegallyKnow() {
+    let prepared = SnapshotProbePenaltyIdentity(.prepared(bundleId: "com.example.prepared"))
+    prepared.captureFromMain(bundleId: "com.example.settled")
+    XCTAssertEqual(
+      prepared.penalizedBundleId,
+      "com.example.prepared",
+      "a capture penalizes the target it was prepared for, whatever lifecycle binds meanwhile"
+    )
+
+    let mainOwned = SnapshotProbePenaltyIdentity(.mainOwnedTarget)
+    XCTAssertNil(
+      mainOwned.penalizedBundleId,
+      "a command-queue caller knows no identity until the probe's main-side block runs"
+    )
+    mainOwned.captureFromMain(bundleId: "com.example.settled")
+    XCTAssertEqual(mainOwned.penalizedBundleId, "com.example.settled")
+  }
+
+  func testMainOwnedSnapshotStateWriteRunsOnMainBeforeReturningWhenMainIsFree() {
+    final class ResultBox {
+      var ranOnMainThread: Bool?
+      var appliedBeforeReturn: Bool?
+    }
+    let box = ResultBox()
+    let finished = expectation(description: "off-main write returned")
+
+    DispatchQueue(label: "agent-device.runner.tests.main-owned-snapshot-state").async {
+      self.applyMainOwnedSnapshotState("unit_test") {
+        box.ranOnMainThread = Thread.isMainThread
+      }
+      box.appliedBeforeReturn = box.ranOnMainThread != nil
+      finished.fulfill()
+    }
+
+    wait(for: [finished], timeout: 3)
+    XCTAssertEqual(box.ranOnMainThread, true)
+    XCTAssertEqual(box.appliedBeforeReturn, true)
+    XCTAssertFalse(hasAbandonedMainThreadWork())
+  }
+#endif
+}
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotTests.swift
index 83ac2f5a00..c679bbcbde 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotTests.swift
@@ -61,6 +61,159 @@ extension RunnerTests {
     XCTAssertEqual(Self.systemModalProbeSlice(budget: 4, deadlineRemaining: -5), 0)
   }
 
+  func testSnapshotAccessibilityUnavailableQueuesInvalidationBehindAbandonedMainThreadWork() {
+    currentBundleId = "com.example.stale-target"
+    runnerAccessibilityHealth = .healthy
+    defer {
+      currentBundleId = nil
+      runnerAccessibilityHealth = .unknown
+    }
+
+    final class ResultBox {
+      var elapsed: TimeInterval?
+      var payload: DataPayload?
+      var bundleStillCachedWhileBlocked: Bool?
+      var healthWhileBlocked: RunnerAccessibilityHealth?
+      var abandonedWhileBlocked: Int?
+    }
+    let box = ResultBox()
+    let mainBlocked = DispatchSemaphore(value: 0)
+    let releaseMain = DispatchSemaphore(value: 0)
+    let finished = expectation(description: "fail-closed capture returned while main was blocked")
+
+    DispatchQueue(label: "agent-device.runner.tests.ax-unavailable-invalidation").async {
+      _ = try? self.runMainThreadWork(
+        "command_execution",
+        timeout: 0,
+        timeoutError: self.mainThreadExecutionTimeoutError
+      ) {
+        mainBlocked.signal()
+        _ = releaseMain.wait(timeout: .now() + 5)
+        return true
+      }
+      _ = mainBlocked.wait(timeout: .now() + 2)
+      let startedAt = Date()
+      box.payload = self.snapshotAccessibilityUnavailable(
+        failure: SnapshotCaptureFailure(
+          code: Self.axSnapshotErrorCode,
+          message: Self.axSnapshotFailureMessage,
+          hint: Self.axSnapshotHint
+        )
+      )
+      box.elapsed = Date().timeIntervalSince(startedAt)
+      box.bundleStillCachedWhileBlocked = self.currentBundleId != nil
+      box.healthWhileBlocked = self.runnerAccessibilityHealth
+      self.mainThreadWorkLock.lock()
+      box.abandonedWhileBlocked = self.abandonedMainThreadWorkCount
+      self.mainThreadWorkLock.unlock()
+      releaseMain.signal()
+      finished.fulfill()
+    }
+
+    wait(for: [finished], timeout: 8)
+    let drainDeadline = Date().addingTimeInterval(2)
+    while hasAbandonedMainThreadWork() || currentBundleId != nil, Date() < drainDeadline {
+      sleepFor(0.005)
+    }
+
+    XCTAssertEqual(box.payload?.runnerFatal, true)
+    XCTAssertLessThan(
+      box.elapsed ?? .infinity,
+      0.5,
+      "the fail-closed capture must not wait behind abandoned main-thread work"
+    )
+    XCTAssertEqual(
+      box.bundleStillCachedWhileBlocked,
+      true,
+      "the invalidation must queue behind the blocked main thread, not run on the command queue"
+    )
+    XCTAssertEqual(
+      box.healthWhileBlocked,
+      .healthy,
+      "the health write must queue behind the blocked main thread, not run on the command queue"
+    )
+    XCTAssertEqual(box.abandonedWhileBlocked, 1, "the deferred write must not add an abandoned unit")
+    XCTAssertFalse(hasAbandonedMainThreadWork())
+    XCTAssertNil(currentBundleId, "the invalidation must run once the main thread frees")
+    XCTAssertEqual(runnerAccessibilityHealth, .unavailable)
+  }
+
+  func testQuerySweepSliceDeadlineIsTheTierSliceNotThePlanDeadline() {
+    let startedAt = Date(timeIntervalSinceReferenceDate: 1_000)
+    let slice = startedAt.addingTimeInterval(Self.flatInteractiveFallbackBudget)
+
+    XCTAssertEqual(
+      Self.querySweepSliceDeadline(
+        startedAt: startedAt,
+        planDeadline: startedAt.addingTimeInterval(Self.snapshotPlanBudget)
+      ),
+      slice
+    )
+    let nearPlanDeadline = startedAt.addingTimeInterval(Self.flatInteractiveFallbackBudget / 2)
+    XCTAssertEqual(
+      Self.querySweepSliceDeadline(startedAt: startedAt, planDeadline: nearPlanDeadline),
+      nearPlanDeadline
+    )
+  }
+
+  func testQuerySweepStopsAtTheSliceDeadlineBeforeAQueryThatCannotFinish() {
+    let startedAt = Date(timeIntervalSinceReferenceDate: 1_000)
+    let sliceDeadline = Self.querySweepSliceDeadline(
+      startedAt: startedAt,
+      planDeadline: startedAt.addingTimeInterval(Self.snapshotPlanBudget)
+    )
+    var clock = startedAt
+    var startedQueries: [Int] = []
+
+    let sweep = Self.runFlatInteractiveQueries(
+      Array(0..<19),
+      deadline: sliceDeadline,
+      now: { clock }
+    ) { query -> (elements: [Int], axUnavailable: Bool) in
+      startedQueries.append(query)
+      clock = clock.addingTimeInterval(0.475)
+      return ([query], false)
+    }
+
+    XCTAssertEqual(startedQueries, [0, 1], "a query must not start with less than one query budget left")
+    XCTAssertEqual(sweep.elements, [0, 1])
+    XCTAssertEqual(sweep.outcome, .deadlineExhausted)
+    XCTAssertLessThanOrEqual(clock, sliceDeadline, "no started query may outlive the tier slice")
+
+    XCTAssertTrue(
+      Self.querySweepCanStartQuery(deadline: sliceDeadline, now: sliceDeadline.addingTimeInterval(-0.2))
+    )
+    XCTAssertFalse(
+      Self.querySweepCanStartQuery(deadline: sliceDeadline, now: sliceDeadline.addingTimeInterval(-0.05))
+    )
+    XCTAssertFalse(Self.querySweepCanStartQuery(deadline: sliceDeadline, now: sliceDeadline))
+  }
+
+  func testQuerySweepRunsEveryQueryThatFitsAndStopsOnAXUnavailable() {
+    let startedAt = Date(timeIntervalSinceReferenceDate: 1_000)
+    let deadline = startedAt.addingTimeInterval(Self.flatInteractiveFallbackBudget)
+
+    let complete = Self.runFlatInteractiveQueries(
+      [0, 1, 2],
+      deadline: deadline,
+      now: { startedAt }
+    ) { query -> (elements: [Int], axUnavailable: Bool) in ([query], false) }
+    XCTAssertEqual(complete.elements, [0, 1, 2])
+    XCTAssertEqual(complete.outcome, .completed)
+
+    let rejected = Self.runFlatInteractiveQueries(
+      [0, 1, 2],
+      deadline: deadline,
+      now: { startedAt }
+    ) { query -> (elements: [Int], axUnavailable: Bool) in ([query], query == 1) }
+    XCTAssertEqual(rejected.elements, [0, 1])
+    XCTAssertEqual(
+      rejected.outcome,
+      .completed,
+      "an AX refusal ends the sweep on its own terms, not on the deadline"
+    )
+  }
+
   // Simulator-only: the bounded probe body returns nil on macOS (no SpringBoard host), so the
   // timeout/penalty/drain machinery below only exists on the iOS branch.
 #if os(iOS)
@@ -83,13 +236,14 @@ extension RunnerTests {
   /// assertion instead of racing a fixed-timing guess.
   private func assertBoundedSystemModalProbeTimeoutRecoversThenReleasesOnDrain(
     entryPointName: String,
-    callEntryPoint: @escaping (XCUIApplication, PresentationOptions) throws -> DataPayload
+    callEntryPoint: @escaping (SnapshotCaptureTarget, PresentationOptions) throws -> DataPayload
   ) {
     let targetBundleId = "com.callstack.agentdevice.runner.missing.snapshot-timeout-test"
     let snapshotTarget = XCUIApplication(bundleIdentifier: targetBundleId)
     let probeReleaseGate = DispatchSemaphore(value: 0)
     currentApp = snapshotTarget
     currentBundleId = targetBundleId
+    let captureTarget = takeSnapshotCaptureTarget(app: snapshotTarget)
     defer {
       probeReleaseGate.signal()
       currentApp = nil
@@ -120,7 +274,7 @@ extension RunnerTests {
     let drained = expectation(description: "\(entryPointName) modal probe drained")
     DispatchQueue(label: "agent-device.runner.tests.modal-probe-timeout").async {
       box.payload = try? callEntryPoint(
-        snapshotTarget,
+        captureTarget,
         PresentationOptions(interactiveOnly: false, depth: nil, scope: nil, raw: false)
       )
 
@@ -130,7 +284,7 @@ extension RunnerTests {
         box.wasBusyBeforeDrain = true
       }
       box.hadAbandonedCaptureBeforeDrain = self.hasAbandonedMainThreadWork()
-      box.wasPenalizedBeforeDrain = self.isSnapshotXCTestChannelPenalized(bundleId: self.currentBundleId)
+      box.wasPenalizedBeforeDrain = self.isSnapshotXCTestChannelPenalized(bundleId: targetBundleId)
 
       // 2) `box.payload` above was already produced -- through the capture plan's recovery
       // tiers -- while the probe is still blocked on `probeReleaseGate`, i.e. recovered before
@@ -185,14 +339,14 @@ extension RunnerTests {
   func testBoundedSystemModalProbeTimeoutRecoversThenReleasesOnDrain() {
     assertBoundedSystemModalProbeTimeoutRecoversThenReleasesOnDrain(entryPointName: "snapshotFast") {
       target, options in
-      try self.snapshotFast(app: target, options: options)
+      try self.snapshotFast(target: target, options: options)
     }
   }
 
   func testBoundedSystemModalProbeTimeoutRecoversThenReleasesOnDrainForSnapshotRaw() {
     assertBoundedSystemModalProbeTimeoutRecoversThenReleasesOnDrain(entryPointName: "snapshotRaw") {
       target, options in
-      try self.snapshotRaw(app: target, options: options)
+      try self.snapshotRaw(target: target, options: options)
     }
   }
 #endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotTimingTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotTimingTests.swift
index 24fdcfaa46..b815c96725 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotTimingTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotTimingTests.swift
@@ -60,6 +60,51 @@ extension RunnerTests {
     )
   }
 
+  /// A tier that stopped starting work at its own deadline is a timeout for the breaker even when it
+  /// answered fast and with a payload: the partial sweep must arm the penalty exactly as a slow tier
+  /// does, and a tier that finished fast must not (#2781).
+  func testDeadlineExhaustedTierAttemptArmsTheChannelPenaltyWithoutBeingSlow() {
+    let capture = SnapshotBackendCapture(
+      payload: DataPayload(nodes: [], truncated: true),
+      effectiveDepth: nil
+    )
+    let exhausted = SnapshotBackendAttempt(
+      outcome: .captured(capture),
+      timing: SnapshotCaptureTiming(acquisitionMs: 1_000, presentationMs: 10),
+      tierOutcome: .deadlineExhausted
+    )
+    XCTAssertEqual(
+      Self.snapshotXCTestPenaltyReason(
+        kind: .querySweep,
+        attempt: exhausted,
+        slowThresholdMs: 3_000
+      ),
+      "queries_backend_timeout"
+    )
+
+    let completed = SnapshotBackendAttempt(
+      outcome: .captured(capture),
+      timing: SnapshotCaptureTiming(acquisitionMs: 1_000, presentationMs: 10),
+      tierOutcome: .completed
+    )
+    XCTAssertNil(
+      Self.snapshotXCTestPenaltyReason(
+        kind: .querySweep,
+        attempt: completed,
+        slowThresholdMs: 3_000
+      )
+    )
+
+    XCTAssertNil(
+      Self.snapshotXCTestPenaltyReason(
+        kind: .privateAX,
+        attempt: exhausted,
+        slowThresholdMs: 3_000
+      ),
+      "a tier that owes nothing to the XCTest channel cannot penalize it"
+    )
+  }
+
   func testSnapshotPhaseTimerReportsAcquisitionAndPresentationSeparately() {
     var now = Date(timeIntervalSinceReferenceDate: 100)
     var timer = SnapshotPhaseTimer(now: { now })

From faa69ff784f59da0a68348c25359405bdf1ab2ff Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 24 Sep 2026 09:06:19 +0200
Subject: [PATCH 076/132] fix(ios): refuse every runner read over a not-running
 session app (#2852)

The refusal now keys on the runner's own read trait, not on a host-stamped per-request mark:
isReadOnlyCommand covers findText, readText, snapshot, gestureViewport, and alert get, so a
mutation's leading read -- the viewport read a gesture starts with, the capture that resolves a
selector click/fill -- refuses with APP_NOT_RUNNING exactly like a user-level read. A bare
activate over a launch SpringBoard holds behind its "Open in ...?" confirmation is a launch
without the URL, whatever command asked for the read.

The daemon-side request-app-intent plumbing and the observationOnly wire field are removed:
the runner's command trait table is the single source of the rule. The refusal stays retriable
for a wait poll while the transport reads it as a definite answer; open, activate, and
interactions that mutate without a leading read keep the foreground repair.

This adopts the rule picked in the #2852 review (option 1) and says so in the CHANGELOG, the
foreground-repairs docs section, and the physical-device help topic's lifecycle facts.
---
 .github/workflows/ios.yml                     |  2 +
 CHANGELOG.md                                  | 11 ++++++
 .../RunnerTests+CommandDispatch.swift         |  5 +++
 .../RunnerTests+Lifecycle.swift               | 25 ++++++++++++
 .../RunnerTests.swift                         |  2 +
 .../RunnerTests+LifecycleTests.swift          | 36 +++++++++++++++++
 .../__tests__/runner-recovery-wiring.test.ts  | 27 +++++++++++++
 .../src/runner/runner-contract.ts             | 39 ++++++++++++-------
 .../src/runner/runner-error-classification.ts | 16 +++++++-
 src/commands/schema/cli-help.ts               |  1 +
 website/docs/docs/commands.md                 |  9 +++++
 11 files changed, 158 insertions(+), 15 deletions(-)

diff --git a/.github/workflows/ios.yml b/.github/workflows/ios.yml
index 00dc9df934..ac9e3f9775 100644
--- a/.github/workflows/ios.yml
+++ b/.github/workflows/ios.yml
@@ -157,6 +157,8 @@ jobs:
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testRecordStartThrowsTheCaptureRefusalItReceived \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testAlertDispatchResolvesItsOwnModalWithoutCoordinateTapRoutingProbe \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testAlertResolutionCannotBypassRequestedDeadline \
+            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testReadRefusesToLaunchANotRunningSessionApp \
+            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testNonReadCommandStillLaunchesANotRunningSessionApp \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testTypeWithoutResolvedInputReturnsTypedFailureBeforeDispatchingText \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testBareTypeUsesTappedInputWhenSoftwareKeyboardIsHidden \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testHardwareKeyboardResponderConfirmsItsOwnKeyboardFocus \
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 187b1f3762..f4ee6cdf56 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -33,6 +33,17 @@
   config that sets `screenshotFullscreen` for one of those surfaces now fails instead of succeeding
   with the same image it always produced; drop the flag there. macOS app sessions and every other
   platform keep accepting `--fullscreen` unchanged. (#2799)
+- Fixed (ios): no runner read launches a session app that is not running anymore. The XCTest runner
+  repaired foreground loss by calling `activate()`, which launches an app that is not running. After
+  `open <app> --relaunch --launch-url <url>` on a Simulator, iOS can hold the launch behind an
+  "Open in …?" confirmation, and the first read of the waiting session launched the app without the
+  URL. Reads — `snapshot`, `wait`, `is`, `get`, a reading `find`, and an interaction's leading reads
+  (the viewport read a `gesture` starts with, the capture that resolves a selector `click`/`fill`) —
+  now refuse with `COMMAND_FAILED`, `details.runnerErrorCode: "APP_NOT_RUNNING"`, `retriable: true`
+  and a hint to answer the prompt with `alert accept` or relaunch with `open`. A `wait` polls
+  through the refusal; the runner transport never resends it. Interactions that mutate without a
+  leading read (`press`, a coordinate `fill`, `swipe`, `scroll`, hardware keys) keep the foreground
+  repair and still bring a stopped app up.
 - Fixed (ios): a local Simulator snapshot taken through the host AX bridge once again publishes the
   geometric `hittable` fact, so `is hittable` and a `hittable:` selector resolve the same controls on
   the bridge and the XCTest runner. The snapshot capability table has declared `hittable =
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandDispatch.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandDispatch.swift
index 16b2dfccd2..7b75a4e23f 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandDispatch.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandDispatch.swift
@@ -441,6 +441,11 @@ extension RunnerTests {
       let normalizedBundleId = command.appBundleId?
         .trimmingCharacters(in: .whitespacesAndNewlines)
       let requestedBundleId = (normalizedBundleId?.isEmpty == true) ? nil : normalizedBundleId
+      if let bundleId = requestedBundleId,
+        let notRunning = notRunningReadResponse(command: command, bundleId: bundleId)
+      {
+        return .response(notRunning)
+      }
       if let bundleId = requestedBundleId {
         if currentBundleId != bundleId || currentApp == nil {
           _ = activateTarget(bundleId: bundleId, reason: "bundle_changed")
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Lifecycle.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Lifecycle.swift
index 8d378a59e5..304a5b1829 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Lifecycle.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Lifecycle.swift
@@ -316,6 +316,31 @@ extension RunnerTests {
     return foreign.count == 1 ? foreign.first : nil
   }
 
+  /// `activate()` on a not-running app is a bare launch, which would drop the URL of a launch
+  /// SpringBoard still holds behind its "Open in …?" confirmation; see `APP_NOT_RUNNING_RUNNER_CODE`.
+  func notRunningReadResponse(command: Command, bundleId: String) -> Response? {
+#if os(iOS)
+    guard isReadOnlyCommand(command),
+      XCUIApplication(bundleIdentifier: bundleId).state == .notRunning
+    else { return nil }
+    NSLog(
+      "AGENT_DEVICE_RUNNER_READ_TARGET_NOT_RUNNING bundle=%@ command=%@",
+      bundleId,
+      command.command.rawValue
+    )
+    return Response(
+      ok: false,
+      error: ErrorPayload(
+        code: RunnerWireErrorCode.appNotRunning,
+        message: "app '\(bundleId)' is not running",
+        hint: "Reads do not launch the app. Relaunch it with open; if a system prompt such as a deep-link confirmation holds its launch, answer it with alert accept."
+      )
+    )
+#else
+    return nil
+#endif
+  }
+
   func activateTarget(bundleId: String, reason: String) -> XCUIApplication {
     let target = XCUIApplication(bundleIdentifier: bundleId)
     let initialState = target.state
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift
index 5574a47797..19a55659bc 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift
@@ -31,8 +31,10 @@ final class RunnerTests: XCTestCase {
   /// String codes the daemon keys behavior on. `RUNNER_BUSY` and `RUNNER_WEDGED` come from the busy
   /// gate; `MAIN_THREAD_TIMEOUT` is emitted by the transport when a command trips the execution
   /// watchdog, so the daemon can tell "the main thread is now occupied" from a generic failure.
+  /// `APP_NOT_RUNNING` refuses a read whose session app is not running.
   enum RunnerWireErrorCode {
     static let mainThreadTimeout = "MAIN_THREAD_TIMEOUT"
+    static let appNotRunning = "APP_NOT_RUNNING"
   }
 
   static let springboardBundleId = "com.apple.springboard"
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+LifecycleTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+LifecycleTests.swift
index 559fa9021b..a4e75fe198 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+LifecycleTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+LifecycleTests.swift
@@ -134,3 +134,39 @@ extension RunnerTests {
   }
 }
 #endif
+
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS && os(iOS)
+extension RunnerTests {
+  /// Installed on every Simulator runtime and cheap to leave terminated.
+  private static let notRunningTargetBundleId = "com.apple.Preferences"
+
+  private func executeOnTerminatedTarget(_ json: String) throws -> (Response, XCUIApplication) {
+    let target = XCUIApplication(bundleIdentifier: Self.notRunningTargetBundleId)
+    target.terminate()
+    invalidateCachedTarget(reason: "unit_test_setup")
+    defer { invalidateCachedTarget(reason: "unit_test_cleanup") }
+    return (try execute(command: try runnerCommandFixture(json)), target)
+  }
+
+  /// Covers a user-level read and a mutation's leading read (a gesture's `gestureViewport`).
+  func testReadRefusesToLaunchANotRunningSessionApp() throws {
+    for command in ["snapshot", "gestureViewport"] {
+      let (response, target) = try executeOnTerminatedTarget(
+        #"{"command":"\#(command)","commandId":"read","appBundleId":"\#(Self.notRunningTargetBundleId)"}"#
+      )
+      XCTAssertEqual(response.error?.code, RunnerWireErrorCode.appNotRunning, command)
+      XCTAssertEqual(target.state, .notRunning, "\(command) must not launch the session app")
+      target.terminate()
+    }
+  }
+
+  func testNonReadCommandStillLaunchesANotRunningSessionApp() throws {
+    let (response, target) = try executeOnTerminatedTarget(
+      #"{"command":"activate","commandId":"repair","appBundleId":"\#(Self.notRunningTargetBundleId)"}"#
+    )
+    defer { target.terminate() }
+    XCTAssertTrue(response.ok)
+    XCTAssertNotEqual(target.state, .notRunning)
+  }
+}
+#endif
diff --git a/packages/platform-apple/src/runner/__tests__/runner-recovery-wiring.test.ts b/packages/platform-apple/src/runner/__tests__/runner-recovery-wiring.test.ts
index 662d1d503a..5ca6489722 100644
--- a/packages/platform-apple/src/runner/__tests__/runner-recovery-wiring.test.ts
+++ b/packages/platform-apple/src/runner/__tests__/runner-recovery-wiring.test.ts
@@ -319,3 +319,30 @@ test.each([undefined, 'get', 'accept', 'dismiss'] as const)(
     }
   },
 );
+
+// The refusal is retriable for the caller's own poll, but to the transport it is a definite runner
+// answer: no resend, no lost-response status probe, and no invalidation of a healthy session.
+test('a read refused over a not-running app is one definite answer, not a transport retry', async () => {
+  server = await startFakeRunnerServer({
+    snapshot: [
+      { kind: 'runnerError', code: 'APP_NOT_RUNNING', message: "app 'com.example' is not running" },
+    ],
+  });
+  seedSession(server.port);
+
+  await assert.rejects(
+    runAppleRunnerCommand(IOS_SIMULATOR, { command: 'snapshot' }),
+    (error: unknown) => {
+      assert.ok(error instanceof AppError);
+      assert.equal(error.code, 'COMMAND_FAILED');
+      assert.equal(error.details?.runnerErrorCode, 'APP_NOT_RUNNING');
+      assert.equal(error.details?.retriable, true);
+      return true;
+    },
+  );
+  assert.deepEqual(
+    server.requests.map((request) => request.command).filter((command) => command !== 'uptime'),
+    ['snapshot'],
+  );
+  assert.equal(invalidateRunnerSessionMock.mock.calls.length, 0);
+});
diff --git a/packages/platform-apple/src/runner/runner-contract.ts b/packages/platform-apple/src/runner/runner-contract.ts
index b7ecaafd14..3ffb929e19 100644
--- a/packages/platform-apple/src/runner/runner-contract.ts
+++ b/packages/platform-apple/src/runner/runner-contract.ts
@@ -27,6 +27,18 @@ export const RUNNER_BUSY_RUNNER_CODE = 'RUNNER_BUSY';
  */
 export const MAIN_THREAD_TIMEOUT_RUNNER_CODE = 'MAIN_THREAD_TIMEOUT';
 
+/**
+ * The runner's own code for a read whose session app is not running. No runner read launches the
+ * app — a bare launch would drop the payload of a launch still pending, such as a deep link held
+ * behind SpringBoard's confirmation — so the runner refuses any command carrying its read-only
+ * trait, including a mutation's leading read (a gesture's viewport read, a selector's resolving
+ * capture). Only the iOS runner refuses (`#if os(iOS)`); the macOS, tvOS and visionOS runners keep the
+ * activate repair. The refusal describes one poll: the launch that confirmation releases may still be
+ * starting when the next read arrives, so it is retriable for a `wait`, while the transport reads
+ * it as a definite answer and never resends it.
+ */
+export const APP_NOT_RUNNING_RUNNER_CODE = 'APP_NOT_RUNNING';
+
 export type RunnerCommand = {
   command:
     | 'tap'
@@ -175,15 +187,17 @@ export const RUNNER_SCREEN_CAPTURE_REFUSAL_RUNNER_CODES: ReadonlySet<string> = n
 /**
  * Runner codes that classify a failure for the host without renaming it on the wire. They stay
  * `COMMAND_FAILED` and survive as `details.runnerErrorCode`, which is what family policy reads:
- * `RUNNER_BUSY` for retriable contention, `ALERT_NOT_FOUND` for an alert that is not there yet, and
- * the scroll keyboard refusal for a surface the runner declined to swipe under the keys.
+ * `RUNNER_BUSY` for retriable contention, `ALERT_NOT_FOUND` for an alert that is not there yet,
+ * the scroll keyboard refusal for a surface the runner declined to swipe under the keys, and the
+ * retriable `APP_NOT_RUNNING` for a read the runner refused rather than launch the session app.
  */
-const DIAGNOSTIC_ONLY_RUNNER_ERROR_CODES: ReadonlySet<string> = new Set([
-  RUNNER_BUSY_RUNNER_CODE,
-  MAIN_THREAD_TIMEOUT_RUNNER_CODE,
-  ALERT_NOT_FOUND_RUNNER_CODE,
-  SCROLL_KEYBOARD_OCCLUDES_SURFACE_RUNNER_CODE,
-  ...RUNNER_SCREEN_CAPTURE_REFUSAL_RUNNER_CODES,
+const DIAGNOSTIC_ONLY_RUNNER_ERROR_CODES: ReadonlyMap<string, { retriable?: true }> = new Map([
+  [RUNNER_BUSY_RUNNER_CODE, { retriable: true }],
+  [MAIN_THREAD_TIMEOUT_RUNNER_CODE, {}],
+  [APP_NOT_RUNNING_RUNNER_CODE, { retriable: true }],
+  [ALERT_NOT_FOUND_RUNNER_CODE, {}],
+  [SCROLL_KEYBOARD_OCCLUDES_SURFACE_RUNNER_CODE, {}],
+  ...[...RUNNER_SCREEN_CAPTURE_REFUSAL_RUNNER_CODES].map((code) => [code, {}] as const),
 ]);
 
 /** Wire code plus the details every path must publish for one runner-reported error code. */
@@ -202,13 +216,12 @@ export function classifyRunnerReportedError(
   runnerErrorCode: string | undefined,
 ): RunnerReportedErrorClass {
   const diagnosticOnly =
-    runnerErrorCode !== undefined && DIAGNOSTIC_ONLY_RUNNER_ERROR_CODES.has(runnerErrorCode);
+    runnerErrorCode === undefined
+      ? undefined
+      : DIAGNOSTIC_ONLY_RUNNER_ERROR_CODES.get(runnerErrorCode);
   return Object.freeze({
     code: diagnosticOnly ? 'COMMAND_FAILED' : toAppErrorCode(runnerErrorCode),
-    details: Object.freeze({
-      runnerErrorCode,
-      ...(runnerErrorCode === RUNNER_BUSY_RUNNER_CODE ? { retriable: true as const } : {}),
-    }),
+    details: Object.freeze({ runnerErrorCode, ...diagnosticOnly }),
   });
 }
 
diff --git a/packages/platform-apple/src/runner/runner-error-classification.ts b/packages/platform-apple/src/runner/runner-error-classification.ts
index 32514622aa..9d5fca5d2c 100644
--- a/packages/platform-apple/src/runner/runner-error-classification.ts
+++ b/packages/platform-apple/src/runner/runner-error-classification.ts
@@ -9,7 +9,11 @@ import {
   type IosDeveloperDiskImageState,
   type IosDeveloperModeState,
 } from './host.ts';
-import { MAIN_THREAD_TIMEOUT_RUNNER_CODE, RUNNER_BUSY_RUNNER_CODE } from './runner-contract.ts';
+import {
+  APP_NOT_RUNNING_RUNNER_CODE,
+  MAIN_THREAD_TIMEOUT_RUNNER_CODE,
+  RUNNER_BUSY_RUNNER_CODE,
+} from './runner-contract.ts';
 
 export const RUNNER_CACHE_RECOVERY_HINT =
   'If runner build products look stale or corrupted, run `pnpm clean:xcuitest` in a local checkout, or remove ~/.agent-device/apple-runner/derived, then retry.';
@@ -66,6 +70,8 @@ type RunnerErrorMatch = {
 };
 
 const hasRetriableFlag: RunnerErrorDetailsMatch = (details) => details.retriable === true;
+const hasAppNotRunningRunnerCode: RunnerErrorDetailsMatch = (details) =>
+  details.runnerErrorCode === APP_NOT_RUNNING_RUNNER_CODE;
 /**
  * The host's own `DevToolsSecurity -status` read, published as typed details by the probe that
  * takes it. The build-failure rule below keys on this field and never on the probe's message, so
@@ -199,7 +205,8 @@ const PROFILE_UNUSABLE: RunnerErrorRule['buildFailure'] = {
  * `flagged_retriable` precedes the denials (an explicitly retriable error
  * stays retriable whatever its message says), and `usbmux_device_unattached`
  * sits first (retrying cannot attach a cable, and its typed verdict carries
- * the recovery hint a generic connect failure would replace).
+ * the recovery hint a generic connect failure would replace). `app_not_running`
+ * precedes it too: its retriable flag is for the caller's poll, not a resend.
  */
 export const RUNNER_ERROR_RULES: readonly RunnerErrorRule[] = [
   {
@@ -207,6 +214,11 @@ export const RUNNER_ERROR_RULES: readonly RunnerErrorRule[] = [
     match: { code: 'DEVICE_NOT_FOUND', details: hasUsbmuxDeviceUnattached },
     verdicts: { connectRetry: false },
   },
+  {
+    reason: 'app_not_running',
+    match: { code: 'COMMAND_FAILED', details: hasAppNotRunningRunnerCode },
+    verdicts: { retryable: false, connectRetry: false },
+  },
   {
     reason: 'flagged_retriable',
     match: { code: 'COMMAND_FAILED', details: hasRetriableFlag },
diff --git a/src/commands/schema/cli-help.ts b/src/commands/schema/cli-help.ts
index 9afafa45dd..d72fcd1264 100644
--- a/src/commands/schema/cli-help.ts
+++ b/src/commands/schema/cli-help.ts
@@ -699,6 +699,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 device skips the runner build, unless --shutdown was requested, the session was recording, the session held a device lease, or the device used a scoped (non-default) simulator set. 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.
   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.
   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).
diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md
index ad3175a063..516cc31350 100644
--- a/website/docs/docs/commands.md
+++ b/website/docs/docs/commands.md
@@ -835,6 +835,15 @@ state the session app was found in and why the runner activated it:
   distinction matters, spend a `snapshot -i` and read its disclosure.
 - The warning is appended; staleness, snapshot-quality, and occluding-system-surface warnings that
   came before it are never replaced.
+- **No read launches a stopped app.** A command that only observes the app (`snapshot`, `wait`,
+  `is`, `get`, a reading `find`) repairs a backgrounded session app, but never launches one that is
+  not running — and neither does an interaction's leading read: the viewport read a `gesture` starts
+  with, or the capture that resolves a selector `click`/`fill`. A bare launch would start the app
+  without the URL of a launch that SpringBoard is still holding behind an "Open in …?" confirmation.
+  A refused command answers `COMMAND_FAILED`, `details.runnerErrorCode: "APP_NOT_RUNNING"` and
+  `retriable: true`, and `wait` keeps polling through it. Answer the prompt with `alert accept`, or
+  relaunch with `open`. Only an interaction that mutates without a leading read — `press`, a
+  coordinate `fill`, `swipe`, `scroll`, a hardware key — still brings a stopped app up.
 
 ## Clipboard
 

From 9fac266b595bf4080724c1292e86cf41ccc9df64 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 24 Sep 2026 09:50:57 +0200
Subject: [PATCH 077/132] fix(ios): keep devicectl hints on physical install
 and delete the dead install paths (#2857)

* fix(ios): attach devicectl hints to physical install/uninstall failures

Physical iOS install and uninstall ran through devicectl without ever
consulting resolveIosDevicectlHint, so a failure lost the Developer
Mode, developer-disk-image, and pairing guidance every other devicectl
call site attaches. Route both failures through the same resolver.

Delete the install/uninstall/assertAppInstallationSupported members of
IosPhysicalDeviceControl and their XCTest rejection functions: nothing
calls them since #1758 moved physical install to deployment/runtime.ts.
Delete pushIosNotification, which deployment/runtime.ts's
pushAppleNotification replaced and only its own tests still called.
Repoint the C.push iOS-simulator coverage declaration at the
deployment-runtime contract test that now exercises simctl push.

* fix(ios): force allowFailure on devicectl install and push requests

installAppleApp's devicectl and simctl branches, and
pushAppleNotification's simctl request, omitted allowFailure. The host
command runner rejects a non-zero exit before assertAppleToolSuccess
runs, so its curated message and the devicectl Developer Mode hint
were dead code on those paths. uninstallAppleApp already set
allowFailure on both branches.

Route every appleTools.run request that feeds assertAppleToolSuccess
through a single runAppleTool helper that forces allowFailure: true,
so the invariant holds at every call site instead of per-branch.

* fix(ios): delete installCoreDeviceApp/uninstallCoreDeviceApp orphaned by #2785

Their only caller was the IosPhysicalDeviceControl install/uninstall
wiring, which the prior commit removed as dead. fallow dead-code
--unused-exports now flags both as unused; delete them and their
now-unused devicectl/config/apps-simctl imports.

* fix(ios): keep the exit-error shape when forcing allowFailure

runAppleTool forced allowFailure: true on every request so the
devicectl hint would attach, but that made the host command runner
return the failed result instead of rejecting it. The local
assertAppleToolSuccess then built COMMAND_FAILED details by hand,
without processExitError, so normalizeError no longer appended the
stderr excerpt to simulator install, physical install, and simulator
push failures, and their details lost cmd/args. Uninstall enrichment
was pre-existing dead code before this branch; the other three
requests regressed on it.

Fold assertAppleToolSuccess into runAppleTool: it still forces
allowFailure, but now also guards the result and throws through
execFailureDetails itself, so a result can't be tolerated without
also being checked. A caller passes the message and an optional hint
function; uninstall additionally passes a tolerate predicate for its
"already missing" case, which is the only one that still needs to
inspect a non-zero result before deciding to fail.

Mirror the same exit-error shape in the runtime.test.ts xcrunLikeRun
fake (cmd/args/processExitError via execFailureDetails, matching
createExitError) so it can catch a call site that drops the excerpt.
Add regression tests for simulator install and simulator push
failures, and assert the normalized message on the existing physical
install/uninstall Developer Mode tests, not just the hint.

* fix(ios): route runAppleTool's exit guard through requireExecSuccess

runAppleTool rebuilt the exec-failure shape locally instead of reusing
requireExecSuccess, so the two copies could drift (as the deleted
assertAppleToolSuccess already had). Widen requireExecSuccess to accept
any result shaped like HostCommandResult (exitCode: number | null) and
call it from runAppleTool, keeping one COMMAND_FAILED shape for every
allowFailure exec call site.

* fix(ios): reuse the install timeout and missing-app checks instead of re-declaring them

runtime.ts's runAppleTool consolidation left IOS_DEVICE_INSTALL_TIMEOUT_MS
(core/config.ts) and isMissingAppErrorOutput (core/apps-simctl.ts) with no
reader after the deleted CoreDevice install/uninstall paths were removed,
while runtime.ts kept a local 120_000 literal and a duplicate substring
check. Import and reuse both instead, and drop the issue-number references
from the surrounding doc comments.

* fix(ios): repoint the missing-app check at the export the base rename left behind

The rebase onto origin/main landed on top of the rename that deleted
core/apps-simctl.ts and moved isMissingAppErrorOutput into
physical-device-apps.ts as a private function. runtime.ts kept
importing from the deleted module, and the base's copy in
physical-device-apps.ts lost its only reader once this branch deletes
uninstallCoreDeviceApp, leaving an unused private declaration.

Export isMissingAppErrorOutput from physical-device-apps.ts and import
it there from runtime.ts, so the missing-app check has exactly one
definition and one caller: the uninstall tolerate predicate.

* test(ios): pin the reinstall uninstall-tolerance branch through deployApp

The uninstall tolerate predicate and its lowercasing had no test
driving createAppleAppDeploymentOperations, so removing either left
the whole suite green. Add a reinstall test, for both a physical
CoreDevice and a simulator, where uninstall exits non-zero with
mixed-case stderr ("ERROR: App Not Installed"): deployApp must still
resolve and the install request must have run.

* fix(ios): key the install hint on the devicectl tool, not the device kind
---
 packages/host-kit/src/internal/exec.ts        |  10 +-
 .../platform-apple/src/__tests__/app-error.ts |  18 +-
 .../src/core/__tests__/app-device-io.test.ts  |  69 -----
 .../src/core/__tests__/apps.test.ts           |  35 +--
 .../platform-apple/src/core/app-device-io.ts  |  27 --
 .../src/core/physical-device-apps.ts          |  38 +--
 .../src/core/physical-device-control.ts       |  27 --
 .../src/deployment/runtime.test.ts            | 260 +++++++++++++++++-
 .../platform-apple/src/deployment/runtime.ts  |  76 +++--
 .../command-coverage/declarations.ts          |   6 +-
 10 files changed, 334 insertions(+), 232 deletions(-)
 delete mode 100644 packages/platform-apple/src/core/__tests__/app-device-io.test.ts

diff --git a/packages/host-kit/src/internal/exec.ts b/packages/host-kit/src/internal/exec.ts
index 7f1f9f8356..d5f759c9d0 100644
--- a/packages/host-kit/src/internal/exec.ts
+++ b/packages/host-kit/src/internal/exec.ts
@@ -688,11 +688,13 @@ function createExitError(
  * than relying on the spawn layer to throw. `extra` accepts a function so
  * failure-only work (hint classification) is not paid on the success path.
  */
-export function requireExecSuccess(
-  result: ExecResult,
+export function requireExecSuccess<
+  R extends Pick<ExecResult, 'stdout' | 'stderr'> & Readonly<{ exitCode: number | null }>,
+>(
+  result: R,
   message: string,
-  extra?: Record<string, unknown> | ((result: ExecResult) => Record<string, unknown>),
-): ExecResult {
+  extra?: Record<string, unknown> | ((result: R) => Record<string, unknown>),
+): R {
   if (result.exitCode === 0) return result;
   throw new AppError(
     'COMMAND_FAILED',
diff --git a/packages/platform-apple/src/__tests__/app-error.ts b/packages/platform-apple/src/__tests__/app-error.ts
index 1a35896125..c7eb8aa3d6 100644
--- a/packages/platform-apple/src/__tests__/app-error.ts
+++ b/packages/platform-apple/src/__tests__/app-error.ts
@@ -1,7 +1,14 @@
 import assert from 'node:assert/strict';
-import { AppError, normalizeError } from '@agent-device/kernel/errors';
+import { AppError, defaultHintForCode, normalizeError } from '@agent-device/kernel/errors';
 
-type ExpectedAppError = { code: string; message?: RegExp; hint?: string | RegExp };
+type ExpectedAppError = {
+  code: string;
+  message?: RegExp;
+  /** Checked against `normalizeError(error).message`, e.g. the stderr excerpt a command failure appends. */
+  normalizedMessage?: RegExp;
+  /** `null` asserts the failure attached no hint of its own, so normalization falls back to the code default. */
+  hint?: string | RegExp | null;
+};
 
 function assertAppError(error: unknown, expected: ExpectedAppError): true {
   assert.ok(
@@ -10,7 +17,12 @@ function assertAppError(error: unknown, expected: ExpectedAppError): true {
   );
   assert.equal(error.code, expected.code);
   if (expected.message) assert.match(error.message, expected.message);
-  if (expected.hint !== undefined) {
+  if (expected.normalizedMessage) {
+    assert.match(normalizeError(error).message, expected.normalizedMessage);
+  }
+  if (expected.hint === null) {
+    assert.equal(normalizeError(error).hint, defaultHintForCode(error.code));
+  } else if (expected.hint !== undefined) {
     const { hint } = normalizeError(error);
     assert.ok(typeof hint === 'string', `expected a hint on ${error.code}, got ${String(hint)}`);
     if (typeof expected.hint === 'string') assert.equal(hint, expected.hint);
diff --git a/packages/platform-apple/src/core/__tests__/app-device-io.test.ts b/packages/platform-apple/src/core/__tests__/app-device-io.test.ts
deleted file mode 100644
index 374026368c..0000000000
--- a/packages/platform-apple/src/core/__tests__/app-device-io.test.ts
+++ /dev/null
@@ -1,69 +0,0 @@
-import { beforeEach, expect, test, vi } from 'vitest';
-import type { DeviceInfo } from '@agent-device/kernel/device';
-
-const { ensureBootedSimulator, runSimctl } = vi.hoisted(() => ({
-  ensureBootedSimulator: vi.fn(),
-  runSimctl: vi.fn(),
-}));
-
-vi.mock('../simulator.ts', () => ({
-  ensureBootedSimulator,
-  requireSimulatorDevice: (device: DeviceInfo) => {
-    if (device.kind !== 'simulator') throw new Error('simulator required');
-  },
-}));
-vi.mock('../simctl.ts', async (importOriginal) => ({
-  ...(await importOriginal<typeof import('../simctl.ts')>()),
-  runSimctlForDevice: runSimctl,
-}));
-
-import { pushIosNotification } from '../app-device-io.ts';
-
-const device: DeviceInfo = {
-  platform: 'apple',
-  appleOs: 'ios',
-  id: 'apple-push-abort',
-  name: 'Apple push abort',
-  kind: 'simulator',
-  target: 'mobile',
-  booted: true,
-};
-
-beforeEach(() => {
-  ensureBootedSimulator.mockReset();
-  ensureBootedSimulator.mockResolvedValue(undefined);
-  runSimctl.mockReset();
-});
-
-test('aborts an in-flight simctl push with the deployment binding signal', async () => {
-  const controller = new AbortController();
-  const aborted = new Error('request aborted');
-  runSimctl.mockImplementation(
-    async (_device: DeviceInfo, _args: string[], options: Readonly<{ signal?: AbortSignal }>) =>
-      await rejectWhenAborted(options.signal),
-  );
-
-  const pending = pushIosNotification(
-    device,
-    'com.example.app',
-    { aps: {} },
-    {
-      signal: controller.signal,
-    },
-  );
-  await vi.waitFor(() => expect(runSimctl).toHaveBeenCalledOnce());
-  expect(runSimctl).toHaveBeenCalledWith(
-    device,
-    ['push', device.id, 'com.example.app', expect.stringContaining('payload.apns')],
-    { signal: controller.signal },
-  );
-  controller.abort(aborted);
-
-  await expect(pending).rejects.toBe(aborted);
-});
-
-async function rejectWhenAborted(signal: AbortSignal | undefined): Promise<never> {
-  return await new Promise<never>((_resolve, reject) => {
-    signal?.addEventListener('abort', () => reject(signal.reason), { once: true });
-  });
-}
diff --git a/packages/platform-apple/src/core/__tests__/apps.test.ts b/packages/platform-apple/src/core/__tests__/apps.test.ts
index 1602dd0c50..4104358338 100644
--- a/packages/platform-apple/src/core/__tests__/apps.test.ts
+++ b/packages/platform-apple/src/core/__tests__/apps.test.ts
@@ -1,6 +1,6 @@
 import { beforeEach, test, vi } from 'vitest';
 import assert from 'node:assert/strict';
-import { promises as fs, readFileSync, writeFileSync } from 'node:fs';
+import { promises as fs, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { mkdtempForTest } from '../../__tests__/tmp-dir.ts';
 
@@ -26,7 +26,7 @@ const retryActual = await vi.importActual<typeof import('@agent-device/host-kit/
 const simulatorActual = await vi.importActual<typeof import('../simulator.ts')>('../simulator.ts');
 
 import { closeIosApp, openIosApp } from '../app-launch.ts';
-import { pushIosNotification, readIosClipboardText } from '../app-device-io.ts';
+import { readIosClipboardText } from '../app-device-io.ts';
 import { resolveIosApp, resolveIosSimulatorDeepLinkBundleId } from '../app-resolution.ts';
 import { screenshotIos } from '../screenshot.ts';
 import { withMockedMacOsHelper } from './macos-helper-test-utils.ts';
@@ -571,37 +571,6 @@ test('openIosApp with app and URL on iOS device launches app bundle with payload
   );
 });
 
-test('pushIosNotification uses simctl push with temporary payload file', async () => {
-  const device: DeviceInfo = {
-    platform: 'apple',
-    id: 'sim-1',
-    name: 'iPhone',
-    kind: 'simulator',
-    booted: true,
-  };
-
-  let capturedPayload: string | undefined;
-  await withFakeAppleTool(
-    (args) => {
-      if (isSimctlListDevices(args)) return BOOTED_SIM_LIST_JSON;
-      if (args[0] === 'simctl' && args[1] === 'push') {
-        capturedPayload = readFileSync(args[4] ?? '', 'utf8');
-        return '';
-      }
-      return '';
-    },
-    async ({ calls }) => {
-      await pushIosNotification(device, 'com.example.app', { aps: { alert: 'hello', badge: 4 } });
-      const pushCall = calls.find((args) => args[0] === 'simctl' && args[1] === 'push');
-      assert.ok(pushCall);
-      assert.equal(pushCall[2], 'sim-1');
-      assert.equal(pushCall[3], 'com.example.app');
-      assert.match(pushCall[4] ?? '', /payload\.apns$/);
-      assert.deepEqual(JSON.parse(capturedPayload ?? ''), { aps: { alert: 'hello', badge: 4 } });
-    },
-  );
-});
-
 test('resolveIosApp resolves app display name on iOS physical devices', async () => {
   const device: DeviceInfo = {
     platform: 'apple',
diff --git a/packages/platform-apple/src/core/app-device-io.ts b/packages/platform-apple/src/core/app-device-io.ts
index 42ea707965..56bf0bac73 100644
--- a/packages/platform-apple/src/core/app-device-io.ts
+++ b/packages/platform-apple/src/core/app-device-io.ts
@@ -1,11 +1,5 @@
-import path from 'node:path';
 import { isMacOs, type DeviceInfo } from '@agent-device/kernel/device';
 import { requireExecSuccess } from '@agent-device/host-kit/command';
-import {
-  makeHostTemporaryDirectory,
-  removeHostPath,
-  writeHostTextFile,
-} from '@agent-device/host-kit/host-file';
 import { ensureBootedSimulator, requireSimulatorDevice } from './simulator.ts';
 import { readMacOsClipboardText, writeMacOsClipboardText } from '../os/macos/apps.ts';
 import { runSimctlForDevice } from './simctl.ts';
@@ -38,24 +32,3 @@ export async function writeIosClipboardText(device: DeviceInfo, text: string): P
     'Failed to write iOS simulator clipboard',
   );
 }
-
-export async function pushIosNotification(
-  device: DeviceInfo,
-  bundleId: string,
-  payload: Record<string, unknown>,
-  options: Readonly<{ signal?: AbortSignal }> = {},
-): Promise<void> {
-  requireSimulatorDevice(device, 'push');
-  options.signal?.throwIfAborted();
-  await ensureBootedSimulator(device, { signal: options.signal });
-  const tempDir = await makeHostTemporaryDirectory('agent-device-ios-push-');
-  const payloadPath = path.join(tempDir, 'payload.apns');
-  try {
-    await writeHostTextFile(payloadPath, `${JSON.stringify(payload)}\n`);
-    await runSimctlForDevice(device, ['push', device.id, bundleId, payloadPath], {
-      signal: options.signal,
-    });
-  } finally {
-    await removeHostPath(tempDir);
-  }
-}
diff --git a/packages/platform-apple/src/core/physical-device-apps.ts b/packages/platform-apple/src/core/physical-device-apps.ts
index 256782d280..fd2df11594 100644
--- a/packages/platform-apple/src/core/physical-device-apps.ts
+++ b/packages/platform-apple/src/core/physical-device-apps.ts
@@ -1,10 +1,8 @@
 import type { AppsFilter } from '@agent-device/contracts/device';
 import type { DeviceInfo } from '@agent-device/kernel/device';
-import { IOS_DEVICE_INSTALL_TIMEOUT_MS } from './config.ts';
 import {
   listIosDeviceApps,
   resolveIosDeviceAppProcesses,
-  runIosDevicectl,
   terminateIosDeviceApp,
 } from './devicectl.ts';
 import type { IosAppInfo, IosDeviceAppProcesses } from './app-info.ts';
@@ -16,40 +14,6 @@ export async function listCoreDeviceApps(
   return await listIosDeviceApps(device, filter);
 }
 
-export async function installCoreDeviceApp(
-  device: DeviceInfo,
-  installablePath: string,
-  signal?: AbortSignal,
-): Promise<void> {
-  await runIosDevicectl(
-    ['device', 'install', 'app', '--device', device.id, installablePath],
-    {
-      action: 'install iOS app',
-      deviceId: device.id,
-    },
-    {
-      signal,
-      timeoutMs: IOS_DEVICE_INSTALL_TIMEOUT_MS,
-    },
-  );
-}
-
-export async function uninstallCoreDeviceApp(
-  device: DeviceInfo,
-  bundleId: string,
-  signal?: AbortSignal,
-): Promise<void> {
-  await runIosDevicectl(
-    ['device', 'uninstall', 'app', '--device', device.id, bundleId],
-    { action: `uninstall iOS app ${bundleId}`, deviceId: device.id },
-    {
-      signal,
-      tolerateOutput: (stdout, stderr) =>
-        isMissingAppErrorOutput(`${stdout}\n${stderr}`.toLowerCase()),
-    },
-  );
-}
-
 export async function terminateCoreDeviceApp(device: DeviceInfo, bundleId: string): Promise<void> {
   await terminateIosDeviceApp(device, bundleId);
 }
@@ -61,7 +25,7 @@ export async function resolveCoreDeviceAppProcesses(
   return await resolveIosDeviceAppProcesses(device, bundleId);
 }
 
-function isMissingAppErrorOutput(output: string): boolean {
+export function isMissingAppErrorOutput(output: string): boolean {
   return (
     output.includes('not installed') ||
     output.includes('not found') ||
diff --git a/packages/platform-apple/src/core/physical-device-control.ts b/packages/platform-apple/src/core/physical-device-control.ts
index a0feeecc14..9d174219c1 100644
--- a/packages/platform-apple/src/core/physical-device-control.ts
+++ b/packages/platform-apple/src/core/physical-device-control.ts
@@ -4,11 +4,9 @@ import { execFailureDetails } from '@agent-device/host-kit/command';
 import type { AppsFilter } from '@agent-device/contracts/device';
 import type { IosAppInfo, IosDeviceAppProcesses } from './app-info.ts';
 import {
-  installCoreDeviceApp,
   listCoreDeviceApps,
   resolveCoreDeviceAppProcesses,
   terminateCoreDeviceApp,
-  uninstallCoreDeviceApp,
 } from './physical-device-apps.ts';
 import {
   ensureCoreDeviceReady,
@@ -42,11 +40,8 @@ type IosPhysicalDeviceLaunchOptions = {
 };
 
 export type IosPhysicalDeviceControl = IosPhysicalDeviceRunnerControl & {
-  assertAppInstallationSupported(device: DeviceInfo): void;
   ensureReady(device: DeviceInfo, signal?: AbortSignal): Promise<void>;
   listApps(device: DeviceInfo, filter: AppsFilter): Promise<IosAppInfo[]>;
-  installApp(device: DeviceInfo, installablePath: string, signal?: AbortSignal): Promise<void>;
-  uninstallApp(device: DeviceInfo, bundleId: string, signal?: AbortSignal): Promise<void>;
   launchApp(
     device: DeviceInfo,
     bundleId: string,
@@ -77,11 +72,8 @@ export type IosPhysicalDeviceControl = IosPhysicalDeviceRunnerControl & {
 const CONTROLS: Record<IosPhysicalDeviceBackend, IosPhysicalDeviceControl> = {
   coredevice: {
     backend: 'coredevice',
-    assertAppInstallationSupported: () => {},
     ensureReady: ensureCoreDeviceReady,
     listApps: listCoreDeviceApps,
-    installApp: installCoreDeviceApp,
-    uninstallApp: uninstallCoreDeviceApp,
     launchApp: launchCoreDeviceApp,
     terminateApp: async (device, bundleId) => await terminateCoreDeviceApp(device, bundleId),
     resolveAppProcesses: resolveCoreDeviceAppProcesses,
@@ -94,11 +86,8 @@ const CONTROLS: Record<IosPhysicalDeviceBackend, IosPhysicalDeviceControl> = {
   },
   xctest: {
     backend: 'xctest',
-    assertAppInstallationSupported: assertXctestAppInstallationUnsupported,
     ensureReady: ensureXctestDeviceReady,
     listApps: rejectXctestAppInventory,
-    installApp: rejectXctestAppInstallation,
-    uninstallApp: rejectXctestAppInstallation,
     launchApp: launchXctestDeviceApp,
     terminateApp: terminateXctestDeviceApp,
     resolveAppProcesses: rejectXctestProcessLookup,
@@ -113,22 +102,6 @@ export function resolveIosPhysicalDeviceControl(device: DeviceInfo): IosPhysical
   return CONTROLS[device.iosPhysicalDeviceBackend === 'xctest' ? 'xctest' : 'coredevice'];
 }
 
-function assertXctestAppInstallationUnsupported(device: DeviceInfo): never {
-  throw new AppError(
-    'UNSUPPORTED_OPERATION',
-    'Installing apps is unavailable on this XCTest-backed physical iOS device.',
-    {
-      deviceId: device.id,
-      backend: 'xctest',
-      hint: 'Install the app with Xcode, then open it in agent-device by bundle ID.',
-    },
-  );
-}
-
-async function rejectXctestAppInstallation(device: DeviceInfo): Promise<never> {
-  return assertXctestAppInstallationUnsupported(device);
-}
-
 async function rejectXctestAppInventory(device: DeviceInfo): Promise<never> {
   throw new AppError(
     'UNSUPPORTED_OPERATION',
diff --git a/packages/platform-apple/src/deployment/runtime.test.ts b/packages/platform-apple/src/deployment/runtime.test.ts
index f477cd7954..e56a876049 100644
--- a/packages/platform-apple/src/deployment/runtime.test.ts
+++ b/packages/platform-apple/src/deployment/runtime.test.ts
@@ -1,9 +1,41 @@
 import { expect, test, vi } from 'vitest';
 import type { AppleAppDeploymentExecutor } from '@agent-device/contracts/app-deployment-runtime';
+import type {
+  AppleToolRequest,
+  HostCommandResult,
+} from '@agent-device/contracts/platform-runtime-host';
 import type { PlatformRuntimeHost } from '@agent-device/contracts/platform-runtime-operations';
 import type { DeviceInfo } from '@agent-device/kernel/device';
+import { AppError } from '@agent-device/kernel/errors';
+import { execFailureDetails } from '@agent-device/host-kit/command';
+import { assertRejectsAppError } from '../__tests__/app-error.ts';
 import { appleAppDeploymentFacts, createAppleAppDeploymentOperations } from './runtime.ts';
 
+/**
+ * Mirrors runXcrun's own contract (host-kit exec.ts): a non-zero exit rejects with the same
+ * `execFailureDetails` shape `createExitError` builds — `processExitError: true` plus `cmd` and
+ * `args` — and no hint, unless the request set `allowFailure`. A fake that throws a bare
+ * COMMAND_FAILED cannot catch a call site that forgot `allowFailure`, or one whose caller drops
+ * the stderr excerpt `normalizeError` would otherwise surface (#2785).
+ */
+function xcrunLikeRun(
+  respond: (
+    request: AppleToolRequest,
+  ) => Readonly<{ stdout: string; stderr: string; exitCode: number }>,
+) {
+  return vi.fn(async (request: AppleToolRequest): Promise<HostCommandResult> => {
+    const result = respond(request);
+    if (result.exitCode !== 0 && !request.allowFailure) {
+      throw new AppError(
+        'COMMAND_FAILED',
+        `xcrun exited with code ${result.exitCode}`,
+        execFailureDetails(result, { cmd: 'xcrun', args: [request.tool, ...request.args] }),
+      );
+    }
+    return result;
+  });
+}
+
 function appleDevice(overrides: Partial<DeviceInfo> = {}): DeviceInfo {
   return {
     platform: 'apple',
@@ -24,9 +56,21 @@ async function withoutInvalidatingAppResolutionCache<Result>(
   return await operation();
 }
 
+function bootedSimulatorListResult(
+  request: AppleToolRequest,
+): Readonly<{ stdout: string; stderr: string; exitCode: number }> {
+  return {
+    stdout: request.args.includes('list')
+      ? '{"devices":{"runtime":[{"udid":"apple-deployment-fact","state":"Booted"}]}}'
+      : '',
+    stderr: '',
+    exitCode: 0,
+  };
+}
+
 function deploymentHost(
   appleDeployment: AppleAppDeploymentExecutor,
-  run = vi.fn(async (request: { args: readonly string[] }) => ({
+  run = xcrunLikeRun((request) => ({
     stdout: request.args.includes('list')
       ? '{"devices":{"runtime":[{"udid":"apple-deployment-fact","state":"Booted"}]}}'
       : '',
@@ -262,6 +306,220 @@ test('exposes only fact-admitted Apple deployment operations', async () => {
   ).toEqual({});
 });
 
+test('physical iOS install failure surfaces the devicectl Developer Mode hint', async () => {
+  const prepareArtifact = vi.fn(async () => ({
+    installablePath: '/tmp/App.app',
+    bundleId: 'com.example.app',
+    appName: 'Example',
+    cleanup: vi.fn(async () => {}),
+  }));
+  const executor = {
+    prepareArtifact,
+    resolveAppBundleId: vi.fn(),
+    withInvalidatedAppResolutionCache: withoutInvalidatingAppResolutionCache,
+  } as AppleAppDeploymentExecutor;
+  const run = xcrunLikeRun((request) =>
+    request.args.includes('install')
+      ? {
+          stdout: '',
+          stderr: 'Unable to install "com.example.app": Developer Mode is disabled on this device.',
+          exitCode: 1,
+        }
+      : { stdout: '', stderr: '', exitCode: 0 },
+  );
+  const host = deploymentHost(executor, run);
+  const device = appleDevice({ kind: 'device', iosPhysicalDeviceBackend: 'coredevice' });
+  const operations = createAppleAppDeploymentOperations({
+    host,
+    device,
+    signal: new AbortController().signal,
+  });
+
+  await assertRejectsAppError(
+    async () =>
+      await operations.deployApp?.({
+        app: 'com.example.app',
+        appPath: '/tmp/App.app',
+        replaceExisting: false,
+      }),
+    {
+      code: 'COMMAND_FAILED',
+      hint: /Developer Mode/,
+      normalizedMessage: /Developer Mode is disabled on this device/,
+    },
+  );
+  expect(run.mock.calls.some(([request]) => request.args.includes('install'))).toBe(true);
+});
+
+test('simulator install failure surfaces the simctl stderr excerpt with no devicectl hint', async () => {
+  const prepareArtifact = vi.fn(async () => ({
+    installablePath: '/tmp/App.app',
+    bundleId: 'com.example.app',
+    appName: 'Example',
+    cleanup: vi.fn(async () => {}),
+  }));
+  const executor = {
+    prepareArtifact,
+    resolveAppBundleId: vi.fn(),
+    withInvalidatedAppResolutionCache: withoutInvalidatingAppResolutionCache,
+  } as AppleAppDeploymentExecutor;
+  const run = xcrunLikeRun((request) =>
+    request.args.includes('install')
+      ? {
+          stdout: '',
+          stderr: 'Failed to install the requested application',
+          exitCode: 1,
+        }
+      : bootedSimulatorListResult(request),
+  );
+  const host = deploymentHost(executor, run);
+  const device = appleDevice();
+  const operations = createAppleAppDeploymentOperations({
+    host,
+    device,
+    signal: new AbortController().signal,
+  });
+
+  await assertRejectsAppError(
+    async () =>
+      await operations.deployApp?.({
+        app: 'com.example.app',
+        appPath: '/tmp/App.app',
+        replaceExisting: false,
+      }),
+    {
+      code: 'COMMAND_FAILED',
+      normalizedMessage: /Failed to install the requested application/,
+      hint: null,
+    },
+  );
+  const [request] = run.mock.calls.find(([call]) => call.args.includes('install'))!;
+  expect(request.allowFailure).toBe(true);
+});
+
+test('simulator push failure surfaces the simctl stderr excerpt', async () => {
+  const executor = {
+    prepareArtifact: vi.fn(),
+    resolveAppBundleId: vi.fn(),
+    withInvalidatedAppResolutionCache: withoutInvalidatingAppResolutionCache,
+  } as AppleAppDeploymentExecutor;
+  const run = xcrunLikeRun((request) =>
+    request.args.includes('push')
+      ? {
+          stdout: '',
+          stderr: 'Invalid device state: Booted',
+          exitCode: 1,
+        }
+      : bootedSimulatorListResult(request),
+  );
+  const host = deploymentHost(executor, run);
+  const device = appleDevice();
+  const operations = createAppleAppDeploymentOperations({
+    host,
+    device,
+    signal: new AbortController().signal,
+  });
+
+  await assertRejectsAppError(
+    async () => await operations.sendPushNotification?.({ appId: 'com.example.app', payload: {} }),
+    {
+      code: 'COMMAND_FAILED',
+      normalizedMessage: /Invalid device state: Booted/,
+      hint: null,
+    },
+  );
+  const [request] = run.mock.calls.find(([call]) => call.args.includes('push'))!;
+  expect(request.allowFailure).toBe(true);
+});
+
+test('physical iOS uninstall failure surfaces the devicectl Developer Mode hint', async () => {
+  const resolveAppBundleId = vi.fn(async () => 'com.example.app');
+  const executor = {
+    prepareArtifact: vi.fn(),
+    resolveAppBundleId,
+    withInvalidatedAppResolutionCache: withoutInvalidatingAppResolutionCache,
+  } as AppleAppDeploymentExecutor;
+  const run = xcrunLikeRun((request) =>
+    request.args.includes('uninstall')
+      ? {
+          stdout: '',
+          stderr:
+            'Unable to uninstall "com.example.app": Developer Mode is disabled on this device.',
+          exitCode: 1,
+        }
+      : { stdout: '', stderr: '', exitCode: 0 },
+  );
+  const host = deploymentHost(executor, run);
+  const device = appleDevice({ kind: 'device', iosPhysicalDeviceBackend: 'coredevice' });
+  const operations = createAppleAppDeploymentOperations({
+    host,
+    device,
+    signal: new AbortController().signal,
+  });
+
+  await assertRejectsAppError(
+    async () =>
+      await operations.deployApp?.({
+        app: 'com.example.app',
+        appPath: '/tmp/replacement.app',
+        replaceExisting: true,
+      }),
+    {
+      code: 'COMMAND_FAILED',
+      hint: /Developer Mode/,
+      normalizedMessage: /Developer Mode is disabled on this device/,
+    },
+  );
+  expect(run.mock.calls.some(([request]) => request.args.includes('uninstall'))).toBe(true);
+});
+
+test.each([
+  [
+    'physical iOS CoreDevice',
+    appleDevice({ kind: 'device', iosPhysicalDeviceBackend: 'coredevice' }),
+  ],
+  ['iOS simulator', appleDevice()],
+] as const)(
+  'reinstall tolerates an already-missing %s uninstall with mixed-case stderr and still installs',
+  async (_name, device) => {
+    const resolveAppBundleId = vi.fn(async () => 'com.example.app');
+    const prepareArtifact = vi.fn(async () => ({
+      installablePath: '/tmp/App.app',
+      bundleId: 'com.example.app',
+      appName: 'Example',
+      cleanup: vi.fn(async () => {}),
+    }));
+    const executor = {
+      prepareArtifact,
+      resolveAppBundleId,
+      withInvalidatedAppResolutionCache: withoutInvalidatingAppResolutionCache,
+    } as AppleAppDeploymentExecutor;
+    const run = xcrunLikeRun((request) => {
+      if (request.args.includes('uninstall')) {
+        return { stdout: '', stderr: 'ERROR: App Not Installed', exitCode: 1 };
+      }
+      return bootedSimulatorListResult(request);
+    });
+    const host = deploymentHost(executor, run);
+    const operations = createAppleAppDeploymentOperations({
+      host,
+      device,
+      signal: new AbortController().signal,
+    });
+
+    await expect(
+      operations.deployApp?.({
+        app: 'com.example.app',
+        appPath: '/tmp/App.app',
+        replaceExisting: true,
+      }),
+    ).resolves.toMatchObject({ bundleId: 'com.example.app' });
+
+    expect(run.mock.calls.some(([request]) => request.args.includes('uninstall'))).toBe(true);
+    expect(run.mock.calls.some(([request]) => request.args.includes('install'))).toBe(true);
+  },
+);
+
 test('preserves Apple reinstall partial-failure ordering', async () => {
   const order: string[] = [];
   const resolveAppBundleId = vi.fn(async () => {
diff --git a/packages/platform-apple/src/deployment/runtime.ts b/packages/platform-apple/src/deployment/runtime.ts
index 394310eb70..65f9d27973 100644
--- a/packages/platform-apple/src/deployment/runtime.ts
+++ b/packages/platform-apple/src/deployment/runtime.ts
@@ -6,10 +6,18 @@ import type {
   MaterializeAppSourceInput,
   PushNotificationInput,
 } from '@agent-device/contracts/app-deployment-runtime';
+import type {
+  AppleToolRequest,
+  HostCommandResult,
+} from '@agent-device/contracts/platform-runtime-host';
 import type { PlatformRuntimeHost } from '@agent-device/contracts/platform-runtime-operations';
 import type { RuntimeOperationFact } from '@agent-device/contracts/platform-runtime';
 import { isIosFamily, type DeviceInfo } from '@agent-device/kernel/device';
 import { AppError } from '@agent-device/kernel/errors';
+import { requireExecSuccess } from '@agent-device/host-kit/command';
+import { isMissingAppErrorOutput } from '../core/physical-device-apps.ts';
+import { IOS_DEVICE_INSTALL_TIMEOUT_MS } from '../core/config.ts';
+import { IOS_DEVICECTL_DEFAULT_HINT, resolveIosDevicectlHint } from '../core/devicectl.ts';
 import { ensureAppleReady } from '../readiness/runtime.ts';
 import { scopeSimctlArgsForDevice } from '../core/simctl.ts';
 
@@ -135,7 +143,8 @@ async function installAppleApp(
   signal: AbortSignal,
 ): Promise<void> {
   await ensureAppleReady(host, device, signal);
-  const result = await host.appleTools.run(
+  await runAppleTool(
+    host,
     device.kind === 'simulator'
       ? {
           tool: 'simctl',
@@ -144,11 +153,11 @@ async function installAppleApp(
       : {
           tool: 'devicectl',
           args: ['device', 'install', 'app', '--device', device.id, installablePath],
-          timeoutMs: 120_000,
+          timeoutMs: IOS_DEVICE_INSTALL_TIMEOUT_MS,
         },
     signal,
+    'Apple app install failed',
   );
-  assertAppleToolSuccess(result, 'Apple app install failed');
 }
 
 async function uninstallAppleApp(
@@ -158,22 +167,24 @@ async function uninstallAppleApp(
   signal: AbortSignal,
 ): Promise<void> {
   await ensureAppleReady(host, device, signal);
-  const result = await host.appleTools.run(
+  await runAppleTool(
+    host,
     device.kind === 'simulator'
       ? {
           tool: 'simctl',
           args: scopeSimctlArgsForDevice(device, ['uninstall', device.id, bundleId]),
-          allowFailure: true,
         }
       : {
           tool: 'devicectl',
           args: ['device', 'uninstall', 'app', '--device', device.id, bundleId],
-          allowFailure: true,
         },
     signal,
+    `Apple app uninstall failed for ${bundleId}`,
+    {
+      tolerate: (result) =>
+        isMissingAppErrorOutput(`${result.stdout}\n${result.stderr}`.toLowerCase()),
+    },
   );
-  if (result.exitCode === 0 || isMissingAppOutput(`${result.stdout}\n${result.stderr}`)) return;
-  assertAppleToolSuccess(result, `Apple app uninstall failed for ${bundleId}`);
 }
 
 async function pushAppleNotification(
@@ -192,38 +203,47 @@ async function pushAppleNotification(
   });
   try {
     await payload.writeText(`${JSON.stringify(input.payload)}\n`);
-    const result = await host.appleTools.run(
+    await runAppleTool(
+      host,
       {
         tool: 'simctl',
         args: scopeSimctlArgsForDevice(device, ['push', device.id, input.appId, payload.path]),
       },
       signal,
+      'Apple push notification failed',
     );
-    assertAppleToolSuccess(result, 'Apple push notification failed');
   } finally {
     await payload[Symbol.asyncDispose]();
   }
 }
 
-function isMissingAppOutput(output: string): boolean {
-  const normalized = output.toLowerCase();
-  return (
-    normalized.includes('not installed') ||
-    normalized.includes('not found') ||
-    normalized.includes('no such file')
-  );
-}
-
-function assertAppleToolSuccess(
-  result: Readonly<{ stdout: string; stderr: string; exitCode: number | null }>,
+/**
+ * The one request path this module uses to run a tolerated Apple tool call: it forces
+ * `allowFailure`, then guards the result itself through `requireExecSuccess` so a non-zero
+ * exit always throws the same COMMAND_FAILED shape as every other exec call site, with the
+ * caller's curated message. A devicectl failure gets the same Developer Mode,
+ * developer-disk-image, and pairing hints the other devicectl call sites attach. `tolerate`
+ * lets a caller accept a specific non-zero result (uninstall's "already missing" case)
+ * without losing that guard for every other outcome.
+ */
+async function runAppleTool(
+  host: PlatformRuntimeHost,
+  request: Omit<AppleToolRequest, 'allowFailure'>,
+  signal: AbortSignal,
   message: string,
-): void {
-  if (result.exitCode === 0) return;
-  throw new AppError('COMMAND_FAILED', message, {
-    stdout: result.stdout,
-    stderr: result.stderr,
-    exitCode: result.exitCode,
-  });
+  options?: Readonly<{ tolerate?: (result: HostCommandResult) => boolean }>,
+): Promise<HostCommandResult> {
+  const result = await host.appleTools.run({ ...request, allowFailure: true }, signal);
+  if (options?.tolerate?.(result)) return result;
+  return requireExecSuccess(result, message, (failed) => ({
+    cmd: 'xcrun',
+    args: [request.tool, ...request.args],
+    ...(request.tool === 'devicectl'
+      ? {
+          hint: resolveIosDevicectlHint(failed.stdout, failed.stderr) ?? IOS_DEVICECTL_DEFAULT_HINT,
+        }
+      : {}),
+  }));
 }
 
 function appleDeployFact(device: DeviceInfo): RuntimeOperationFact {
diff --git a/test/integration/command-coverage/declarations.ts b/test/integration/command-coverage/declarations.ts
index 7495497e7a..b3adbb26c4 100644
--- a/test/integration/command-coverage/declarations.ts
+++ b/test/integration/command-coverage/declarations.ts
@@ -508,9 +508,9 @@ const COMMAND_COVERAGE_DECLARATIONS = {
       'typed broadcast extras are persisted by the fixture receiver and rendered after refresh',
     ),
     iosSimulator: iosSimulator.contract(
-      'packages/platform-apple/src/core/__tests__/apps.test.ts',
-      'pushIosNotification uses simctl push with temporary payload file',
-      'simctl push dispatch; fixture has no notification entitlement or UI oracle',
+      'packages/platform-apple/src/deployment/runtime.test.ts',
+      'exposes only fact-admitted Apple deployment operations',
+      'simctl push dispatch through the shared Apple deployment operations; fixture has no notification entitlement or UI oracle',
     ),
     macos: macos.contract(
       'packages/platform-apple/src/deployment/runtime.test.ts',

From 9dd537975f160d0b445d8cd9d99671648e8954d4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 24 Sep 2026 10:47:10 +0200
Subject: [PATCH 078/132] fix(ios-runner): return work that finished at the
 timeout boundary and bound recorder frame capture (#2837)

* fix(ios-runner): answer main-thread work that finished at the timeout boundary

runMainThreadWork threw MAIN_THREAD_TIMEOUT whenever its wait timed out,
even when the main-queue block finished between the wait and the lock
and had already stored its result. A tap that happened was then reported
as a timeout, and a daemon retry could repeat the gesture.

Work that is finished under the lock now returns or rethrows its stored
result like work that finished in time, and is not counted as abandoned.
Only work still unfinished under the lock is abandoned and throws the
timeout error. No timeout value changes.

Closes #2782

* fix(ios-runner): bound recorder frame capture through runMainThreadWork

A recording tick captured its frame with an unbounded DispatchQueue.main.sync
on the recorder queue. While the main thread was wedged the first tick
blocked the recorder queue, and the busy and wedged accounting never saw it.

Each tick after the bootstrap frame now hops to main through
runMainThreadWork with a timeout of one frame interval, on iOS and macOS.
A capture that times out drops the frame and counts as abandoned work; its
late result is discarded and never appended. While any abandoned main-thread
work is outstanding the tick is skipped, so the recorder keeps at most one
capture pending on main. The bootstrap frame is still taken on the calling
thread, and screenshots keep their on-main capture path.

Closes #2801

* docs(recording): note that the Apple runner drops frames it cannot capture in time

Refs #2801

* fix(ios-runner): keep recorder frames off a main thread that commands are using

A recorder tick is optional main-thread work. It now hops to main only
while no dispatched main-thread work is in flight or abandoned, checked
and enqueued under the same lock every dispatch enqueues under, so it
never queues behind a command's hop and never raises the occupancy that
the busy gate, the response stamp and the snapshot tier skip read.

The per-frame bound is a fixed one-second capture timeout instead of the
frame interval: a capture slower than the interval lowers the frame rate,
and only a capture that slow counts as abandoned main-thread work.

* fix(ios-runner): read in-flight work alone in the optional main-thread gate

Production marks a dispatch abandoned only while its block is still running on main, so
mainThreadWorkInFlightCount == 0 already implies abandonedMainThreadWorkCount == 0 and the second
term in runMainThreadWorkIfIdle's guard could never decide anything. Drop it and pin the gate to the
one counter that names main-thread occupancy.

* test(ios-runner): pin the optional main-thread gate across a real timeout and drain
---
 .../RunnerTests+CommandDispatch.swift         |   2 +-
 .../RunnerTests+MainThreadWork.swift          |  92 +++-
 .../RunnerTests+ScreenRecorder.swift          |  44 +-
 .../RunnerTests.swift                         |  10 +
 .../RunnerTests+MainThreadWorkTests.swift     | 205 ++++++++
 .../RunnerTests+RecordingTests.swift          | 438 +++++++++++++++++-
 website/docs/docs/commands.md                 |   1 +
 7 files changed, 769 insertions(+), 23 deletions(-)

diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandDispatch.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandDispatch.swift
index 7b75a4e23f..f58f712686 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandDispatch.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandDispatch.swift
@@ -358,7 +358,7 @@ extension RunnerTests {
           outputPath: resolvedOutPath,
           fps: command.fps.map { Int32($0) }
         )
-        try recorder.start { [weak self] in
+        try startRecording(recorder) { [weak self] in
           guard let self else { return .failure(.unresolvedScreen) }
           return self.captureRunnerFrameResult(app: activeApp)
         }
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+MainThreadWork.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+MainThreadWork.swift
index d624b10ba6..267f2b0b61 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+MainThreadWork.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+MainThreadWork.swift
@@ -12,7 +12,9 @@ import XCTest
 extension RunnerTests {
   /// Tracks one main-queue dispatch so the watchdog and the dispatched block can agree, under
   /// `mainThreadWorkLock`, on exactly one of: finished in time, or abandoned.
-  private final class MainThreadWorkState {
+  private final class MainThreadWorkState<T> {
+    let completed = DispatchSemaphore(value: 0)
+    var result: Result<T, Error>?
     var finished = false
     var abandoned = false
   }
@@ -62,24 +64,71 @@ extension RunnerTests {
     if Thread.isMainThread {
       return try work()
     }
-    var result: Result<T, Error>?
-    let semaphore = DispatchSemaphore(value: 0)
-    let workState = MainThreadWorkState()
+    mainThreadWorkLock.lock()
+    let state = enqueueMainThreadWorkLocked(operation, work)
+    mainThreadWorkLock.unlock()
+    return try awaitMainThreadWork(
+      state,
+      operation: operation,
+      timeout: timeout,
+      timeoutError: timeoutError,
+      onAbandoned: onAbandoned
+    )
+  }
+
+  /// Runs optional `work` like `runMainThreadWork`, but only while no other dispatched main-thread
+  /// work is in flight; otherwise it returns `nil` without dispatching. The check and the enqueue
+  /// happen under one hold of `mainThreadWorkLock`, the same lock every dispatch enqueues under, so
+  /// admitted work never waits in the main queue behind a command's hop. The in-flight count covers
+  /// abandoned work too: a block stays counted until it returns, and it marks itself abandoned in
+  /// the same window, so occupancy that outlived its slice is already declined here.
+  func runMainThreadWorkIfIdle<T>(
+    _ operation: String,
+    timeout: TimeInterval,
+    timeoutError: @escaping () -> Error,
+    _ work: @escaping () throws -> T
+  ) throws -> T? {
+    if Thread.isMainThread {
+      return nil
+    }
+    mainThreadWorkLock.lock()
+    guard mainThreadWorkInFlightCount == 0 else {
+      mainThreadWorkLock.unlock()
+      return nil
+    }
+    let state = enqueueMainThreadWorkLocked(operation, work)
+    mainThreadWorkLock.unlock()
+    return try awaitMainThreadWork(
+      state,
+      operation: operation,
+      timeout: timeout,
+      timeoutError: timeoutError,
+      onAbandoned: nil
+    )
+  }
+
+  private func enqueueMainThreadWorkLocked<T>(
+    _ operation: String,
+    _ work: @escaping () throws -> T
+  ) -> MainThreadWorkState<T> {
+    let state = MainThreadWorkState<T>()
+    mainThreadWorkInFlightCount += 1
     DispatchQueue.main.async {
       do {
-        result = .success(try work())
+        state.result = .success(try work())
       } catch {
-        result = .failure(error)
+        state.result = .failure(error)
       }
       self.mainThreadWorkLock.lock()
-      let abandoned = workState.abandoned
+      self.mainThreadWorkInFlightCount -= 1
+      let abandoned = state.abandoned
       if abandoned {
         self.abandonedMainThreadWorkCount -= 1
         if self.abandonedMainThreadWorkCount == 0 {
           self.abandonedMainThreadWorkSince = nil
         }
       } else {
-        workState.finished = true
+        state.finished = true
       }
       let allDrained = abandoned && self.abandonedMainThreadWorkCount == 0
       self.mainThreadWorkLock.unlock()
@@ -89,14 +138,29 @@ extension RunnerTests {
           NSLog("AGENT_DEVICE_RUNNER_ABANDONED_WORK_DRAINED")
         }
       }
-      semaphore.signal()
+      state.completed.signal()
     }
-    let waitResult = semaphore.wait(timeout: .now() + timeout)
+    return state
+  }
+
+  private func awaitMainThreadWork<T>(
+    _ state: MainThreadWorkState<T>,
+    operation: String,
+    timeout: TimeInterval,
+    timeoutError: @escaping () -> Error,
+    onAbandoned: (() -> Void)?
+  ) throws -> T {
+    let waitResult = state.completed.wait(timeout: .now() + timeout)
     if waitResult == .timedOut {
+      #if AGENT_DEVICE_RUNNER_UNIT_TESTS
+      mainThreadWorkTimedOutForTesting?()
+      #endif
+      // Work that finished before the lock was taken already stored its result: it is answered
+      // like work that finished in time, so an action that happened is never reported as a timeout.
       mainThreadWorkLock.lock()
-      let abandoned = !workState.finished
+      let abandoned = !state.finished
       if abandoned {
-        workState.abandoned = true
+        state.abandoned = true
         abandonedMainThreadWorkCount += 1
         if abandonedMainThreadWorkSince == nil {
           abandonedMainThreadWorkSince = Date()
@@ -110,10 +174,10 @@ extension RunnerTests {
           timeout
         )
         onAbandoned?()
+        throw timeoutError()
       }
-      throw timeoutError()
     }
-    switch result {
+    switch state.result {
     case .success(let value):
       return value
     case .failure(let error):
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+ScreenRecorder.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+ScreenRecorder.swift
index a7e13154fe..c70b0e3228 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+ScreenRecorder.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+ScreenRecorder.swift
@@ -24,14 +24,20 @@ extension RunnerTests {
     private var isStopping = false
     private var startedSession = false
     private var startError: Error?
+    #if AGENT_DEVICE_RUNNER_UNIT_TESTS
+    private var appendedFramesForTesting: [RunnerImage] = []
+    #endif
 
     init(outputPath: String, fps: Int32?) {
       self.outputPath = outputPath
       self.fps = fps
     }
 
+    /// `bootstrap` must produce the frame that sizes the writer and runs on the caller's thread.
+    /// `frame` answers each tick with an image, or `nil` to drop the tick.
     func start(
-      capture: @escaping () -> Result<CapturedAppScreen, RunnerAppScreenCaptureFailure>
+      bootstrap: @escaping () -> Result<CapturedAppScreen, RunnerAppScreenCaptureFailure>,
+      frame: @escaping () -> RunnerImage?
     ) throws {
       let url = URL(fileURLWithPath: outputPath)
       let directory = url.deletingLastPathComponent()
@@ -49,7 +55,7 @@ extension RunnerTests {
       var lastFailure: RunnerAppScreenCaptureFailure?
       let bootstrapDeadline = Date().addingTimeInterval(2.0)
       while Date() < bootstrapDeadline {
-        switch capture() {
+        switch bootstrap() {
         case .success(let captured):
           bootstrapImage = captured.image
           dimensions = CGSize(width: captured.pixelWidth, height: captured.pixelHeight)
@@ -129,8 +135,8 @@ extension RunnerTests {
       timer.setEventHandler { [weak self] in
         guard let self else { return }
         if self.shouldStop() { return }
-        guard case .success(let captured) = capture() else { return }
-        self.append(image: captured.image)
+        guard let image = frame() else { return }
+        self.append(image: image)
       }
       self.timer = timer
       timer.resume()
@@ -227,6 +233,9 @@ extension RunnerTests {
         return
       }
       lastTimestampValue = timestampValue
+      #if AGENT_DEVICE_RUNNER_UNIT_TESTS
+      appendedFramesForTesting.append(image)
+      #endif
     }
 
     private func timestampCandidateValue(for nowUptime: TimeInterval) -> Int64 {
@@ -285,6 +294,27 @@ extension RunnerTests {
 }
 
 extension RunnerTests {
+  /// Starts `recorder` on the frames `capture` produces. The bootstrap frame is taken on the calling
+  /// thread, which is main for `record start`. Each later tick is optional work: it hops to main only
+  /// while no other main-thread work is in flight, so it never queues behind a command.
+  /// A capture still running after `recordingFrameCaptureTimeout` is abandoned and its frame dropped;
+  /// its late result is never returned.
+  func startRecording(
+    _ recorder: ScreenRecorder,
+    capture: @escaping () -> Result<CapturedAppScreen, RunnerAppScreenCaptureFailure>
+  ) throws {
+    try recorder.start(bootstrap: capture) { [weak self] in
+      guard let self else { return nil }
+      return try? self.runMainThreadWorkIfIdle(
+        "recording_frame",
+        timeout: self.recordingFrameCaptureTimeout,
+        timeoutError: self.mainThreadExecutionTimeoutError
+      ) {
+        try capture().get().image
+      }
+    }
+  }
+
   /// The error a `record start` bootstrap raises when no initial frame arrived. On iOS the last capture
   /// refusal (if any) is the honest reason and travels as its own typed code; only when nothing
   /// refused — a macOS host capture, or a deadline that elapsed before any answer — does it fall back
@@ -319,5 +349,11 @@ extension RunnerTests.ScreenRecorder {
     lastTimestampValue = allocatedTimestamp
     return allocatedTimestamp
   }
+
+  func appendedFrameSnapshotForTesting() -> [RunnerImage] {
+    lock.lock()
+    defer { lock.unlock() }
+    return appendedFramesForTesting
+  }
 }
 #endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift
index 19a55659bc..725261ff2a 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift
@@ -79,6 +79,10 @@ final class RunnerTests: XCTestCase {
   let xctestIdleKeepaliveInterval: TimeInterval = 60.0
   let minRecordingFps = 1
   let maxRecordingFps = 120
+  // A recorder frame still capturing on main after this long is abandoned and dropped. It bounds a
+  // screenshot round trip, not the frame interval: a capture slower than the interval lowers the
+  // frame rate, and only a capture this slow counts as main-thread occupancy.
+  let recordingFrameCaptureTimeout: TimeInterval = 1
   var needsPostSnapshotInteractionDelay = false
   // Per-command markers that restate a fact of the bound target (the fast app guard, the
   // synthesized gesture policy per gesture kind) write only when that fact changes; otherwise a
@@ -106,6 +110,9 @@ final class RunnerTests: XCTestCase {
   // and post-capture bookkeeping stays off main (#1105/#1244).
   let mainThreadWorkLock = NSLock()
   var abandonedMainThreadWorkCount = 0
+  // Dispatched main-queue work that has not finished yet, abandoned or not. Only optional work
+  // reads it, to stay off a main thread that commands are using; occupancy readers do not.
+  var mainThreadWorkInFlightCount = 0
   var abandonedMainThreadWorkSince: Date?
   // Past this age the runner stops claiming "busy, retry soon" and reports itself wedged so
   // the daemon recycles it — the only cure once the main thread is stuck for good.
@@ -201,6 +208,9 @@ final class RunnerTests: XCTestCase {
   var blockingSystemModalPresenceOverrideForTesting: Bool?
   var alertResolutionOverrideForTesting: ((Date) -> RunnerAlert?)?
   var alertButtonHittabilityProbeOverrideForTesting: ((Date) -> Bool)?
+  // Runs on the waiting thread after `runMainThreadWork`'s wait timed out and before it takes the
+  // lock that decides between finished and abandoned, so a test can finish the work in that window.
+  var mainThreadWorkTimedOutForTesting: (() -> Void)?
   #endif
   // Observability for the record(_:) suppression below: how many AX-broken-screen snapshot
   // issues this session muted, so wedge investigations see the volume without grepping logs.
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+MainThreadWorkTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+MainThreadWorkTests.swift
index f98e37e7a8..3a292bff9e 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+MainThreadWorkTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+MainThreadWorkTests.swift
@@ -89,5 +89,210 @@ extension RunnerTests {
       return XCTFail("expected the runner idle once the abandoned work drained")
     }
   }
+
+  func testRunMainThreadWorkReturnsWorkThatFinishedAtTheTimeoutBoundary() {
+    let outcome = runMainThreadWorkFinishingAtTheTimeoutBoundary { 42 }
+
+    XCTAssertNil(outcome.error, "work that finished before the lock must not read as a timeout")
+    XCTAssertEqual(outcome.value, 42)
+    XCTAssertEqual(outcome.abandonedCount, 0)
+    XCTAssertEqual(outcome.onAbandonedCalls, 0)
+  }
+
+  func testRunMainThreadWorkRethrowsWorkThatFailedAtTheTimeoutBoundary() {
+    let outcome = runMainThreadWorkFinishingAtTheTimeoutBoundary { () throws -> Int in
+      throw NSError(domain: "agent-device.runner.tests", code: 7)
+    }
+
+    XCTAssertNil(outcome.value)
+    XCTAssertEqual((outcome.error as NSError?)?.domain, "agent-device.runner.tests")
+    XCTAssertEqual((outcome.error as NSError?)?.code, 7)
+    XCTAssertEqual(outcome.abandonedCount, 0)
+    XCTAssertEqual(outcome.onAbandonedCalls, 0)
+  }
+
+  func testRunMainThreadWorkIfIdleDeclinesWhileOtherWorkIsInFlight() {
+    final class Outcome {
+      var offeredWhileInFlight = false
+      var whileInFlight: Bool?
+      var ranWhileInFlight = false
+      var whenIdle: Bool?
+      var error: Error?
+    }
+    let outcome = Outcome()
+    let releaseCommand = DispatchSemaphore(value: 0)
+    let commandEntered = DispatchSemaphore(value: 0)
+    let finished = expectation(description: "optional work was offered during and after the command")
+
+    DispatchQueue(label: "agent-device.runner.tests.in-flight-command").async {
+      _ = try? self.runMainThreadWork(
+        "command_execution",
+        timeout: 5,
+        timeoutError: self.mainThreadExecutionTimeoutError
+      ) {
+        commandEntered.signal()
+        _ = releaseCommand.wait(timeout: .now() + 3)
+      }
+    }
+    DispatchQueue(label: "agent-device.runner.tests.optional-work").async {
+      defer { finished.fulfill() }
+      guard commandEntered.wait(timeout: .now() + 3) == .success else { return }
+      do {
+        outcome.whileInFlight = try self.runMainThreadWorkIfIdle(
+          "recording_frame",
+          timeout: 5,
+          timeoutError: self.mainThreadExecutionTimeoutError
+        ) { () -> Bool in
+          outcome.ranWhileInFlight = true
+          return true
+        }
+        outcome.offeredWhileInFlight = true
+      } catch {
+        outcome.error = error
+      }
+      releaseCommand.signal()
+      let idleDeadline = Date().addingTimeInterval(3)
+      while Date() < idleDeadline {
+        self.mainThreadWorkLock.lock()
+        let inFlight = self.mainThreadWorkInFlightCount
+        self.mainThreadWorkLock.unlock()
+        if inFlight == 0 { break }
+        usleep(2_000)
+      }
+      do {
+        outcome.whenIdle = try self.runMainThreadWorkIfIdle(
+          "recording_frame",
+          timeout: 5,
+          timeoutError: self.mainThreadExecutionTimeoutError
+        ) {
+          Thread.isMainThread
+        }
+      } catch {
+        outcome.error = error
+      }
+    }
+
+    wait(for: [finished], timeout: 10)
+    XCTAssertNil(outcome.error)
+    XCTAssertTrue(outcome.offeredWhileInFlight)
+    XCTAssertNil(outcome.whileInFlight, "optional work declines while a hop is in flight")
+    XCTAssertFalse(outcome.ranWhileInFlight, "declined work is never dispatched")
+    XCTAssertEqual(outcome.whenIdle, true, "optional work runs on main once main is idle")
+    XCTAssertFalse(hasAbandonedMainThreadWork())
+  }
+
+  func testRunMainThreadWorkIfIdleDeclinesAbandonedWorkUntilItDrains() {
+    final class Outcome {
+      var abandonedCount = 0
+      var inFlightCount = 0
+      var offeredWhileAbandoned = false
+      var whileAbandoned: Bool?
+      var ranWhileAbandoned = false
+      var afterDrain: Bool?
+      var error: Error?
+    }
+    let outcome = Outcome()
+    let releaseWork = DispatchSemaphore(value: 0)
+    let finished = expectation(description: "optional work was offered while abandoned and after drain")
+
+    DispatchQueue(label: "agent-device.runner.tests.abandoned-then-drained").async {
+      defer { finished.fulfill() }
+      _ = try? self.runMainThreadWork(
+        "command_execution",
+        timeout: 0,
+        timeoutError: self.mainThreadExecutionTimeoutError
+      ) {
+        _ = releaseWork.wait(timeout: .now() + 3)
+      }
+      self.mainThreadWorkLock.lock()
+      outcome.abandonedCount = self.abandonedMainThreadWorkCount
+      outcome.inFlightCount = self.mainThreadWorkInFlightCount
+      self.mainThreadWorkLock.unlock()
+      do {
+        outcome.whileAbandoned = try self.runMainThreadWorkIfIdle(
+          "recording_frame",
+          timeout: 5,
+          timeoutError: self.mainThreadExecutionTimeoutError
+        ) { () -> Bool in
+          outcome.ranWhileAbandoned = true
+          return true
+        }
+        outcome.offeredWhileAbandoned = true
+      } catch {
+        outcome.error = error
+      }
+      releaseWork.signal()
+      let drainDeadline = Date().addingTimeInterval(3)
+      while self.hasAbandonedMainThreadWork(), Date() < drainDeadline {
+        usleep(2_000)
+      }
+      do {
+        outcome.afterDrain = try self.runMainThreadWorkIfIdle(
+          "recording_frame",
+          timeout: 5,
+          timeoutError: self.mainThreadExecutionTimeoutError
+        ) {
+          Thread.isMainThread
+        }
+      } catch {
+        outcome.error = error
+      }
+    }
+
+    wait(for: [finished], timeout: 10)
+    XCTAssertNil(outcome.error)
+    XCTAssertEqual(outcome.abandonedCount, 1)
+    XCTAssertEqual(outcome.inFlightCount, 1, "abandoned work stays counted in flight until it returns")
+    XCTAssertTrue(outcome.offeredWhileAbandoned)
+    XCTAssertNil(outcome.whileAbandoned, "optional work declines while abandoned work holds main")
+    XCTAssertFalse(outcome.ranWhileAbandoned, "declined work is never dispatched")
+    XCTAssertEqual(outcome.afterDrain, true, "optional work runs on main once abandoned work drained")
+    XCTAssertFalse(hasAbandonedMainThreadWork())
+  }
+
+  private final class BoundaryOutcome {
+    var value: Int?
+    var error: Error?
+    var abandonedCount: Int?
+    var onAbandonedCalls = 0
+  }
+
+  /// Times the wait out immediately, then lets the work finish before the watchdog takes the lock:
+  /// the seam releases the blocked work and waits for the serial main queue to run past it.
+  private func runMainThreadWorkFinishingAtTheTimeoutBoundary(
+    _ produce: @escaping () throws -> Int
+  ) -> BoundaryOutcome {
+    let outcome = BoundaryOutcome()
+    let releaseWork = DispatchSemaphore(value: 0)
+    let finished = expectation(description: "off-main caller finished")
+    mainThreadWorkTimedOutForTesting = {
+      releaseWork.signal()
+      DispatchQueue.main.sync {}
+    }
+    defer { mainThreadWorkTimedOutForTesting = nil }
+
+    DispatchQueue(label: "agent-device.runner.tests.timeout-boundary").async {
+      do {
+        outcome.value = try self.runMainThreadWork(
+          "command_execution",
+          timeout: 0,
+          timeoutError: self.mainThreadExecutionTimeoutError,
+          onAbandoned: { outcome.onAbandonedCalls += 1 }
+        ) {
+          _ = releaseWork.wait(timeout: .now() + 2)
+          return try produce()
+        }
+      } catch {
+        outcome.error = error
+      }
+      self.mainThreadWorkLock.lock()
+      outcome.abandonedCount = self.abandonedMainThreadWorkCount
+      self.mainThreadWorkLock.unlock()
+      finished.fulfill()
+    }
+
+    wait(for: [finished], timeout: 3)
+    return outcome
+  }
 }
 #endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+RecordingTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+RecordingTests.swift
index ce8bd2c2c5..0c97926342 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+RecordingTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+RecordingTests.swift
@@ -1,4 +1,9 @@
 import XCTest
+#if canImport(UIKit)
+import UIKit
+#elseif canImport(AppKit)
+import AppKit
+#endif
 
 extension RunnerTests {
 #if AGENT_DEVICE_RUNNER_UNIT_TESTS
@@ -76,10 +81,13 @@ extension RunnerTests {
     var captureCalls = 0
     var thrown: Error?
     XCTAssertThrowsError(
-      try recorder.start(capture: {
-        captureCalls += 1
-        return .failure(.unresolvedWindow)
-      })
+      try recorder.start(
+        bootstrap: {
+          captureCalls += 1
+          return .failure(.unresolvedWindow)
+        },
+        frame: { nil }
+      )
     ) { error in
       thrown = error
       XCTAssertEqual(
@@ -96,3 +104,425 @@ extension RunnerTests {
   }
 }
 #endif
+
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS
+/// Frames for a recording test. Every capture draws a new image, so an appended frame is identified
+/// by instance, and holds the calling thread for `captureDelay` like a screenshot round trip. An
+/// armed wedge makes the next capture block the main thread until released, and remembers the image
+/// that capture will hand back late.
+private final class RecordingFrameSource {
+  static let side = 128
+  private let captureDelay: TimeInterval
+  private let lock = NSLock()
+  private var wedgeArmed = false
+  private var wedgedImage: RunnerImage?
+  let wedgeEntered = DispatchSemaphore(value: 0)
+  let releaseWedge = DispatchSemaphore(value: 0)
+
+  init(captureDelay: TimeInterval = 0) {
+    self.captureDelay = captureDelay
+  }
+
+  var lateImage: RunnerImage? {
+    lock.lock()
+    defer { lock.unlock() }
+    return wedgedImage
+  }
+
+  func armWedge() {
+    lock.lock()
+    wedgeArmed = true
+    lock.unlock()
+  }
+
+  func capture() -> Result<CapturedAppScreen, RunnerAppScreenCaptureFailure> {
+    if captureDelay > 0 {
+      Thread.sleep(forTimeInterval: captureDelay)
+    }
+    let image = Self.makeImage()
+    lock.lock()
+    let wedge = wedgeArmed
+    wedgeArmed = false
+    if wedge {
+      wedgedImage = image
+    }
+    lock.unlock()
+    if wedge {
+      wedgeEntered.signal()
+      _ = releaseWedge.wait(timeout: .now() + 10)
+    }
+    return .success(
+      CapturedAppScreen(
+        image: image,
+        displayID: 0,
+        pixelWidth: Self.side,
+        pixelHeight: Self.side,
+        pixelsPerPoint: 1
+      )
+    )
+  }
+
+  private static func makeImage() -> RunnerImage {
+    let context = CGContext(
+      data: nil,
+      width: side,
+      height: side,
+      bitsPerComponent: 8,
+      bytesPerRow: 0,
+      space: CGColorSpaceCreateDeviceRGB(),
+      bitmapInfo: CGImageAlphaInfo.noneSkipFirst.rawValue
+    )!
+    context.setFillColor(red: 0, green: 0.4, blue: 1, alpha: 1)
+    context.fill(CGRect(x: 0, y: 0, width: side, height: side))
+    let cgImage = context.makeImage()!
+    #if canImport(UIKit)
+    return UIImage(cgImage: cgImage)
+    #else
+    return NSImage(cgImage: cgImage, size: NSSize(width: side, height: side))
+    #endif
+  }
+}
+
+/// Samples, off main, the readers that commands consult for main-thread occupancy until stopped.
+private final class MainThreadOccupancySampler {
+  private let lock = NSLock()
+  private var stopped = false
+  private let done = DispatchSemaphore(value: 0)
+  private(set) var sampled = false
+  private(set) var sawBusy = false
+  private(set) var sawAbandoned = false
+  private(set) var sawXCTestTierSkip = false
+
+  init(runner: RunnerTests) {
+    DispatchQueue(label: "agent-device.runner.tests.occupancy-sampler").async {
+      defer { self.done.signal() }
+      while !self.isStopped {
+        let busy = runner.currentMainThreadBusyState().reportsMainThreadBusy
+        let abandoned = runner.hasAbandonedMainThreadWork()
+        let tierSkip = runner.shouldSkipSnapshotBackendForAbandonedMainThreadWork(.recursiveTree)
+        self.lock.lock()
+        self.sampled = true
+        self.sawBusy = self.sawBusy || busy
+        self.sawAbandoned = self.sawAbandoned || abandoned
+        self.sawXCTestTierSkip = self.sawXCTestTierSkip || tierSkip
+        self.lock.unlock()
+        usleep(2_000)
+      }
+    }
+  }
+
+  private var isStopped: Bool {
+    lock.lock()
+    defer { lock.unlock() }
+    return stopped
+  }
+
+  func stop() {
+    lock.lock()
+    stopped = true
+    lock.unlock()
+    _ = done.wait(timeout: .now() + 2)
+  }
+}
+
+extension RunnerTests {
+  func testRecordingFrameTimeoutDropsTheFrameAndResumesOnceTheWorkDrains() throws {
+    let source = RecordingFrameSource()
+    let recorder = ScreenRecorder(outputPath: recordingTestOutputPath(), fps: 10)
+    try startRecording(recorder, capture: source.capture)
+    defer { try? recorder.stop() }
+    XCTAssertTrue(pumpMainThread(until: { recorder.appendedFrameSnapshotForTesting().count >= 3 }))
+
+    final class Observation {
+      var abandonedWhileWedged: Int?
+      var framesWhileWedged: Int?
+      var secondsToAbandon: TimeInterval?
+    }
+    let observation = Observation()
+    let observed = expectation(description: "the wedged frame was abandoned and released")
+    source.armWedge()
+    DispatchQueue(label: "agent-device.runner.tests.recording-timeout").async {
+      defer {
+        source.releaseWedge.signal()
+        observed.fulfill()
+      }
+      guard source.wedgeEntered.wait(timeout: .now() + 3) == .success else { return }
+      let enteredAt = Date()
+      guard self.waitOffMain(until: { self.hasAbandonedMainThreadWork() }) else { return }
+      observation.secondsToAbandon = Date().timeIntervalSince(enteredAt)
+      self.mainThreadWorkLock.lock()
+      observation.abandonedWhileWedged = self.abandonedMainThreadWorkCount
+      self.mainThreadWorkLock.unlock()
+      observation.framesWhileWedged = recorder.appendedFrameSnapshotForTesting().count
+    }
+    wait(for: [observed], timeout: 15)
+
+    let framesAtRelease = observation.framesWhileWedged ?? 0
+    XCTAssertTrue(
+      pumpMainThread(until: {
+        !self.hasAbandonedMainThreadWork()
+          && recorder.appendedFrameSnapshotForTesting().count >= framesAtRelease + 2
+      }),
+      "the abandoned capture drains and the recorder appends frames again"
+    )
+    XCTAssertEqual(observation.abandonedWhileWedged, 1, "the timed-out frame counts as abandoned")
+    XCTAssertLessThan(
+      observation.secondsToAbandon ?? .infinity,
+      recordingFrameCaptureTimeout + 1,
+      "a frame is bounded by the recording capture timeout, not the command watchdog"
+    )
+    let lateImage = try XCTUnwrap(source.lateImage)
+    XCTAssertFalse(
+      recorder.appendedFrameSnapshotForTesting().contains { $0 === lateImage },
+      "the late result of the abandoned capture is never appended"
+    )
+  }
+
+  func testRecordingPersistentWedgeKeepsOneCaptureQueuedOnMain() throws {
+    let source = RecordingFrameSource()
+    let recorder = ScreenRecorder(outputPath: recordingTestOutputPath(), fps: 20)
+    try startRecording(recorder, capture: source.capture)
+    defer { try? recorder.stop() }
+    XCTAssertTrue(pumpMainThread(until: { recorder.appendedFrameSnapshotForTesting().count >= 2 }))
+
+    final class Observation {
+      var maxAbandoned = 0
+      var maxInFlight = 0
+    }
+    let observation = Observation()
+    let observed = expectation(description: "the wedge was held for many ticks")
+    source.armWedge()
+    DispatchQueue(label: "agent-device.runner.tests.recording-wedge").async {
+      defer {
+        source.releaseWedge.signal()
+        observed.fulfill()
+      }
+      guard source.wedgeEntered.wait(timeout: .now() + 3) == .success else { return }
+      let holdUntil = Date().addingTimeInterval(self.recordingFrameCaptureTimeout * 2.5)
+      while Date() < holdUntil {
+        self.mainThreadWorkLock.lock()
+        observation.maxAbandoned = max(observation.maxAbandoned, self.abandonedMainThreadWorkCount)
+        observation.maxInFlight = max(observation.maxInFlight, self.mainThreadWorkInFlightCount)
+        self.mainThreadWorkLock.unlock()
+        usleep(10_000)
+      }
+    }
+    wait(for: [observed], timeout: 15)
+    XCTAssertTrue(pumpMainThread(until: { !self.hasAbandonedMainThreadWork() }))
+
+    XCTAssertEqual(
+      observation.maxAbandoned,
+      1,
+      "every tick against a wedged main thread leaves one recorder capture pending, not one per tick"
+    )
+    XCTAssertEqual(observation.maxInFlight, 1, "skipped ticks dispatch nothing to main")
+  }
+
+  func testRecordingStopDuringATimedOutCaptureAppendsNoLateFrame() throws {
+    let source = RecordingFrameSource()
+    let recorder = ScreenRecorder(outputPath: recordingTestOutputPath(), fps: 10)
+    try startRecording(recorder, capture: source.capture)
+    XCTAssertTrue(pumpMainThread(until: { recorder.appendedFrameSnapshotForTesting().count >= 2 }))
+
+    final class Observation {
+      var stopError: Error?
+      var stopReturnedWhileWedged = false
+      var framesAtStop: Int?
+    }
+    let observation = Observation()
+    let observed = expectation(description: "stop returned during the timed-out capture")
+    source.armWedge()
+    DispatchQueue(label: "agent-device.runner.tests.recording-stop").async {
+      defer {
+        source.releaseWedge.signal()
+        observed.fulfill()
+      }
+      guard source.wedgeEntered.wait(timeout: .now() + 3) == .success else { return }
+      guard self.waitOffMain(until: { self.hasAbandonedMainThreadWork() }) else { return }
+      do {
+        try recorder.stop()
+      } catch {
+        observation.stopError = error
+      }
+      observation.stopReturnedWhileWedged = self.hasAbandonedMainThreadWork()
+      observation.framesAtStop = recorder.appendedFrameSnapshotForTesting().count
+    }
+    wait(for: [observed], timeout: 20)
+    XCTAssertTrue(pumpMainThread(until: { !self.hasAbandonedMainThreadWork() }))
+    sleepFor(0.3)
+
+    XCTAssertNil(observation.stopError)
+    XCTAssertTrue(observation.stopReturnedWhileWedged, "stop must not wait for the wedged capture")
+    XCTAssertEqual(recorder.appendedFrameSnapshotForTesting().count, observation.framesAtStop)
+    let lateImage = try XCTUnwrap(source.lateImage)
+    XCTAssertFalse(recorder.appendedFrameSnapshotForTesting().contains { $0 === lateImage })
+  }
+
+  func testRecordingStopRefusesAFrameThatFinishedAtTheTimeoutBoundary() throws {
+    let source = RecordingFrameSource()
+    let recorder = ScreenRecorder(outputPath: recordingTestOutputPath(), fps: 10)
+    try startRecording(recorder, capture: source.capture)
+    XCTAssertTrue(pumpMainThread(until: { recorder.appendedFrameSnapshotForTesting().count >= 2 }))
+
+    final class Observation {
+      var framesAtStop: Int?
+    }
+    let observation = Observation()
+    mainThreadWorkTimedOutForTesting = {
+      try? recorder.stop()
+      observation.framesAtStop = recorder.appendedFrameSnapshotForTesting().count
+      source.releaseWedge.signal()
+      DispatchQueue.main.sync {}
+    }
+    defer { mainThreadWorkTimedOutForTesting = nil }
+    source.armWedge()
+    XCTAssertTrue(pumpMainThread(until: { observation.framesAtStop != nil }))
+    sleepFor(0.3)
+
+    XCTAssertFalse(hasAbandonedMainThreadWork(), "a capture finished at the boundary is not abandoned")
+    let lateImage = try XCTUnwrap(source.lateImage)
+    XCTAssertFalse(
+      recorder.appendedFrameSnapshotForTesting().contains { $0 === lateImage },
+      "a frame returned after stop is never appended"
+    )
+    XCTAssertEqual(recorder.appendedFrameSnapshotForTesting().count, observation.framesAtStop)
+  }
+
+  func testRecordingAfterAStopDuringATimedOutCaptureStartsClean() throws {
+    let first = RecordingFrameSource()
+    let firstRecorder = ScreenRecorder(outputPath: recordingTestOutputPath(), fps: 10)
+    try startRecording(firstRecorder, capture: first.capture)
+    XCTAssertTrue(pumpMainThread(until: { firstRecorder.appendedFrameSnapshotForTesting().count >= 2 }))
+    let stopped = expectation(description: "first recording stopped during its timed-out capture")
+    first.armWedge()
+    DispatchQueue(label: "agent-device.runner.tests.recording-restart").async {
+      defer {
+        first.releaseWedge.signal()
+        stopped.fulfill()
+      }
+      guard first.wedgeEntered.wait(timeout: .now() + 3) == .success else { return }
+      guard self.waitOffMain(until: { self.hasAbandonedMainThreadWork() }) else { return }
+      try? firstRecorder.stop()
+    }
+    wait(for: [stopped], timeout: 20)
+    XCTAssertTrue(pumpMainThread(until: { !self.hasAbandonedMainThreadWork() }))
+    let firstFrames = firstRecorder.appendedFrameSnapshotForTesting()
+
+    let second = RecordingFrameSource()
+    let secondOutputPath = recordingTestOutputPath()
+    let secondRecorder = ScreenRecorder(outputPath: secondOutputPath, fps: 10)
+    try startRecording(secondRecorder, capture: second.capture)
+    XCTAssertTrue(pumpMainThread(until: { secondRecorder.appendedFrameSnapshotForTesting().count >= 3 }))
+    try secondRecorder.stop()
+
+    let secondFrames = secondRecorder.appendedFrameSnapshotForTesting()
+    XCTAssertFalse(secondFrames.contains { frame in firstFrames.contains { $0 === frame } })
+    let lateImage = try XCTUnwrap(first.lateImage)
+    XCTAssertFalse(secondFrames.contains { $0 === lateImage })
+    XCTAssertFalse(firstRecorder.appendedFrameSnapshotForTesting().contains { $0 === lateImage })
+    XCTAssertEqual(firstRecorder.appendedFrameSnapshotForTesting().count, firstFrames.count)
+    XCTAssertFalse(hasAbandonedMainThreadWork())
+    let attributes = try FileManager.default.attributesOfItem(atPath: secondOutputPath)
+    XCTAssertGreaterThan((attributes[.size] as? NSNumber)?.intValue ?? 0, 0)
+  }
+
+  func testRecordingFrameNeverQueuesBehindACommandsMainThreadWork() throws {
+    let source = RecordingFrameSource()
+    let recorder = ScreenRecorder(outputPath: recordingTestOutputPath(), fps: 60)
+    try startRecording(recorder, capture: source.capture)
+    defer { try? recorder.stop() }
+    XCTAssertTrue(pumpMainThread(until: { recorder.appendedFrameSnapshotForTesting().count >= 3 }))
+
+    let occupancy = MainThreadOccupancySampler(runner: self)
+    let commandFinished = expectation(description: "the command's main-thread hops finished")
+    final class Outcome {
+      var error: Error?
+    }
+    let outcome = Outcome()
+    DispatchQueue(label: "agent-device.runner.tests.recording-command").async {
+      defer {
+        occupancy.stop()
+        commandFinished.fulfill()
+      }
+      do {
+        for _ in 0..<2 {
+          try self.runMainThreadWork(
+            "command_execution",
+            timeout: self.mainThreadExecutionTimeout,
+            timeoutError: self.mainThreadExecutionTimeoutError
+          ) {
+            Thread.sleep(forTimeInterval: self.recordingFrameCaptureTimeout + 0.3)
+          }
+        }
+      } catch {
+        outcome.error = error
+      }
+    }
+    wait(for: [commandFinished], timeout: 15)
+    let framesAfterCommand = recorder.appendedFrameSnapshotForTesting().count
+    XCTAssertTrue(
+      pumpMainThread(until: { recorder.appendedFrameSnapshotForTesting().count >= framesAfterCommand + 2 }),
+      "the recorder appends frames again once the command leaves main"
+    )
+
+    XCTAssertNil(outcome.error)
+    XCTAssertTrue(occupancy.sampled, "the sampler ran while the command held main")
+    XCTAssertFalse(occupancy.sawBusy, "a recorder tick must not make the busy gate or stamp see occupancy")
+    XCTAssertFalse(occupancy.sawAbandoned, "a recorder tick must not mark work abandoned")
+    XCTAssertFalse(occupancy.sawXCTestTierSkip, "a recorder tick must not skip XCTest snapshot tiers")
+    guard case .idle = currentMainThreadBusyState() else {
+      return XCTFail("expected the runner idle after the command")
+    }
+  }
+
+  func testRecordingFrameSlowerThanTheIntervalStillYieldsFrames() throws {
+    let fps: Int32 = 20
+    let interval = 1.0 / Double(fps)
+    let source = RecordingFrameSource(captureDelay: interval * 1.6)
+    let recorder = ScreenRecorder(outputPath: recordingTestOutputPath(), fps: fps)
+    try startRecording(recorder, capture: source.capture)
+    defer { try? recorder.stop() }
+    XCTAssertTrue(pumpMainThread(until: { recorder.appendedFrameSnapshotForTesting().count >= 2 }))
+
+    let window: TimeInterval = 1.5
+    let occupancy = MainThreadOccupancySampler(runner: self)
+    let framesBefore = recorder.appendedFrameSnapshotForTesting().count
+    sleepFor(window)
+    occupancy.stop()
+    let yielded = recorder.appendedFrameSnapshotForTesting().count - framesBefore
+
+    XCTAssertGreaterThanOrEqual(
+      yielded,
+      Int(window / (interval * 1.6) / 3),
+      "a capture slower than the interval lowers the frame rate instead of dropping every frame"
+    )
+    XCTAssertTrue(occupancy.sampled)
+    XCTAssertFalse(occupancy.sawAbandoned, "an ordinary slow capture is not abandoned work")
+    XCTAssertFalse(occupancy.sawBusy, "an ordinary slow capture keeps the runner available")
+  }
+
+  private func recordingTestOutputPath() -> String {
+    (NSTemporaryDirectory() as NSString).appendingPathComponent(
+      "record-bounded-\(UUID().uuidString).mp4"
+    )
+  }
+
+  private func pumpMainThread(timeout: TimeInterval = 5, until condition: () -> Bool) -> Bool {
+    let deadline = Date().addingTimeInterval(timeout)
+    while !condition() {
+      if Date() >= deadline { return false }
+      sleepFor(0.01)
+    }
+    return true
+  }
+
+  private func waitOffMain(timeout: TimeInterval = 5, until condition: () -> Bool) -> Bool {
+    let deadline = Date().addingTimeInterval(timeout)
+    while !condition() {
+      if Date() >= deadline { return false }
+      usleep(5_000)
+    }
+    return true
+  }
+}
+#endif
diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md
index 516cc31350..b2a54416e2 100644
--- a/website/docs/docs/commands.md
+++ b/website/docs/docs/commands.md
@@ -1060,6 +1060,7 @@ agent-device record stop                # Stop active recording
 - Burned-in touch overlays are exported only on macOS hosts, because the overlay pipeline depends on Swift + AVFoundation helpers.
 - On Linux or other non-macOS hosts, `record stop` still succeeds and returns the raw video plus telemetry sidecar, and includes `overlayWarning` when burn-in overlays were skipped.
 - On iOS simulators, a busy CoreSimulator host recording slot makes `record start` return non-retriable `DEVICE_IN_USE` with `details.reason: apple_simulator_recording_busy`. Use `record stop` in the session that owns the active recording. If a previous recorder died and no recording is active, ask the host operator to restart the CoreSimulator stream service before retrying.
+- When the Apple runner records (`--fps` sets its frame rate), it captures a frame only while no command is using the runner's main thread; a frame that falls during that work is skipped instead of queued behind it. A capture slower than the frame interval lowers the frame rate, and a capture still running after one second is dropped. A busy app or a long command can therefore yield fewer frames than `--fps` requests.
 - Android uses `adb shell screenrecord`, which has a 180s platform limit. `record start` publishes a durable device manifest. Longer recordings are split into MP4 chunks while the daemon stays alive; after daemon restart, `record stop` recovers only manifest-owned chunks and warns when gesture overlay telemetry was lost.
 - Android `screenrecord` encodes a frame only when the screen changes, so a clip ends at the last frame the recorder encoded instead of at `record stop`: a window that ends on an unchanged screen yields a shorter video, while every on-screen change inside the window stays at its real offset in it. `record stop` reports `durationMs` as host wall clock from `record start` until the export finished, and when the video can be measured it also reports `capturedDurationMs` and warns with how much of the window that video covers.
 - Limrun iOS and Android direct sessions record the whole simulator or emulator screen through the provider's server-side recorder, so every `--scope` captures the same frame and `--fps` and `--hide-touches` are refused with `INVALID_ARGS` before any device work. `record stop` asks the instance to stop once and then downloads the served MP4 to the output path; that download is bounded to end inside the request window, so a slow or dropped transfer ends typed, leaves no file behind, and is retried by the next `record stop` from the same URL while the instance lives. Nothing survives a daemon restart: the recording is `unreattachable` and the instance disposes the file when the lease is released.

From 072872e57c2d2851dc24885bac3b4e6bfac2e8ab Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Oskar=20Kwa=C5=9Bniewski?= <oskar@okwasniewski.com>
Date: Thu, 24 Sep 2026 10:47:24 +0200
Subject: [PATCH 079/132] fix(ios-runner): resend read-only commands across the
 RUNNER_BUSY drain window (#2804)

* fix(ios-runner): resend read-only commands across the RUNNER_BUSY drain window

* fix(ios-runner): keep the RUNNER_BUSY refusal through a mid-window wait deadline

A wait bounds each poll with its own abort signal and keeps the last typed
refusal as the wait's cause. Inside the resend window that deadline surfaced
as a bare cancellation, so a wait timing out mid-window reported a stalled
capture and dropped the runner's own code, message and hint. The resend loop
now remembers the last busy refusal and rethrows it when the abort is a
caller deadline; only a cancelled request reports as a cancellation.

Also: jitter 0 on the resend policy so the documented 5.4s window is the
actual one, and a test pinning that a mutating command meets RUNNER_BUSY once
with no status probe and no resend.

* fix(ios-runner): read the caller deadline from the abort reason, not registry absence

A wait bounds each poll with an abort whose reason is a TimeoutError; that
typed reason now decides whether the last RUNNER_BUSY refusal is rethrown,
so a deadline landing mid-fetch during a resend (surfacing as whatever the
transport threw on abort) is read the same way as one that wakes a delay.
A cancelled request still reports as a cancellation.
---
 .../runner-command-busy-resend.test.ts        | 243 ++++++++++++++++++
 .../runner-error-classification.test.ts       |  25 ++
 .../src/runner/runner-client.ts               |  68 ++++-
 .../src/runner/runner-error-classification.ts |  42 ++-
 .../src/runner/runner-lifecycle.ts            |   8 +-
 .../src/runner/runner-session.ts              |   5 +-
 6 files changed, 373 insertions(+), 18 deletions(-)
 create mode 100644 packages/platform-apple/src/runner/__tests__/runner-command-busy-resend.test.ts

diff --git a/packages/platform-apple/src/runner/__tests__/runner-command-busy-resend.test.ts b/packages/platform-apple/src/runner/__tests__/runner-command-busy-resend.test.ts
new file mode 100644
index 0000000000..3c5fa48440
--- /dev/null
+++ b/packages/platform-apple/src/runner/__tests__/runner-command-busy-resend.test.ts
@@ -0,0 +1,243 @@
+import { beforeEach, test, vi } from 'vitest';
+import assert from 'node:assert/strict';
+import { IOS_SIMULATOR } from './device-fixtures.ts';
+import { createTestRequestCancellation, makeRunnerSession } from './runner-session-fixtures.ts';
+import { AppError, isRequestCanceledError } from '@agent-device/kernel/errors';
+import { appleRunnerTestHost } from '../test-host.ts';
+
+// The read-only resend policy around a `RUNNER_BUSY` refusal. The runner refuses fast while
+// watchdog-abandoned XCTest work drains, so the daemon's resend has to outlast that drain, keep
+// the old three-attempt budget for transport failures, and stay cancellable across the seconds it
+// may now wait.
+
+const {
+  mockEnsureRunnerSession,
+  mockExecuteRunnerCommandWithSession,
+  mockReadRunnerSessionLiveness,
+  mockInvalidateRunnerSession,
+} = vi.hoisted(() => ({
+  mockEnsureRunnerSession: vi.fn(),
+  mockExecuteRunnerCommandWithSession: vi.fn(),
+  mockReadRunnerSessionLiveness: vi.fn(),
+  mockInvalidateRunnerSession: vi.fn(),
+}));
+
+vi.mock('../runner-session.ts', async () => {
+  const actual =
+    await vi.importActual<typeof import('../runner-session.ts')>('../runner-session.ts');
+  return {
+    ...actual,
+    ensureRunnerSession: mockEnsureRunnerSession,
+    executeRunnerCommandWithSession: mockExecuteRunnerCommandWithSession,
+    readRunnerSessionLiveness: mockReadRunnerSessionLiveness,
+    invalidateRunnerSession: mockInvalidateRunnerSession,
+  };
+});
+
+import { runAppleRunnerCommand } from '../runner-client.ts';
+import { buildRunnerResponseError } from '../runner-contract.ts';
+import { resetRunnerRecycleLedgerForTests } from '../runner-recycle-ledger.ts';
+
+const requestCancellation = createTestRequestCancellation();
+
+beforeEach(() => {
+  vi.resetAllMocks();
+  vi.useRealTimers();
+  resetRunnerRecycleLedgerForTests();
+  requestCancellation.reset();
+  appleRunnerTestHost.update({
+    emitDiagnostic: vi.fn(),
+    isRequestCanceled: requestCancellation.isRequestCanceled,
+    getRequestSignal: () => undefined,
+  });
+  const session = makeRunnerSession({ state: 'ready' });
+  mockEnsureRunnerSession.mockResolvedValue(session);
+  // A live session, or `executeRunnerCommand` reads the resend as a recycle boot and charges the
+  // per-request recycle budget instead of resending.
+  mockReadRunnerSessionLiveness.mockReturnValue({
+    sessionId: session.sessionId,
+    liveness: 'ready',
+  });
+});
+
+/** The runner's live refusal, exactly as the transport decodes it. */
+function busyRefusal(): AppError {
+  return buildRunnerResponseError({
+    ok: false,
+    error: { code: 'RUNNER_BUSY', message: 'The iOS runner is still finishing a previous command' },
+  });
+}
+
+function sentCommands(): string[] {
+  return mockExecuteRunnerCommandWithSession.mock.calls.map((call) => call[2].command);
+}
+
+test('read-only commands wait out RUNNER_BUSY past the transport resend backoff', async () => {
+  // Three busy answers spaced 200/400/800ms apart, then the runner answers. The default three
+  // attempts stopped after the second delay, before the abandoned work had drained.
+  vi.useFakeTimers();
+  mockExecuteRunnerCommandWithSession
+    .mockRejectedValueOnce(busyRefusal())
+    .mockRejectedValueOnce(busyRefusal())
+    .mockRejectedValueOnce(busyRefusal())
+    .mockResolvedValueOnce({ nodes: [], truncated: false });
+
+  const pending = runAppleRunnerCommand(IOS_SIMULATOR, { command: 'snapshot' });
+  await vi.advanceTimersByTimeAsync(6_000);
+  const result = await pending;
+
+  assert.deepEqual(result, { nodes: [], truncated: false });
+  assert.equal(mockInvalidateRunnerSession.mock.calls.length, 0);
+  // A structured refusal already says the command did not run, so no status probe sits between
+  // the resends.
+  assert.deepEqual(sentCommands(), ['snapshot', 'snapshot', 'snapshot', 'snapshot']);
+});
+
+test('a RUNNER_BUSY resend still ends when the refusals outlast the window', async () => {
+  vi.useFakeTimers();
+  mockExecuteRunnerCommandWithSession.mockImplementation(async () => {
+    throw busyRefusal();
+  });
+
+  const pending = runAppleRunnerCommand(IOS_SIMULATOR, { command: 'snapshot' });
+  const settled = pending.then(
+    () => undefined,
+    (error: unknown) => error,
+  );
+  await vi.advanceTimersByTimeAsync(20_000);
+  const error = await settled;
+
+  assert.ok(error instanceof AppError);
+  assert.equal(error.details?.runnerErrorCode, 'RUNNER_BUSY');
+  assert.equal(error.details?.recovery, undefined, 'the raw refusal reaches the caller unwrapped');
+  assert.deepEqual(sentCommands(), Array<string>(8).fill('snapshot'));
+});
+
+test('read-only transport failures keep the three-attempt resend budget', async () => {
+  mockExecuteRunnerCommandWithSession
+    .mockRejectedValueOnce(new AppError('COMMAND_FAILED', 'fetch failed'))
+    .mockResolvedValueOnce({ lifecycleState: 'started' })
+    .mockRejectedValueOnce(new AppError('COMMAND_FAILED', 'fetch failed'))
+    .mockResolvedValueOnce({ lifecycleState: 'started' })
+    .mockRejectedValueOnce(new AppError('COMMAND_FAILED', 'fetch failed'))
+    .mockResolvedValueOnce({ lifecycleState: 'started' })
+    .mockResolvedValueOnce({ nodes: [], truncated: false });
+
+  await assert.rejects(
+    () => runAppleRunnerCommand(IOS_SIMULATOR, { command: 'snapshot' }),
+    (error: unknown) => {
+      assert.ok(error instanceof AppError);
+      assert.equal(error.message, 'fetch failed');
+      return true;
+    },
+  );
+
+  assert.equal(sentCommands().filter((command) => command === 'snapshot').length, 3);
+});
+
+test('a wait deadline landing mid-window rethrows the last RUNNER_BUSY refusal, not a cancel', async () => {
+  // `wait` bounds each poll with its own abort signal (runWithinWaitDeadline) and keeps the last
+  // typed refusal as the wait's cause. The refusal must therefore survive the deadline: a bare
+  // cancellation would make the wait report a stalled capture and drop the runner's own code.
+  vi.useFakeTimers();
+  const deadline = new AbortController();
+  mockExecuteRunnerCommandWithSession
+    .mockRejectedValueOnce(busyRefusal())
+    .mockResolvedValue({ nodes: [], truncated: false });
+
+  const pending = runAppleRunnerCommand(
+    IOS_SIMULATOR,
+    { command: 'snapshot' },
+    { requestId: 'req-wait', signal: deadline.signal },
+  );
+  const settled = pending.then(
+    () => undefined,
+    (error: unknown) => error,
+  );
+  await vi.advanceTimersByTimeAsync(50);
+  deadline.abort(new DOMException('Wait deadline exceeded', 'TimeoutError'));
+  await vi.advanceTimersByTimeAsync(0);
+  const error = await settled;
+
+  assert.ok(error instanceof AppError, `expected the refusal, got ${String(error)}`);
+  assert.equal(error.details?.runnerErrorCode, 'RUNNER_BUSY');
+  assert.equal(error.details?.retriable, true);
+  assert.deepEqual(sentCommands(), ['snapshot']);
+});
+
+test('a wait deadline landing mid-fetch during a resend still rethrows the RUNNER_BUSY refusal', async () => {
+  vi.useFakeTimers();
+  const deadline = new AbortController();
+  mockExecuteRunnerCommandWithSession.mockRejectedValueOnce(busyRefusal()).mockImplementationOnce(
+    (_device, _session, _command, _logPath, _timeoutMs, signal: AbortSignal | undefined) =>
+      new Promise((_resolve, reject) => {
+        signal?.addEventListener('abort', () => reject(signal.reason), { once: true });
+      }),
+  );
+
+  const pending = runAppleRunnerCommand(
+    IOS_SIMULATOR,
+    { command: 'snapshot' },
+    { requestId: 'req-wait-mid-fetch', signal: deadline.signal },
+  );
+  const settled = pending.then(
+    () => undefined,
+    (error: unknown) => error,
+  );
+  // Past the first 200ms delay: the second send is in flight when the deadline lands.
+  await vi.advanceTimersByTimeAsync(250);
+  deadline.abort(new DOMException('Wait deadline exceeded', 'TimeoutError'));
+  await vi.advanceTimersByTimeAsync(0);
+  const error = await settled;
+
+  assert.ok(error instanceof AppError, `expected the refusal, got ${String(error)}`);
+  assert.equal(error.details?.runnerErrorCode, 'RUNNER_BUSY');
+  assert.deepEqual(sentCommands(), ['snapshot', 'snapshot']);
+});
+
+test('a cancelled request wakes the RUNNER_BUSY delay and reports the cancellation', async () => {
+  vi.useFakeTimers();
+  const request = new AbortController();
+  appleRunnerTestHost.update({ getRequestSignal: () => request.signal });
+  mockExecuteRunnerCommandWithSession
+    .mockRejectedValueOnce(busyRefusal())
+    .mockResolvedValue({ nodes: [], truncated: false });
+
+  const pending = runAppleRunnerCommand(
+    IOS_SIMULATOR,
+    { command: 'snapshot' },
+    { requestId: 'req-cancelled' },
+  );
+  const settled = pending.then(
+    () => undefined,
+    (error: unknown) => error,
+  );
+  // Inside the first 200ms delay; the next attempt would otherwise succeed at the timer.
+  await vi.advanceTimersByTimeAsync(50);
+  requestCancellation.markRequestCanceled('req-cancelled');
+  request.abort();
+  await vi.advanceTimersByTimeAsync(0);
+  const error = await settled;
+
+  assert.ok(isRequestCanceledError(error), `expected a canceled request, got ${String(error)}`);
+  assert.deepEqual(sentCommands(), ['snapshot']);
+});
+
+test('a mutating command meets RUNNER_BUSY once, with no status probe and no resend', async () => {
+  // The status-recovery bypass for structured replies reaches mutating commands too: the refusal
+  // says the tap did not run, so there is nothing to recover and nothing is replayed.
+  mockExecuteRunnerCommandWithSession.mockRejectedValueOnce(busyRefusal());
+
+  await assert.rejects(
+    () => runAppleRunnerCommand(IOS_SIMULATOR, { command: 'tap', x: 120, y: 240 }),
+    (error: unknown) => {
+      assert.ok(error instanceof AppError);
+      assert.equal(error.details?.runnerErrorCode, 'RUNNER_BUSY');
+      assert.equal(error.details?.recovery, undefined);
+      return true;
+    },
+  );
+
+  assert.deepEqual(sentCommands(), ['tap']);
+  assert.equal(mockInvalidateRunnerSession.mock.calls.length, 0);
+});
diff --git a/packages/platform-apple/src/runner/__tests__/runner-error-classification.test.ts b/packages/platform-apple/src/runner/__tests__/runner-error-classification.test.ts
index f1936ad802..64b379f792 100644
--- a/packages/platform-apple/src/runner/__tests__/runner-error-classification.test.ts
+++ b/packages/platform-apple/src/runner/__tests__/runner-error-classification.test.ts
@@ -8,6 +8,7 @@ import {
 import {
   RUNNER_ERROR_RULES,
   isRetryableRunnerError,
+  isRunnerBusyError,
   resolveRunnerFatalErrorReason,
   shouldRebuildCachedRunnerArtifact,
   shouldRestartRunnerAfterReadinessPreflight,
@@ -301,3 +302,27 @@ test('a refused screen capture keeps the runner reason and stays off the wire co
     assert.equal(classified.details.retriable, undefined);
   }
 });
+
+// --- busy refusal (isRunnerBusyError) ---
+
+test('only the typed RUNNER_BUSY refusal reads as busy', () => {
+  assert.equal(
+    isRunnerBusyError(commandFailed('runner is busy', { runnerErrorCode: 'RUNNER_BUSY' })),
+    true,
+  );
+  // The stalling command's own timeout already spent its wait: not a refusal to resend.
+  assert.equal(
+    isRunnerBusyError(
+      commandFailed('main thread execution timed out', { runnerErrorCode: 'MAIN_THREAD_TIMEOUT' }),
+    ),
+    false,
+  );
+  assert.equal(
+    isRunnerBusyError(
+      commandFailed('The iOS runner is still finishing a previous command', { retriable: true }),
+    ),
+    false,
+  );
+  assert.equal(isRunnerBusyError(commandFailed('RUNNER_BUSY')), false);
+  assert.equal(isRunnerBusyError(new Error('RUNNER_BUSY')), false);
+});
diff --git a/packages/platform-apple/src/runner/runner-client.ts b/packages/platform-apple/src/runner/runner-client.ts
index a32b352463..76bcc29388 100644
--- a/packages/platform-apple/src/runner/runner-client.ts
+++ b/packages/platform-apple/src/runner/runner-client.ts
@@ -1,4 +1,4 @@
-import { retryWithPolicy, emitDiagnostic } from './host.ts';
+import { retryWithPolicy, emitDiagnostic, getRequestSignal, isRequestCanceled } from './host.ts';
 import { isIosFamily, type DeviceInfo } from '@agent-device/kernel/device';
 import {
   ensureRunnerSession,
@@ -9,10 +9,11 @@ import {
 } from './runner-session.ts';
 import {
   assertRunnerRequestActive,
+  resolveRunnerRequestSignal,
   withRunnerCommandId,
   type RunnerCommand,
 } from './runner-contract.ts';
-import { isRetryableRunnerError } from './runner-error-classification.ts';
+import { isRetryableRunnerError, isRunnerBusyError } from './runner-error-classification.ts';
 import { isReadOnlyRunnerCommand } from './runner-command-traits.ts';
 import {
   createLocalAppleRunnerProvider,
@@ -32,6 +33,45 @@ import { RUNNER_COMMAND_TIMEOUT_MS } from './runner-transport.ts';
 
 // --- Runner command execution ---
 
+/**
+ * Attempts a read-only command may spend on one error class; 1 means no resend. A `RUNNER_BUSY`
+ * refusal is the runner refusing fast on purpose while it drains abandoned XCTest work (#1105), so
+ * that budget has to outlast the drain. The window is a heuristic, not a measurement: 200ms doubling
+ * to a 1s cap, no jitter, is 5.4s of delay across eight attempts before round trips, and a drain
+ * that outlives it still surfaces as `RUNNER_BUSY` (the runner's own `abandonedForSeconds=` marker
+ * in runner.log is the evidence for tuning it). Transport failures keep the pre-existing three
+ * attempts. The budget is positional: the error on each attempt sets how many attempts the loop may
+ * reach in total, so three busy refusals followed by a transport failure resend no further.
+ */
+const RUNNER_BUSY_RESEND_ATTEMPTS = 8;
+const TRANSPORT_RESEND_ATTEMPTS = 3;
+const READ_ONLY_RESEND_POLICY = {
+  maxAttempts: RUNNER_BUSY_RESEND_ATTEMPTS,
+  baseDelayMs: 200,
+  maxDelayMs: 1_000,
+  jitter: 0,
+};
+
+function readOnlyResendBudget(error: unknown): number {
+  if (isRunnerBusyError(error)) return RUNNER_BUSY_RESEND_ATTEMPTS;
+  return isRetryableRunnerError(error) ? TRANSPORT_RESEND_ATTEMPTS : 1;
+}
+
+/**
+ * Whether the caller's own deadline ended this command, as opposed to the request being cancelled.
+ * A `wait` bounds each poll with an abort signal whose reason is a `TimeoutError`
+ * (`runWithinWaitDeadline`); a cancelled request aborts through the registered request signal or
+ * the cancellation registry. The typed reason decides, so a deadline that lands mid-fetch (surfacing
+ * as whatever the transport threw on abort) is read the same way as one that wakes a delay.
+ */
+function callerDeadlineExpired(options: AppleRunnerCommandOptions): boolean {
+  if (isRequestCanceled(options.requestId) || getRequestSignal(options.requestId)?.aborted) {
+    return false;
+  }
+  const reason: unknown = options.signal?.aborted ? options.signal.reason : undefined;
+  return reason instanceof DOMException && reason.name === 'TimeoutError';
+}
+
 export async function runAppleRunnerCommand(
   device: DeviceInfo,
   command: RunnerCommand,
@@ -41,21 +81,35 @@ export async function runAppleRunnerCommand(
   assertRunnerRequestActive(options.requestId);
   const runnerCommand = withRunnerCommandId(command);
   const provider = resolveAppleRunnerRuntime(device, options);
-  if (isReadOnlyRunnerCommand(runnerCommand)) {
-    return retryWithPolicy(
+  if (!isReadOnlyRunnerCommand(runnerCommand)) {
+    return provider.runCommand(device, runnerCommand, options);
+  }
+  let lastBusyRefusal: unknown;
+  try {
+    return await retryWithPolicy(
       () => {
         assertRunnerRequestActive(options.requestId);
         return provider.runCommand(device, runnerCommand, options);
       },
       {
-        shouldRetry: (error) => {
+        ...READ_ONLY_RESEND_POLICY,
+        shouldRetry: (error, attempt) => {
           assertRunnerRequestActive(options.requestId);
-          return isRetryableRunnerError(error);
+          if (isRunnerBusyError(error)) lastBusyRefusal = error;
+          return attempt < readOnlyResendBudget(error);
         },
       },
+      // The busy window is seconds long, so an abort must wake the delay instead of sleeping it
+      // out and sending one more attempt.
+      { signal: resolveRunnerRequestSignal(options) },
     );
+  } catch (error) {
+    // A caller's deadline (a `wait` poll bounding this capture) that lands mid-window still has an
+    // answer: the runner refused, and that typed refusal is what the caller can act on. Only a
+    // cancelled request reports as a bare cancellation.
+    if (lastBusyRefusal && callerDeadlineExpired(options)) throw lastBusyRefusal;
+    throw error;
   }
-  return provider.runCommand(device, runnerCommand, options);
 }
 
 export async function notifyIosRunnerAppRelaunched(
diff --git a/packages/platform-apple/src/runner/runner-error-classification.ts b/packages/platform-apple/src/runner/runner-error-classification.ts
index 9d5fca5d2c..aa8e1c072b 100644
--- a/packages/platform-apple/src/runner/runner-error-classification.ts
+++ b/packages/platform-apple/src/runner/runner-error-classification.ts
@@ -72,6 +72,8 @@ type RunnerErrorMatch = {
 const hasRetriableFlag: RunnerErrorDetailsMatch = (details) => details.retriable === true;
 const hasAppNotRunningRunnerCode: RunnerErrorDetailsMatch = (details) =>
   details.runnerErrorCode === APP_NOT_RUNNING_RUNNER_CODE;
+const hasRunnerBusyCode: RunnerErrorDetailsMatch = (details) =>
+  details.runnerErrorCode === RUNNER_BUSY_RUNNER_CODE;
 /**
  * The host's own `DevToolsSecurity -status` read, published as typed details by the probe that
  * takes it. The build-failure rule below keys on this field and never on the probe's message, so
@@ -95,8 +97,14 @@ const hasReadinessPreflightFailure: RunnerErrorDetailsMatch = (details) =>
   details.runnerReadinessPreflightFailed === true && !isRequestCanceledDetails(details);
 
 type RunnerErrorVerdicts = {
-  /** isRetryableRunnerError: transport error worth a same-session resend. */
+  /**
+   * isRetryableRunnerError: worth a same-session resend, either a transport failure or a structured
+   * refusal that executed nothing. Whether a lost response needs status recovery is a separate
+   * question ({@link isStructuredRunnerFailure}).
+   */
   retryable?: boolean;
+  /** isRunnerBusyError: the runner refused fast while abandoned main-thread work drains. */
+  drainResend?: boolean;
   /** shouldRetryRunnerConnectError: connect loop may keep waiting for the runner. */
   connectRetry?: boolean;
   /** Session-fatal classification: invalidate the cached runner session with this reason. */
@@ -219,6 +227,13 @@ export const RUNNER_ERROR_RULES: readonly RunnerErrorRule[] = [
     match: { code: 'COMMAND_FAILED', details: hasAppNotRunningRunnerCode },
     verdicts: { retryable: false, connectRetry: false },
   },
+  {
+    // Named before the generic retriable flag so diagnostics say what refused, not that a flag
+    // was set. Nothing ran: the runner answered before dispatching the command (#1105).
+    reason: 'runner_busy_refusal',
+    match: { code: 'COMMAND_FAILED', details: hasRunnerBusyCode },
+    verdicts: { retryable: true, connectRetry: true, drainResend: true },
+  },
   {
     reason: 'flagged_retriable',
     match: { code: 'COMMAND_FAILED', details: hasRetriableFlag },
@@ -512,14 +527,31 @@ export function isRetryableRunnerError(err: unknown): boolean {
  * `details.runnerErrorCode`), so family policy reads the typed detail rather than the message.
  */
 export function isRunnerMainThreadOccupiedError(error: unknown): boolean {
-  if (!(error instanceof AppError)) return false;
-  const runnerErrorCode = error.details?.runnerErrorCode;
+  if (isRunnerBusyError(error)) return true;
   return (
-    runnerErrorCode === RUNNER_BUSY_RUNNER_CODE ||
-    runnerErrorCode === MAIN_THREAD_TIMEOUT_RUNNER_CODE
+    error instanceof AppError && error.details?.runnerErrorCode === MAIN_THREAD_TIMEOUT_RUNNER_CODE
   );
 }
 
+/**
+ * True when the runner refused this command outright because watchdog-abandoned XCTest work still
+ * occupies its main thread (`RUNNER_BUSY`). Nothing was executed, so a read-only caller may resend
+ * once the work drains; `MAIN_THREAD_TIMEOUT` is deliberately excluded because that command already
+ * spent its wait.
+ */
+export function isRunnerBusyError(error: unknown): boolean {
+  return runnerErrorVerdict(error, 'drainResend') ?? false;
+}
+
+/**
+ * True when the runner answered with a structured failure: the reply itself carries the runner's
+ * payload, so the command's outcome is known and no lifecycle status probe is needed to recover it.
+ * A transport-shaped failure (aborted body, malformed payload, refused connection) answered nothing.
+ */
+export function isStructuredRunnerFailure(error: unknown): boolean {
+  return error instanceof AppError && error.details?.runner !== undefined;
+}
+
 /**
  * True when usbmuxd answered and the device is simply not attached by cable.
  * A CoreDevice-backed device falls back to its network tunnel; an XCTest-backed
diff --git a/packages/platform-apple/src/runner/runner-lifecycle.ts b/packages/platform-apple/src/runner/runner-lifecycle.ts
index aa06dcd967..1cb4884a6f 100644
--- a/packages/platform-apple/src/runner/runner-lifecycle.ts
+++ b/packages/platform-apple/src/runner/runner-lifecycle.ts
@@ -21,6 +21,7 @@ import {
 } from './runner-contract.ts';
 import {
   isRetryableRunnerError,
+  isStructuredRunnerFailure,
   shouldRebuildCachedRunnerArtifact,
   shouldRestartRunnerAfterReadinessPreflight,
   shouldRestartRunnerBeforeCommandSend,
@@ -327,7 +328,10 @@ export async function executeRunnerCommand(
         recoveredDiagnosticPhase: 'ios_runner_readiness_preflight_recovered',
       });
     }
-    if (session && isRetryableRunnerError(appErr)) {
+    // Status recovery answers "did the command I lost the response to run?". A structured reply
+    // (a RUNNER_BUSY refusal, for one) already answered, so it is rethrown for the caller's own
+    // resend policy instead of paying a status round trip per attempt.
+    if (session && isRetryableRunnerError(appErr) && !isStructuredRunnerFailure(appErr)) {
       return await handleRunnerTransportErrorAfterCommandSend({
         device,
         session,
@@ -394,7 +398,7 @@ async function restartSessionAndRunCommand(params: {
     return recovered;
   } catch (error) {
     const retryAppErr = asAppError(error, 'COMMAND_FAILED');
-    if (isRetryableRunnerError(retryAppErr)) {
+    if (isRetryableRunnerError(retryAppErr) && !isStructuredRunnerFailure(retryAppErr)) {
       try {
         return await handleRunnerTransportErrorAfterCommandSend({
           device,
diff --git a/packages/platform-apple/src/runner/runner-session.ts b/packages/platform-apple/src/runner/runner-session.ts
index e27b692034..c8f655733b 100644
--- a/packages/platform-apple/src/runner/runner-session.ts
+++ b/packages/platform-apple/src/runner/runner-session.ts
@@ -43,6 +43,7 @@ import {
 import {
   resolveRunnerFatalErrorReason,
   isRunnerMainThreadOccupiedError,
+  isStructuredRunnerFailure,
   enrichRunnerStartupFailureWithDeviceStates,
 } from './runner-error-classification.ts';
 import {
@@ -977,10 +978,6 @@ function readRunnerMainThreadBusy(data: Record<string, unknown>): boolean | unde
   return typeof data.runnerMainThreadBusy === 'boolean' ? data.runnerMainThreadBusy : undefined;
 }
 
-function isStructuredRunnerFailure(error: unknown): boolean {
-  return error instanceof AppError && error.details?.runner !== undefined;
-}
-
 function markSkippedPreflightTransportError(
   error: unknown,
   session: RunnerSession,

From 7ddaff137409bb2c43bf401bd5d36bbec7f3e85c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 24 Sep 2026 11:07:30 +0200
Subject: [PATCH 080/132] fix(ios): cut modal-contained presentations from
 bridge snapshots (#2850)

* fix(ios): cut modal-contained presentations from bridge snapshots

The host AX bridge reports every sibling container in a window, so each
UIKit modal presentation left the screens it presents over published as
live content. A sheet covers only part of the screen, so the geometric
occlusion pass left the covered controls actionable and selectors resolved
them: a three-screen stack published 567 nodes across three screens where
the same app under the XCTest runner published 76 across the top one.

The presentation cut now applies modal containment: when the last
transition view under a container carries UIKit's dimming view as its
direct child, the earlier transition views that dimmed area spans, and
their subtrees, are cut from the regular and interactive snapshots. Raw
snapshots still report them, and producers that report no UIKit class
names never trigger the rule, so it stays inert on the runner. Every
removed source is counted in the fold's presentation stats (ADR 0026).

The rule joins `geometry-policy.ts`, the module the fold already evaluates
for its per-node decisions, rather than arriving as a new eager module: the
eager-closure budget holds this entry surface at its merge-base size.

* fix(ios): cut a presentation only when its dimming view takes touches

A sheet resting at an undimmed detent keeps UIKit's dimming view as a
direct child of its transition view, at the same window-sized frame, while
the presenting screen stays reachable. The modal-containment rule treated
any such dimming view as proof of modality, so the bridge snapshot cut the
presenting screen's controls: on react-navigation's form-sheet example,
`snapshot -i` over the `Custom Dimming` sheet published only the sheet,
although a press on the presenting `Height Steps` button navigates.

The Simulator AX bridge now reads `XC_kAXXCAttributeIsUserInteractionEnabled`
for dimming views (source version v1.7.0) and the decoder publishes it as
`userInteractionEnabled`. It reads false for the undimmed detent and true
for a dimmed form sheet and a card modal; no attribute the bridge already
read tells them apart, and `IsVisible` reads false for both the undimmed
sheet and the card modal. The read targets dimming views alone: requesting
the attribute for every node cost about half again the capture time on a
492-node tree. The rule now asserts containment only when the dimming view
takes touches, and fails closed when the producer did not read it.

The modal rule and the structural identifier rule now share one
parent-link subtree walker in tree.ts.
---
 CHANGELOG.md                                  |  21 ++
 apple/snapshot-bridge/SnapshotBridgeRuntime.m |  48 +++-
 .../adr/0004-ios-snapshot-backend-strategy.md |  53 ++++
 .../src/ios-snapshot-engine/engine.ts         |   2 +
 .../geometry-policy.test.ts                   | 259 ++++++++++++++++++
 .../ios-snapshot-engine/geometry-policy.ts    |  81 +++++-
 .../src/ios-snapshot-engine/geometry.ts       |   8 +-
 .../ios-snapshot-engine/noise-structural.ts   |  24 +-
 .../runner-presentation.ts                    |   1 +
 .../src/ios-snapshot-engine/tree.ts           |  23 +-
 .../src/ios-snapshot-engine/types.ts          |   2 +
 packages/kernel/src/snapshot.ts               |   2 +
 .../fixtures/wire-vocabulary.json             |   3 +-
 .../src/snapshot-source/protocol.test.ts      |   2 +-
 .../src/snapshot-source/protocol.ts           |   3 +-
 .../src/snapshot-source/tree.test.ts          |  24 ++
 .../src/snapshot-source/tree.ts               |  11 +
 .../capture/runtime/snapshot-unchanged.ts     |   1 +
 18 files changed, 541 insertions(+), 27 deletions(-)
 create mode 100644 packages/capture-kit/src/ios-snapshot-engine/geometry-policy.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f4ee6cdf56..d63c20cf2e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -44,6 +44,27 @@
   through the refusal; the runner transport never resends it. Interactions that mutate without a
   leading read (`press`, a coordinate `fill`, `swipe`, `scroll`, hardware keys) keep the foreground
   repair and still bring a stopped app up.
+- Fixed (ios): a local Simulator snapshot taken through the host AX bridge no longer publishes the
+  screens a modal presentation covers, so a selector resolves the control the user can reach instead
+  of the stale copy underneath it. UIKit appends each presentation as a later sibling of what it
+  presents over, and the bridge reports every sibling, so a React Navigation stack that presents its
+  pushed routes as sheets kept all three screens live: one capture of a three-screen stack published
+  567 nodes across three screens where the same app under the XCTest runner published 76 across the
+  top one. Maestro's visibility predicate is geometric, so `- tapOn: "Push article"` matched the
+  covered screen's button first and the flow failed on an assertion about the screen that never
+  arrived, and `presentation: "formSheet"` fields matched intermittently (#2638). Geometry cannot
+  close this: a sheet leaves most of the covered screen uncovered, and the occlusion pass only
+  treats floating chrome as a cover. The presentation cut now applies modal containment — when the
+  last transition view under a container carries UIKit's dimming view as its direct child and that
+  dimming view takes touches, the earlier transition views that dimmed area spans, and everything
+  under them, are cut from the regular and interactive snapshots. The bridge now reads
+  `userInteractionEnabled` on dimming views (source version v1.7.0) because a sheet resting at an
+  undimmed detent keeps its dimming view while the screen under it stays reachable; that sheet, and
+  any presentation UIKit does not dim, is left as it was, so the cut asserts containment only where
+  the producer states it. `snapshot --raw` still reports the covered screens, and producers that
+  report no UIKit class names — the XCTest runner, whose own queries answered 76 nodes for that same
+  state, plus `appium-source` and `limrun-ios-tree` — never trigger the cut. All 39 flows of React Navigation's Maestro suite pass on an iPhone 17 Simulator running
+  iOS 26.2 with this change, including two that never passed on the bridge.
 - Fixed (ios): a local Simulator snapshot taken through the host AX bridge once again publishes the
   geometric `hittable` fact, so `is hittable` and a `hittable:` selector resolve the same controls on
   the bridge and the XCTest runner. The snapshot capability table has declared `hittable =
diff --git a/apple/snapshot-bridge/SnapshotBridgeRuntime.m b/apple/snapshot-bridge/SnapshotBridgeRuntime.m
index 6f79767b9a..a4e8da8eb3 100644
--- a/apple/snapshot-bridge/SnapshotBridgeRuntime.m
+++ b/apple/snapshot-bridge/SnapshotBridgeRuntime.m
@@ -18,7 +18,7 @@
 NSString *const kProtocolVersionKey = @"protocolVersion";
 NSString *const kSourceVersionKey = @"sourceVersion";
 NSString *const kRequestIdKey = @"requestId";
-NSString *const kSourceVersion = @"agent-device-simulator-ax-v1.6.0";
+NSString *const kSourceVersion = @"agent-device-simulator-ax-v1.7.0";
 const NSUInteger kProtocolVersion = 1;
 const uint32_t kMaximumFrameBytes = 16 * 1024 * 1024;
 const NSUInteger kMaximumDepth = 128;
@@ -34,8 +34,11 @@
 static NSString *const kAttributeAutomationType = @"XC_kAXXCAttributeAutomationType";
 static NSString *const kAttributeTraits = @"XC_kAXXCAttributeTraits";
 static NSString *const kAttributeChildren = @"XC_kAXXCAttributeChildren";
+static NSString *const kAttributeIsUserInteractionEnabled = @"XC_kAXXCAttributeIsUserInteractionEnabled";
+static NSString *const kPresentationDimmingViewClass = @"UIDimmingView";
 static NSString *const kSnapshotAttributes = @"UIAccessibilitySnapshotKeyAttributes";
 static NSString *const kSnapshotChildren = @"UIAccessibilitySnapshotKeyChildren";
+static NSString *const kSnapshotElement = @"UIAccessibilitySnapshotKeyElement";
 static NSString *const kXctAutomationSupportPath =
     @"/Developer/Library/PrivateFrameworks/XCTAutomationSupport.framework/XCTAutomationSupport";
 static NSString *const kAxRuntimePath =
@@ -202,8 +205,35 @@ - (nullable id)jsonValue:(id)value name:(NSString *)name
   return nil;
 }
 
+/*
+ * Whether a presentation's dimming view takes touches is what separates a sheet that blocks the
+ * content under it from one resting at an undimmed detent, and nothing else in the tree says so.
+ * It is read for dimming views alone: requesting it for every node costs about half again the
+ * capture time.
+ */
+- (nullable NSNumber *)userInteractionEnabledForSnapshot:(NSDictionary *)snapshot
+                                                 options:(nullable NSDictionary *)options
+{
+  id element = snapshot[kSnapshotElement];
+  NSNumber *attribute = [options[@"attributes"] firstObject];
+  if (!element || ![attribute isKindOfClass:NSNumber.class]) return nil;
+  @try {
+    NSError *failure = nil;
+    NSDictionary *read = [_framework userTestingSnapshotForElement:element options:options error:&failure];
+    if (![read isKindOfClass:NSDictionary.class]) return nil;
+    NSDictionary *attributes = read[kSnapshotAttributes];
+    if (![attributes isKindOfClass:NSDictionary.class]) return nil;
+    id value = attributes[attribute];
+    return [value isKindOfClass:NSNumber.class] ? @([(NSNumber *)value boolValue]) : nil;
+  } @catch (NSException *exception) {
+    (void)exception;
+    return nil;
+  }
+}
+
 - (nullable NSDictionary *)nodeFromSnapshot:(id)snapshot
                               namesByNumber:(NSDictionary<NSNumber *, NSString *> *)namesByNumber
+                         interactionOptions:(nullable NSDictionary *)interactionOptions
                                       depth:(NSUInteger)depth
                                    maxDepth:(NSUInteger)maxDepth
                                    maxNodes:(NSUInteger)maxNodes
@@ -233,6 +263,11 @@ - (nullable NSDictionary *)nodeFromSnapshot:(id)snapshot
     id safe = [self jsonValue:attributes[number] name:name];
     if (safe) node[name] = safe;
   }
+  if ([node[kAttributeElementType] isEqual:kPresentationDimmingViewClass]) {
+    NSNumber *interaction = [self userInteractionEnabledForSnapshot:(NSDictionary *)snapshot
+                                                            options:interactionOptions];
+    if (interaction) node[kAttributeIsUserInteractionEnabled] = interaction;
+  }
 
   NSArray *children = ((NSDictionary *)snapshot)[kSnapshotChildren];
   if (![children isKindOfClass:NSArray.class]) {
@@ -246,6 +281,7 @@ - (nullable NSDictionary *)nodeFromSnapshot:(id)snapshot
     for (id child in children) {
       NSDictionary *built = [self nodeFromSnapshot:child
                                      namesByNumber:namesByNumber
+                                interactionOptions:interactionOptions
                                              depth:depth + 1
                                           maxDepth:maxDepth
                                              maxNodes:maxNodes
@@ -317,6 +353,15 @@ - (nullable NSDictionary *)snapshotForProcess:(pid_t)pid
   options[@"maxDepth"] = @(maxDepth);
   options[@"maxChildren"] = @(maxNodes);
   options[@"maxArrayCount"] = @(maxNodes);
+  NSArray<NSNumber *> *interactionAttribute = _attributeNumbersForNames(@[ kAttributeIsUserInteractionEnabled ]);
+  NSMutableDictionary *interactionOptions = nil;
+  if ([interactionAttribute isKindOfClass:NSArray.class] && interactionAttribute.count == 1) {
+    interactionOptions = [options mutableCopy];
+    interactionOptions[@"attributes"] = interactionAttribute;
+    interactionOptions[@"maxDepth"] = @0;
+    interactionOptions[@"maxChildren"] = @0;
+    interactionOptions[@"maxArrayCount"] = @0;
+  }
   BOOL automationEnabled = [self assertAutomationMode:YES];
   NSError *runtimeError = nil;
   id snapshot = nil;
@@ -372,6 +417,7 @@ - (nullable NSDictionary *)snapshotForProcess:(pid_t)pid
   NSUInteger count = 0;
   NSDictionary *tree = [self nodeFromSnapshot:snapshot
                                 namesByNumber:namesByNumber
+                           interactionOptions:interactionOptions
                                         depth:0
                                      maxDepth:maxDepth
                                         maxNodes:maxNodes
diff --git a/docs/adr/0004-ios-snapshot-backend-strategy.md b/docs/adr/0004-ios-snapshot-backend-strategy.md
index 46042f3e3b..5e8fe6e66a 100644
--- a/docs/adr/0004-ios-snapshot-backend-strategy.md
+++ b/docs/adr/0004-ios-snapshot-backend-strategy.md
@@ -475,3 +475,56 @@ last reader that can still refuse geometry it cannot place is the tap-path keybo
 width rule therefore remains. The rule detects un-normalized
 arrival, not a standing fact about iOS: the producers above do normalize, and a band taller than it
 is wide is what one that did not looks like.
+
+## Amendment: modal containment in the presentation cut
+
+The bridge reads one window and reports every container hanging off it, while XCTest's own queries
+answer only the presentation the user can reach. React Navigation's card-plus-modal example is the
+measured case: three routes presented as sheets left three transition-view containers in one window
+and one capture published 567 nodes across three screens, where the same app state under the runner
+published 76 across the top screen alone. Maestro's visibility test is geometric, so a `tapOn`
+resolved the covered screen's button and the flow failed on an assertion about the screen that never
+arrived, and a `presentation: "formSheet"` route's fields matched intermittently (#2638).
+
+Decision. The fold applies modal containment: when the last transition view under a container carries
+UIKit's dimming view as its direct child and the producer reports that dimming view takes touches
+(`userInteractionEnabled: true`), the earlier transition views whose frame that dimmed area spans are
+cut, with their subtrees, from the regular and interactive projections. Every part of the claim is a
+producer fact rather than an ordering guess — the dimming view is UIKit's own declaration that it dims
+what sits behind, its interaction state says whether a touch there reaches what sits behind, and its
+frame is the producer's rectangle, which is what a covered container must be inside. A presentation
+with no dimming view, a dimming view the producer did not read or reports passing touches through,
+and any container whose earlier sibling is not a transition view keep today's behavior: containment
+is asserted only where the producer states it, so the rule fails closed rather than guessing which
+siblings are shadows.
+
+A sheet resting at an undimmed detent (`largestUndimmedDetentIdentifier`, react-native-screens
+`sheetLargestUndimmedDetentIndex`) is why the interaction state is part of the claim. UIKit keeps the
+dimming view in the tree at the same window-sized frame, and the presenting screen stays reachable: on
+react-navigation's form-sheet example a press on the presenting screen's `Height Steps` button
+navigates while the `Custom Dimming` sheet rests at its smallest detent. The bridge reports that
+dimming view `userInteractionEnabled: false`, and `true` for the dimmed form sheet and the card modal.
+No attribute the bridge already read told them apart, and `XC_kAXXCAttributeIsVisible` cannot either:
+it reads false for the undimmed sheet's dimming view and for the card modal's. The bridge reads the
+attribute for dimming views alone, in one follow-up read per view: requesting it on every node cost
+about half again the capture time on a 492-node tree, while the targeted read did not move it.
+Every source the cut removes is counted in the presentation's
+`stats.modalContainedNodeCount` — internal evidence, per ADR 0026, never wire vocabulary — because
+the same screen either side of an animation otherwise moves hundreds of comparable lines with nothing
+to attribute them to.
+
+Why this seam and not the neighbouring ones. The semantic presentation rules
+(`IOS_PRESENTATION_RULES`) run only for the interactive projection, so a suppression rule there could
+not deliver the same claim to a regular `snapshot`; the regular eligibility table is pinned against
+its Swift twin, so widening it would move a cross-language contract that this rule does not touch; the
+occlusion pass *marks* a node covered and keeps it published, and a published-but-marked node is
+exactly the 567-versus-76 divergence being fixed, since visibility filtering reads geometry and not
+the mark; and cutting at acquisition would leak the decision into `--raw`, which owes the reader the
+tree the platform reported. Raw therefore still carries the covered screens.
+
+Producers that report no UIKit class names or no dimming-view interaction state never trigger the
+cut, and that is a fact about their output rather than a backend exception in the fold: the runner already omits modal-contained content
+from its own queries, `appium-source` and `limrun-ios-tree` report element types and no classes, and
+the macOS desktop surface arrives already presented. A scope naming a modal-contained screen now
+publishes an empty projection, which is the same healthy empty answer any other unmatched scope gives
+— the screen is not what is presented.
diff --git a/packages/capture-kit/src/ios-snapshot-engine/engine.ts b/packages/capture-kit/src/ios-snapshot-engine/engine.ts
index a8df22b5d0..5a22ae4a7b 100644
--- a/packages/capture-kit/src/ios-snapshot-engine/engine.ts
+++ b/packages/capture-kit/src/ios-snapshot-engine/engine.ts
@@ -101,6 +101,7 @@ function presentAcquiredSnapshot(
         presentedNodeCount: projected.nodes.length,
         sourceNodeCount: acquisition.nodes.length,
         parentClipLookups: 0,
+        modalContainedNodeCount: 0,
       },
     };
   }
@@ -153,6 +154,7 @@ function presentAcquiredSnapshot(
       presentedNodeCount: compacted.nodes.length,
       sourceNodeCount: acquisition.nodes.length,
       parentClipLookups: folded.stats.parentClipLookups + validation.parentClipLookups,
+      modalContainedNodeCount: folded.stats.modalContainedNodeCount,
     },
   };
 }
diff --git a/packages/capture-kit/src/ios-snapshot-engine/geometry-policy.test.ts b/packages/capture-kit/src/ios-snapshot-engine/geometry-policy.test.ts
new file mode 100644
index 0000000000..9afe2542b1
--- /dev/null
+++ b/packages/capture-kit/src/ios-snapshot-engine/geometry-policy.test.ts
@@ -0,0 +1,259 @@
+import { expect, test } from 'vitest';
+import type { RawSnapshotNode, Rect } from '@agent-device/kernel/snapshot';
+import { foldIosSnapshot } from './geometry.ts';
+import { collectModalContainedIndexes } from './geometry-policy.ts';
+import { projectIosSnapshot } from './projection.ts';
+
+const VIEWPORT = { x: 0, y: 0, width: 402, height: 874 };
+const SHEET: Rect = { x: 16, y: 62, width: 370, height: 747 };
+
+type PresentationShape = Readonly<{
+  title: string;
+  containerRole?: string;
+  rect?: Rect;
+  dimming?: 'direct' | 'nested';
+  /** What the producer read from the dimming view; `undefined` means it did not read it. */
+  dimmingTakesTouches?: boolean;
+}>;
+
+/**
+ * Mirrors a react-navigation capture: the presenting container carries only a drop shadow with
+ * UIKit's dimming view below it, while each modal presentation carries a dimming view as a
+ * direct child of its transition view. The Simulator AX bridge reads `userInteractionEnabled`
+ * on every dimming view, so the fixture defaults to the dimmed state it reports.
+ */
+function presentationSubtree(
+  start: number,
+  depth: number,
+  parentIndex: number,
+  shape: PresentationShape,
+): RawSnapshotNode[] {
+  const rect = shape.rect ?? VIEWPORT;
+  const takesTouches = 'dimmingTakesTouches' in shape ? shape.dimmingTakesTouches : true;
+  const dimmingRect: Rect = {
+    x: -VIEWPORT.width,
+    y: -VIEWPORT.height,
+    width: VIEWPORT.width * 3,
+    height: VIEWPORT.height * 3,
+  };
+  const nodes: RawSnapshotNode[] = [
+    snapshotNode(start, depth, parentIndex, 'UITransitionView', 'Other'),
+    snapshotNode(start + 1, depth + 1, start, 'UIDropShadowView', 'Other', undefined, rect),
+    snapshotNode(
+      start + 2,
+      depth + 2,
+      start + 1,
+      shape.containerRole ?? 'RNSModalScreen',
+      'Other',
+      shape.title,
+      rect,
+    ),
+    snapshotNode(start + 3, depth + 3, start + 2, undefined, 'Button', `Push from ${shape.title}`, {
+      x: rect.x + 12,
+      y: rect.y + 92,
+      width: 120,
+      height: 40,
+    }),
+  ];
+  const direct = (shape.dimming ?? 'direct') === 'direct';
+  const dimming = snapshotNode(
+    start + 4,
+    depth + (direct ? 1 : 2),
+    direct ? start : start + 1,
+    'UIDimmingView',
+    'Other',
+    undefined,
+    dimmingRect,
+  );
+  nodes.splice(direct ? 1 : 2, 0, {
+    ...dimming,
+    ...(takesTouches === undefined ? {} : { userInteractionEnabled: takesTouches }),
+  });
+  return nodes;
+}
+
+function snapshotNode(
+  index: number,
+  depth: number,
+  parentIndex: number | undefined,
+  role: string | undefined,
+  type: string,
+  label?: string,
+  rect: Rect = VIEWPORT,
+): RawSnapshotNode {
+  return {
+    index,
+    depth,
+    ...(parentIndex === undefined ? {} : { parentIndex }),
+    type,
+    ...(role ? { role } : {}),
+    ...(label ? { label } : {}),
+    rect,
+    hittable: true,
+  };
+}
+
+function windowWith(children: RawSnapshotNode[]): RawSnapshotNode[] {
+  return [snapshotNode(0, 0, undefined, 'UIWindow', 'Window'), ...children];
+}
+
+function stackedPresentations(): RawSnapshotNode[] {
+  return windowWith([
+    ...presentationSubtree(1, 1, 0, {
+      title: 'Article by Dalek',
+      containerRole: 'RCTSurfaceHostingProxyRootView',
+      dimming: 'nested',
+    }),
+    ...presentationSubtree(6, 1, 0, { title: 'Albums', rect: SHEET }),
+    ...presentationSubtree(11, 1, 0, { title: 'Article by The Doctor' }),
+  ]);
+}
+
+test('dims away every earlier presentation the covering dimming view spans', () => {
+  const contained = collectModalContainedIndexes(stackedPresentations());
+  expect([...contained].sort((left, right) => left - right)).toEqual([
+    1, 2, 3, 4, 5, 6, 7, 8, 9, 10,
+  ]);
+});
+
+test('keeps the covering presentation and everything it contains', () => {
+  const contained = collectModalContainedIndexes(stackedPresentations());
+  expect([...contained].filter((index) => index >= 11)).toEqual([]);
+});
+
+test('presents only the covering subtree through the fold', () => {
+  const folded = foldIosSnapshot(stackedPresentations(), VIEWPORT, false, 'cursor-projected');
+  expect(folded.nodes.flatMap((node) => (node.raw.label ? [node.raw.label] : []))).toEqual([
+    'Article by The Doctor',
+    'Push from Article by The Doctor',
+  ]);
+});
+
+test('records how many sources the cut removed', () => {
+  const folded = foldIosSnapshot(stackedPresentations(), VIEWPORT, false, 'cursor-projected');
+  expect(folded.stats.modalContainedNodeCount).toBe(10);
+  expect(folded.stats.sourceNodeCount).toBe(16);
+});
+
+test('publishes an empty projection when a scope names a modal-contained screen', () => {
+  const folded = foldIosSnapshot(stackedPresentations(), VIEWPORT, false, 'cursor-projected');
+  const covered = projectIosSnapshot({
+    nodes: folded.nodes,
+    projection: 'regular',
+    scope: 'Albums',
+    depth: null,
+    foldPolicy: 'cursor-projected',
+  });
+  const covering = projectIosSnapshot({
+    nodes: folded.nodes,
+    projection: 'regular',
+    scope: 'Article by The Doctor',
+    depth: null,
+    foldPolicy: 'cursor-projected',
+  });
+  expect(covered.nodes).toEqual([]);
+  expect(covering.nodes.length).toBeGreaterThan(0);
+});
+
+test('spares an earlier sibling that is not a presentation container', () => {
+  const nodes = windowWith([
+    snapshotNode(1, 1, 0, 'RCTSurfaceHostingProxyRootView', 'Other'),
+    snapshotNode(2, 2, 1, undefined, 'Button', 'Live control', {
+      x: 12,
+      y: 154,
+      width: 120,
+      height: 40,
+    }),
+    ...presentationSubtree(3, 1, 0, { title: 'Albums' }),
+  ]);
+  expect(collectModalContainedIndexes(nodes).size).toBe(0);
+});
+
+test('fails closed when the last sibling is not a presentation container', () => {
+  const nodes = windowWith([
+    ...presentationSubtree(1, 1, 0, { title: 'Article by Dalek' }),
+    snapshotNode(6, 1, 0, '_UIAlertControllerView', 'Other', 'Don’t leave'),
+    { ...snapshotNode(7, 2, 6, 'UIDimmingView', 'Other'), userInteractionEnabled: true },
+  ]);
+  expect(collectModalContainedIndexes(nodes).size).toBe(0);
+});
+
+test('fails closed when the dimming view sits below the presentation container', () => {
+  const nodes = windowWith([
+    ...presentationSubtree(1, 1, 0, { title: 'Article by Dalek' }),
+    ...presentationSubtree(6, 1, 0, { title: 'Albums', dimming: 'nested' }),
+  ]);
+  expect(collectModalContainedIndexes(nodes).size).toBe(0);
+});
+
+test('fails closed when the dimming view does not span the earlier container', () => {
+  const nodes = windowWith([
+    ...presentationSubtree(1, 1, 0, { title: 'Article by Dalek' }),
+    snapshotNode(6, 1, 0, 'UITransitionView', 'Other'),
+    {
+      ...snapshotNode(7, 2, 6, 'UIDimmingView', 'Other', undefined, {
+        x: 0,
+        y: 0,
+        width: 10,
+        height: 10,
+      }),
+      userInteractionEnabled: true,
+    },
+    snapshotNode(8, 2, 6, 'UIDropShadowView', 'Other', undefined, SHEET),
+  ]);
+  expect(collectModalContainedIndexes(nodes).size).toBe(0);
+});
+
+test('stays inert on a tree that reports no UIKit class names', () => {
+  const nodes = windowWith([
+    snapshotNode(1, 1, 0, undefined, 'Other', 'Article by Dalek'),
+    snapshotNode(2, 1, 0, undefined, 'Other', 'Article by The Doctor'),
+  ]);
+  expect(collectModalContainedIndexes(nodes).size).toBe(0);
+});
+
+test('contains a full-screen presentation that a sheet does not geometrically cover', () => {
+  const nodes = windowWith([
+    ...presentationSubtree(1, 1, 0, { title: 'Article by Dalek' }),
+    ...presentationSubtree(6, 1, 0, { title: 'Albums', rect: SHEET }),
+  ]);
+  expect([...collectModalContainedIndexes(nodes)].sort((left, right) => left - right)).toEqual([
+    1, 2, 3, 4, 5,
+  ]);
+});
+
+test('leaves the presenting screen reachable under a sheet at an undimmed detent', () => {
+  const nodes = windowWith([
+    ...presentationSubtree(1, 1, 0, {
+      title: 'Form Sheet',
+      containerRole: 'RCTSurfaceHostingProxyRootView',
+      dimming: 'nested',
+      dimmingTakesTouches: false,
+    }),
+    ...presentationSubtree(6, 1, 0, {
+      title: 'Custom Dimming',
+      rect: { x: 8, y: 654, width: 386, height: 212 },
+      dimmingTakesTouches: false,
+    }),
+  ]);
+  expect(collectModalContainedIndexes(nodes).size).toBe(0);
+  const folded = foldIosSnapshot(nodes, VIEWPORT, false, 'cursor-projected');
+  expect(folded.nodes.flatMap((node) => (node.raw.label ? [node.raw.label] : []))).toEqual([
+    'Form Sheet',
+    'Push from Form Sheet',
+    'Custom Dimming',
+    'Push from Custom Dimming',
+  ]);
+});
+
+test('fails closed when the producer did not read whether the dimming view takes touches', () => {
+  const nodes = windowWith([
+    ...presentationSubtree(1, 1, 0, { title: 'Article by Dalek' }),
+    ...presentationSubtree(6, 1, 0, {
+      title: 'Albums',
+      rect: SHEET,
+      dimmingTakesTouches: undefined,
+    }),
+  ]);
+  expect(collectModalContainedIndexes(nodes).size).toBe(0);
+});
diff --git a/packages/capture-kit/src/ios-snapshot-engine/geometry-policy.ts b/packages/capture-kit/src/ios-snapshot-engine/geometry-policy.ts
index 7f0108a68e..8d1ffd155f 100644
--- a/packages/capture-kit/src/ios-snapshot-engine/geometry-policy.ts
+++ b/packages/capture-kit/src/ios-snapshot-engine/geometry-policy.ts
@@ -1,12 +1,21 @@
 import type { Rect, RawSnapshotNode } from '@agent-device/kernel/snapshot';
-import { isPositiveFiniteRect } from '@agent-device/kernel/rect';
+import { isPositiveFiniteRect, rectContains } from '@agent-device/kernel/rect';
 import { normalizeType } from '@agent-device/contracts/snapshot';
+import { collectChildrenByParent, collectSubtreeByParentLinks } from './tree.ts';
 import type { IosSnapshotFoldPolicy } from './types.ts';
 
 const SCROLL_CONTAINER_TYPES = new Set(['collectionview', 'scrollview', 'table']);
 const VISIBILITY_CARRIER_TYPES = new Set(['application', 'window']);
 const NEGLIGIBLE_DECORATION_TOLERANCE = 1;
 
+/**
+ * Private UIKit classes are matched by exact name, unlike the substring role tests the occlusion
+ * pass uses: this rule decides node membership, so a near miss on a class name has to fail closed
+ * rather than widen the cut.
+ */
+const PRESENTATION_CONTAINER_ROLE = 'uitransitionview';
+const PRESENTATION_DIMMING_ROLE = 'uidimmingview';
+
 export type TraversalState = Readonly<{
   projectedOut: boolean;
   ancestorClip?: Rect;
@@ -223,3 +232,73 @@ function intersectRect(left: Rect, right: Rect): Rect {
     height: bottomEdge - y,
   };
 }
+
+type CoveringPresentation = Readonly<{
+  container: RawSnapshotNode;
+  dimmingRect: Rect;
+}>;
+
+/**
+ * UIKit appends each modal presentation as a later sibling of the container it presents over,
+ * dims the content behind it with a dimming view that is a direct child of the presentation
+ * container, and the host accessibility snapshot reports siblings in that subview order. A
+ * presenting container carries only a drop shadow, so a direct-child dimming view separates a
+ * modal presentation from an ordinary container, and its dimmed area says which earlier
+ * presentation the user can no longer reach. A sheet resting at an undimmed detent keeps that
+ * dimming view with user interaction disabled and touches reach the content under it, so the
+ * rule asserts containment only when the producer states the dimming view takes touches.
+ *
+ * Producers that report no UIKit class names or no `userInteractionEnabled` — the XCTest runner,
+ * whose own queries already omit modal-contained content — never trigger this rule.
+ */
+export function collectModalContainedIndexes(
+  nodes: readonly RawSnapshotNode[],
+): ReadonlySet<number> {
+  const childrenByParent = collectChildrenByParent(nodes);
+  const contained = new Set<number>();
+  for (const siblings of childrenByParent.values()) {
+    const covering = findCoveringPresentation(siblings, childrenByParent);
+    if (!covering) continue;
+    for (const sibling of siblings.slice(0, -1)) {
+      if (!isDimmedByPresentation(covering, sibling)) continue;
+      contained.add(sibling.index);
+      for (const descendant of collectSubtreeByParentLinks(sibling, childrenByParent)) {
+        contained.add(descendant.index);
+      }
+    }
+  }
+  return contained;
+}
+
+function findCoveringPresentation(
+  siblings: readonly RawSnapshotNode[],
+  childrenByParent: ReadonlyMap<number, RawSnapshotNode[]>,
+): CoveringPresentation | undefined {
+  const last = siblings.at(-1);
+  if (!last || !isPresentationContainer(last)) return undefined;
+  const dimming = (childrenByParent.get(last.index) ?? []).find(isPresentationDimmingView);
+  if (dimming?.userInteractionEnabled !== true || !isPositiveFiniteRect(dimming.rect)) {
+    return undefined;
+  }
+  return { container: last, dimmingRect: dimming.rect };
+}
+
+function isDimmedByPresentation(covering: CoveringPresentation, sibling: RawSnapshotNode): boolean {
+  return (
+    isPresentationContainer(sibling) &&
+    isPositiveFiniteRect(sibling.rect) &&
+    rectContains(covering.dimmingRect, sibling.rect)
+  );
+}
+
+function isPresentationContainer(node: RawSnapshotNode): boolean {
+  return hasRole(node, PRESENTATION_CONTAINER_ROLE);
+}
+
+function isPresentationDimmingView(node: RawSnapshotNode): boolean {
+  return hasRole(node, PRESENTATION_DIMMING_ROLE);
+}
+
+function hasRole(node: RawSnapshotNode, role: string): boolean {
+  return normalizeType(node.role ?? '') === role;
+}
diff --git a/packages/capture-kit/src/ios-snapshot-engine/geometry.ts b/packages/capture-kit/src/ios-snapshot-engine/geometry.ts
index 61b6345cea..f69739b62c 100644
--- a/packages/capture-kit/src/ios-snapshot-engine/geometry.ts
+++ b/packages/capture-kit/src/ios-snapshot-engine/geometry.ts
@@ -2,6 +2,7 @@ import type { Rect, RawSnapshotNode } from '@agent-device/kernel/snapshot';
 import { isGeometricallyActionable } from '@agent-device/kernel/rect';
 import { validateIosSnapshotGraph } from './graph.ts';
 import {
+  collectModalContainedIndexes,
   rootTraversal,
   traversalDecision,
   type BranchState,
@@ -22,13 +23,15 @@ export function foldIosSnapshot(
   options: IosSnapshotFoldOptions = {},
 ): { nodes: IosSnapshotPresentationNode[]; stats: IosSnapshotPresentationStats } {
   validateIosSnapshotGraph(nodes);
-  const hasChildren = buildChildPresence(nodes);
+  const modalContained = collectModalContainedIndexes(nodes);
+  const presentable = nodes.filter((node) => !modalContained.has(node.index));
+  const hasChildren = buildChildPresence(presentable);
   const states = new Map<number, BranchState>();
   const kept: IosSnapshotPresentationNode[] = [];
   const hints = new Map<number, { above: boolean; below: boolean }>();
   let parentClipLookups = 0;
 
-  for (const node of nodes) {
+  for (const node of presentable) {
     const parentState = readParentState(node, states, () => {
       parentClipLookups += 1;
     });
@@ -61,6 +64,7 @@ export function foldIosSnapshot(
       presentedNodeCount: presented.length,
       sourceNodeCount: nodes.length,
       parentClipLookups,
+      modalContainedNodeCount: modalContained.size,
     },
   };
 }
diff --git a/packages/capture-kit/src/ios-snapshot-engine/noise-structural.ts b/packages/capture-kit/src/ios-snapshot-engine/noise-structural.ts
index cafa3847d4..12a55ef743 100644
--- a/packages/capture-kit/src/ios-snapshot-engine/noise-structural.ts
+++ b/packages/capture-kit/src/ios-snapshot-engine/noise-structural.ts
@@ -1,6 +1,10 @@
 import type { RawSnapshotNode } from '@agent-device/kernel/snapshot';
 import { normalizeType } from '@agent-device/contracts/snapshot';
-import { collectChildrenByParent, type SnapshotTreeRuleContext } from './tree.ts';
+import {
+  collectChildrenByParent,
+  collectSubtreeByParentLinks,
+  type SnapshotTreeRuleContext,
+} from './tree.ts';
 
 export function collectIosStructuralIdentifierSuppression(
   nodes: RawSnapshotNode[],
@@ -27,21 +31,3 @@ export function collectIosStructuralIdentifierSuppression(
     context.suppressNode(node, content);
   }
 }
-
-function collectSubtreeByParentLinks(
-  root: RawSnapshotNode,
-  childrenByParent: ReadonlyMap<number, RawSnapshotNode[]>,
-): RawSnapshotNode[] {
-  const descendants: RawSnapshotNode[] = [];
-  const visited = new Set<number>([root.index]);
-  const pending = [...(childrenByParent.get(root.index) ?? [])];
-  while (pending.length > 0) {
-    const current = pending.pop();
-    if (!current || visited.has(current.index)) continue;
-    visited.add(current.index);
-    descendants.push(current);
-    const children = childrenByParent.get(current.index);
-    if (children) pending.push(...children);
-  }
-  return descendants;
-}
diff --git a/packages/capture-kit/src/ios-snapshot-engine/runner-presentation.ts b/packages/capture-kit/src/ios-snapshot-engine/runner-presentation.ts
index 4a48b11284..cbae8a042d 100644
--- a/packages/capture-kit/src/ios-snapshot-engine/runner-presentation.ts
+++ b/packages/capture-kit/src/ios-snapshot-engine/runner-presentation.ts
@@ -42,6 +42,7 @@ export function presentIosRunnerSnapshot(
       presentedNodeCount: compacted.nodes.length,
       sourceNodeCount: input.presentation.payload.nodes.length,
       parentClipLookups: validationStats.parentClipLookups,
+      modalContainedNodeCount: 0,
     },
   };
 }
diff --git a/packages/capture-kit/src/ios-snapshot-engine/tree.ts b/packages/capture-kit/src/ios-snapshot-engine/tree.ts
index 8cd1d5c77e..9b4621c63f 100644
--- a/packages/capture-kit/src/ios-snapshot-engine/tree.ts
+++ b/packages/capture-kit/src/ios-snapshot-engine/tree.ts
@@ -12,7 +12,9 @@ export type SnapshotTreeRuleContext = {
   suppressNode: (source: RawSnapshotNode, representatives: readonly RawSnapshotNode[]) => void;
 };
 
-export function collectChildrenByParent(nodes: RawSnapshotNode[]): Map<number, RawSnapshotNode[]> {
+export function collectChildrenByParent(
+  nodes: readonly RawSnapshotNode[],
+): Map<number, RawSnapshotNode[]> {
   const childrenByParent = new Map<number, RawSnapshotNode[]>();
   for (const node of nodes) {
     if (typeof node.parentIndex !== 'number') continue;
@@ -23,6 +25,25 @@ export function collectChildrenByParent(nodes: RawSnapshotNode[]): Map<number, R
   return childrenByParent;
 }
 
+/** A node's descendants, walked through parent links only so reported depths are not needed. */
+export function collectSubtreeByParentLinks(
+  root: RawSnapshotNode,
+  childrenByParent: ReadonlyMap<number, RawSnapshotNode[]>,
+): RawSnapshotNode[] {
+  const descendants: RawSnapshotNode[] = [];
+  const visited = new Set<number>([root.index]);
+  const pending = [...(childrenByParent.get(root.index) ?? [])];
+  while (pending.length > 0) {
+    const current = pending.pop();
+    if (!current || visited.has(current.index)) continue;
+    visited.add(current.index);
+    descendants.push(current);
+    const children = childrenByParent.get(current.index);
+    if (children) pending.push(...children);
+  }
+  return descendants;
+}
+
 const descendantEndPositionCache = new WeakMap<RawSnapshotNode[], number[]>();
 
 export function collectDescendants(
diff --git a/packages/capture-kit/src/ios-snapshot-engine/types.ts b/packages/capture-kit/src/ios-snapshot-engine/types.ts
index 29e4fb5bdc..91fd4392bc 100644
--- a/packages/capture-kit/src/ios-snapshot-engine/types.ts
+++ b/packages/capture-kit/src/ios-snapshot-engine/types.ts
@@ -20,6 +20,8 @@ export type IosSnapshotPresentationStats = Readonly<{
   presentedNodeCount: number;
   sourceNodeCount: number;
   parentClipLookups: number;
+  /** Sources the presentation cut removed because a later modal presentation dims them. */
+  modalContainedNodeCount: number;
 }>;
 
 export type IosSnapshotEnginePresentation = Readonly<{
diff --git a/packages/kernel/src/snapshot.ts b/packages/kernel/src/snapshot.ts
index 33eeafed20..ff57222c86 100644
--- a/packages/kernel/src/snapshot.ts
+++ b/packages/kernel/src/snapshot.ts
@@ -239,6 +239,8 @@ export type RawSnapshotNode = {
   selectionStart?: number;
   selectionEnd?: number;
   visibleToUser?: boolean;
+  /** UIKit `isUserInteractionEnabled`; absent means the producer did not read it, not false. */
+  userInteractionEnabled?: boolean;
   hittable?: boolean;
   depth?: number;
   parentIndex?: number;
diff --git a/packages/platform-apple/src/snapshot-source/fixtures/wire-vocabulary.json b/packages/platform-apple/src/snapshot-source/fixtures/wire-vocabulary.json
index 3b78906a73..6eacf669d6 100644
--- a/packages/platform-apple/src/snapshot-source/fixtures/wire-vocabulary.json
+++ b/packages/platform-apple/src/snapshot-source/fixtures/wire-vocabulary.json
@@ -1,6 +1,6 @@
 {
   "protocolVersion": 1,
-  "sourceVersion": "agent-device-simulator-ax-v1.6.0",
+  "sourceVersion": "agent-device-simulator-ax-v1.7.0",
   "requestKeys": [
     "verb",
     "requestId",
@@ -38,6 +38,7 @@
     "XC_kAXXCAttributeFrame",
     "XC_kAXXCAttributeAutomationType",
     "XC_kAXXCAttributeTraits",
+    "XC_kAXXCAttributeIsUserInteractionEnabled",
     "XC_kAXXCAttributeChildren"
   ]
 }
diff --git a/packages/platform-apple/src/snapshot-source/protocol.test.ts b/packages/platform-apple/src/snapshot-source/protocol.test.ts
index a2839aed01..4fda71db5f 100644
--- a/packages/platform-apple/src/snapshot-source/protocol.test.ts
+++ b/packages/platform-apple/src/snapshot-source/protocol.test.ts
@@ -142,7 +142,7 @@ test('wire vocabulary guard keeps TS and Objective-C literals aligned', async ()
   assert.deepEqual(wireVocabulary.responseKeys, SNAPSHOT_SOURCE_RESPONSE_KEYS);
   assert.deepEqual(wireVocabulary.attributeKeys, SNAPSHOT_SOURCE_ATTRIBUTE_KEYS);
   assert.match(nativeSource, /kProtocolVersion = 1/);
-  assert.match(nativeSource, /kSourceVersion = @"agent-device-simulator-ax-v1\.6\.0"/);
+  assert.match(nativeSource, /kSourceVersion = @"agent-device-simulator-ax-v1\.7\.0"/);
   for (const key of [
     ...wireVocabulary.requestKeys,
     ...wireVocabulary.responseKeys,
diff --git a/packages/platform-apple/src/snapshot-source/protocol.ts b/packages/platform-apple/src/snapshot-source/protocol.ts
index cb2f887f30..ce663f86ec 100644
--- a/packages/platform-apple/src/snapshot-source/protocol.ts
+++ b/packages/platform-apple/src/snapshot-source/protocol.ts
@@ -3,7 +3,7 @@ import { snapshotSourceError } from './errors.ts';
 import type { SnapshotSourceLimits } from './types.ts';
 
 export const SNAPSHOT_SOURCE_PROTOCOL_VERSION = 1;
-export const SNAPSHOT_SOURCE_VERSION = 'agent-device-simulator-ax-v1.6.0';
+export const SNAPSHOT_SOURCE_VERSION = 'agent-device-simulator-ax-v1.7.0';
 const FRAME_HEADER_BYTES = 4;
 
 export const SNAPSHOT_SOURCE_WIRE_KEYS = Object.freeze([
@@ -45,6 +45,7 @@ export const SNAPSHOT_SOURCE_ATTRIBUTE_KEYS = Object.freeze([
   'XC_kAXXCAttributeFrame',
   'XC_kAXXCAttributeAutomationType',
   'XC_kAXXCAttributeTraits',
+  'XC_kAXXCAttributeIsUserInteractionEnabled',
   'XC_kAXXCAttributeChildren',
 ] as const);
 
diff --git a/packages/platform-apple/src/snapshot-source/tree.test.ts b/packages/platform-apple/src/snapshot-source/tree.test.ts
index 23853eddc0..553c3a4e98 100644
--- a/packages/platform-apple/src/snapshot-source/tree.test.ts
+++ b/packages/platform-apple/src/snapshot-source/tree.test.ts
@@ -429,3 +429,27 @@ test('a window reporting the app box quarter-turned is counted as an unresolved
     0,
   );
 });
+
+test('the bridge tree publishes whether a dimming view takes touches', () => {
+  const dimming = (enabled?: unknown) => ({
+    [application]: 'UIDimmingView',
+    [frame]: { X: -390, Y: -844, Width: 1170, Height: 2532 },
+    ...(enabled === undefined ? {} : { XC_kAXXCAttributeIsUserInteractionEnabled: enabled }),
+    [children]: [],
+  });
+  const decode = (enabled?: unknown) =>
+    decodeSnapshotBridgeTree(
+      { [application]: 'Application', [children]: [dimming(enabled)] },
+      { truncated: false },
+      limits,
+    ).nodes[1];
+
+  assert.equal(decode(true)?.userInteractionEnabled, true);
+  assert.equal(decode(false)?.userInteractionEnabled, false, 'a sheet at an undimmed detent');
+  assert.equal(decode()?.userInteractionEnabled, undefined, 'an unread fact stays unknown');
+  assert.throws(
+    () => decode(1),
+    (error: unknown) =>
+      error instanceof SnapshotSourceError && error.failureCode === 'user-interaction-invalid',
+  );
+});
diff --git a/packages/platform-apple/src/snapshot-source/tree.ts b/packages/platform-apple/src/snapshot-source/tree.ts
index dd8322f78f..8fe1f6518f 100644
--- a/packages/platform-apple/src/snapshot-source/tree.ts
+++ b/packages/platform-apple/src/snapshot-source/tree.ts
@@ -20,6 +20,7 @@ const ATTRIBUTE = Object.freeze({
   frame: 'XC_kAXXCAttributeFrame',
   automationType: 'XC_kAXXCAttributeAutomationType',
   traits: 'XC_kAXXCAttributeTraits',
+  userInteractionEnabled: 'XC_kAXXCAttributeIsUserInteractionEnabled',
   children: 'XC_kAXXCAttributeChildren',
 });
 
@@ -245,6 +246,7 @@ function nodeFacts(
   // Publishes `selected: true` only when the selected bit is set and omits it otherwise — the same
   // shape the XCTest tree produces, so a `selected:` selector cannot tell the producers apart.
   const selected = traits === undefined || (traits & SELECTED_TRAIT) === 0n ? undefined : true;
+  const userInteractionEnabled = optionalBoolean(value[ATTRIBUTE.userInteractionEnabled]);
   return {
     index,
     ...(parentIndex === undefined ? {} : { parentIndex }),
@@ -265,6 +267,7 @@ function nodeFacts(
     ...(frame ? { rect: frame } : {}),
     ...(enabled === undefined ? {} : { enabled }),
     ...(selected === undefined ? {} : { selected }),
+    ...(userInteractionEnabled === undefined ? {} : { userInteractionEnabled }),
     depth,
   };
 }
@@ -395,6 +398,14 @@ function traitsFromGuest(value: unknown): bigint | undefined {
   return BigInt(value);
 }
 
+function optionalBoolean(value: unknown): boolean | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== 'boolean') {
+    throw snapshotSourceError('malformed-tree', 'user-interaction-invalid');
+  }
+  return value;
+}
+
 function optionalInteger(value: unknown): number | undefined {
   if (value === undefined || value === null) return undefined;
   if (!Number.isSafeInteger(value))
diff --git a/src/commands/capture/runtime/snapshot-unchanged.ts b/src/commands/capture/runtime/snapshot-unchanged.ts
index dab0fe96a8..aa249709ce 100644
--- a/src/commands/capture/runtime/snapshot-unchanged.ts
+++ b/src/commands/capture/runtime/snapshot-unchanged.ts
@@ -88,6 +88,7 @@ type ComparableSnapshotNode = Omit<
   | 'selectionStart'
   | 'selectionEnd'
   | 'visibleToUser'
+  | 'userInteractionEnabled'
   | 'inheritsLabel'
   | 'inheritsIdentifier'
 >;

From 5c19230713a42ca466fa0eed6fefa98a4a90cd27 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 24 Sep 2026 11:09:46 +0200
Subject: [PATCH 081/132] fix(apple-runner): resend a read only on the runner's
 busy refusal (#2863)

The transport's same-request resend also matched a generic flagged_retriable
row keyed on details.retriable, which tells a caller's poll to try again.
Startup-phase failures (runner_phase_budget_exhausted,
apple_toolchain_probe_unavailable) and external provider failures carry that
flag, so a read-only command resent them up to three times, each with a fresh
startup budget. Drop that row and the app_not_running row that undid it for
APP_NOT_RUNNING: #2804's runner_busy_refusal row, keyed on the RUNNER_BUSY
runner code, is now the only resend rule for a structured runner refusal.

Closes #2862
---
 CHANGELOG.md                                  |  8 ++
 .../runner-error-classification.test.ts       | 15 ++-
 .../__tests__/runner-recovery-wiring.test.ts  | 97 ++++++++++++++++++-
 .../src/runner/runner-error-classification.ts | 37 +++----
 4 files changed, 124 insertions(+), 33 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d63c20cf2e..45a21de44e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+- Changed (apple): a read-only runner command is resent inside the same request only when the
+  runner refused it as `RUNNER_BUSY`. Before, any `COMMAND_FAILED` carrying `details.retriable:
+  true` was sent up to three times. That flag tells a caller's own poll, such as `wait`, to try
+  again. It does not mean a resend is safe inside one request. A runner startup that ran out of its
+  budget (`runner_phase_budget_exhausted`) or could not read the Xcode toolchain
+  (`apple_toolchain_probe_unavailable`) now fails once, not three times with a fresh startup budget
+  each time. A `retriable` failure from an external Apple runner provider is also no longer resent.
+  The error keeps `retriable: true`, so the caller's next request still tries again. (#2862)
 - Fixed (mobile): a read taken right after a `scroll`, `swipe`, or `gesture swipe` no longer reports
   a definite miss when the surface never settled. When post-gesture stabilization ran out of budget
   on a surface still moving, `is visible` answered a plain `selector_not_found` and `is absent`
diff --git a/packages/platform-apple/src/runner/__tests__/runner-error-classification.test.ts b/packages/platform-apple/src/runner/__tests__/runner-error-classification.test.ts
index 64b379f792..2919324ad9 100644
--- a/packages/platform-apple/src/runner/__tests__/runner-error-classification.test.ts
+++ b/packages/platform-apple/src/runner/__tests__/runner-error-classification.test.ts
@@ -59,11 +59,16 @@ test('boot-shaped failures are not retryable', () => {
   );
 });
 
-test('an explicitly retriable flag wins over any message denial', () => {
-  const flagged = runnerConnectFailure('xcodebuild_exited_early', 'xcodebuild exited early', {
-    retriable: true,
-  });
-  assert.equal(isRetryableRunnerError(flagged), true);
+test('only the runner busy refusal earns a resend; a retriable flag alone does not', () => {
+  const busy = classifyRunnerReportedError('RUNNER_BUSY');
+  assert.equal(isRetryableRunnerError(new AppError(busy.code, 'busy', busy.details)), true);
+  const notRunning = classifyRunnerReportedError('APP_NOT_RUNNING');
+  assert.equal(notRunning.details.retriable, true);
+  assert.equal(
+    isRetryableRunnerError(new AppError(notRunning.code, 'not running', notRunning.details)),
+    false,
+  );
+  assert.equal(isRetryableRunnerError(commandFailed('boom', { retriable: true })), false);
 });
 
 test('retryable requires an AppError with COMMAND_FAILED', () => {
diff --git a/packages/platform-apple/src/runner/__tests__/runner-recovery-wiring.test.ts b/packages/platform-apple/src/runner/__tests__/runner-recovery-wiring.test.ts
index 5ca6489722..b71fe25732 100644
--- a/packages/platform-apple/src/runner/__tests__/runner-recovery-wiring.test.ts
+++ b/packages/platform-apple/src/runner/__tests__/runner-recovery-wiring.test.ts
@@ -1,12 +1,18 @@
 import assert from 'node:assert/strict';
 import { afterEach, beforeEach, expect, test, vi } from 'vitest';
 import { AppError } from '@agent-device/kernel/errors';
+import { resetAllProcessMemosForTests } from '@agent-device/kernel/ttl-memo';
 import { IOS_SIMULATOR } from './device-fixtures.ts';
 import type { ExecResult } from '@agent-device/host-kit/command';
 import type { RunnerSession } from '../runner-session.ts';
 import { appleRunnerTestHost } from '../test-host.ts';
 import { withAppleRunnerProvider } from '../runner-provider.ts';
-import type { RunnerCommand } from '../runner-contract.ts';
+import { classifyRunnerReportedError, type RunnerCommand } from '../runner-contract.ts';
+import {
+  createRunnerPhaseBudget,
+  requireRunnerPhaseRemainingMs,
+  resolveExpectedRunnerCacheMetadata,
+} from '../runner-cache-metadata.ts';
 import { startFakeRunnerServer, type FakeRunnerServer } from './fake-runner-server.ts';
 
 /**
@@ -298,7 +304,8 @@ test.each([undefined, 'get', 'accept', 'dismiss'] as const)(
   'alert action %s selects provider retries by mutation semantics',
   async (action) => {
     const commands: RunnerCommand[] = [];
-    const failure = new AppError('COMMAND_FAILED', 'response unavailable', { retriable: true });
+    const busy = classifyRunnerReportedError('RUNNER_BUSY');
+    const failure = new AppError(busy.code, 'runner busy', busy.details);
     const result = withAppleRunnerProvider(
       async (_device, command) => {
         commands.push(command);
@@ -346,3 +353,89 @@ test('a read refused over a not-running app is one definite answer, not a transp
   );
   assert.equal(invalidateRunnerSessionMock.mock.calls.length, 0);
 });
+
+test('a read the runner refused as busy is resent on the same session', async () => {
+  server = await startFakeRunnerServer({
+    snapshot: [
+      { kind: 'runnerError', code: 'RUNNER_BUSY', message: 'runner is draining' },
+      { kind: 'ok', data: { captured: true } },
+    ],
+    status: [
+      {
+        kind: 'ok',
+        data: {
+          lifecycleState: 'failed',
+          lifecycleErrorCode: 'RUNNER_BUSY',
+          lifecycleErrorMessage: 'runner is draining',
+        },
+      },
+    ],
+  });
+  seedSession(server.port);
+
+  assert.deepEqual(await runAppleRunnerCommand(IOS_SIMULATOR, { command: 'snapshot' }), {
+    captured: true,
+  });
+  assert.equal(server.requests.filter((request) => request.command === 'snapshot').length, 2);
+  assert.equal(invalidateRunnerSessionMock.mock.calls.length, 0);
+});
+
+// `retriable` on these tells the caller's next request to try again. Resending inside this request
+// would open a fresh startup budget per attempt, or second-guess a provider's own transport policy.
+const readSnapshot = () => runAppleRunnerCommand(IOS_SIMULATOR, { command: 'snapshot' });
+const sessionStarts = () => ensureRunnerSessionMock.mock.calls.length;
+
+test.each([
+  {
+    producer: 'a spent startup budget',
+    reason: 'runner_phase_budget_exhausted',
+    arrange: () => {
+      ensureRunnerSessionMock.mockImplementation(async () =>
+        requireRunnerPhaseRemainingMs(createRunnerPhaseBudget(0, undefined), 'runner_startup'),
+      );
+      return { run: readSnapshot, sends: sessionStarts };
+    },
+  },
+  {
+    producer: 'an unreadable toolchain',
+    reason: 'apple_toolchain_probe_unavailable',
+    arrange: () => {
+      resetAllProcessMemosForTests();
+      appleRunnerTestHost.update({
+        runCmdSync: () => ({ exitCode: 1, stdout: '', stderr: 'xcode-select: error' }),
+      });
+      ensureRunnerSessionMock.mockImplementation(async () =>
+        resolveExpectedRunnerCacheMetadata(IOS_SIMULATOR),
+      );
+      return { run: readSnapshot, sends: sessionStarts };
+    },
+  },
+  {
+    producer: 'an external runner provider',
+    reason: 'provider_transport_unavailable',
+    arrange: () => {
+      let calls = 0;
+      const provider = async () => {
+        calls += 1;
+        throw new AppError('COMMAND_FAILED', 'provider transport unavailable', {
+          reason: 'provider_transport_unavailable',
+          retriable: true,
+        });
+      };
+      return {
+        run: () => withAppleRunnerProvider(provider, { deviceId: IOS_SIMULATOR.id }, readSnapshot),
+        sends: () => calls,
+      };
+    },
+  },
+])('a retriable read failure from $producer is not resent', async ({ reason, arrange }) => {
+  const { run, sends } = arrange();
+
+  await assert.rejects(run(), (error: unknown) => {
+    assert.ok(error instanceof AppError);
+    assert.equal(error.details?.reason, reason);
+    assert.equal(error.details?.retriable, true);
+    return true;
+  });
+  assert.equal(sends(), 1);
+});
diff --git a/packages/platform-apple/src/runner/runner-error-classification.ts b/packages/platform-apple/src/runner/runner-error-classification.ts
index aa8e1c072b..97dd1b393f 100644
--- a/packages/platform-apple/src/runner/runner-error-classification.ts
+++ b/packages/platform-apple/src/runner/runner-error-classification.ts
@@ -9,11 +9,7 @@ import {
   type IosDeveloperDiskImageState,
   type IosDeveloperModeState,
 } from './host.ts';
-import {
-  APP_NOT_RUNNING_RUNNER_CODE,
-  MAIN_THREAD_TIMEOUT_RUNNER_CODE,
-  RUNNER_BUSY_RUNNER_CODE,
-} from './runner-contract.ts';
+import { MAIN_THREAD_TIMEOUT_RUNNER_CODE, RUNNER_BUSY_RUNNER_CODE } from './runner-contract.ts';
 
 export const RUNNER_CACHE_RECOVERY_HINT =
   'If runner build products look stale or corrupted, run `pnpm clean:xcuitest` in a local checkout, or remove ~/.agent-device/apple-runner/derived, then retry.';
@@ -21,7 +17,7 @@ export const RUNNER_CACHE_RECOVERY_HINT =
 /**
  * Details evidence a rule requires beyond code and message. A predicate rather than a
  * fixed vocabulary because the useful evidence is a shape: a recorded deadline, a
- * preflight marker, a retriable flag. Every predicate below names one.
+ * preflight marker, a runner error code. Every predicate below names one.
  */
 type RunnerErrorDetailsMatch = (details: AppErrorDetails) => boolean;
 
@@ -69,9 +65,12 @@ type RunnerErrorMatch = {
   details?: RunnerErrorDetailsMatch;
 };
 
-const hasRetriableFlag: RunnerErrorDetailsMatch = (details) => details.retriable === true;
-const hasAppNotRunningRunnerCode: RunnerErrorDetailsMatch = (details) =>
-  details.runnerErrorCode === APP_NOT_RUNNING_RUNNER_CODE;
+/**
+ * The runner refused the command before running it while abandoned main-thread work drains (#1105).
+ * A resend keys on this code, never on `details.retriable`: that flag tells a caller's poll to try
+ * again, and its other producers (a not-running app, a spent startup budget, an unavailable
+ * toolchain probe, an external provider) must not be resent inside one request.
+ */
 const hasRunnerBusyCode: RunnerErrorDetailsMatch = (details) =>
   details.runnerErrorCode === RUNNER_BUSY_RUNNER_CODE;
 /**
@@ -210,11 +209,8 @@ const PROFILE_UNUSABLE: RunnerErrorRule['buildFailure'] = {
  * and since #2680 so does the one classification of startup failures — a row
  * carries recovery verdicts, a `buildFailure` reason and hint, or both.
  * Per axis, the FIRST matching rule that defines the axis wins — which is why
- * `flagged_retriable` precedes the denials (an explicitly retriable error
- * stays retriable whatever its message says), and `usbmux_device_unattached`
- * sits first (retrying cannot attach a cable, and its typed verdict carries
- * the recovery hint a generic connect failure would replace). `app_not_running`
- * precedes it too: its retriable flag is for the caller's poll, not a resend.
+ * `usbmux_device_unattached` sits first (retrying cannot attach a cable, and its
+ * typed verdict carries the recovery hint a generic connect failure would replace).
  */
 export const RUNNER_ERROR_RULES: readonly RunnerErrorRule[] = [
   {
@@ -223,22 +219,11 @@ export const RUNNER_ERROR_RULES: readonly RunnerErrorRule[] = [
     verdicts: { connectRetry: false },
   },
   {
-    reason: 'app_not_running',
-    match: { code: 'COMMAND_FAILED', details: hasAppNotRunningRunnerCode },
-    verdicts: { retryable: false, connectRetry: false },
-  },
-  {
-    // Named before the generic retriable flag so diagnostics say what refused, not that a flag
-    // was set. Nothing ran: the runner answered before dispatching the command (#1105).
+    // Nothing ran: the runner answered before dispatching the command (#1105).
     reason: 'runner_busy_refusal',
     match: { code: 'COMMAND_FAILED', details: hasRunnerBusyCode },
     verdicts: { retryable: true, connectRetry: true, drainResend: true },
   },
-  {
-    reason: 'flagged_retriable',
-    match: { code: 'COMMAND_FAILED', details: hasRetriableFlag },
-    verdicts: { retryable: true, connectRetry: true },
-  },
   {
     // Says `artifactSuspect: false` on purpose: a boot that cannot compile is not cured by wiping
     // derived data.

From 1b31bee64d58c8a240c491496de257346ecc4e0f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 24 Sep 2026 11:35:18 +0200
Subject: [PATCH 082/132] fix(providers): name the simulator HID helper in the
 fold refusal hints (#2873)

Since #2762 fold poses a foldable iPhone simulator by spawning a HID sender
inside a host simulator (simctl spawn), not through Xcode Device Hub. Reword
the Limrun and WebDriver refusal hints and the comments that still described
the Device Hub path. Refusal reasons and codes are unchanged.

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 packages/contracts/src/navigation.ts                       | 2 +-
 packages/platform-android/src/runtime.test.ts              | 3 ++-
 packages/platform-web/src/runtime.test.ts                  | 3 ++-
 packages/provider-limrun/src/interaction-operations.ts     | 7 +++++--
 packages/provider-webdriver/src/platform-runtime.ts        | 2 +-
 .../provider-scenarios/provider-device-runtime.fixtures.ts | 3 ++-
 .../provider-ios-runner-transport.test.ts                  | 6 +++---
 7 files changed, 16 insertions(+), 10 deletions(-)

diff --git a/packages/contracts/src/navigation.ts b/packages/contracts/src/navigation.ts
index 3d5c6c1d62..fca6600b99 100644
--- a/packages/contracts/src/navigation.ts
+++ b/packages/contracts/src/navigation.ts
@@ -52,7 +52,7 @@ export type OrientationCommandResult = {
  * `fold` — `{ action: 'fold', pose, hingeAngleDegrees, screen?, message }`.
  *
  * Unlike `orientation`, there is no unconfirmed variant: the Apple owner reads the hinge angle
- * back from CoreDevice after pressing the Device Hub pose control, and reports a pose only when
+ * back from CoreDevice after the simulator HID helper sends the pose, and reports a pose only when
  * that reading agrees with the request. `screen` names the panel the device lights afterwards and
  * that panel's native point size (ADR 0025); it is the panel's geometry, not the app viewport, so a
  * caller must take a fresh snapshot before placing a tap.
diff --git a/packages/platform-android/src/runtime.test.ts b/packages/platform-android/src/runtime.test.ts
index bb0d47b805..011afb24f9 100644
--- a/packages/platform-android/src/runtime.test.ts
+++ b/packages/platform-android/src/runtime.test.ts
@@ -225,7 +225,8 @@ test('Android refuses the fold fact on every kind', async () => {
       createAndroidPlatformRuntime(androidNavigationHost()),
       runtimeDevice,
     );
-    // A foldable hinge is posed through Xcode Device Hub; no adb surface poses one.
+    // fold drives only foldable iPhone simulators; the Android emulator posture control is not
+    // driven yet.
     expect(binding.facts.operations.setFoldPose).toEqual({
       available: false,
       reason: 'unsupported-platform-leaf',
diff --git a/packages/platform-web/src/runtime.test.ts b/packages/platform-web/src/runtime.test.ts
index f25bccc885..5ba868a300 100644
--- a/packages/platform-web/src/runtime.test.ts
+++ b/packages/platform-web/src/runtime.test.ts
@@ -214,7 +214,8 @@ test('clipboard, the app switcher, app events, settings and alerts carry no web
     'appSwitcher',
     // The Action Button is iPhone/iPad hardware with no web analogue at all.
     'actionButton',
-    // A foldable hinge is posed through Xcode Device Hub; the web target has none.
+    // A foldable hinge is posed through the host's iOS simulator HID helper; the web target has
+    // none.
     'setFoldPose',
     'triggerAppEvent',
     // R58/R59: the retired `settings` and `alert` descriptors declared no web leaf either.
diff --git a/packages/provider-limrun/src/interaction-operations.ts b/packages/provider-limrun/src/interaction-operations.ts
index 1c5796bc30..18a0acb9da 100644
--- a/packages/provider-limrun/src/interaction-operations.ts
+++ b/packages/provider-limrun/src/interaction-operations.ts
@@ -341,11 +341,14 @@ export function limrunSystemButtonOperationFacts(
   });
 }
 
-/** A foldable hinge is posed through the host's Xcode Device Hub, which no Limrun session has. */
+/**
+ * `fold` sends a HID hinge event through a helper the daemon host spawns inside one of its own iOS
+ * simulators with `simctl spawn`; a Limrun session's device is not a host simulator.
+ */
 export const LIMRUN_FOLD_UNAVAILABLE = Object.freeze({
   available: false,
   reason: 'unsupported-provider-mode',
-  hint: 'fold poses a foldable iPhone simulator through Xcode Device Hub on the host, which no Limrun session exposes.',
+  hint: 'fold runs a HID helper through simctl spawn inside a foldable iPhone simulator on the daemon host; a Limrun session has no such simulator.',
 } as const);
 
 /** The fold refusal both Limrun legs share. */
diff --git a/packages/provider-webdriver/src/platform-runtime.ts b/packages/provider-webdriver/src/platform-runtime.ts
index 5302e3d955..ae377d493b 100644
--- a/packages/provider-webdriver/src/platform-runtime.ts
+++ b/packages/provider-webdriver/src/platform-runtime.ts
@@ -245,7 +245,7 @@ const systemButtonUnavailable = Object.freeze({
 const foldUnavailable = Object.freeze({
   available: false,
   reason: 'unsupported-provider-mode',
-  hint: 'fold poses a foldable iPhone simulator through Xcode Device Hub, which no WebDriver backend exposes.',
+  hint: 'fold runs a HID helper through simctl spawn inside a foldable iPhone simulator on the daemon host; a WebDriver backend has no such simulator.',
 } as const);
 
 /**
diff --git a/test/integration/provider-scenarios/provider-device-runtime.fixtures.ts b/test/integration/provider-scenarios/provider-device-runtime.fixtures.ts
index 06a4785f7e..e5a6fbe438 100644
--- a/test/integration/provider-scenarios/provider-device-runtime.fixtures.ts
+++ b/test/integration/provider-scenarios/provider-device-runtime.fixtures.ts
@@ -270,7 +270,8 @@ function providerScenarioRuntimeFacts(
       // hardware exists on the iPhone/iPad leaf only, so the fixture reads the same kernel rule the
       // Apple owner's fact reads instead of restating it (#2699).
       actionButton: hasAppleActionButton(device) ? fakeProviderAvailable : fakeProviderUnavailable,
-      // A provider session has no Device Hub on the host, so no fixture leg poses a hinge.
+      // A provider session has no host simulator for the fold HID helper, so no fixture leg poses
+      // a hinge.
       setFoldPose: fakeProviderUnavailable,
       // Provider-owned iOS keyboard actions ride the same runner transport the shared interactor
       // does (#1297): a fixture scenario that can drive the interactor at all can drive these.
diff --git a/test/integration/provider-scenarios/provider-ios-runner-transport.test.ts b/test/integration/provider-scenarios/provider-ios-runner-transport.test.ts
index a9094e6f01..d8619d861d 100644
--- a/test/integration/provider-scenarios/provider-ios-runner-transport.test.ts
+++ b/test/integration/provider-scenarios/provider-ios-runner-transport.test.ts
@@ -132,9 +132,9 @@ test('provider transport carries the Action Button press without an app activati
   });
 });
 
-// A hinge pose is posed through Xcode Device Hub on the host, which a provider-owned device has no
-// access to, so the provider fixture states the refusal cell and admission refuses before anything
-// reaches the transport: no runner call, no local Device Hub press.
+// A hinge pose is sent by a HID helper the host spawns inside a local iOS simulator, which a
+// provider-owned device is not, so the provider fixture states the refusal cell and admission
+// refuses before anything reaches the transport.
 test('provider transport refuses a fold before any runner traffic', async () => {
   await withProviderScenarioResource(createInteractorSeamWorld, async ({ daemon, calls }) => {
     const lease = await allocateLease(daemon);

From fd241232c5df243386f0a5a2e54fab721228f9f3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 24 Sep 2026 11:35:31 +0200
Subject: [PATCH 083/132] fix(selectors): retire the stored tree after a side
 effect or a native read (#2869)

Selector reads reuse the session's stored tree for 750 ms after its
capture. Two events outdated that tree without replacing it: a wait text
satisfied by the owner's native text reading after an earlier miss
capture, and a mutation that captured nothing. The next get or is then
reused the pre-change tree and reported Selector did not match.

Every side-effect seam (expireRefFrame) and every native text reading now
marks the session's current tree outdated, and the session cache tier
refuses an outdated tree. The mark is keyed by the tree, so it survives
the session record copies that reset the per-session runtime revision.

Closes #2866
---
 CHANGELOG.md                                  |  7 +++
 docs/agents/selector-capture.md               |  4 +-
 src/daemon/__tests__/wait-runtime.test.ts     | 48 +++++++++++++++++
 .../__tests__/interaction-touch-press.test.ts | 53 +++++++++++++++++++
 src/daemon/ref-frame.ts                       | 16 ++++++
 src/daemon/selector-capture-runtime.ts        |  3 +-
 src/daemon/selector-runtime-backend.ts        | 21 ++++----
 7 files changed, 140 insertions(+), 12 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 45a21de44e..b94914b0e0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,13 @@
   (`apple_toolchain_probe_unavailable`) now fails once, not three times with a fresh startup budget
   each time. A `retriable` failure from an external Apple runner provider is also no longer resent.
   The error keeps `retriable: true`, so the caller's next request still tries again. (#2862)
+- Fixed (mobile): a `get`, `is`, `find`, or `wait` selector read no longer answers from a tree that
+  a later command outdated. Selector reads reuse the session's stored tree for 750 ms after its
+  capture. Two cases outdated that tree without replacing it: a `wait text` satisfied by the
+  owner's native text reading after an earlier miss capture, and a mutation that captured nothing
+  (for example a coordinate `press`). The next read then reused the pre-change tree and could
+  report `Selector did not match` for an element that was on screen. A side effect or a native read
+  now retires the stored tree, and the next read captures again.
 - Fixed (mobile): a read taken right after a `scroll`, `swipe`, or `gesture swipe` no longer reports
   a definite miss when the surface never settled. When post-gesture stabilization ran out of budget
   on a surface still moving, `is visible` answered a plain `selector_not_found` and `is absent`
diff --git a/docs/agents/selector-capture.md b/docs/agents/selector-capture.md
index 44c3b89ccf..6a6411f457 100644
--- a/docs/agents/selector-capture.md
+++ b/docs/agents/selector-capture.md
@@ -9,7 +9,9 @@ These are cross-route behavior requirements; their rationale and owning decision
   resolution; ambiguity and other runner failures remain failures.
 - Regular selector reads are capture-backed. `@ref` resolves against its authorized ref frame,
   while `get`, `is`, `find`, and `wait` selectors capture through the backend. Polling bypasses the
-  snapshot cache, as do active freshness recovery and stabilization.
+  snapshot cache, as do active freshness recovery and stabilization. The cache serves a stored tree
+  only while it is the newest observation: a side-effect seam or a native read such as `wait
+  text`'s owner text reading retires it.
 - Sparse capture verdicts are observable failures and never replace the session snapshot. Only a
   user-facing snapshot may publish a fallback screenshot; internal polling must not create one
   artifact per attempt.
diff --git a/src/daemon/__tests__/wait-runtime.test.ts b/src/daemon/__tests__/wait-runtime.test.ts
index 4177872305..fe84f4fa1c 100644
--- a/src/daemon/__tests__/wait-runtime.test.ts
+++ b/src/daemon/__tests__/wait-runtime.test.ts
@@ -26,6 +26,7 @@ import { unavailableDeploymentSnapshotAndShutdownOperationFacts } from '../../__
 import type { BindDeviceRuntime, InspectDeviceRuntimeFacts } from '../request-runtime-binding.ts';
 import { handleSnapshotCommands } from '../handlers/snapshot.ts';
 import { resolveBoundSelectorCapture } from '../selector-capture-binding.ts';
+import { dispatchGetViaRuntime } from '../selector-runtime.ts';
 import type { DaemonRequest } from '../daemon-request.ts';
 
 const webDevice = {
@@ -389,6 +390,53 @@ test('a text wait is satisfied by the owner native reading when the tree never c
   expect(harness.captureSnapshot).toHaveBeenCalled();
 });
 
+test('a read after a natively satisfied text wait captures instead of reusing the older tree', async () => {
+  // Poll 1: the native reading misses and the capture still shows the previous screen, which it
+  // publishes to the session. The app then navigates, and poll 2's native reading sees the
+  // destination, so the stored tree is older than the observation that satisfied the wait.
+  let nativeReads = 0;
+  const harness = waitRuntimeHarness({
+    findText: available,
+    findTextAnswers: () => {
+      nativeReads += 1;
+      return nativeReads > 1;
+    },
+    nodesPerPoll: [
+      [{ index: 0, depth: 0, type: 'StaticText', label: 'Home' }],
+      [
+        { index: 0, depth: 0, type: 'StaticText', label: 'Automation lab' },
+        { index: 1, depth: 0, type: 'StaticText', label: 'cold.start' },
+      ],
+    ],
+  });
+  const {
+    response: waited,
+    session,
+    sessionStore,
+  } = await runWait(['text', 'Automation lab', '2000'], harness);
+  expect(waited).toMatchObject({ ok: true, data: { text: 'Automation lab' } });
+  expect(harness.captureSnapshot).toHaveBeenCalledOnce();
+
+  const read = await dispatchGetViaRuntime({
+    req: {
+      command: 'get',
+      positionals: ['text', 'label="cold.start"'],
+      token: 't',
+      session: session.name,
+      flags: {},
+      meta: { requestId: 'wait-runtime-get' },
+    } as unknown as DaemonRequest,
+    sessionName: session.name,
+    logPath: '/tmp/daemon.log',
+    sessionStore,
+    inspectFacts: harness.inspectFacts,
+    bindDevice: harness.bindDevice,
+  });
+
+  expect(read).toMatchObject({ ok: true, data: { text: 'cold.start' } });
+  expect(harness.captureSnapshot).toHaveBeenCalledTimes(2);
+});
+
 test('a satisfied native reading short-circuits the poll without capturing', async () => {
   const harness = waitRuntimeHarness({
     findText: available,
diff --git a/src/daemon/interaction/internal/__tests__/interaction-touch-press.test.ts b/src/daemon/interaction/internal/__tests__/interaction-touch-press.test.ts
index d12d43c8eb..be2046aeda 100644
--- a/src/daemon/interaction/internal/__tests__/interaction-touch-press.test.ts
+++ b/src/daemon/interaction/internal/__tests__/interaction-touch-press.test.ts
@@ -1,5 +1,6 @@
 import { test, expect, vi, beforeEach } from 'vitest';
 import { attachRefs } from '@agent-device/kernel/snapshot';
+import { makeIosSession } from '../../../../__tests__/test-utils/session-factories.ts';
 import { makeSessionStore } from '../../../../__tests__/test-utils/store-factory.ts';
 import { handleInteractionCommands } from '../../index.ts';
 import {
@@ -391,3 +392,55 @@ test('#1654: the shared guards still run on the pre-resolved node', async () =>
   }
   expect(readPressPoint(mockTapPoint)).toBeUndefined();
 });
+
+test('a read right after a press captures the post-tap screen instead of reusing the pre-tap tree', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'read-after-press';
+  sessionStore.set(sessionName, makeIosSession(sessionName, { appBundleId: 'com.example.app' }));
+  const screen = (step: string) => ({
+    backend: 'xctest' as const,
+    producer: 'apple-runner' as const,
+    nodes: [
+      { index: 0, depth: 0, type: 'Application', rect: { x: 0, y: 0, width: 393, height: 852 } },
+      {
+        index: 1,
+        depth: 1,
+        parentIndex: 0,
+        type: 'Button',
+        label: 'Next',
+        rect: { x: 24, y: 120, width: 120, height: 44 },
+        enabled: true,
+        hittable: true,
+      },
+      {
+        index: 2,
+        depth: 1,
+        parentIndex: 0,
+        type: 'StaticText',
+        label: step,
+        identifier: 'step',
+        rect: { x: 24, y: 220, width: 320, height: 24 },
+      },
+    ],
+  });
+  mockCaptureSnapshotForSession
+    .mockResolvedValueOnce(screen('Step 1'))
+    .mockResolvedValue(screen('Step 2'));
+  const run = async (command: string, positionals: string[]) =>
+    await handleInteractionCommands({
+      req: { token: 't', session: sessionName, command, positionals, flags: {} },
+      sessionName,
+      sessionStore,
+      contextFromFlags,
+      ...getRuntimeBindings(),
+    });
+
+  expect(await run('is', ['visible', 'label=Next'])).toMatchObject({ ok: true });
+  expect(await run('press', ['84', '142'])).toMatchObject({ ok: true });
+  expect(mockCaptureSnapshotForSession).toHaveBeenCalledTimes(1);
+
+  const read = await run('get', ['text', 'id="step"']);
+
+  expect(read).toMatchObject({ ok: true, data: { text: 'Step 2' } });
+  expect(mockCaptureSnapshotForSession).toHaveBeenCalledTimes(2);
+});
diff --git a/src/daemon/ref-frame.ts b/src/daemon/ref-frame.ts
index bdb5e2e341..b51c332084 100644
--- a/src/daemon/ref-frame.ts
+++ b/src/daemon/ref-frame.ts
@@ -10,6 +10,7 @@ import {
 import type { SessionState } from './session-state.ts';
 
 const runtimeRevisions = new WeakMap<SessionState, number>();
+const outdatedObservations = new WeakSet<SnapshotState>();
 
 /**
  * ADR 0014 session ref-frame lifetime — the authorization model for mutation
@@ -89,10 +90,25 @@ export function refFrameTree(session: SessionState): SnapshotState | undefined {
  */
 export function expireRefFrame(session: SessionState): void {
   advanceSessionRuntimeRevision(session);
+  markSessionSnapshotOutdated(session);
   session.refFrame = expiredRefFrame(refFrame(session));
   session.snapshotScopeSource = undefined;
 }
 
+/**
+ * Record that the device was observed or changed after the session's stored tree was
+ * captured: a side-effect seam above, or a native read that produces no tree (such as `wait
+ * text`'s owner text reading). An outdated tree stays the session's latest stored observation,
+ * but a selector read never reuses it in place of a capture.
+ */
+export function markSessionSnapshotOutdated(session: SessionState): void {
+  if (session.snapshot) outdatedObservations.add(session.snapshot);
+}
+
+export function isOutdatedObservation(snapshot: SnapshotState): boolean {
+  return outdatedObservations.has(snapshot);
+}
+
 /**
  * Monotonic, daemon-private revision for side-effect lineage. Unlike the
  * client-visible snapshot/ref generations, this advances for every possible
diff --git a/src/daemon/selector-capture-runtime.ts b/src/daemon/selector-capture-runtime.ts
index 1b24f5510a..bfbe7849c5 100644
--- a/src/daemon/selector-capture-runtime.ts
+++ b/src/daemon/selector-capture-runtime.ts
@@ -15,6 +15,7 @@ import { captureSnapshot } from './snapshot-capture.ts';
 import { setSessionSnapshot } from './session-snapshot.ts';
 import { getActiveAndroidSnapshotFreshness } from './session-snapshot-freshness.ts';
 import { isPostGestureStabilizationPending } from './deferred-interaction-outcome.ts';
+import { isOutdatedObservation } from './ref-frame.ts';
 import type { BoundSelectorCapture } from './selector-capture-binding.ts';
 import { buildRuntimeCaptureInput } from './snapshot-runtime-capture-input.ts';
 import { isLegacySparseIosInteractiveSnapshot } from '@agent-device/selectors/absence-observation';
@@ -258,7 +259,7 @@ function reusableSessionSnapshot(params: {
 }): SnapshotState | undefined {
   const { session, timestamp, request } = params;
   const snapshot = session?.snapshot;
-  if (!snapshot) return undefined;
+  if (!snapshot || isOutdatedObservation(snapshot)) return undefined;
   if (!canUseSessionSnapshotCache(session, request)) return undefined;
   if (!isFreshSelectorSnapshot(snapshot, timestamp)) return undefined;
   if (snapshot.presentationKey !== presentationKeyFor(request)) return undefined;
diff --git a/src/daemon/selector-runtime-backend.ts b/src/daemon/selector-runtime-backend.ts
index a256ba0ec1..2348d31c3f 100644
--- a/src/daemon/selector-runtime-backend.ts
+++ b/src/daemon/selector-runtime-backend.ts
@@ -12,6 +12,7 @@ import { createDaemonRuntimeSessionStore } from './runtime-session.ts';
 import { contextFromFlags, type BoundContextFromFlags } from './context.ts';
 import { readTextForNode } from './selector-text-runtime.ts';
 import { setSessionSnapshot } from './session-snapshot.ts';
+import { markSessionSnapshotOutdated } from './ref-frame.ts';
 import { SessionStore } from './session-store.ts';
 import type { DaemonRequest, DaemonResponse } from './daemon-request.ts';
 import type { SessionState } from './session-state.ts';
@@ -220,16 +221,16 @@ function createSelectorBackend(params: SelectorRuntimeDeviceParams): AgentDevice
     // reports `found: false` and the poll consults the canonical tree.
     ...(boundFindText
       ? {
-          findText: async (context: BackendCommandContext, text: string) => ({
-            found: (
-              await boundFindText({
-                text,
-                options: { appBundleId: session?.appBundleId, surface: session?.surface },
-                execution: runnerExecution,
-                ...(context.signal ? { signal: context.signal } : {}),
-              })
-            ).found,
-          }),
+          findText: async (context: BackendCommandContext, text: string) => {
+            const { found } = await boundFindText({
+              text,
+              options: { appBundleId: session?.appBundleId, surface: session?.surface },
+              execution: runnerExecution,
+              ...(context.signal ? { signal: context.signal } : {}),
+            });
+            if (session) markSessionSnapshotOutdated(session);
+            return { found };
+          },
         }
       : {}),
   };

From 6debef0634d6dfdb998891a47d32e2bb5b7b95ea Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 24 Sep 2026 11:35:42 +0200
Subject: [PATCH 084/132] fix(ios-runner): adopt the scene lifecycle so the
 host app launches on the iOS 27 SDK (#2867)

* fix(ios-runner): adopt the scene lifecycle so the host app launches on the iOS 27 SDK

Built with the Xcode 27 SDK, UIKit traps a legacy app-delegate app at launch
in UIApplicationEvaluateRuntimeIssueForNoSceneLifecycleAdoption, so every
XCTest that launched the runner host app failed on iOS 27 runtimes.

The host app now uses one scene delegate that owns the window on iOS, tvOS
and visionOS. A single-scene UIApplicationSceneManifest naming that delegate
is merged into the generated Info.plist for the UIKit SDKs; the macOS AppKit
host is unchanged. The legacy UIScreen-sized app-delegate window and the
visionOS-only configurationForConnectingSceneSession path are removed.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* docs(agents): tie the UIScene launch trap to the iOS 27 SDK on 27.0 and 27.1

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .../project.pbxproj                           | 17 +++++++++
 .../AgentDeviceRunner/AgentDeviceRunnerApp.m  | 37 +------------------
 .../AgentDeviceRunner/Info.plist              | 23 ++++++++++++
 docs/agents/device-verification.md            |  4 +-
 4 files changed, 43 insertions(+), 38 deletions(-)
 create mode 100644 apple/runner/AgentDeviceRunner/AgentDeviceRunner/Info.plist

diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunner.xcodeproj/project.pbxproj b/apple/runner/AgentDeviceRunner/AgentDeviceRunner.xcodeproj/project.pbxproj
index 506ee028df..f6c7706c48 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunner.xcodeproj/project.pbxproj
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunner.xcodeproj/project.pbxproj
@@ -21,9 +21,22 @@
 		20EA2EDD2F2CFC7C001CF0EF /* AgentDeviceRunnerUITests.xctest */ = {isa = PBXFileReference; explicitFileType = wrapper.cfbundle; includeInIndex = 0; path = AgentDeviceRunnerUITests.xctest; sourceTree = BUILT_PRODUCTS_DIR; };
 /* End PBXFileReference section */
 
+/* Begin PBXFileSystemSynchronizedBuildFileExceptionSet section */
+		20EA2EF02F2CFC7C001CF0EF /* Exceptions for "AgentDeviceRunner" folder in "AgentDeviceRunner" target */ = {
+			isa = PBXFileSystemSynchronizedBuildFileExceptionSet;
+			membershipExceptions = (
+				Info.plist,
+			);
+			target = 20EA2EC52F2CFC7B001CF0EF /* AgentDeviceRunner */;
+		};
+/* End PBXFileSystemSynchronizedBuildFileExceptionSet section */
+
 /* Begin PBXFileSystemSynchronizedRootGroup section */
 		20EA2EC82F2CFC7B001CF0EF /* AgentDeviceRunner */ = {
 			isa = PBXFileSystemSynchronizedRootGroup;
+			exceptions = (
+				20EA2EF02F2CFC7C001CF0EF /* Exceptions for "AgentDeviceRunner" folder in "AgentDeviceRunner" target */,
+			);
 			path = AgentDeviceRunner;
 			sourceTree = "<group>";
 		};
@@ -352,6 +365,8 @@
 				DEVELOPMENT_TEAM = 2S799L9W4M;
 				ENABLE_PREVIEWS = YES;
 				GENERATE_INFOPLIST_FILE = YES;
+				INFOPLIST_FILE = AgentDeviceRunner/Info.plist;
+				"INFOPLIST_FILE[sdk=macosx*]" = "";
 				INFOPLIST_KEY_UIApplicationSceneManifest_Generation = NO;
 				INFOPLIST_KEY_UIApplicationSupportsIndirectInputEvents = YES;
 				INFOPLIST_KEY_UILaunchScreen_Generation = YES;
@@ -386,6 +401,8 @@
 				DEVELOPMENT_TEAM = 2S799L9W4M;
 				ENABLE_PREVIEWS = YES;
 				GENERATE_INFOPLIST_FILE = YES;
+				INFOPLIST_FILE = AgentDeviceRunner/Info.plist;
+				"INFOPLIST_FILE[sdk=macosx*]" = "";
 				INFOPLIST_KEY_UIApplicationSceneManifest_Generation = NO;
 				INFOPLIST_KEY_UIApplicationSupportsIndirectInputEvents = YES;
 				INFOPLIST_KEY_UILaunchScreen_Generation = YES;
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunner/AgentDeviceRunnerApp.m b/apple/runner/AgentDeviceRunner/AgentDeviceRunner/AgentDeviceRunnerApp.m
index 937f0f3d59..08da7d0762 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunner/AgentDeviceRunnerApp.m
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunner/AgentDeviceRunnerApp.m
@@ -319,7 +319,7 @@ - (void)viewDidLoad {
 
 @end
 
-#if defined(TARGET_OS_VISION) && TARGET_OS_VISION
+// UIApplicationSceneManifest in Info.plist names this class; a rename must update the manifest.
 @interface AgentDeviceRunnerSceneDelegate : UIResponder <UIWindowSceneDelegate>
 @property(nonatomic, strong) UIWindow *window;
 @end
@@ -342,46 +342,11 @@ - (void)scene:(UIScene *)scene
 }
 
 @end
-#endif
 
 @interface AgentDeviceRunnerAppDelegate : UIResponder <UIApplicationDelegate>
-@property(nonatomic, strong) UIWindow *window;
 @end
 
 @implementation AgentDeviceRunnerAppDelegate
-
-- (BOOL)application:(UIApplication *)application
-    didFinishLaunchingWithOptions:(NSDictionary<UIApplicationLaunchOptionsKey, id> *)launchOptions {
-  (void)application;
-  (void)launchOptions;
-
-#if defined(TARGET_OS_VISION) && TARGET_OS_VISION
-  return YES;
-#else
-  self.window = [[UIWindow alloc] initWithFrame:UIScreen.mainScreen.bounds];
-  self.window.rootViewController = [[AgentDeviceRunnerViewController alloc] init];
-  [self.window makeKeyAndVisible];
-
-  return YES;
-#endif
-}
-
-#if defined(TARGET_OS_VISION) && TARGET_OS_VISION
-- (UISceneConfiguration *)application:(UIApplication *)application
-    configurationForConnectingSceneSession:(UISceneSession *)connectingSceneSession
-                                   options:(UISceneConnectionOptions *)options {
-  (void)application;
-  (void)connectingSceneSession;
-  (void)options;
-
-  UISceneConfiguration *configuration =
-      [[UISceneConfiguration alloc] initWithName:@"Default Configuration"
-                                     sessionRole:UIWindowSceneSessionRoleApplication];
-  configuration.delegateClass = AgentDeviceRunnerSceneDelegate.class;
-  return configuration;
-}
-#endif
-
 @end
 
 int main(int argc, char *argv[]) {
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunner/Info.plist b/apple/runner/AgentDeviceRunner/AgentDeviceRunner/Info.plist
new file mode 100644
index 0000000000..af35d72e3e
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunner/Info.plist
@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>UIApplicationSceneManifest</key>
+	<dict>
+		<key>UIApplicationSupportsMultipleScenes</key>
+		<false/>
+		<key>UISceneConfigurations</key>
+		<dict>
+			<key>UIWindowSceneSessionRoleApplication</key>
+			<array>
+				<dict>
+					<key>UISceneConfigurationName</key>
+					<string>Default Configuration</string>
+					<key>UISceneDelegateClassName</key>
+					<string>AgentDeviceRunnerSceneDelegate</string>
+				</dict>
+			</array>
+		</dict>
+	</dict>
+</dict>
+</plist>
diff --git a/docs/agents/device-verification.md b/docs/agents/device-verification.md
index 29391a4f26..ce843cbe9f 100644
--- a/docs/agents/device-verification.md
+++ b/docs/agents/device-verification.md
@@ -91,8 +91,8 @@ toolchain per command:
   reports it as `overlayWarning` on `record stop` rather than returning a broken file. Only reach
   for `record start --hide-touches` when you want the fastest raw capture, not to dodge the defect.
   See ADR 0025 and #2707.
-- An app must adopt the UIScene lifecycle to launch on iOS 27.1 at all: a legacy
-  `UIApplicationDelegate` app traps at launch inside
+- An app built with the iOS 27 SDK must adopt the UIScene lifecycle to launch on an iOS 27.0 or
+  27.1 simulator at all: a legacy `UIApplicationDelegate` app traps at launch inside
   `___UIApplicationEvaluateRuntimeIssueForNoSceneLifecycleAdoption`, which reads like a broken
   device but is not one.
 - The 27.1 runtime in this beta accepts only the `iPhone Duo` device type, so a second non-foldable

From 0749551b7151cc2374e69009db772957ea979b4e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 24 Sep 2026 12:03:30 +0200
Subject: [PATCH 085/132] 0.21.13

---
 package.json | 2 +-
 server.json  | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/package.json b/package.json
index 252d486080..f54bd19536 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "agent-device",
-  "version": "0.21.12",
+  "version": "0.21.13",
   "description": "Mobile app automation and verification for AI coding agents. CLI, MCP server, and typed Node.js API for iOS, Android, HarmonyOS, TV, web, macOS, and Linux.",
   "mcpName": "io.github.callstack/agent-device",
   "license": "MIT",
diff --git a/server.json b/server.json
index e5b141a9e1..6693cea7ea 100644
--- a/server.json
+++ b/server.json
@@ -7,12 +7,12 @@
     "url": "https://github.com/callstack/agent-device",
     "source": "github"
   },
-  "version": "0.21.12",
+  "version": "0.21.13",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "agent-device",
-      "version": "0.21.12",
+      "version": "0.21.13",
       "transport": {
         "type": "stdio"
       },

From 6433dcc01dc677324fedb520a0ae4efa4b851832 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 24 Sep 2026 12:43:24 +0200
Subject: [PATCH 086/132] docs(adr): rewrap the overlong ADR 0013
 gesture-schedule line (#2874)

Rewrap the tail of the Apple eased-schedule paragraph to the 100-column
width the rest of the ADR uses. No wording changes.

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 docs/adr/0013-unified-gesture-plans.md | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/docs/adr/0013-unified-gesture-plans.md b/docs/adr/0013-unified-gesture-plans.md
index 7d9f0a5f39..ce5077504f 100644
--- a/docs/adr/0013-unified-gesture-plans.md
+++ b/docs/adr/0013-unified-gesture-plans.md
@@ -126,9 +126,10 @@ Platform adapters consume the canonical plan:
   Live iOS characterization of an eased sampled schedule against the linear ones in
   [issue #1586](https://github.com/callstack/agent-device/issues/1586) confirmed that distinction:
   the schedules crossed the same fling-recognizer thresholds in the tested range but produced
-  materially different post-release ScrollView positions and long-duration recognition behavior. The distinction is intentional policy at the Apple adapter
-  boundary, not a second interpretation of a `GesturePlan`; changes require live evidence for both
-  recognizer activation and post-release content movement.
+  materially different post-release ScrollView positions and long-duration recognition behavior. The
+  distinction is intentional policy at the Apple adapter boundary, not a second interpretation of a
+  `GesturePlan`; changes require live evidence for both recognizer activation and post-release
+  content movement.
 - WebDriver lowers a supported plan to synchronized W3C pointer action sources. A one-contact
   endpoint plan becomes pointer down, one timed W3C `pointerMove` from start to end, and pointer up;
   the driver owns interpolation across that W3C tick. Multi-touch remains capability-gated until a

From 57886b3780621d37a931d6790150cfd7206befb2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 24 Sep 2026 12:43:53 +0200
Subject: [PATCH 087/132] ci(diagnose): retire the 1874 diagnose loop (#2875)

The loop's default test stopped reaching a commit wait in #2845: it asserts
route xctest-element, so a default dispatch collects no [DEBUG-1874]
cadence. That test never reached #2080's route, even before #2845. It is a
bare `type`, and the synthesized-first-responder-replacement route fires
only for `fill` on a penalized XCTest channel. So this loop was never
#2080's reproduction path.

No existing RunnerTests method reaches the real replacement route. The one
test that reaches its commit wait
(testTypeTextReliablyPacesSynthesizedReplacementThroughProductionCaller)
uses a recording synthesizer against Springboard, so every poll reads nil
and the wait always ends notObserved at the 3 s stall deadline. Looping it
records a fixed, synthetic cadence. A new penalized coordinate-fill test
could reach the route, but the cadence records lengths only (#1924), so it
still could not capture the corrupted value #2080 needs. #2080's triage
asks for a local reproduction with test-only value instrumentation instead.

Delete the workflow, its iteration reader, and that reader's test. The
runner's [DEBUG-1874] lines stay: runner.log in the iOS smoke lane is where
the #2080 trace came from, and existing tests pin their format and
redaction.

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .github/workflows/1874-diagnose.yml           | 132 ---------------
 .../__tests__/diagnose-1874-iteration.test.ts | 157 ------------------
 scripts/diagnose-1874-iteration.ts            |  80 ---------
 vitest.config.ts                              |   1 -
 4 files changed, 370 deletions(-)
 delete mode 100644 .github/workflows/1874-diagnose.yml
 delete mode 100644 scripts/__tests__/diagnose-1874-iteration.test.ts
 delete mode 100644 scripts/diagnose-1874-iteration.ts

diff --git a/.github/workflows/1874-diagnose.yml b/.github/workflows/1874-diagnose.yml
deleted file mode 100644
index a0e9ee0a01..0000000000
--- a/.github/workflows/1874-diagnose.yml
+++ /dev/null
@@ -1,132 +0,0 @@
-name: 1874 Diagnose
-
-# Under the lane rule in #1781:
-#
-#   - Catches: iOS text-entry commit episodes on CI hardware — the dispatched test looped on both
-#     arches, with and without the neighbour test that shares the simulator. An absorbed episode
-#     surfaces as a slow pass, so the cadence is kept for passes too.
-#   - Evidence: the 2026-08-21 dispatch passed 50/50 and still caught an episode (`type-all`
-#     2487 ms across 5 polls) that no PR lane would report; it does not reproduce locally.
-#   - Cost: manual dispatch and the `diagnose/1874-commit-stall` branch only — never a PR or `main`.
-#     One dispatch is four macOS slots, each a runner build plus `iterations` iterations of
-#     simulator time.
-#   - Kill criterion: delete when #2080 closes. It is the last open text-entry question this loop
-#     is the CI reproduction path for, and nothing else reads these artifacts.
-
-on:
-  workflow_dispatch:
-    inputs:
-      iterations:
-        description: 'Loop iterations per job'
-        required: false
-        default: '25'
-      test:
-        description: 'RunnerTests method to loop'
-        required: false
-        default: testBareTypeUsesTappedInputWhenSoftwareKeyboardIsHidden
-  push:
-    branches:
-      - diagnose/1874-commit-stall
-
-permissions:
-  contents: read
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-jobs:
-  stall-loop:
-    name: ${{ matrix.arch }} ${{ matrix.mode }} stall loop
-    runs-on: macos-26
-    timeout-minutes: 90
-    strategy:
-      fail-fast: false
-      matrix:
-        mode: [isolated, pair]
-        arch: [x86_64, arm64]
-    env:
-      IOS_RUNTIME_VERSION: '26.2'
-      AGENT_DEVICE_IOS_RUNNER_DERIVED_PATH: ${{ github.workspace }}/.tmp/ios-runner-derived
-      AGENT_DEVICE_XCUITEST_INCLUDE_UNIT_TESTS: '1'
-      AGENT_DEVICE_XCUITEST_ARCHS: ${{ matrix.arch }}
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Setup toolchain
-        uses: ./.github/actions/setup-node-pnpm
-
-      - name: Restore and build iOS XCTest runner
-        uses: ./.github/actions/setup-apple-runner-build
-        with:
-          derived-path: ${{ env.AGENT_DEVICE_IOS_RUNNER_DERIVED_PATH }}
-          cache-key-prefix: ios-runner-prebuilt
-          cache-key-suffix: -ios-${{ env.IOS_RUNTIME_VERSION }}-1874-${{ matrix.arch }}
-          gate: swift-runner-ios
-          xcuitest-platform: ios
-          xcuitest-destination: generic/platform=iOS Simulator
-
-      - name: Boot iOS test simulator
-        id: ios-simulator
-        uses: ./.github/actions/boot-ios-test-simulator
-        with:
-          runtime-version: ${{ env.IOS_RUNTIME_VERSION }}
-          preferred-device-name: iPhone 17 Pro
-
-      - name: Stall loop
-        env:
-          ITERATIONS_INPUT: ${{ github.event.inputs.iterations }}
-          TEST_INPUT: ${{ github.event.inputs.test }}
-        run: |
-          set -euo pipefail
-          XCTESTRUN_PATH="$(find "$AGENT_DEVICE_IOS_RUNNER_DERIVED_PATH/Build/Products" -maxdepth 1 -name '*.xctestrun' -print -quit)"
-          test -n "$XCTESTRUN_PATH"
-          UDID="${{ steps.ios-simulator.outputs.simulator-udid }}"
-          ITER="${ITERATIONS_INPUT:-25}"
-          TEST_NAME="${TEST_INPUT:-testBareTypeUsesTappedInputWhenSoftwareKeyboardIsHidden}"
-          mkdir -p .tmp
-
-          if [ "${{ matrix.mode }}" = "pair" ]; then
-            EXTRA_ONLY_TESTING=(-only-testing:AgentDeviceRunnerUITests/RunnerTests/testBareDelayedTypeFailsWhenTappedInputDisappearsMidCommand)
-          else
-            EXTRA_ONLY_TESTING=()
-          fi
-
-          sys_prof="$(system_profiler SPHardwareDataType 2>/dev/null | grep -E 'Chip|Cores|Memory' || true)"
-          echo "HOST: $sys_prof" | tee stall-summary.txt
-
-          pass=0; skipped=0; failed=0; noresult=0; runfailed=0
-          for i in $(seq 1 "$ITER"); do
-            LOG=".tmp/stall-run-$i.log"
-            set +e
-            xcodebuild test-without-building \
-              -xctestrun "$XCTESTRUN_PATH" \
-              -destination "platform=iOS Simulator,id=$UDID" \
-              -only-testing:"AgentDeviceRunnerUITests/RunnerTests/$TEST_NAME" \
-              ${EXTRA_ONLY_TESTING[@]+"${EXTRA_ONLY_TESTING[@]}"} \
-              > "$LOG" 2>&1
-            rc=$?
-            set -e
-            verdict="$(node --experimental-strip-types scripts/diagnose-1874-iteration.ts \
-              "$LOG" "$TEST_NAME" "$i" "$rc")"
-            case "$verdict" in
-              passed) pass=$((pass+1)) ;;
-              skipped) skipped=$((skipped+1)) ;;
-              no-result) noresult=$((noresult+1)) ;;
-              run-failed) runfailed=$((runfailed+1)) ;;
-              *) failed=$((failed+1)) ;;
-            esac
-          done
-
-          echo "RESULT arch=${{ matrix.arch }} mode=${{ matrix.mode }}: $pass passed, $skipped skipped, $failed failed, $noresult no-result, $runfailed run-failed of $ITER" | tee -a stall-summary.txt
-
-      - name: Upload stall evidence
-        if: always()
-        uses: actions/upload-artifact@v4
-        with:
-          name: stall-evidence-${{ matrix.arch }}-${{ matrix.mode }}
-          include-hidden-files: true
-          path: |
-            stall-summary.txt
-            .tmp/stall-evidence-*.log
-          if-no-files-found: ignore
diff --git a/scripts/__tests__/diagnose-1874-iteration.test.ts b/scripts/__tests__/diagnose-1874-iteration.test.ts
deleted file mode 100644
index 350fdf21eb..0000000000
--- a/scripts/__tests__/diagnose-1874-iteration.test.ts
+++ /dev/null
@@ -1,157 +0,0 @@
-import { execFileSync } from 'node:child_process';
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { expect, test } from 'vitest';
-import { readIteration, type IterationReport } from '../diagnose-1874-iteration.ts';
-
-const root = path.join(path.dirname(fileURLToPath(import.meta.url)), '../..');
-const script = path.join(root, 'scripts/diagnose-1874-iteration.ts');
-const WORKFLOW = path.join(root, '.github/workflows/1874-diagnose.yml');
-const NAME = 'testBareTypeUsesTappedInputWhenSoftwareKeyboardIsHidden';
-const POLL = '[DEBUG-1874] poll t=1ms observedLen=0 expectedPrefixLen=0';
-const CADENCE = [
-  '[DEBUG-1874] wait start expectedLen=17',
-  POLL,
-  '[DEBUG-1874] wait outcome=settled',
-];
-
-const verdictLine = (test: string, word: string) =>
-  `Test Case '-[X.RunnerTests ${test}]' ${word} (1.0 seconds).`;
-const phases = (typeAllMs: string) =>
-  [
-    `phase=focus durationMs=644.6`,
-    `phase=type-all durationMs=${typeAllMs}`,
-    `phase=total durationMs=7379.7`,
-  ].map((phase) => `AGENT_DEVICE_RUNNER_TEXT_ENTRY_PHASE commandId=c ${phase} chars=17`);
-
-const SHAPES: readonly (Partial<IterationReport> & { name: string; log: string[]; rc?: number })[] =
-  [
-    {
-      name: 'healthy pass',
-      log: [verdictLine(NAME, 'passed'), ...phases('796.1'), ...CADENCE],
-      verdict: 'passed',
-      keepEvidence: false,
-      lines: ['iter=1 verdict=passed rc=0 durationMs=796.1 polls=1'],
-    },
-    {
-      name: 'slow pass — an absorbed episode, which is the evidence #1874 wants',
-      log: [verdictLine(NAME, 'passed'), ...phases('14146.4'), ...CADENCE],
-      verdict: 'passed',
-      keepEvidence: true,
-      lines: ['iter=1 verdict=passed rc=0 durationMs=14146.4 polls=1', ...CADENCE],
-    },
-    {
-      name: 'a pass a tenth of a millisecond over the slow threshold is still slow',
-      log: [verdictLine(NAME, 'passed'), ...phases('2000.1'), ...CADENCE],
-      verdict: 'passed',
-      keepEvidence: true,
-    },
-    {
-      name: 'skipped — an environment flip, not a stall',
-      log: [verdictLine(NAME, 'skipped')],
-      verdict: 'skipped',
-      keepEvidence: true,
-      lines: ['iter=1 verdict=skipped rc=0 durationMs=0 polls=0'],
-    },
-    {
-      name: 'no verdict at all — ours to own, not the product’s',
-      log: ['Executed 0 tests, with 0 failures (0 unexpected) in 0.000 seconds'],
-      verdict: 'no-result',
-      keepEvidence: true,
-    },
-    {
-      name: 'a verdict word this loop does not model is not a stall either',
-      log: [verdictLine(NAME, 'errored')],
-      verdict: 'no-result',
-    },
-    {
-      name: 'pair mode — the neighbour test logs first',
-      log: [
-        verdictLine('testBareDelayedTypeFailsWhenTappedInputDisappearsMidCommand', 'passed'),
-        'AGENT_DEVICE_RUNNER_TEXT_ENTRY_PHASE commandId=n phase=type-all durationMs=5000.0 chars=17',
-        verdictLine(NAME, 'passed'),
-        ...phases('812.0'),
-      ],
-      verdict: 'passed',
-      keepEvidence: false,
-    },
-    {
-      name: 'restarted — the final word is the outcome',
-      log: [verdictLine(NAME, 'failed'), ...phases('900.0'), verdictLine(NAME, 'passed')],
-      verdict: 'passed',
-      keepEvidence: false,
-    },
-    {
-      name: 'measured test passed, xcodebuild did not',
-      log: [verdictLine(NAME, 'passed'), ...phases('796.1'), ...CADENCE],
-      rc: 65,
-      verdict: 'run-failed',
-      keepEvidence: true,
-    },
-    {
-      name: 'louder than the cadence cap',
-      log: [verdictLine(NAME, 'failed'), ...Array.from({ length: 45 }, () => POLL)],
-      verdict: 'failed',
-      keepEvidence: true,
-      lines: [
-        'iter=1 verdict=failed rc=0 durationMs=0 polls=45',
-        ...Array.from({ length: 40 }, () => POLL),
-        '… 5 more DEBUG-1874 lines (full log in the artifact)',
-      ],
-    },
-  ];
-
-test.each(SHAPES)('reads a $name iteration', (shape) => {
-  const report = readIteration(shape.log.join('\n'), NAME, 1, shape.rc ?? 0);
-  expect(report.verdict).toBe(shape.verdict);
-  if (shape.keepEvidence !== undefined) expect(report.keepEvidence).toBe(shape.keepEvidence);
-  if (shape.lines) expect(report.lines).toEqual(shape.lines);
-});
-
-test('the workflow forwards the exit status xcodebuild actually returned', () => {
-  const workflow = fs.readFileSync(WORKFLOW, 'utf8');
-  expect(workflow).toContain('rc=$?');
-  expect(workflow).toMatch(/diagnose-1874-iteration\.ts \\\n\s*"\$LOG" "\$TEST_NAME" "\$i" "\$rc"/);
-});
-
-test('the test name is matched literally, not as a pattern', () => {
-  const log = verdictLine('testAXB', 'passed');
-  expect(readIteration(log, 'testA.B', 1, 0).verdict).toBe('no-result');
-  expect(readIteration(log, 'testAXB', 1, 0).verdict).toBe('passed');
-});
-
-test.each([
-  { label: 'slow pass', rc: 0, verdict: 'passed' },
-  { label: 'nonzero exit over a green measured test', rc: 65, verdict: 'run-failed' },
-])(
-  'the entry point writes, keeps evidence and prints the verdict for a $label',
-  ({ rc, verdict }) => {
-    const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'diagnose-1874-'));
-    try {
-      fs.mkdirSync(path.join(cwd, '.tmp'));
-      const log = path.join(cwd, 'iteration.log');
-      fs.writeFileSync(
-        log,
-        [verdictLine(NAME, 'passed'), ...phases('14146.4'), ...CADENCE].join('\n'),
-      );
-
-      const printed = execFileSync(
-        process.execPath,
-        ['--experimental-strip-types', script, log, NAME, '7', `${rc}`],
-        { cwd, encoding: 'utf8' },
-      );
-
-      expect(printed).toBe(verdict);
-      expect(fs.readFileSync(path.join(cwd, 'stall-summary.txt'), 'utf8')).toBe(
-        [`iter=7 verdict=${verdict} rc=${rc} durationMs=14146.4 polls=1`, ...CADENCE, ''].join(
-          '\n',
-        ),
-      );
-      expect(fs.existsSync(path.join(cwd, '.tmp', 'stall-evidence-7.log'))).toBe(true);
-    } finally {
-      fs.rmSync(cwd, { recursive: true, force: true });
-    }
-  },
-);
diff --git a/scripts/diagnose-1874-iteration.ts b/scripts/diagnose-1874-iteration.ts
deleted file mode 100644
index 6913042a4d..0000000000
--- a/scripts/diagnose-1874-iteration.ts
+++ /dev/null
@@ -1,80 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import { pathToFileURL } from 'node:url';
-
-const SLOW_PASS_MS = 2000;
-const CADENCE_LIMIT = 40;
-const SUMMARY = 'stall-summary.txt';
-const EVIDENCE_DIR = '.tmp';
-
-type MeasuredVerdict = 'passed' | 'skipped' | 'failed';
-
-export type IterationReport = {
-  readonly verdict: MeasuredVerdict | 'no-result' | 'run-failed';
-  readonly keepEvidence: boolean;
-  readonly lines: readonly string[];
-};
-
-export function readIteration(
-  log: string,
-  testName: string,
-  iteration: number,
-  rc: number,
-): IterationReport {
-  const lines = log.split('\n');
-  const marker = `${testName}]' `;
-  const word = lines
-    .filter((line) => line.includes(marker))
-    .map((line) => line.slice(line.indexOf(marker) + marker.length).split(' ')[0])
-    .at(-1);
-  const measured = isMeasuredVerdict(word) ? word : 'no-result';
-  const exitContradictsMeasured = rc !== 0 && measured !== 'failed' && measured !== 'no-result';
-  const verdict = exitContradictsMeasured ? 'run-failed' : measured;
-  const durationMs = Number(
-    lines
-      .flatMap((line) => /phase=type-all durationMs=(\d+(?:\.\d+)?)/.exec(line)?.[1] ?? [])
-      .at(-1) ?? 0,
-  );
-  const cadence = lines.filter((line) => line.includes('[DEBUG-1874]'));
-  const keepEvidence = verdict !== 'passed' || durationMs > SLOW_PASS_MS;
-
-  const polls = cadence.filter((line) => line.includes('] poll')).length;
-  const summary = `iter=${iteration} verdict=${verdict} rc=${rc} durationMs=${durationMs} polls=${polls}`;
-  const dropped = cadence.length - CADENCE_LIMIT;
-  return {
-    verdict,
-    keepEvidence,
-    lines: !keepEvidence
-      ? [summary]
-      : [
-          summary,
-          ...cadence.slice(0, CADENCE_LIMIT),
-          ...(dropped > 0 ? [`… ${dropped} more DEBUG-1874 lines (full log in the artifact)`] : []),
-        ],
-  };
-}
-
-function isMeasuredVerdict(word: string | undefined): word is MeasuredVerdict {
-  return word === 'passed' || word === 'skipped' || word === 'failed';
-}
-
-function main(): number {
-  const [logPath, testName, iteration, rc] = process.argv.slice(2);
-  if (!logPath || !testName || !iteration || !rc) {
-    throw new Error('usage: diagnose-1874-iteration.ts <log> <testName> <iteration> <rc>');
-  }
-  const report = readIteration(
-    fs.readFileSync(logPath, 'utf8'),
-    testName,
-    Number(iteration),
-    Number(rc),
-  );
-  fs.appendFileSync(SUMMARY, `${report.lines.join('\n')}\n`);
-  if (report.keepEvidence) {
-    fs.copyFileSync(logPath, path.join(EVIDENCE_DIR, `stall-evidence-${iteration}.log`));
-  }
-  process.stdout.write(report.verdict);
-  return 0;
-}
-
-if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) process.exit(main());
diff --git a/vitest.config.ts b/vitest.config.ts
index 4482f235e2..77b2793122 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -163,7 +163,6 @@ export default defineConfig({
             // Parses CI configuration only, so this action guard needs no device or subprocess lane.
             'test/ci/upload-agent-device-artifacts.test.ts',
             'test/ci/upload-artifact-hidden-paths.test.ts',
-            'scripts/__tests__/diagnose-1874-iteration.test.ts',
             // The size reporter is preserved across a base checkout; its entrypoint and imported
             // modules must move as one directory or the Bundle Size lane fails before measuring.
             'test/ci/size-workflow.test.ts',

From f47e9c9ef4db2e73c7a2b5d5c2d2ef150af474c3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 24 Sep 2026 12:44:12 +0200
Subject: [PATCH 088/132] docs(ios-runner): point RUNNER_PROTOCOL.md at the
 current declarations and document recovery and busy codes (#2876)

* docs(ios-runner): repoint RUNNER_PROTOCOL.md and document recovery/busy codes

The command-names pointer named runner-client.ts, which now only sends
commands; the RunnerCommand union moved to runner-contract.ts a while back.
Add sections for commandId + the command journal + status recovery,
runnerFatal/runnerMainThreadBusy response fields, and the typed runner error
codes now on the wire (RUNNER_BUSY, RUNNER_WEDGED, MAIN_THREAD_TIMEOUT,
APP_NOT_RUNNING, ALERT_NOT_FOUND, SCROLL_KEYBOARD_OCCLUDES_SURFACE, and the
APP_SCREEN_* capture-refusal codes), each linked to its declaration site
instead of copied tables.

* docs(ios-runner): fix RUNNER_PROTOCOL error-code and busy-stamp claims

Round 2 of adversarial review on #2797 found the round-1 doc still
diverged from the code it describes: it claimed RUNNER_ERROR_RULES has
a row for MAIN_THREAD_TIMEOUT (it does not - only RUNNER_BUSY and
RUNNER_WEDGED have rows; MAIN_THREAD_TIMEOUT is read directly by
isRunnerMainThreadOccupiedError), it still re-listed the diagnostic-only
codes' owning files in prose instead of linking to the registries, it
described the runnerMainThreadBusy unchanged-flag cases loosely enough
to read as "any code without an occupancy match" rather than the actual
two cases (an ok response with no stamp, or a non-structured
transport-shaped failure), and it named runMainThreadWork/
runMainThreadWorkIfIdle plus RunnerTests+Transport.swift as the busy
stamp's read/definition when the state read is actually
currentMainThreadBusyState().reportsMainThreadBusy and the stamp itself
is defined in RunnerTests+Models.swift (Transport.swift only calls it).

Every changed sentence is re-checked against the implementation with
file:line, and every code path other than RUNNER_BUSY/RUNNER_WEDGED/
MAIN_THREAD_TIMEOUT now points at DIAGNOSTIC_ONLY_RUNNER_ERROR_CODES
and RUNNER_ERROR_RULES instead of restating what those registries own.

* docs(ios-runner): reduce RUNNER_PROTOCOL recovery and error sections to declaration pointers

* docs(ios-runner): link where the runner produces its busy stamp, runnerFatal and error codes
---
 apple/runner/RUNNER_PROTOCOL.md | 38 ++++++++++++++++++++++++++++++---
 1 file changed, 35 insertions(+), 3 deletions(-)

diff --git a/apple/runner/RUNNER_PROTOCOL.md b/apple/runner/RUNNER_PROTOCOL.md
index dc3bdc2801..aa80ffac1e 100644
--- a/apple/runner/RUNNER_PROTOCOL.md
+++ b/apple/runner/RUNNER_PROTOCOL.md
@@ -62,10 +62,11 @@ than silently applied:
 { "command": "rotate", "orientation": "landscape-left" }
 ```
 
-The current command names are defined in:
+The current command names and per-command traits are defined in:
 
-- [`../../packages/platform-apple/src/runner/runner-client.ts`](../../packages/platform-apple/src/runner/runner-client.ts)
-- [`AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift`](AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift)
+- `RunnerCommand` in [`../../packages/platform-apple/src/runner/runner-contract.ts`](../../packages/platform-apple/src/runner/runner-contract.ts)
+- `RUNNER_COMMAND_TRAITS` in [`../../packages/platform-apple/src/runner/runner-command-traits.ts`](../../packages/platform-apple/src/runner/runner-command-traits.ts)
+- `CommandType` in [`AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift`](AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift)
 
 ## Response Shape
 
@@ -97,3 +98,34 @@ Successful and failed responses use the same top-level envelope:
 - Treat the TypeScript and Swift wire models as a single contract.
 - When adding, removing, or renaming a command, update the protocol fixtures/tests in the same change.
 - Keep this file focused on the actual wire shape rather than implementation details of command execution.
+
+## Recovery, Busy State, and Error Codes
+
+These behaviors are owned by code. This section only says where each one is declared; read the
+declaration for the current rules.
+
+- **Command ids and `status` recovery.** The daemon attaches a `commandId` with `withRunnerCommandId`
+  ([`runner-contract.ts`](../../packages/platform-apple/src/runner/runner-contract.ts)). The runner records commands in
+  `RunnerCommandJournal` ([`RunnerTests+CommandJournal.swift`](AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandJournal.swift)) and
+  answers the `status` command in `executeStatus`
+  ([`RunnerTests+CommandDispatch.swift`](AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandDispatch.swift)). The daemon's recovery
+  decisions live in [`runner-command-recovery.ts`](../../packages/platform-apple/src/runner/runner-command-recovery.ts).
+- **`runnerMainThreadBusy`.** The runner stamps successful responses with `stampingCurrentMainThreadBusy`
+  ([`RunnerTests+Models.swift`](AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift)) from `currentMainThreadBusyState()`
+  ([`RunnerTests+MainThreadWork.swift`](AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+MainThreadWork.swift)), applied in `jsonResponse`
+  ([`RunnerTests+Transport.swift`](AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Transport.swift)). The daemon reads the stamp in [`runner-session.ts`](../../packages/platform-apple/src/runner/runner-session.ts).
+- **`runnerFatal`.** A field of the response data (`runnerFatal` in
+  [`RunnerTests+Models.swift`](AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift)); for example, a sparse snapshot payload in
+  [`RunnerTests+Snapshot.swift`](AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Snapshot.swift) sets it. The daemon reads it in
+  `resolveRunnerFatalReason` ([`runner-session.ts`](../../packages/platform-apple/src/runner/runner-session.ts)).
+- **Runner error codes** (for example `RUNNER_BUSY`, `RUNNER_WEDGED`, `MAIN_THREAD_TIMEOUT`). On the runner
+  side, wire codes are declared in `RunnerWireErrorCode` ([`RunnerTests.swift`](AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift));
+  `RUNNER_BUSY` and `RUNNER_WEDGED` come from the busy gate in
+  [`RunnerTests+CommandDispatch.swift`](AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandDispatch.swift), and `MAIN_THREAD_TIMEOUT` from
+  the main-thread watchdog in [`RunnerTests+Transport.swift`](AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Transport.swift). The daemon
+  classifies a runner-reported code in `classifyRunnerReportedError`
+  ([`runner-contract.ts`](../../packages/platform-apple/src/runner/runner-contract.ts)): codes listed in `DIAGNOSTIC_ONLY_RUNNER_ERROR_CODES`
+  arrive as `COMMAND_FAILED` with `details.runnerErrorCode`, and other codes pass through as typed
+  codes. How the daemon reacts to a failure (retry, resend, session-fatal) is declared in
+  `RUNNER_ERROR_RULES` and the helpers beside it
+  ([`runner-error-classification.ts`](../../packages/platform-apple/src/runner/runner-error-classification.ts)).

From fe2ac00f77d792a3184f0e7ad926ca11bd8339ea Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 24 Sep 2026 13:40:01 +0200
Subject: [PATCH 089/132] test(ios): recover the E2E visibility search from a
 scroll that overshoots its target (#2883)

A controlled iOS scroll can still release with inertia when the host is
loaded: the app misses the slow tail of the eased drag and UIKit flings
with a mid-drag velocity (~420 pt/s measured), so one scroll down 0.75
moved content 719-852 pt instead of 439-505 pt and carried the one-row
automation-longpress target past the viewport. The forward-only search
then had nowhere to go (#2491).

The search now follows three forward scrolls (2.25 viewports, unchanged)
with three shorter reverse scrolls, whose travel plus a measured fling
stays inside one viewport, and gives a surface the read reports as
unsettled a bounded pause before re-reading it instead of re-reading at
once.
---
 ...os-simulator-e2e-visibility-scroll.test.ts | 157 +++++++++++-------
 .../ios-simulator-e2e/live-assertions.ts      |  87 ++++++----
 2 files changed, 152 insertions(+), 92 deletions(-)

diff --git a/test/integration/ios-simulator-e2e-visibility-scroll.test.ts b/test/integration/ios-simulator-e2e-visibility-scroll.test.ts
index fd79c11b4d..ae2458bb30 100644
--- a/test/integration/ios-simulator-e2e-visibility-scroll.test.ts
+++ b/test/integration/ios-simulator-e2e-visibility-scroll.test.ts
@@ -2,7 +2,10 @@ import assert from 'node:assert/strict';
 import test from 'node:test';
 
 import type { CliJsonResult } from './cli-json.ts';
-import { searchForVisibleElement } from './ios-simulator-e2e/live-assertions.ts';
+import {
+  searchForVisibleElement,
+  type ScrollSearchDevice,
+} from './ios-simulator-e2e/live-assertions.ts';
 
 function result(status: number, details?: Record<string, unknown>): CliJsonResult {
   return {
@@ -13,84 +16,114 @@ function result(status: number, details?: Record<string, unknown>): CliJsonResul
   };
 }
 
-test('an existing offscreen element scrolls until the visibility probe passes', async () => {
-  const probes = [result(1), result(0)];
-  const probeAttempts: number[] = [];
-  const scrollAttempts: number[] = [];
-
-  await searchForVisibleElement(
-    'id="automation-longpress"',
-    async (attempt) => {
-      probeAttempts.push(attempt);
-      return probes.shift() ?? result(1);
+const UNSETTLED = { unsettledGesture: { action: 'scroll', positionals: [] } };
+
+/**
+ * A vertical list the search drives. Offsets are in viewports; the target is visible while the
+ * offset lies inside `visible`. Each scroll moves by the next planned travel, clamped to the list
+ * bounds. `movesUntilSettled` keeps the surface moving after every scroll that moved until the
+ * search pauses to settle it, so each read before that misses with `unsettledGesture`: the CI
+ * failure shape.
+ */
+function list(options: {
+  visible?: readonly [number, number];
+  downTravel?: readonly number[];
+  end?: number;
+  movesUntilSettled?: boolean;
+}) {
+  const downTravel = [...(options.downTravel ?? [])];
+  const end = options.end ?? 10;
+  let offset = 0;
+  let moving = false;
+  const log: string[] = [];
+  const device: ScrollSearchDevice = {
+    probeVisibility: async (probe) => {
+      log.push(`probe ${probe}`);
+      const [from, to] = options.visible ?? [Infinity, Infinity];
+      if (!moving && offset >= from && offset <= to) return result(0);
+      return result(1, moving ? UNSETTLED : { reason: 'selector_not_found' });
     },
-    async (attempt) => {
-      scrollAttempts.push(attempt);
+    settle: async () => {
+      log.push('settle');
+      moving = false;
     },
-  );
+    scroll: async (step) => {
+      const travel = step.direction === 'down' ? (downTravel.shift() ?? 0.75) : -0.5;
+      const next = Math.min(end, Math.max(0, offset + travel));
+      const moved = next !== offset;
+      offset = next;
+      moving = options.movesUntilSettled === true && moved;
+      log.push(`scroll ${step.direction} ${step.amount}`);
+    },
+  };
+  return { device, log };
+}
 
-  assert.deepEqual(probeAttempts, [1, 2]);
-  assert.deepEqual(scrollAttempts, [1]);
+test('an existing offscreen element scrolls until the visibility probe passes', async () => {
+  const { device, log } = list({ visible: [0.5, 1.2] });
+
+  await searchForVisibleElement('id="target"', device);
+
+  assert.deepEqual(log, ['probe 1', 'scroll down 0.75', 'probe 2']);
 });
 
 test('a stalled capture retries without scrolling or consuming an attempt', async () => {
   const probes = [result(1, { captureStalled: true }), result(0)];
-  const probeAttempts: number[] = [];
-  const scrollAttempts: number[] = [];
-
-  await searchForVisibleElement(
-    'id="automation-longpress"',
-    async (attempt) => {
-      probeAttempts.push(attempt);
-      return probes.shift() ?? result(1);
-    },
-    async (attempt) => {
-      scrollAttempts.push(attempt);
+  const scrolls: string[] = [];
+
+  await searchForVisibleElement('id="target"', {
+    probeVisibility: async () => probes.shift() ?? result(1),
+    settle: async () => assert.fail('a stalled capture is not a moving surface'),
+    scroll: async (step) => {
+      scrolls.push(step.direction);
     },
-  );
+  });
 
-  assert.deepEqual(probeAttempts, [1, 1]);
-  assert.deepEqual(scrollAttempts, []);
+  assert.deepEqual([probes.length, scrolls], [0, []]);
 });
 
-/**
- * The CI failure shape: the element is on screen only at offset 1, and the first read after each
- * scroll lands on a surface still moving, so it misses with `unsettledGesture`.
- */
-function listWithUnsettledFirstReads(visibleAt?: number) {
-  let offset = 0;
-  let moving = false;
-  const probes: number[] = [];
-  const scrolls: number[] = [];
-  const probe = async (attempt: number) => {
-    probes.push(attempt);
-    const unsettled = moving;
-    moving = false;
-    if (!unsettled && offset === visibleAt) return result(0);
-    return result(1, unsettled ? { unsettledGesture: { action: 'scroll', positionals: [] } } : {});
-  };
-  const scroll = async (attempt: number) => {
-    scrolls.push(attempt);
-    offset += 1;
-    moving = true;
-  };
-  return { probes, scrolls, probe, scroll };
-}
+test('an unsettled miss waits for the surface to settle and re-reads at the same offset', async () => {
+  const { device, log } = list({ visible: [0.5, 1.2], movesUntilSettled: true });
 
-test('an unsettled miss after the scroll that reached the element is re-read at the same offset', async () => {
-  const list = listWithUnsettledFirstReads(1);
+  await searchForVisibleElement('id="target"', device);
+
+  assert.deepEqual(log, ['probe 1', 'scroll down 0.75', 'probe 2', 'settle', 'probe 3']);
+});
 
-  await searchForVisibleElement('id="target"', list.probe, list.scroll);
+test('a forward scroll that overshoots the element is recovered by scrolling back', async () => {
+  // Measured on an iOS 26 simulator under host load: one `scroll down 0.75` moved content 852 pt
+  // instead of its usual 439-505 pt, which carried a one-row target past the viewport.
+  const { device, log } = list({
+    visible: [0.6, 1.25],
+    downTravel: [1.4, 0.75, 0.75],
+    end: 2.2,
+    movesUntilSettled: true,
+  });
 
-  assert.deepEqual([list.probes, list.scrolls], [[1, 2, 2], [1]]);
+  await searchForVisibleElement('id="target"', device);
+
+  assert.deepEqual(
+    log.filter((entry) => entry.startsWith('scroll')),
+    ['scroll down 0.75', 'scroll down 0.75', 'scroll down 0.75', 'scroll up 0.5', 'scroll up 0.5'],
+  );
 });
 
-test('a real absence still fails after the forward scrolls, naming every step', async () => {
-  const list = listWithUnsettledFirstReads();
+test('a real absence still fails after both sweeps, naming every step', async () => {
+  const { device, log } = list({ movesUntilSettled: true });
 
   await assert.rejects(
-    searchForVisibleElement('id="target"', list.probe, list.scroll),
-    /scroll after attempt 3: [\s\S]*probe 4:/,
+    searchForVisibleElement('id="target"', device),
+    /scroll down 3: [\s\S]*scroll up 6: [\s\S]*probe \d+:/,
+  );
+  assert.deepEqual(
+    log.filter((entry) => entry.startsWith('scroll')),
+    [
+      'scroll down 0.75',
+      'scroll down 0.75',
+      'scroll down 0.75',
+      'scroll up 0.5',
+      'scroll up 0.5',
+      'scroll up 0.5',
+    ],
   );
-  assert.deepEqual(list.scrolls, [1, 2, 3]);
 });
diff --git a/test/integration/ios-simulator-e2e/live-assertions.ts b/test/integration/ios-simulator-e2e/live-assertions.ts
index af9cdbf757..b0e33d0092 100644
--- a/test/integration/ios-simulator-e2e/live-assertions.ts
+++ b/test/integration/ios-simulator-e2e/live-assertions.ts
@@ -40,33 +40,53 @@ export function snapshotNodes(result: { json?: any }): LiveSnapshotNode[] {
   return nodes as LiveSnapshotNode[];
 }
 
-const SCROLL_SEARCH_ATTEMPTS = 4;
+/**
+ * Three forward scrolls reach 2.25 viewports of finger travel. The reverse steps are shorter: a
+ * controlled iOS scroll can still carry post-release inertia under host load (ADR 0013), so a
+ * forward step can carry a short target past the viewport, and a reverse step plus that inertia
+ * must stay inside one viewport so the reverse sweep cannot skip it again.
+ */
+const FORWARD = { direction: 'down', amount: '0.75' } as const;
+const REVERSE = { direction: 'up', amount: '0.5' } as const;
+const SCROLL_SEARCH_PLAN = [FORWARD, FORWARD, FORWARD, REVERSE, REVERSE, REVERSE];
 // A stalled capture, or one taken while the last scroll was still moving, says nothing about where
 // the element is, so re-reading it must not consume a scroll. A couple of re-reads per scroll absorb
 // a slow runner without masking a real absence.
 const SCROLL_SEARCH_REREADS = 2;
+const SETTLE_MS = '1000';
+
+export type ScrollSearchStep = (typeof SCROLL_SEARCH_PLAN)[number];
+
+export type ScrollSearchDevice = {
+  probeVisibility: (probe: number) => Promise<CliJsonResult>;
+  /** Gives a surface that was still moving a bounded pause before the next read. */
+  settle: () => Promise<void>;
+  scroll: (step: ScrollSearchStep, index: number) => Promise<unknown>;
+};
 
 export async function assertElementTextAfterScrolling(
   context: LiveContext,
   selector: string,
   expected: string,
 ): Promise<void> {
-  await searchForVisibleElement(
-    selector,
-    (attempt) =>
+  await searchForVisibleElement(selector, {
+    probeVisibility: (probe) =>
       runStep(
         context,
-        `check ${selector} visibility after scroll (attempt ${attempt})`,
+        `check ${selector} visibility (probe ${probe})`,
         ['is', 'visible', selector],
         { allowFailure: true },
       ),
-    (attempt) =>
-      runStep(context, `scroll toward ${selector} after attempt ${attempt}`, [
+    settle: async () => {
+      await runStep(context, `settle before re-reading ${selector}`, ['wait', SETTLE_MS]);
+    },
+    scroll: (step, index) =>
+      runStep(context, `scroll ${step.direction} toward ${selector} (scroll ${index})`, [
         'scroll',
-        'down',
-        '0.75',
+        step.direction,
+        step.amount,
       ]).then((result) => result.json?.data),
-  );
+  });
   await assertElementText(context, selector, expected);
 }
 
@@ -78,34 +98,41 @@ export async function assertElementTextAfterScrolling(
  */
 export async function searchForVisibleElement(
   selector: string,
-  probeVisibility: (attempt: number) => Promise<CliJsonResult>,
-  scrollAfterAttempt: (attempt: number) => Promise<unknown>,
+  device: ScrollSearchDevice,
 ): Promise<void> {
-  let rereadsLeft = SCROLL_SEARCH_REREADS;
   const history: string[] = [];
-
-  for (let attempt = 1; attempt <= SCROLL_SEARCH_ATTEMPTS;) {
-    const probe = await probeVisibility(attempt);
-    history.push(`probe ${attempt}: ${JSON.stringify(probe.json ?? { status: probe.status })}`);
-    if (probe.status === 0) return;
-
-    const details = probe.json?.error?.details;
-    const readNothing = details?.captureStalled === true || details?.unsettledGesture !== undefined;
-    if (readNothing && rereadsLeft > 0) {
-      rereadsLeft -= 1;
-      continue;
+  let probes = 0;
+  const readWindow = async (): Promise<boolean> => {
+    for (let rereads = 0; ; rereads += 1) {
+      probes += 1;
+      const result = await device.probeVisibility(probes);
+      history.push(`probe ${probes}: ${JSON.stringify(result.json ?? { status: result.status })}`);
+      if (result.status === 0) return true;
+      const unread = unreadSurface(result);
+      if (unread === undefined || rereads === SCROLL_SEARCH_REREADS) return false;
+      if (unread === 'moving') {
+        await device.settle();
+        history.push(`settled for ${SETTLE_MS} ms`);
+      }
     }
+  };
 
-    attempt += 1;
-    if (attempt <= SCROLL_SEARCH_ATTEMPTS) {
-      const scrolled = await scrollAfterAttempt(attempt - 1);
-      history.push(`scroll after attempt ${attempt - 1}: ${JSON.stringify(scrolled ?? null)}`);
-      rereadsLeft = SCROLL_SEARCH_REREADS;
-    }
+  for (const [index, step] of SCROLL_SEARCH_PLAN.entries()) {
+    if (await readWindow()) return;
+    const scrolled = await device.scroll(step, index + 1);
+    history.push(`scroll ${step.direction} ${index + 1}: ${JSON.stringify(scrolled ?? null)}`);
   }
+  if (await readWindow()) return;
   assert.fail(`${selector} did not become visible after scrolling\n${history.join('\n')}`);
 }
 
+/** Why a missed probe says nothing about where the element is, if it says nothing. */
+function unreadSurface(result: CliJsonResult): 'moving' | 'stalled' | undefined {
+  const details = result.json?.error?.details;
+  if (details?.unsettledGesture !== undefined) return 'moving';
+  return details?.captureStalled === true ? 'stalled' : undefined;
+}
+
 function requireNode(
   result: CliJsonResult,
   identifier: string,

From 72862063c85db012889099d86d6875d3d4c54a66 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 24 Sep 2026 13:41:01 +0200
Subject: [PATCH 090/132] fix(ios): drop -Werror from runtime clang builds and
 cache the fold helper build (#2858)

* refactor(ios): extract the native build cache from the snapshot bridge

Move the snapshot bridge's content+toolchain-keyed build cache (lock,
atomic publish, manifest matching, source fingerprinting, and the
budgeted xcrun exec) into native-build-cache.ts as generic, reusable
primitives. The bridge's manifest shape, cache key derivation, and
compile argv (including -Werror) are unchanged; this is a pure move.

* fix(ios): drop -Werror from runtime clang builds and cache the fold helper

Runtime clang builds no longer use -Werror. A new SDK warning in the AX
snapshot bridge or the fold helper can no longer break snapshot or fold
on a user's machine. A darwin-only compile of each helper's exact
production argv with -Werror appended keeps the warning gate in CI
instead.

The fold helper no longer recompiles Fold.m into a temp dir on every
call: it now shares the bridge's content- and toolchain-keyed build
cache (native-build-cache.ts) and is built once per source hash and
Xcode toolchain, cached under ~/.agent-device/fold-helper. Both cache
keys now also fold in the compile argv, so a compiler-flag or
framework-list change that touches neither the source nor the
toolchain cannot serve a stale binary. The cache's process-lock
description is caller-supplied, since the bridge and the fold helper
now share one lock implementation over two different resources.

FOLD_REQUEST_TIMEOUT_MS rises from 210s to 240s to cover the new
preparation budget; its comment lists each step's budget, mirrored in
command-descriptor-timeout-policy.test.ts's pinned envelope. Help and
docs describe the cache.

* chore(gates): cover the fold helper's -Werror gate in the iOS macOS CI step

ios.yml's clean-installed preparation step now also runs the fold
helper's -Werror conformance test and watches apple/fold-helper and
packages/platform-apple/src/foldable for changes, matching the
existing bridge gate.

* refactor(ios): key native build cache hits on the cache key and keep fold build error details

ensureNativeBuildCacheEntry now takes the build's key inputs, derives
the cache key itself, and returns it. A hit only needs the manifest's
cacheKey and binary hash to match, because the key already hashes every
field the per-caller MANIFEST_FIELDS lists compared again. That removes
nativeBuildManifestFieldsMatch, both field lists, and the
snapshotBridgeCacheKey/foldHelperCacheKey wrappers. Keys are
byte-identical to before, so existing cache entries still hit.

A fold helper cache failure now keeps the underlying failure's hint and
typed details (the native-build-stalled hint and timeoutMs,
toolchain-probe stderr, a missing source's filePath) instead of
replacing them with a fixed hint.

Tests: simulator-hid.test.ts mocks the fold helper cache instead of
retesting it through exec fakes, which drops sendSimulatorFoldPose's
test-only cacheRoot option. The -Werror absence checks assert the argv
directly, and the darwin gates append -Werror instead of splicing it in.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .github/workflows/ios.yml                     |  10 +-
 CHANGELOG.md                                  |   8 +
 .../command-registry/src/timeout-policy.ts    |  13 +-
 .../src/foldable/fold-helper-cache.test.ts    | 182 +++++++++++
 .../src/foldable/fold-helper-cache.ts         | 156 ++++++++++
 .../src/foldable/simulator-hid.test.ts        |  68 ++--
 .../src/foldable/simulator-hid.ts             |  74 ++---
 .../src/snapshot-source/cache-identity.ts     |  62 ++--
 .../src/snapshot-source/cache.test.ts         |  11 +-
 .../src/snapshot-source/cache.ts              | 292 +++++-------------
 .../src/snapshot-source/host.ts               |   2 +-
 .../native-build-cache.test.ts                | 103 ++++++
 .../src/snapshot-source/native-build-cache.ts | 184 +++++++++++
 .../snapshot-source/native-runtime.test.ts    |  31 +-
 .../src/snapshot-source/types.ts              |   5 +-
 .../command-descriptor-timeout-policy.test.ts |   7 +-
 src/commands/schema/cli-help.ts               |   2 +-
 .../provider-scenarios/ios-fold.test.ts       |  38 ++-
 website/docs/docs/commands.md                 |   2 +-
 19 files changed, 896 insertions(+), 354 deletions(-)
 create mode 100644 packages/platform-apple/src/foldable/fold-helper-cache.test.ts
 create mode 100644 packages/platform-apple/src/foldable/fold-helper-cache.ts
 create mode 100644 packages/platform-apple/src/snapshot-source/native-build-cache.test.ts
 create mode 100644 packages/platform-apple/src/snapshot-source/native-build-cache.ts

diff --git a/.github/workflows/ios.yml b/.github/workflows/ios.yml
index ac9e3f9775..d04fa8f140 100644
--- a/.github/workflows/ios.yml
+++ b/.github/workflows/ios.yml
@@ -126,7 +126,7 @@ jobs:
           runtime-version: ${{ env.IOS_RUNTIME_VERSION }}
           preferred-device-name: iPhone 17 Pro
 
-      - name: Verify clean-installed Simulator snapshot bridge preparation
+      - name: Verify clean-installed Simulator snapshot bridge preparation and the fold-helper -Werror gate
         if: github.event_name == 'pull_request'
         env:
           BASE_SHA: ${{ github.event.pull_request.base.sha }}
@@ -134,15 +134,19 @@ jobs:
           git fetch origin "$BASE_SHA" --depth=1
           if git diff --quiet "$BASE_SHA"...HEAD -- \
             apple/snapshot-bridge \
+            apple/fold-helper \
             packages/platform-apple/src/snapshot-source \
+            packages/platform-apple/src/foldable \
             scripts/check-package.ts \
             scripts/size-report-install.mjs \
             scripts/size-report-package.mjs; then
-            echo "Snapshot bridge packaging is unchanged; skipping preparation proof."
+            echo "Snapshot bridge and fold-helper sources are unchanged; skipping preparation proof."
             exit 0
           fi
           pnpm build
-          pnpm exec vitest run packages/platform-apple/src/snapshot-source/native-runtime.test.ts
+          pnpm exec vitest run \
+            packages/platform-apple/src/snapshot-source/native-runtime.test.ts \
+            packages/platform-apple/src/foldable/fold-helper-cache.test.ts
           pnpm check:package -- --verify-snapshot-bridge-preparation
 
       - name: Run targeted iOS runner XCTest regressions
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b94914b0e0..f84ddd4613 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -80,6 +80,14 @@
   report no UIKit class names — the XCTest runner, whose own queries answered 76 nodes for that same
   state, plus `appium-source` and `limrun-ios-tree` — never trigger the cut. All 39 flows of React Navigation's Maestro suite pass on an iPhone 17 Simulator running
   iOS 26.2 with this change, including two that never passed on the bridge.
+- Fixed (ios): runtime clang builds no longer compile with `-Werror`, so a new warning from a future
+  Xcode SDK cannot break the AX bridge or fold on a user's machine that this repository cannot fix
+  for them. The fold helper is now built through the same content- and toolchain-keyed build cache
+  as the AX bridge, so a fold call after the first serves a cached binary instead of recompiling
+  `Fold.m` on every call, and switching `DEVELOPER_DIR` busts the cache instead of serving a binary
+  built against a different SDK. A darwin-only CI step (`.github/workflows/ios.yml`) compiles each
+  build's production argv with `-Werror` appended whenever its sources change, so a new warning still
+  fails CI (#2796).
 - Fixed (ios): a local Simulator snapshot taken through the host AX bridge once again publishes the
   geometric `hittable` fact, so `is hittable` and a `hittable:` selector resolve the same controls on
   the bridge and the XCTest runner. The snapshot capability table has declared `hittable =
diff --git a/packages/command-registry/src/timeout-policy.ts b/packages/command-registry/src/timeout-policy.ts
index 29bddc8c1d..ca17ee37b7 100644
--- a/packages/command-registry/src/timeout-policy.ts
+++ b/packages/command-registry/src/timeout-policy.ts
@@ -43,11 +43,16 @@ export const DEFAULT_TIMEOUT_POLICY: CommandTimeoutPolicy = {
 };
 
 /**
- * `fold` spends up to four bounded CoreDevice hinge reads (`IOS_HINGE_ANGLE_TIMEOUT_MS` each on a
- * wedged host) after a 30s helper build and up to 60s of timed HID motion, which can sum past the
- * standard envelope; the envelope covers that worst case with the usual margin.
+ * `fold`'s worst case sums every step budget on the route (platform-apple owns the constants;
+ * command-registry does not import them, so the figures below are copied, not derived):
+ *   - display-inventory query (foldable check):        5s
+ *   - fold-helper preparation (toolchain probe + build): 60s
+ *   - HID dispatch (60s max keyframe duration + 10s):   70s
+ *   - hinge settle reads (4 attempts x 20s):            80s
+ *   - lit-panel display-inventory query:                 5s
+ *   total: 220s. The envelope below covers that with margin.
  */
-const FOLD_REQUEST_TIMEOUT_MS = 210_000;
+const FOLD_REQUEST_TIMEOUT_MS = 240_000;
 
 export const FOLD_TIMEOUT_POLICY: CommandTimeoutPolicy = {
   budget: { source: 'none' },
diff --git a/packages/platform-apple/src/foldable/fold-helper-cache.test.ts b/packages/platform-apple/src/foldable/fold-helper-cache.test.ts
new file mode 100644
index 0000000000..f582319d60
--- /dev/null
+++ b/packages/platform-apple/src/foldable/fold-helper-cache.test.ts
@@ -0,0 +1,182 @@
+import assert from 'node:assert/strict';
+import { readFile, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { beforeAll, describe, test } from 'vitest';
+import { runCmd } from '@agent-device/host-kit/command';
+import { mkdtempForTest } from '../__tests__/tmp-dir.ts';
+import { execKillTimeoutError } from '../snapshot-source/__tests__/exec-timeout-fixture.ts';
+import { createSnapshotSourceHost } from '../snapshot-source/host.ts';
+import type { SnapshotSourceHost } from '../snapshot-source/types.ts';
+import {
+  buildFoldHelperCompileArgv,
+  ensureFoldHelperBinary,
+  FOLD_HELPER_BUILD_TIMEOUT_MS,
+} from './fold-helper-cache.ts';
+
+function fakeFoldHelperHost(
+  binary: () => string,
+  xcodeVersion: () => string = () => 'Xcode 16.4\nBuild version 16F6',
+): SnapshotSourceHost {
+  const real = createSnapshotSourceHost();
+  return {
+    ...real,
+    run: async (command, args) => {
+      if (command === 'xcrun' && args.includes('clang')) {
+        const outputPath = args.at(-1)!;
+        await writeFile(outputPath, binary());
+        return { stdout: '', stderr: '', exitCode: 0 };
+      }
+      const stdout =
+        command === 'xcodebuild'
+          ? xcodeVersion()
+          : command === 'sw_vers'
+            ? args.includes('-buildVersion')
+              ? '24G90'
+              : '15.6'
+            : command === 'uname'
+              ? 'arm64'
+              : '';
+      return { stdout, stderr: '', exitCode: 0 };
+    },
+  };
+}
+
+test('a cache hit does not build, and a source or toolchain change does', async () => {
+  const root = await mkdtempForTest('agent-device-fold-helper-cache-');
+  const sourceRoot = path.join(root, 'source');
+  const cacheRoot = path.join(root, 'cache');
+  await (await import('@agent-device/host-kit/host-file')).ensureHostDirectory(sourceRoot);
+  await writeFile(path.join(sourceRoot, 'Fold.m'), 'fold source v1');
+
+  let builds = 0;
+  let xcodeVersion = 'Xcode 16.4\nBuild version 16F6';
+  const host = fakeFoldHelperHost(
+    () => {
+      builds += 1;
+      return `binary-${builds}`;
+    },
+    () => xcodeVersion,
+  );
+
+  try {
+    const first = await ensureFoldHelperBinary({ host, sourceRoot, cacheRoot });
+    assert.equal(builds, 1);
+    assert.equal(await readFile(first.path, 'utf8'), 'binary-1');
+
+    const hit = await ensureFoldHelperBinary({ host, sourceRoot, cacheRoot });
+    assert.equal(hit.path, first.path);
+    assert.equal(builds, 1);
+
+    await writeFile(path.join(sourceRoot, 'Fold.m'), 'fold source v2');
+    const sourceChanged = await ensureFoldHelperBinary({ host, sourceRoot, cacheRoot });
+    assert.notEqual(sourceChanged.path, first.path);
+    assert.equal(builds, 2);
+
+    xcodeVersion = 'Xcode 16.5\nBuild version 16F5';
+    const toolchainChanged = await ensureFoldHelperBinary({ host, sourceRoot, cacheRoot });
+    assert.notEqual(toolchainChanged.path, sourceChanged.path);
+    assert.equal(builds, 3);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('the runtime clang build never uses -Werror', () => {
+  assert.ok(!buildFoldHelperCompileArgv({ sourceRoot: '', outputPath: '' }).includes('-Werror'));
+});
+
+test('a failed compile reports fold-helper-build-failed with the compiler output', async () => {
+  const root = await mkdtempForTest('agent-device-fold-helper-cache-failure-');
+  const sourceRoot = path.join(root, 'source');
+  const cacheRoot = path.join(root, 'cache');
+  await (await import('@agent-device/host-kit/host-file')).ensureHostDirectory(sourceRoot);
+  await writeFile(path.join(sourceRoot, 'Fold.m'), 'fold source');
+  const okHost = fakeFoldHelperHost(() => 'binary');
+  const host: SnapshotSourceHost = {
+    ...okHost,
+    run: async (command, args, options) => {
+      if (command === 'xcrun' && args.includes('clang')) {
+        return { stdout: '', stderr: 'compiler detail', exitCode: 1 };
+      }
+      return await okHost.run(command, args, options);
+    },
+  };
+
+  try {
+    await assert.rejects(ensureFoldHelperBinary({ host, sourceRoot, cacheRoot }), {
+      code: 'COMMAND_FAILED',
+      details: {
+        stdout: '',
+        stderr: 'compiler detail',
+        exitCode: 1,
+        processExitError: true,
+        hint: 'Select an Xcode with the iOS simulator SDK and foldable HID support using DEVELOPER_DIR.',
+        reason: 'fold-helper-build-failed',
+      },
+    });
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('a compile exec killed at its budget reports the fold-helper build, not the exec layer', async () => {
+  const root = await mkdtempForTest('agent-device-fold-helper-cache-stall-');
+  const sourceRoot = path.join(root, 'source');
+  const cacheRoot = path.join(root, 'cache');
+  await (await import('@agent-device/host-kit/host-file')).ensureHostDirectory(sourceRoot);
+  await writeFile(path.join(sourceRoot, 'Fold.m'), 'fold source');
+  const okHost = fakeFoldHelperHost(() => 'binary');
+  const host: SnapshotSourceHost = {
+    ...okHost,
+    run: async (command, args, options) => {
+      if (command === 'xcrun' && args.includes('clang')) throw await execKillTimeoutError();
+      return await okHost.run(command, args, options);
+    },
+  };
+
+  try {
+    await assert.rejects(
+      ensureFoldHelperBinary({ host, sourceRoot, cacheRoot }),
+      (error: unknown) => {
+        assert.ok(error instanceof Error);
+        assert.equal((error as { code?: string }).code, 'COMMAND_FAILED');
+        assert.equal(
+          (error as { details?: { reason?: string } }).details?.reason,
+          'fold-helper-build-failed',
+        );
+        const details = (error as { details?: Record<string, unknown> }).details;
+        assert.equal(details?.cause, 'native-build-stalled');
+        assert.equal(details?.timeoutMs, FOLD_HELPER_BUILD_TIMEOUT_MS);
+        assert.match(String(details?.hint), /stopped the fold helper build/);
+        return true;
+      },
+    );
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+// #2796: the production compile drops -Werror so a stale toolchain warning cannot fail a build;
+// this is the gate that keeps a new Fold.m warning from passing CI unnoticed. It runs the
+// production argv (`buildFoldHelperCompileArgv`) against the real iphonesimulator SDK with
+// -Werror appended, so a warning fails here instead of nowhere.
+//
+// The compile runs in beforeAll, not in the test body: it is a real clang invocation (see the
+// unit slow-test budget in docs/agents/testing.md), and the snapshot-bridge sibling gate in
+// native-runtime.test.ts keeps its compile out of test-case wall time the same way.
+describe.skipIf(process.platform !== 'darwin')('fold helper warning gate', () => {
+  let compiled: { exitCode: number; stderr: string };
+  beforeAll(async () => {
+    const sourceRoot = path.resolve(import.meta.dirname, '../../../../apple/fold-helper');
+    const binary = path.join(await mkdtempForTest('fold-helper-werror-'), 'fold-helper');
+    const argv = buildFoldHelperCompileArgv({ sourceRoot, outputPath: binary });
+    compiled = await runCmd('xcrun', [...argv, '-Werror'], {
+      allowFailure: true,
+      timeoutMs: FOLD_HELPER_BUILD_TIMEOUT_MS,
+    });
+  }, FOLD_HELPER_BUILD_TIMEOUT_MS + 30_000);
+
+  test('the production fold helper argv compiles clean under -Werror', () => {
+    assert.equal(compiled.exitCode, 0, compiled.stderr);
+  });
+});
diff --git a/packages/platform-apple/src/foldable/fold-helper-cache.ts b/packages/platform-apple/src/foldable/fold-helper-cache.ts
new file mode 100644
index 0000000000..c1fb958f25
--- /dev/null
+++ b/packages/platform-apple/src/foldable/fold-helper-cache.ts
@@ -0,0 +1,156 @@
+import path from 'node:path';
+import { AppError } from '@agent-device/kernel/errors';
+import { execFailureDetails } from '@agent-device/host-kit/command';
+import { runAppleToolCommand } from '../core/tool-provider.ts';
+import { COLD_TOOLCHAIN_PROBE_TIMEOUT_MS } from '../runner/apple-runner-platform.ts';
+import { readHostToolchainIdentity } from '../snapshot-source/cache-identity.ts';
+import {
+  createSnapshotSourceDeadline,
+  type SnapshotSourceDeadline,
+} from '../snapshot-source/deadline.ts';
+import { SnapshotSourceError } from '../snapshot-source/errors.ts';
+import { createSnapshotSourceHost } from '../snapshot-source/host.ts';
+import {
+  ensureNativeBuildCacheEntry,
+  execNativeBuildClang,
+  fingerprintNativeBuildSource,
+} from '../snapshot-source/native-build-cache.ts';
+import type { SnapshotSourceHost } from '../snapshot-source/types.ts';
+
+const FOLD_HELPER_SOURCE_FILENAME = 'Fold.m';
+const FOLD_HELPER_BINARY_FILENAME = 'fold-helper';
+const FOLD_HELPER_SCHEMA_VERSION = 1 as const;
+const FOLD_HELPER_LOCK_DESCRIPTION = 'iOS Simulator fold helper cache';
+const FOLD_HELPER_BUILD_HINT =
+  'Select an Xcode with the iOS simulator SDK and foldable HID support using DEVELOPER_DIR.';
+
+/** Upper bound on a single fold-helper clang invocation; the same budget the prior per-call build used. */
+export const FOLD_HELPER_BUILD_TIMEOUT_MS = 30_000;
+
+/** Ceiling on locating, probing and (if needed) building a cached fold-helper binary. */
+const FOLD_HELPER_PREPARATION_DEADLINE_MS =
+  COLD_TOOLCHAIN_PROBE_TIMEOUT_MS + FOLD_HELPER_BUILD_TIMEOUT_MS;
+
+/**
+ * The fold helper binary for the host's active toolchain, building and caching it if needed. Shares
+ * the snapshot bridge's content+toolchain-keyed build cache (`native-build-cache.ts`), so a fold
+ * call after the first serves a cached binary instead of recompiling `Fold.m`, and a `DEVELOPER_DIR`
+ * switch busts the cache instead of serving a binary built against a different SDK (#2796).
+ *
+ * Build and cache failures surface as `AppError('COMMAND_FAILED', ..., {reason:
+ * 'fold-helper-build-failed'})`, the error shape `sendSimulatorFoldPose` reported before this cache
+ * existed, carrying the underlying failure's hint and details.
+ */
+export async function ensureFoldHelperBinary(
+  input: Readonly<{
+    signal?: AbortSignal;
+    host?: SnapshotSourceHost;
+    cacheRoot?: string;
+    sourceRoot?: string;
+  }> = {},
+): Promise<Readonly<{ path: string }>> {
+  const host = input.host ?? createFoldHelperCacheHost();
+  const deadline = createSnapshotSourceDeadline(FOLD_HELPER_PREPARATION_DEADLINE_MS, input.signal);
+  try {
+    const sourceRoot = input.sourceRoot ?? path.join(host.projectRoot(), 'apple', 'fold-helper');
+    const sourceHash = await fingerprintNativeBuildSource(
+      host,
+      sourceRoot,
+      [FOLD_HELPER_SOURCE_FILENAME],
+      deadline,
+    );
+    const toolchain = await readHostToolchainIdentity(host, deadline);
+    const cacheRoot =
+      input.cacheRoot ?? path.join(host.homeDirectory(), '.agent-device', 'fold-helper');
+    return await ensureNativeBuildCacheEntry({
+      host,
+      deadline,
+      lockDescription: FOLD_HELPER_LOCK_DESCRIPTION,
+      cacheRoot,
+      binaryFilename: FOLD_HELPER_BINARY_FILENAME,
+      keyInputs: {
+        schemaVersion: FOLD_HELPER_SCHEMA_VERSION,
+        sourceHash,
+        toolchain,
+        // Placeholder paths keep the key independent of the install location and build directory.
+        compileArgv: buildFoldHelperCompileArgv({ sourceRoot: '', outputPath: '' }),
+      },
+      build: (outputPath) => compileFoldHelper(host, deadline, sourceRoot, outputPath),
+    });
+  } catch (error) {
+    throw asFoldHelperCacheError(error);
+  }
+}
+
+function createFoldHelperCacheHost(): SnapshotSourceHost {
+  const real = createSnapshotSourceHost();
+  return {
+    ...real,
+    // Routed through the Apple tool-provider scope, not `run`'s default `runCmd`, so a fold test
+    // can fake every exec this cache makes the same way it fakes the simctl dispatch (#2796).
+    run: (command, args, options) => runAppleToolCommand(command, args, options),
+  };
+}
+
+/**
+ * The production `xcrun`/clang argv for the fold helper source, exposed so a darwin-only
+ * conformance test can compile it with `-Werror` appended and a unit test can assert it never
+ * carries `-Werror` on its own (#2796).
+ */
+export function buildFoldHelperCompileArgv(
+  input: Readonly<{ sourceRoot: string; outputPath: string }>,
+): readonly string[] {
+  return [
+    '--sdk',
+    'iphonesimulator',
+    'clang',
+    '-mios-simulator-version-min=15.0',
+    '-fobjc-arc',
+    '-Wall',
+    '-Wextra',
+    '-framework',
+    'Foundation',
+    '-framework',
+    'IOKit',
+    path.join(input.sourceRoot, FOLD_HELPER_SOURCE_FILENAME),
+    '-o',
+    input.outputPath,
+  ];
+}
+
+async function compileFoldHelper(
+  host: SnapshotSourceHost,
+  deadline: SnapshotSourceDeadline,
+  sourceRoot: string,
+  outputPath: string,
+): Promise<void> {
+  const result = await execNativeBuildClang({
+    host,
+    deadline,
+    argv: buildFoldHelperCompileArgv({ sourceRoot, outputPath }),
+    budgetMs: FOLD_HELPER_BUILD_TIMEOUT_MS,
+    label: 'fold helper',
+  });
+  if (result.exitCode !== 0 || !host.exists(outputPath)) {
+    throw foldHelperBuildFailed(execFailureDetails(result));
+  }
+}
+
+/**
+ * Rewraps a cache failure as the fold helper's build error, keeping its hint and typed details; a
+ * cancellation, and any error that is not a snapshot-source failure, passes through unchanged.
+ */
+function asFoldHelperCacheError(error: unknown): unknown {
+  if (!(error instanceof SnapshotSourceError) || error.failureKind === 'cancelled') return error;
+  const { bridgeFailure: _kind, bridgeFailureCode: cause, ...details } = error.details ?? {};
+  return foldHelperBuildFailed({ ...details, cause }, error);
+}
+
+function foldHelperBuildFailed(details: Readonly<Record<string, unknown>>, cause?: unknown) {
+  return new AppError(
+    'COMMAND_FAILED',
+    'Unable to build the simulator fold helper',
+    { hint: FOLD_HELPER_BUILD_HINT, ...details, reason: 'fold-helper-build-failed' },
+    cause,
+  );
+}
diff --git a/packages/platform-apple/src/foldable/simulator-hid.test.ts b/packages/platform-apple/src/foldable/simulator-hid.test.ts
index 3fc7c397c6..9cccc35e8f 100644
--- a/packages/platform-apple/src/foldable/simulator-hid.test.ts
+++ b/packages/platform-apple/src/foldable/simulator-hid.test.ts
@@ -1,51 +1,51 @@
-import { expect, test } from 'vitest';
-import { existsSync } from 'node:fs';
-import path from 'node:path';
+import { expect, test, vi } from 'vitest';
 import { withAppleToolProvider, createLocalAppleToolProvider } from '../core/tool-provider.ts';
 import { IOS_SIMULATOR } from '../__tests__/device-fixtures.ts';
+import { ensureFoldHelperBinary } from './fold-helper-cache.ts';
 import { sendSimulatorFoldPose } from './simulator-hid.ts';
 
+vi.mock('./fold-helper-cache.ts', () => ({
+  ensureFoldHelperBinary: vi.fn(async () => ({ path: '/cache/fold-helper' })),
+}));
+
 const selectedDuo = { ...IOS_SIMULATOR, id: 'selected-duo' };
 
-test.each(['success', 'build', 'dispatch', 'cancel'] as const)(
-  'HID route targets the UDID, cleans temporary artifacts, and handles %s',
-  async (failure) => {
-    const calls: string[][] = [];
+test.each(['success', 'dispatch', 'cancel'] as const)(
+  'HID route spawns the cached helper on the UDID and handles %s',
+  async (outcome) => {
     const controller = new AbortController();
-    let binary = '';
+    if (outcome === 'cancel') {
+      vi.mocked(ensureFoldHelperBinary).mockImplementationOnce(async () => {
+        controller.abort(new Error('cancelled'));
+        return { path: '/cache/fold-helper' };
+      });
+    }
+    const dispatches: string[][] = [];
     await withAppleToolProvider(
       createLocalAppleToolProvider({
         runCommand: async (command, args, options) => {
           expect(command).toBe('xcrun');
           expect(options?.signal).toBe(controller.signal);
-          expect(options?.timeoutMs).toBeGreaterThan(0);
-          calls.push(args);
-          if (args.includes('clang')) {
-            binary = args.at(-1)!;
-            expect(existsSync(path.dirname(binary))).toBe(true);
-            expect(existsSync(args[args.indexOf('-o') - 1]!)).toBe(true);
-            if (failure === 'cancel') controller.abort(new Error('cancelled'));
-            return { stdout: '', stderr: 'compiler detail', exitCode: failure === 'build' ? 1 : 0 };
-          }
-          expect(args).toEqual(['simctl', 'spawn', 'selected-duo', binary, 'half-open']);
-          return { stdout: '', stderr: 'spawn detail', exitCode: failure === 'dispatch' ? 1 : 0 };
+          dispatches.push([...args]);
+          return { stdout: '', stderr: 'spawn detail', exitCode: outcome === 'dispatch' ? 1 : 0 };
         },
       }),
       async () => {
         const operation = sendSimulatorFoldPose(selectedDuo, 'half-open', controller.signal);
-        if (failure === 'success') await expect(operation).resolves.toBeUndefined();
-        else if (failure === 'cancel') await expect(operation).rejects.toThrow('cancelled');
+        if (outcome === 'success') await expect(operation).resolves.toBeUndefined();
+        else if (outcome === 'cancel') await expect(operation).rejects.toThrow('cancelled');
         else
           await expect(operation).rejects.toMatchObject({
             code: 'COMMAND_FAILED',
-            details: {
-              reason: failure === 'build' ? 'fold-helper-build-failed' : 'fold-hid-dispatch-failed',
-            },
+            details: { reason: 'fold-hid-dispatch-failed', deviceId: 'selected-duo' },
           });
       },
     );
-    expect(calls).toHaveLength(failure === 'build' || failure === 'cancel' ? 1 : 2);
-    expect(existsSync(path.dirname(binary))).toBe(false);
+    expect(dispatches).toEqual(
+      outcome === 'cancel'
+        ? []
+        : [['simctl', 'spawn', 'selected-duo', '/cache/fold-helper', 'half-open']],
+    );
   },
 );
 
@@ -58,12 +58,10 @@ test('streams all keyframes in one process with a duration-derived timeout', asy
   await withAppleToolProvider(
     createLocalAppleToolProvider({
       runCommand: async (_command, args, options) => {
-        if (args[0] === 'simctl') {
-          dispatches++;
-          expect(JSON.parse(args.at(-1)!)).toEqual(keyframes);
-          expect(options?.timeoutMs).toBe(70000);
-          expect(options?.kill).toEqual({ signal: 'SIGTERM', graceMs: 1000 });
-        }
+        dispatches++;
+        expect(JSON.parse(args.at(-1)!)).toEqual(keyframes);
+        expect(options?.timeoutMs).toBe(70000);
+        expect(options?.kill).toEqual({ signal: 'SIGTERM', graceMs: 1000 });
         return { stdout: '', stderr: '', exitCode: 0 };
       },
     }),
@@ -74,18 +72,16 @@ test('streams all keyframes in one process with a duration-derived timeout', asy
 
 test('HID dispatch addresses the UDID inside its scoped simulator set', async () => {
   const dispatches: string[][] = [];
-  let binary = '';
   await withAppleToolProvider(
     createLocalAppleToolProvider({
       runCommand: async (_command, args) => {
-        if (args.includes('clang')) binary = args.at(-1)!;
-        else dispatches.push(args);
+        dispatches.push([...args]);
         return { stdout: '', stderr: '', exitCode: 0 };
       },
     }),
     () => sendSimulatorFoldPose({ ...selectedDuo, simulatorSetPath: '/tmp/scoped-set' }, 'closed'),
   );
   expect(dispatches).toEqual([
-    ['simctl', '--set', '/tmp/scoped-set', 'spawn', 'selected-duo', binary, 'closed'],
+    ['simctl', '--set', '/tmp/scoped-set', 'spawn', 'selected-duo', '/cache/fold-helper', 'closed'],
   ]);
 });
diff --git a/packages/platform-apple/src/foldable/simulator-hid.ts b/packages/platform-apple/src/foldable/simulator-hid.ts
index b59c90cb92..f16cf59811 100644
--- a/packages/platform-apple/src/foldable/simulator-hid.ts
+++ b/packages/platform-apple/src/foldable/simulator-hid.ts
@@ -1,71 +1,33 @@
-import path from 'node:path';
 import type { FoldKeyframe, FoldPose } from '@agent-device/contracts/device';
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import { AppError } from '@agent-device/kernel/errors';
 import { execFailureDetails } from '@agent-device/host-kit/command';
-import { makeHostTemporaryDirectory, removeHostDirectory } from '@agent-device/host-kit/host-file';
-import { findProjectRoot } from '@agent-device/host-kit/version';
 import { runSimctlForDevice } from '../core/simctl.ts';
-import { runXcrun } from '../core/tool-provider.ts';
+import { ensureFoldHelperBinary } from './fold-helper-cache.ts';
 
-/** Compiles for the selected Xcode and dispatches inside exactly the requested simulator. */
+/** Builds (or reuses the cached build of) the fold helper, then dispatches inside the requested simulator. */
 export async function sendSimulatorFoldPose(
   device: DeviceInfo,
   pose: FoldPose | readonly FoldKeyframe[],
   signal?: AbortSignal,
 ): Promise<void> {
   signal?.throwIfAborted();
-  const directory = await makeHostTemporaryDirectory('agent-device-fold-');
-  try {
-    const binary = path.join(directory, 'fold');
-    const build = await runXcrun(
-      [
-        '--sdk',
-        'iphonesimulator',
-        'clang',
-        '-mios-simulator-version-min=15.0',
-        '-fobjc-arc',
-        '-Wall',
-        '-Wextra',
-        '-Werror',
-        '-framework',
-        'Foundation',
-        '-framework',
-        'IOKit',
-        path.join(findProjectRoot(), 'apple', 'fold-helper', 'Fold.m'),
-        '-o',
-        binary,
-      ],
-      { signal, timeoutMs: 30_000, allowFailure: true },
+  const binary = await ensureFoldHelperBinary({ signal });
+  signal?.throwIfAborted();
+  const durationMs = typeof pose === 'string' ? 0 : pose.at(-1)!.atMs;
+  const payload = typeof pose === 'string' ? pose : JSON.stringify(pose);
+  const sent = await runSimctlForDevice(device, ['spawn', device.id, binary.path, payload], {
+    signal,
+    timeoutMs: durationMs + 10_000,
+    // simctl must forward termination to the guest before the host kills it.
+    kill: { signal: 'SIGTERM', graceMs: 1000 },
+    allowFailure: true,
+  });
+  if (sent.exitCode !== 0) {
+    throw new AppError(
+      'COMMAND_FAILED',
+      'Unable to send the simulator hinge pose',
+      execFailureDetails(sent, { reason: 'fold-hid-dispatch-failed', deviceId: device.id }),
     );
-    if (build.exitCode !== 0) {
-      throw new AppError(
-        'COMMAND_FAILED',
-        'Unable to build the simulator fold helper',
-        execFailureDetails(build, {
-          reason: 'fold-helper-build-failed',
-          hint: 'Select an Xcode with the iOS simulator SDK and foldable HID support using DEVELOPER_DIR.',
-        }),
-      );
-    }
-    signal?.throwIfAborted();
-    const durationMs = typeof pose === 'string' ? 0 : pose.at(-1)!.atMs;
-    const payload = typeof pose === 'string' ? pose : JSON.stringify(pose);
-    const sent = await runSimctlForDevice(device, ['spawn', device.id, binary, payload], {
-      signal,
-      timeoutMs: durationMs + 10_000,
-      // simctl must forward termination to the guest before the host kills it.
-      kill: { signal: 'SIGTERM', graceMs: 1000 },
-      allowFailure: true,
-    });
-    if (sent.exitCode !== 0) {
-      throw new AppError(
-        'COMMAND_FAILED',
-        'Unable to send the simulator hinge pose',
-        execFailureDetails(sent, { reason: 'fold-hid-dispatch-failed', deviceId: device.id }),
-      );
-    }
-  } finally {
-    await removeHostDirectory(directory);
   }
 }
diff --git a/packages/platform-apple/src/snapshot-source/cache-identity.ts b/packages/platform-apple/src/snapshot-source/cache-identity.ts
index 5bf7e42a1e..8c5d4c5e81 100644
--- a/packages/platform-apple/src/snapshot-source/cache-identity.ts
+++ b/packages/platform-apple/src/snapshot-source/cache-identity.ts
@@ -1,5 +1,3 @@
-import { createHash } from 'node:crypto';
-import path from 'node:path';
 import { isCommandTimeoutError, type ExecResult } from '@agent-device/host-kit/command';
 import { COLD_TOOLCHAIN_PROBE_TIMEOUT_MS } from '../runner/apple-runner-platform.ts';
 import { snapshotSourceError, type SnapshotSourceError } from './errors.ts';
@@ -13,14 +11,18 @@ import type { SnapshotSourceHost } from './types.ts';
  * identity therefore execs one Xcode-owned binary rather than two, because a toolchain probe that
  * cannot answer fails the whole job with nothing but a cache key at stake (#2712).
  */
-export type SnapshotSourceToolchainIdentity = Readonly<{
+export type HostToolchainIdentity = Readonly<{
   xcode: string;
   macosProductVersion: string;
   macosBuild: string;
   architecture: 'arm64' | 'x86_64';
-  simulatorRuntime: string;
 }>;
 
+export type SnapshotSourceToolchainIdentity = HostToolchainIdentity &
+  Readonly<{
+    simulatorRuntime: string;
+  }>;
+
 export const SNAPSHOT_BRIDGE_SOURCE_FILENAMES = [
   'SnapshotBridge.m',
   'SnapshotBridgeRuntime.m',
@@ -34,50 +36,38 @@ export const SNAPSHOT_BRIDGE_COMPILE_FILENAMES = [
   'SnapshotBridgeCapture.m',
 ] as const;
 
-export async function fingerprintSnapshotBridgeSource(
-  host: SnapshotSourceHost,
-  root: string,
-  deadline: SnapshotSourceDeadline,
-): Promise<string> {
-  const hash = createHash('sha256');
-  for (const sourceFile of SNAPSHOT_BRIDGE_SOURCE_FILENAMES) {
-    const filePath = path.join(root, sourceFile);
-    remainingSnapshotSourceMs(deadline, 'native-source-fingerprint-deadline');
-    if (!host.exists(filePath)) {
-      throw snapshotSourceError('unsupported', 'native-source-missing', { filePath });
-    }
-    hash.update(sourceFile);
-    hash.update('\0');
-    hash.update(await host.readBinary(filePath));
-    hash.update('\0');
-  }
-  return hash.digest('hex');
-}
-
-export async function readSnapshotSourceToolchain(
+/**
+ * The host's active toolchain, independent of any simulator runtime: which Xcode `xcrun` resolves
+ * against, the macOS build it runs on, and its architecture. Shared by every runtime clang build in
+ * this package, so a cache keyed on it is invalidated exactly when switching `DEVELOPER_DIR` would
+ * change what clang produces (#2796).
+ */
+export async function readHostToolchainIdentity(
   host: SnapshotSourceHost,
-  simulatorRuntime: string,
   deadline: SnapshotSourceDeadline,
-): Promise<SnapshotSourceToolchainIdentity> {
+): Promise<HostToolchainIdentity> {
   // The one Xcode-owned binary this read execs: SnapshotSourceToolchainIdentity says why (#2712).
   const xcode = await toolOutput(host, 'xcodebuild', ['-version'], deadline);
   const macosProductVersion = await toolOutput(host, 'sw_vers', ['-productVersion'], deadline);
   const macosBuild = await toolOutput(host, 'sw_vers', ['-buildVersion'], deadline);
   const architecture = await toolOutput(host, 'uname', ['-m'], deadline);
-  const runtime = simulatorRuntime.trim();
-  if (!runtime) throw snapshotSourceError('unsupported', 'simulator-runtime-missing');
   if (architecture !== 'arm64' && architecture !== 'x86_64') {
     throw snapshotSourceError('unsupported', 'simulator-architecture-unsupported', {
       architecture,
     });
   }
-  return {
-    xcode,
-    macosProductVersion,
-    macosBuild,
-    architecture,
-    simulatorRuntime: runtime,
-  };
+  return { xcode, macosProductVersion, macosBuild, architecture };
+}
+
+export async function readSnapshotSourceToolchain(
+  host: SnapshotSourceHost,
+  simulatorRuntime: string,
+  deadline: SnapshotSourceDeadline,
+): Promise<SnapshotSourceToolchainIdentity> {
+  const identity = await readHostToolchainIdentity(host, deadline);
+  const runtime = simulatorRuntime.trim();
+  if (!runtime) throw snapshotSourceError('unsupported', 'simulator-runtime-missing');
+  return { ...identity, simulatorRuntime: runtime };
 }
 
 async function toolOutput(
diff --git a/packages/platform-apple/src/snapshot-source/cache.test.ts b/packages/platform-apple/src/snapshot-source/cache.test.ts
index bfbb6da496..e157ec95a2 100644
--- a/packages/platform-apple/src/snapshot-source/cache.test.ts
+++ b/packages/platform-apple/src/snapshot-source/cache.test.ts
@@ -5,7 +5,7 @@ import path from 'node:path';
 import { test } from 'vitest';
 import { isCommandTimeoutError } from '@agent-device/host-kit/command';
 import { createSnapshotSourceHost } from './host.ts';
-import { ensureSnapshotBridgeBinary } from './cache.ts';
+import { buildSnapshotBridgeCompileArgv, ensureSnapshotBridgeBinary } from './cache.ts';
 import { SnapshotSourceError } from './errors.ts';
 import { createSnapshotSourceDeadline } from './deadline.ts';
 import { DEFAULT_SNAPSHOT_SOURCE_LIMITS } from './limits.ts';
@@ -125,6 +125,15 @@ test('snapshot bridge preparation is cold-once, atomic, and invalidates corrupt
   }
 });
 
+test('the runtime clang build never uses -Werror', () => {
+  const argv = buildSnapshotBridgeCompileArgv({
+    architecture: 'arm64',
+    sourceRoot: '',
+    outputPath: '',
+  });
+  assert.ok(!argv.includes('-Werror'));
+});
+
 test('concurrent snapshot bridge preparation publishes one cache entry', async () => {
   const root = await mkdtempForTest('agent-device-snapshot-source-concurrent-');
   const sourceRoot = path.join(root, 'source');
diff --git a/packages/platform-apple/src/snapshot-source/cache.ts b/packages/platform-apple/src/snapshot-source/cache.ts
index 4d5f4bf088..1614bd987b 100644
--- a/packages/platform-apple/src/snapshot-source/cache.ts
+++ b/packages/platform-apple/src/snapshot-source/cache.ts
@@ -1,16 +1,17 @@
-import { createHash } from 'node:crypto';
 import path from 'node:path';
-import { isCommandTimeoutError, type ExecResult } from '@agent-device/host-kit/command';
-import { withProcessLock } from '@agent-device/host-kit/file';
-import { SnapshotSourceError, snapshotSourceError } from './errors.ts';
-import { remainingSnapshotSourceMs, type SnapshotSourceDeadline } from './deadline.ts';
+import { snapshotSourceError } from './errors.ts';
+import type { SnapshotSourceDeadline } from './deadline.ts';
 import {
-  fingerprintSnapshotBridgeSource,
   readSnapshotSourceToolchain,
   SNAPSHOT_BRIDGE_COMPILE_FILENAMES,
   SNAPSHOT_BRIDGE_SOURCE_FILENAMES,
   type SnapshotSourceToolchainIdentity,
 } from './cache-identity.ts';
+import {
+  ensureNativeBuildCacheEntry,
+  execNativeBuildClang,
+  fingerprintNativeBuildSource,
+} from './native-build-cache.ts';
 import { SNAPSHOT_SOURCE_PROTOCOL_VERSION, SNAPSHOT_SOURCE_VERSION } from './protocol.ts';
 import type {
   SnapshotSourceBridgeBinary,
@@ -18,19 +19,9 @@ import type {
   SnapshotSourceLimits,
 } from './types.ts';
 
-type SnapshotBridgeCacheManifest = Readonly<{
-  schemaVersion: 1;
-  protocolVersion: number;
-  sourceVersion: string;
-  sourceHash: string;
-  cacheKey: string;
-  toolchain: SnapshotSourceToolchainIdentity;
-  binarySha256: string;
-}>;
-
 const CACHE_SCHEMA_VERSION = 1 as const;
 const BRIDGE_FILENAME = 'snapshot-bridge';
-const MANIFEST_FILENAME = 'manifest.json';
+const BRIDGE_LOCK_DESCRIPTION = 'iOS Simulator snapshot bridge cache';
 
 /**
  * @internal Upper bound on a single snapshot-bridge clang invocation, exposed for the host bridge
@@ -51,146 +42,95 @@ export async function ensureSnapshotBridgeBinary(
 ): Promise<SnapshotSourceBridgeBinary> {
   const deadline = input.deadline;
   const sourceRoot = input.sourceRoot ?? resolveSnapshotBridgeSourceRoot(input.host);
-  const sourceHash = await fingerprintSnapshotBridgeSource(input.host, sourceRoot, deadline);
+  const sourceHash = await fingerprintNativeBuildSource(
+    input.host,
+    sourceRoot,
+    SNAPSHOT_BRIDGE_SOURCE_FILENAMES,
+    deadline,
+  );
   const toolchain = await readSnapshotSourceToolchain(input.host, input.runtime, deadline);
-  const cacheKey = hashJson({
-    schemaVersion: CACHE_SCHEMA_VERSION,
-    protocolVersion: SNAPSHOT_SOURCE_PROTOCOL_VERSION,
-    sourceVersion: SNAPSHOT_SOURCE_VERSION,
-    sourceHash,
-    toolchain,
-  });
   const cacheRoot =
     input.cacheRoot ?? path.join(input.host.homeDirectory(), '.agent-device', 'snapshot-source');
-  const entryPath = path.join(cacheRoot, cacheKey);
-  return await withProcessLock({
-    acquire: () => input.host.acquireLock(path.join(cacheRoot, `${cacheKey}.lock`), { deadline }),
-    task: async () => {
-      const cached = await readValidCache(
-        input.host,
-        entryPath,
-        {
-          sourceHash,
-          cacheKey,
-          toolchain,
-        },
+  const entry = await ensureNativeBuildCacheEntry({
+    host: input.host,
+    deadline,
+    cacheRoot,
+    binaryFilename: BRIDGE_FILENAME,
+    lockDescription: BRIDGE_LOCK_DESCRIPTION,
+    keyInputs: {
+      schemaVersion: CACHE_SCHEMA_VERSION,
+      protocolVersion: SNAPSHOT_SOURCE_PROTOCOL_VERSION,
+      sourceVersion: SNAPSHOT_SOURCE_VERSION,
+      sourceHash,
+      toolchain,
+      // Placeholder paths keep the key independent of the install location and build directory.
+      compileArgv: buildSnapshotBridgeCompileArgv({
+        architecture: toolchain.architecture,
+        sourceRoot: '',
+        outputPath: '',
+      }),
+    },
+    build: async (outputPath) => {
+      const result = await execNativeBuildClang({
+        host: input.host,
         deadline,
-      );
-      if (cached) return cached;
-      remainingSnapshotSourceMs(deadline, 'native-build-deadline');
-      if (input.host.exists(entryPath)) await input.host.remove(entryPath);
-
-      remainingSnapshotSourceMs(deadline, 'native-build-deadline');
-      await input.host.ensureDirectory(cacheRoot);
-      const temporaryPath = path.join(cacheRoot, `.${cacheKey}.${input.host.processId()}.tmp`);
-      remainingSnapshotSourceMs(deadline, 'native-build-deadline');
-      await input.host.remove(temporaryPath);
-      try {
-        remainingSnapshotSourceMs(deadline, 'native-build-deadline');
-        await input.host.ensureDirectory(temporaryPath);
-        const outputPath = path.join(temporaryPath, BRIDGE_FILENAME);
-        const result = await compileSnapshotBridge(
-          input.host,
-          deadline,
-          toolchain.architecture,
+        argv: buildSnapshotBridgeCompileArgv({
+          architecture: toolchain.architecture,
           sourceRoot,
           outputPath,
-        );
-        if (result.exitCode !== 0 || !input.host.exists(outputPath)) {
-          throw snapshotSourceError('unsupported', 'native-build-failed', {
-            exitCode: result.exitCode,
-            stderr: result.stderr.slice(0, 4096),
-          });
-        }
-        remainingSnapshotSourceMs(deadline, 'native-build-deadline');
-        await input.host.chmod(outputPath, 0o755);
-        const binarySha256 = await sha256File(input.host, outputPath, deadline);
-        const manifest: SnapshotBridgeCacheManifest = {
-          schemaVersion: CACHE_SCHEMA_VERSION,
-          protocolVersion: SNAPSHOT_SOURCE_PROTOCOL_VERSION,
-          sourceVersion: SNAPSHOT_SOURCE_VERSION,
-          sourceHash,
-          cacheKey,
-          toolchain,
-          binarySha256,
-        };
-        await input.host.writeText(
-          path.join(temporaryPath, MANIFEST_FILENAME),
-          `${JSON.stringify(manifest, null, 2)}\n`,
-        );
-        remainingSnapshotSourceMs(deadline, 'native-build-deadline');
-        await input.host.rename(temporaryPath, entryPath);
-        return {
-          path: path.join(entryPath, BRIDGE_FILENAME),
-          sourceHash,
-          cacheKey,
-          protocolVersion: SNAPSHOT_SOURCE_PROTOCOL_VERSION,
-          sourceVersion: SNAPSHOT_SOURCE_VERSION,
-        };
-      } catch (error) {
-        await input.host.remove(temporaryPath);
-        throw error;
+        }),
+        budgetMs: BUILD_TIMEOUT_MS,
+        label: 'bridge',
+      });
+      if (result.exitCode !== 0 || !input.host.exists(outputPath)) {
+        throw snapshotSourceError('unsupported', 'native-build-failed', {
+          exitCode: result.exitCode,
+          stderr: result.stderr.slice(0, 4096),
+        });
       }
     },
   });
+  return {
+    path: entry.path,
+    sourceHash,
+    cacheKey: entry.cacheKey,
+    protocolVersion: SNAPSHOT_SOURCE_PROTOCOL_VERSION,
+    sourceVersion: SNAPSHOT_SOURCE_VERSION,
+  };
 }
 
 /**
- * One clang invocation for the bridge sources. A compile exec this module asked to be killed is
- * reported with the budget it hit: after the identity read stopped opening `xcrun` of its own
- * (#2712), this is the process's first `xcrun` exec, and the exec layer's bare
- * `xcrun timed out after Nms` would land on a job as an unattributed command failure again.
+ * The production `xcrun`/clang argv for the bridge sources, exposed so a darwin-only conformance
+ * test can compile it with `-Werror` appended and a unit test can assert it never carries `-Werror`
+ * on its own (#2796).
  */
-async function compileSnapshotBridge(
-  host: SnapshotSourceHost,
-  deadline: SnapshotSourceDeadline,
-  architecture: SnapshotSourceToolchainIdentity['architecture'],
-  sourceRoot: string,
-  outputPath: string,
-): Promise<ExecResult> {
-  const timeoutMs = Math.min(
-    BUILD_TIMEOUT_MS,
-    remainingSnapshotSourceMs(deadline, 'native-build-deadline'),
-  );
-  try {
-    return await host.run(
-      'xcrun',
-      [
-        '--sdk',
-        'iphonesimulator',
-        'clang',
-        '-arch',
-        architecture,
-        '-mios-simulator-version-min=15.0',
-        '-fobjc-arc',
-        '-Werror',
-        '-Wall',
-        '-Wextra',
-        '-framework',
-        'Foundation',
-        '-framework',
-        'CoreGraphics',
-        ...SNAPSHOT_BRIDGE_COMPILE_FILENAMES.map((sourceFile) => path.join(sourceRoot, sourceFile)),
-        '-o',
-        outputPath,
-      ],
-      { signal: deadline.signal, timeoutMs, allowFailure: true },
-    );
-  } catch (error) {
-    if (!isCommandTimeoutError(error)) throw error;
-    throw snapshotSourceError(
-      'timeout',
-      'native-build-stalled',
-      {
-        timeoutMs,
-        hint:
-          `The Simulator SDK toolchain did not answer within ${timeoutMs}ms, which stopped the bridge ` +
-          `build before clang reported anything. Run \`xcrun --sdk iphonesimulator clang --version\` ` +
-          `by hand until it answers, then retry.`,
-      },
-      error,
-    );
-  }
+export function buildSnapshotBridgeCompileArgv(
+  input: Readonly<{
+    architecture: SnapshotSourceToolchainIdentity['architecture'];
+    sourceRoot: string;
+    outputPath: string;
+  }>,
+): readonly string[] {
+  return [
+    '--sdk',
+    'iphonesimulator',
+    'clang',
+    '-arch',
+    input.architecture,
+    '-mios-simulator-version-min=15.0',
+    '-fobjc-arc',
+    '-Wall',
+    '-Wextra',
+    '-framework',
+    'Foundation',
+    '-framework',
+    'CoreGraphics',
+    ...SNAPSHOT_BRIDGE_COMPILE_FILENAMES.map((sourceFile) =>
+      path.join(input.sourceRoot, sourceFile),
+    ),
+    '-o',
+    input.outputPath,
+  ];
 }
 
 function resolveSnapshotBridgeSourceRoot(host: SnapshotSourceHost): string {
@@ -213,67 +153,3 @@ function resolveSnapshotBridgeSourceRoot(host: SnapshotSourceHost): string {
   }
   throw snapshotSourceError('unsupported', 'native-source-missing', { projectRoot });
 }
-
-// fallow-ignore-next-line complexity
-async function readValidCache(
-  host: SnapshotSourceHost,
-  entryPath: string,
-  expected: Readonly<{
-    sourceHash: string;
-    cacheKey: string;
-    toolchain: SnapshotSourceToolchainIdentity;
-  }>,
-  deadline: SnapshotSourceDeadline,
-): Promise<SnapshotSourceBridgeBinary | undefined> {
-  const binaryPath = path.join(entryPath, BRIDGE_FILENAME);
-  if (!host.exists(binaryPath) || !host.exists(path.join(entryPath, MANIFEST_FILENAME))) {
-    return undefined;
-  }
-  try {
-    const manifest = JSON.parse(
-      await host.readText(path.join(entryPath, MANIFEST_FILENAME)),
-    ) as Partial<SnapshotBridgeCacheManifest>;
-    if (
-      manifest.schemaVersion !== CACHE_SCHEMA_VERSION ||
-      manifest.protocolVersion !== SNAPSHOT_SOURCE_PROTOCOL_VERSION ||
-      manifest.sourceVersion !== SNAPSHOT_SOURCE_VERSION ||
-      manifest.sourceHash !== expected.sourceHash ||
-      manifest.cacheKey !== expected.cacheKey ||
-      JSON.stringify(manifest.toolchain) !== JSON.stringify(expected.toolchain) ||
-      typeof manifest.binarySha256 !== 'string'
-    ) {
-      return undefined;
-    }
-    if ((await sha256File(host, binaryPath, deadline)) !== manifest.binarySha256) return undefined;
-    return {
-      path: binaryPath,
-      sourceHash: expected.sourceHash,
-      cacheKey: expected.cacheKey,
-      protocolVersion: SNAPSHOT_SOURCE_PROTOCOL_VERSION,
-      sourceVersion: SNAPSHOT_SOURCE_VERSION,
-    };
-  } catch (error) {
-    if (
-      error instanceof SnapshotSourceError &&
-      (error.failureKind === 'cancelled' || error.failureKind === 'timeout')
-    ) {
-      throw error;
-    }
-    return undefined;
-  }
-}
-
-async function sha256File(
-  host: SnapshotSourceHost,
-  filePath: string,
-  deadline: SnapshotSourceDeadline,
-): Promise<string> {
-  remainingSnapshotSourceMs(deadline, 'native-cache-hash-deadline');
-  return createHash('sha256')
-    .update(await host.readBinary(filePath))
-    .digest('hex');
-}
-
-function hashJson(value: unknown): string {
-  return createHash('sha256').update(JSON.stringify(value)).digest('hex').slice(0, 32);
-}
diff --git a/packages/platform-apple/src/snapshot-source/host.ts b/packages/platform-apple/src/snapshot-source/host.ts
index b80421d1fe..9c11d40d3e 100644
--- a/packages/platform-apple/src/snapshot-source/host.ts
+++ b/packages/platform-apple/src/snapshot-source/host.ts
@@ -185,7 +185,7 @@ async function acquireSnapshotSourceLock(
     timeoutMs: remainingSnapshotSourceMs(deadline, 'cache-lock-deadline'),
     pollMs: 100,
     ownerGraceMs: 5_000,
-    description: 'iOS Simulator snapshot bridge cache',
+    description: options.description,
   });
   const signal = deadline.signal;
   if (!signal) return await pending;
diff --git a/packages/platform-apple/src/snapshot-source/native-build-cache.test.ts b/packages/platform-apple/src/snapshot-source/native-build-cache.test.ts
new file mode 100644
index 0000000000..2d558e37c9
--- /dev/null
+++ b/packages/platform-apple/src/snapshot-source/native-build-cache.test.ts
@@ -0,0 +1,103 @@
+import assert from 'node:assert/strict';
+import { readdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { test } from 'vitest';
+import { mkdtempForTest } from '../__tests__/tmp-dir.ts';
+import { createSnapshotSourceDeadline } from './deadline.ts';
+import { createSnapshotSourceHost } from './host.ts';
+import { ensureNativeBuildCacheEntry, fingerprintNativeBuildSource } from './native-build-cache.ts';
+import type { SnapshotSourceHost } from './types.ts';
+
+function testDeadline() {
+  return createSnapshotSourceDeadline(30_000, undefined);
+}
+
+test('a cache hit skips the build, and a key-input or binary change rebuilds', async () => {
+  const root = await mkdtempForTest('agent-device-native-build-cache-');
+  const cacheRoot = path.join(root, 'cache');
+  const host = createSnapshotSourceHost();
+  let builds = 0;
+
+  const ensure = (keyInputs: Readonly<Record<string, unknown>> = { sourceHash: 'abc' }) =>
+    ensureNativeBuildCacheEntry({
+      host,
+      deadline: testDeadline(),
+      cacheRoot,
+      binaryFilename: 'built',
+      lockDescription: 'test native build cache',
+      keyInputs,
+      build: async (outputPath) => {
+        builds += 1;
+        await writeFile(outputPath, `binary-${builds}`);
+      },
+    });
+
+  const first = await ensure();
+  assert.equal(builds, 1);
+
+  const hit = await ensure();
+  assert.equal(hit.path, first.path);
+  assert.equal(builds, 1, 'a matching cache entry is served without rebuilding');
+
+  await writeFile(first.path, 'tampered');
+  const afterTamper = await ensure();
+  assert.equal(builds, 2, 'a binary hash mismatch rebuilds instead of serving a corrupt entry');
+  assert.equal(await readFile(afterTamper.path, 'utf8'), 'binary-2');
+
+  const changedInputs = await ensure({ sourceHash: 'abc', compileArgv: ['-DNew'] });
+  assert.notEqual(changedInputs.cacheKey, first.cacheKey);
+  assert.equal(builds, 3, 'any key-input change, such as the compile argv, rebuilds');
+  const manifest = JSON.parse(
+    await readFile(path.join(path.dirname(changedInputs.path), 'manifest.json'), 'utf8'),
+  ) as Record<string, unknown>;
+  assert.deepEqual(manifest.compileArgv, ['-DNew'], 'the manifest records the key inputs');
+  assert.equal(manifest.cacheKey, changedInputs.cacheKey);
+});
+
+test('a failed build leaves no cache entry, and a later call can retry', async () => {
+  const root = await mkdtempForTest('agent-device-native-build-cache-failure-');
+  const cacheRoot = path.join(root, 'cache');
+  const host = createSnapshotSourceHost();
+  let attempts = 0;
+
+  const ensure = () =>
+    ensureNativeBuildCacheEntry({
+      host,
+      deadline: testDeadline(),
+      cacheRoot,
+      binaryFilename: 'built',
+      lockDescription: 'test native build cache',
+      keyInputs: { sourceHash: 'def' },
+      build: async (outputPath) => {
+        attempts += 1;
+        if (attempts === 1) throw new Error('build failed');
+        await writeFile(outputPath, 'binary-2');
+      },
+    });
+
+  await assert.rejects(ensure(), /build failed/);
+  assert.deepEqual(
+    (await readdir(cacheRoot)).filter((name) => !name.endsWith('.lock')),
+    [],
+    'neither an entry nor a temp directory survives the failed build',
+  );
+
+  const recovered = await ensure();
+  assert.equal(attempts, 2);
+  assert.equal(await readFile(recovered.path, 'utf8'), 'binary-2');
+});
+
+test('fingerprintNativeBuildSource keys on filename as well as content, so a rename busts the cache', async () => {
+  const root = await mkdtempForTest('agent-device-native-fingerprint-');
+  const host: SnapshotSourceHost = createSnapshotSourceHost();
+  await (await import('@agent-device/host-kit/host-file')).ensureHostDirectory(root);
+  await writeFile(path.join(root, 'A.m'), 'same content');
+  await writeFile(path.join(root, 'B.m'), 'same content');
+
+  const asA = await fingerprintNativeBuildSource(host, root, ['A.m'], testDeadline());
+  const asB = await fingerprintNativeBuildSource(host, root, ['B.m'], testDeadline());
+  assert.notEqual(asA, asB, 'identical bytes under a different filename fingerprint differently');
+
+  const again = await fingerprintNativeBuildSource(host, root, ['A.m'], testDeadline());
+  assert.equal(asA, again, 'fingerprinting is deterministic for the same root and filenames');
+});
diff --git a/packages/platform-apple/src/snapshot-source/native-build-cache.ts b/packages/platform-apple/src/snapshot-source/native-build-cache.ts
new file mode 100644
index 0000000000..33897dbf63
--- /dev/null
+++ b/packages/platform-apple/src/snapshot-source/native-build-cache.ts
@@ -0,0 +1,184 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { withProcessLock } from '@agent-device/host-kit/file';
+import { isCommandTimeoutError, type ExecResult } from '@agent-device/host-kit/command';
+import { remainingSnapshotSourceMs, type SnapshotSourceDeadline } from './deadline.ts';
+import { SnapshotSourceError, snapshotSourceError } from './errors.ts';
+import type { SnapshotSourceHost } from './types.ts';
+
+const MANIFEST_FILENAME = 'manifest.json';
+
+export type NativeBuildCacheEntry = Readonly<{ path: string; cacheKey: string }>;
+
+/**
+ * One locked cache entry keyed on everything its build depends on: a candidate hit is verified
+ * against its manifest's key and binary hash, a miss builds into a temp directory and publishes it
+ * with an atomic rename, and a build that fails leaves no partial entry behind. Every runtime clang
+ * build in this package shares this mechanism so a stale entry, a corrupt cache, or a
+ * `DEVELOPER_DIR` switch is handled once (#2796).
+ */
+export async function ensureNativeBuildCacheEntry(
+  input: Readonly<{
+    host: SnapshotSourceHost;
+    deadline: SnapshotSourceDeadline;
+    cacheRoot: string;
+    binaryFilename: string;
+    /** Names the contended resource in a lock-stall diagnostic; every caller states its own. */
+    lockDescription: string;
+    /** Everything the built binary depends on: hashed into the cache key and recorded in the manifest. */
+    keyInputs: Readonly<Record<string, unknown>>;
+    /** Builds `outputPath` and throws its own typed error on failure. */
+    build: (outputPath: string) => Promise<void>;
+  }>,
+): Promise<NativeBuildCacheEntry> {
+  const { host, deadline, cacheRoot, binaryFilename } = input;
+  const cacheKey = createHash('sha256')
+    .update(JSON.stringify(input.keyInputs))
+    .digest('hex')
+    .slice(0, 32);
+  const entryPath = path.join(cacheRoot, cacheKey);
+  return await withProcessLock({
+    acquire: () =>
+      host.acquireLock(path.join(cacheRoot, `${cacheKey}.lock`), {
+        deadline,
+        description: input.lockDescription,
+      }),
+    task: async () => {
+      const cached = await readValidCacheEntry(host, entryPath, binaryFilename, cacheKey, deadline);
+      if (cached) return { path: cached, cacheKey };
+      remainingSnapshotSourceMs(deadline, 'native-build-deadline');
+      if (host.exists(entryPath)) await host.remove(entryPath);
+      remainingSnapshotSourceMs(deadline, 'native-build-deadline');
+      await host.ensureDirectory(cacheRoot);
+      const temporaryPath = path.join(cacheRoot, `.${cacheKey}.${host.processId()}.tmp`);
+      remainingSnapshotSourceMs(deadline, 'native-build-deadline');
+      await host.remove(temporaryPath);
+      try {
+        remainingSnapshotSourceMs(deadline, 'native-build-deadline');
+        await host.ensureDirectory(temporaryPath);
+        const outputPath = path.join(temporaryPath, binaryFilename);
+        await input.build(outputPath);
+        remainingSnapshotSourceMs(deadline, 'native-build-deadline');
+        await host.chmod(outputPath, 0o755);
+        const binarySha256 = await sha256File(host, outputPath);
+        const manifest = { ...input.keyInputs, cacheKey, binarySha256 };
+        await host.writeText(
+          path.join(temporaryPath, MANIFEST_FILENAME),
+          `${JSON.stringify(manifest, null, 2)}\n`,
+        );
+        remainingSnapshotSourceMs(deadline, 'native-build-deadline');
+        await host.rename(temporaryPath, entryPath);
+        return { path: path.join(entryPath, binaryFilename), cacheKey };
+      } catch (error) {
+        await host.remove(temporaryPath);
+        throw error;
+      }
+    },
+  });
+}
+
+async function readValidCacheEntry(
+  host: SnapshotSourceHost,
+  entryPath: string,
+  binaryFilename: string,
+  cacheKey: string,
+  deadline: SnapshotSourceDeadline,
+): Promise<string | undefined> {
+  const binaryPath = path.join(entryPath, binaryFilename);
+  const manifestPath = path.join(entryPath, MANIFEST_FILENAME);
+  if (!host.exists(binaryPath) || !host.exists(manifestPath)) return undefined;
+  try {
+    const manifest = JSON.parse(await host.readText(manifestPath)) as Record<string, unknown>;
+    if (manifest.cacheKey !== cacheKey || typeof manifest.binarySha256 !== 'string') {
+      return undefined;
+    }
+    remainingSnapshotSourceMs(deadline, 'native-cache-hash-deadline');
+    const matchesBinary = (await sha256File(host, binaryPath)) === manifest.binarySha256;
+    return matchesBinary ? binaryPath : undefined;
+  } catch (error) {
+    if (isCacheReadCancellationOrTimeout(error)) throw error;
+    return undefined;
+  }
+}
+
+/** Distinguishes a real cache-read failure (corrupt entry, stale manifest) from a caller cancellation or deadline. */
+function isCacheReadCancellationOrTimeout(error: unknown): boolean {
+  return (
+    error instanceof SnapshotSourceError &&
+    (error.failureKind === 'cancelled' || error.failureKind === 'timeout')
+  );
+}
+
+async function sha256File(host: SnapshotSourceHost, filePath: string): Promise<string> {
+  return createHash('sha256')
+    .update(await host.readBinary(filePath))
+    .digest('hex');
+}
+
+/**
+ * SHA-256 over `sourceFilenames`, read from `root` in the given order and keyed by filename so a
+ * rename busts the cache. Every runtime clang build in this package fingerprints its sources this
+ * way, over its own filename list (#2796).
+ */
+export async function fingerprintNativeBuildSource(
+  host: SnapshotSourceHost,
+  root: string,
+  sourceFilenames: readonly string[],
+  deadline: SnapshotSourceDeadline,
+): Promise<string> {
+  const hash = createHash('sha256');
+  for (const sourceFile of sourceFilenames) {
+    const filePath = path.join(root, sourceFile);
+    remainingSnapshotSourceMs(deadline, 'native-source-fingerprint-deadline');
+    if (!host.exists(filePath)) {
+      throw snapshotSourceError('unsupported', 'native-source-missing', { filePath });
+    }
+    hash.update(sourceFile);
+    hash.update('\0');
+    hash.update(await host.readBinary(filePath));
+    hash.update('\0');
+  }
+  return hash.digest('hex');
+}
+
+/**
+ * One budgeted `xcrun` invocation, shared by every runtime clang build in this package so a compile
+ * exec this module asked to be killed is reported once, as `'native-build-stalled'`, with the
+ * budget it hit and a hint naming `label`'s build (#2796).
+ */
+export async function execNativeBuildClang(
+  input: Readonly<{
+    host: SnapshotSourceHost;
+    deadline: SnapshotSourceDeadline;
+    argv: readonly string[];
+    budgetMs: number;
+    /** Names the build in the stall hint, e.g. "bridge" or "fold helper". */
+    label: string;
+  }>,
+): Promise<ExecResult> {
+  const timeoutMs = Math.min(
+    input.budgetMs,
+    remainingSnapshotSourceMs(input.deadline, 'native-build-deadline'),
+  );
+  try {
+    return await input.host.run('xcrun', [...input.argv], {
+      signal: input.deadline.signal,
+      timeoutMs,
+      allowFailure: true,
+    });
+  } catch (error) {
+    if (!isCommandTimeoutError(error)) throw error;
+    throw snapshotSourceError(
+      'timeout',
+      'native-build-stalled',
+      {
+        timeoutMs,
+        hint:
+          `The Simulator SDK toolchain did not answer within ${timeoutMs}ms, which stopped the ${input.label} ` +
+          `build before clang reported anything. Run \`xcrun --sdk iphonesimulator clang --version\` ` +
+          `by hand until it answers, then retry.`,
+      },
+      error,
+    );
+  }
+}
diff --git a/packages/platform-apple/src/snapshot-source/native-runtime.test.ts b/packages/platform-apple/src/snapshot-source/native-runtime.test.ts
index 9e8939e6d4..32e88106a9 100644
--- a/packages/platform-apple/src/snapshot-source/native-runtime.test.ts
+++ b/packages/platform-apple/src/snapshot-source/native-runtime.test.ts
@@ -4,7 +4,7 @@ import path from 'node:path';
 import { beforeAll, describe, test } from 'vitest';
 import { runCmd } from '@agent-device/host-kit/command';
 import { mkdtempForTest } from '../__tests__/tmp-dir.ts';
-import { BUILD_TIMEOUT_MS } from './cache.ts';
+import { buildSnapshotBridgeCompileArgv, BUILD_TIMEOUT_MS } from './cache.ts';
 import { createSnapshotSourceDeadline, remainingSnapshotSourceMs } from './deadline.ts';
 
 // The host bridge compile is budgeted from a deadline sized to production's build ceiling, not a
@@ -94,6 +94,35 @@ const recoveryFixture = JSON.parse(readFileSync(recoveryFixturePath, 'utf8')) as
   recoveryCases: readonly { name: string }[];
 };
 
+// #2796: the production compile drops -Werror so a stale toolchain warning cannot fail a build; this
+// is the gate that keeps a new SnapshotBridge*.m warning from passing CI unnoticed. It runs the
+// production argv (`buildSnapshotBridgeCompileArgv`) against the real iphonesimulator SDK with
+// -Werror appended, so a warning fails here instead of nowhere.
+describe.skipIf(process.platform !== 'darwin')('bridge warning gate', () => {
+  // The compile runs in beforeAll, not in the test body: it is a real clang invocation (see the
+  // unit slow-test budget in docs/agents/testing.md), and this file's other describe blocks
+  // already keep their compiles out of test-case wall time the same way.
+  let compiled: { exitCode: number; stderr: string };
+  beforeAll(async () => {
+    const nativeRoot = path.resolve(import.meta.dirname, '../../../../apple/snapshot-bridge');
+    const binary = path.join(await mkdtempForTest('snapshot-bridge-werror-'), 'snapshot-bridge');
+    const architecture = process.arch === 'arm64' ? 'arm64' : 'x86_64';
+    const argv = buildSnapshotBridgeCompileArgv({
+      architecture,
+      sourceRoot: nativeRoot,
+      outputPath: binary,
+    });
+    compiled = await runCmd('xcrun', [...argv, '-Werror'], {
+      allowFailure: true,
+      timeoutMs: BUILD_TIMEOUT_MS,
+    });
+  }, COMPILE_HOOK_TIMEOUT_MS);
+
+  test('the production bridge argv compiles clean under -Werror', () => {
+    assert.equal(compiled.exitCode, 0, compiled.stderr);
+  });
+});
+
 describe.skipIf(process.platform !== 'darwin')(
   'shared AX recovery conformance (host bridge)',
   () => {
diff --git a/packages/platform-apple/src/snapshot-source/types.ts b/packages/platform-apple/src/snapshot-source/types.ts
index 2cec940121..fa0b20c838 100644
--- a/packages/platform-apple/src/snapshot-source/types.ts
+++ b/packages/platform-apple/src/snapshot-source/types.ts
@@ -103,7 +103,10 @@ export type SnapshotSourceHost = Readonly<{
   remove(path: string): Promise<void>;
   acquireLock(
     path: string,
-    options: { deadline: SnapshotSourceDeadline },
+    /** `description` names the contended resource in a stall's diagnostic, e.g. "iOS Simulator
+     * snapshot bridge cache"; every lock holder states its own, since this host is shared by every
+     * runtime clang build in the package. */
+    options: { deadline: SnapshotSourceDeadline; description: string },
   ): Promise<() => Promise<void>>;
   emitDiagnostic(event: {
     level?: 'debug' | 'info' | 'warn' | 'error';
diff --git a/src/__tests__/command-descriptor-timeout-policy.test.ts b/src/__tests__/command-descriptor-timeout-policy.test.ts
index 89888805d6..906cf289c0 100644
--- a/src/__tests__/command-descriptor-timeout-policy.test.ts
+++ b/src/__tests__/command-descriptor-timeout-policy.test.ts
@@ -143,9 +143,10 @@ test('request envelopes deviating from the default are bounded, reviewed sets',
     reinstall: 180_000,
     install_source: 180_000,
     longpress: 210_000,
-    // fold: one macOS helper press (30s) plus up to four bounded CoreDevice hinge reads (20s
-    // each on a wedged host) can pass the default envelope; the policy covers that worst case.
-    fold: 210_000,
+    // fold: display-inventory query + fold-helper preparation + HID dispatch + hinge settle
+    // reads + lit-panel display-inventory query can sum to 220s worst case; the policy covers
+    // that with margin.
+    fold: 240_000,
     // #1774: base allocation budget (300s) + client/daemon race margin (30s).
     lease_allocate: 330_000,
     test: 'unbounded',
diff --git a/src/commands/schema/cli-help.ts b/src/commands/schema/cli-help.ts
index d72fcd1264..9177607575 100644
--- a/src/commands/schema/cli-help.ts
+++ b/src/commands/schema/cli-help.ts
@@ -753,7 +753,7 @@ Changing the pose:
   Expect a fold to take 10-16 seconds: each hinge read is a five-second devicectl stream, and half-open waits for the hinge to stop moving. Re-snapshot after every fold; refs and coordinates from before it are stale, and the command's message says so.
   Timed motion: fold --keyframes '[{"atMs":0,"angle":0},{"atMs":5000,"angle":180}]'. Use 2–64 frames starting at 0ms, increasing integer timestamps up to 60000ms, and angles from 0 to 180. The last timestamp sets motion duration, excluding setup and verification. Equal angles hold; cancellation stops motion. See the fold examples in the command and Node API documentation for trajectories.
 
-  Requirements: an iOS simulator session on a foldable device and an Xcode toolchain with the iOS simulator SDK and foldable HID support (verified on Xcode 27.1). Device Hub and host Accessibility permission are not required. The command builds a small temporary helper with the selected Xcode and runs it through simctl spawn for the session UDID; build or dispatch failures are reported without a UI fallback. The app under test reads the resulting pose as UIHinge.status.
+  Requirements: an iOS simulator session on a foldable device and an Xcode toolchain with the iOS simulator SDK and foldable HID support (verified on Xcode 27.1). Device Hub and host Accessibility permission are not required. The command runs a small helper through simctl spawn for the session UDID; the helper is built once per Fold.m source hash and Xcode toolchain, cached under ~/.agent-device/fold-helper, and rebuilt only when the source or the toolchain changes. Build or dispatch failures are reported without a UI fallback. The app under test reads the resulting pose as UIHinge.status.
   If a task asserts behavior for more than one pose, fold to each pose and re-snapshot, and report which poses the run covered.`,
   },
   remote: {
diff --git a/test/integration/provider-scenarios/ios-fold.test.ts b/test/integration/provider-scenarios/ios-fold.test.ts
index 7ba5beef58..49beb7d31e 100644
--- a/test/integration/provider-scenarios/ios-fold.test.ts
+++ b/test/integration/provider-scenarios/ios-fold.test.ts
@@ -4,11 +4,32 @@ import { assertRpcOk } from './assertions.ts';
 import { makeIosAppSession } from '../../../src/__tests__/test-utils/session-factories.ts';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
-import { test } from 'vitest';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, test } from 'vitest';
 import { createProviderScenarioHarness } from './harness.ts';
 import { createRecordingAppleToolProvider } from './providers.ts';
 import { PROVIDER_SCENARIO_IOS_SIMULATOR } from './fixtures.ts';
 
+// The fold helper's build cache lives under the host home directory (#2796), so this test scopes
+// HOME to a throwaway directory: otherwise it would read and write the real developer/CI machine's
+// `~/.agent-device/fold-helper` cache and the `builds` assertion below would depend on whatever that
+// machine's cache already held.
+let previousHome: string | undefined;
+let isolatedHome: string;
+
+beforeEach(() => {
+  previousHome = process.env.HOME;
+  isolatedHome = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-fold-home-'));
+  process.env.HOME = isolatedHome;
+});
+
+afterEach(() => {
+  if (previousHome === undefined) delete process.env.HOME;
+  else process.env.HOME = previousHome;
+  fs.rmSync(isolatedHome, { recursive: true, force: true });
+});
+
 test('timed fold keyframes reach simulator HID through the public client and daemon', async () => {
   const trajectory = [
     { atMs: 0, angle: 0 },
@@ -49,9 +70,21 @@ test('timed fold keyframes reach simulator HID through the public client and dae
     appleToolProvider: () => ({
       ...tool.provider,
       runCommand: async (command, args) => {
+        if (command === 'xcodebuild') {
+          return { stdout: 'Xcode 16.4\nBuild version 16F6', stderr: '', exitCode: 0 };
+        }
+        if (command === 'sw_vers') {
+          return {
+            stdout: args.includes('-buildVersion') ? '24G90' : '15.6',
+            stderr: '',
+            exitCode: 0,
+          };
+        }
+        if (command === 'uname') return { stdout: 'arm64', stderr: '', exitCode: 0 };
         assert.equal(command, 'xcrun');
         assert.ok(args.includes('clang'));
         builds++;
+        fs.writeFileSync(args.at(-1)!, 'fold-helper-binary');
         return ok;
       },
     }),
@@ -83,7 +116,8 @@ test('timed fold keyframes reach simulator HID through the public client and dae
       await daemon.callCommand(parsed.command, parsed.positionals ?? [], parsed.flags),
     );
     assert.equal(replayed.hingeAngleDegrees, 100);
-    assert.equal(builds, 2);
+    // The second fold call reuses the cached fold helper binary instead of rebuilding (#2796).
+    assert.equal(builds, 1);
     assert.equal(tool.calls.filter((call) => call.includes('spawn')).length, 2);
     assert.equal(tool.calls.filter((call) => call.includes('hinge-angle')).length, 4);
   } finally {
diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md
index b2a54416e2..55319492a5 100644
--- a/website/docs/docs/commands.md
+++ b/website/docs/docs/commands.md
@@ -92,7 +92,7 @@ agent-device fold open
 - `action-button` reports that the press was dispatched, not what the system did with it. Simulators run no Shortcuts and no App Intents, so what a press triggers can only be verified on a physical iPhone; on a Simulator the command proves the press was accepted and that the session app was not brought forward.
 - `fold <closed|half-open|open>` puts a foldable iPhone simulator (iPhone Duo) into a hinge pose. The command sends a private HID hinge event inside the selected simulator (ADR 0025), then reads the hinge angle back with `devicectl device motion hinge-angle` and reports the pose only when that reading agrees: `closed` is 0°, `open` is 180°, and `half-open` is any angle between them (requested at 130°). An angle inside that interval only proves the category, so `half-open` is reported once two consecutive readings both fall inside it and agree within 0.5°. The response names the panel the device now lights and its native panel point size, marked `coordinateSpace: "native-panel"`; that size is the panel's own geometry, not the next snapshot's viewport (a 669x951 inner panel can host a 951x669 app window), so it cannot place a tap. Re-snapshot afterwards, and never carry refs or coordinates across a `fold`. After that snapshot, taps, long presses, and scrolling follow the app window on the active panel in closed, half-open, and open poses.
 - For timed motion, use `fold --keyframes '[{"atMs":0,"angle":0},{"atMs":1667,"angle":160},{"atMs":3333,"angle":100},{"atMs":5000,"angle":180}]'`. This runs the opening/reversal/reopening sequence over five seconds. Supply either a preset or keyframes, never both. Use 2–64 keyframes starting at 0ms with strictly increasing integer timestamps up to 60,000ms and finite angles in 0–180°. Linear interpolation runs at roughly 60Hz; equal consecutive angles hold the hinge. Motion duration excludes preparation and final-angle verification. Cancellation stops at the current angle; re-snapshot even after an interrupted trajectory.
-- `fold` is simulator-only and requires an Xcode toolchain with the iOS simulator SDK and foldable HID support (verified on Xcode 27.1). It compiles a temporary helper and runs it against the session UDID. Device Hub and host Accessibility permission are not required. Build failures report `fold-helper-build-failed`; dispatch failures report `fold-hid-dispatch-failed`. There is no UI fallback. Single-panel simulators and physical devices are refused.
+- `fold` is simulator-only and requires an Xcode toolchain with the iOS simulator SDK and foldable HID support (verified on Xcode 27.1). It runs a helper against the session UDID; the helper is built once per `Fold.m` source hash and Xcode toolchain, cached under `~/.agent-device/fold-helper`, and rebuilt only when the source or the toolchain changes. Device Hub and host Accessibility permission are not required. Build failures report `fold-helper-build-failed`; dispatch failures report `fold-hid-dispatch-failed`. There is no UI fallback. Single-panel simulators and physical devices are refused.
 - `fold` costs one bounded hinge stream per read, and devicectl's smallest stream is five seconds: `closed` and `open` take about ten seconds, `half-open` about sixteen, because the hinge animates and the command waits for it to stop. A hinge whose last reading is some other pose fails with `COMMAND_FAILED` and `reason: fold-pose-unverified`, naming the angle CoreDevice still reports. A hinge seen `half-open` but never at rest fails with `reason: fold-pose-unsettled`, naming the observed and previous angles: the requested category was observed, and what is missing is a pose the hinge holds (#2730).
 - `action-button` is not a cheap command to loop. On an iPhone 17 Pro Simulator the press itself spent about five seconds inside XCUITest, while `home` and `app-switcher` on the same session took under two seconds each.
 - On iOS devices, `http(s)://` URLs open in Safari when no app is active. Custom scheme URLs require an active app in the session.

From 01923482c02bc6855b69b8ab23f57985983f2ca5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 24 Sep 2026 14:46:29 +0200
Subject: [PATCH 091/132] fix(ios): parse the Xcode 27 <tagged-backtrace>
 time-profile stack (#2889)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(ios): parse the Xcode 27 <tagged-backtrace> time-profile stack

Xcode 27 renamed the time-profile stack element and its engineering-type to
tagged-backtrace while keeping the same frame children and id/ref reuse. The
parser matched only <backtrace>, so every row of an Xcode 27 export resolved no
stack, and writeAppleXctracePerfReport failed a trace holding tens of thousands
of samples with "Apple xctrace CPU report contained no samples". Read either
spelling through one name set so id/ref resolution, the innermost-frame rule,
and the report shape stay exactly as they were for older exports.

The fixture is a verbatim 22-row prefix of an xctrace 27.1 (27A9269) export: 19
stack definitions, 2 rows naming their stack through a tagged-backtrace ref, 4
innermost frames and 3 innermost binaries reached through refs, and one row
whose stack column is a sentinel. The multi-run test now carries a cross-run
frame ref because a real append-run export numbers ids with one counter across
its runs.

Closes #2860

* chore(gates): own .xml package captures in the affected selector

The package-capture ownership rule matched .json only, so the first recorded
xctrace export under a package fixture directory had no derivable owner and
failed the gate open to all 59 checks even though exactly one suite reads it.
Accept .xml beside .json and pin both spellings in the ownership test.

* test(ios): synthesize the Xcode 27 time-profile rows instead of committing a capture

The captured export leaked a machine's home directory, per-user temp-dir token,
and installed-software identity — an MDM endpoint-security agent among them —
into a public repo, and a 30 KB blob of 2000-char lines defeats diff, format, and
grep for coverage the synthetic rows already give.

Keep the shapes that capture proved: a `<tagged-backtrace>` definition, a row that
names its stack by ref, a `truncated="YES"` stack whose innermost frame is a
`<frame ref>`, an innermost `<binary ref>`, and a stack-column `<sentinel/>` row.
The binary-ref case is the one the pre-existing suite survived before. Symbols,
binaries, and weights are synthetic.

Give the cross-run frame reference its own test, so the multi-run aggregation case
keeps answering independently the way it did before this PR.

* chore(gates): drop the .xml package-capture extension

That extension was added only to own the captured xctrace export this branch no
longer commits, so the rule would own nothing real. Revert to the `.json` capture
rule and keep the ownership test on the captures that exist.
---
 CHANGELOG.md                                  |  6 ++
 .../core/__tests__/perf-time-profile.test.ts  | 76 +++++++++++++++++++
 .../src/core/perf-time-profile.ts             | 11 ++-
 3 files changed, 90 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f84ddd4613..3563479a11 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+- Fixed (ios): `perf cpu profile report --kind xctrace` on Xcode 27 no longer fails with
+  `Apple xctrace CPU report contained no samples` on a trace that holds thousands of samples. Xcode
+  27 exports each `time-profile` sample stack as `<tagged-backtrace>` instead of `<backtrace>`, and
+  the parser read only the old element, so every row resolved no stack at all. Both spellings now
+  parse through the same `id`/`ref` resolution, so a profile recorded with an older Xcode reports
+  what it did before. (#2860)
 - Changed (apple): a read-only runner command is resent inside the same request only when the
   runner refused it as `RUNNER_BUSY`. Before, any `COMMAND_FAILED` carrying `details.retriable:
   true` was sent up to three times. That flag tells a caller's own poll, such as `wait`, to try
diff --git a/packages/platform-apple/src/core/__tests__/perf-time-profile.test.ts b/packages/platform-apple/src/core/__tests__/perf-time-profile.test.ts
index 0fe89b0cd9..0f7ce6d46b 100644
--- a/packages/platform-apple/src/core/__tests__/perf-time-profile.test.ts
+++ b/packages/platform-apple/src/core/__tests__/perf-time-profile.test.ts
@@ -2,6 +2,58 @@ import assert from 'node:assert/strict';
 import { test } from 'vitest';
 import { parseAppleTimeProfileSummary } from '../perf-time-profile.ts';
 
+test('reads Xcode 27 tagged-backtrace stacks and skips stack sentinels', () => {
+  // xctrace 27 renamed the `time-profile` stack element to `<tagged-backtrace>` and kept the same
+  // `id`/`ref` reuse over frames and binaries. These row shapes come from a real 27.1 export; the
+  // symbols, binaries, and weights here are synthetic.
+  const summary = parseAppleTimeProfileSummary(
+    `<trace-query-result><node>
+      <row>
+        <weight id="weight-1">1000000</weight>
+        <tagged-backtrace id="stack-1">
+          <frame id="frame-1" name="hot"><binary id="binary-1" name="App"/></frame>
+          <frame name="caller"><binary name="Framework"/></frame>
+        </tagged-backtrace>
+      </row>
+      <row><weight ref="weight-1"/><tagged-backtrace ref="stack-1"/></row>
+      <row>
+        <weight ref="weight-1"/>
+        <tagged-backtrace id="stack-2" truncated="YES"><frame ref="frame-1"/></tagged-backtrace>
+      </row>
+      <row>
+        <weight ref="weight-1"/>
+        <tagged-backtrace id="stack-3">
+          <frame id="frame-2" name="warm"><binary ref="binary-1"/></frame>
+        </tagged-backtrace>
+      </row>
+      <row><weight ref="weight-1"/><sentinel/></row>
+    </node></trace-query-result>`,
+    2,
+  );
+
+  // `hot` is sampled as a stack definition, through a `<tagged-backtrace ref>`, and through a
+  // truncated stack whose innermost frame is a `<frame ref>`. `warm` reaches its binary only
+  // through `<binary ref>`, and the sentinel row carries a weight with no stack at all.
+  assert.deepEqual(summary, {
+    sampleCount: 4,
+    totalSampleWeightMs: 4,
+    topFunctions: [
+      {
+        symbol: 'hot',
+        binary: 'App',
+        selfSampleMs: 3,
+        selfSamplePercent: 75,
+      },
+      {
+        symbol: 'warm',
+        binary: 'App',
+        selfSampleMs: 1,
+        selfSamplePercent: 25,
+      },
+    ],
+  });
+});
+
 test('aggregates weighted innermost frames and follows xctrace references', () => {
   const summary = parseAppleTimeProfileSummary(
     `<trace-query-result><node><row>
@@ -44,6 +96,30 @@ test('aggregates rows exported from multiple trace runs', () => {
   assert.equal(summary.topFunctions[0]?.symbol, 'runTwo');
 });
 
+test('resolves a frame reference an earlier trace run defined', () => {
+  // A real `xctrace record --append-run` export numbers element ids with one counter across its
+  // runs, so a row of a later run refs a frame an earlier run defined. Scoping the id index per
+  // `<node>` would drop that row's frame instead of attributing it to the earlier symbol.
+  const summary = parseAppleTimeProfileSummary(
+    `<trace-query-result>
+      <node xpath="/trace-toc/run[1]"><row><weight>1000000</weight><tagged-backtrace><frame id="frame-1" name="shared"/></tagged-backtrace></row></node>
+      <node xpath="/trace-toc/run[2]"><row><weight>3000000</weight><tagged-backtrace><frame ref="frame-1"/></tagged-backtrace></row></node>
+    </trace-query-result>`,
+  );
+  assert.deepEqual(summary, {
+    sampleCount: 2,
+    totalSampleWeightMs: 4,
+    topFunctions: [
+      {
+        symbol: 'shared',
+        binary: undefined,
+        selfSampleMs: 4,
+        selfSamplePercent: 100,
+      },
+    ],
+  });
+});
+
 test('skips incomplete rows', () => {
   assert.deepEqual(
     parseAppleTimeProfileSummary(
diff --git a/packages/platform-apple/src/core/perf-time-profile.ts b/packages/platform-apple/src/core/perf-time-profile.ts
index ee34f145e3..a13bc9c3ec 100644
--- a/packages/platform-apple/src/core/perf-time-profile.ts
+++ b/packages/platform-apple/src/core/perf-time-profile.ts
@@ -4,6 +4,11 @@ import { findAllXmlNodes, indexXmlNodesById, resolveXmlReference } from './perf-
 
 const APPLE_TIME_PROFILE_FUNCTION_LIMIT = 10;
 
+// Xcode 27 renamed the `time-profile` stack element and its `engineering-type` to
+// `<tagged-backtrace>` while keeping the same `<frame>` children and `id`/`ref` reuse, so both
+// spellings carry one sampled stack.
+const APPLE_TIME_PROFILE_STACK_ELEMENT_NAMES = new Set(['backtrace', 'tagged-backtrace']);
+
 export type AppleTimeProfileFunction = {
   symbol: string;
   binary?: string;
@@ -78,14 +83,14 @@ function readRowWeightNs(row: XmlNode, nodesById: Map<string, XmlNode>): number
 }
 
 function readInnermostFrame(row: XmlNode, nodesById: Map<string, XmlNode>): XmlNode | undefined {
-  const backtrace = resolveXmlReference(
-    row.children.find((node) => node.name === 'backtrace'),
+  const stack = resolveXmlReference(
+    row.children.find((node) => APPLE_TIME_PROFILE_STACK_ELEMENT_NAMES.has(node.name)),
     nodesById,
   );
   // xctrace lists a sampled backtrace from the innermost frame outward. The first
   // frame therefore owns self time; a focused multi-frame test pins this ordering.
   return resolveXmlReference(
-    backtrace?.children.find((node) => node.name === 'frame'),
+    stack?.children.find((node) => node.name === 'frame'),
     nodesById,
   );
 }

From d852b7952b0cf086e9c978460fab7b822888b550 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 24 Sep 2026 15:51:03 +0200
Subject: [PATCH 092/132] fix(interaction): carry one post-gesture outcome on
 the tree and disclose it on every route (#2864)

A selector click, press, or fill right after a scroll whose surface never
settled missed on that moving tree and answered a plain selector_not_found,
and find lost the fact when a sparse capture was recovered by a re-capture.
A proven no-effect gesture reached only snapshot, through annotations that
selector reads and interactions drop.

Both facts are one field, SnapshotState.postGestureOutcome ({ kind:
'unsettled' | 'no-effect', gesture }), stamped by post-gesture
stabilization. A re-capture taken at once to recover or widen that tree
inherits it. Every route discloses it through withCaptureDisclosures;
interactions pass their request capture proof as the consumed tree. A
failure's disclosure sentence now lands in error.hint, the hint request
finalization keeps. withGestureNoEffectWarning is deleted.

Closes #2853
Closes #2856
---
 CHANGELOG.md                                  | 14 ++--
 .../capture-kit/src/post-gesture-stability.ts | 65 ++++++--------
 packages/kernel/src/snapshot.ts               | 25 +++++-
 packages/selectors/src/absence-observation.ts |  7 +-
 src/commands/capture/runtime/snapshot.test.ts | 12 ++-
 src/commands/capture/runtime/snapshot.ts      |  6 +-
 .../interaction/runtime/resolution.ts         |  8 +-
 .../interaction/runtime/wait-absent.test.ts   |  5 +-
 ...pture-disclosure-target-activation.test.ts | 16 ++--
 .../__tests__/capture-disclosure.test.ts      | 14 ++--
 .../deferred-interaction-outcome.test.ts      |  8 +-
 src/daemon/__tests__/is-runtime.test.ts       | 58 +++++++++++--
 .../post-gesture-no-effect-claim.test.ts      | 37 +++++---
 .../post-gesture-stabilization.test.ts        |  9 +-
 .../selector-capture-runtime.test.ts          | 16 ++--
 ...ts => snapshot-runtime-disclosure.test.ts} | 50 ++++++++++-
 src/daemon/capture-disclosure.ts              | 81 +++++++++---------
 src/daemon/deferred-interaction-outcome.ts    |  7 +-
 src/daemon/gesture-no-effect.ts               | 22 -----
 .../find-target-activation-disclosure.test.ts | 53 ++++++++----
 ...=> interaction-capture-disclosure.test.ts} | 84 ++++++++++++++++++-
 .../internal/find-target-capture.ts           |  6 +-
 src/daemon/interaction/internal/find.ts       | 12 +--
 .../internal/interaction-runtime.ts           |  4 +-
 .../interaction/internal/interaction.ts       | 15 ++--
 src/daemon/interaction/internal/types.ts      |  4 +-
 src/daemon/selector-capture-runtime.ts        | 37 ++++----
 src/daemon/selector-runtime-backend.ts        |  8 +-
 src/daemon/selector-runtime.ts                |  6 +-
 src/daemon/snapshot-runtime.ts                | 10 +--
 src/daemon/wait-current-surface.test.ts       |  8 +-
 src/daemon/wait-current-surface.ts            |  8 +-
 src/daemon/wait-runtime.ts                    |  6 +-
 ...os-simulator-e2e-visibility-scroll.test.ts | 24 +++++-
 .../ios-simulator-e2e/live-assertions.ts      |  2 +-
 website/docs/docs/commands.md                 |  4 +-
 36 files changed, 490 insertions(+), 261 deletions(-)
 rename src/daemon/__tests__/{snapshot-runtime-target-activation.test.ts => snapshot-runtime-disclosure.test.ts} (71%)
 delete mode 100644 src/daemon/gesture-no-effect.ts
 rename src/daemon/interaction/internal/__tests__/{interaction-target-activation-disclosure.test.ts => interaction-capture-disclosure.test.ts} (53%)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3563479a11..63fc667515 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -26,11 +26,15 @@
 - Fixed (mobile): a read taken right after a `scroll`, `swipe`, or `gesture swipe` no longer reports
   a definite miss when the surface never settled. When post-gesture stabilization ran out of budget
   on a surface still moving, `is visible` answered a plain `selector_not_found` and `is absent`
-  passed. That capture now carries `unsettledGesture`: `is`, `get`, `find`, and `wait` report it (in
-  `error.details` or `data`) with an appended warning, `snapshot` appends the warning, `is absent`
-  refuses with `observation: "unsettled"`, `wait absent` keeps polling, and the next read captures
-  afresh. Click, press, and fill by selector do not disclose it yet. A failed read now also carries
-  `targetActivation` in `error.details`, the same place as `unsettledGesture`.
+  passed. The capture now carries `postGestureOutcome` (`{ kind, gesture: { action, positionals } }`)
+  with `kind: "unsettled"`, and so does a re-capture taken at once to recover or widen it. A proven
+  no-effect gesture rides the same field with `kind: "no-effect"`; before, its warning reached only
+  `snapshot`. `is`, `get`, `find`, `wait`, and every interaction that captured it (`click`, `press`,
+  `fill`, and the other touch and gesture commands) report the field in `data` or `error.details`
+  with an appended warning; `snapshot` appends the warning. `is absent` refuses an unsettled capture
+  with `observation: "unsettled"`, `wait absent` keeps polling, and the next read captures afresh.
+  A failed read also carries `targetActivation` in `error.details`, and a failed interaction now
+  keeps the disclosure sentences in its hint.
 - Fixed (ios): `open` on a local Simulator now waits for the launched app's discovery before it
   decides whether the app is observable. On a loaded host `simctl spawn launchctl list` outlasts one
   1.5 s discovery wait slice, and the launch observation read that slice as an unobservable app, so
diff --git a/packages/capture-kit/src/post-gesture-stability.ts b/packages/capture-kit/src/post-gesture-stability.ts
index 438a674bbb..5ce237f1ce 100644
--- a/packages/capture-kit/src/post-gesture-stability.ts
+++ b/packages/capture-kit/src/post-gesture-stability.ts
@@ -1,6 +1,6 @@
 import { emitDiagnostic } from '@agent-device/host-kit/diagnostics';
 import { sleep } from '@agent-device/host-kit/retry';
-import type { PostGestureAction } from '@agent-device/kernel/snapshot';
+import type { PostGestureAction, PostGestureOutcome } from '@agent-device/kernel/snapshot';
 
 /**
  * Pure post-gesture stability mechanics: the quiet-window polling loop and the
@@ -59,41 +59,37 @@ export type PostGestureStabilityHooks<T, S extends readonly unknown[]> = {
 
 export type PostGestureStabilityOutcome<T> = {
   value: T;
-  /** Present when the deadline expired while the last two captures still disagreed. */
-  unsettledGesture?: PostGestureAction;
   /**
-   * Present ONLY when the accept-stale verdict is corroborated by full-surface
-   * evidence (`surfacesIdentical`). The bare verdict is NOT enough — it is
-   * subset-tolerant by design, and a successful scroll that replaced every
-   * list cell under fixed chrome still reads accept-stale (#1601 review P1).
-   * Callers surface this to the agent: a diagnostics-only signal let one
-   * benchmark run burn 40 calls re-issuing scrolls that moved nothing (#1600).
+   * `unsettled` when the deadline expired while the last two captures still disagreed.
+   * `no-effect` ONLY when the accept-stale verdict is corroborated by full-surface evidence
+   * (`surfacesIdentical`): the bare verdict is subset-tolerant by design, and a successful scroll
+   * that replaced every list cell under fixed chrome still reads accept-stale (#1601 review P1).
+   * Callers surface it to the agent: a diagnostics-only signal let one benchmark run burn 40 calls
+   * re-issuing scrolls that moved nothing (#1600).
    */
-  gestureNoEffect?: PostGestureAction;
+  postGestureOutcome?: PostGestureOutcome;
 };
 
-function describePostGestureAction(gesture: PostGestureAction): string {
-  return [gesture.action, ...gesture.positionals].join(' ').trim();
-}
-
 /**
- * The agent-facing wording for a proven no-effect gesture. Names the exact
- * gesture, admits the honest ambiguity (at-edge is a legitimate no-op the
- * platform cannot distinguish), and hands over the one escape hatch that
- * moved a stuck list when synthesized scrolls did not (#1600, element-18:
- * raw `swipe` worked where scroll/fling/pan all silently no-opped).
+ * The agent-facing sentence for a post-gesture outcome, true whether the read that carries it found
+ * its target or not. A no-effect gesture admits the honest ambiguity (at-edge is a legitimate no-op
+ * the platform cannot distinguish) and hands over the escape hatch that moved a stuck list when
+ * synthesized scrolls did not (#1600: raw `swipe` worked where scroll/fling/pan all no-opped).
  */
-export function formatGestureNoEffectWarning(action: string, positionals: string[]): string {
-  return (
-    `${describePostGestureAction({ action, positionals })} produced no visible change: the tree still matches its pre-gesture state. ` +
-    'Either the container is already at its edge, or it ignores synthesized scrolls — ' +
-    'a raw drag moves such lists: swipe x1 y1 x2 y2 (start inside the list).'
-  );
+export function formatPostGestureOutcomeWarning({ kind, gesture }: PostGestureOutcome): string {
+  const named = [gesture.action, ...gesture.positionals].join(' ').trim();
+  return kind === 'unsettled'
+    ? `The surface was still changing after ${named} when this tree was read, so it may not match where the surface comes to rest: an element missing from it is not proof of absence.`
+    : `${named} produced no visible change: the tree still matches its pre-gesture state. ` +
+        'Either the container is already at its edge, or it ignores synthesized scrolls — ' +
+        'a raw drag moves such lists: swipe x1 y1 x2 y2 (start inside the list).';
 }
 
-/** A miss on a tree read while a gesture's surface was still changing is not proof of absence. */
-export function formatGestureUnsettledWarning(gesture: PostGestureAction): string {
-  return `The surface was still changing after ${describePostGestureAction(gesture)} when this was read, so an element missing from it may still be on screen. Read again before treating it as absent.`;
+function postGestureOutcome(
+  kind: PostGestureOutcome['kind'],
+  pending: PostGestureAction,
+): PostGestureOutcome {
+  return { kind, gesture: { action: pending.action, positionals: pending.positionals } };
 }
 
 /**
@@ -199,10 +195,7 @@ export async function runPostGestureStabilityLoop<T, S extends readonly unknown[
     },
   });
   if (lastPairAgreed) return { value: previous.value };
-  return {
-    value: previous.value,
-    unsettledGesture: { action: pending.action, positionals: pending.positionals },
-  };
+  return { value: previous.value, postGestureOutcome: postGestureOutcome('unsettled', pending) };
 }
 
 type CapturedSurface<T, S> = {
@@ -266,13 +259,7 @@ function buildAcceptedOutcome<T, S extends readonly unknown[]>(
     baselineSignature !== undefined &&
     hooks.surfacesIdentical(baselineSignature, current.signature)
   ) {
-    return {
-      value: current.value,
-      gestureNoEffect: {
-        action: pending.action,
-        positionals: pending.positionals,
-      },
-    };
+    return { value: current.value, postGestureOutcome: postGestureOutcome('no-effect', pending) };
   }
   emitDiagnostic({
     level: 'info',
diff --git a/packages/kernel/src/snapshot.ts b/packages/kernel/src/snapshot.ts
index ff57222c86..7c0bdfdf89 100644
--- a/packages/kernel/src/snapshot.ts
+++ b/packages/kernel/src/snapshot.ts
@@ -502,13 +502,34 @@ export type SnapshotState = {
    * the foreground instead (#2682). Consumers that surface this tree disclose the repair.
    */
   targetActivation?: IosTargetActivation;
-  /** The gesture whose surface was still changing when stabilization gave up on this capture. */
-  unsettledGesture?: PostGestureAction;
+  /** What post-gesture stabilization proved about the gesture before this capture. */
+  postGestureOutcome?: PostGestureOutcome;
 } & SnapshotStateProvenance;
 
 /** The gesture a post-gesture outcome fact names: the command and its positionals. */
 export type PostGestureAction = { action: string; positionals: string[] };
 
+/**
+ * `unsettled`: the surface was still changing when the stabilization deadline expired.
+ * `no-effect`: the settled surface still matches the pre-gesture tree (#1600).
+ */
+export type PostGestureOutcome = {
+  kind: 'unsettled' | 'no-effect';
+  gesture: PostGestureAction;
+};
+
+/**
+ * A capture taken at once to recover or widen `previous` reads the same moment after the same
+ * gesture, so it carries that capture's outcome.
+ */
+export function inheritPostGestureOutcome<T extends SnapshotState>(
+  previous: SnapshotState,
+  recapture: T,
+): T {
+  recapture.postGestureOutcome ??= previous.postGestureOutcome;
+  return recapture;
+}
+
 export type SnapshotUnchanged = {
   ageMs: number;
   nodeCount: number;
diff --git a/packages/selectors/src/absence-observation.ts b/packages/selectors/src/absence-observation.ts
index 02964761ef..71067fa7e0 100644
--- a/packages/selectors/src/absence-observation.ts
+++ b/packages/selectors/src/absence-observation.ts
@@ -72,7 +72,7 @@ export function absenceCaptureOptionMessage(
 export function classifyAbsenceObservation(
   snapshot: Pick<
     SnapshotState,
-    'backend' | 'nodes' | 'snapshotQuality' | 'truncated' | 'unsettledGesture'
+    'backend' | 'nodes' | 'snapshotQuality' | 'truncated' | 'postGestureOutcome'
   >,
   matches: readonly SnapshotNode[],
 ): AbsenceObservation {
@@ -100,7 +100,10 @@ export function classifyAbsenceObservation(
     };
   }
   if (matchCount === 0) {
-    return { kind: snapshot.unsettledGesture ? 'unsettled' : 'absent', matches: 0 };
+    return {
+      kind: snapshot.postGestureOutcome?.kind === 'unsettled' ? 'unsettled' : 'absent',
+      matches: 0,
+    };
   }
   return { kind: 'present', matches: matchCount, firstMatch: firstMatch! };
 }
diff --git a/src/commands/capture/runtime/snapshot.test.ts b/src/commands/capture/runtime/snapshot.test.ts
index d24f27a490..b5b908b7d9 100644
--- a/src/commands/capture/runtime/snapshot.test.ts
+++ b/src/commands/capture/runtime/snapshot.test.ts
@@ -13,7 +13,8 @@ import {
   type CommandSessionStore,
 } from '../../../runtime.ts';
 import { makeSnapshotState } from '@agent-device/selectors/snapshot-geometry-fixtures';
-import { formatGestureUnsettledWarning } from '@agent-device/capture-kit/post-gesture-stability';
+import type { PostGestureOutcome } from '@agent-device/kernel/snapshot';
+import { formatPostGestureOutcomeWarning } from '@agent-device/capture-kit/post-gesture-stability';
 
 test('runtime snapshot captures nodes and updates the session baseline', async () => {
   let stored: Parameters<CommandSessionStore['set']>[0] | undefined;
@@ -789,17 +790,20 @@ test('runtime snapshot leaves the keyboard band off when the backend measured no
 });
 
 test('runtime snapshot warns when its tree was read on a surface still moving after a gesture', async () => {
-  const gesture = { action: 'scroll', positionals: ['down'] };
+  const outcome: PostGestureOutcome = {
+    kind: 'unsettled',
+    gesture: { action: 'scroll', positionals: ['down'] },
+  };
   const device = createSnapshotOnlyDevice({
     snapshot: {
       ...makeSnapshotState([{ index: 0, depth: 0, type: 'Window', label: 'Home' }], {
         backend: 'xctest',
       }),
-      unsettledGesture: gesture,
+      postGestureOutcome: outcome,
     },
   });
 
   const result = await device.capture.snapshot({ session: 'default' });
 
-  assert.deepEqual(result.warnings, [formatGestureUnsettledWarning(gesture)]);
+  assert.deepEqual(result.warnings, [formatPostGestureOutcomeWarning(outcome)]);
 });
diff --git a/src/commands/capture/runtime/snapshot.ts b/src/commands/capture/runtime/snapshot.ts
index 21f058fe53..c0d9cd9ca7 100644
--- a/src/commands/capture/runtime/snapshot.ts
+++ b/src/commands/capture/runtime/snapshot.ts
@@ -26,7 +26,7 @@ import {
   renderSnapshotQualityWarnings,
   truncatedCaptureWarning,
 } from '@agent-device/capture-kit/quality-warnings';
-import { formatGestureUnsettledWarning } from '@agent-device/capture-kit/post-gesture-stability';
+import { formatPostGestureOutcomeWarning } from '@agent-device/capture-kit/post-gesture-stability';
 import { buildSnapshotVisibility } from '@agent-device/capture-kit/snapshot-visibility';
 import { ANDROID_SYSTEM_SURFACE_DISCLOSURE } from '@agent-device/contracts/android-system-surface-disclosure';
 import { formatReactNativeOverlayWarning } from '../../react-native/overlay.ts';
@@ -261,8 +261,8 @@ function buildSnapshotWarnings(params: {
     );
   }
   warnings.push(...truncatedCaptureWarning(snapshotTruncationForResult(params.snapshot)));
-  if (params.snapshot.unsettledGesture) {
-    warnings.push(formatGestureUnsettledWarning(params.snapshot.unsettledGesture));
+  if (params.snapshot.postGestureOutcome) {
+    warnings.push(formatPostGestureOutcomeWarning(params.snapshot.postGestureOutcome));
   }
   warnings.push(...buildEmptyAndroidInteractiveWarnings(params));
   if (!params.annotations.quality) {
diff --git a/src/commands/interaction/runtime/resolution.ts b/src/commands/interaction/runtime/resolution.ts
index 48696a74b4..c85b5a7420 100644
--- a/src/commands/interaction/runtime/resolution.ts
+++ b/src/commands/interaction/runtime/resolution.ts
@@ -5,7 +5,11 @@ import type {
   SnapshotNode,
   SnapshotState,
 } from '@agent-device/kernel/snapshot';
-import { findNodeByRef, normalizeRef } from '@agent-device/kernel/snapshot';
+import {
+  findNodeByRef,
+  inheritPostGestureOutcome,
+  normalizeRef,
+} from '@agent-device/kernel/snapshot';
 import { resolveRectCenter } from '@agent-device/kernel/rect-center';
 import type {
   AgentDeviceRuntime,
@@ -390,7 +394,9 @@ async function resolveSelectorInteractionTarget(
     params.pipeline,
   );
   if ((!resolved || !resolved.node.rect) && params.requireInteractive) {
+    const interactive = capture.snapshot;
     capture = await captureInteractionSnapshot(runtime, options, false);
+    inheritPostGestureOutcome(interactive, capture.snapshot);
     resolved = resolveActionSelector(
       capture.snapshot.nodes,
       selectorExpression,
diff --git a/src/commands/interaction/runtime/wait-absent.test.ts b/src/commands/interaction/runtime/wait-absent.test.ts
index 2c5bf6f35f..88d69c0f27 100644
--- a/src/commands/interaction/runtime/wait-absent.test.ts
+++ b/src/commands/interaction/runtime/wait-absent.test.ts
@@ -145,7 +145,10 @@ test('wait absent does not take a miss on a surface still moving after a gesture
   const unsettled = {
     snapshot: {
       ...makeSnapshotState([]),
-      unsettledGesture: { action: 'scroll', positionals: ['down'] },
+      postGestureOutcome: {
+        kind: 'unsettled' as const,
+        gesture: { action: 'scroll', positionals: ['down'] },
+      },
     },
   };
   const device = absentDevice([unsettled, snapshot('Removed')]);
diff --git a/src/daemon/__tests__/capture-disclosure-target-activation.test.ts b/src/daemon/__tests__/capture-disclosure-target-activation.test.ts
index b381114465..570d4d916f 100644
--- a/src/daemon/__tests__/capture-disclosure-target-activation.test.ts
+++ b/src/daemon/__tests__/capture-disclosure-target-activation.test.ts
@@ -54,7 +54,7 @@ test('a failure response appends the repair to its hint and keeps the original d
   assert.equal(response.error.message, 'selector missed');
   assert.equal(response.error.code, 'COMMAND_FAILED');
   assert.equal(response.error.details?.blockedBy, 'android_foreground_surface');
-  assert.match(String(response.error.details?.hint), /prior state runningBackground/);
+  assert.match(String(response.error.hint), /prior state runningBackground/);
 });
 
 test('a capture with no repair leaves the response byte-identical', () => {
@@ -64,7 +64,7 @@ test('a capture with no repair leaves the response byte-identical', () => {
 });
 
 /**
- * A failure carries the sentence in `error.details.hint`. That carrier is exactly where a route could
+ * A failure carries the sentence in `error.hint`. That carrier is exactly where a route could
  * cheaply borrow the previous command's repair off the stored snapshot and blame it on this request,
  * so the repair travels only on the request's own proof (#2682).
  */
@@ -77,7 +77,7 @@ test('a failure does not borrow a repair the stored snapshot happens to carry',
   const response = withCaptureDisclosures({
     response: failed,
     consumedTree: { targetActivation: FACT },
-    activationProof: {},
+    captureProof: {},
   });
 
   assert.equal(response, failed);
@@ -95,7 +95,7 @@ test('surface and foreground disclosures ride one response together', () => {
       iosSystemSurfaceBundleId: 'com.apple.SafariViewService',
       targetActivation: FACT,
     },
-    activationProof: { state: { targetActivation: FACT } },
+    captureProof: { targetActivation: FACT },
   });
   const data = dataOf(response);
   assert.match(String(data.warning), /system web sign-in sheet/);
@@ -117,22 +117,22 @@ test('a repair that passes through two wrappers is named once in the failure hin
       details: { hint: 'Use snapshot to see the current tree.' },
     },
   };
-  const proof = { state: { targetActivation: FACT } };
+  const proof = { targetActivation: FACT };
 
   const once = withCaptureDisclosures({
     response: missed,
     consumedTree: { targetActivation: FACT },
-    activationProof: proof,
+    captureProof: proof,
   });
   const twice = withCaptureDisclosures({
     response: once,
     consumedTree: { targetActivation: FACT },
-    activationProof: proof,
+    captureProof: proof,
   });
 
   assert.equal(twice.ok, false);
   if (twice.ok) return;
-  const hint = String(twice.error.details?.hint);
+  const hint = String(twice.error.hint);
   assert.equal(
     hint.split(iosTargetActivationDisclosure(FACT)).length - 1,
     1,
diff --git a/src/daemon/__tests__/capture-disclosure.test.ts b/src/daemon/__tests__/capture-disclosure.test.ts
index a7a52de12f..e848ded858 100644
--- a/src/daemon/__tests__/capture-disclosure.test.ts
+++ b/src/daemon/__tests__/capture-disclosure.test.ts
@@ -148,7 +148,7 @@ test('wait timeout for app text hidden behind a system surface discloses the occ
   expect(response.ok).toBe(false);
   if (response.ok) return;
   expect(response.error.message).toMatch(/wait timed out for text: Bakery list/);
-  expect(String(response.error.details?.hint)).toContain(ANDROID_SYSTEM_SURFACE_DISCLOSURE);
+  expect(String(response.error.hint)).toContain(ANDROID_SYSTEM_SURFACE_DISCLOSURE);
 });
 
 test('sessionless read-only find still discloses the occluding system surface', async () => {
@@ -204,7 +204,7 @@ test('disclosure appends after an existing failure hint instead of replacing it'
   );
   expect(response.ok).toBe(false);
   if (response.ok) return;
-  const hint = String(response.error.details?.hint);
+  const hint = String(response.error.hint);
   expect(hint).toContain('prior hint text');
   expect(hint).toContain(ANDROID_SYSTEM_SURFACE_DISCLOSURE);
   expect(hint.indexOf('prior hint text')).toBeLessThan(
@@ -261,7 +261,7 @@ test('sessionless wait timeout still discloses the occluding system surface', as
   expect(response.ok).toBe(false);
   if (response.ok) return;
   expect(sessionStore.get('default')).toBeUndefined();
-  expect(String(response.error.details?.hint)).toContain(ANDROID_SYSTEM_SURFACE_DISCLOSURE);
+  expect(String(response.error.hint)).toContain(ANDROID_SYSTEM_SURFACE_DISCLOSURE);
 });
 
 // --- #2438: an in-place iOS system surface (web sign-in sheet) discloses on the same shared seam ---
@@ -350,7 +350,7 @@ test('mutating find that misses on an in-place system surface still discloses it
 
   expect(response?.ok).toBe(false);
   if (response?.ok) return;
-  expect(String(response?.error.details?.hint)).toContain(WEB_SIGN_IN_DISCLOSURE);
+  expect(String(response?.error.hint)).toContain(WEB_SIGN_IN_DISCLOSURE);
 });
 
 test('the shared disclosure helper reports an iOS system surface on both outcomes', () => {
@@ -368,13 +368,13 @@ test('the shared disclosure helper reports an iOS system surface on both outcome
   );
   expect(failed.ok).toBe(false);
   if (failed.ok) return;
-  expect(String(failed.error.details?.hint)).toContain(WEB_SIGN_IN_DISCLOSURE);
+  expect(String(failed.error.hint)).toContain(WEB_SIGN_IN_DISCLOSURE);
 });
 
 /**
  * A timed-out `wait text` polled the device and the runner had to re-activate the session app to
  * answer those polls (#2682). The disclosure arrives on the failure the same way the occlusion one
- * does: in `error.details.hint`.
+ * does: in `error.hint`.
  */
 test('wait timeout whose polls required a foreground repair discloses the repair', async () => {
   const sessionStore = makeSessionStore();
@@ -412,7 +412,7 @@ test('wait timeout whose polls required a foreground repair discloses the repair
 
   expect(response.ok).toBe(false);
   if (response.ok) return;
-  expect(String(response.error.details?.hint)).toContain(
+  expect(String(response.error.hint)).toContain(
     iosTargetActivationDisclosure(TARGET_ACTIVATION_FACT),
   );
 });
diff --git a/src/daemon/__tests__/deferred-interaction-outcome.test.ts b/src/daemon/__tests__/deferred-interaction-outcome.test.ts
index 1dbc8374c7..e112fe4a62 100644
--- a/src/daemon/__tests__/deferred-interaction-outcome.test.ts
+++ b/src/daemon/__tests__/deferred-interaction-outcome.test.ts
@@ -280,7 +280,7 @@ test('a pending stabilization resolves through the quiet-window loop and clears
   assert.equal(result?.warnings, undefined);
 });
 
-test('a proven no-effect gesture surfaces its warning on the resolved capture (iOS accept-stale)', async () => {
+test('a proven no-effect gesture is stamped on the resolved capture tree (iOS accept-stale)', async () => {
   vi.useFakeTimers();
   const session = makeSession('ios');
   session.snapshot = pickupSnapshot();
@@ -299,8 +299,10 @@ test('a proven no-effect gesture surfaces its warning on the resolved capture (i
   }
   const result = await pendingResult;
 
-  assert.equal(result?.warnings?.length, 1);
-  assert.match(result?.warnings?.[0] ?? '', /produced no visible change/);
+  assert.deepEqual(result?.snapshot.postGestureOutcome, {
+    kind: 'no-effect',
+    gesture: { action: 'scroll', positionals: ['down'] },
+  });
   assert.equal(isPostGestureStabilizationPending(session), false);
 });
 
diff --git a/src/daemon/__tests__/is-runtime.test.ts b/src/daemon/__tests__/is-runtime.test.ts
index 722948d9ab..32c84ba5b3 100644
--- a/src/daemon/__tests__/is-runtime.test.ts
+++ b/src/daemon/__tests__/is-runtime.test.ts
@@ -10,10 +10,11 @@ import {
 import { makeSessionStore } from '../../__tests__/test-utils/store-factory.ts';
 import { withTestDeviceInventory } from '../../__tests__/test-utils/device-inventory-gateways.ts';
 import { makeSnapshotState } from '@agent-device/selectors/snapshot-geometry-fixtures';
+import type { PostGestureOutcome } from '@agent-device/kernel/snapshot';
 import type { DaemonRequest } from '../daemon-request.ts';
 import { selectorCaptureFixture } from './selector-capture-fixture.ts';
 import { markDeferredInteractionOutcome } from '../deferred-interaction-outcome.ts';
-import { formatGestureUnsettledWarning } from '@agent-device/capture-kit/post-gesture-stability';
+import { formatPostGestureOutcomeWarning } from '@agent-device/capture-kit/post-gesture-stability';
 
 const { mockRunAppleRunnerCommand } = vi.hoisted(() => ({ mockRunAppleRunnerCommand: vi.fn() }));
 
@@ -455,16 +456,59 @@ test('a miss on a surface that never settled carries the unsettled fact, and the
   const pending = isVisible();
   // Just past the 1.5s stabilization deadline, so the re-read lands inside the cache window.
   await vi.advanceTimersByTimeAsync(1_700);
-  const gesture = { action: 'scroll', positionals: [] };
+  const outcome: PostGestureOutcome = {
+    kind: 'unsettled',
+    gesture: { action: 'scroll', positionals: [] },
+  };
 
   const response = await pending;
-  expect(response?.ok === false && response.error.details).toMatchObject({
-    reason: 'selector_not_found',
-    unsettledGesture: gesture,
-    hint: expect.stringContaining(formatGestureUnsettledWarning(gesture)),
+  expect(response?.ok === false && response.error).toMatchObject({
+    hint: expect.stringContaining(formatPostGestureOutcomeWarning(outcome)),
+    details: { reason: 'selector_not_found', postGestureOutcome: outcome },
   });
   const captures = fixture.captures.length;
   const reread = await isVisible();
   expect(fixture.captures.length).toBe(captures + 1);
-  expect(reread?.ok === false && reread.error.details?.unsettledGesture).toBeUndefined();
+  expect(reread?.ok === false && reread.error.details?.postGestureOutcome).toBeUndefined();
+});
+
+test('a read after a scroll that moved nothing carries the no-effect outcome, and the re-read reuses its settled tree', async () => {
+  vi.useFakeTimers();
+  const row = {
+    index: 0,
+    type: 'Cell',
+    identifier: 'row',
+    rect: { x: 0, y: 200, width: 390, height: 60 },
+  };
+  const fixture = selectorCaptureFixture({
+    snapshot: () => ({ nodes: [row], backend: 'xctest', producer: 'apple-runner' }),
+  });
+  const sessionStore = makeSessionStore();
+  const session = makeIosAppSession('is-no-effect', { snapshot: makeSnapshotState([row]) });
+  markDeferredInteractionOutcome({ session, command: 'scroll', positionals: ['down'], flags: {} });
+  sessionStore.set('is-no-effect', session);
+  const isVisible = () =>
+    dispatchIsViaRuntime({
+      req: isRequest('is-no-effect', ['visible', 'id=row']),
+      sessionName: 'is-no-effect',
+      sessionStore,
+      inspectFacts: fixture.inspectFacts,
+      bindDevice: fixture.bindDevice,
+    });
+  const pending = isVisible();
+  // A tree that still matches its pre-gesture baseline is distrusted up to the 3.5s cap.
+  await vi.advanceTimersByTimeAsync(3_700);
+  const outcome: PostGestureOutcome = {
+    kind: 'no-effect',
+    gesture: { action: 'scroll', positionals: ['down'] },
+  };
+
+  const response = await pending;
+  expect(response?.ok && response.data).toMatchObject({
+    postGestureOutcome: outcome,
+    warnings: [formatPostGestureOutcomeWarning(outcome)],
+  });
+  const captures = fixture.captures.length;
+  await isVisible();
+  expect(fixture.captures.length).toBe(captures);
 });
diff --git a/src/daemon/__tests__/post-gesture-no-effect-claim.test.ts b/src/daemon/__tests__/post-gesture-no-effect-claim.test.ts
index bfe0ddca12..d07512cd9e 100644
--- a/src/daemon/__tests__/post-gesture-no-effect-claim.test.ts
+++ b/src/daemon/__tests__/post-gesture-no-effect-claim.test.ts
@@ -17,7 +17,8 @@ import {
   capturePostGestureStabilizedResult,
   markDeferredInteractionOutcome,
 } from '../deferred-interaction-outcome.ts';
-import { formatGestureNoEffectWarning } from '@agent-device/capture-kit/post-gesture-stability';
+import { formatPostGestureOutcomeWarning } from '@agent-device/capture-kit/post-gesture-stability';
+import type { PostGestureAction } from '@agent-device/kernel/snapshot';
 import type { SessionState } from '../session-state.ts';
 import {
   chromeWithListSnapshot,
@@ -25,7 +26,10 @@ import {
   pickupSnapshot,
 } from './post-gesture-stabilization-fixtures.ts';
 
-// When the agent-facing gestureNoEffect claim may and may not surface — split
+const noEffectWarning = (gesture: PostGestureAction) =>
+  formatPostGestureOutcomeWarning({ kind: 'no-effect', gesture });
+
+// When the agent-facing no-effect claim may and may not surface — split
 // by subject from post-gesture-stabilization.test.ts (the capture loop), per
 // #1563. Loop mechanics (rebase, distrust budget, timeouts) stay in the
 // loop file; everything here is about the claim and its veto instrumentation.
@@ -129,7 +133,7 @@ test('a backend flip mid-poll withholds the no-effect claim, and records the rea
 
   assert.equal(rebased, 1);
   assert.equal(staleAccepts, 1, 'the loop still accepts the stale read after the distrust budget');
-  assert.equal(result.gestureNoEffect, undefined);
+  assert.equal(result.postGestureOutcome, undefined);
   assert.equal(vetoed, 1, 'the withheld claim must be observable');
   // The reason is the point: a rebase means the corroboration pair is
   // cross-backend, which is a categorically different answer from "the
@@ -165,7 +169,7 @@ test('a successful scroll that flips the capture backend must not claim no-effec
 
   assert.equal(rebased, 1);
   assert.equal(
-    result.gestureNoEffect,
+    result.postGestureOutcome,
     undefined,
     'the scroll swapped every list cell — a no-effect claim here is a false positive',
   );
@@ -204,7 +208,7 @@ test('no pre-gesture snapshot means no baseline, no rebase, and no no-effect cla
   assert.equal(rebased, 0);
   assert.equal(vetoed, 0);
   assert.equal(
-    result.gestureNoEffect,
+    result.postGestureOutcome,
     undefined,
     'a no-effect claim needs a real pre-gesture baseline, never one the loop invented for itself',
   );
@@ -234,7 +238,7 @@ test('scope drift accepts stale but is vetoed from claiming no-effect, observabl
   );
 
   assert.equal(staleAccepts, 1);
-  assert.equal(result.gestureNoEffect, undefined);
+  assert.equal(result.postGestureOutcome, undefined);
   assert.equal(vetoed, 1);
   // Scope drift reads as one-sided membership, never as movement: both cells
   // are missing from the narrowed capture, the shared chrome button has not
@@ -292,7 +296,7 @@ test('same-backend membership drift vetoes the claim and records the divergence
 
   assert.equal(rebased, 0, 'same backend throughout: this is drift, not a flip');
   assert.equal(staleAccepts, 1);
-  assert.equal(result.gestureNoEffect, undefined);
+  assert.equal(result.postGestureOutcome, undefined);
   assert.equal(vetoed, 1);
   // The counts are what distinguish this from the scope-drift case above:
   // one extra key on the CURRENT side, everything shared unmoved. Same veto,
@@ -359,22 +363,31 @@ test('summarizeDiscriminatingSurfaceDivergence counts one-sided keys and moved r
   });
 });
 
-test('formatGestureNoEffectWarning names the gesture and the raw-drag escape hatch', () => {
+test('the no-effect warning names the gesture and the raw-drag escape hatch', () => {
   // Positionals echo verbatim: the warning names the gesture the agent issued,
   // and `scroll down 1` is what they issued.
-  const scrollWarning = formatGestureNoEffectWarning('scroll', ['down', '1']);
+  const scrollWarning = noEffectWarning({
+    action: 'scroll',
+    positionals: ['down', '1'],
+  });
   assert.match(scrollWarning, /scroll down 1 produced no visible change/);
   assert.match(scrollWarning, /swipe x1 y1 x2 y2/);
   assert.match(scrollWarning, /already at its edge/);
 
-  const gestureWarning = formatGestureNoEffectWarning('gesture', ['swipe', 'left']);
+  const gestureWarning = noEffectWarning({
+    action: 'gesture',
+    positionals: ['swipe', 'left'],
+  });
   assert.match(gestureWarning, /gesture swipe left produced no visible change/);
 
-  const bareWarning = formatGestureNoEffectWarning('swipe', []);
+  const bareWarning = noEffectWarning({ action: 'swipe', positionals: [] });
   assert.match(bareWarning, /swipe produced no visible change/);
 
   // The regression the deleted heuristic caused: every positional of a swipe is
   // a coordinate, so "drop anything numeric-looking" left a contentless "swipe".
-  const swipeWarning = formatGestureNoEffectWarning('swipe', ['10', '20', '30', '40']);
+  const swipeWarning = noEffectWarning({
+    action: 'swipe',
+    positionals: ['10', '20', '30', '40'],
+  });
   assert.match(swipeWarning, /^swipe 10 20 30 40 produced no visible change/);
 });
diff --git a/src/daemon/__tests__/post-gesture-stabilization.test.ts b/src/daemon/__tests__/post-gesture-stabilization.test.ts
index d8c99751f8..48ee133df3 100644
--- a/src/daemon/__tests__/post-gesture-stabilization.test.ts
+++ b/src/daemon/__tests__/post-gesture-stabilization.test.ts
@@ -176,7 +176,8 @@ test('capturePostGestureStabilizedResult keeps polling past the normal deadline
   assert.equal(session.postGestureStabilization, undefined);
   // #1600: a stale-accept is the daemon PROVING the gesture moved nothing —
   // that verdict must reach the caller, not only the diagnostics stream.
-  assert.equal(result.gestureNoEffect?.action, 'scroll');
+  assert.equal(result.postGestureOutcome?.kind, 'no-effect');
+  assert.equal(result.postGestureOutcome?.gesture.action, 'scroll');
   // Proves it kept polling well past the OLD 1.5s accept point (2 attempts,
   // ~200ms) instead of trusting the first quiet match.
   assert.ok(captureCount > 8, `expected sustained polling, saw ${captureCount} captures`);
@@ -217,7 +218,7 @@ test('a replaced list under fixed chrome now settles outright, and still claims
   const { result, staleAccepts } = await resultPromise;
 
   assert.equal(staleAccepts, 0);
-  assert.equal(result.gestureNoEffect, undefined);
+  assert.equal(result.postGestureOutcome, undefined);
 });
 
 test('capturePostGestureStabilizedResult trusts a quiet signature once content genuinely differs from the baseline (iOS)', async () => {
@@ -247,7 +248,7 @@ test('capturePostGestureStabilizedResult trusts a quiet signature once content g
   assert.equal(settled, 1);
   assert.equal(staleAccepts, 0);
   // A genuine settle carries no no-effect claim.
-  assert.equal(result.gestureNoEffect, undefined);
+  assert.equal(result.postGestureOutcome, undefined);
   // Accepted at the first quiet match (initial capture + one poll = 2
   // attempts): no distrust cost for a genuine settle.
   assert.equal(capture.mock.calls.length, 2);
@@ -364,7 +365,7 @@ test('a deadline that expires right after a rebased quiet pair is not reported a
   const { result, rebased, timeouts } = await resultPromise;
 
   assert.deepEqual([rebased, timeouts], [1, 1]);
-  assert.equal(result.unsettledGesture, undefined);
+  assert.equal(result.postGestureOutcome, undefined);
 });
 
 test('capturePostGestureStabilizedResult catches a frozen target even when the baseline came from a broader-scope capture than the post-gesture reads (iOS, live regression)', async () => {
diff --git a/src/daemon/__tests__/selector-capture-runtime.test.ts b/src/daemon/__tests__/selector-capture-runtime.test.ts
index 64cf3655e8..9384dc7553 100644
--- a/src/daemon/__tests__/selector-capture-runtime.test.ts
+++ b/src/daemon/__tests__/selector-capture-runtime.test.ts
@@ -9,7 +9,7 @@ import {
   type SnapshotState,
 } from '@agent-device/kernel/snapshot';
 import type { DaemonResponse } from '../daemon-request.ts';
-import { type RequestActivationProof, withCaptureDisclosures } from '../capture-disclosure.ts';
+import { type RequestCaptureProof, withCaptureDisclosures } from '../capture-disclosure.ts';
 import { makeIosSession } from '../../__tests__/test-utils/session-factories.ts';
 import { makeSessionStore } from '../../__tests__/test-utils/store-factory.ts';
 import { createSelectorCaptureRuntime } from '../selector-capture-runtime.ts';
@@ -223,14 +223,14 @@ function proofRuntime(params: {
       : {}),
   } as never);
   const consumedSnapshot: { state?: SnapshotState } = {};
-  const activationProof: RequestActivationProof = {};
+  const captureProof: RequestCaptureProof = {};
   const runtime = createSelectorCaptureRuntime({
     device: session.device,
     session,
     sessionStore,
     sessionName: params.sessionName,
     consumedSnapshot,
-    activationProof,
+    captureProof,
     capture: boundCapture,
     req: {
       token: 't',
@@ -240,7 +240,7 @@ function proofRuntime(params: {
       flags: {},
     },
   });
-  return { runtime, consumedSnapshot, activationProof };
+  return { runtime, consumedSnapshot, captureProof };
 }
 
 /**
@@ -264,12 +264,12 @@ test('a session-snapshot cache hit consumes a repaired tree without earning the
 
   expect(boundCapture).not.toHaveBeenCalled();
   expect(holders.consumedSnapshot.state?.targetActivation).toEqual(REPAIR);
-  expect(holders.activationProof.state).toBeUndefined();
+  expect(holders.captureProof.targetActivation).toBeUndefined();
 
   const response = withCaptureDisclosures({
     response: { ok: true, data: { nodes: [] } } as DaemonResponse,
     consumedTree: holders.consumedSnapshot.state,
-    activationProof: holders.activationProof,
+    captureProof: holders.captureProof,
   });
   expect(response.ok).toBe(true);
   if (response.ok) {
@@ -287,7 +287,7 @@ test('a capture the request took itself earns the repair proof', async () => {
   await holders.runtime.capture({ flags: {}, cache: { useSessionSnapshot: true } });
 
   expect(boundCapture).toHaveBeenCalledTimes(1);
-  expect(holders.activationProof.state?.targetActivation).toEqual(REPAIR);
+  expect(holders.captureProof.targetActivation).toEqual(REPAIR);
 });
 
 /**
@@ -310,7 +310,7 @@ test('a later fact-less capture does not erase an earlier repair proof', async (
   await holders.runtime.capture({ flags: {}, cache: { forceFresh: true } });
 
   expect(boundCapture).toHaveBeenCalledTimes(2);
-  expect(holders.activationProof.state?.targetActivation).toEqual(REPAIR);
+  expect(holders.captureProof.targetActivation).toEqual(REPAIR);
 });
 
 function makeCaptureRuntime(sessionName: string) {
diff --git a/src/daemon/__tests__/snapshot-runtime-target-activation.test.ts b/src/daemon/__tests__/snapshot-runtime-disclosure.test.ts
similarity index 71%
rename from src/daemon/__tests__/snapshot-runtime-target-activation.test.ts
rename to src/daemon/__tests__/snapshot-runtime-disclosure.test.ts
index ee199d77ed..75e59093d1 100644
--- a/src/daemon/__tests__/snapshot-runtime-target-activation.test.ts
+++ b/src/daemon/__tests__/snapshot-runtime-disclosure.test.ts
@@ -1,7 +1,10 @@
 import path from 'node:path';
-import { beforeEach, expect, test, vi } from 'vitest';
+import { afterEach, beforeEach, expect, test, vi } from 'vitest';
 import { iosTargetActivationDisclosure } from '@agent-device/contracts/ios-target-activation';
-import type { IosTargetActivation } from '@agent-device/kernel/snapshot';
+import type { IosTargetActivation, PostGestureOutcome } from '@agent-device/kernel/snapshot';
+import { formatPostGestureOutcomeWarning } from '@agent-device/capture-kit/post-gesture-stability';
+import { makeSnapshotState } from '@agent-device/selectors/snapshot-geometry-fixtures';
+import { markDeferredInteractionOutcome } from '../deferred-interaction-outcome.ts';
 import { makeIosSession } from '../../__tests__/test-utils/session-factories.ts';
 import { mkdtempForTestSync } from '../../__tests__/test-utils/tmp-dir.ts';
 import { SessionStore } from '../session-store.ts';
@@ -24,6 +27,10 @@ beforeEach(() => {
   legacyDispatchCapture.mockReset();
 });
 
+afterEach(() => {
+  vi.useRealTimers();
+});
+
 test('a snapshot that captured a repaired tree discloses the repair it paid for', async () => {
   const input = scenario({});
   legacyDispatchCapture.mockResolvedValue({
@@ -95,13 +102,50 @@ test('a snapshot refused before it captured reports no repair and no surface it
 
   expect(response.ok).toBe(false);
   if (response.ok) return;
-  const hint = String(response.error.details?.hint ?? '');
+  const hint = String(response.error.hint ?? '');
   expect(hint.includes(iosTargetActivationDisclosure(REPAIR))).toBe(false);
   expect(hint.includes('was not foreground')).toBe(false);
   expect(hint.includes('system web sign-in sheet')).toBe(false);
   expect(JSON.stringify(response.error.details ?? {})).not.toContain('targetActivation');
 });
 
+/** A scroll that moved nothing reaches the agent on the snapshot that proved it (#1600). */
+test('a snapshot after a scroll that moved nothing warns and stamps the no-effect outcome', async () => {
+  const input = scenario({});
+  const button = {
+    index: 0,
+    depth: 0,
+    type: 'Button',
+    label: 'Continue',
+    rect: { x: 0, y: 0, width: 100, height: 44 },
+    hittable: true,
+  };
+  const session = input.sessionStore.get(input.sessionName)!;
+  session.snapshot = makeSnapshotState([button], { backend: 'xctest' });
+  markDeferredInteractionOutcome({ session, command: 'scroll', positionals: ['up'], flags: {} });
+  legacyDispatchCapture.mockResolvedValue({ backend: 'xctest', truncated: false, nodes: [button] });
+  const outcome: PostGestureOutcome = {
+    kind: 'no-effect',
+    gesture: { action: 'scroll', positionals: ['up'] },
+  };
+
+  const realSetTimeout = globalThis.setTimeout;
+  vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'Date'] });
+  let done = false;
+  const pending = dispatchSnapshot(input).finally(() => (done = true));
+  // The route awaits real I/O between polls, so the faked clock advances while the test yields.
+  while (!done) {
+    await vi.advanceTimersByTimeAsync(100);
+    await new Promise((resolve) => realSetTimeout(resolve, 1));
+  }
+  const response = await pending;
+
+  expect(response.ok && response.data?.warnings).toContain(
+    formatPostGestureOutcomeWarning(outcome),
+  );
+  expect(input.sessionStore.get(input.sessionName)?.snapshot?.postGestureOutcome).toEqual(outcome);
+});
+
 function scenario(params: { storedRepair?: boolean }) {
   const root = mkdtempForTestSync('agent-device-snapshot-target-activation');
   const sessionName = 'default';
diff --git a/src/daemon/capture-disclosure.ts b/src/daemon/capture-disclosure.ts
index 1e594f1613..5a6ac46f6d 100644
--- a/src/daemon/capture-disclosure.ts
+++ b/src/daemon/capture-disclosure.ts
@@ -2,18 +2,19 @@ import type { SnapshotState } from '@agent-device/kernel/snapshot';
 import { systemSurfaceDisclosure } from '@agent-device/contracts/android-system-surface-disclosure';
 import { iosSystemSurfaceDisclosure } from '@agent-device/contracts/ios-system-surface';
 import { iosTargetActivationDisclosure } from '@agent-device/contracts/ios-target-activation';
-import { formatGestureUnsettledWarning } from '@agent-device/capture-kit/post-gesture-stability';
+import { formatPostGestureOutcomeWarning } from '@agent-device/capture-kit/post-gesture-stability';
 import type { DaemonResponse } from './daemon-request.ts';
 
-/** The capture provenance a response must be disclosed against (#2438, #2682, unsettled gestures). */
+/** The capture provenance a response must be disclosed against (#2438, #2682, gesture outcomes). */
 export type CaptureProvenance = Pick<
   SnapshotState,
-  'systemSurfaceOnly' | 'iosSystemSurfaceBundleId' | 'targetActivation' | 'unsettledGesture'
+  'systemSurfaceOnly' | 'iosSystemSurfaceBundleId' | 'targetActivation' | 'postGestureOutcome'
 >;
 
 /**
- * The foreground repair THIS request paid for, filled by the capture path only when the request
- * actually captured a tree (#2682).
+ * The whole-tree facts THIS request's own captures observed, filled by the capture path only when the
+ * request actually captured a tree: the foreground repair it paid for (#2682) and the outcome of the
+ * gesture it read after.
  *
  * Separate from the consumed tree on purpose. A selector read may answer from a cached or stored
  * tree — that tree still describes the surface the response is about, which is what #2438 discloses
@@ -21,23 +22,23 @@ export type CaptureProvenance = Pick<
  * consumed tree would tell a command "you found the session app out of foreground" when it never
  * looked, which is a fabricated observation rather than a disclosure.
  */
-export type RequestActivationProof = {
-  state?: CaptureProvenance;
-};
+export type RequestCaptureProof = Pick<
+  CaptureProvenance,
+  'targetActivation' | 'postGestureOutcome'
+>;
 
 /**
- * Note the repair a capture paid for, and hand that capture back. First fact wins: a later capture in
- * the same request that reports no repair — a sparse recovery's fresh tree, a poll's fact-less read —
- * cannot erase the capture that did (#2682). One rule, because three capture paths owe it and a
- * hand-copied condition drifts from the other two the moment one of them learns something.
+ * Note the facts a capture observed, and hand that capture back. First fact wins: a later capture in
+ * the same request that reports none — a sparse recovery's fresh tree, a poll's fact-less read, a
+ * post-action observation — cannot erase the capture that did (#2682).
  */
-export function recordActivationProof<T extends CaptureProvenance>(
-  proof: RequestActivationProof | undefined,
+export function recordCaptureProof<T extends CaptureProvenance>(
+  proof: RequestCaptureProof | undefined,
   snapshot: T,
 ): T {
-  if (proof !== undefined && proof.state === undefined && snapshot.targetActivation !== undefined) {
-    proof.state = snapshot;
-  }
+  if (proof === undefined) return snapshot;
+  proof.targetActivation ??= snapshot.targetActivation;
+  proof.postGestureOutcome ??= snapshot.postGestureOutcome;
   return snapshot;
 }
 
@@ -59,15 +60,15 @@ export function withSystemSurfaceDisclosure(
 }
 
 /**
- * Disclose a fact about the whole answered tree (#2682 foreground repair, an unsettled gesture). Its
- * sentence is APPENDED, never replacing an earlier warning, and the typed fact lands on either
- * outcome (`data` or `error.details`) even when the sentence was already carried.
+ * Disclose a fact about the whole answered tree. Its sentence is APPENDED, never replacing an earlier
+ * warning, and the typed fact lands on either outcome (`data` or `error.details`) even when the
+ * sentence was already carried.
  */
-function withTreeFactDisclosure<K extends 'targetActivation' | 'unsettledGesture'>(
+function withTreeFactDisclosure<K extends keyof RequestCaptureProof>(
   response: DaemonResponse,
   key: K,
-  fact: CaptureProvenance[K],
-  sentence: (fact: NonNullable<CaptureProvenance[K]>) => string,
+  fact: RequestCaptureProof[K],
+  sentence: (fact: NonNullable<RequestCaptureProof[K]>) => string,
 ): DaemonResponse {
   if (!fact) return response;
   const disclosed = appendDisclosure(response, sentence(fact), 'warnings');
@@ -93,31 +94,32 @@ export function withTargetActivationDisclosure(
 
 /**
  * Every capture-provenance disclosure a response owes, from the two different things a capture can
- * prove: what the answered tree describes (#2438 — cache tiers included, because the surface is
- * still on screen) and what this request's own capture found (#2682 — cache hits excluded, because
- * a request that captured nothing repaired nothing).
+ * prove: what the answered tree describes (#2438 and the post-gesture outcome — cache tiers
+ * included, because the tree still describes the surface) and what this request's own capture found
+ * (#2682 — cache hits excluded, because a request that captured nothing repaired nothing). A route
+ * that aims at the trees its own captures read passes its proof as the consumed tree.
  */
 export function withCaptureDisclosures(params: {
   response: DaemonResponse;
   consumedTree: CaptureProvenance | undefined;
-  activationProof?: RequestActivationProof;
+  captureProof?: RequestCaptureProof;
 }): DaemonResponse {
-  const { response, consumedTree, activationProof } = params;
+  const { response, consumedTree, captureProof } = params;
   return withTargetActivationDisclosure(
     withTreeFactDisclosure(
       withSystemSurfaceDisclosure(response, consumedTree),
-      'unsettledGesture',
-      consumedTree?.unsettledGesture,
-      formatGestureUnsettledWarning,
+      'postGestureOutcome',
+      consumedTree?.postGestureOutcome,
+      formatPostGestureOutcomeWarning,
     ),
-    activationProof?.state,
+    captureProof,
   );
 }
 
 /**
  * Which success-side field a disclosure enters. #2438's surface sentence shipped on the singular
  * `warning`; the repair sentence ships on the `warnings` array beside the typed fact that travels
- * with it. Failure has one carrier for both: `error.details.hint`.
+ * with it. Failure has one carrier for both: `error.hint`, the hint request finalization keeps.
  */
 type DisclosureCarrier = 'warning' | 'warnings';
 
@@ -135,14 +137,9 @@ function appendDisclosure(
 ): DaemonResponse {
   if (carriesDisclosure(response, disclosure)) return response;
   if (!response.ok) {
-    const details = response.error.details ?? {};
-    return {
-      ...response,
-      error: {
-        ...response.error,
-        details: { ...details, hint: appended(details.hint, disclosure) },
-      },
-    };
+    // A route that built its failure from details carries its hint there until finalization.
+    const hint = response.error.hint ?? response.error.details?.hint;
+    return { ...response, error: { ...response.error, hint: appended(hint, disclosure) } };
   }
   if (carrier === 'warnings') {
     return {
@@ -166,7 +163,7 @@ function appendDisclosure(
 function carriesDisclosure(response: DaemonResponse, disclosure: string): boolean {
   const carriers: unknown[] = response.ok
     ? [response.data?.warning, ...responseWarnings(response.data?.warnings)]
-    : [response.error.details?.hint];
+    : [response.error.hint];
   return carriers.some((carrier) => typeof carrier === 'string' && carrier.includes(disclosure));
 }
 
diff --git a/src/daemon/deferred-interaction-outcome.ts b/src/daemon/deferred-interaction-outcome.ts
index 23208ad04a..c772b48db5 100644
--- a/src/daemon/deferred-interaction-outcome.ts
+++ b/src/daemon/deferred-interaction-outcome.ts
@@ -13,7 +13,6 @@ import {
   isNavigationSensitiveAction,
   type SnapshotFreshnessMode,
 } from '@agent-device/capture-kit/snapshot-freshness';
-import { withGestureNoEffectWarning } from './gesture-no-effect.ts';
 import {
   areInteractionSurfaceSignaturesStable,
   buildInteractionSurfaceSignature,
@@ -354,13 +353,13 @@ export async function capturePostGestureStabilizedResult<T>(params: {
   return outcome;
 }
 
-/** The stabilized attempt as a capture result: the tree carries an unsettled outcome as its own fact. */
+/** The stabilized attempt as a capture result: the tree carries the gesture's outcome as its own fact. */
 function resolvedPostGestureCapture(
   stabilized: PostGestureStabilityOutcome<DeferredOutcomeSnapshotAttempt>,
 ): DeferredOutcomeCaptureResult {
   const { snapshot, annotations } = stabilized.value;
-  if (stabilized.unsettledGesture) snapshot.unsettledGesture = stabilized.unsettledGesture;
-  return { snapshot, ...withGestureNoEffectWarning(annotations, stabilized.gestureNoEffect) };
+  if (stabilized.postGestureOutcome) snapshot.postGestureOutcome = stabilized.postGestureOutcome;
+  return { snapshot, ...annotations };
 }
 
 function isPostGestureStabilizingAction(
diff --git a/src/daemon/gesture-no-effect.ts b/src/daemon/gesture-no-effect.ts
deleted file mode 100644
index 38ce4d9cb3..0000000000
--- a/src/daemon/gesture-no-effect.ts
+++ /dev/null
@@ -1,22 +0,0 @@
-import type { SnapshotCaptureAnnotations } from '@agent-device/contracts/capture';
-import { formatGestureNoEffectWarning } from '@agent-device/capture-kit/post-gesture-stability';
-
-/**
- * #1600: a proven no-effect gesture must reach the agent inside the very
- * response it reads next, not only the diagnostics stream. Warnings ride the
- * existing annotations channel so every renderer that already prints capture
- * warnings picks this up with no new plumbing.
- */
-export function withGestureNoEffectWarning(
-  annotations: SnapshotCaptureAnnotations,
-  gestureNoEffect: { action: string; positionals: string[] } | undefined,
-): SnapshotCaptureAnnotations {
-  if (!gestureNoEffect) return annotations;
-  return {
-    ...annotations,
-    warnings: [
-      ...(annotations.warnings ?? []),
-      formatGestureNoEffectWarning(gestureNoEffect.action, gestureNoEffect.positionals),
-    ],
-  };
-}
diff --git a/src/daemon/interaction/internal/__tests__/find-target-activation-disclosure.test.ts b/src/daemon/interaction/internal/__tests__/find-target-activation-disclosure.test.ts
index fdce22ef13..c795e37258 100644
--- a/src/daemon/interaction/internal/__tests__/find-target-activation-disclosure.test.ts
+++ b/src/daemon/interaction/internal/__tests__/find-target-activation-disclosure.test.ts
@@ -1,5 +1,5 @@
 import { beforeEach, expect, test, vi } from 'vitest';
-import type { IosTargetActivation } from '@agent-device/kernel/snapshot';
+import type { IosTargetActivation, PostGestureOutcome } from '@agent-device/kernel/snapshot';
 import { iosTargetActivationDisclosure } from '@agent-device/contracts/ios-target-activation';
 import { makeSessionStore } from '../../../../__tests__/test-utils/store-factory.ts';
 import { makeIosSession } from '../../../../__tests__/test-utils/session-factories.ts';
@@ -8,7 +8,7 @@ import { legacyDispatchCapture } from '../../../__tests__/legacy-snapshot-captur
 import { getRuntimeBindings } from '../../../__tests__/interaction-get-runtime-fixture.ts';
 import { handleFindCommands } from '../../index.ts';
 import { markDeferredInteractionOutcome } from '../../../deferred-interaction-outcome.ts';
-import { formatGestureUnsettledWarning } from '@agent-device/capture-kit/post-gesture-stability';
+import { formatPostGestureOutcomeWarning } from '@agent-device/capture-kit/post-gesture-stability';
 
 vi.mock('../../../snapshot-interactor-capture.ts', async () => {
   const fixture = await import('../../../__tests__/legacy-snapshot-capture-fixture.ts');
@@ -73,7 +73,9 @@ beforeEach(() => {
   legacyDispatchCapture.mockReset();
 });
 
-async function findClick(captures: Record<string, unknown>[], afterScroll = false) {
+type CaptureScript = (call: number, context?: Record<string, unknown>) => Record<string, unknown>;
+
+async function findClick(captures: Record<string, unknown>[] | CaptureScript, afterScroll = false) {
   const sessionStore = makeSessionStore();
   const session = makeIosSession('default', { appBundleId: 'com.example.app' });
   if (afterScroll)
@@ -81,7 +83,10 @@ async function findClick(captures: Record<string, unknown>[], afterScroll = fals
   sessionStore.set('default', session);
   let call = 0;
   legacyDispatchCapture.mockImplementation(
-    async () => captures[Math.min(call++, captures.length - 1)],
+    async (_device, _command, _positionals, _out, context) =>
+      typeof captures === 'function'
+        ? captures(call++, context)
+        : captures[Math.min(call++, captures.length - 1)],
   );
 
   const response = await handleFindCommands({
@@ -125,23 +130,33 @@ test('a find that stayed sparse reports the repair on the failure it returns', a
 
   expect(response?.ok).toBe(false);
   if (!response || response.ok) return;
-  const hint = String(response.error.details?.hint ?? '');
-  expect(hint).toContain(iosTargetActivationDisclosure(FACT));
+  expect(response.error.hint).toContain(iosTargetActivationDisclosure(FACT));
 });
 
-/** The tree a mutating find resolves against carries every provenance fact, not a hand-picked few. */
-test('a find that misses on a surface still moving after a scroll reports the unsettled fact', async () => {
-  const moving = Array.from({ length: 40 }, (_, call) => ({
-    ...RECOVERED_TREE,
+/**
+ * A sparse capture on a surface still moving after a scroll is replaced by find's query-scoped
+ * recovery right away. The recovery reads the same moment, so its miss is not proof of absence either.
+ */
+test('a find that misses after recovering a sparse capture of a moving surface reports the unsettled outcome', async () => {
+  const movingSparse = (call: number) => ({
+    ...SPARSE_VERDICT,
+    targetActivation: undefined,
     nodes: [
-      RECOVERED_TREE.nodes[0],
+      SPARSE_VERDICT.nodes[0],
       { ...RECOVERED_TREE.nodes[1], label: 'Wi-Fi', rect: { ...SCREEN, y: 600 - call * 37 } },
     ],
-  }));
+  });
+  const recoveredWithoutTarget = {
+    ...RECOVERED_TREE,
+    nodes: [RECOVERED_TREE.nodes[0], { ...RECOVERED_TREE.nodes[1], label: 'Wi-Fi' }],
+  };
   const realSetTimeout = globalThis.setTimeout;
   vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'Date'] });
   let done = false;
-  const pending = findClick(moving, true).finally(() => (done = true));
+  const pending = findClick(
+    (call, context) => (context?.snapshotScope ? recoveredWithoutTarget : movingSparse(call)),
+    true,
+  ).finally(() => (done = true));
   // The route awaits real I/O between polls, so the faked clock advances while the test yields.
   while (!done) {
     await vi.advanceTimersByTimeAsync(50);
@@ -150,10 +165,12 @@ test('a find that misses on a surface still moving after a scroll reports the un
   const { response } = await pending;
   vi.useRealTimers();
 
-  expect(response?.ok === false && response.error.details).toMatchObject({
-    unsettledGesture: { action: 'scroll', positionals: [] },
-    hint: expect.stringContaining(
-      formatGestureUnsettledWarning({ action: 'scroll', positionals: [] }),
-    ),
+  const outcome: PostGestureOutcome = {
+    kind: 'unsettled',
+    gesture: { action: 'scroll', positionals: [] },
+  };
+  expect(response?.ok === false && response.error).toMatchObject({
+    hint: expect.stringContaining(formatPostGestureOutcomeWarning(outcome)),
+    details: { postGestureOutcome: outcome },
   });
 });
diff --git a/src/daemon/interaction/internal/__tests__/interaction-target-activation-disclosure.test.ts b/src/daemon/interaction/internal/__tests__/interaction-capture-disclosure.test.ts
similarity index 53%
rename from src/daemon/interaction/internal/__tests__/interaction-target-activation-disclosure.test.ts
rename to src/daemon/interaction/internal/__tests__/interaction-capture-disclosure.test.ts
index d915ae7be9..03c0e94f7d 100644
--- a/src/daemon/interaction/internal/__tests__/interaction-target-activation-disclosure.test.ts
+++ b/src/daemon/interaction/internal/__tests__/interaction-capture-disclosure.test.ts
@@ -1,7 +1,8 @@
-import { test, expect } from 'vitest';
+import { test, expect, vi } from 'vitest';
 import {
   attachRefs,
   type IosTargetActivation,
+  type PostGestureOutcome,
   type SnapshotState,
 } from '@agent-device/kernel/snapshot';
 import { iosTargetActivationDisclosure } from '@agent-device/contracts/ios-target-activation';
@@ -9,6 +10,14 @@ import { makeSessionStore } from '../../../../__tests__/test-utils/store-factory
 import { handleInteractionCommands } from '../../index.ts';
 import { getRuntimeBindings } from '../../../__tests__/interaction-get-runtime-fixture.ts';
 import { contextFromFlags, makeSession } from './interaction-touch-fixtures.ts';
+import { legacyDispatchCapture } from '../../../__tests__/legacy-snapshot-capture-fixture.ts';
+import { markDeferredInteractionOutcome } from '../../../deferred-interaction-outcome.ts';
+import { formatPostGestureOutcomeWarning } from '@agent-device/capture-kit/post-gesture-stability';
+
+vi.mock('../../../snapshot-interactor-capture.ts', async () => {
+  const fixture = await import('../../../__tests__/legacy-snapshot-capture-fixture.ts');
+  return { captureSnapshotWithInteractor: fixture.captureSnapshotThroughLegacyDispatchFixture };
+});
 
 const FACT: IosTargetActivation = {
   reason: 'stale_target',
@@ -124,3 +133,76 @@ test('a press that consumes no capture is not disclosed against an older tree',
     expect(response.data?.targetActivation).toBeUndefined();
   }
 });
+
+const UNSETTLED: PostGestureOutcome = {
+  kind: 'unsettled',
+  gesture: { action: 'scroll', positionals: ['down'] },
+};
+
+/** A press by selector right after a scroll whose list never stops moving. */
+async function pressAfterUnsettledScroll(selector: string) {
+  const sessionStore = makeSessionStore();
+  const session = makeSession('default');
+  markDeferredInteractionOutcome({ session, command: 'scroll', positionals: ['down'], flags: {} });
+  sessionStore.set('default', session);
+  let call = 0;
+  legacyDispatchCapture.mockImplementation(async () => {
+    call += 1;
+    return {
+      backend: 'xctest',
+      nodes: [
+        { index: 0, depth: 0, type: 'Application', rect: { x: 0, y: 0, width: 390, height: 844 } },
+        {
+          index: 1,
+          parentIndex: 0,
+          depth: 1,
+          type: 'Cell',
+          label: 'Wi-Fi',
+          rect: { x: 16, y: 600 - call * 37, width: 370, height: 52 },
+          hittable: true,
+        },
+      ],
+    };
+  });
+  const realSetTimeout = globalThis.setTimeout;
+  vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'Date'] });
+  let done = false;
+  const pending = handleInteractionCommands({
+    req: { token: 't', session: 'default', command: 'press', positionals: [selector], flags: {} },
+    sessionName: 'default',
+    sessionStore,
+    contextFromFlags,
+    ...getRuntimeBindings(),
+  }).finally(() => (done = true));
+  // The route awaits real I/O between polls, so the faked clock advances while the test yields.
+  while (!done) {
+    await vi.advanceTimersByTimeAsync(50);
+    await new Promise((resolve) => realSetTimeout(resolve, 1));
+  }
+  const response = await pending;
+  vi.useRealTimers();
+  return { response, stored: sessionStore.get('default')?.snapshot };
+}
+
+/**
+ * The miss on the interactive capture is retried on a full tree at once; that retry reads the same
+ * moving surface, so neither the response nor the stored tree may present the miss as settled.
+ */
+test('a press that misses on a surface still moving after a scroll reports the unsettled outcome', async () => {
+  const { response, stored } = await pressAfterUnsettledScroll('label="General"');
+
+  expect(response?.ok === false && response.error).toMatchObject({
+    hint: expect.stringContaining(formatPostGestureOutcomeWarning(UNSETTLED)),
+    details: { reason: 'selector_not_found', postGestureOutcome: UNSETTLED },
+  });
+  expect(stored?.postGestureOutcome).toEqual(UNSETTLED);
+});
+
+test('a press that lands on a surface still moving after a scroll reports the outcome once', async () => {
+  const { response } = await pressAfterUnsettledScroll('label="Wi-Fi"');
+
+  expect(response?.ok && response.data).toMatchObject({
+    postGestureOutcome: UNSETTLED,
+    warnings: [formatPostGestureOutcomeWarning(UNSETTLED)],
+  });
+});
diff --git a/src/daemon/interaction/internal/find-target-capture.ts b/src/daemon/interaction/internal/find-target-capture.ts
index f1698f340d..e0b906f539 100644
--- a/src/daemon/interaction/internal/find-target-capture.ts
+++ b/src/daemon/interaction/internal/find-target-capture.ts
@@ -1,7 +1,7 @@
 import type { FindLocator } from '@agent-device/selectors';
 import type { BoundSelectorCapture } from '../../selector-capture-binding.ts';
 import type { SnapshotQualityVerdict, SnapshotState } from '@agent-device/kernel/snapshot';
-import type { CaptureProvenance, RequestActivationProof } from '../../capture-disclosure.ts';
+import type { CaptureProvenance, RequestCaptureProof } from '../../capture-disclosure.ts';
 import { createSelectorCaptureRuntime } from '../../selector-capture-runtime.ts';
 import { SessionStore } from '../../session-store.ts';
 import type { DaemonRequest, DaemonResponse } from '../../daemon-request.ts';
@@ -32,7 +32,7 @@ export function createFindTargetCapture(
      * Filled by whichever capture this find actually took, including a re-capture that replaced a
      * sparse first tree — find's response is owed the repair its own first capture paid for.
      */
-    activationProof: RequestActivationProof;
+    captureProof: RequestCaptureProof;
   }>,
 ): () => Promise<FindTargetTree> {
   const { device, session, req, logPath, locator, query, sessionStore, sessionName } = params;
@@ -44,7 +44,7 @@ export function createFindTargetCapture(
     req,
     logPath,
     capture: params.capture,
-    activationProof: params.activationProof,
+    captureProof: params.captureProof,
   });
   return async () => {
     // Interaction targets need the full interactive tree so duplicate labels can
diff --git a/src/daemon/interaction/internal/find.ts b/src/daemon/interaction/internal/find.ts
index 552e4b68fd..8a24349bc5 100644
--- a/src/daemon/interaction/internal/find.ts
+++ b/src/daemon/interaction/internal/find.ts
@@ -18,7 +18,7 @@ import type { SessionState } from '../../session-state.ts';
 import { SessionStore } from '../../session-store.ts';
 import { contextFromFlags } from '../../context.ts';
 import { readCommandMessage, successText } from '@agent-device/kernel/success-text';
-import type { RequestActivationProof } from '../../capture-disclosure.ts';
+import type { RequestCaptureProof } from '../../capture-disclosure.ts';
 import { withCaptureDisclosures } from '../../capture-disclosure.ts';
 import { recordSessionAction } from '../../session-action-recorder.ts';
 import { stripInternalInteractionFlags } from '../../interaction-outcome-policy.ts';
@@ -129,7 +129,7 @@ export async function handleFindCommands(params: FindRouteInput): Promise<Daemon
   // One proof for the whole request: whichever capture of find's (first pass or a sparse re-capture)
   // activated the session app owns the disclosure, including when the re-capture's tree is the one
   // that survives and gets answered from (#2682).
-  const activationProof: RequestActivationProof = {};
+  const captureProof: RequestCaptureProof = {};
   const readTargetTree = createFindTargetCapture({
     device,
     session,
@@ -140,7 +140,7 @@ export async function handleFindCommands(params: FindRouteInput): Promise<Daemon
     sessionStore,
     sessionName,
     capture: boundSelector.capture,
-    activationProof,
+    captureProof,
   });
 
   const ctx: FindContext = {
@@ -166,7 +166,7 @@ export async function handleFindCommands(params: FindRouteInput): Promise<Daemon
     return withCaptureDisclosures({
       response: sparseFindSnapshotResponse(snapshotResult.snapshotQuality),
       consumedTree: snapshotResult,
-      activationProof,
+      captureProof,
     });
   }
   const { nodes } = snapshotResult;
@@ -186,7 +186,7 @@ export async function handleFindCommands(params: FindRouteInput): Promise<Daemon
     return withCaptureDisclosures({
       response: matchResult.response,
       consumedTree: snapshotResult,
-      activationProof,
+      captureProof,
     });
   }
   const node = matchResult.node;
@@ -213,7 +213,7 @@ export async function handleFindCommands(params: FindRouteInput): Promise<Daemon
     ? withCaptureDisclosures({
         response,
         consumedTree: snapshotResult,
-        activationProof,
+        captureProof,
       })
     : response;
 }
diff --git a/src/daemon/interaction/internal/interaction-runtime.ts b/src/daemon/interaction/internal/interaction-runtime.ts
index 4ed682ebc6..0ca084d4ad 100644
--- a/src/daemon/interaction/internal/interaction-runtime.ts
+++ b/src/daemon/interaction/internal/interaction-runtime.ts
@@ -12,7 +12,7 @@ import type { DaemonCommandContext } from '../../context.ts';
 import { createDaemonRuntimePolicy } from '../../runtime-policy.ts';
 import { buildAppleRunnerRequestOptions } from '../../apple-runner-options.ts';
 import { isLocalIosRunnerSession } from '../../direct-ios-selector.ts';
-import { recordActivationProof } from '../../capture-disclosure.ts';
+import { recordCaptureProof } from '../../capture-disclosure.ts';
 import { confirmIosOffscreenTargetVisible } from '../../offscreen-target-probe.ts';
 import { createDaemonRuntimeSessionStore } from '../../runtime-session.ts';
 import { expireRefFrame } from '../../ref-frame.ts';
@@ -56,7 +56,7 @@ export function createInteractionRuntimeForRoute(
         params.contextFromFlags,
         options,
       );
-      return recordActivationProof(params.activationProof, snapshot);
+      return recordCaptureProof(params.captureProof, snapshot);
     },
     runtimeSessions: createDaemonRuntimeSessionStore({
       sessionName: params.sessionName,
diff --git a/src/daemon/interaction/internal/interaction.ts b/src/daemon/interaction/internal/interaction.ts
index 9da7b33160..1cc82a0a63 100644
--- a/src/daemon/interaction/internal/interaction.ts
+++ b/src/daemon/interaction/internal/interaction.ts
@@ -1,9 +1,6 @@
 import type { DaemonResponse } from '../../daemon-request.ts';
 import type { SessionState } from '../../session-state.ts';
-import {
-  type RequestActivationProof,
-  withTargetActivationDisclosure,
-} from '../../capture-disclosure.ts';
+import { type RequestCaptureProof, withCaptureDisclosures } from '../../capture-disclosure.ts';
 import type { CaptureSnapshotForSession, InteractionRouteInput } from './types.ts';
 import { dispatchFillViaRuntime } from './interaction-touch-fill.ts';
 import { dispatchTargetedTouchViaRuntime } from './interaction-touch-press.ts';
@@ -27,12 +24,12 @@ import { errorResponse, noActiveSessionError } from '@agent-device/kernel/contra
 export async function handleInteractionCommands(
   params: InteractionRouteInput & { captureSnapshotForSession: CaptureSnapshotForSession },
 ): Promise<DaemonResponse | null> {
-  const activationProof: RequestActivationProof = {};
-  const routed = { ...params, refSnapshotFlagGuardResponse, activationProof };
+  const captureProof: RequestCaptureProof = {};
+  const routed = { ...params, refSnapshotFlagGuardResponse, captureProof };
   const response = await dispatchInteractionCommand(routed);
-  // The interaction's own capture is what the gesture was aimed at, so a foreground repair inside
-  // it belongs on this response even though the interaction routes never read the stored snapshot.
-  return response ? withTargetActivationDisclosure(response, activationProof.state) : response;
+  return response
+    ? withCaptureDisclosures({ response, consumedTree: captureProof, captureProof })
+    : response;
 }
 
 type RoutedInteractionInput = InteractionRouteInput & {
diff --git a/src/daemon/interaction/internal/types.ts b/src/daemon/interaction/internal/types.ts
index 8a63ae5524..9236285c0d 100644
--- a/src/daemon/interaction/internal/types.ts
+++ b/src/daemon/interaction/internal/types.ts
@@ -1,7 +1,7 @@
 import type { CommandFlags } from '@agent-device/contracts/command';
 import type { AndroidObservationAdapter } from '@agent-device/contracts/android-observation';
 import type { Rect, SnapshotPreferredBackend, SnapshotState } from '@agent-device/kernel/snapshot';
-import type { RequestActivationProof } from '../../capture-disclosure.ts';
+import type { RequestCaptureProof } from '../../capture-disclosure.ts';
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import type { CommandSessionStore } from '../../../runtime-contract.ts';
 import type { DeferredInteractionOutcomeMark } from '../../deferred-interaction-outcome.ts';
@@ -35,7 +35,7 @@ export type InteractionRouteInput = {
    * The foreground repair this request's own capture reported, when it captured at all. A coordinate
    * press consumes no capture and must not be disclosed against an earlier request's tree (#2682).
    */
-  activationProof?: RequestActivationProof;
+  captureProof?: RequestCaptureProof;
 };
 
 export type FindRouteInput = {
diff --git a/src/daemon/selector-capture-runtime.ts b/src/daemon/selector-capture-runtime.ts
index bfbe7849c5..18a2664970 100644
--- a/src/daemon/selector-capture-runtime.ts
+++ b/src/daemon/selector-capture-runtime.ts
@@ -2,6 +2,7 @@ import type { CommandFlags } from '@agent-device/contracts/command';
 import type { BackendSnapshotResult } from '../backend.ts';
 import {
   buildSnapshotPresentationKey,
+  inheritPostGestureOutcome,
   snapshotPresentationOptionsFromFlags,
   type SnapshotState,
 } from '@agent-device/kernel/snapshot';
@@ -9,8 +10,8 @@ import { isSparseSnapshotQualityVerdict } from '@agent-device/capture-kit/snapsh
 import type { DaemonRequest } from './daemon-request.ts';
 import type { SessionState } from './session-state.ts';
 import { SessionStore } from './session-store.ts';
-import { recordActivationProof } from './capture-disclosure.ts';
-import type { RequestActivationProof } from './capture-disclosure.ts';
+import { recordCaptureProof } from './capture-disclosure.ts';
+import type { RequestCaptureProof } from './capture-disclosure.ts';
 import { captureSnapshot } from './snapshot-capture.ts';
 import { setSessionSnapshot } from './session-snapshot.ts';
 import { getActiveAndroidSnapshotFreshness } from './session-snapshot-freshness.ts';
@@ -36,7 +37,7 @@ export type SelectorCaptureRuntimeParams = {
    * Filled ONLY by a capture this request actually took, never by a cache tier — the foreground
    * repair a route may disclose has to be one the route paid for (#2682).
    */
-  activationProof?: RequestActivationProof;
+  captureProof?: RequestCaptureProof;
   /**
    * The request-bound capture from `resolveBoundSelectorCapture`: every cache tier, recovery
    * re-capture, and poll below reaches the platform through it. Required since find (R35) —
@@ -134,22 +135,28 @@ async function captureSelectorSnapshot(params: {
   const { params: runtimeParams, request } = params;
   const snapshot = await runCapture(runtimeParams, request, request.snapshotScope);
   if (request.recovery?.legacyIosSparse && isLegacySparseIosInteractiveSnapshot(snapshot)) {
-    return await recoverLegacySparseIosSnapshot({
-      runtimeParams,
-      request,
-      policy: request.recovery.legacyIosSparse,
-    });
+    return inheritPostGestureOutcome(
+      snapshot,
+      await recoverLegacySparseIosSnapshot({
+        runtimeParams,
+        request,
+        policy: request.recovery.legacyIosSparse,
+      }),
+    );
   }
   if (
     request.recovery?.sparseVerdictQueryScope?.shouldScope &&
     isSparseSnapshotQualityVerdict(snapshot.snapshotQuality)
   ) {
-    return await recoverSparseVerdictWithQueryScope({
-      runtimeParams,
-      request,
-      policy: request.recovery.sparseVerdictQueryScope,
+    return inheritPostGestureOutcome(
       snapshot,
-    });
+      await recoverSparseVerdictWithQueryScope({
+        runtimeParams,
+        request,
+        policy: request.recovery.sparseVerdictQueryScope,
+        snapshot,
+      }),
+    );
   }
   return snapshot;
 }
@@ -222,7 +229,7 @@ async function runCapture(
   // Recorded here rather than at the caller that consumes the result: a sparse recovery re-capture
   // DISCARDS this tree and returns a fresh one, and the repair this capture paid for belongs to the
   // request, not to whichever tree survives (#2682).
-  return recordActivationProof(params.activationProof, capture.snapshot);
+  return recordCaptureProof(params.captureProof, capture.snapshot);
 }
 
 function readReusableLastSnapshot(params: {
@@ -274,7 +281,7 @@ function canUseSessionSnapshotCache(
   if (request.cache?.useSessionSnapshot !== true) return false;
   if (getActiveAndroidSnapshotFreshness(session)) return false;
   if (shouldBypassForPostGestureStabilization(session, request)) return false;
-  return session.snapshot?.unsettledGesture === undefined;
+  return session.snapshot?.postGestureOutcome?.kind !== 'unsettled';
 }
 
 function isFreshSelectorSnapshot(snapshot: SnapshotState, timestamp: number): boolean {
diff --git a/src/daemon/selector-runtime-backend.ts b/src/daemon/selector-runtime-backend.ts
index 2348d31c3f..4af5d63305 100644
--- a/src/daemon/selector-runtime-backend.ts
+++ b/src/daemon/selector-runtime-backend.ts
@@ -28,7 +28,7 @@ import type { AndroidObservationAdapter } from '@agent-device/contracts/android-
 import type { PlatformResourceCleanup } from './platform-resource-cleanup.ts';
 import { getRequestSignal } from '@agent-device/host-kit/request';
 import { snapshotOptionsToFlags } from '../backend-snapshot-options.ts';
-import type { RequestActivationProof } from './capture-disclosure.ts';
+import type { RequestCaptureProof } from './capture-disclosure.ts';
 import { checkIsArgs } from '@agent-device/selectors';
 import { noActiveSessionError } from '@agent-device/kernel/contracts';
 
@@ -42,7 +42,7 @@ export type SelectorRuntimeParams = {
   // sessionless routes disclose from here because no session record stores the capture.
   consumedSnapshot?: { state?: SnapshotState };
   /** The repair this request's own capture reported, when it captured at all (#2682). */
-  activationProof?: RequestActivationProof;
+  captureProof?: RequestCaptureProof;
   signal?: AbortSignal;
   inspectFacts?: InspectDeviceRuntimeFacts;
   bindDevice?: BindDeviceRuntime;
@@ -94,7 +94,7 @@ async function resolveSelectorRuntimeDevice(
   requireSession: boolean,
 ): Promise<ResolvedSelectorDevice> {
   params.consumedSnapshot ??= {};
-  params.activationProof ??= {};
+  params.captureProof ??= {};
   const session = params.sessionStore.get(params.sessionName);
   if (!session && requireSession) return { ok: false, response: noActiveSessionError() };
   const device = session?.device ?? (await resolveTargetDevice(params.req.flags ?? {}));
@@ -172,7 +172,7 @@ function createSelectorBackend(params: SelectorRuntimeDeviceParams): AgentDevice
           sessionName,
           req,
           consumedSnapshot: params.consumedSnapshot,
-          activationProof: params.activationProof,
+          captureProof: params.captureProof,
           logPath,
           capture: boundOperations.capture,
         });
diff --git a/src/daemon/selector-runtime.ts b/src/daemon/selector-runtime.ts
index c49279293a..13ea73daa6 100644
--- a/src/daemon/selector-runtime.ts
+++ b/src/daemon/selector-runtime.ts
@@ -104,7 +104,7 @@ export async function dispatchFindReadOnlyViaRuntime(
   return withCaptureDisclosures({
     response,
     consumedTree: consumedSessionSnapshot(params),
-    activationProof: params.activationProof,
+    captureProof: params.captureProof,
   });
 }
 
@@ -182,7 +182,7 @@ export async function dispatchGetViaRuntime(
   return withCaptureDisclosures({
     response,
     consumedTree: consumedSessionSnapshot(params),
-    activationProof: params.activationProof,
+    captureProof: params.captureProof,
   });
 }
 
@@ -242,7 +242,7 @@ export async function dispatchIsViaRuntime(
   return withCaptureDisclosures({
     response: await maybeAndroidForegroundBlockerResponse(params, response, `is ${predicate}`),
     consumedTree: consumedSessionSnapshot(params),
-    activationProof: params.activationProof,
+    captureProof: params.captureProof,
   });
 }
 
diff --git a/src/daemon/snapshot-runtime.ts b/src/daemon/snapshot-runtime.ts
index 96c938473f..b7cf97cf30 100644
--- a/src/daemon/snapshot-runtime.ts
+++ b/src/daemon/snapshot-runtime.ts
@@ -4,7 +4,7 @@ import {
   SNAPSHOT_COMMAND_OPTION_KEYS,
   snapshotOptionsFromFlags,
 } from '@agent-device/kernel/snapshot';
-import type { RequestActivationProof } from './capture-disclosure.ts';
+import type { RequestCaptureProof } from './capture-disclosure.ts';
 import { withTargetActivationDisclosure } from './capture-disclosure.ts';
 import { dispatchSnapshotRuntimeCommand } from './snapshot-command-runtime.ts';
 import { captureSparseFallbackScreenshot } from './sparse-fallback-screenshot.ts';
@@ -15,7 +15,7 @@ import type { SessionState } from './session-state.ts';
 export async function dispatchSnapshotViaRuntime(
   params: SnapshotRuntimeRouteParams,
 ): Promise<DaemonResponse> {
-  const activationProof: RequestActivationProof = {};
+  const captureProof: RequestCaptureProof = {};
   const response = await dispatchSnapshotRuntimeCommand({
     ...params,
     command: 'snapshot',
@@ -33,9 +33,7 @@ export async function dispatchSnapshotViaRuntime(
       });
       // This request's own capture, read here rather than off the stored snapshot: a snapshot that
       // failed before capturing must not inherit the previous command's repair (#2682).
-      if (result.targetActivation && !activationProof.state) {
-        activationProof.state = { targetActivation: result.targetActivation };
-      }
+      if (result.targetActivation) captureProof.targetActivation ??= result.targetActivation;
       const refsGeneration = publishedSnapshotGeneration(
         request,
         params.sessionStore.get(resolvedSessionName),
@@ -83,7 +81,7 @@ export async function dispatchSnapshotViaRuntime(
   // own annotations, so re-deriving it from the stored snapshot would copy a sentence the response
   // already carries — and on a snapshot that failed before capturing, would credit it with a surface
   // it never observed (#2682).
-  return withTargetActivationDisclosure(response, activationProof.state);
+  return withTargetActivationDisclosure(response, captureProof);
 }
 
 function publishedSnapshotGeneration(
diff --git a/src/daemon/wait-current-surface.test.ts b/src/daemon/wait-current-surface.test.ts
index f11a6aa40b..3b1865a865 100644
--- a/src/daemon/wait-current-surface.test.ts
+++ b/src/daemon/wait-current-surface.test.ts
@@ -1,7 +1,7 @@
 import { expect, test, vi } from 'vitest';
 
 import { ANDROID_EMULATOR } from '../__tests__/test-utils/device-fixtures.ts';
-import type { RequestActivationProof } from './capture-disclosure.ts';
+import type { RequestCaptureProof } from './capture-disclosure.ts';
 import { maybeWaitTimeoutSurfaceResponse } from './wait-current-surface.ts';
 import type { BoundSelectorCapture } from './selector-capture-binding.ts';
 
@@ -113,10 +113,10 @@ test('the decoration capture records the foreground repair it paid for', async (
     targetActivation: repair,
     nodes: [{ index: 0, depth: 0, type: 'Button', label: 'Receipt' }],
   })) as unknown as BoundSelectorCapture;
-  const activationProof: RequestActivationProof = {};
+  const captureProof: RequestCaptureProof = {};
 
   await maybeWaitTimeoutSurfaceResponse(
-    { req, session: undefined, device: ANDROID_EMULATOR, capture, activationProof },
+    { req, session: undefined, device: ANDROID_EMULATOR, capture, captureProof },
     {
       ok: false as const,
       error: {
@@ -127,5 +127,5 @@ test('the decoration capture records the foreground repair it paid for', async (
     },
   );
 
-  expect(activationProof.state).toMatchObject({ targetActivation: repair });
+  expect(captureProof.targetActivation).toEqual(repair);
 });
diff --git a/src/daemon/wait-current-surface.ts b/src/daemon/wait-current-surface.ts
index 5238b2fb37..db7de91bcd 100644
--- a/src/daemon/wait-current-surface.ts
+++ b/src/daemon/wait-current-surface.ts
@@ -1,7 +1,7 @@
 import { WAIT_REASONS } from '@agent-device/contracts/wait';
 import type { SnapshotNode } from '@agent-device/kernel/snapshot';
-import { recordActivationProof } from './capture-disclosure.ts';
-import type { RequestActivationProof } from './capture-disclosure.ts';
+import { recordCaptureProof } from './capture-disclosure.ts';
+import type { RequestCaptureProof } from './capture-disclosure.ts';
 import type { DaemonRequest, DaemonResponse } from './daemon-request.ts';
 import type { SessionState } from './session-state.ts';
 import { captureSnapshot } from './snapshot-capture.ts';
@@ -25,7 +25,7 @@ type WaitCurrentSurfaceParams = {
    * A timed-out wait still consumed that capture to describe its surface, so the repair it paid for
    * belongs to the response this module decorates.
    */
-  activationProof?: RequestActivationProof;
+  captureProof?: RequestCaptureProof;
 };
 
 type CurrentSurfaceDetails = {
@@ -89,7 +89,7 @@ async function inspectCurrentSurface(
         }),
       ),
   });
-  recordActivationProof(params.activationProof, capture.snapshot);
+  recordCaptureProof(params.captureProof, capture.snapshot);
   const orderedNodes = [...capture.snapshot.nodes].sort(compareSurfacePriority);
   const labels = topSurfaceTexts(orderedNodes, 6, { includeIdentifiers: true });
   if (labels.length === 0) return null;
diff --git a/src/daemon/wait-runtime.ts b/src/daemon/wait-runtime.ts
index 025061dabd..766f7df922 100644
--- a/src/daemon/wait-runtime.ts
+++ b/src/daemon/wait-runtime.ts
@@ -54,7 +54,7 @@ export async function dispatchWaitViaRuntime(params: DispatchWaitParams): Promis
   // Wait builds its runtime directly (no createBoundSelectorRuntime), so the consumed-snapshot slot
   // must be initialized here too or sessionless waits have nowhere to report the capture from.
   params.consumedSnapshot ??= {};
-  params.activationProof ??= {};
+  params.captureProof ??= {};
   // A pure sleep consumes no capture, so it never earns the system-surface disclosure below.
   if (parsed.kind === 'sleep') {
     return await executeWaitRequest(
@@ -86,7 +86,7 @@ export async function dispatchWaitViaRuntime(params: DispatchWaitParams): Promis
       params.platformResourceCleanup,
     ),
     consumedTree: consumedSessionSnapshot(params),
-    activationProof: params.activationProof,
+    captureProof: params.captureProof,
   });
 }
 
@@ -187,7 +187,7 @@ async function executeWaitRequest(
           session,
           device,
           capture: waitOperations.capture,
-          activationProof: params.activationProof,
+          captureProof: params.captureProof,
         },
         response,
       )
diff --git a/test/integration/ios-simulator-e2e-visibility-scroll.test.ts b/test/integration/ios-simulator-e2e-visibility-scroll.test.ts
index ae2458bb30..e2de4a401b 100644
--- a/test/integration/ios-simulator-e2e-visibility-scroll.test.ts
+++ b/test/integration/ios-simulator-e2e-visibility-scroll.test.ts
@@ -16,13 +16,15 @@ function result(status: number, details?: Record<string, unknown>): CliJsonResul
   };
 }
 
-const UNSETTLED = { unsettledGesture: { action: 'scroll', positionals: [] } };
+const UNSETTLED = {
+  postGestureOutcome: { kind: 'unsettled', gesture: { action: 'scroll', positionals: [] } },
+};
 
 /**
  * A vertical list the search drives. Offsets are in viewports; the target is visible while the
  * offset lies inside `visible`. Each scroll moves by the next planned travel, clamped to the list
  * bounds. `movesUntilSettled` keeps the surface moving after every scroll that moved until the
- * search pauses to settle it, so each read before that misses with `unsettledGesture`: the CI
+ * search pauses to settle it, so each read before that misses with an unsettled outcome: the CI
  * failure shape.
  */
 function list(options: {
@@ -82,6 +84,24 @@ test('a stalled capture retries without scrolling or consuming an attempt', asyn
   assert.deepEqual([probes.length, scrolls], [0, []]);
 });
 
+test('a miss after a gesture that moved nothing is a real read, not a moving surface', async () => {
+  const noEffect = {
+    postGestureOutcome: { kind: 'no-effect', gesture: { action: 'scroll', positionals: [] } },
+  };
+  const probes = [result(1, noEffect), result(0)];
+  const scrolls: string[] = [];
+
+  await searchForVisibleElement('id="target"', {
+    probeVisibility: async () => probes.shift() ?? result(1),
+    settle: async () => assert.fail('a no-effect read is settled'),
+    scroll: async (step) => {
+      scrolls.push(step.direction);
+    },
+  });
+
+  assert.deepEqual([probes.length, scrolls], [0, ['down']]);
+});
+
 test('an unsettled miss waits for the surface to settle and re-reads at the same offset', async () => {
   const { device, log } = list({ visible: [0.5, 1.2], movesUntilSettled: true });
 
diff --git a/test/integration/ios-simulator-e2e/live-assertions.ts b/test/integration/ios-simulator-e2e/live-assertions.ts
index b0e33d0092..7b37a9842c 100644
--- a/test/integration/ios-simulator-e2e/live-assertions.ts
+++ b/test/integration/ios-simulator-e2e/live-assertions.ts
@@ -129,7 +129,7 @@ export async function searchForVisibleElement(
 /** Why a missed probe says nothing about where the element is, if it says nothing. */
 function unreadSurface(result: CliJsonResult): 'moving' | 'stalled' | undefined {
   const details = result.json?.error?.details;
-  if (details?.unsettledGesture !== undefined) return 'moving';
+  if (details?.postGestureOutcome?.kind === 'unsettled') return 'moving';
   return details?.captureStalled === true ? 'stalled' : undefined;
 }
 
diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md
index 55319492a5..e470e55ce3 100644
--- a/website/docs/docs/commands.md
+++ b/website/docs/docs/commands.md
@@ -558,7 +558,9 @@ agent-device is text 'id="greeting"' "Welcome back"
 - `is visible` checks whether the resolved element is present in the current visible snapshot viewport. A node without its own rect still passes when a visible ancestor within the viewport provides the on-screen geometry.
 - `is exists` only checks whether the selector matches in the current snapshot.
 - `is absent` passes only when the selector has zero matches in one readable, complete, settled, unscoped, full-depth accessibility capture. It does not mean hidden; `--scope` and `--depth` are rejected, and sparse, unreadable, truncated, or unsettled captures fail closed.
-- A read that answers from the first capture after a `scroll`, `swipe`, or `gesture swipe` waits for two consecutive captures to agree. When the surface is still changing when that budget runs out, `is`, `get`, `find`, and `wait` carry `unsettledGesture` (`{ "action", "positionals" }`) in `error.details` or `data` and append a warning, and `snapshot` appends the warning. A miss on that capture is not proof of absence: read again. `is absent` refuses it with `observation: "unsettled"`, and `wait absent` keeps polling.
+- A read that answers from the first capture after a `scroll`, `swipe`, or `gesture swipe` waits for two consecutive captures to agree. That capture, and a re-capture taken at once to recover or widen it, carry `postGestureOutcome` (`{ "kind", "gesture": { "action", "positionals" } }`) when stabilization proved something about the gesture. `is`, `get`, `find`, `wait`, and an interaction that captured it (such as `click`, `press`, or `fill`) report it in `error.details` or `data` and append a warning, and `snapshot` appends the warning.
+  - `kind: "unsettled"`: the surface was still changing when the budget ran out. A miss on that capture is not proof of absence: read again. `is absent` refuses it with `observation: "unsettled"`, and `wait absent` keeps polling.
+  - `kind: "no-effect"`: the settled tree still matches the tree from before the gesture. The container may be at its edge or may ignore synthesized scrolls; a raw `swipe x1 y1 x2 y2` inside the list moves such lists.
 - `wait text` is a text-presence wait, not a hittability assertion.
 - Strict `wait absent` is not exported to Maestro's lenient `notVisible` condition; Maestro export reports it as unsupported unless an exact zero-candidate primitive becomes available.
 - `is text <selector> <value>` compares the resolved element text against the expected value.

From b916605e1418e2ca3c6f229bd17c0f15fd7b2c9b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 24 Sep 2026 15:51:19 +0200
Subject: [PATCH 093/132] fix(apple): refuse fold on a scoped simulator set at
 runtime admission (#2887)

* fix(apple): refuse fold on a scoped simulator set at runtime admission

fold on an iPhone Duo inside --ios-simulator-device-set failed after the
HID send because CoreDevice's display inventory and hinge-angle readback
resolve a scoped simulator as not found, so ADR 0025's post-dispatch
verification is impossible. Refuse it instead at the owning setFoldPose
fact when device.simulatorSetPath is present, with the typed
unsupported-device-scope reason; the routed response derives the same
reason and a hint naming the set. The default set and the existing
kind/OS refusals are unchanged.

* test(apple): prove the scoped fold refusal on the daemon route

Move the zero-side-effect proof onto the real fold route: a scoped
setFoldPose fact is refused at admission, so the wire error carries the
typed unsupported-device-scope reason and the set name and the device is
never bound. Refocus the colocated narrowDeviceBinding test to what it
proves, and collapse the repeated CoreDevice-scope rationale to one
owning comment.

* refactor(daemon): share the generic runtime-admission refusal builder

The fold override restated the same UNSUPPORTED_OPERATION + '<command> is
not supported on this device' + hint the admission default already built,
only to add details.reason. Own that refusal once in admitRuntimeOperations
and reuse it: the default is byte-identical, fold passes its typed reason
as details, and no other route's wire shape changes.

* docs(fold): keep the scoped-set rationale on the reference surfaces

The terse fold command description restated the same CoreDevice-scope
rationale the deep help topic and commands.md carry. The description now
states only the refusal, its typed reason, and the fix; the why lives on
the surfaces a user opens to read more.

* refactor(daemon): carry the typed reason in the one refusal both runtime seams build

The generic route and the request-scoped session handlers each owned a
byte-identical UNSUPPORTED_OPERATION refusal, but only the session seam
attached details.reason, so the shared default emitted the same sentence
with a different wire shape and fold had to re-add the reason through a
custom unavailableResponse. unsupportedOperationResponse now always attaches
details: { reason } and unavailableRuntimeOperationResponse delegates to it,
so one builder owns sentence + reason + hint for both seams. fold drops its
override and its second 'fold' mention; conformance asserts the single shape.

Nits: cross-link the scoped HID transport test to the owning fact that
refuses the scope, and assert hint propagation with a sentinel instead of
echoing production wording.
---
 packages/contracts/src/platform-runtime.ts    |   2 +
 .../src/foldable/runtime.test.ts              | 103 ++++++++++++++++++
 .../platform-apple/src/foldable/runtime.ts    |  21 +++-
 .../src/foldable/simulator-hid.test.ts        |   3 +
 packages/platform-apple/src/runtime.test.ts   |  22 ++++
 src/commands/schema/cli-help.ts               |   2 +-
 src/commands/system/index.ts                  |   2 +-
 src/daemon/__tests__/fold-runtime.test.ts     |  39 ++++++-
 src/daemon/__tests__/keyboard-runtime.test.ts |   1 +
 .../__tests__/runtime-binding-conformance.ts  |   3 +-
 src/daemon/runtime-admission.ts               |  25 ++++-
 src/daemon/session-runtime-admission.ts       |  16 ++-
 website/docs/docs/commands.md                 |   1 +
 13 files changed, 217 insertions(+), 23 deletions(-)
 create mode 100644 packages/platform-apple/src/foldable/runtime.test.ts

diff --git a/packages/contracts/src/platform-runtime.ts b/packages/contracts/src/platform-runtime.ts
index 9170994551..dff20619e5 100644
--- a/packages/contracts/src/platform-runtime.ts
+++ b/packages/contracts/src/platform-runtime.ts
@@ -126,6 +126,7 @@ export type RuntimeOperationUnavailability = Readonly<{
     | 'unsupported-platform-leaf'
     | 'unsupported-device-kind'
     | 'unsupported-device-backend'
+    | 'unsupported-device-scope'
     | 'unsupported-provider-mode'
     | 'owner-capability-missing';
   hint?: string;
@@ -406,6 +407,7 @@ function isRuntimeOperationUnavailabilityReason(
     value === 'unsupported-platform-leaf' ||
     value === 'unsupported-device-kind' ||
     value === 'unsupported-device-backend' ||
+    value === 'unsupported-device-scope' ||
     value === 'unsupported-provider-mode' ||
     value === 'owner-capability-missing'
   );
diff --git a/packages/platform-apple/src/foldable/runtime.test.ts b/packages/platform-apple/src/foldable/runtime.test.ts
new file mode 100644
index 0000000000..4eaf1525e8
--- /dev/null
+++ b/packages/platform-apple/src/foldable/runtime.test.ts
@@ -0,0 +1,103 @@
+import { beforeEach, expect, test, vi } from 'vitest';
+
+vi.mock('./pose.ts', () => ({ setAppleFoldPose: vi.fn() }));
+
+import {
+  localRuntimeOwner,
+  narrowDeviceBinding,
+  type DeviceBinding,
+  type RuntimeFacts,
+} from '@agent-device/contracts/platform-runtime';
+import {
+  foldRuntimeUse,
+  type PlatformRuntimeOperations,
+} from '@agent-device/contracts/platform-runtime-operations';
+import { deviceShape, type DeviceInfo } from '@agent-device/kernel/device';
+
+import { appleFoldableFacts, createAppleFoldableOperations } from './runtime.ts';
+import { setAppleFoldPose } from './pose.ts';
+
+const mockPose = vi.mocked(setAppleFoldPose);
+
+const duo: DeviceInfo = {
+  platform: 'apple',
+  appleOs: 'ios',
+  id: '4F879835-4AB3-4046-B033-5AB769209DD4',
+  name: 'iPhone Duo',
+  kind: 'simulator',
+  target: 'mobile',
+  booted: true,
+};
+const scopedDuo: DeviceInfo = { ...duo, simulatorSetPath: '/tmp/scoped-set' };
+
+/** A full owner binding whose fold cell is derived only from the fact under test. */
+function foldBinding(device: DeviceInfo): DeviceBinding<PlatformRuntimeOperations> {
+  const { setFoldPose } = appleFoldableFacts(device);
+  return {
+    device,
+    owner: localRuntimeOwner('apple'),
+    facts: {
+      device: { ...deviceShape(device), providerMode: 'local' },
+      operations: { setFoldPose } as RuntimeFacts<PlatformRuntimeOperations>['operations'],
+    },
+    operations: createAppleFoldableOperations({ device, signal: new AbortController().signal }),
+    [Symbol.asyncDispose]: async () => {},
+  };
+}
+
+function thrownBy<T>(run: () => T): unknown {
+  try {
+    run();
+  } catch (error) {
+    return error;
+  }
+  throw new Error('expected the routed fold binding to refuse');
+}
+
+beforeEach(() => {
+  mockPose.mockReset();
+});
+
+test('the default-set iPhone Duo admits setFoldPose and binds the pose operation', () => {
+  expect(appleFoldableFacts(duo).setFoldPose).toEqual({ available: true });
+  expect(
+    createAppleFoldableOperations({ device: duo, signal: new AbortController().signal }),
+  ).toHaveProperty('setFoldPose', expect.any(Function));
+});
+
+test('a scoped simulator set refuses setFoldPose with the typed unsupported-device-scope fact', () => {
+  expect(appleFoldableFacts(scopedDuo).setFoldPose).toMatchObject({
+    available: false,
+    reason: 'unsupported-device-scope',
+    hint: expect.stringContaining('/tmp/scoped-set'),
+  });
+});
+
+test('a scoped simulator set binds no pose operation and never reaches a hinge', () => {
+  const operations = createAppleFoldableOperations({
+    device: scopedDuo,
+    signal: new AbortController().signal,
+  });
+  expect(operations).not.toHaveProperty('setFoldPose');
+  expect(mockPose).not.toHaveBeenCalled();
+});
+
+test('the narrowed fold use refuses a scoped simulator set with the typed fact reason and hint', () => {
+  const refusal = thrownBy(() => narrowDeviceBinding(foldBinding(scopedDuo), foldRuntimeUse)) as {
+    code?: string;
+    details?: { reason?: string; hint?: string };
+  };
+  expect(refusal.code).toBe('UNSUPPORTED_OPERATION');
+  expect(refusal.details?.reason).toBe('unsupported-device-scope');
+  expect(refusal.details?.hint).toContain('/tmp/scoped-set');
+});
+
+test('a scoped set never outranks the existing kind and OS refusals', () => {
+  expect(appleFoldableFacts({ ...scopedDuo, kind: 'device' }).setFoldPose).toMatchObject({
+    available: false,
+    reason: 'unsupported-device-kind',
+  });
+  expect(
+    appleFoldableFacts({ ...scopedDuo, appleOs: 'tvos', target: 'tv' }).setFoldPose,
+  ).toMatchObject({ available: false, reason: 'unsupported-platform-leaf' });
+});
diff --git a/packages/platform-apple/src/foldable/runtime.ts b/packages/platform-apple/src/foldable/runtime.ts
index c5310f0b31..5460a42c4e 100644
--- a/packages/platform-apple/src/foldable/runtime.ts
+++ b/packages/platform-apple/src/foldable/runtime.ts
@@ -19,16 +19,33 @@ const foldOsUnavailable = Object.freeze({
   hint: 'fold poses the hinge of a foldable iPhone; tvOS, macOS, watchOS and visionOS simulators have no hinge.',
 } as const);
 
+/**
+ * A fold inside a scoped simulator set cannot verify its pose: the HID send honours `--set`, but
+ * `devicectl device info displays` and `devicectl device motion hinge-angle` take only `--device`
+ * and resolve a scoped simulator as `not found`, so ADR 0025's post-dispatch readback is impossible.
+ * The refusal is the owning fact, before any display probe or HID effect; the default set is unaffected.
+ */
+function foldScopeUnavailable(simulatorSetPath: string) {
+  return {
+    available: false,
+    reason: 'unsupported-device-scope',
+    hint: `fold cannot resolve a simulator scoped to the set at "${simulatorSetPath}": CoreDevice's display inventory and hinge-angle readback need a simulator in the default set, so the pose could not be verified. Run fold without --ios-simulator-device-set.`,
+  } as const;
+}
+
 /**
  * The simulator leaf that can carry a hinge: iPhone and iPad. Which *model* inside it actually
  * folds is not in `DeviceInfo`, so the operation answers that from CoreDevice's display table and
  * refuses a single-panel simulator with a typed `UNSUPPORTED_OPERATION`, the way the runner
- * answers for the Action Button hardware.
+ * answers for the Action Button hardware. A simulator scoped to a non-default set is refused too;
+ * see {@link foldScopeUnavailable}.
  */
 function appleFoldFact(device: DeviceInfo): RuntimeOperationFact {
   if (device.kind !== 'simulator') return foldKindUnavailable;
   const os = resolveDeviceAppleOs(device);
-  return os === 'ios' || os === 'ipados' ? available : foldOsUnavailable;
+  if (os !== 'ios' && os !== 'ipados') return foldOsUnavailable;
+  if (device.simulatorSetPath) return foldScopeUnavailable(device.simulatorSetPath);
+  return available;
 }
 
 /** The foldable cell: `setFoldPose`. */
diff --git a/packages/platform-apple/src/foldable/simulator-hid.test.ts b/packages/platform-apple/src/foldable/simulator-hid.test.ts
index 9cccc35e8f..4874686cb8 100644
--- a/packages/platform-apple/src/foldable/simulator-hid.test.ts
+++ b/packages/platform-apple/src/foldable/simulator-hid.test.ts
@@ -70,6 +70,9 @@ test('streams all keyframes in one process with a duration-derived timeout', asy
   expect(dispatches).toBe(1);
 });
 
+// Transport-level only: this pins that a pose dispatch routes through runSimctlForDevice, which
+// targets the UDID inside its scoped set. It is NOT end-to-end scoped-fold support — `appleFoldFact`
+// refuses `unsupported-device-scope` at runtime admission before this dispatch is ever reached.
 test('HID dispatch addresses the UDID inside its scoped simulator set', async () => {
   const dispatches: string[][] = [];
   await withAppleToolProvider(
diff --git a/packages/platform-apple/src/runtime.test.ts b/packages/platform-apple/src/runtime.test.ts
index fc717d51d9..fcd1b6ed25 100644
--- a/packages/platform-apple/src/runtime.test.ts
+++ b/packages/platform-apple/src/runtime.test.ts
@@ -282,6 +282,28 @@ test.each(Object.entries(leaves))(
   },
 );
 
+// A simulator scoped to a non-default set is refused by the owner's own fact, before any display
+// probe or HID effect: CoreDevice's display inventory and hinge-angle readback cannot resolve it,
+// so ADR 0025's post-dispatch verification is impossible. The default-set iOS leaf stays admitted.
+test('refuses the fold fact for a scoped simulator set and binds no pose operation', async () => {
+  const scoped = appleDevice({ simulatorSetPath: '/tmp/scoped-set' });
+  const binding = await createApplePlatformRuntime(platformRuntimeHostFixture()).bind({
+    device: scoped,
+    intent: { kind: 'ordinary' },
+    scope: {
+      signal: new AbortController().signal,
+      diagnostics: { emit: () => {} },
+      progress: { report: () => {} },
+    },
+  });
+  expect(binding.facts.operations.setFoldPose).toMatchObject({
+    available: false,
+    reason: 'unsupported-device-scope',
+    hint: expect.stringContaining('/tmp/scoped-set'),
+  });
+  expect(binding.operations.setFoldPose).toBeUndefined();
+});
+
 /**
  * The Action Button is a physical control on iPhone and iPad leaves only. visionOS is the leaf that
  * separates this from `orientation`'s mobile-input reading: a headset has a Digital Crown and no
diff --git a/src/commands/schema/cli-help.ts b/src/commands/schema/cli-help.ts
index 9177607575..444a845d1d 100644
--- a/src/commands/schema/cli-help.ts
+++ b/src/commands/schema/cli-help.ts
@@ -749,7 +749,7 @@ Screens are handled for you:
 
 Changing the pose:
   agent-device fold closed | half-open | open
-  fold sends a private HID hinge event inside the selected simulator and then reads the hinge angle back from CoreDevice until it agrees: closed is 0 degrees, open is 180, and half-open is any angle between them (requested at 130 degrees). An angle in that interval only proves the category, so half-open is reported once two consecutive readings both fall inside it and agree within 0.5 degrees. The response reports the verified pose, the hinge angle, and the panel the device now lights with its native panel point size, marked coordinateSpace "native-panel". That point size is the panel's own geometry, not the next snapshot's viewport, so it cannot place a tap: the active app window can differ (a 669x951 inner panel hosts a 951x669 window). A hinge whose last reading is some other pose fails with COMMAND_FAILED and reason fold-pose-unverified, naming the angle CoreDevice still reports; a hinge seen half-open but never at rest fails with reason fold-pose-unsettled, naming the observed and previous angles. A single-panel simulator fails with UNSUPPORTED_OPERATION.
+  fold sends a private HID hinge event inside the selected simulator and then reads the hinge angle back from CoreDevice until it agrees: closed is 0 degrees, open is 180, and half-open is any angle between them (requested at 130 degrees). An angle in that interval only proves the category, so half-open is reported once two consecutive readings both fall inside it and agree within 0.5 degrees. The response reports the verified pose, the hinge angle, and the panel the device now lights with its native panel point size, marked coordinateSpace "native-panel". That point size is the panel's own geometry, not the next snapshot's viewport, so it cannot place a tap: the active app window can differ (a 669x951 inner panel hosts a 951x669 window). A hinge whose last reading is some other pose fails with COMMAND_FAILED and reason fold-pose-unverified, naming the angle CoreDevice still reports; a hinge seen half-open but never at rest fails with reason fold-pose-unsettled, naming the observed and previous angles. A single-panel simulator fails with UNSUPPORTED_OPERATION. A simulator scoped to a non-default set with --ios-simulator-device-set is refused before any hinge is touched, with UNSUPPORTED_OPERATION and reason unsupported-device-scope: the HID send honors the set, but CoreDevice's display inventory and hinge-angle readback resolve a scoped simulator as not found, so the pose could not be verified. Run fold without --ios-simulator-device-set (in the default set).
   Expect a fold to take 10-16 seconds: each hinge read is a five-second devicectl stream, and half-open waits for the hinge to stop moving. Re-snapshot after every fold; refs and coordinates from before it are stale, and the command's message says so.
   Timed motion: fold --keyframes '[{"atMs":0,"angle":0},{"atMs":5000,"angle":180}]'. Use 2–64 frames starting at 0ms, increasing integer timestamps up to 60000ms, and angles from 0 to 180. The last timestamp sets motion duration, excluding setup and verification. Equal angles hold; cancellation stops motion. See the fold examples in the command and Node API documentation for trajectories.
 
diff --git a/src/commands/system/index.ts b/src/commands/system/index.ts
index 448d3b51c0..25fe92323f 100644
--- a/src/commands/system/index.ts
+++ b/src/commands/system/index.ts
@@ -72,7 +72,7 @@ const homeCommandDescription =
   'Send the selected device to its home screen. This leaves the app session open but moves the foreground away from the app.';
 const orientationCommandDescription = 'Set device orientation on iOS and Android';
 const foldCommandDescription =
-  'Fold or unfold a foldable iPhone simulator (iPhone Duo) into the closed, half-open, or open pose, or follow timestamped angle keyframes, by sending a simulator HID hinge event, then read the hinge angle back from CoreDevice to confirm it. A pose change moves the app to a different panel with a different point size, so every ref and coordinate from before it is stale: re-snapshot after this command. Taps, long presses, and scrolling target the app window on its current panel in closed, half-open, and open poses. Simulator-only; requires the iOS simulator SDK; Device Hub and host Accessibility permission are not required.';
+  'Fold or unfold a foldable iPhone simulator (iPhone Duo) into the closed, half-open, or open pose, or follow timestamped angle keyframes, by sending a simulator HID hinge event, then read the hinge angle back from CoreDevice to confirm it. A pose change moves the app to a different panel with a different point size, so every ref and coordinate from before it is stale: re-snapshot after this command. Taps, long presses, and scrolling target the app window on its current panel in closed, half-open, and open poses. Simulator-only; requires the iOS simulator SDK; Device Hub and host Accessibility permission are not required. A simulator scoped to a non-default simulator set is refused with UNSUPPORTED_OPERATION and reason unsupported-device-scope; run fold against a simulator in the default set.';
 const appSwitcherCommandDescription =
   'Open the device app switcher to inspect or change foreground apps. This changes the visible system UI and may move focus away from the current app.';
 const keyboardCommandDescription =
diff --git a/src/daemon/__tests__/fold-runtime.test.ts b/src/daemon/__tests__/fold-runtime.test.ts
index ed41d0d900..693e36587d 100644
--- a/src/daemon/__tests__/fold-runtime.test.ts
+++ b/src/daemon/__tests__/fold-runtime.test.ts
@@ -16,7 +16,7 @@ import {
   foldRuntimeUse,
   type PlatformRuntimeOperations,
 } from '@agent-device/contracts/platform-runtime-operations';
-import { deviceShape } from '@agent-device/kernel/device';
+import { deviceShape, type DeviceInfo } from '@agent-device/kernel/device';
 import { makeSession } from '../../__tests__/test-utils/session-factories.ts';
 import type { BindDeviceRuntime, InspectDeviceRuntimeFacts } from '../request-runtime-binding.ts';
 import type { GenericPlatformExecutionParams } from '../request-generic-dispatch.ts';
@@ -60,13 +60,14 @@ function runtimeHarness(
     pose: 'open',
     hingeAngleDegrees: 180,
   })),
+  device: DeviceInfo = testDevice,
 ) {
   const facts: RuntimeFacts<PlatformRuntimeOperations> = {
-    device: { ...deviceShape(testDevice), providerMode: 'local' },
+    device: { ...deviceShape(device), providerMode: 'local' },
     operations: { setFoldPose: fact } as RuntimeFacts<PlatformRuntimeOperations>['operations'],
   };
   const binding = {
-    device: testDevice,
+    device,
     owner: localRuntimeOwner('apple'),
     facts,
     operations: { setFoldPose },
@@ -162,6 +163,38 @@ test('rejects an unavailable exact-owner fact before binding', async () => {
   });
 });
 
+// The scoped-set refusal is a real route outcome, not just a narrowed binding: a scoped session's
+// `setFoldPose` fact refuses on admission, so the wire error carries the typed reason and the fact's
+// own hint, and the device is never bound or posed. The hint is a sentinel the route could never
+// compose, so the assertion proves propagation without re-typing production's wording.
+test('refuses a scoped simulator set on the route with the typed reason, never binding', async () => {
+  const scopedDevice: DeviceInfo = { ...testDevice, simulatorSetPath: '/tmp/scoped-set' };
+  const scopeRefusal = {
+    available: false,
+    reason: 'unsupported-device-scope',
+    hint: 'SCOPED-SET-HINT-SENTINEL',
+  } as const;
+  const harness = runtimeHarness(scopeRefusal, vi.fn(), scopedDevice);
+
+  const resolved = await resolveBoundFoldRuntime({
+    device: scopedDevice,
+    positionals: ['half-open'],
+    inspectFacts: harness.inspectFacts,
+    bindDevice: harness.bindDevice,
+  });
+
+  expect(resolved.ok).toBe(false);
+  if (resolved.ok || resolved.response.ok) throw new Error('the scoped-set fact admitted fold');
+  expect(resolved.response.error).toMatchObject({
+    code: 'UNSUPPORTED_OPERATION',
+    message: 'fold is not supported on this device',
+    hint: 'SCOPED-SET-HINT-SENTINEL',
+    details: { reason: 'unsupported-device-scope' },
+  });
+  expect(harness.bindDevice).not.toHaveBeenCalled();
+  expect(harness.setFoldPose).not.toHaveBeenCalled();
+});
+
 test('passes the validated timed intent to the admitted fold owner', async () => {
   const setFoldPose = vi.fn(async (): Promise<SetFoldPoseResult> => ({
     pose: 'half-open',
diff --git a/src/daemon/__tests__/keyboard-runtime.test.ts b/src/daemon/__tests__/keyboard-runtime.test.ts
index 2f76f4b2c9..dcd55296e0 100644
--- a/src/daemon/__tests__/keyboard-runtime.test.ts
+++ b/src/daemon/__tests__/keyboard-runtime.test.ts
@@ -195,6 +195,7 @@ test('android status is refused on iOS with the retired in-handler hint', async
         code: 'UNSUPPORTED_OPERATION',
         message: 'keyboard status is not supported on this device',
         hint: unavailable.hint,
+        details: { reason: unavailable.reason },
       },
     },
   });
diff --git a/src/daemon/__tests__/runtime-binding-conformance.ts b/src/daemon/__tests__/runtime-binding-conformance.ts
index 87d12bc1ee..bfc125365c 100644
--- a/src/daemon/__tests__/runtime-binding-conformance.ts
+++ b/src/daemon/__tests__/runtime-binding-conformance.ts
@@ -226,7 +226,7 @@ export async function refuseUnavailableExactOwnerFact(
   return resolved.response;
 }
 
-/** The wording `admitRuntimeOperations` gives every single-use route it refuses. */
+/** The wording and shape `admitRuntimeOperations` gives every single-use route it refuses. */
 function unsupportedOperationRefusal(
   command: ConformedRuntimeCommand,
   unavailable: RuntimeOperationUnavailability,
@@ -234,6 +234,7 @@ function unsupportedOperationRefusal(
   return {
     code: 'UNSUPPORTED_OPERATION',
     message: `${command} is not supported on this device`,
+    details: { reason: unavailable.reason },
     ...(unavailable.hint ? { hint: unavailable.hint } : {}),
   };
 }
diff --git a/src/daemon/runtime-admission.ts b/src/daemon/runtime-admission.ts
index 8c47cecb4c..a08b7b466d 100644
--- a/src/daemon/runtime-admission.ts
+++ b/src/daemon/runtime-admission.ts
@@ -42,6 +42,24 @@ export type RuntimeAdmissionRequest = RuntimeAdmissionBindings &
 
 export type { RuntimeAdmissionBindings };
 
+/**
+ * The one refusal the daemon reports when a device's exact runtime owner did not admit an
+ * operation. Both seams — this generic route and the request-scoped session handlers — build their
+ * `UNSUPPORTED_OPERATION` here, so the `<command> is not supported on this device` sentence, the
+ * typed `details.reason`, and the hint have a single owner and one wire shape.
+ */
+export function unsupportedOperationResponse(
+  command: string,
+  unavailable: RuntimeOperationUnavailability,
+): DaemonFailureResponse {
+  return errorResponse(
+    'UNSUPPORTED_OPERATION',
+    `${command} is not supported on this device`,
+    { reason: unavailable.reason },
+    unavailable.hint ? { hint: unavailable.hint } : undefined,
+  );
+}
+
 /**
  * The one facts-admission seam every migrated command route shares. It performs exactly one
  * side-effect-free inspection and hands back the binding gateway only once the exact device cell
@@ -57,12 +75,7 @@ export async function admitRuntimeOperations(
     if (fact.available) continue;
     const response = request.unavailableResponse
       ? request.unavailableResponse(fact)
-      : errorResponse(
-          'UNSUPPORTED_OPERATION',
-          `${request.command} is not supported on this device`,
-          undefined,
-          fact.hint ? { hint: fact.hint } : undefined,
-        );
+      : unsupportedOperationResponse(request.command, fact);
     return { type: 'response', response };
   }
   return { type: 'admitted', bind: requireDeviceBinding(request.bindDevice) };
diff --git a/src/daemon/session-runtime-admission.ts b/src/daemon/session-runtime-admission.ts
index 905891f2f5..3895c2f98b 100644
--- a/src/daemon/session-runtime-admission.ts
+++ b/src/daemon/session-runtime-admission.ts
@@ -8,7 +8,7 @@ import { AppError } from '@agent-device/kernel/errors';
 import type { BindDeviceRuntime, InspectDeviceRuntimeFacts } from './request-runtime-binding.ts';
 import type { SessionStore } from './session-store.ts';
 import type { DaemonRequest, DaemonResponse } from './daemon-request.ts';
-import { errorResponse } from '@agent-device/kernel/contracts';
+import { unsupportedOperationResponse } from './runtime-admission.ts';
 
 export type RuntimeCommandHandlerParams = Readonly<{
   req: DaemonRequest;
@@ -18,18 +18,16 @@ export type RuntimeCommandHandlerParams = Readonly<{
   bindDevice?: BindDeviceRuntime;
 }>;
 
-/** Shared facts-first admission for request-scoped runtime command handlers. */
+/**
+ * Shared facts-first admission for request-scoped runtime command handlers. Availability is the
+ * only thing decided here; the refusal wording, `details.reason`, and hint come from the same
+ * `unsupportedOperationResponse` the generic route uses, so both seams keep one wire shape.
+ */
 export function unavailableRuntimeOperationResponse(
   command: string,
   fact: RuntimeOperationFact,
 ): DaemonResponse | undefined {
-  if (fact.available) return undefined;
-  return errorResponse(
-    'UNSUPPORTED_OPERATION',
-    `${command} is not supported on this device`,
-    { reason: fact.reason },
-    fact.hint ? { hint: fact.hint } : undefined,
-  );
+  return fact.available ? undefined : unsupportedOperationResponse(command, fact);
 }
 
 export function requireRuntimeFacts(
diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md
index e470e55ce3..e5b2974062 100644
--- a/website/docs/docs/commands.md
+++ b/website/docs/docs/commands.md
@@ -93,6 +93,7 @@ agent-device fold open
 - `fold <closed|half-open|open>` puts a foldable iPhone simulator (iPhone Duo) into a hinge pose. The command sends a private HID hinge event inside the selected simulator (ADR 0025), then reads the hinge angle back with `devicectl device motion hinge-angle` and reports the pose only when that reading agrees: `closed` is 0°, `open` is 180°, and `half-open` is any angle between them (requested at 130°). An angle inside that interval only proves the category, so `half-open` is reported once two consecutive readings both fall inside it and agree within 0.5°. The response names the panel the device now lights and its native panel point size, marked `coordinateSpace: "native-panel"`; that size is the panel's own geometry, not the next snapshot's viewport (a 669x951 inner panel can host a 951x669 app window), so it cannot place a tap. Re-snapshot afterwards, and never carry refs or coordinates across a `fold`. After that snapshot, taps, long presses, and scrolling follow the app window on the active panel in closed, half-open, and open poses.
 - For timed motion, use `fold --keyframes '[{"atMs":0,"angle":0},{"atMs":1667,"angle":160},{"atMs":3333,"angle":100},{"atMs":5000,"angle":180}]'`. This runs the opening/reversal/reopening sequence over five seconds. Supply either a preset or keyframes, never both. Use 2–64 keyframes starting at 0ms with strictly increasing integer timestamps up to 60,000ms and finite angles in 0–180°. Linear interpolation runs at roughly 60Hz; equal consecutive angles hold the hinge. Motion duration excludes preparation and final-angle verification. Cancellation stops at the current angle; re-snapshot even after an interrupted trajectory.
 - `fold` is simulator-only and requires an Xcode toolchain with the iOS simulator SDK and foldable HID support (verified on Xcode 27.1). It runs a helper against the session UDID; the helper is built once per `Fold.m` source hash and Xcode toolchain, cached under `~/.agent-device/fold-helper`, and rebuilt only when the source or the toolchain changes. Device Hub and host Accessibility permission are not required. Build failures report `fold-helper-build-failed`; dispatch failures report `fold-hid-dispatch-failed`. There is no UI fallback. Single-panel simulators and physical devices are refused.
+- A simulator scoped to a non-default set with `--ios-simulator-device-set` is refused before any hinge is touched with `UNSUPPORTED_OPERATION` and `details.reason: "unsupported-device-scope"`. The HID send accepts `--set`, but `devicectl device info displays` and `devicectl device motion hinge-angle` accept only `--device` and resolve a scoped simulator as not found, so the pose could not be read back (ADR 0025). Run `fold` against a simulator in the default set.
 - `fold` costs one bounded hinge stream per read, and devicectl's smallest stream is five seconds: `closed` and `open` take about ten seconds, `half-open` about sixteen, because the hinge animates and the command waits for it to stop. A hinge whose last reading is some other pose fails with `COMMAND_FAILED` and `reason: fold-pose-unverified`, naming the angle CoreDevice still reports. A hinge seen `half-open` but never at rest fails with `reason: fold-pose-unsettled`, naming the observed and previous angles: the requested category was observed, and what is missing is a pose the hinge holds (#2730).
 - `action-button` is not a cheap command to loop. On an iPhone 17 Pro Simulator the press itself spent about five seconds inside XCUITest, while `home` and `app-switcher` on the same session took under two seconds each.
 - On iOS devices, `http(s)://` URLs open in Safari when no app is active. Custom scheme URLs require an active app in the session.

From a363a0239cbd8e2811b22a2d45eebb9ddc3883b3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 24 Sep 2026 15:52:10 +0200
Subject: [PATCH 094/132] refactor(ios): make unscoped simctl argv a type error
 at the Apple tool port (#2898)

* refactor(platform-apple): take simctl set scope from the device record

Brand scoped simctl argv in contracts (ScopedSimctlArgs) so the Apple
tool port and the provider simctl executor refuse raw argv. Mint a
SimulatorAddress from a DeviceInfo, make the set-scope builder take an
explicit scope, and delete buildSimctlArgs.

Move the log-stream and AX bridge spawns off the set-scope builder:
the log stream takes the set from its DeviceInfo, and the snapshot
target carries a SimulatorAddress in place of udid and simulatorSetPath.
Doctor keeps set scope for 'simctl help'. No argv changes.

Refs #2878

* test(platform-apple): pin scoped-set simctl argv for doctor, log stream and network recovery

Refs #2878

* chore(gates): add R79 apple-simulator-scope layering rule

Refuse hand-built 'simctl' argv arrays, a '--set' literal, casts that
forge ScopedSimctlArgs or SimulatorAddress, and any reference to the
set-scope builder outside its owners (core/simctl.ts,
simulator-inventory.ts, logs/doctor.ts).

Refs #2878
---
 .../contracts/src/network-runtime.test.ts     |   1 +
 .../contracts/src/platform-runtime-host.ts    |  15 +-
 .../__tests__/app-launch-device-open.test.ts  |   2 +-
 .../core/__tests__/screenshot-density.test.ts |   4 +-
 .../src/core/__tests__/simctl.test.ts         |  38 ++++-
 .../src/core/__tests__/tool-provider.test.ts  |   9 +-
 packages/platform-apple/src/core/simctl.ts    |  50 ++++--
 .../src/core/tool-provider-types.ts           |   5 +
 .../platform-apple/src/core/tool-provider.ts  |  11 +-
 .../platform-apple/src/deployment/runtime.ts  |   2 +-
 .../platform-apple/src/logs/doctor.test.ts    |  15 ++
 packages/platform-apple/src/logs/doctor.ts    |   3 +-
 .../src/logs/log-predicate.test.ts            |  17 ++-
 .../platform-apple/src/logs/log-predicate.ts  |  40 +++--
 .../platform-apple/src/logs/start.test.ts     |  36 +++++
 packages/platform-apple/src/logs/start.ts     |   7 +-
 .../src/network/runtime.test.ts               |  39 +++++
 .../platform-apple/src/network/runtime.ts     |   6 +-
 .../platform-apple/src/simulator-inventory.ts |   3 +-
 .../src/snapshot-observability.test.ts        |   3 +-
 .../platform-apple/src/snapshot-route.test.ts |   9 +-
 packages/platform-apple/src/snapshot-route.ts |   4 +-
 .../src/snapshot-source/adapter.test.ts       |  18 ++-
 .../src/snapshot-source/adapter.ts            |   2 +-
 .../src/snapshot-source/host.test.ts          |  10 +-
 .../src/snapshot-source/host.ts               |  36 ++---
 .../src/snapshot-source/lifecycle.test.ts     |  27 +++-
 .../src/snapshot-source/lifecycle.ts          |  16 +-
 .../src/snapshot-source/types.ts              |   7 +-
 .../src/snapshot-target.test.ts               |  10 +-
 .../platform-apple/src/snapshot-target.ts     |  13 +-
 .../apple-simulator-scope-policy.test.ts      | 143 ++++++++++++++++++
 .../layering/apple-simulator-scope-policy.ts  | 128 ++++++++++++++++
 scripts/layering/check.ts                     |   6 +
 .../request-platform-providers.test.ts        |   2 +-
 .../provider-scenarios/providers.ts           |   8 +-
 36 files changed, 609 insertions(+), 136 deletions(-)
 create mode 100644 scripts/layering/apple-simulator-scope-policy.test.ts
 create mode 100644 scripts/layering/apple-simulator-scope-policy.ts

diff --git a/packages/contracts/src/network-runtime.test.ts b/packages/contracts/src/network-runtime.test.ts
index f7f020a194..afd7e9a53c 100644
--- a/packages/contracts/src/network-runtime.test.ts
+++ b/packages/contracts/src/network-runtime.test.ts
@@ -21,6 +21,7 @@ function compileTimeNetworkProjectionProof(
 void compileTimeNetworkProjectionProof;
 
 function compileTimeCanonicalHostProof(host: NetworkRuntimeHost): void {
+  // @ts-expect-error Raw simctl argv cannot cross the Apple tool port; scope it in platform-apple.
   void host.appleTools.run({ tool: 'simctl', args: ['spawn', 'sim-1', 'log', 'show'] });
   void host.appleTools.run({
     tool: 'simctl',
diff --git a/packages/contracts/src/platform-runtime-host.ts b/packages/contracts/src/platform-runtime-host.ts
index ea81f0a762..e5f9450b64 100644
--- a/packages/contracts/src/platform-runtime-host.ts
+++ b/packages/contracts/src/platform-runtime-host.ts
@@ -55,12 +55,15 @@ export type HostCommandRunner = Readonly<{
 
 export type AppleXcrunTool = 'simctl' | 'devicectl' | 'xctrace';
 
-export type AppleToolRequest = Readonly<{
-  tool: AppleXcrunTool;
-  args: readonly string[];
-  timeoutMs?: number;
-  allowFailure?: boolean;
-}>;
+declare const scopedSimctlArgs: unique symbol;
+/** simctl argv (after the tool name) already scoped to its simulator set; minted only by platform-apple. */
+export type ScopedSimctlArgs = readonly string[] & { readonly [scopedSimctlArgs]: true };
+
+export type AppleToolRequest = Readonly<{ timeoutMs?: number; allowFailure?: boolean }> &
+  (
+    | Readonly<{ tool: 'simctl'; args: ScopedSimctlArgs }>
+    | Readonly<{ tool: Exclude<AppleXcrunTool, 'simctl'>; args: readonly string[] }>
+  );
 
 /** Request-bound foreground Apple tooling backed by the selected scoped provider. */
 export type AppleToolHost = Readonly<{
diff --git a/packages/platform-apple/src/core/__tests__/app-launch-device-open.test.ts b/packages/platform-apple/src/core/__tests__/app-launch-device-open.test.ts
index 3af9ddbc09..de2e6dac11 100644
--- a/packages/platform-apple/src/core/__tests__/app-launch-device-open.test.ts
+++ b/packages/platform-apple/src/core/__tests__/app-launch-device-open.test.ts
@@ -64,7 +64,7 @@ test('openIosDevice leaves the macOS desktop target alone', async () => {
   const provider = createLocalAppleToolProvider({
     simctl: {
       run: async (args) => {
-        simctlCalls.push(args);
+        simctlCalls.push([...args]);
         return { exitCode: 0, stdout: '', stderr: '' };
       },
     },
diff --git a/packages/platform-apple/src/core/__tests__/screenshot-density.test.ts b/packages/platform-apple/src/core/__tests__/screenshot-density.test.ts
index ccda003702..b1b8dfdd1a 100644
--- a/packages/platform-apple/src/core/__tests__/screenshot-density.test.ts
+++ b/packages/platform-apple/src/core/__tests__/screenshot-density.test.ts
@@ -8,7 +8,7 @@ import { screenshotIos } from '../screenshot.ts';
 import { createLocalAppleToolProvider, withAppleToolProvider } from '../tool-provider.ts';
 import { mkdtempForTest } from '../../__tests__/tmp-dir.ts';
 
-function startsWithArgs(args: string[], expected: string[]): boolean {
+function startsWithArgs(args: readonly string[], expected: string[]): boolean {
   return expected.every((value, index) => args[index] === value);
 }
 
@@ -29,7 +29,7 @@ test('screenshotIos caches simulator screen scale per device', async () => {
   const provider = createLocalAppleToolProvider({
     simctl: {
       run: async (args) => {
-        calls.push(args);
+        calls.push([...args]);
         if (startsWithArgs(args, ['getenv', device.id, 'SIMULATOR_MAINSCREEN_SCALE'])) {
           return { exitCode: 0, stdout: '3\n', stderr: '' };
         }
diff --git a/packages/platform-apple/src/core/__tests__/simctl.test.ts b/packages/platform-apple/src/core/__tests__/simctl.test.ts
index 1845a402c0..d24f1ce197 100644
--- a/packages/platform-apple/src/core/__tests__/simctl.test.ts
+++ b/packages/platform-apple/src/core/__tests__/simctl.test.ts
@@ -1,12 +1,14 @@
 import { test } from 'vitest';
 import assert from 'node:assert/strict';
 import {
-  buildSimctlArgs,
+  buildSimctlArgsForAddress,
   buildSimctlArgsForDevice,
   readSimctlDevicesByRuntime,
   readSimctlDeviceState,
   scopeSimctlArgs,
   scopeSimctlArgsForDevice,
+  simulatorAddressFor,
+  type SimulatorAddress,
 } from '../simctl.ts';
 import type { DeviceInfo } from '@agent-device/kernel/device';
 
@@ -18,10 +20,11 @@ const IOS_SIMULATOR: DeviceInfo = {
   target: 'mobile',
 };
 
-test('buildSimctlArgs uses --set when simulator set path is provided', () => {
-  const args = buildSimctlArgs(['list', 'devices', '-j'], {
-    simulatorSetPath: '/tmp/tenant-a/simulator-set',
-  });
+test('buildSimctlArgsForAddress uses --set when the address names a simulator set', () => {
+  const args = buildSimctlArgsForAddress(
+    simulatorAddressFor({ ...IOS_SIMULATOR, simulatorSetPath: '/tmp/tenant-a/simulator-set' }),
+    ['list', 'devices', '-j'],
+  );
   assert.deepEqual(args, [
     'simctl',
     '--set',
@@ -85,6 +88,31 @@ test('scopeSimctlArgsForDevice scopes simulators only', () => {
   ]);
 });
 
+test('simulatorAddressFor carries the set of iOS-family simulators only', () => {
+  const scoped = { ...IOS_SIMULATOR, simulatorSetPath: '/tmp/tenant-d/simulator-set' };
+  assert.deepEqual(simulatorAddressFor(scoped), {
+    udid: 'sim-1',
+    simulatorSetPath: '/tmp/tenant-d/simulator-set',
+  });
+  assert.deepEqual(simulatorAddressFor({ ...scoped, kind: 'device' }), {
+    udid: 'sim-1',
+    simulatorSetPath: undefined,
+  });
+  assert.deepEqual(simulatorAddressFor({ ...scoped, platform: 'android', kind: 'emulator' }), {
+    udid: 'sim-1',
+    simulatorSetPath: undefined,
+  });
+});
+
+function compileTimeSimulatorScopeProof(): void {
+  // @ts-expect-error A set-scope call states its set; leaving it out does not mean the default set.
+  void scopeSimctlArgs(['list']);
+  // @ts-expect-error A simulator address is minted from its DeviceInfo, never written by hand.
+  const forged: SimulatorAddress = { udid: 'sim-1', simulatorSetPath: undefined };
+  void forged;
+}
+void compileTimeSimulatorScopeProof;
+
 const LISTING = JSON.stringify({
   devices: {
     'com.apple.CoreSimulator.SimRuntime.iOS-18-0': [
diff --git a/packages/platform-apple/src/core/__tests__/tool-provider.test.ts b/packages/platform-apple/src/core/__tests__/tool-provider.test.ts
index 70e21fa415..43584b19f9 100644
--- a/packages/platform-apple/src/core/__tests__/tool-provider.test.ts
+++ b/packages/platform-apple/src/core/__tests__/tool-provider.test.ts
@@ -3,11 +3,18 @@ import { test } from 'vitest';
 import {
   createLocalAppleToolProvider,
   readApplePlistJson,
+  resolveAppleToolProvider,
   runAppleToolCommand,
   runXcrun,
   withAppleToolProvider,
 } from '../tool-provider.ts';
 
+function compileTimeScopedSimctlProof(): void {
+  // @ts-expect-error Raw simctl argv cannot reach the provider; scope it in core/simctl.ts.
+  void resolveAppleToolProvider().simctl.run(['spawn', 'sim-1', 'bridge']);
+}
+void compileTimeScopedSimctlProof;
+
 test('scoped Apple tool provider handles xcrun execution', async () => {
   const calls: Array<[string, string[]]> = [];
   const provider = createLocalAppleToolProvider({
@@ -35,7 +42,7 @@ test('scoped Apple tool provider prefers semantic simctl and devicectl hooks', a
     },
     simctl: {
       run: async (args) => {
-        calls.push(['simctl', args]);
+        calls.push(['simctl', [...args]]);
         return { exitCode: 0, stdout: 'simctl', stderr: '' };
       },
     },
diff --git a/packages/platform-apple/src/core/simctl.ts b/packages/platform-apple/src/core/simctl.ts
index b47011bcdd..eddb2d7933 100644
--- a/packages/platform-apple/src/core/simctl.ts
+++ b/packages/platform-apple/src/core/simctl.ts
@@ -1,33 +1,55 @@
 import { isIosFamily, type DeviceInfo } from '@agent-device/kernel/device';
 import { type ExecOptions, type ExecResult } from '@agent-device/host-kit/command';
 import { resolveIosSimulatorDeviceSetPath } from '@agent-device/kernel/device-isolation';
+import type { ScopedSimctlArgs } from '@agent-device/contracts/platform-runtime-host';
 import { runXcrun } from './tool-provider.ts';
 
-type SimctlArgsOptions = {
-  simulatorSetPath?: string;
+/** The set of a simctl call that names no device; `undefined` names the default set on purpose. */
+export type SimulatorSetScope = Readonly<{ simulatorSetPath: string | undefined }>;
+
+declare const simulatorAddress: unique symbol;
+/** A simulator udid with the set that holds it; minted only from a DeviceInfo. */
+export type SimulatorAddress = Readonly<{ udid: string; simulatorSetPath: string | undefined }> & {
+  readonly [simulatorAddress]: true;
 };
 
-/** Arguments that follow the `simctl` tool name, scoped to the simulator set when one is given. */
+export function simulatorAddressFor(device: DeviceInfo): SimulatorAddress {
+  const simulatorSetPath =
+    isIosFamily(device) && device.kind === 'simulator' ? device.simulatorSetPath : undefined;
+  return Object.freeze({ udid: device.id, simulatorSetPath }) as SimulatorAddress;
+}
+
+/** Arguments that follow the `simctl` tool name for a call that names no device. */
 export function scopeSimctlArgs(
   args: readonly string[],
-  options: SimctlArgsOptions = {},
-): string[] {
-  const simulatorSetPath = resolveIosSimulatorDeviceSetPath(options.simulatorSetPath);
-  if (!simulatorSetPath) return [...args];
-  return ['--set', simulatorSetPath, ...args];
+  scope: SimulatorSetScope,
+): ScopedSimctlArgs {
+  const simulatorSetPath = resolveIosSimulatorDeviceSetPath(scope.simulatorSetPath);
+  const scoped = simulatorSetPath ? ['--set', simulatorSetPath, ...args] : [...args];
+  return Object.freeze(scoped) as ScopedSimctlArgs;
+}
+
+/** Arguments that follow the `simctl` tool name, scoped to the set holding the addressed simulator. */
+export function scopeSimctlArgsForAddress(
+  address: SimulatorAddress,
+  args: readonly string[],
+): ScopedSimctlArgs {
+  return scopeSimctlArgs(args, { simulatorSetPath: address.simulatorSetPath });
 }
 
 /** Arguments that follow the `simctl` tool name, scoped to the simulator set holding the device. */
-export function scopeSimctlArgsForDevice(device: DeviceInfo, args: readonly string[]): string[] {
-  if (!isIosFamily(device) || device.kind !== 'simulator') return [...args];
-  return scopeSimctlArgs(args, { simulatorSetPath: device.simulatorSetPath });
+export function scopeSimctlArgsForDevice(
+  device: DeviceInfo,
+  args: readonly string[],
+): ScopedSimctlArgs {
+  return scopeSimctlArgsForAddress(simulatorAddressFor(device), args);
 }
 
-export function buildSimctlArgs(
+export function buildSimctlArgsForAddress(
+  address: SimulatorAddress,
   args: readonly string[],
-  options: SimctlArgsOptions = {},
 ): string[] {
-  return ['simctl', ...scopeSimctlArgs(args, options)];
+  return ['simctl', ...scopeSimctlArgsForAddress(address, args)];
 }
 
 export function buildSimctlArgsForDevice(device: DeviceInfo, args: readonly string[]): string[] {
diff --git a/packages/platform-apple/src/core/tool-provider-types.ts b/packages/platform-apple/src/core/tool-provider-types.ts
index 51892efa5e..c7458d3edc 100644
--- a/packages/platform-apple/src/core/tool-provider-types.ts
+++ b/packages/platform-apple/src/core/tool-provider-types.ts
@@ -1,4 +1,5 @@
 import type { AppsFilter } from '@agent-device/contracts/device';
+import type { ScopedSimctlArgs } from '@agent-device/contracts/platform-runtime-host';
 import { type ExecOptions, type ExecResult } from '@agent-device/host-kit/command';
 import type { IosAppInfo } from './app-info.ts';
 
@@ -19,6 +20,10 @@ export type AppleXcrunToolProvider = {
   run: AppleToolSubcommandExecutor;
 };
 
+export type AppleSimctlToolProvider = {
+  run: (args: ScopedSimctlArgs, options?: ExecOptions) => Promise<ExecResult>;
+};
+
 export type AppleMacOsHelperProvider = {
   run: AppleToolSubcommandExecutor;
 };
diff --git a/packages/platform-apple/src/core/tool-provider.ts b/packages/platform-apple/src/core/tool-provider.ts
index 02d3190073..1850f4abef 100644
--- a/packages/platform-apple/src/core/tool-provider.ts
+++ b/packages/platform-apple/src/core/tool-provider.ts
@@ -5,15 +5,16 @@ import {
   type ExecOptions,
   type ExecResult,
 } from '@agent-device/host-kit/command';
+import type { ScopedSimctlArgs } from '@agent-device/contracts/platform-runtime-host';
 import { createScopedProvider } from '@agent-device/kernel/scoped-provider';
 import { createLocalAppleMacOsHostProvider } from '../os/macos/host-provider.ts';
 import type {
   AppleMacOsHelperProvider,
   AppleMacOsHostProvider,
   ApplePlistProvider,
+  AppleSimctlToolProvider,
   AppleToolAvailabilityChecker,
   AppleToolCommandExecutor,
-  AppleToolSubcommandExecutor,
   AppleXcrunToolProvider,
 } from './tool-provider-types.ts';
 
@@ -29,7 +30,7 @@ export type {
 
 export type AppleToolProvider = {
   runCommand: AppleToolCommandExecutor;
-  simctl: AppleXcrunToolProvider;
+  simctl: AppleSimctlToolProvider;
   devicectl: AppleXcrunToolProvider;
   macosHelper?: AppleMacOsHelperProvider;
   macosHost?: AppleMacOsHostProvider;
@@ -118,7 +119,7 @@ export async function runXcrun(args: string[], options?: ExecOptions): Promise<E
   const provider = resolveAppleToolProvider();
   const [tool, ...toolArgs] = args;
   if (tool === 'simctl') {
-    return await provider.simctl.run(toolArgs, options);
+    return await provider.simctl.run(toolArgs as unknown as ScopedSimctlArgs, options);
   }
   if (tool === 'devicectl') {
     return await provider.devicectl.run(toolArgs, options);
@@ -149,7 +150,9 @@ function coerceRunCommand(run: AppleToolCommandExecutor): AppleToolCommandExecut
   return async (cmd, args, options) => coerceExecResult(await run(cmd, args, options));
 }
 
-function coerceRun(run: AppleToolSubcommandExecutor): AppleToolSubcommandExecutor {
+function coerceRun<Args>(
+  run: (args: Args, options?: ExecOptions) => Promise<ExecResult>,
+): (args: Args, options?: ExecOptions) => Promise<ExecResult> {
   return async (args, options) => coerceExecResult(await run(args, options));
 }
 
diff --git a/packages/platform-apple/src/deployment/runtime.ts b/packages/platform-apple/src/deployment/runtime.ts
index 65f9d27973..22dd945e4a 100644
--- a/packages/platform-apple/src/deployment/runtime.ts
+++ b/packages/platform-apple/src/deployment/runtime.ts
@@ -228,7 +228,7 @@ async function pushAppleNotification(
  */
 async function runAppleTool(
   host: PlatformRuntimeHost,
-  request: Omit<AppleToolRequest, 'allowFailure'>,
+  request: AppleToolRequest,
   signal: AbortSignal,
   message: string,
   options?: Readonly<{ tolerate?: (result: HostCommandResult) => boolean }>,
diff --git a/packages/platform-apple/src/logs/doctor.test.ts b/packages/platform-apple/src/logs/doctor.test.ts
index e07a0ebf8d..f9747bc00b 100644
--- a/packages/platform-apple/src/logs/doctor.test.ts
+++ b/packages/platform-apple/src/logs/doctor.test.ts
@@ -21,6 +21,21 @@ test('simulator doctor routes the exact simctl probe through appleTools', async
   );
 });
 
+test('simulator doctor probes simctl without a set, even for a scoped-set simulator', async () => {
+  const appleToolRun = vi.fn(async () => ({ stdout: 'simctl help', stderr: '', exitCode: 0 }));
+  const fixture = hostFixture({ appleToolRun });
+
+  await doctorAppleAppLogs(
+    fixture.host,
+    appleDevice({ simulatorSetPath: '/tmp/scoped-set' }),
+    'com.example.app',
+  );
+  expect(appleToolRun).toHaveBeenCalledWith(
+    { tool: 'simctl', args: ['help'], allowFailure: true },
+    undefined,
+  );
+});
+
 test('CoreDevice doctor routes version discovery through appleTools', async () => {
   const appleToolRun = vi.fn(async (request) => ({
     stdout: request.args.includes('--help')
diff --git a/packages/platform-apple/src/logs/doctor.ts b/packages/platform-apple/src/logs/doctor.ts
index e163e607e8..2414566351 100644
--- a/packages/platform-apple/src/logs/doctor.ts
+++ b/packages/platform-apple/src/logs/doctor.ts
@@ -1,6 +1,7 @@
 import { isMacOs, type DeviceInfo } from '@agent-device/kernel/device';
 import type { AppLogRuntimeHost } from '@agent-device/contracts/app-log-runtime';
 import { appLogCommandSucceeded, bestEffortAppLogCheck } from '@agent-device/capture-kit';
+import { scopeSimctlArgs } from '../core/simctl.ts';
 import { APPLE_XCTEST_LOGS_HINT, backendForAppleDevice } from './backend.ts';
 import {
   checkCoreDeviceConsoleCaptureSupport,
@@ -27,7 +28,7 @@ export async function doctorAppleAppLogs(
           await host.appleTools.run(
             {
               tool: 'simctl',
-              args: ['help'],
+              args: scopeSimctlArgs(['help'], { simulatorSetPath: undefined }),
               allowFailure: true,
             },
             signal,
diff --git a/packages/platform-apple/src/logs/log-predicate.test.ts b/packages/platform-apple/src/logs/log-predicate.test.ts
index 8c3d607326..3633066f03 100644
--- a/packages/platform-apple/src/logs/log-predicate.test.ts
+++ b/packages/platform-apple/src/logs/log-predicate.test.ts
@@ -18,12 +18,17 @@ test('Apple app-log predicate covers bundle and executable provenance', () => {
 
 test('Apple app-log arguments preserve simulator-set and CoreDevice launch semantics', () => {
   assert.deepEqual(
-    buildIosSimulatorLogStreamArgs({
-      deviceId: 'sim-1',
-      appBundleId: 'com.example.app',
-      executableName: 'ExampleExec',
-      simulatorSetPath: '/tmp/tenant-a/simulators',
-    }),
+    buildIosSimulatorLogStreamArgs(
+      {
+        platform: 'apple',
+        id: 'sim-1',
+        name: 'iPhone 17',
+        kind: 'simulator',
+        target: 'mobile',
+        simulatorSetPath: '/tmp/tenant-a/simulators',
+      },
+      { appBundleId: 'com.example.app', executableName: 'ExampleExec' },
+    ),
     [
       'simctl',
       '--set',
diff --git a/packages/platform-apple/src/logs/log-predicate.ts b/packages/platform-apple/src/logs/log-predicate.ts
index 4fa3e598de..15893d2f2b 100644
--- a/packages/platform-apple/src/logs/log-predicate.ts
+++ b/packages/platform-apple/src/logs/log-predicate.ts
@@ -1,4 +1,5 @@
-import { buildSimctlArgs } from '../core/simctl.ts';
+import type { DeviceInfo } from '@agent-device/kernel/device';
+import { buildSimctlArgsForDevice } from '../core/simctl.ts';
 
 export function buildAppleLogPredicate(appBundleId: string, executableName?: string): string {
   const escapedBundleId = escapePredicateString(appBundleId);
@@ -21,27 +22,22 @@ export function buildAppleLogPredicate(appBundleId: string, executableName?: str
   return clauses.join(' OR ');
 }
 
-export function buildIosSimulatorLogStreamArgs(params: {
-  deviceId: string;
-  appBundleId: string;
-  executableName?: string;
-  simulatorSetPath?: string;
-}): string[] {
-  return buildSimctlArgs(
-    [
-      'spawn',
-      params.deviceId,
-      'log',
-      'stream',
-      '--style',
-      'compact',
-      '--level',
-      'info',
-      '--predicate',
-      buildAppleLogPredicate(params.appBundleId, params.executableName),
-    ],
-    { simulatorSetPath: params.simulatorSetPath },
-  );
+export function buildIosSimulatorLogStreamArgs(
+  device: DeviceInfo,
+  params: { appBundleId: string; executableName?: string },
+): string[] {
+  return buildSimctlArgsForDevice(device, [
+    'spawn',
+    device.id,
+    'log',
+    'stream',
+    '--style',
+    'compact',
+    '--level',
+    'info',
+    '--predicate',
+    buildAppleLogPredicate(params.appBundleId, params.executableName),
+  ]);
 }
 
 export function buildIosDeviceConsoleLaunchArgs(deviceId: string, appBundleId: string): string[] {
diff --git a/packages/platform-apple/src/logs/start.test.ts b/packages/platform-apple/src/logs/start.test.ts
index 78b4f8ad4f..835cf866a7 100644
--- a/packages/platform-apple/src/logs/start.test.ts
+++ b/packages/platform-apple/src/logs/start.test.ts
@@ -55,3 +55,39 @@ test('simulator start resolves its app container through appleTools and keeps pl
     'log',
   ]);
 });
+
+test('simulator log stream takes the set of the device it streams from', async () => {
+  const appleToolRun = vi.fn(async () => ({ stdout: '', stderr: '', exitCode: 1 }));
+  const fixture = hostFixture({ appleToolRun, failProcessStart: true });
+
+  await expect(
+    startAppleAppLogs(
+      fixture.host,
+      appleDevice({ simulatorSetPath: '/tmp/scoped-set' }),
+      {
+        sessionId: 'session',
+        appBundleId: 'com.example.app',
+        outputPath: '/tmp/app.log',
+        fence: { token: 'fence', generation: 1 },
+      },
+      localRuntimeOwner('apple'),
+    ),
+  ).rejects.toThrow('start failed');
+
+  expect(appleToolRun).toHaveBeenCalledWith(
+    expect.objectContaining({
+      args: ['--set', '/tmp/scoped-set', 'get_app_container', 'apple-1', 'com.example.app', 'app'],
+    }),
+    undefined,
+  );
+  expect(fixture.backgroundCommands[0]?.slice(0, 8)).toEqual([
+    'xcrun',
+    'simctl',
+    '--set',
+    '/tmp/scoped-set',
+    'spawn',
+    'apple-1',
+    'log',
+    'stream',
+  ]);
+});
diff --git a/packages/platform-apple/src/logs/start.ts b/packages/platform-apple/src/logs/start.ts
index a25b3a67e8..4c41375636 100644
--- a/packages/platform-apple/src/logs/start.ts
+++ b/packages/platform-apple/src/logs/start.ts
@@ -159,12 +159,7 @@ async function commandForAppleAppLogs(
   const executableName = await resolveSimulatorExecutable(host, device, appBundleId, signal);
   return {
     executable: 'xcrun',
-    args: buildIosSimulatorLogStreamArgs({
-      deviceId: device.id,
-      appBundleId,
-      executableName,
-      simulatorSetPath: device.simulatorSetPath,
-    }),
+    args: buildIosSimulatorLogStreamArgs(device, { appBundleId, executableName }),
     allowFailure: true,
   } as const;
 }
diff --git a/packages/platform-apple/src/network/runtime.test.ts b/packages/platform-apple/src/network/runtime.test.ts
index 2a88f22125..176e943715 100644
--- a/packages/platform-apple/src/network/runtime.test.ts
+++ b/packages/platform-apple/src/network/runtime.test.ts
@@ -48,6 +48,45 @@ test('recovers an empty iOS simulator dump from bounded simctl log history', asy
   );
 });
 
+test.each([
+  ['a session start', { state: 'active', startedAt: 1_000 } as const, ['--start', '@1']],
+  ['no session start', undefined, ['--last', '5m']],
+])(
+  'scopes the whole log-show argv of a scoped-set simulator after %s',
+  async (_label, snapshot, window) => {
+    const runSimctl = vi.fn(async () => ({ stdout: '', stderr: '', exitCode: 0 }));
+    await dumpAppleNetworkTraffic(
+      host({ runSimctl }),
+      { ...simulator, simulatorSetPath: '/tmp/scoped-set' },
+      input(snapshot ? { appLogSnapshot: snapshot } : {}),
+      new AbortController().signal,
+    );
+
+    expect(runSimctl).toHaveBeenCalledWith(
+      {
+        tool: 'simctl',
+        args: [
+          '--set',
+          '/tmp/scoped-set',
+          'spawn',
+          'sim-1',
+          'log',
+          'show',
+          '--style',
+          'compact',
+          '--info',
+          '--predicate',
+          expect.any(String),
+          ...window,
+        ],
+        allowFailure: true,
+        timeoutMs: 4_000,
+      },
+      expect.any(AbortSignal),
+    );
+  },
+);
+
 test('preserves the simulator no-HTTP explanation after recovery returns app lines', async () => {
   const result = await dumpAppleNetworkTraffic(
     host({
diff --git a/packages/platform-apple/src/network/runtime.ts b/packages/platform-apple/src/network/runtime.ts
index cc9b021c89..0cb43d331c 100644
--- a/packages/platform-apple/src/network/runtime.ts
+++ b/packages/platform-apple/src/network/runtime.ts
@@ -89,6 +89,7 @@ async function recoverSimulatorTraffic(
   appLogPath: string,
   signal: AbortSignal,
 ): Promise<{ scan: NetworkScan; lineCount: number } | undefined> {
+  const startedAt = input.appLogSnapshot?.startedAt;
   const args = scopeSimctlArgsForDevice(device, [
     'spawn',
     device.id,
@@ -99,13 +100,10 @@ async function recoverSimulatorTraffic(
     '--info',
     '--predicate',
     buildPredicate(input.appBundleId as string),
-  ]);
-  const startedAt = input.appLogSnapshot?.startedAt;
-  args.push(
     ...(typeof startedAt === 'number' && Number.isFinite(startedAt) && startedAt > 0
       ? ['--start', `@${Math.floor(startedAt / 1000)}`]
       : ['--last', '5m']),
-  );
+  ]);
   const result = await host.appleTools.run(
     { tool: 'simctl', args, allowFailure: true, timeoutMs: 4_000 },
     signal,
diff --git a/packages/platform-apple/src/simulator-inventory.ts b/packages/platform-apple/src/simulator-inventory.ts
index 05d316a207..dcdc03147e 100644
--- a/packages/platform-apple/src/simulator-inventory.ts
+++ b/packages/platform-apple/src/simulator-inventory.ts
@@ -2,6 +2,7 @@ import type { DeviceInventoryRequest } from '@agent-device/contracts/device';
 import type {
   DeviceInventoryHostFor,
   PlatformRequestScope,
+  ScopedSimctlArgs,
 } from '@agent-device/contracts/platform-runtime-host';
 import { sortAppleDevicesForSelection, type DeviceInfo } from '@agent-device/kernel/device';
 import { AppError } from '@agent-device/kernel/errors';
@@ -26,7 +27,7 @@ type SimctlListDevicesPayload = {
 
 const BOOTED_SIMULATOR_PROBE_TIMEOUT_MS = 3_000;
 
-export function buildSimctlListArgs(simulatorSetPath: string | undefined): string[] {
+export function buildSimctlListArgs(simulatorSetPath: string | undefined): ScopedSimctlArgs {
   return scopeSimctlArgs(['list', 'devices', '-j'], { simulatorSetPath });
 }
 
diff --git a/packages/platform-apple/src/snapshot-observability.test.ts b/packages/platform-apple/src/snapshot-observability.test.ts
index d107e33ce5..3459948d7a 100644
--- a/packages/platform-apple/src/snapshot-observability.test.ts
+++ b/packages/platform-apple/src/snapshot-observability.test.ts
@@ -5,6 +5,7 @@ import {
 } from '@agent-device/host-kit/diagnostics';
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import { AppError } from '@agent-device/kernel/errors';
+import { simulatorAddressFor } from './core/simctl.ts';
 import { createLaunchObservationProbe } from './snapshot-observability.ts';
 import type { SnapshotSourceFailure, SnapshotSourceOutcome } from './snapshot-source-facade.ts';
 import type { SimulatorSnapshotTarget } from './snapshot-target.ts';
@@ -20,7 +21,7 @@ const simulator = {
 } as const satisfies DeviceInfo;
 
 const target = {
-  udid: simulator.id,
+  simulator: simulatorAddressFor(simulator),
   runtime: 'iOS 26.0',
   pid: 42,
   generation: '42:launch-a',
diff --git a/packages/platform-apple/src/snapshot-route.test.ts b/packages/platform-apple/src/snapshot-route.test.ts
index 2f5a9b6647..d1be189ac7 100644
--- a/packages/platform-apple/src/snapshot-route.test.ts
+++ b/packages/platform-apple/src/snapshot-route.test.ts
@@ -9,6 +9,7 @@ vi.mock('./system-surface-presence.ts', () => ({
 }));
 import { areIosSnapshotComparisonIdentitiesEqual } from '@agent-device/capture-kit/ios-snapshot-planning';
 import { IOS_SYSTEM_SURFACE_HOSTS } from '@agent-device/contracts/ios-system-surface';
+import { simulatorAddressFor } from './core/simctl.ts';
 import { createLocalAppleToolProvider, withAppleToolProvider } from './core/tool-provider.ts';
 import { platformRuntimeHostFixture } from './runtime.fixtures.ts';
 import { createAppleSnapshotRoute } from './snapshot-route.ts';
@@ -26,7 +27,7 @@ const ios = {
 } as const satisfies DeviceInfo;
 
 const target = {
-  udid: ios.id,
+  simulator: simulatorAddressFor(ios),
   runtime: 'iOS 26.0',
   pid: 42,
   generation: '42:launch-a',
@@ -489,7 +490,7 @@ test('a slow app discovery yields to a live runner within its wait slice, then s
   const released = new Promise<void>((resolve) => {
     release = resolve;
   });
-  const run = vi.fn(async (args: string[]) => {
+  const run = vi.fn(async (args: readonly string[]) => {
     if (args[0] === 'spawn') await released;
     return {
       stdout:
@@ -555,7 +556,7 @@ test('an open waits out a slow app discovery, so the first capture after it star
   const released = new Promise<void>((resolve) => {
     release = resolve;
   });
-  const run = vi.fn(async (args: string[]) => {
+  const run = vi.fn(async (args: readonly string[]) => {
     if (args[0] === 'spawn') await released;
     return {
       stdout:
@@ -729,7 +730,7 @@ test('a slow app discovery keeps observation on the bridge while no runner can a
   const released = new Promise<void>((resolve) => {
     release = resolve;
   });
-  const run = vi.fn(async (args: string[]) => {
+  const run = vi.fn(async (args: readonly string[]) => {
     if (args[0] === 'spawn') await released;
     return {
       stdout:
diff --git a/packages/platform-apple/src/snapshot-route.ts b/packages/platform-apple/src/snapshot-route.ts
index 1961abdca5..9bed7d9eb6 100644
--- a/packages/platform-apple/src/snapshot-route.ts
+++ b/packages/platform-apple/src/snapshot-route.ts
@@ -277,13 +277,13 @@ async function fallbackAfterFailure(
   if (opensGenerationCircuit(failure)) disabledGenerations.add(generationKey(failedTarget));
   emitRouteDiagnostic(
     failure.code,
-    { id: failedTarget.udid },
+    { id: failedTarget.simulator.udid },
     failedTarget.generation,
     cause,
     failure.details,
   );
   return await runFallback(
-    failedTarget.udid,
+    failedTarget.simulator.udid,
     input,
     fallback,
     identity.lineage,
diff --git a/packages/platform-apple/src/snapshot-source/adapter.test.ts b/packages/platform-apple/src/snapshot-source/adapter.test.ts
index d419def596..008872b399 100644
--- a/packages/platform-apple/src/snapshot-source/adapter.test.ts
+++ b/packages/platform-apple/src/snapshot-source/adapter.test.ts
@@ -10,6 +10,7 @@ import {
 } from '@agent-device/capture-kit/ios-snapshot-planning';
 import { createSnapshotSourceHost } from './host.ts';
 import { createSimulatorSnapshotSource } from './adapter.ts';
+import { simulatorAddressFor } from '../core/simctl.ts';
 import { DEPTH_HINT_PROBE_BACK_AFTER_USES } from './depth-hints.ts';
 import {
   encodeSnapshotBridgeFrame,
@@ -47,7 +48,11 @@ test('the Simulator AX source returns raw acquisition facts and discloses unsupp
 
   try {
     const result = await source.acquire({
-      target: { ...sourceTarget, targetId: 'target-1', simulatorSetPath: '/tmp/scoped-set' },
+      target: {
+        ...targetForTest('/tmp/scoped-set'),
+        generation: 'generation-1',
+        targetId: 'target-1',
+      },
       hint,
     });
     assert.deepEqual(
@@ -472,9 +477,16 @@ type AdapterFixture = {
   startedTargets: Array<Parameters<SnapshotSourceHost['start']>[0]>;
 };
 
-function targetForTest() {
+function targetForTest(simulatorSetPath?: string) {
   return {
-    udid: 'simulator-1',
+    simulator: simulatorAddressFor({
+      platform: 'apple',
+      id: 'simulator-1',
+      name: 'iPhone 17',
+      kind: 'simulator',
+      target: 'mobile',
+      ...(simulatorSetPath ? { simulatorSetPath } : {}),
+    }),
     runtime: 'iOS 26.2',
     pid: 321,
   };
diff --git a/packages/platform-apple/src/snapshot-source/adapter.ts b/packages/platform-apple/src/snapshot-source/adapter.ts
index f82c771124..4ffd715553 100644
--- a/packages/platform-apple/src/snapshot-source/adapter.ts
+++ b/packages/platform-apple/src/snapshot-source/adapter.ts
@@ -121,7 +121,7 @@ export function createSimulatorSnapshotSource(
 // fallow-ignore-next-line complexity
 function validateRequest(request: SnapshotSourceRequest): void {
   if (
-    !request.target.udid.trim() ||
+    !request.target.simulator.udid.trim() ||
     !request.target.runtime.trim() ||
     !request.target.generation.trim() ||
     !Number.isSafeInteger(request.target.pid) ||
diff --git a/packages/platform-apple/src/snapshot-source/host.test.ts b/packages/platform-apple/src/snapshot-source/host.test.ts
index 893677b787..989e0feaef 100644
--- a/packages/platform-apple/src/snapshot-source/host.test.ts
+++ b/packages/platform-apple/src/snapshot-source/host.test.ts
@@ -2,6 +2,7 @@ import assert from 'node:assert/strict';
 import { EventEmitter } from 'node:events';
 import { test, vi } from 'vitest';
 import { runCmdBackground } from '@agent-device/host-kit/command';
+import { simulatorAddressFor } from '../core/simctl.ts';
 import { createSnapshotSourceHost, snapshotSourceSocketPath } from './host.ts';
 
 vi.mock('@agent-device/host-kit/command', async (importOriginal) => ({
@@ -40,7 +41,14 @@ test.each([
   });
 
   const started = createSnapshotSourceHost().start(
-    { udid: 'simulator-1', ...(simulatorSetPath ? { simulatorSetPath } : {}) },
+    simulatorAddressFor({
+      platform: 'apple',
+      id: 'simulator-1',
+      name: 'iPhone 17',
+      kind: 'simulator',
+      target: 'mobile',
+      ...(simulatorSetPath ? { simulatorSetPath } : {}),
+    }),
     '/tmp/bridge',
     '/tmp/bridge.sock',
   );
diff --git a/packages/platform-apple/src/snapshot-source/host.ts b/packages/platform-apple/src/snapshot-source/host.ts
index 9c11d40d3e..f54afe12dd 100644
--- a/packages/platform-apple/src/snapshot-source/host.ts
+++ b/packages/platform-apple/src/snapshot-source/host.ts
@@ -23,14 +23,9 @@ import { emitDiagnostic, withDiagnosticTimer } from '@agent-device/host-kit/diag
 import { findProjectRoot } from '@agent-device/host-kit/version';
 import { SnapshotSourceError, snapshotSourceError } from './errors.ts';
 import { remainingSnapshotSourceMs } from './deadline.ts';
-import type {
-  SnapshotSourceHost,
-  SnapshotSourceProcess,
-  SnapshotSourceSocket,
-  SnapshotSourceTarget,
-} from './types.ts';
+import type { SnapshotSourceHost, SnapshotSourceProcess, SnapshotSourceSocket } from './types.ts';
 import { readSnapshotTargetProcessStartTime } from '../snapshot-process.ts';
-import { buildSimctlArgs } from '../core/simctl.ts';
+import { buildSimctlArgsForAddress, type SimulatorAddress } from '../core/simctl.ts';
 
 const BRIDGE_IDLE_TIMEOUT_SECONDS = 60;
 const MAX_PROCESS_LOG_BYTES = 64 * 1024;
@@ -60,7 +55,7 @@ export function createSnapshotSourceHost(): SnapshotSourceHost {
 }
 
 function startSnapshotBridge(
-  target: Pick<SnapshotSourceTarget, 'udid' | 'simulatorSetPath'>,
+  simulator: SimulatorAddress,
   bridgePath: string,
   socketPath: string,
   options: { signal?: AbortSignal } = {},
@@ -70,20 +65,17 @@ function startSnapshotBridge(
   }
   const started = runCmdBackground(
     'xcrun',
-    buildSimctlArgs(
-      [
-        'spawn',
-        target.udid,
-        bridgePath,
-        'serve',
-        socketPath,
-        '--idle-timeout',
-        String(BRIDGE_IDLE_TIMEOUT_SECONDS),
-        '--exit-on-disconnect',
-        'false',
-      ],
-      { simulatorSetPath: target.simulatorSetPath },
-    ),
+    buildSimctlArgsForAddress(simulator, [
+      'spawn',
+      simulator.udid,
+      bridgePath,
+      'serve',
+      socketPath,
+      '--idle-timeout',
+      String(BRIDGE_IDLE_TIMEOUT_SECONDS),
+      '--exit-on-disconnect',
+      'false',
+    ]),
     {
       allowFailure: true,
       captureOutput: false,
diff --git a/packages/platform-apple/src/snapshot-source/lifecycle.test.ts b/packages/platform-apple/src/snapshot-source/lifecycle.test.ts
index c2da49247f..f817182837 100644
--- a/packages/platform-apple/src/snapshot-source/lifecycle.test.ts
+++ b/packages/platform-apple/src/snapshot-source/lifecycle.test.ts
@@ -10,11 +10,13 @@ import {
   SNAPSHOT_SOURCE_VERSION,
 } from './protocol.ts';
 import { SnapshotBridgeManager } from './lifecycle.ts';
+import { simulatorAddressFor } from '../core/simctl.ts';
 import type {
   SnapshotSourceHost,
   SnapshotSourceLimits,
   SnapshotSourceProcess,
   SnapshotSourceSocket,
+  SnapshotSourceTarget,
 } from './types.ts';
 
 const limits: SnapshotSourceLimits = {
@@ -25,8 +27,16 @@ const limits: SnapshotSourceLimits = {
   maxDurationMs: 100,
 };
 
+const simulatorDevice = {
+  platform: 'apple',
+  id: 'simulator-1',
+  name: 'iPhone 17',
+  kind: 'simulator',
+  target: 'mobile',
+} as const;
+
 const target = {
-  udid: 'simulator-1',
+  simulator: simulatorAddressFor(simulatorDevice),
   runtime: 'iOS 26.2',
   pid: 123,
   generation: 'generation-1',
@@ -40,6 +50,12 @@ const bridge = {
   sourceVersion: SNAPSHOT_SOURCE_VERSION,
 };
 
+function compileTimeSnapshotTargetProof(): SnapshotSourceTarget {
+  // @ts-expect-error A target names its simulator through an address minted from its DeviceInfo.
+  return { udid: 'simulator-1', runtime: 'iOS 26.2', pid: 123, generation: 'generation-1' };
+}
+void compileTimeSnapshotTargetProof;
+
 test('the bridge manager reuses a healthy per-device helper and stops it exactly once', async () => {
   const fixture = createLifecycleFixture();
   const manager = new SnapshotBridgeManager(fixture.host);
@@ -56,7 +72,10 @@ test('the bridge manager reuses a healthy per-device helper and stops it exactly
 test('the helper starts inside the simulator set that owns the target', async () => {
   const fixture = createLifecycleFixture();
   const manager = new SnapshotBridgeManager(fixture.host);
-  const scopedTarget = { ...target, simulatorSetPath: '/tmp/scoped-set' };
+  const scopedTarget = {
+    ...target,
+    simulator: simulatorAddressFor({ ...simulatorDevice, simulatorSetPath: '/tmp/scoped-set' }),
+  };
 
   await manager.request({
     target: scopedTarget,
@@ -66,7 +85,9 @@ test('the helper starts inside the simulator set that owns the target', async ()
     deadline: deadline(),
   });
 
-  assert.deepEqual(fixture.startedTargets, [scopedTarget]);
+  assert.deepEqual(fixture.startedTargets, [
+    { udid: 'simulator-1', simulatorSetPath: '/tmp/scoped-set' },
+  ]);
   await manager.close();
 });
 
diff --git a/packages/platform-apple/src/snapshot-source/lifecycle.ts b/packages/platform-apple/src/snapshot-source/lifecycle.ts
index d89abcc129..4c48a37a60 100644
--- a/packages/platform-apple/src/snapshot-source/lifecycle.ts
+++ b/packages/platform-apple/src/snapshot-source/lifecycle.ts
@@ -55,7 +55,7 @@ export class SnapshotBridgeManager {
 
   async request(input: SnapshotBridgeRequest): Promise<SnapshotBridgeEnvelope> {
     if (this.closed) throw snapshotSourceError('unsupported', 'source-closed');
-    return await this.withSimulatorLock(input.target.udid, input.deadline, () =>
+    return await this.withSimulatorLock(input.target.simulator.udid, input.deadline, () =>
       this.requestInSimulator(input),
     );
   }
@@ -64,7 +64,7 @@ export class SnapshotBridgeManager {
     if (this.closed) throw snapshotSourceError('unsupported', 'source-closed');
     const deadline = input.deadline;
     remainingSnapshotSourceMs(deadline, 'bridge-request-deadline');
-    const previousSession = this.sessions.get(input.target.udid);
+    const previousSession = this.sessions.get(input.target.simulator.udid);
     const session = await this.ensureSession(input, deadline);
     try {
       const targetStartTime = await this.readTargetStartTime(input.target, deadline);
@@ -127,7 +127,7 @@ export class SnapshotBridgeManager {
     input: SnapshotBridgeRequest,
     deadline: SnapshotSourceDeadline,
   ): Promise<BridgeSession> {
-    const key = input.target.udid;
+    const key = input.target.simulator.udid;
     const existing = this.sessions.get(key);
     if (existing && existing.bridgePath === input.bridge.path && existing.process.isAlive()) {
       if (!existing.socket || existing.socket.destroyed) {
@@ -137,14 +137,18 @@ export class SnapshotBridgeManager {
     }
     if (existing) await this.removeSession(existing, true);
 
-    const socketPath = snapshotSourceSocketPath(this.host, input.target.udid, this.ownerId);
+    const socketPath = snapshotSourceSocketPath(
+      this.host,
+      input.target.simulator.udid,
+      this.ownerId,
+    );
     await this.host.ensureDirectory(path.dirname(socketPath));
     await this.host.remove(socketPath);
-    const bridgeProcess = this.host.start(input.target, input.bridge.path, socketPath, {
+    const bridgeProcess = this.host.start(input.target.simulator, input.bridge.path, socketPath, {
       signal: deadline.signal,
     });
     const session: BridgeSession = {
-      udid: input.target.udid,
+      udid: input.target.simulator.udid,
       bridgePath: input.bridge.path,
       socketPath,
       process: bridgeProcess,
diff --git a/packages/platform-apple/src/snapshot-source/types.ts b/packages/platform-apple/src/snapshot-source/types.ts
index fa0b20c838..70f69675ee 100644
--- a/packages/platform-apple/src/snapshot-source/types.ts
+++ b/packages/platform-apple/src/snapshot-source/types.ts
@@ -5,6 +5,7 @@ import type {
   IosViewportEvidence,
 } from '@agent-device/contracts/ios-snapshot';
 import type { RawSnapshotNode } from '@agent-device/kernel/snapshot';
+import type { SimulatorAddress } from '../core/simctl.ts';
 import type { SnapshotSourceDeadline } from './deadline.ts';
 
 export type SnapshotSourceLimits = Readonly<{
@@ -16,14 +17,12 @@ export type SnapshotSourceLimits = Readonly<{
 }>;
 
 export type SnapshotSourceTarget = Readonly<{
-  udid: string;
+  simulator: SimulatorAddress;
   runtime: string;
   pid: number;
   generation: string;
   targetId?: string;
   processStartTime?: string;
-  /** Device set that owns `udid`; absent for the default CoreSimulator set. */
-  simulatorSetPath?: string;
 }>;
 
 export type SnapshotSourceRequest = Readonly<{
@@ -84,7 +83,7 @@ export type SnapshotSourceHost = Readonly<{
   homeDirectory(): string;
   run(command: string, args: string[], options?: ExecOptions): Promise<ExecResult>;
   start(
-    target: Pick<SnapshotSourceTarget, 'udid' | 'simulatorSetPath'>,
+    simulator: SimulatorAddress,
     bridgePath: string,
     socketPath: string,
     options?: { signal?: AbortSignal },
diff --git a/packages/platform-apple/src/snapshot-target.test.ts b/packages/platform-apple/src/snapshot-target.test.ts
index 08e830ca80..09093a9c23 100644
--- a/packages/platform-apple/src/snapshot-target.test.ts
+++ b/packages/platform-apple/src/snapshot-target.test.ts
@@ -18,7 +18,7 @@ const signal = () => new AbortController().signal;
 
 function targetFixture() {
   const state = { pid: 42, launch: 'launch-a', start: 'start-a' as string | null };
-  const run = vi.fn(async (args: string[], _options?: { timeoutMs?: number }) => ({
+  const run = vi.fn(async (args: readonly string[], _options?: { timeoutMs?: number }) => ({
     stdout: args.includes('spawn')
       ? `90\t0\tUIKitApplication:com.example.app.beta[wrong][rb-legacy]\n${state.pid}\t0\tUIKitApplication:${app}[${state.launch}][rb-legacy]`
       : JSON.stringify({
@@ -53,7 +53,7 @@ test('an unchanged OS process reuses its exact app target without another simctl
     const second = await fixture.resolve(ios, app, signal());
     expect(second).toBe(first);
     expect(first).toEqual({
-      udid: ios.id,
+      simulator: { udid: ios.id, simulatorSetPath: undefined },
       runtime: 'com.apple.CoreSimulator.SimRuntime.iOS-26-0',
       pid: 42,
       generation: `42:UIKitApplication:${app}[launch-a][rb-legacy]:start-a`,
@@ -73,7 +73,7 @@ test('a target in a scoped simulator set carries that set to the bridge', async
       app,
       signal(),
     );
-    expect(target.simulatorSetPath).toBe('/tmp/scoped-set');
+    expect(target.simulator.simulatorSetPath).toBe('/tmp/scoped-set');
     expect(fixture.run.mock.calls.map(([args]) => args.slice(0, 2))).toEqual([
       ['--set', '/tmp/scoped-set'],
       ['--set', '/tmp/scoped-set'],
@@ -167,7 +167,7 @@ function deferredSpawn(fixture: ReturnType<typeof targetFixture>) {
     release = resolve;
   });
   const respond = fixture.run.getMockImplementation()!;
-  fixture.run.mockImplementation(async (args: string[]) =>
+  fixture.run.mockImplementation(async (args: readonly string[]) =>
     args[0] === 'spawn' ? await released.then(() => respond(args)) : await respond(args),
   );
   return release;
@@ -255,7 +255,7 @@ test('a failed runtime probe does not release the slot while the launch-job prob
   const fixture = targetFixture();
   const release = deferredSpawn(fixture);
   const respond = fixture.run.getMockImplementation()!;
-  fixture.run.mockImplementation(async (args: string[], options) =>
+  fixture.run.mockImplementation(async (args: readonly string[], options) =>
     args[0] === 'list'
       ? { stdout: '', stderr: 'simctl list failed', exitCode: 1 }
       : await respond(args, options),
diff --git a/packages/platform-apple/src/snapshot-target.ts b/packages/platform-apple/src/snapshot-target.ts
index b24f7178d5..dfca5792c5 100644
--- a/packages/platform-apple/src/snapshot-target.ts
+++ b/packages/platform-apple/src/snapshot-target.ts
@@ -1,7 +1,12 @@
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import { AppError } from '@agent-device/kernel/errors';
 import { createDetachedAttempts, waitForDetachedAttempt } from './detached-attempt.ts';
-import { readSimctlDevicesByRuntime, runSimctlForDevice } from './core/simctl.ts';
+import {
+  readSimctlDevicesByRuntime,
+  runSimctlForDevice,
+  simulatorAddressFor,
+  type SimulatorAddress,
+} from './core/simctl.ts';
 import { readSnapshotTargetProcessStartTime } from './snapshot-process.ts';
 
 /** Identity re-check of a cached target: one local `ps`, never CoreSimulator IPC. */
@@ -19,13 +24,12 @@ const TARGET_DISCOVERY_TIMEOUT_MS = 15_000;
 const TARGET_DISCOVERY_PENDING = 'simulator-target-discovery-pending';
 
 export type SimulatorSnapshotTarget = Readonly<{
-  udid: string;
+  simulator: SimulatorAddress;
   runtime: string;
   pid: number;
   generation: string;
   targetId: string;
   processStartTime: string;
-  simulatorSetPath?: string;
 }>;
 
 export type SimulatorSnapshotTargetResolver = (
@@ -111,13 +115,12 @@ async function resolveSimulatorSnapshotTarget(
     throw targetError('simulator-target-identity-unavailable', device, appBundleId);
   }
   return Object.freeze({
-    udid: device.id,
+    simulator: simulatorAddressFor(device),
     runtime,
     pid: job.pid,
     generation: `${job.pid}:${job.label}:${processStartTime}`,
     targetId: `${device.id}:${appBundleId}`,
     processStartTime,
-    ...(device.simulatorSetPath ? { simulatorSetPath: device.simulatorSetPath } : {}),
   });
 }
 
diff --git a/scripts/layering/apple-simulator-scope-policy.test.ts b/scripts/layering/apple-simulator-scope-policy.test.ts
new file mode 100644
index 0000000000..652633518d
--- /dev/null
+++ b/scripts/layering/apple-simulator-scope-policy.test.ts
@@ -0,0 +1,143 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import {
+  appleSimulatorScopeViolations,
+  isPolicedSimulatorScopeFile,
+} from './apple-simulator-scope-policy.ts';
+
+const APPLE_SRC = 'packages/platform-apple/src/';
+const ARGV_MESSAGE =
+  /^builds or forges simctl argv outside core\/simctl\.ts; use scopeSimctlArgsForDevice\/runSimctlForDevice or a SimulatorAddress from simulatorAddressFor\(device\)$/;
+const SET_SCOPE_MESSAGE =
+  /^set-scope simctl builder outside its owners; a call that names a udid takes its set from the device \(scopeSimctlArgsForDevice\) or its SimulatorAddress$/;
+
+function violationsFor(file: string, source: string) {
+  return appleSimulatorScopeViolations(new Map([[file, source]]));
+}
+
+function assertFlagged(file: string, source: string, message: RegExp): void {
+  const violations = violationsFor(file, source);
+  assert.equal(violations.length, 1, `${file}: ${source}`);
+  assert.equal(violations[0]!.rule, 'R79 apple-simulator-scope');
+  assert.equal(violations[0]!.file, file);
+  assert.match(violations[0]!.message, message);
+}
+
+const HAND_BUILT_SPAWN = "runXcrun(['simctl', 'spawn', udid, binary]);\n";
+const HAND_BUILT_BRIDGE = "runCmdBackground('xcrun', ['simctl', 'spawn', udid, bridge]);\n";
+const EXPLICIT_DEFAULT_SET =
+  "scopeSimctlArgs(['spawn', udid, bin], { simulatorSetPath: undefined });\n";
+const ALIASED_SET_SCOPE = "import { scopeSimctlArgs as scope } from '../core/simctl.ts';\n";
+const FORGED_ARGV =
+  "resolveAppleToolProvider().simctl.run(['spawn', udid, bin] as unknown as ScopedSimctlArgs);\n";
+const FORGED_ADDRESS = 'const address = { udid, simulatorSetPath } as SimulatorAddress;\n';
+const HAND_PREFIX = "const args = ['--set', path, ...args];\n";
+
+test('the two #2818 hand-built simctl spawns are refused', () => {
+  assertFlagged(`${APPLE_SRC}foldable/simulator-hid.ts`, HAND_BUILT_SPAWN, ARGV_MESSAGE);
+  assertFlagged(`${APPLE_SRC}snapshot-source/host.ts`, HAND_BUILT_BRIDGE, ARGV_MESSAGE);
+});
+
+test('the set-scope builder is refused outside its owners, aliased or not', () => {
+  assertFlagged(`${APPLE_SRC}foldable/simulator-hid.ts`, EXPLICIT_DEFAULT_SET, SET_SCOPE_MESSAGE);
+  assertFlagged(`${APPLE_SRC}snapshot-source/host.ts`, ALIASED_SET_SCOPE, SET_SCOPE_MESSAGE);
+});
+
+test('a forged scoped argv or simulator address is refused', () => {
+  assertFlagged('src/platform-runtime-planted.ts', FORGED_ARGV, ARGV_MESSAGE);
+  assertFlagged(`${APPLE_SRC}foldable/simulator-hid.ts`, FORGED_ADDRESS, ARGV_MESSAGE);
+  assertFlagged(
+    `${APPLE_SRC}foldable/simulator-hid.ts`,
+    'const address = <SimulatorAddress>{ udid, simulatorSetPath };\n',
+    ARGV_MESSAGE,
+  );
+});
+
+test('a hand-rolled --set prefix is refused outside core/simctl.ts', () => {
+  assertFlagged(`${APPLE_SRC}foldable/simulator-hid.ts`, HAND_PREFIX, ARGV_MESSAGE);
+});
+
+test('the argv owners may build, prefix and mint', () => {
+  const owner = `${APPLE_SRC}core/simctl.ts`;
+  for (const source of [
+    HAND_BUILT_SPAWN,
+    HAND_BUILT_BRIDGE,
+    EXPLICIT_DEFAULT_SET,
+    ALIASED_SET_SCOPE,
+    FORGED_ARGV,
+    FORGED_ADDRESS,
+    HAND_PREFIX,
+  ]) {
+    assert.deepEqual(violationsFor(owner, source), [], source);
+  }
+  assert.deepEqual(
+    violationsFor(
+      `${APPLE_SRC}core/tool-provider.ts`,
+      "provider.simctl.run(toolArgs as unknown as ScopedSimctlArgs, options);\nrunCmd('xcrun', ['simctl', ...args]);\n",
+    ),
+    [],
+  );
+});
+
+test('the tool provider may not forge an address or a --set prefix', () => {
+  assertFlagged(`${APPLE_SRC}core/tool-provider.ts`, FORGED_ADDRESS, ARGV_MESSAGE);
+  assertFlagged(`${APPLE_SRC}core/tool-provider.ts`, HAND_PREFIX, ARGV_MESSAGE);
+});
+
+test('the calls that name no device may take set scope', () => {
+  for (const file of [`${APPLE_SRC}simulator-inventory.ts`, `${APPLE_SRC}logs/doctor.ts`]) {
+    assert.deepEqual(
+      violationsFor(
+        file,
+        "import { scopeSimctlArgs } from './core/simctl.ts';\nscopeSimctlArgs(['help'], { simulatorSetPath: undefined });\n",
+      ),
+      [],
+      file,
+    );
+  }
+});
+
+test('tests, fixtures and scripts are not policed', () => {
+  for (const file of [
+    `${APPLE_SRC}foldable/simulator-hid.test.ts`,
+    `${APPLE_SRC}core/__tests__/simctl.test.ts`,
+    `${APPLE_SRC}runtime.fixtures.ts`,
+    'scripts/ios-snapshot-benchmark/lifecycle.ts',
+    'test/integration/provider-scenarios/providers.ts',
+  ]) {
+    assert.equal(isPolicedSimulatorScopeFile(file), false, file);
+    assert.deepEqual(violationsFor(file, HAND_BUILT_SPAWN + EXPLICIT_DEFAULT_SET), [], file);
+  }
+  assert.equal(isPolicedSimulatorScopeFile(`${APPLE_SRC}foldable/simulator-hid.ts`), true);
+  assert.equal(isPolicedSimulatorScopeFile('src/platform-runtime-apple-tool-host.ts'), true);
+});
+
+test('devicectl argv and scoped device calls are not simctl violations', () => {
+  assert.deepEqual(
+    violationsFor(
+      `${APPLE_SRC}deployment/runtime.ts`,
+      [
+        "host.appleTools.run({ tool: 'devicectl', args: ['device', 'install', 'app', '--device', id] });",
+        "host.appleTools.run({ tool: 'simctl', args: scopeSimctlArgsForDevice(device, ['boot', device.id]) });",
+        "runXcrun(buildSimctlArgsForAddress(simulatorAddressFor(device), ['spawn', device.id]));",
+      ].join('\n'),
+    ),
+    [],
+  );
+});
+
+test('an unaliased import of the set-scope builder is one violation', () => {
+  assertFlagged(
+    `${APPLE_SRC}snapshot-source/host.ts`,
+    "import { scopeSimctlArgs } from '../core/simctl.ts';\n",
+    SET_SCOPE_MESSAGE,
+  );
+});
+
+test('a violation reports the line of the offending node', () => {
+  const [violation] = violationsFor(
+    `${APPLE_SRC}foldable/simulator-hid.ts`,
+    `const a = 1;\n\n${HAND_BUILT_SPAWN}`,
+  );
+  assert.equal(violation!.line, 3);
+});
diff --git a/scripts/layering/apple-simulator-scope-policy.ts b/scripts/layering/apple-simulator-scope-policy.ts
new file mode 100644
index 0000000000..b83f4dd67a
--- /dev/null
+++ b/scripts/layering/apple-simulator-scope-policy.ts
@@ -0,0 +1,128 @@
+// Catches: a simctl argv that addresses a simulator without the set that holds it -- built by hand
+//   (`['simctl', 'spawn', udid, ...]` into runXcrun, runCmdBackground or an `executable: 'xcrun'`
+//   spec), prefixed by hand (`'--set'`), forged through a cast to `ScopedSimctlArgs` or
+//   `SimulatorAddress`, or scoped through the set-scope builder with the set written out as
+//   `undefined`. Every form type-checks where the brand does not reach (plain argv executors) or
+//   where the set-scope builder accepts an explicit `undefined`, and every form runs against the
+//   default CoreSimulator set: `Invalid device` for a simulator in a scoped set, or a different
+//   simulator with the same udid.
+// Evidence: #2784 (fixed by #2818): the AX snapshot bridge (`snapshot-source/host.ts`) and the
+//   fold HID helper (`foldable/simulator-hid.ts`) built `['simctl', 'spawn', udid, ...]` from a
+//   bare udid and lost the set; #2824 moved every call site onto `core/simctl.ts` and checked it
+//   with a manual `git grep "'--set'"`, which this rule turns into a gate.
+// Cost: 271 LOC (128 rule + 143 test).
+// Kill criterion: none enforced today; retire only by maintainer decision that scoped simulator
+//   sets (`--ios-simulator-device-set`) are no longer supported, or when every simctl executor
+//   takes an argv type that only `core/simctl.ts` can mint.
+
+import { parseSync } from 'oxc-parser';
+import { visitAst } from './layering-ast.ts';
+import type { LayeringViolation } from './model.ts';
+
+type AstNode = Record<string, unknown>;
+
+const RULE = 'R79 apple-simulator-scope';
+
+const APPLE_SRC = 'packages/platform-apple/src/';
+const SIMCTL_OWNER = `${APPLE_SRC}core/simctl.ts`;
+const TOOL_PROVIDER = `${APPLE_SRC}core/tool-provider.ts`;
+const ARGV_OWNERS = new Set([SIMCTL_OWNER, TOOL_PROVIDER]);
+/** The owners whose simctl calls name no device, so they take set scope. */
+const SET_SCOPE_OWNERS = new Set([
+  SIMCTL_OWNER,
+  `${APPLE_SRC}simulator-inventory.ts`,
+  `${APPLE_SRC}logs/doctor.ts`,
+]);
+const SET_SCOPE_BUILDER = 'scopeSimctlArgs';
+
+const ARGV_MESSAGE =
+  'builds or forges simctl argv outside core/simctl.ts; use scopeSimctlArgsForDevice/runSimctlForDevice ' +
+  'or a SimulatorAddress from simulatorAddressFor(device)';
+const SET_SCOPE_MESSAGE =
+  'set-scope simctl builder outside its owners; a call that names a udid takes its set from the ' +
+  'device (scopeSimctlArgsForDevice) or its SimulatorAddress';
+
+/** Production TypeScript under `packages/*\/src/` and `src/`; tests and fixtures are exempt. */
+export function isPolicedSimulatorScopeFile(file: string): boolean {
+  if (!/^packages\/[^/]+\/src\//.test(file) && !file.startsWith('src/')) return false;
+  return !(
+    file.endsWith('.test.ts') ||
+    file.includes('/__tests__/') ||
+    file.endsWith('.fixtures.ts')
+  );
+}
+
+export function appleSimulatorScopeViolations(
+  sources: ReadonlyMap<string, string>,
+): LayeringViolation[] {
+  const violations: LayeringViolation[] = [];
+  for (const [file, source] of sources) {
+    if (!isPolicedSimulatorScopeFile(file)) continue;
+    const reported = new Set<string>();
+    const report = (node: AstNode, message: string) => {
+      const offset = Number(node.start ?? 0);
+      if (reported.has(`${offset}:${message}`)) return;
+      reported.add(`${offset}:${message}`);
+      violations.push({ rule: RULE, file, line: lineAt(source, offset), message });
+    };
+    visitAst(parseSync(file, source).program, (node) => {
+      if (
+        !ARGV_OWNERS.has(file) &&
+        node.type === 'ArrayExpression' &&
+        isStringLiteral((node.elements as unknown[])[0], 'simctl')
+      ) {
+        report(node, ARGV_MESSAGE);
+      }
+      if (file.startsWith(APPLE_SRC) && file !== SIMCTL_OWNER && isStringLiteral(node, '--set')) {
+        report(node, ARGV_MESSAGE);
+      }
+      if (
+        (node.type === 'TSAsExpression' || node.type === 'TSTypeAssertion') &&
+        forgesBrand(file, node.typeAnnotation)
+      ) {
+        report(node, ARGV_MESSAGE);
+      }
+      if (
+        !SET_SCOPE_OWNERS.has(file) &&
+        node.type === 'Identifier' &&
+        node.name === SET_SCOPE_BUILDER
+      ) {
+        report(node, SET_SCOPE_MESSAGE);
+      }
+    });
+  }
+  return violations;
+}
+
+function forgesBrand(file: string, typeAnnotation: unknown): boolean {
+  const names = referencedTypeNames(typeAnnotation);
+  return (
+    (file !== SIMCTL_OWNER && names.has('SimulatorAddress')) ||
+    (!ARGV_OWNERS.has(file) && names.has('ScopedSimctlArgs'))
+  );
+}
+
+function referencedTypeNames(typeAnnotation: unknown): Set<string> {
+  const names = new Set<string>();
+  visitAst(typeAnnotation, (node) => {
+    if (node.type !== 'TSTypeReference') return;
+    const typeName = node.typeName as AstNode | undefined;
+    const name =
+      typeName?.type === 'TSQualifiedName' ? (typeName.right as AstNode).name : typeName?.name;
+    if (typeof name === 'string') names.add(name);
+  });
+  return names;
+}
+
+function isStringLiteral(node: unknown, value: string): boolean {
+  return (
+    node !== null &&
+    typeof node === 'object' &&
+    (node as AstNode).type === 'Literal' &&
+    (node as AstNode).value === value
+  );
+}
+
+function lineAt(source: string, offset: number): number {
+  return source.slice(0, offset).split('\n').length;
+}
diff --git a/scripts/layering/check.ts b/scripts/layering/check.ts
index 2d135cf4fb..bf09d3b43a 100644
--- a/scripts/layering/check.ts
+++ b/scripts/layering/check.ts
@@ -40,6 +40,9 @@
 //     directly (R77) — the subtree sits in the eager closure of seven Apple façade entries the
 //     eager-closure-budgets gate holds at a fixed size, so a direct host-kit edge grows all seven;
 //     host-kit reaches the runner only through `runner/host.ts`, bound in `core/runner-host.ts`.
+//   - Over SIMCTL ARGV in production source: only `core/simctl.ts` (and the provider executors in
+//     `core/tool-provider.ts`) build, prefix or mint scoped simctl argv, and only the calls that
+//     name no device take set scope (R79), so a udid never runs outside the set that holds it.
 //   - Over REQUEST-BOUND RUNTIME EXECUTION: facts remain the only admission authority and daemon
 //     code cannot manufacture or repair a narrowed runtime proof (R66).
 //   - Over CONTRACTS PRODUCTION SOURCE: contracts owns vocabulary only — host, process, and timer
@@ -99,6 +102,7 @@ import {
   platformPackagePolicySummary,
 } from './platform-package-policy.ts';
 import { appleRunnerHostPortViolations } from './apple-runner-host-port-policy.ts';
+import { appleSimulatorScopeViolations } from './apple-simulator-scope-policy.ts';
 import {
   listUntrackedProductionTypeScriptFiles,
   readTrackedPlatformPackageDeclarations,
@@ -456,6 +460,7 @@ export const LAYERING_RULE_IDS = [
   'package-boundaries',
   'platform-package-policy',
   'apple-runner-host-port',
+  'apple-simulator-scope',
   'retired-platforms-zone',
   'src-utils-retirement',
   'replay-ownership',
@@ -510,6 +515,7 @@ export const LAYERING_RULES: Readonly<Record<LayeringRuleId, LayeringRule>> = {
     ),
   'apple-runner-host-port': (context) =>
     appleRunnerHostPortViolations(context.allTypeScriptSources),
+  'apple-simulator-scope': (context) => appleSimulatorScopeViolations(context.allTypeScriptSources),
   'retired-platforms-zone': () => checkRetiredPlatformsZone(listTrackedPlatformZoneFiles(repoRoot)),
   'src-utils-retirement': (context) =>
     retiredPathRuleViolations('R14', context.trackedSrcUtilsFiles),
diff --git a/src/daemon/__tests__/request-platform-providers.test.ts b/src/daemon/__tests__/request-platform-providers.test.ts
index 13209ba53c..693a2b7acb 100644
--- a/src/daemon/__tests__/request-platform-providers.test.ts
+++ b/src/daemon/__tests__/request-platform-providers.test.ts
@@ -56,7 +56,7 @@ test('request platform provider scope applies Apple tool provider only for Apple
             },
             simctl: {
               run: async (args) => {
-                calls.push(args);
+                calls.push([...args]);
                 return { exitCode: 0, stdout: 'simctl-ok', stderr: '' };
               },
             },
diff --git a/test/integration/provider-scenarios/providers.ts b/test/integration/provider-scenarios/providers.ts
index c39a5f56f0..b9166cef34 100644
--- a/test/integration/provider-scenarios/providers.ts
+++ b/test/integration/provider-scenarios/providers.ts
@@ -6,13 +6,13 @@ import type {
   AppleToolProvider,
   AppleToolSubcommandExecutor,
 } from '@agent-device/platform-apple/tool-provider';
-import { type ExecResult } from '@agent-device/host-kit/command';
+import { type ExecOptions, type ExecResult } from '@agent-device/host-kit/command';
 import type { ProviderScenarioTranscript } from './transcript.ts';
 
 export type FlatToolCall = [string, ...string[]];
 
 type RecordingAppleToolHandlers = {
-  simctl?: AppleToolSubcommandExecutor;
+  simctl?: AppleToolProvider['simctl']['run'];
   devicectl?: AppleToolSubcommandExecutor;
   macosHelper?: AppleToolSubcommandExecutor;
   macosHost?: AppleMacOsHostProvider;
@@ -215,7 +215,7 @@ function simctlListDevicesJson(
 export function simctlDeviceLifecycleHandler(
   runtime: string,
   devices: Array<{ name: string; udid: string; state?: string; isAvailable?: boolean }>,
-): AppleToolSubcommandExecutor {
+): (args: readonly string[], options?: ExecOptions) => Promise<ExecResult> {
   return async (args) => {
     const result = simctlListDevicesResult(args, runtime, devices);
     if (result) return result;
@@ -237,7 +237,7 @@ export function unexpectedProviderCall(platform: string, command: readonly strin
 }
 
 export function simctlListDevicesResult(
-  args: string[],
+  args: readonly string[],
   runtime: string,
   devices: Array<{ name: string; udid: string; state?: string; isAvailable?: boolean }>,
 ): ExecResult | undefined {

From dbc08a417a5fb98b12643da983ba83772d0fd219 Mon Sep 17 00:00:00 2001
From: alcpereira <48070464+alcpereira@users.noreply.github.com>
Date: Thu, 24 Sep 2026 15:16:44 +0100
Subject: [PATCH 095/132] fix(install): send a default User-Agent with
 app-source downloads (#2842) (#2846)

api.github.com answers 403 to requests without a User-Agent, so GitHub
artifact URLs failed since the transport stopped sending one. Downloads
now send 'agent-device' unless the caller sets their own.

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .../src/install-source-download.test.ts       | 37 +++++++++++++++++++
 .../src/install-source-download.ts            |  8 +++-
 2 files changed, 44 insertions(+), 1 deletion(-)

diff --git a/packages/provision-kit/src/install-source-download.test.ts b/packages/provision-kit/src/install-source-download.test.ts
index 64ddbcd3da..dbd6e4c742 100644
--- a/packages/provision-kit/src/install-source-download.test.ts
+++ b/packages/provision-kit/src/install-source-download.test.ts
@@ -51,6 +51,43 @@ test('download redirects revalidate destinations and strip sensitive cross-origi
   }
 });
 
+test('download sends a default user-agent that a caller header replaces', async () => {
+  const tempRoot = await mkdtempForTest('agent-device-download-user-agent-');
+  const lookup = vi
+    .spyOn(dns, 'lookup')
+    .mockImplementation(
+      async () =>
+        [{ address: '93.184.216.34', family: 4 }] as unknown as Awaited<
+          ReturnType<typeof dns.lookup>
+        >,
+    );
+  const requestMock = vi
+    .spyOn(networkTransport, 'requestApprovedUrl')
+    .mockImplementation(async () => response(200, Buffer.from('apk')));
+  try {
+    await downloadInstallSource({
+      tempDir: tempRoot,
+      url: 'https://example.com/default.apk',
+      signal: new AbortController().signal,
+    });
+    await downloadInstallSource({
+      tempDir: tempRoot,
+      url: 'https://example.com/custom.apk',
+      headers: { 'User-Agent': 'caller-agent' },
+      signal: new AbortController().signal,
+    });
+    const defaultHeaders = requestMock.mock.calls[0]![0].headers;
+    const customHeaders = requestMock.mock.calls[1]![0].headers;
+    assert.equal(defaultHeaders['user-agent'], 'agent-device');
+    assert.equal(customHeaders['User-Agent'], 'caller-agent');
+    assert.equal(customHeaders['user-agent'], undefined);
+  } finally {
+    requestMock.mockRestore();
+    lookup.mockRestore();
+    await fs.rm(tempRoot, { recursive: true, force: true });
+  }
+});
+
 test('download errors do not disclose URL credentials or query values', async () => {
   const tempRoot = await mkdtempForTest('agent-device-download-redaction-');
   const lookup = vi
diff --git a/packages/provision-kit/src/install-source-download.ts b/packages/provision-kit/src/install-source-download.ts
index d1e90dd2cf..ac6bc6b362 100644
--- a/packages/provision-kit/src/install-source-download.ts
+++ b/packages/provision-kit/src/install-source-download.ts
@@ -11,6 +11,7 @@ import { approveDownloadSourceUrl } from './install-source-network.ts';
 import * as networkTransport from './install-source-network-transport.ts';
 
 const MAX_REDIRECTS = 5;
+const DEFAULT_USER_AGENT = 'agent-device';
 const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
 const NETWORK_ERROR_CODE_RE = /^[A-Z][A-Z0-9_]{0,63}$/;
 const FORBIDDEN_HEADERS = new Set([
@@ -34,7 +35,7 @@ export async function downloadInstallSource(params: {
   signal: AbortSignal;
 }): Promise<string> {
   let currentUrl = parseSourceUrl(params.url);
-  let headers = sanitizeHeaders(params.headers);
+  let headers = withDefaultUserAgent(sanitizeHeaders(params.headers));
   for (let redirectCount = 0; ; redirectCount += 1) {
     const response = await requestHop(currentUrl, headers, params.signal);
     try {
@@ -170,6 +171,11 @@ function sanitizeHeaders(input: Record<string, string> | undefined): Record<stri
   );
 }
 
+function withDefaultUserAgent(headers: Record<string, string>): Record<string, string> {
+  if (Object.keys(headers).some((name) => name.toLowerCase() === 'user-agent')) return headers;
+  return { ...headers, 'user-agent': DEFAULT_USER_AGENT };
+}
+
 function crossOriginHeaders(headers: Record<string, string>): Record<string, string> {
   return Object.fromEntries(
     Object.entries(headers).filter(([name]) =>

From d5c21f8faed21ef2ab71475a609eff0d5ca332d2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Oskar=20Kwa=C5=9Bniewski?= <oskar@okwasniewski.com>
Date: Thu, 24 Sep 2026 17:12:06 +0200
Subject: [PATCH 096/132] fix(android): carry the content description beside
 the label on the snapshot node (#2912)

An Android node is labelled by its text and falls back to the content description only when it has none, so an accessibility label the app set beside visible text never reached the wire: a labelled text view was named by its content, a filled field by its value, an empty field by its hint, a filled password field by its dots. The parser already read `content-desc`; the hierarchy node now carries it as `contentDescription` whenever it is not already the label, through the raw snapshot node, the unchanged-snapshot comparison, and the selector digest. `label` is unchanged, so nothing that keys on it moves.
---
 packages/kernel/src/snapshot.ts               |  7 ++++++
 .../src/ui-hierarchy-builder.ts               |  1 +
 .../platform-android/src/ui-hierarchy-node.ts |  2 ++
 packages/platform-android/src/ui-hierarchy.ts |  4 +++-
 src/__tests__/android-ui-hierarchy.test.ts    | 22 +++++++++++++++++++
 .../capture/runtime/snapshot-unchanged.ts     |  1 +
 src/daemon/response-views.ts                  |  1 +
 7 files changed, 37 insertions(+), 1 deletion(-)

diff --git a/packages/kernel/src/snapshot.ts b/packages/kernel/src/snapshot.ts
index 7c0bdfdf89..b0f38a3233 100644
--- a/packages/kernel/src/snapshot.ts
+++ b/packages/kernel/src/snapshot.ts
@@ -226,6 +226,13 @@ export type RawSnapshotNode = {
   subrole?: string;
   label?: string;
   value?: string;
+  /**
+   * Android content description when it is not already the `label`. An Android node is
+   * labelled by its text and falls back to the content description only when it has none,
+   * so an accessibility label the app set beside visible text (a labelled text view, a
+   * filled or hinted field) is carried here for consumers that want the accessible name.
+   */
+  contentDescription?: string;
   identifier?: string;
   rect?: Rect;
   enabled?: boolean;
diff --git a/packages/platform-android/src/ui-hierarchy-builder.ts b/packages/platform-android/src/ui-hierarchy-builder.ts
index 7edae0f476..ea608a2c5e 100644
--- a/packages/platform-android/src/ui-hierarchy-builder.ts
+++ b/packages/platform-android/src/ui-hierarchy-builder.ts
@@ -347,6 +347,7 @@ function createAndroidRawSnapshotNode(
     type: node.type ?? undefined,
     label: node.label ?? undefined,
     value: node.value ?? undefined,
+    contentDescription: node.contentDescription,
     identifier: node.identifier ?? undefined,
     bundleId: node.packageName ?? undefined,
     rect: node.rect,
diff --git a/packages/platform-android/src/ui-hierarchy-node.ts b/packages/platform-android/src/ui-hierarchy-node.ts
index 90e4a3fb92..c6e3138c32 100644
--- a/packages/platform-android/src/ui-hierarchy-node.ts
+++ b/packages/platform-android/src/ui-hierarchy-node.ts
@@ -8,6 +8,8 @@ export type AndroidUiHierarchy = {
   type: string | null;
   label: string | null;
   value: string | null;
+  /** The content description when the label is the text rather than it; see `RawSnapshotNode`. */
+  contentDescription?: string;
   identifier: string | null;
   packageName: string | null;
   rect?: Rect;
diff --git a/packages/platform-android/src/ui-hierarchy.ts b/packages/platform-android/src/ui-hierarchy.ts
index e130c89f14..cf5933cec7 100644
--- a/packages/platform-android/src/ui-hierarchy.ts
+++ b/packages/platform-android/src/ui-hierarchy.ts
@@ -298,11 +298,13 @@ function normalizeAndroidUiHierarchyNode(
   depth: number,
   parent: AndroidNode,
 ): AndroidUiHierarchy {
+  const label = attrs.text || attrs.desc;
   return attachAndroidSiblingOrder(
     {
       type: attrs.className,
-      label: attrs.text || attrs.desc,
+      label,
       value: attrs.text,
+      ...(attrs.desc && attrs.desc !== label ? { contentDescription: attrs.desc } : {}),
       identifier: attrs.resourceId,
       packageName: attrs.packageName,
       rect: attrs.rect,
diff --git a/src/__tests__/android-ui-hierarchy.test.ts b/src/__tests__/android-ui-hierarchy.test.ts
index 4de605940c..62a41f90c9 100644
--- a/src/__tests__/android-ui-hierarchy.test.ts
+++ b/src/__tests__/android-ui-hierarchy.test.ts
@@ -41,6 +41,7 @@ test('parseUiHierarchy reads double-quoted Android node attributes', () => {
   assert.equal(result.nodes.length, 1);
   assert.equal(result.nodes[0]!.value, 'Hello');
   assert.equal(result.nodes[0]!.label, 'Hello');
+  assert.equal(result.nodes[0]!.contentDescription, 'Greeting');
   assert.equal(result.nodes[0]!.identifier, 'com.demo:id/title');
   assert.deepEqual(result.nodes[0]!.rect, { x: 10, y: 20, width: 100, height: 40 });
   assert.equal(result.nodes[0]!.hittable, true);
@@ -111,9 +112,30 @@ test('interactive Android snapshots keep Compose semantic views inside actionabl
 
   assert.equal(result.nodes[0]?.hittable, true);
   assert.equal(result.nodes[1]?.label, 'Start a call');
+  assert.equal(result.nodes[1]?.contentDescription, undefined);
   assert.equal(result.nodes[1]?.parentIndex, 0);
 });
 
+test('an Android content description beside text is carried, and one that is the label is not repeated', () => {
+  const xml = `<hierarchy>
+  <node class="android.widget.EditText" package="com.example.app" text="Ada Lovelace" content-desc="Name field" resource-id="name-input" bounds="[0,0][390,44]" visible-to-user="true"/>
+  <node class="android.widget.EditText" package="com.example.app" text="Type your name" content-desc="Name field" hint-showing="true" resource-id="empty-input" bounds="[0,60][390,104]" visible-to-user="true"/>
+  <node class="android.widget.TextView" package="com.example.app" text="Plain controls" content-desc="Plain controls" bounds="[0,120][390,164]" visible-to-user="true"/>
+  <node class="android.widget.TextView" package="com.example.app" text="Untitled" bounds="[0,180][390,224]" visible-to-user="true"/>
+</hierarchy>`;
+
+  const result = parseUiHierarchy(xml, 800, { raw: true });
+
+  assert.equal(result.nodes[0]?.label, 'Ada Lovelace');
+  assert.equal(result.nodes[0]?.contentDescription, 'Name field');
+  assert.equal(result.nodes[1]?.label, 'Type your name');
+  assert.equal(result.nodes[1]?.hintShowing, true);
+  assert.equal(result.nodes[1]?.contentDescription, 'Name field');
+  assert.equal(result.nodes[2]?.label, 'Plain controls');
+  assert.equal(result.nodes[2]?.contentDescription, undefined);
+  assert.equal(result.nodes[3]?.contentDescription, undefined);
+});
+
 test('interactive Android snapshots keep a fixed sibling outside filtered scroll content (#1377)', () => {
   const xml = `<hierarchy>
   <node class="android.widget.FrameLayout" bounds="[0,0][400,800]" visible-to-user="true">
diff --git a/src/commands/capture/runtime/snapshot-unchanged.ts b/src/commands/capture/runtime/snapshot-unchanged.ts
index aa249709ce..61929117be 100644
--- a/src/commands/capture/runtime/snapshot-unchanged.ts
+++ b/src/commands/capture/runtime/snapshot-unchanged.ts
@@ -107,6 +107,7 @@ const PRESENTATION_SCALAR_FIELDS = {
   subrole: true,
   label: true,
   value: true,
+  contentDescription: true,
   identifier: true,
   enabled: true,
   selected: true,
diff --git a/src/daemon/response-views.ts b/src/daemon/response-views.ts
index 14c007e9dd..62ad99e599 100644
--- a/src/daemon/response-views.ts
+++ b/src/daemon/response-views.ts
@@ -110,6 +110,7 @@ const SELECTOR_DIGEST_NODE_FIELDS = [
   'subrole',
   'label',
   'value',
+  'contentDescription',
   'identifier',
   'enabled',
   'selected',

From 8c61aea285d73000afbb332e892cdea1fb256587 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 24 Sep 2026 17:17:03 +0200
Subject: [PATCH 097/132] docs(adr): repair 0004 paths, record the RUNNER_BUSY
 asymmetry, settle 0026 status (#2909)

* docs(adr): fix retired paths, record RUNNER_BUSY asymmetry, settle status

ADR 0004 cited `src/snapshot/**`, retired by the capture-kit move (#2385).
The ownership and boundary sentences now point at the `snapshot-policy`
declaration in scripts/layering/architecture-ownership.ts, and the three
policy bullets name the paths that exist.

ADR 0005 documented runner occupancy and drain but never recorded the
shipped asymmetry: a read-only request waits out `RUNNER_BUSY` and is
resent, while a mutating one is attempted once with nothing replayed. Both
decisions are keyed on the daemon-side `RUNNER_COMMAND_TRAITS` read-only
trait, not on a runner-side classification. The close-and-pooling sentence
keeps its scope so it no longer reads as contradicting that policy.

ADR 0026 was still `Proposed` after #2758 and #2759 shipped its ownership
decision. It is `Accepted`, with the two open #2754 steps named as open
work rather than as the decision.

Closes #2892

* docs(adr): mark the unshipped ADR 0026 rules and narrow two claims

Recording ADR 0026 as Accepted made two unshipped rules read as current: the
"every removed source" row and the ejection ledger in Contracts. Both now name
#2754 step 5 as the open contract, and the `ScrollArea` passages record the
decision #2759 shipped instead of asking for one.

ADR 0004's boundary sentence said the gate covers the facet; it covers only the
roots `snapshot-policy` declares, so the overlay modules beside that tree are
now named as outside it. ADR 0005's keying sentence claimed the runner reports
nothing; it is the runner-side classification of the command that plays no part,
while the refusal code selects the budget.
---
 .../adr/0004-ios-snapshot-backend-strategy.md | 36 +++++++-------
 .../0005-ios-runner-interaction-lifecycle.md  | 25 ++++++++--
 docs/adr/0026-scroll-clip-authority.md        | 49 ++++++++++++-------
 docs/adr/README.md                            |  2 +-
 4 files changed, 70 insertions(+), 42 deletions(-)

diff --git a/docs/adr/0004-ios-snapshot-backend-strategy.md b/docs/adr/0004-ios-snapshot-backend-strategy.md
index 5e8fe6e66a..dc46f6db6c 100644
--- a/docs/adr/0004-ios-snapshot-backend-strategy.md
+++ b/docs/adr/0004-ios-snapshot-backend-strategy.md
@@ -102,16 +102,16 @@ those runtimes; it does not imply that Swift and TypeScript share an implementat
 The macOS XCTest runner is the desktop-surface exception: its already-presented nodes bypass the iOS
 presentation engine and continue through neutral snapshot assembly.
 
-The same split now holds for the three remaining Wave 4 policies tracked by #1983, so
-`src/snapshot/` is the host-side owner of snapshot policy generally rather than of presentation
-alone:
+The same split now holds for the three remaining Wave 4 policies tracked by #1983, so the host-side
+facet in `@agent-device/capture-kit` owns snapshot policy generally rather than presentation alone:
 
 - **Freshness recovery.** The freshness window, the Android staleness classification and its
-  thresholds, and the retry loop live in `src/snapshot/snapshot-freshness/`. The loop is
-  parameterized by a classifier and a retry schedule, so "how long may a backend lag behind a real
-  transition" is a policy input rather than a constant the loop owns. The schedule is stated as a
-  duration budget; the loop derives the deadline from the window's `markedAt` itself, so the
-  budget is always spent from the action and a caller has no absolute instant it could get wrong.
+  thresholds, and the retry loop live in `packages/capture-kit/src/snapshot/snapshot-freshness/`.
+  The loop is parameterized by a classifier and a retry schedule, so "how long may a backend lag
+  behind a real transition" is a policy input rather than a constant the loop owns. The schedule is
+  stated as a duration budget; the loop derives the deadline from the window's `markedAt` itself, so
+  the budget is always spent from the action and a caller has no absolute instant it could get
+  wrong.
   `src/daemon/session-snapshot-freshness.ts` keeps only what needs a session: reading and retiring
   the window on store-owned `SessionState`, and choosing the comparison baseline from snapshot
   lineage. It remains the declared R7 owner of `androidSnapshotFreshness`.
@@ -125,8 +125,8 @@ alone:
   reclassifying. No message shape is consulted anywhere on that path, so rewording helper or
   wrapper prose cannot move the reason, and prose that merely reads like a timeout does not become
   one — both directions are asserted end to end against the real producer.
-  `src/snapshot/snapshot-timeout-policy.ts` reads the reason; the human-facing hint is derived
-  from it rather than decided alongside it.
+  `packages/capture-kit/src/snapshot/snapshot-timeout-policy.ts` reads the reason; the
+  human-facing hint is derived from it rather than decided alongside it.
 
   The published `details.androidSnapshotTimeoutScreenshot` payload is vocabulary in
   `@agent-device/contracts/snapshot-timeout-evidence`, a union whose arms encode which claims can
@@ -136,13 +136,15 @@ alone:
   The daemon keeps the ordering that genuinely needs it: resolving a bound screenshot runtime,
   writing the artifact, annotating it from the stored observation, and emitting the diagnostics.
 - **Screenshot-overlay policy.** Which Android nodes earn an overlay ref, and what rectangle an
-  overlay for one of them covers, live in `src/snapshot/screenshot-overlay/`. The daemon keeps
-  approved artifact and ref assembly only: ranking, projection to screenshot pixels, drawing, and
-  PNG IO.
-
-`scripts/layering/snapshot-presentation-boundary.test.ts` enforces the direction for the whole
-facet: nothing under `src/snapshot/` may import `src/daemon/`. It carries a positive control,
-because a filter that stopped matching would look identical to a boundary being obeyed.
+  overlay for one of them covers, live in `packages/capture-kit/src/screenshot-overlay*.ts`. The
+  daemon keeps approved artifact and ref assembly only: ranking, projection to screenshot pixels,
+  drawing, and PNG IO.
+
+`scripts/layering/snapshot-presentation-boundary.test.ts` enforces the direction, but only across
+the roots `snapshot-policy` declares in `scripts/layering/architecture-ownership.ts`: nothing in
+that snapshot tree may import `src/daemon/`, while the overlay modules beside the tree sit outside
+those roots and are outside that gate. It carries a positive control, because a filter that stopped
+matching would look identical to a boundary being obeyed.
 
 The residual call sites #1983 also named are audited and deliberately left in place.
 `src/daemon/direct-ios-selector.ts` carries no presentation policy: `isLocalIosRunnerSession` and
diff --git a/docs/adr/0005-ios-runner-interaction-lifecycle.md b/docs/adr/0005-ios-runner-interaction-lifecycle.md
index 888af655c8..5c539144ce 100644
--- a/docs/adr/0005-ios-runner-interaction-lifecycle.md
+++ b/docs/adr/0005-ios-runner-interaction-lifecycle.md
@@ -65,12 +65,27 @@ therefore drained), and left intact by a transport failure or an unstamped recov
 healthy `ok` is never read as proof of drain because a private-AX snapshot can be served while an
 abandoned tree crawl still grinds on the XCTest main thread (#2552).
 
+What a `RUNNER_BUSY` refusal then costs the caller turns on the daemon's own per-command read-only
+trait, not on any runner-side classification of the command: `RUNNER_COMMAND_TRAITS` in
+`packages/platform-apple/src/runner/runner-command-traits.ts`, read through
+`isReadOnlyRunnerCommand` where `runAppleRunnerCommand` decides whether to wrap the send in a resend
+loop. The asymmetry is shipped, and asserted in `runner-command-busy-resend.test.ts`: a read-only
+command treats the refusal as *not yet*, waiting the drain out on the busy-specific budget sized to
+outlast it and resending until the runner answers or the window ends; a mutating command treats the
+same refusal as *not mine to send again* — one attempt, and the refusal reaches the caller unwrapped
+with nothing replayed. Neither path pays a status probe, because a structured reply already answered
+"did my command run?" (the bypass in `runner-lifecycle.ts`). The same trait already decides the
+startup-preflight skip above, so it is the single place a change to that classification lands.
+
 Close that would retain a runner for reuse first stops it when that occupancy is set, awaiting the
-stop so the lease is released before the next request, because a runner still finishing
-watchdog-abandoned work refuses every command until it drains or escalates to `RUNNER_WEDGED`; pooling
-it back to the next `open` hands the same stalled runner to the caller and `close` recovers nothing.
-Killing the process is the only way to abort uncancellable XCTest work. This is the `RUNNER_WEDGED`
-restart from #1105 applied at the close boundary rather than after the wedge threshold elapses.
+stop so the lease is released before the next request. A runner still finishing watchdog-abandoned
+work does refuse every command sent to it until it drains or escalates to `RUNNER_WEDGED`, and that
+fact is stated here for the close-and-pooling decision only: the read-only resend above is one live
+caller waiting the same refusal out on its own budget, and `close` does not inherit that wait on the
+pool's behalf. Pooling the stalled runner back hands it to the next `open` and `close` recovers
+nothing. Killing the process is the only way to abort uncancellable XCTest work. This is the
+`RUNNER_WEDGED` restart from #1105 applied at the close boundary rather than after the wedge
+threshold elapses.
 
 When XCTest reports a root accessibility snapshot failure such as `kAXErrorIllegalArgument`, the
 runner treats the cached app target as suspect. Interactive snapshots fail closed to a truncated
diff --git a/docs/adr/0026-scroll-clip-authority.md b/docs/adr/0026-scroll-clip-authority.md
index c4c0bc1d59..f265b4dab1 100644
--- a/docs/adr/0026-scroll-clip-authority.md
+++ b/docs/adr/0026-scroll-clip-authority.md
@@ -2,8 +2,12 @@
 
 ## Status
 
-Proposed (2026-09-22). Refines ADR 0004's fact/interpretation boundary for scroll geometry; does not
-supersede it. Implementation contract: #2754.
+Accepted (2026-09-22). The ownership decision is shipped: #2758 reads an indicator's owner off the
+parent edge, climbing only same-frame ancestors — the tolerance the #2754 step 3 survey justified on
+real captures — and #2759 pairs the two eligibility lists and settles `ScrollArea` for macOS. Two
+#2754 steps stay open work rather than part of this decision: the runner-stage differential arm, and
+the typed ejection disposition the "every removed source" row below names. Refines ADR 0004's
+fact/interpretation boundary for scroll geometry; does not supersede it.
 
 An interactive iOS snapshot of a list dropped every row after a row holding selectable text. A
 `UITextView` is a UIScrollView and XCTest publishes its scroll indicator inside the text, so the
@@ -22,7 +26,7 @@ walking up past the indicator's parent, and that guess decided which nodes exist
 | Removing a node **because a scroll band hides it** | Requires evidence: the clip fold's result, or a band whose owner is the indicator's parent. A guess about ownership may not do it |
 | Removing a node by semantic delegation — a collapsed row, a duplicate label, a wrapper's content | Out of scope here. That is compaction, and it keeps its own authority |
 | Weaker evidence than a parent edge | Directional hints (`hiddenContentAbove` / `hiddenContentBelow`) and nothing that changes membership |
-| Every removed source | Ends with a typed disposition. Internal evidence, never wire vocabulary |
+| Every removed source | Must end with a typed disposition — the open #2754 step 5 contract, not shipped code. Internal evidence, never wire vocabulary |
 
 ## Contracts
 
@@ -47,8 +51,12 @@ neither eligible set contains it, and the iOS runner never emits it — it origi
 `AXScrollArea` mapping. That helper's trees do reach these rules, through `snapshot-desktop-surface.ts`
 → `ios-snapshot-runtime.ts` → `publishIosSnapshot`, so on that surface a `ScrollArea` host can be dropped
 by eligibility while its children re-parent past it, which leaves a parent-edge lookup with no owner.
-Reusing this rule for macOS therefore needs a `ScrollArea` eligibility decision made there, not carried
-over from the iOS claim above.
+Reusing this rule for macOS therefore needed a `ScrollArea` eligibility decision made there, not
+carried over from the iOS claim above, and #2759 made it with cases rather than by admitting the
+type for iOS's sake: `scrollarea` stays out of both eligible sets, a `ScrollArea` carrying content
+survives eligibility on those trees and owns its band, and a label-less one is dropped, leaving its
+indicator with no owner to band — which under-clips (safe) instead of mis-clipping the enclosing
+list (`eligibility-parity.test.ts`).
 
 **Why the band exists at all.** XCTest reports a scroll view's frame spanning the bars and the safe
 area, not the visible track. In the pinned Settings tree the `CollectionView` frame is the whole screen,
@@ -56,16 +64,17 @@ area, not the visible track. In the pinned Settings tree the `CollectionView` fr
 cannot express visibility, and deleting indicator clipping would return content that is scrolled under
 the chrome. The band is necessary; only *who owns it* was ever in question.
 
-**Visibility ejection needs evidence, and every ejection is recorded.** Most of the engine's 23 removal
-sites delegate semantics or drop decoration — a collapsed row, a duplicate label, a wrapper's content, a
-system indicator — and this ADR does not touch their authority. It governs the four visibility-driven
-sites among them, the scroll band's one and the keyboard band's three, alongside the clip fold's own
-inclusion decision in `geometry-policy.ts`. Of those, the scroll band is the one a weak signal can reach,
-and directional hints are its safe outlet when nothing is the indicator's parent. Every source index ends
-either presented, with its representatives, or removed with a typed reason, which makes the ledger complete
-by construction rather than gated. The existing `presentedIndexesBySourceIndex` in
-`ios-snapshot-engine/semantic-index.ts` is the shape to extend; a second parallel ledger would be a second
-source of truth.
+**Visibility ejection needs evidence, and every ejection must be recorded.** Most of the engine's 23
+removal sites delegate semantics or drop decoration — a collapsed row, a duplicate label, a
+wrapper's content, a system indicator — and this ADR does not touch their authority. It governs the
+four visibility-driven sites among them, the scroll band's one and the keyboard band's three,
+alongside the clip fold's own inclusion decision in `geometry-policy.ts`. Of those, the scroll band
+is the one a weak signal can reach, and directional hints are its safe outlet when nothing is the
+indicator's parent. Every source index must end either presented, with its representatives, or
+removed with a typed reason, which makes the ledger complete by construction rather than gated;
+#2754 step 5 still owes that reason, and `presentedIndexesBySourceIndex` in
+`ios-snapshot-engine/semantic-index.ts` records representatives and no removal reason today. That
+ledger is the shape to extend; a second parallel ledger would be a second source of truth.
 
 ## Refuted alternatives
 
@@ -118,10 +127,12 @@ source of truth.
   upward. So `findScrollIndicatorContainer` returns null when the node is itself a scroll type;
   `runner-presentation.test.ts` pins a scroll host labelled as an indicator leaving its parent list's
   band intact.
-- **macOS is already a second consumer of these rules.** Desktop capture runs the engine through
-  `snapshot-desktop-surface.ts` → `ios-snapshot-runtime.ts` → `publishIosSnapshot`, and its trees carry
-  `ScrollArea`, which neither eligible set admits. The parent-edge rule needs its own decision there
-  before it is reused, not a carry-over from the iOS claim.
+- **macOS is already a second consumer of these rules, and #2759 settled its `ScrollArea`
+  question.** Desktop capture runs the engine through `snapshot-desktop-surface.ts` →
+  `ios-snapshot-runtime.ts` → `publishIosSnapshot`, and its trees carry `ScrollArea`, which neither
+  eligible set admits: a content-bearing one survives eligibility and owns its band; a label-less
+  one is dropped and leaves its indicator with no owner, under-clipping instead of mis-clipping the
+  list. `eligibility-parity.test.ts` pins both outcomes and the TS/Swift eligibility pair.
 - **Ejection inventory precedes any API change.** 23 suppression sites across ten rules, and two of them
   (`scroll`, `transitions`) already rewrite rects on other nodes in the same pass that ejects — the
   combination the proposed API split claimed to make impossible.
diff --git a/docs/adr/README.md b/docs/adr/README.md
index 51e2a8af42..c68b299dc7 100644
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@ -27,7 +27,7 @@
 | [0023 End-State Entry-to-Platform Hop Trace](0023-end-state-hop-trace.md) | the hop counting definition, the ordered `press`/Android and dual-arm `snapshot`/iOS chains, per-hop roles, and the deletion test behind the numbers ADR 0019 and ADR 0022 quote |
 | [0024 Screen Recording — One Coordinator, Two Facts (Proposed)](0024-screen-recording-provable-signal.md) | `record start`/`stop` lifecycle, the export-exists / recorder-stopped split, backend stop-and-collect contract, recovery through the coordinator, the ADR 0019 §5 amendment and the failed-finish cleanup fix |
 | [0025 Foldable Apple Panels — Capture the Lit Panel](0025-foldable-apple-panels.md) | iPhone Duo outer/inner panels, CoreDevice display info as the only screen authority, why `simctl`'s implicit display default captures a black panel, derived (never asserted) pose, and why no pose-control command exists |
-| [0026 Scroll Clip Authority — Ownership Is the Parent Edge (Proposed)](0026-scroll-clip-authority.md) | iOS scroll indicators and the visible band, why ownership is read from the parent edge instead of an ancestor walk, what may remove a node from an interactive snapshot, and ejection dispositions |
+| [0026 Scroll Clip Authority — Ownership Is the Parent Edge](0026-scroll-clip-authority.md) | iOS scroll indicators and the visible band, why ownership is read from the parent edge instead of an ancestor walk, what may remove a node from an interactive snapshot, and ejection dispositions |
 | [0027 Descriptor Root Size vs Eager-Closure Budget (Proposed)](0027-descriptor-root-vs-eager-closure-budget.md) | splitting `packages/command-registry/src/registry.ts`, the ADR-0019 eager-closure module-count budget, and why a byte-neutral hub split is currently unshippable |
 | [0028 Capability-Family Cell Vocabulary — One Runtime Source (Proposed)](0028-capability-family-cell-vocabulary.md) | adding a capability operation family, `UnavailablePlatformRuntimeFacts` / `UNAVAILABLE_CELLS`, `INTERACTOR_OPERATIONS`, and why an eight-package fan-out recurs |
 

From 81aff325b60e274b1e996a6b48e4688d226d5e59 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 24 Sep 2026 17:19:10 +0200
Subject: [PATCH 098/132] fix(ios-runner): one synthesize-then-fallback helper;
 sequence taps use the standalone tap policy (#2865)

* fix(ios-runner): route every synthesized gesture through one fallback helper

A synthesized tap step inside `sequence` resolved its context with the
synthesized-drag policy, so it refused the XCTest coordinate fallback when
accessibility was unavailable and failed outright when no window frame
resolved. A standalone synthesized tap falls back in both cases.

`performSynthesizedGesture` now performs the synthesized gesture, decides the
XCTest coordinate fallback from the gesture kind's policy, and logs the
decision. Selector tap, coordinate tap, sequence tap step, type focus and
drag use it; each site keeps its own XCTest gesture and bookkeeping. A
sequence tap step takes the coordinate-tap policy, and the fallback decision
reads the kind rather than a policy copy on the coordinate context.

Remove the unused `whenAccessibilityHealthy` keyboard policy, the drag
fallback branch that a nil frame could never reach, and the text-entry focus
predicate the helper replaces. Scroll keeps `privateSynthesisRequired`.

Fixes #2788

* fix(ios-runner): route the in-app back tap through the synthesized gesture helper

Pin the sequence tap step fallback at the sequence command response with a
simulator test that forces private tap synthesis to fail while accessibility
is unavailable.

* docs(changelog): note the synthesized sequence tap fallback
---
 .github/workflows/ios.yml                     |  1 +
 CHANGELOG.md                                  | 10 +++
 .../RunnerTests+CommandExecution.swift        | 36 ++++-----
 .../RunnerTests+GestureExecution.swift        | 21 ++---
 .../RunnerTests+Navigation.swift              | 21 ++---
 .../RunnerTests+ScrollDragExecution.swift     | 32 ++------
 .../RunnerTests+SequenceExecution.swift       | 62 +++++----------
 ...RunnerTests+SynthesizedGesturePolicy.swift | 67 +++++++++++-----
 .../RunnerTests+SynthesizedInteraction.swift  |  1 -
 .../RunnerTests+SynthesizedTextEntry.swift    |  7 --
 .../RunnerTests+TypeExecution.swift           | 21 ++---
 .../RunnerTests+CommandExecutionTests.swift   | 28 +++----
 .../RunnerTests+SequenceExecutionTests.swift  | 48 +++++++----
 ...rTests+SynthesizedGesturePolicyTests.swift | 79 ++++++++++++++++++-
 .../RunnerTests+TextEntryPolicyTests.swift    |  9 ---
 .../0011-interaction-guarantee-contract.md    | 11 +--
 16 files changed, 256 insertions(+), 198 deletions(-)

diff --git a/.github/workflows/ios.yml b/.github/workflows/ios.yml
index d04fa8f140..c115474c75 100644
--- a/.github/workflows/ios.yml
+++ b/.github/workflows/ios.yml
@@ -158,6 +158,7 @@ jobs:
             -xctestrun "$XCTESTRUN_PATH" \
             -destination "platform=iOS Simulator,id=${{ steps.ios-simulator.outputs.simulator-udid }}" \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testSinglePointerFlingFallsBackToXCTestCoordinateDragWhenPrivateSynthesisFails \
+            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testSynthesizedSequenceTapFallsBackToXCTestCoordinateTapWhenAccessibilityIsUnavailable \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testRecordStartThrowsTheCaptureRefusalItReceived \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testAlertDispatchResolvesItsOwnModalWithoutCoordinateTapRoutingProbe \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testAlertResolutionCannotBypassRequestedDeadline \
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 63fc667515..8fa3d7b9be 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -35,6 +35,16 @@
   with `observation: "unsettled"`, `wait absent` keeps polling, and the next read captures afresh.
   A failed read also carries `targetActivation` in `error.details`, and a failed interaction now
   keeps the disclosure sentences in its hint.
+  passed. That capture now carries `unsettledGesture`: `is`, `get`, `find`, and `wait` report it (in
+  `error.details` or `data`) with an appended warning, `snapshot` appends the warning, `is absent`
+  refuses with `observation: "unsettled"`, `wait absent` keeps polling, and the next read captures
+  afresh. Click, press, and fill by selector do not disclose it yet. A failed read now also carries
+  `targetActivation` in `error.details`, the same place as `unsettledGesture`.
+- Fixed (ios): a synthesized tap step inside a runner `sequence` (for example `press x y --count N`)
+  now follows the standalone tap's policy instead of its own. When accessibility is unavailable or no
+  app window resolves, the step now falls back to an XCTest coordinate tap instead of failing the
+  step with `UNSUPPORTED_OPERATION`. One helper now owns the synthesize-then-fallback decision at
+  every synthesized tap site (#2788).
 - Fixed (ios): `open` on a local Simulator now waits for the launched app's discovery before it
   decides whether the app is observable. On a loaded host `simctl spawn launchctl list` outlasts one
   1.5 s discovery wait slice, and the launch observation read that slice as an unobservable app, so
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
index 77bdd1a17f..491b7962ad 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
@@ -78,20 +78,15 @@ extension RunnerTests {
               app: activeApp,
               policy: synthesizedGesturePolicy(policyKind)
             )
-            let (timing, outcome) = performGesture(activeApp, idleTimeout: false) {
+            switch performSynthesizedGesture(activeApp, kind: policyKind, context: context, synthesize: {
               synthesizedTapAt(
                 app: activeApp,
                 x: touchPoint.x,
                 y: touchPoint.y,
                 context: context
               )
-            }
-            if case .performed = outcome {
-              logSynthesizedGesturePolicyDecision(
-                kind: policyKind,
-                context: context,
-                fallbackAttempted: false
-              )
+            }) {
+            case .performed(let timing):
               if isTextEntry {
                 waitForTextEntryReadinessAfterTap(app: activeApp, element: element)
               }
@@ -107,13 +102,12 @@ extension RunnerTests {
                   ? match.usedNonHittableFallback
                   : nil
               )
+            case .xctestFallback(let message, let hint):
+              fallback = GestureFallback(strategy: "xctest-coordinate-tap", message: message, hint: hint)
+            case .refused(_, let message, let hint):
+              clearRememberedTextEntryTap()
+              return unsupportedResponse(message: message, hint: hint)
             }
-            logSynthesizedGesturePolicyDecision(
-              kind: policyKind,
-              context: context,
-              fallbackAttempted: true
-            )
-            fallback = gestureFallback(strategy: "xctest-coordinate-tap", from: outcome)
           }
           let (timing, outcome) = performGesture(activeApp) {
             if expectedPoint != nil || match.usedNonHittableFallback {
@@ -172,16 +166,18 @@ extension RunnerTests {
             app: activeApp,
             policy: synthesizedGesturePolicy(policyKind)
           )
-          let (timing, outcome) = performGesture(activeApp, idleTimeout: false) {
+          switch performSynthesizedGesture(activeApp, kind: policyKind, context: context, synthesize: {
             synthesizedTapAt(app: activeApp, x: x, y: y, context: context)
-          }
-          if case .performed = outcome {
-            logSynthesizedGesturePolicyDecision(kind: policyKind, context: context, fallbackAttempted: false)
+          }) {
+          case .performed(let timing):
             rememberTextEntryTap(textInput)
             return gestureResponse(message: "tapped", timing: timing)
+          case .xctestFallback(let message, let hint):
+            fallback = GestureFallback(strategy: "xctest-coordinate-tap", message: message, hint: hint)
+          case .refused(_, let message, let hint):
+            clearRememberedTextEntryTap()
+            return unsupportedResponse(message: message, hint: hint)
           }
-          logSynthesizedGesturePolicyDecision(kind: policyKind, context: context, fallbackAttempted: true)
-          fallback = gestureFallback(strategy: "xctest-coordinate-tap", from: outcome)
         }
         let touchFrame = resolvedTouchVisualizationFrame(app: activeApp, x: x, y: y)
         let (timing, outcome) = performGesture(activeApp) { tapAt(app: activeApp, x: x, y: y) }
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+GestureExecution.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+GestureExecution.swift
index 46d14d17f7..7959acbf94 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+GestureExecution.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+GestureExecution.swift
@@ -25,13 +25,17 @@ extension RunnerTests {
     case .performed:
       return nil
     case .unsupported(let message, let hint):
-      return Response(
-        ok: false,
-        error: ErrorPayload(code: "UNSUPPORTED_OPERATION", message: message, hint: hint)
-      )
+      return unsupportedResponse(message: message, hint: hint)
     }
   }
 
+  func unsupportedResponse(message: String, hint: String?) -> Response {
+    Response(
+      ok: false,
+      error: ErrorPayload(code: "UNSUPPORTED_OPERATION", message: message, hint: hint)
+    )
+  }
+
   /// Optional visualization frame returned with a gesture response.
   enum GestureFrame {
     case none
@@ -45,15 +49,6 @@ extension RunnerTests {
     let hint: String?
   }
 
-  func gestureFallback(strategy: String, from outcome: RunnerInteractionOutcome) -> GestureFallback? {
-    switch outcome {
-    case .performed:
-      return nil
-    case .unsupported(let message, let hint):
-      return GestureFallback(strategy: strategy, message: message, hint: hint)
-    }
-  }
-
 
   /// Runs a gesture action with uniform timing capture. Touch gestures pass `idleTimeout: true`
   /// (the default) to run inside the scroll idle-timeout + quiescence-skip wrapper; synthesis
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Navigation.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Navigation.swift
index a4df398737..da185b037e 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Navigation.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Navigation.swift
@@ -159,17 +159,20 @@ extension RunnerTests {
       app: app,
       policy: synthesizedGesturePolicy(.coordinateTap)
     )?.withReferenceFrame(frame)
-    let synthesized = performGesture(app, idleTimeout: false) {
+    switch performSynthesizedGesture(app, kind: .coordinateTap, context: context, synthesize: {
       synthesizedTapAt(app: app, x: point.x, y: point.y, context: context)
-    }
-    if case .performed = synthesized.outcome {
-      return verifyNavigationFallbackOutcome(app: app, before: before)
-    }
-    let fallback = performGesture(app) {
-      tapAt(app: app, x: point.x, y: point.y)
-    }
-    if case .performed = fallback.outcome {
+    }) {
+    case .performed:
       return verifyNavigationFallbackOutcome(app: app, before: before)
+    case .refused:
+      return .unavailable
+    case .xctestFallback:
+      let fallback = performGesture(app) {
+        tapAt(app: app, x: point.x, y: point.y)
+      }
+      if case .performed = fallback.outcome {
+        return verifyNavigationFallbackOutcome(app: app, before: before)
+      }
     }
 #endif
     return .unavailable
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+ScrollDragExecution.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+ScrollDragExecution.swift
index 022a23d61c..77c896c5ba 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+ScrollDragExecution.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+ScrollDragExecution.swift
@@ -149,19 +149,6 @@ extension RunnerTests {
       context: context
     )
     else {
-      if context?.allowsXCTestCoordinateFallback == true {
-        logSynthesizedGesturePolicyDecision(kind: policyKind, context: context, fallbackAttempted: true)
-        return executeCoordinateDragFallback(
-          activeApp: activeApp,
-          x: x,
-          y: y,
-          x2: x2,
-          y2: y2,
-          durationMs: durationMs,
-          message: message,
-          fallback: nil
-        )
-      }
       logSynthesizedGesturePolicyDecision(kind: policyKind, context: context, fallbackAttempted: false)
       return Response(
         ok: false,
@@ -179,7 +166,7 @@ extension RunnerTests {
       y2: plan.points.y2,
       referenceFrame: plan.referenceFrame
     )
-    let (timing, outcome) = performGesture(activeApp, idleTimeout: false) {
+    switch performSynthesizedGesture(activeApp, kind: policyKind, context: plan.context, synthesize: {
       synthesizedDragAt(
         app: activeApp,
         x: plan.points.x,
@@ -190,13 +177,10 @@ extension RunnerTests {
         profile: profile,
         context: plan.context
       )
-    }
-    if case .performed = outcome {
-      logSynthesizedGesturePolicyDecision(kind: policyKind, context: plan.context, fallbackAttempted: false)
+    }) {
+    case .performed(let timing):
       return gestureResponse(message: message, timing: timing, frame: .drag(dragFrame))
-    }
-    if plan.context.allowsXCTestCoordinateFallback {
-      logSynthesizedGesturePolicyDecision(kind: policyKind, context: plan.context, fallbackAttempted: true)
+    case .xctestFallback(let fallbackMessage, let hint):
       return executeCoordinateDragFallback(
         activeApp: activeApp,
         x: plan.points.x,
@@ -205,11 +189,11 @@ extension RunnerTests {
         y2: plan.points.y2,
         durationMs: durationMs,
         message: message,
-        fallback: gestureFallback(strategy: "xctest-coordinate-drag", from: outcome)
+        fallback: GestureFallback(strategy: "xctest-coordinate-drag", message: fallbackMessage, hint: hint)
       )
+    case .refused(_, let refusalMessage, let hint):
+      return unsupportedResponse(message: refusalMessage, hint: hint)
     }
-    logSynthesizedGesturePolicyDecision(kind: policyKind, context: plan.context, fallbackAttempted: false)
-    return unsupportedResponse(for: outcome)
 #else
     return nil
 #endif
@@ -223,7 +207,7 @@ extension RunnerTests {
     y2: Double,
     durationMs: Double,
     message: String,
-    fallback: GestureFallback?
+    fallback: GestureFallback
   ) -> Response {
     let dragPoints = keyboardAvoidingDragPoints(app: activeApp, x: x, y: y, x2: x2, y2: y2)
     let dragFrame = resolvedDragVisualizationFrame(
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SequenceExecution.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SequenceExecution.swift
index b6ea551520..9bc0481861 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SequenceExecution.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SequenceExecution.swift
@@ -143,51 +143,21 @@ extension RunnerTests {
   ) -> SequenceStepOutcome {
     let x = step.x ?? 0
     let y = step.y ?? 0
-    // Synthesized HID tap fast path mirrors the individual `tap` command (idleTimeout:false, with
-    // a tapAt fallback when synthesis is unsupported), so fusing a jittered tap series does not
-    // change the touch mechanism for these inputs.
-    if step.kind == "tap", step.synthesized == true {
-      let policyKind = SynthesizedGesturePolicyKind.synthesizedDrag
-#if os(iOS)
-      guard let synthesizedContext else {
-        let nowMs = ProcessInfo.processInfo.systemUptime * 1000
-        logSynthesizedGesturePolicyDecision(kind: policyKind, context: nil, fallbackAttempted: false)
-        return SequenceStepOutcome(
-          outcome: .unsupported(
-            message: "synthesized coordinate tap could not resolve a finite coordinate frame",
-            hint: "Retry after the app is foregrounded, or use a plain screenshot to choose coordinates."
-          ),
-          gestureStartUptimeMs: nowMs,
-          gestureEndUptimeMs: nowMs
-        )
-      }
-#endif
-      let (timing, outcome) = performGesture(activeApp, idleTimeout: false) {
+    if let policyKind = synthesizedPolicyKind(forSequenceStep: step) {
+      switch performSynthesizedGesture(activeApp, kind: policyKind, context: synthesizedContext, synthesize: {
         synthesizedTapAt(app: activeApp, x: x, y: y, context: synthesizedContext)
-      }
-      if case .performed = outcome {
-        logSynthesizedGesturePolicyDecision(kind: policyKind, context: synthesizedContext, fallbackAttempted: false)
-        if let pauseMs = step.pauseMs, pauseMs > 0 {
-          sleepFor(min(max(pauseMs, 0), 10000) / 1000.0)
-        }
-        return SequenceStepOutcome(
-          outcome: outcome,
-          gestureStartUptimeMs: timing.gestureStartUptimeMs,
-          gestureEndUptimeMs: timing.gestureEndUptimeMs
-        )
-      }
-#if os(iOS)
-      guard synthesizedContext.allowsXCTestCoordinateFallback else {
-        logSynthesizedGesturePolicyDecision(kind: policyKind, context: synthesizedContext, fallbackAttempted: false)
-        return SequenceStepOutcome(
-          outcome: outcome,
-          gestureStartUptimeMs: timing.gestureStartUptimeMs,
-          gestureEndUptimeMs: timing.gestureEndUptimeMs
+      }) {
+      case .performed(let timing):
+        return finishedSequenceStep(step, timing: timing, outcome: .performed)
+      case .refused(let timing, let message, let hint):
+        return finishedSequenceStep(
+          step,
+          timing: timing,
+          outcome: .unsupported(message: message, hint: hint)
         )
+      case .xctestFallback:
+        break
       }
-      logSynthesizedGesturePolicyDecision(kind: policyKind, context: synthesizedContext, fallbackAttempted: true)
-#endif
-      // Synthesis unsupported (e.g. macOS) — fall through to the drag-based tapAt below.
     }
     let (timing, outcome) = performGesture(activeApp) {
       switch step.kind {
@@ -201,6 +171,14 @@ extension RunnerTests {
         return tapAt(app: activeApp, x: x, y: y)
       }
     }
+    return finishedSequenceStep(step, timing: timing, outcome: outcome)
+  }
+
+  private func finishedSequenceStep(
+    _ step: SequenceStep,
+    timing: (gestureStartUptimeMs: Double, gestureEndUptimeMs: Double),
+    outcome: RunnerInteractionOutcome
+  ) -> SequenceStepOutcome {
     // Sleep AFTER the step — pauseMs is the inter-step gap — but only when the step performed.
     // assembleSequenceExecution stops at the first unsupported outcome, so pausing after a failed
     // step would burn up to 10s of watchdog budget with no following step to separate from.
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SynthesizedGesturePolicy.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SynthesizedGesturePolicy.swift
index 74723a7f44..212d136781 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SynthesizedGesturePolicy.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SynthesizedGesturePolicy.swift
@@ -14,15 +14,12 @@ enum RunnerAccessibilityHealth: String, Equatable {
 
 enum SynthesizedKeyboardPolicy: String, Equatable, Hashable {
   case never
-  case whenAccessibilityHealthy
   case requiredWhenAvailable
 
   func allowsProbe(accessibilityHealth: RunnerAccessibilityHealth) -> Bool {
     switch self {
     case .never:
       return false
-    case .whenAccessibilityHealthy:
-      return accessibilityHealth == .healthy
     case .requiredWhenAvailable:
       return accessibilityHealth != .unavailable
     }
@@ -63,7 +60,6 @@ struct SynthesizedCoordinateContext {
   /// through this same window so geometry and routing can never name different windows.
   let resolvedWindow: XCUIElement
   let keyboardPolicy: SynthesizedKeyboardPolicy
-  let fallbackPolicy: SynthesizedFallbackPolicy
   let accessibilityHealth: RunnerAccessibilityHealth
 
   func withReferenceFrame(_ frame: CGRect) -> SynthesizedCoordinateContext {
@@ -71,15 +67,10 @@ struct SynthesizedCoordinateContext {
       referenceFrame: frame,
       resolvedWindow: resolvedWindow,
       keyboardPolicy: keyboardPolicy,
-      fallbackPolicy: fallbackPolicy,
       accessibilityHealth: accessibilityHealth
     )
   }
 
-  var allowsXCTestCoordinateFallback: Bool {
-    fallbackPolicy.allowsXCTestCoordinateFallback(accessibilityHealth: accessibilityHealth)
-  }
-
   var allowsKeyboardProbe: Bool {
     keyboardPolicy.allowsProbe(accessibilityHealth: accessibilityHealth)
   }
@@ -115,10 +106,22 @@ func shouldProbeCoordinateTapTextInput(xCTestChannelPenalized: Bool) -> Bool {
   !xCTestChannelPenalized
 }
 
-func sequenceHasSynthesizedCoordinateStep(_ steps: [SequenceStep]) -> Bool {
-  steps.contains { step in
-    step.synthesized == true && step.kind == "tap"
-  }
+/// A synthesized `tap` step in a `sequence` is a standalone coordinate tap and follows its policy.
+func synthesizedPolicyKind(forSequenceStep step: SequenceStep) -> SynthesizedGesturePolicyKind? {
+  step.synthesized == true && step.kind == "tap" ? .coordinateTap : nil
+}
+
+/// A synthesized gesture's result for its call site, which owns the XCTest coordinate gesture.
+enum SynthesizedGestureAttempt {
+  case performed(timing: (gestureStartUptimeMs: Double, gestureEndUptimeMs: Double))
+  /// Synthesis failed and the policy allows the call site's XCTest coordinate gesture.
+  case xctestFallback(message: String, hint: String?)
+  /// Synthesis failed and the policy refuses an XCTest coordinate gesture.
+  case refused(
+    timing: (gestureStartUptimeMs: Double, gestureEndUptimeMs: Double),
+    message: String,
+    hint: String?
+  )
 }
 
 extension RunnerTests {
@@ -126,11 +129,36 @@ extension RunnerTests {
     steps: [SequenceStep],
     app: XCUIApplication
   ) -> SynthesizedCoordinateContext? {
-    guard sequenceHasSynthesizedCoordinateStep(steps) else { return nil }
-    return synthesizedCoordinateContext(
-      app: app,
-      policy: synthesizedGesturePolicy(.synthesizedDrag)
+    guard let kind = steps.lazy.compactMap(synthesizedPolicyKind(forSequenceStep:)).first else {
+      return nil
+    }
+    return synthesizedCoordinateContext(app: app, policy: synthesizedGesturePolicy(kind))
+  }
+
+  /// `context` is nil when no window frame resolved; `kind`'s fallback policy then reads the
+  /// runner's current accessibility health.
+  func performSynthesizedGesture(
+    _ app: XCUIApplication,
+    kind: SynthesizedGesturePolicyKind,
+    context: SynthesizedCoordinateContext?,
+    synthesize: () -> RunnerInteractionOutcome
+  ) -> SynthesizedGestureAttempt {
+    let (timing, outcome) = performGesture(app, idleTimeout: false, synthesize)
+    guard case .unsupported(let message, let hint) = outcome else {
+      logSynthesizedGesturePolicyDecision(kind: kind, context: context, fallbackAttempted: false)
+      return .performed(timing: timing)
+    }
+    let fallbackAllowed = synthesizedGesturePolicy(kind).fallbackPolicy.allowsXCTestCoordinateFallback(
+      accessibilityHealth: context?.accessibilityHealth ?? runnerAccessibilityHealth
+    )
+    logSynthesizedGesturePolicyDecision(
+      kind: kind,
+      context: context,
+      fallbackAttempted: fallbackAllowed
     )
+    return fallbackAllowed
+      ? .xctestFallback(message: message, hint: hint)
+      : .refused(timing: timing, message: message, hint: hint)
   }
 
   func logSynthesizedGesturePolicyDecision(
@@ -162,11 +190,12 @@ extension RunnerTests {
       return "AGENT_DEVICE_RUNNER_SYNTHESIZED_GESTURE_POLICY kind=\(kind.rawValue)"
         + " context=unavailable fallbackAttempted=\(fallbackAttempted)"
     }
+    let fallbackPolicy = synthesizedGesturePolicy(kind).fallbackPolicy
     return "AGENT_DEVICE_RUNNER_SYNTHESIZED_GESTURE_POLICY kind=\(kind.rawValue)"
       + " axHealth=\(context.accessibilityHealth.rawValue) frameSource=window"
       + " keyboardPolicy=\(context.keyboardPolicy.rawValue)"
-      + " fallbackPolicy=\(context.fallbackPolicy.rawValue)"
-      + " fallbackAllowed=\(context.allowsXCTestCoordinateFallback)"
+      + " fallbackPolicy=\(fallbackPolicy.rawValue)"
+      + " fallbackAllowed=\(fallbackPolicy.allowsXCTestCoordinateFallback(accessibilityHealth: context.accessibilityHealth))"
       + " fallbackAttempted=\(fallbackAttempted)"
   }
 }
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SynthesizedInteraction.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SynthesizedInteraction.swift
index 1d307ddd91..369f588cf9 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SynthesizedInteraction.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SynthesizedInteraction.swift
@@ -384,7 +384,6 @@ extension RunnerTests {
       referenceFrame: referenceFrame,
       resolvedWindow: window,
       keyboardPolicy: policy.keyboardPolicy,
-      fallbackPolicy: policy.fallbackPolicy,
       accessibilityHealth: health
     )
 #else
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SynthesizedTextEntry.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SynthesizedTextEntry.swift
index 59086f3bd6..0ea1c6e65e 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SynthesizedTextEntry.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SynthesizedTextEntry.swift
@@ -270,11 +270,4 @@ extension RunnerTests {
   ) -> Bool {
     repairMode == .replacement && hasX && hasY && xCTestChannelPenalized
   }
-
-  static func shouldFallbackFromSynthesizedTextEntryFocus(
-    _ outcome: RunnerInteractionOutcome
-  ) -> Bool {
-    if case .unsupported = outcome { return true }
-    return false
-  }
 }
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+TypeExecution.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+TypeExecution.swift
index 2150047869..5ec6f27826 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+TypeExecution.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+TypeExecution.swift
@@ -31,27 +31,20 @@ extension RunnerTests {
         app: activeApp,
         policy: synthesizedGesturePolicy(policyKind)
       )
-      let (_, outcome) = performGesture(activeApp, idleTimeout: false) {
+      switch performSynthesizedGesture(activeApp, kind: policyKind, context: context, synthesize: {
         synthesizedTapAt(app: activeApp, x: x, y: y, context: context)
-      }
-      if Self.shouldFallbackFromSynthesizedTextEntryFocus(outcome) {
-        logSynthesizedGesturePolicyDecision(
-          kind: policyKind,
-          context: context,
-          fallbackAttempted: true
-        )
-      } else {
-        logSynthesizedGesturePolicyDecision(
-          kind: policyKind,
-          context: context,
-          fallbackAttempted: false
-        )
+      }) {
+      case .performed:
         resolvedCoordinateContext = context
         resolvedCoordinateTarget = TextEntryTarget(
           element: nil,
           refreshPoint: CGPoint(x: x, y: y),
           prefersFocusedElement: false
         )
+      case .xctestFallback:
+        break
+      case .refused(_, let message, let hint):
+        return unsupportedResponse(message: message, hint: hint)
       }
     }
 #else
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+CommandExecutionTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+CommandExecutionTests.swift
index 33d3a82a25..af9a99939e 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+CommandExecutionTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+CommandExecutionTests.swift
@@ -10,30 +10,30 @@ private final class RunnerSynthesizedTapFailureStub: NSObject {
     "forced private synthesis failure"
   }
 }
+
+extension RunnerTests {
+  /// Makes private tap synthesis fail until the returned closure restores it.
+  func forceSynthesizedTapFailure() throws -> () -> Void {
+    let selector = NSSelectorFromString("synthesizeTapWithApplication:resolvedWindow:x:y:")
+    let synthesizedTapMethod = try XCTUnwrap(class_getClassMethod(RunnerSynthesizedGesture.self, selector))
+    let failureStubMethod = try XCTUnwrap(class_getClassMethod(RunnerSynthesizedTapFailureStub.self, selector))
+    let originalImplementation = method_getImplementation(synthesizedTapMethod)
+    method_setImplementation(synthesizedTapMethod, method_getImplementation(failureStubMethod))
+    return { method_setImplementation(synthesizedTapMethod, originalImplementation) }
+  }
+}
 #endif
 
 #if AGENT_DEVICE_RUNNER_UNIT_TESTS
 extension RunnerTests {
 #if os(iOS)
   func testSelectorTapFallsBackToXCTestCoordinateWhenPrivateSynthesisFails() throws {
-    let selector = NSSelectorFromString("synthesizeTapWithApplication:resolvedWindow:x:y:")
-    guard
-      let synthesizedTapMethod = class_getClassMethod(RunnerSynthesizedGesture.self, selector),
-      let failureStubMethod = class_getClassMethod(RunnerSynthesizedTapFailureStub.self, selector)
-    else {
-      XCTFail("unable to install synthesized tap failure stub")
-      return
-    }
-    let originalImplementation = method_getImplementation(synthesizedTapMethod)
-    method_setImplementation(
-      synthesizedTapMethod,
-      method_getImplementation(failureStubMethod)
-    )
+    let restoreSynthesizedTap = try forceSynthesizedTapFailure()
     app.launch()
     currentApp = app
     runnerAccessibilityHealth = .healthy
     defer {
-      method_setImplementation(synthesizedTapMethod, originalImplementation)
+      restoreSynthesizedTap()
       invalidateCachedTarget(reason: "unit_test_cleanup")
       app.terminate()
     }
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SequenceExecutionTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SequenceExecutionTests.swift
index a2e0327df6..8535c29ebb 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SequenceExecutionTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SequenceExecutionTests.swift
@@ -57,20 +57,6 @@ extension RunnerTests {
     XCTAssertTrue(response.error?.message.contains("at most 20") ?? false)
   }
 
-  func testSequenceHasSynthesizedCoordinateStep() {
-    XCTAssertTrue(
-      sequenceHasSynthesizedCoordinateStep([
-        sequenceStep(kind: "tap", x: 1, y: 2, synthesized: true),
-      ])
-    )
-    XCTAssertFalse(
-      sequenceHasSynthesizedCoordinateStep([
-        sequenceStep(kind: "tap", x: 1, y: 2),
-        sequenceStep(kind: "doubleTap", x: 1, y: 2, synthesized: true),
-      ])
-    )
-  }
-
   func testAssembleSequencePreservesOrderOnSuccess() {
     let steps = [
       sequenceStep(kind: "tap", x: 1, y: 1),
@@ -151,8 +137,7 @@ extension RunnerTests {
   private func sequenceStep(
     kind: String,
     x: Double?,
-    y: Double? = nil,
-    synthesized: Bool? = nil
+    y: Double? = nil
   ) -> SequenceStep {
     SequenceStep(
       kind: kind,
@@ -160,7 +145,7 @@ extension RunnerTests {
       y: y,
       durationMs: nil,
       pauseMs: nil,
-      synthesized: synthesized
+      synthesized: nil
     )
   }
 
@@ -184,3 +169,32 @@ extension RunnerTests {
   }
 }
 #endif
+
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS && os(iOS)
+extension RunnerTests {
+  func testSynthesizedSequenceTapFallsBackToXCTestCoordinateTapWhenAccessibilityIsUnavailable() throws {
+    let restoreSynthesizedTap = try forceSynthesizedTapFailure()
+    app.launch()
+    currentApp = app
+    defer {
+      restoreSynthesizedTap()
+      invalidateCachedTarget(reason: "unit_test_cleanup")
+      app.terminate()
+    }
+    let label = app.staticTexts["Agent Device Runner"]
+    XCTAssertTrue(label.waitForExistence(timeout: appExistenceTimeout))
+    let point = CGPoint(x: label.frame.midX, y: label.frame.midY)
+    runnerAccessibilityHealth = .unavailable
+    let command = try runnerCommandFixture(
+      #"{"command":"sequence","commandId":"sequence-synthesized-tap-fallback","steps":[{"kind":"tap","x":\#(point.x),"y":\#(point.y),"synthesized":true}]}"#
+    )
+
+    let response = try executeOnMainPrepared(command: command, activeApp: app)
+
+    XCTAssertTrue(response.ok)
+    XCTAssertEqual(response.data?.completedSteps, 1)
+    XCTAssertNil(response.data?.failedStepIndex)
+    XCTAssertEqual(response.data?.sequenceResults?.first?.ok, true)
+  }
+}
+#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SynthesizedGesturePolicyTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SynthesizedGesturePolicyTests.swift
index acb3d9b032..ed7d2cb4ab 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SynthesizedGesturePolicyTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SynthesizedGesturePolicyTests.swift
@@ -58,10 +58,7 @@ extension RunnerTests {
   /// Keyboard-policy semantics only. Which command gets which policy is the table below; a probe
   /// that is merely permitted still costs a live AX fetch, so the two questions stay separate.
   func testSynthesizedKeyboardPolicyAllowsProbeOnlyWhenAccessibilityPermitsIt() {
-    XCTAssertFalse(
-      SynthesizedKeyboardPolicy.whenAccessibilityHealthy
-        .allowsProbe(accessibilityHealth: .unknown)
-    )
+    XCTAssertFalse(SynthesizedKeyboardPolicy.never.allowsProbe(accessibilityHealth: .healthy))
     XCTAssertTrue(
       SynthesizedKeyboardPolicy.requiredWhenAvailable
         .allowsProbe(accessibilityHealth: .unknown)
@@ -101,5 +98,79 @@ extension RunnerTests {
     XCTAssertFalse(shouldProbeCoordinateTapTextInput(xCTestChannelPenalized: true))
   }
 
+  func testOnlySynthesizedSequenceTapStepsTakeTheCoordinateTapPolicy() {
+    XCTAssertEqual(synthesizedPolicyKind(forSequenceStep: sequenceStep("tap", synthesized: true)), .coordinateTap)
+    XCTAssertNil(synthesizedPolicyKind(forSequenceStep: sequenceStep("tap", synthesized: nil)))
+    XCTAssertNil(synthesizedPolicyKind(forSequenceStep: sequenceStep("doubleTap", synthesized: true)))
+    XCTAssertNil(synthesizedPolicyKind(forSequenceStep: sequenceStep("longPress", synthesized: true)))
+  }
+
+  func testFailedCoordinateTapSynthesisFallsBackToXCTestAtEveryAccessibilityHealth() {
+    for health: RunnerAccessibilityHealth in [.unknown, .healthy, .unavailable] {
+      runnerAccessibilityHealth = health
+      for context in [nil, synthesizedGestureTestContext(accessibilityHealth: health)] {
+        let label = "axHealth=\(health.rawValue) context=\(context == nil ? "unresolved" : "resolved")"
+        let attempt = performSynthesizedGesture(
+          app,
+          kind: .coordinateTap,
+          context: context,
+          synthesize: failedSynthesis
+        )
+        XCTAssertEqual(synthesizedGestureRoute(attempt), "xctestFallback", label)
+      }
+    }
+  }
+
+  func testSynthesizedGestureFallbackFollowsItsKindAndTheResolvedAccessibilityHealth() {
+    runnerAccessibilityHealth = .healthy
+    let unavailable = synthesizedGestureTestContext(accessibilityHealth: .unavailable)
+    let unknown = synthesizedGestureTestContext(accessibilityHealth: .unknown)
+    let cases: [(SynthesizedGesturePolicyKind, SynthesizedCoordinateContext?, String)] = [
+      (.scroll, synthesizedGestureTestContext(accessibilityHealth: .healthy), "refused"),
+      (.synthesizedDrag, unavailable, "refused"),
+      (.synthesizedDrag, unknown, "xctestFallback"),
+      (.coordinateTap, unavailable, "xctestFallback"),
+    ]
+    for (kind, context, expected) in cases {
+      let attempt = performSynthesizedGesture(app, kind: kind, context: context, synthesize: failedSynthesis)
+      XCTAssertEqual(synthesizedGestureRoute(attempt), expected, "kind=\(kind.rawValue)")
+      switch attempt {
+      case .xctestFallback(let message, let hint), .refused(_, let message, let hint):
+        XCTAssertEqual(message, "forced private synthesis failure")
+        XCTAssertEqual(hint, "forced hint")
+      case .performed:
+        break
+      }
+      let performed = performSynthesizedGesture(app, kind: kind, context: context) { .performed }
+      XCTAssertEqual(synthesizedGestureRoute(performed), "performed", "kind=\(kind.rawValue)")
+    }
+  }
+
+  private func failedSynthesis() -> RunnerInteractionOutcome {
+    .unsupported(message: "forced private synthesis failure", hint: "forced hint")
+  }
+
+  private func synthesizedGestureRoute(_ attempt: SynthesizedGestureAttempt) -> String {
+    switch attempt {
+    case .performed: return "performed"
+    case .xctestFallback: return "xctestFallback"
+    case .refused: return "refused"
+    }
+  }
+
+  private func synthesizedGestureTestContext(
+    accessibilityHealth: RunnerAccessibilityHealth
+  ) -> SynthesizedCoordinateContext {
+    SynthesizedCoordinateContext(
+      referenceFrame: CGRect(x: 0, y: 0, width: 390, height: 844),
+      resolvedWindow: app.windows.firstMatch,
+      keyboardPolicy: .never,
+      accessibilityHealth: accessibilityHealth
+    )
+  }
+
+  private func sequenceStep(_ kind: String, synthesized: Bool?) -> SequenceStep {
+    SequenceStep(kind: kind, x: 10, y: 20, durationMs: nil, pauseMs: nil, synthesized: synthesized)
+  }
 }
 #endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+TextEntryPolicyTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+TextEntryPolicyTests.swift
index 556dd1aa65..f0563c6476 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+TextEntryPolicyTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+TextEntryPolicyTests.swift
@@ -204,15 +204,6 @@ extension RunnerTests {
   }
 #endif
 
-  func testResolvedCoordinateTextEntryFallsBackWhenSynthesizedFocusIsUnavailable() {
-    XCTAssertFalse(Self.shouldFallbackFromSynthesizedTextEntryFocus(.performed))
-    XCTAssertTrue(
-      Self.shouldFallbackFromSynthesizedTextEntryFocus(
-        .unsupported(message: "private synthesis unavailable", hint: "use XCTest")
-      )
-    )
-  }
-
   func testResolvedCoordinateTextEntryRouteRequiresReplacementCoordinatesAndPenalizedXCTest() {
     let cases: [(TextTypingRepairMode, Bool, Bool, Bool, Bool)] = [
       (.replacement, true, true, false, false),
diff --git a/docs/adr/0011-interaction-guarantee-contract.md b/docs/adr/0011-interaction-guarantee-contract.md
index 51665d3613..4f8d9da027 100644
--- a/docs/adr/0011-interaction-guarantee-contract.md
+++ b/docs/adr/0011-interaction-guarantee-contract.md
@@ -301,13 +301,14 @@ XCTest-coordinate fallback rules stay runner-local in
 `RunnerTests+SynthesizedGesturePolicy.swift`. That Swift policy is the source of
 truth because the current table has only three behaviors:
 
-- coordinate synthesized tap never probes keyboards and may use the coordinate
-  fallback;
+- coordinate synthesized tap, standalone, as a `sequence` step, or as the
+  in-app `back` top-leading tap, never probes keyboards and may use the
+  coordinate fallback;
 - default iOS scroll probes keyboards only after AX is known healthy and must
   not fall back to `XCUICoordinate`;
-- synthesized one-contact `gesture` plans and synthesized sequence tap steps may
-  still use the coordinate fallback before AX health is known, but stop using it
-  once a snapshot stamps AX unavailable.
+- synthesized one-contact `gesture` plans may still use the coordinate fallback
+  before AX health is known, but stop using it once a snapshot stamps AX
+  unavailable.
 
 The non-obvious parts are covered by gated XCTest policy tests instead of a
 cross-language mirror. A future sibling registry should only be introduced once

From bb5089a01d2a158550afd1faea3a78e3220f694c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 24 Sep 2026 17:24:48 +0200
Subject: [PATCH 099/132] fix(ios): find a popover dismiss region in one query
 instead of reading every element (#2901)

* fix(ios): find a popover dismiss region in one query instead of reading every element

alert get/accept/dismiss with no alert walked every descendant of every window,
one XCTest round trip per element plus a retry cycle for each element that
vanished mid-walk. On the WebView lab it outran the 10 s alert budget and kept
the runner main thread busy past 30 s, so the following wait saw RUNNER_BUSY on
every poll until its deadline (smoke:webview-remote-content, #2491).

* refactor(ios): share one dismiss-popup marker rule and widen the crowded-screen margin

The query predicate, the alert-title filter, and the post-activation observation
now all read one pattern. The crowded fixture grows to 500 labels so the absent
alert test fails by a wide margin without the query (282 s against a 5 s cap),
and a new test covers a window that is itself the marker, which the single
containing query also returns.

* chore(gates): run the alert resolution crowded-screen tests in the PR XCTest lane
---
 .github/workflows/ios.yml                     |  3 ++
 CHANGELOG.md                                  |  6 +++
 .../AgentDeviceRunner/AgentDeviceRunnerApp.m  | 23 +++++++++
 .../RunnerTests+Alert.swift                   | 34 +++++++------
 .../RunnerTests+AlertObservation.swift        |  5 +-
 .../UnitTests/RunnerTests+AlertTests.swift    | 50 +++++++++++++++++++
 6 files changed, 103 insertions(+), 18 deletions(-)

diff --git a/.github/workflows/ios.yml b/.github/workflows/ios.yml
index c115474c75..59c74bf5df 100644
--- a/.github/workflows/ios.yml
+++ b/.github/workflows/ios.yml
@@ -201,6 +201,9 @@ jobs:
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testAlertHittableProbeCompletingAfterDeadlineLeavesTheOriginalUntouched \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testAlertActivationIgnoresAnAppThatNeverSettlesBeforeTheDeadline \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testAlertActivationDoesNotWaitOutANotificationBanner \
+            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testAlertResolutionWithoutAnAlertDoesNotReadEveryElementOfTheScreen \
+            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testAlertResolutionFindsADismissPopupMarkerOnACrowdedScreen \
+            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testAlertResolutionFindsAWindowThatIsItselfTheDismissPopupMarker \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testSystemModalProbeSliceSharesAndClampsToPlanDeadline \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testDispatchRecoverySkipsBookkeepingWhileXCTestChannelOccupied \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testBoundedSystemModalProbeTimeoutRecoversThenReleasesOnDrain \
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8fa3d7b9be..6a238a9932 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,12 @@
   the parser read only the old element, so every row resolved no stack at all. Both spellings now
   parse through the same `id`/`ref` resolution, so a profile recorded with an older Xcode reports
   what it did before. (#2860)
+- Fixed (ios): `alert get`, `accept`, or `dismiss` with no alert on screen no longer reads every
+  element of the app to look for a popover's dismiss region. That walk cost one XCTest round trip
+  per element, plus XCTest's retry cycle for each element that vanished mid-walk. On a loading
+  WebView it outran the 10 s alert budget and kept the runner's main thread busy for more than 30 s
+  after the command failed, so later commands failed with `RUNNER_BUSY`. The dismiss region is now
+  found with one predicate query per window set. (#2491)
 - Changed (apple): a read-only runner command is resent inside the same request only when the
   runner refused it as `RUNNER_BUSY`. Before, any `COMMAND_FAILED` carrying `details.retriable:
   true` was sent up to three times. That flag tells a caller's own poll, such as `wait`, to try
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunner/AgentDeviceRunnerApp.m b/apple/runner/AgentDeviceRunner/AgentDeviceRunner/AgentDeviceRunnerApp.m
index 08da7d0762..b9cd0b9005 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunner/AgentDeviceRunnerApp.m
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunner/AgentDeviceRunnerApp.m
@@ -295,6 +295,24 @@ - (void)viewDidLoad {
     ]];
   }
 
+  if ([NSProcessInfo.processInfo.arguments containsObject:@"--agent-device-crowded-screen"]) {
+    for (NSUInteger row = 0; row < 500; row++) {
+      UILabel *rowLabel = [[UILabel alloc] initWithFrame:CGRectMake(0, 60 + (row % 30) * 24, 400, 16)];
+      rowLabel.text = [NSString stringWithFormat:@"Crowded row %lu", (unsigned long)row];
+      rowLabel.accessibilityIdentifier = [NSString stringWithFormat:@"agent-device-crowded-row-%lu", (unsigned long)row];
+      [self.view addSubview:rowLabel];
+    }
+  }
+
+  BOOL markedButton = [NSProcessInfo.processInfo.arguments containsObject:@"--agent-device-dismiss-popup"];
+  if (markedButton || [NSProcessInfo.processInfo.arguments containsObject:@"--agent-device-dismiss-popup-window"]) {
+    UIButton *dismissRegion = [UIButton buttonWithType:UIButtonTypeSystem];
+    dismissRegion.accessibilityIdentifier = markedButton ? @" Dismiss Popup " : @"agent-device-close-popover";
+    [dismissRegion setTitle:@"Close popover" forState:UIControlStateNormal];
+    dismissRegion.frame = CGRectMake(40, 40, 200, 44);
+    [self.view addSubview:dismissRegion];
+  }
+
   if ([NSProcessInfo.processInfo.arguments containsObject:@"--agent-device-selector-read-regression"]) {
     NSString *const duplicateIdentifier = @"agent-device-selector-read-duplicate";
 
@@ -338,6 +356,11 @@ - (void)scene:(UIScene *)scene
 
   self.window = [[UIWindow alloc] initWithWindowScene:(UIWindowScene *)scene];
   self.window.rootViewController = [[AgentDeviceRunnerViewController alloc] init];
+#if TARGET_OS_IOS
+  if ([NSProcessInfo.processInfo.arguments containsObject:@"--agent-device-dismiss-popup-window"]) {
+    self.window.accessibilityIdentifier = @"Dismiss popup";
+  }
+#endif
   [self.window makeKeyAndVisible];
 }
 
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Alert.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Alert.swift
index 60df7eea72..c7bc8312fc 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Alert.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Alert.swift
@@ -161,22 +161,26 @@ extension RunnerTests {
     elements.first { isVisibleElement($0) }
   }
 
+  /// The marker is matched inside XCTest's query, so the screen is read once per query. Reading each
+  /// descendant instead costs one round trip per element, and on a screen whose tree changes while
+  /// it is read (a loading web view) each vanished element adds XCTest's retry cycle. `containing`
+  /// also matches a window that is itself the marker.
   private func firstDismissPopupWindow(in app: XCUIApplication) -> XCUIElement? {
-    safeElementsQuery {
-      app.windows.allElementsBoundByIndex
-    }.first { window in
-      if !isVisibleElement(window) { return false }
-      if isDismissPopupMarker(window.label) || isDismissPopupMarker(window.identifier) {
-        return true
-      }
-      return safeElementsQuery {
-        window.descendants(matching: .any).allElementsBoundByIndex
-      }.contains { descendant in
-        isDismissPopupMarker(descendant.label) || isDismissPopupMarker(descendant.identifier)
-      }
-    }
+    firstExistingElement(in: safeElementsQuery {
+      app.windows.containing(Self.dismissPopupMarker).allElementsBoundByIndex
+    })
   }
 
+  /// The one definition of a popover's dismiss region: a label or identifier that reads "dismiss
+  /// popup", in any case, with any surrounding whitespace. XCTest queries take it as a format predicate.
+  private static let dismissPopupMarkerPattern = #"\s*dismiss popup\s*"#
+  private static let dismissPopupMarker = NSPredicate(
+    format: "label MATCHES[c] %@ OR identifier MATCHES[c] %@",
+    dismissPopupMarkerPattern,
+    dismissPopupMarkerPattern
+  )
+  private static let dismissPopupMarkerText = NSPredicate(format: "SELF MATCHES[c] %@", dismissPopupMarkerPattern)
+
   private func chooseAlertButton(_ buttons: [XCUIElement], action: String) -> XCUIElement? {
     if action == "accept" {
       if let accept = buttons.first(where: { isAcceptButton($0.label) }) {
@@ -285,7 +289,7 @@ extension RunnerTests {
     return hittable
   }
 
-  private func isDismissPopupMarker(_ label: String) -> Bool {
-    label.trimmingCharacters(in: .whitespacesAndNewlines).caseInsensitiveCompare("dismiss popup") == .orderedSame
+  func isDismissPopupMarker(_ text: String) -> Bool {
+    Self.dismissPopupMarkerText.evaluate(with: text)
   }
 }
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+AlertObservation.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+AlertObservation.swift
index f6d4cb5335..6ef66572c9 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+AlertObservation.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+AlertObservation.swift
@@ -68,9 +68,8 @@ extension RunnerTests {
   }
 
   private func containsDismissPopupMarker(_ snapshot: XCUIElementSnapshot) -> Bool {
-    [snapshot.label, snapshot.identifier].contains {
-      $0.trimmingCharacters(in: .whitespacesAndNewlines).caseInsensitiveCompare("dismiss popup") == .orderedSame
-    } || snapshot.children.contains { containsDismissPopupMarker($0) }
+    [snapshot.label, snapshot.identifier].contains { isDismissPopupMarker($0) } ||
+      snapshot.children.contains { containsDismissPopupMarker($0) }
   }
 
   private func alertPresentation(_ snapshot: XCUIElementSnapshot) -> RunnerAlertPresentation {
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+AlertTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+AlertTests.swift
index 1beb0bec9d..c5c18f6140 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+AlertTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+AlertTests.swift
@@ -7,3 +7,53 @@ extension RunnerTests {
   }
 }
 #endif
+
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS && os(iOS)
+extension RunnerTests {
+  func testAlertResolutionWithoutAnAlertDoesNotReadEveryElementOfTheScreen() throws {
+    launchCrowdedScreen(extraArguments: [])
+    defer { terminateCrowdedScreen() }
+
+    let startedAt = Date()
+    XCTAssertNil(resolveAlert(app: app, deadline: startedAt.addingTimeInterval(RunnerTests.defaultAlertCommandTimeout)))
+    // Half the command's own budget: an absent alert answers ALERT_NOT_FOUND well inside it on a
+    // contended host, while a read per element spends it many times over on this screen.
+    XCTAssertLessThan(Date().timeIntervalSince(startedAt), RunnerTests.defaultAlertCommandTimeout / 2)
+  }
+
+  func testAlertResolutionFindsADismissPopupMarkerOnACrowdedScreen() throws {
+    launchCrowdedScreen(extraArguments: ["--agent-device-dismiss-popup"])
+    defer { terminateCrowdedScreen() }
+
+    let alert = try XCTUnwrap(
+      resolveAlert(app: app, deadline: Date().addingTimeInterval(RunnerTests.defaultAlertCommandTimeout))
+    )
+    XCTAssertEqual(alert.source, .dismissPopup)
+    XCTAssertEqual(alert.root.elementType, .window)
+    XCTAssertTrue(alert.buttons.contains { $0.identifier == " Dismiss Popup " })
+  }
+
+  func testAlertResolutionFindsAWindowThatIsItselfTheDismissPopupMarker() throws {
+    launchCrowdedScreen(extraArguments: ["--agent-device-dismiss-popup-window"])
+    defer { terminateCrowdedScreen() }
+
+    let alert = try XCTUnwrap(
+      resolveAlert(app: app, deadline: Date().addingTimeInterval(RunnerTests.defaultAlertCommandTimeout))
+    )
+    XCTAssertEqual(alert.source, .dismissPopup)
+    XCTAssertEqual(alert.root.identifier, "Dismiss popup")
+    XCTAssertTrue(alert.buttons.contains { $0.identifier == "agent-device-close-popover" })
+  }
+
+  private func launchCrowdedScreen(extraArguments: [String]) {
+    app.launchArguments = ["--agent-device-crowded-screen"] + extraArguments
+    app.launch()
+    XCTAssertTrue(app.staticTexts["agent-device-crowded-row-499"].waitForExistence(timeout: appExistenceTimeout))
+  }
+
+  private func terminateCrowdedScreen() {
+    invalidateCachedTarget(reason: "unit_test_cleanup")
+    app.terminate()
+  }
+}
+#endif

From 86d719dc331abf1fd69a3c4b1e0191faa2db8f30 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 24 Sep 2026 17:24:49 +0200
Subject: [PATCH 100/132] test(ios): wait out the launch an accepted deep-link
 confirmation releases (#2902)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* test(ios): wait out the launch an accepted deep-link confirmation releases

The smoke automation scenario accepted SpringBoard's "Open in …?" prompt and then gave the
route one 10 s wait. On a loaded host the released launch reached the foreground 20.7 s after
the Open tap (CI run 35991523779; 27.4 s locally), so every read answered the retriable
APP_NOT_RUNNING and the step failed although the app later rendered the deep-linked route.

The deep-link confirmation helper moves to its own module and keys every step on the typed
details.runnerErrorCode: only a destination wait that ends on APP_NOT_RUNNING probes for the
confirmation or earns another wait, up to four 15 s waits. Any other miss returns to the
caller's own destination assertion, and the alert probe never queries a rendered screen.

Refs #2491

* fix(ios-e2e): recover readable deep-link timeouts
---
 ...mulator-e2e-deep-link-confirmation.test.ts | 170 ++++++++++++++++++
 .../live-automation-scenario.ts               |  44 +----
 .../live-deep-link-confirmation.ts            |  82 +++++++++
 .../live-snapshot-depth-frontier.ts           |   2 +-
 .../live-webview-remote-content.ts            |   2 +-
 5 files changed, 255 insertions(+), 45 deletions(-)
 create mode 100644 test/integration/ios-simulator-e2e-deep-link-confirmation.test.ts
 create mode 100644 test/integration/ios-simulator-e2e/live-deep-link-confirmation.ts

diff --git a/test/integration/ios-simulator-e2e-deep-link-confirmation.test.ts b/test/integration/ios-simulator-e2e-deep-link-confirmation.test.ts
new file mode 100644
index 0000000000..a07a38db8e
--- /dev/null
+++ b/test/integration/ios-simulator-e2e-deep-link-confirmation.test.ts
@@ -0,0 +1,170 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import type { CliJsonResult } from './cli-json.ts';
+import {
+  answerDeepLinkConfirmation,
+  type DeepLinkConfirmationDevice,
+} from './ios-simulator-e2e/live-deep-link-confirmation.ts';
+
+function result(status: number, json?: unknown): CliJsonResult {
+  return { json, status, stderr: '', stdout: '' };
+}
+
+const LANDED = result(0, { success: true });
+const LAUNCH_PENDING = result(1, {
+  error: {
+    code: 'COMMAND_FAILED',
+    details: { reason: 'wait_capture_stalled', runnerErrorCode: 'APP_NOT_RUNNING' },
+  },
+});
+const WRONG_ROUTE = result(1, {
+  error: { code: 'COMMAND_FAILED', details: { reason: 'wait_target_absent' } },
+});
+const READABLE_TIMEOUT = result(1, {
+  error: {
+    code: 'COMMAND_FAILED',
+    details: { reason: 'wait_deadline_exceeded', readableCaptures: 5, captureTruncated: true },
+  },
+});
+const OPEN_PROMPT = result(0, {
+  data: { message: 'Open in “Agent Device Tester”?', items: ['Cancel', 'Open'] },
+});
+const NO_ALERT = result(1, { error: { code: 'COMMAND_FAILED' } });
+
+/** A simulator whose destination waits and alert probes answer in the order given. */
+function simulator(destinationWaits: CliJsonResult[], alerts: CliJsonResult[] = [OPEN_PROMPT]) {
+  const log: string[] = [];
+  const device: DeepLinkConfirmationDevice = {
+    waitForDestination: async (step) => {
+      log.push(step);
+      const next = destinationWaits.shift();
+      assert.ok(next, `unexpected destination wait: ${step}`);
+      return next;
+    },
+    inspectAlert: async () => {
+      log.push('alert get');
+      const next = alerts.shift();
+      assert.ok(next, 'unexpected alert probe');
+      return next;
+    },
+    acceptAlert: async () => {
+      log.push('alert accept');
+    },
+  };
+  return { device, log };
+}
+
+const waits = (log: string[]) => log.filter((step) => step.startsWith('wait for')).length;
+
+test('a destination that arrives never probes for the confirmation', async () => {
+  const { device, log } = simulator([LANDED]);
+
+  await answerDeepLinkConfirmation(device);
+
+  assert.deepEqual(log, ['wait for the deep-link destination (1/5)']);
+});
+
+test('a readable destination timeout still answers a real Open confirmation', async () => {
+  const { device, log } = simulator([READABLE_TIMEOUT, LANDED]);
+
+  await answerDeepLinkConfirmation(device);
+
+  assert.deepEqual(log, [
+    'wait for the deep-link destination (1/5)',
+    'alert get',
+    'alert accept',
+    'wait for the deep-link destination (2/5)',
+  ]);
+});
+
+test('a readable no-match that answers Open waits for the released launch', async () => {
+  const { device, log } = simulator([WRONG_ROUTE, LAUNCH_PENDING, LANDED]);
+
+  await answerDeepLinkConfirmation(device);
+
+  assert.deepEqual(log, [
+    'wait for the deep-link destination (1/5)',
+    'alert get',
+    'alert accept',
+    'wait for the deep-link destination (2/5)',
+    'wait for the deep-link destination (3/5)',
+  ]);
+});
+
+test('a truncated capture retries for four bounded waits without accepting a missing alert', async () => {
+  const { device, log } = simulator(
+    [READABLE_TIMEOUT, READABLE_TIMEOUT, READABLE_TIMEOUT, READABLE_TIMEOUT, LANDED],
+    [NO_ALERT, NO_ALERT, NO_ALERT, NO_ALERT],
+  );
+
+  await answerDeepLinkConfirmation(device);
+
+  assert.equal(waits(log), 5);
+  assert.equal(log.filter((step) => step === 'alert get').length, 4);
+  assert.equal(log.includes('alert accept'), false);
+});
+
+test('the launch an accepted confirmation releases is waited for until it lands', async () => {
+  // CI run 35991523779: the app reached the foreground 20.7 s after `alert accept` tapped Open.
+  const { device, log } = simulator([LAUNCH_PENDING, LAUNCH_PENDING, LAUNCH_PENDING, LANDED]);
+
+  await answerDeepLinkConfirmation(device);
+
+  assert.deepEqual(log, [
+    'wait for the deep-link destination (1/5)',
+    'alert get',
+    'alert accept',
+    'wait for the deep-link destination (2/5)',
+    'wait for the deep-link destination (3/5)',
+    'wait for the deep-link destination (4/5)',
+  ]);
+});
+
+test('a readable miss probes once and leaves a wrong route to the caller', async () => {
+  const { device, log } = simulator([WRONG_ROUTE], [NO_ALERT]);
+
+  await answerDeepLinkConfirmation(device);
+
+  assert.deepEqual(log, ['wait for the deep-link destination (1/5)', 'alert get']);
+});
+
+test('after the accept, a readable no-match still gets a bounded launch wait', async () => {
+  const { device, log } = simulator([LAUNCH_PENDING, WRONG_ROUTE, LANDED]);
+
+  await answerDeepLinkConfirmation(device);
+
+  assert.equal(waits(log), 3);
+});
+
+test('a confirmation that appears late is still answered once', async () => {
+  const { device, log } = simulator(
+    [LAUNCH_PENDING, LAUNCH_PENDING, LAUNCH_PENDING, LANDED],
+    [NO_ALERT, OPEN_PROMPT],
+  );
+
+  await answerDeepLinkConfirmation(device);
+
+  assert.deepEqual(
+    log.filter((step) => step.startsWith('alert')),
+    ['alert get', 'alert get', 'alert accept'],
+  );
+});
+
+test('the wait budget is bounded when the app never starts', async () => {
+  const { device, log } = simulator(Array.from({ length: 5 }, () => LAUNCH_PENDING));
+
+  await answerDeepLinkConfirmation(device);
+
+  assert.equal(waits(log), 5);
+});
+
+test('a prompt that is not the deep-link confirmation is never accepted', async () => {
+  const { device, log } = simulator(
+    [LAUNCH_PENDING],
+    [result(0, { data: { message: 'Allow notifications?', items: ['Allow'] } })],
+  );
+
+  await assert.rejects(answerDeepLinkConfirmation(device));
+  assert.equal(log.includes('alert accept'), false);
+});
diff --git a/test/integration/ios-simulator-e2e/live-automation-scenario.ts b/test/integration/ios-simulator-e2e/live-automation-scenario.ts
index dfe77d2eac..6b3168a0f3 100644
--- a/test/integration/ios-simulator-e2e/live-automation-scenario.ts
+++ b/test/integration/ios-simulator-e2e/live-automation-scenario.ts
@@ -11,19 +11,13 @@ import {
   assertJsonContains,
   assertWaitText,
 } from './live-assertions.ts';
+import { acceptDeepLinkConfirmationIfPresent } from './live-deep-link-confirmation.ts';
 import { clearStateLaunchUrlMaestroFlow } from './live-fixtures.ts';
 import { type LiveContext, runStep, verifyBehavior, verifyCommand } from './live-harness.ts';
 
 const C = PUBLIC_COMMANDS;
 const ALERT_WAIT_TIMEOUT = String(DEFAULT_ALERT_TIMEOUT_MS);
 const FIXTURE_HOME_TITLE = 'Agent Device Tester';
-/**
- * Deliberately generous. This budget decides whether the alert probe below runs at all, so it must
- * outlast the slowest honest route mount on a cold CI simulator — the WebView lab took over 2.5 s
- * there while rendering correctly. Waiting longer costs nothing when a confirmation really is up,
- * because the route never renders until it is accepted; being too short costs the whole scenario.
- */
-const DEEP_LINK_DESTINATION_WAIT_MS = '15000';
 /** The Automation lab's own first landmark; see `acceptDeepLinkConfirmationIfPresent`. */
 const AUTOMATION_LAB_LANDMARK = ['text', 'Automation lab'] as const;
 const AUTOMATION_DEEP_LINK =
@@ -253,42 +247,6 @@ async function assertClearStateLaunchUrl(context: LiveContext): Promise<void> {
   await assertElementText(context, 'id="automation-event-payload"', '{"source":"deep-link"}');
 }
 
-/**
- * iOS sometimes puts an "Open in <app>?" confirmation in front of a custom-scheme deep link, so a
- * scenario that launched one must accept it before asserting anything. `destination` is the `wait`
- * predicate for the route's own first landmark, and it decides whether the alert probe runs at all:
- * a landmark that arrived proves no confirmation is in the way. Each caller passes its own, because
- * a shared landmark never matches off its route and sends every caller into the probe — and
- * `alert get` against a live WKWebView screen is the XCTest query that exceeds the runner's
- * execution watchdog, leaving every later command refused as `RUNNER_BUSY` (#2484 follow-up). The
- * landmark must therefore be a native node the route renders before its content, and the budget
- * above must outlast a cold mount, so the probe is reached only when something really is blocking.
- */
-export async function acceptDeepLinkConfirmationIfPresent(
-  context: LiveContext,
-  destination: readonly string[],
-): Promise<void> {
-  const arrived = await runStep(
-    context,
-    'wait for deep-link destination before inspecting system UI',
-    ['wait', ...destination, DEEP_LINK_DESTINATION_WAIT_MS],
-    { allowFailure: true },
-  );
-  if (arrived.status === 0) return;
-
-  const alert = await runStep(context, 'inspect delayed deep-link system alert', ['alert', 'get'], {
-    allowFailure: true,
-  });
-  if (alert.status !== 0) return;
-  const alertInfo = alert.json?.data;
-  assert.match(String(alertInfo?.message), /^Open in\b/, JSON.stringify(alert.json));
-  assert.ok(
-    Array.isArray(alertInfo?.items) && alertInfo.items.includes('Open'),
-    JSON.stringify(alert.json),
-  );
-  await runStep(context, 'accept deep-link confirmation', ['alert', 'accept']);
-}
-
 async function openAutomationDeepLink(context: LiveContext, step: string): Promise<void> {
   await runStep(context, step, [
     'open',
diff --git a/test/integration/ios-simulator-e2e/live-deep-link-confirmation.ts b/test/integration/ios-simulator-e2e/live-deep-link-confirmation.ts
new file mode 100644
index 0000000000..cbeb4a4e64
--- /dev/null
+++ b/test/integration/ios-simulator-e2e/live-deep-link-confirmation.ts
@@ -0,0 +1,82 @@
+import assert from 'node:assert/strict';
+
+import type { CliJsonResult } from '../cli-json.ts';
+import { type LiveContext, runStep } from './live-harness.ts';
+
+/** One destination wait; generous because the WebView lab took over 2.5 s to mount on cold CI. */
+const DEEP_LINK_DESTINATION_WAIT_MS = '15000';
+/**
+ * One wait can find the confirmation holding the launch; four more cover its release or a stalled
+ * runner restart. The answered launch usually reaches the foreground within 3 s, but a loaded host
+ * held it for 20.7 s (CI run 35991523779) and 27.4 s (a local run).
+ */
+const DESTINATION_WAITS = 5;
+/** `details.runnerErrorCode` of a read the runner refused because the session app is not running. */
+const APP_NOT_RUNNING = 'APP_NOT_RUNNING';
+
+export type DeepLinkConfirmationDevice = {
+  waitForDestination: (step: string) => Promise<CliJsonResult>;
+  inspectAlert: () => Promise<CliJsonResult>;
+  acceptAlert: () => Promise<unknown>;
+};
+
+/**
+ * iOS can hold a custom-scheme deep link behind an "Open in <app>?" confirmation. `destination` is
+ * the `wait` predicate for the route's own first landmark, a native node the route renders before
+ * its content.
+ */
+export function acceptDeepLinkConfirmationIfPresent(
+  context: LiveContext,
+  destination: readonly string[],
+): Promise<void> {
+  return answerDeepLinkConfirmation({
+    waitForDestination: (step) =>
+      runStep(context, step, ['wait', ...destination, DEEP_LINK_DESTINATION_WAIT_MS], {
+        allowFailure: true,
+      }),
+    inspectAlert: () =>
+      runStep(context, 'inspect delayed deep-link system alert', ['alert', 'get'], {
+        allowFailure: true,
+      }),
+    acceptAlert: () => runStep(context, 'accept deep-link confirmation', ['alert', 'accept']),
+  });
+}
+
+/**
+ * A readable destination timeout can still leave the launch behind a system confirmation. Probe
+ * once per miss until it is answered; a truncated or stalled capture then gets another bounded
+ * wait, while a readable wrong-route miss without a prompt goes to the caller's assertion.
+ */
+export async function answerDeepLinkConfirmation(
+  device: DeepLinkConfirmationDevice,
+): Promise<void> {
+  let answered = false;
+  for (let wait = 1; wait <= DESTINATION_WAITS; wait += 1) {
+    const arrived = await device.waitForDestination(
+      `wait for the deep-link destination (${wait}/${DESTINATION_WAITS})`,
+    );
+    if (arrived.status === 0) return;
+    const details = arrived.json?.error?.details;
+    const launchPending = details?.runnerErrorCode === APP_NOT_RUNNING;
+    const reason = details?.reason;
+    const readableMiss = reason === 'wait_target_absent' || reason === 'wait_deadline_exceeded';
+    const interruptedCapture =
+      reason === 'wait_capture_stalled' || reason === 'wait_runner_restart_exhausted';
+    if (!launchPending && !readableMiss && !interruptedCapture) return;
+    if (!answered) answered = await acceptOpenConfirmation(device);
+    if (!answered && reason === 'wait_target_absent') return;
+  }
+}
+
+async function acceptOpenConfirmation(device: DeepLinkConfirmationDevice): Promise<boolean> {
+  const alert = await device.inspectAlert();
+  if (alert.status !== 0) return false;
+  const alertInfo = alert.json?.data;
+  assert.match(String(alertInfo?.message), /^Open in\b/, JSON.stringify(alert.json));
+  assert.ok(
+    Array.isArray(alertInfo?.items) && alertInfo.items.includes('Open'),
+    JSON.stringify(alert.json),
+  );
+  await device.acceptAlert();
+  return true;
+}
diff --git a/test/integration/ios-simulator-e2e/live-snapshot-depth-frontier.ts b/test/integration/ios-simulator-e2e/live-snapshot-depth-frontier.ts
index 84997a70d9..ce21123612 100644
--- a/test/integration/ios-simulator-e2e/live-snapshot-depth-frontier.ts
+++ b/test/integration/ios-simulator-e2e/live-snapshot-depth-frontier.ts
@@ -6,7 +6,7 @@ import {
   type LiveSnapshotNode as SnapshotNode,
   snapshotNodes,
 } from './live-assertions.ts';
-import { acceptDeepLinkConfirmationIfPresent } from './live-automation-scenario.ts';
+import { acceptDeepLinkConfirmationIfPresent } from './live-deep-link-confirmation.ts';
 import { type LiveContext, runStep, verifyBehavior } from './live-harness.ts';
 
 const VISIBLE_DEPTH_DEEP_LINK = 'agent-device-test-app:///snapshot-depth';
diff --git a/test/integration/ios-simulator-e2e/live-webview-remote-content.ts b/test/integration/ios-simulator-e2e/live-webview-remote-content.ts
index 711f4fab6f..484ab49c0c 100644
--- a/test/integration/ios-simulator-e2e/live-webview-remote-content.ts
+++ b/test/integration/ios-simulator-e2e/live-webview-remote-content.ts
@@ -1,7 +1,7 @@
 import assert from 'node:assert/strict';
 
 import { assertWaitText, snapshotNodes } from './live-assertions.ts';
-import { acceptDeepLinkConfirmationIfPresent } from './live-automation-scenario.ts';
+import { acceptDeepLinkConfirmationIfPresent } from './live-deep-link-confirmation.ts';
 import { type LiveContext, runStep, verifyBehavior } from './live-harness.ts';
 
 const WEBVIEW_LAB_DEEP_LINK = 'agent-device-test-app:///webview';

From efce35265063faf39b4fc26eb97dcd2173668889 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Oskar=20Kwa=C5=9Bniewski?= <oskar@okwasniewski.com>
Date: Thu, 24 Sep 2026 18:08:56 +0200
Subject: [PATCH 101/132] fix(android): carry the heading flag and the role
 description on the snapshot node (#2915)

React Native puts a header, a tab, a tab list, a radio group, a link, or a menu on a plain android.view.View and tells the accessibility tree what it is through two facts: the heading flag and the role description androidx stores in the node extras. The helper serialized neither, and the host reads only the helper's XML, so every one of them was a nameless View to an agent and to `get attrs`. The helper now writes `heading` when the node reports it (API 28 or later) and `role-description` when the app set one; the parser, the Android hierarchy node, and the published snapshot node carry them to `get attrs`, the unchanged-snapshot comparison, and the selector digest. The class stays the type, and snapshot text is unchanged: mapping a description to a role is the consumer's call.
---
 CHANGELOG.md                                  |  7 +++
 .../snapshothelper/AccessibilityTreeXml.java  | 15 +++++
 packages/kernel/src/snapshot.ts               |  4 ++
 .../__tests__/ui-hierarchy-role-facts.test.ts | 60 +++++++++++++++++++
 .../src/ui-hierarchy-builder.ts               |  2 +
 .../platform-android/src/ui-hierarchy-node.ts |  2 +
 packages/platform-android/src/ui-hierarchy.ts | 17 ++++++
 src/__tests__/android-ui-hierarchy.test.ts    | 36 +++++++++++
 .../capture/runtime/snapshot-unchanged.ts     |  2 +
 src/daemon/response-views.ts                  |  2 +
 website/docs/docs/snapshots.md                | 12 +++-
 11 files changed, 156 insertions(+), 3 deletions(-)
 create mode 100644 packages/platform-android/src/__tests__/ui-hierarchy-role-facts.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6a238a9932..7ee85fc461 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+- Fixed (android): snapshot nodes and `get attrs` carry the accessibility `heading` flag and the
+  `roleDescription` an app set on a node. React Native puts a header, a tab, a tab list, a link, or a
+  menu on a plain `android.view.View` and tells the accessibility tree what it is through these two
+  facts; the helper never serialized either, so every one of them was a nameless `View` to an agent.
+  The helper now writes `heading` when the node reports it (API 28 or later) and `role-description`
+  when the app set one, and the parser, the Android hierarchy node, and the published snapshot node
+  carry them to `get attrs` and the selector digest. The class stays the `type`.
 - Fixed (ios): `perf cpu profile report --kind xctrace` on Xcode 27 no longer fails with
   `Apple xctrace CPU report contained no samples` on a trace that holds thousands of samples. Xcode
   27 exports each `time-profile` sample stack as `<tagged-backtrace>` instead of `<backtrace>`, and
diff --git a/android/snapshot-helper/src/main/java/com/callstack/agentdevice/snapshothelper/AccessibilityTreeXml.java b/android/snapshot-helper/src/main/java/com/callstack/agentdevice/snapshothelper/AccessibilityTreeXml.java
index 0753f242d8..802cd38bb1 100644
--- a/android/snapshot-helper/src/main/java/com/callstack/agentdevice/snapshothelper/AccessibilityTreeXml.java
+++ b/android/snapshot-helper/src/main/java/com/callstack/agentdevice/snapshothelper/AccessibilityTreeXml.java
@@ -53,6 +53,8 @@ static void appendNode(
     appendAttribute(xml, "class", node.getClassName());
     appendNonEmptyAttribute(xml, "package", node.getPackageName());
     appendNonEmptyAttribute(xml, "content-desc", node.getContentDescription());
+    appendNonEmptyAttribute(xml, "role-description", roleDescription(node));
+    appendTrueAttribute(xml, "heading", isHeading(node));
     appendAttribute(xml, "visible-to-user", Boolean.toString(node.isVisibleToUser()));
     appendDrawingOrderAttribute(xml, node);
     appendTrueAttribute(xml, "clickable", node.isClickable());
@@ -146,6 +148,19 @@ private static void appendTrueAttribute(StringBuilder xml, String name, boolean
     }
   }
 
+  // The platform node has no role description getter: androidx writes the value an app set
+  // (AccessibilityNodeInfoCompat.setRoleDescription) into the node extras under this key, and
+  // TalkBack reads it from there.
+  private static CharSequence roleDescription(AccessibilityNodeInfo node) {
+    return node.getExtras().getCharSequence("AccessibilityNodeInfo.roleDescription");
+  }
+
+  // isHeading() arrived in API 28. Older releases keep the compat flag in an extras bit this
+  // helper does not read, so a heading on API 23-27 reports nothing.
+  private static boolean isHeading(AccessibilityNodeInfo node) {
+    return Build.VERSION.SDK_INT >= Build.VERSION_CODES.P && node.isHeading();
+  }
+
   // Declared residue (agent-device #1832): checked / checkable / long-clickable are not serialized,
   // so toggle state is invisible to agents. Adding them is a helper protocol change (new attributes
   // + host parser + fields on the wire node), tracked there.
diff --git a/packages/kernel/src/snapshot.ts b/packages/kernel/src/snapshot.ts
index b0f38a3233..eace66eba8 100644
--- a/packages/kernel/src/snapshot.ts
+++ b/packages/kernel/src/snapshot.ts
@@ -238,6 +238,10 @@ export type RawSnapshotNode = {
   enabled?: boolean;
   selected?: boolean;
   focused?: boolean;
+  /** Accessibility heading flag an app set on the node; absent means not a heading or unavailable. */
+  heading?: boolean;
+  /** Localized role description an app set beside the native class, verbatim (`Tab`, `Tab List`, `Link`). */
+  roleDescription?: string;
   /** Native accessibility facts; absent means unavailable, not false. */
   editable?: boolean;
   password?: boolean;
diff --git a/packages/platform-android/src/__tests__/ui-hierarchy-role-facts.test.ts b/packages/platform-android/src/__tests__/ui-hierarchy-role-facts.test.ts
new file mode 100644
index 0000000000..494920afa9
--- /dev/null
+++ b/packages/platform-android/src/__tests__/ui-hierarchy-role-facts.test.ts
@@ -0,0 +1,60 @@
+import { expect, test } from 'vitest';
+import { buildUiHierarchySnapshot, parseUiHierarchyTree } from '../ui-hierarchy.ts';
+
+// A React Native screen: `accessibilityRole="header"` is a plain View the helper flags as a heading,
+// a tab bar is a View with the role description the app set, and a label carries neither.
+const ROLE_FACTS_XML = `<hierarchy>
+  <node class="android.widget.FrameLayout" resource-id="root" bounds="[0,0][400,800]"
+    window-index="0" window-type="1" window-layer="1" window-active="true" window-focused="true"
+    window-bounds="[0,0][400,800]" visible-to-user="true" enabled="true">
+    <node class="android.view.View" resource-id="inventory-header" text="Inventory" heading="true"
+      bounds="[0,0][400,60]" enabled="true" visible-to-user="true" />
+    <node class="android.view.View" resource-id="section-tabs" role-description="tab list"
+      bounds="[0,60][400,120]" enabled="true" visible-to-user="true">
+      <node class="android.view.View" resource-id="tab-fields" text="Fields" role-description="tab"
+        bounds="[0,60][200,120]" clickable="true" enabled="true" visible-to-user="true" />
+    </node>
+    <node class="android.widget.TextView" resource-id="plain-label" text="Wi-Fi"
+      bounds="[0,120][400,180]" enabled="true" visible-to-user="true" />
+  </node>
+</hierarchy>`;
+
+function nodesById(raw: boolean, interactiveOnly = false) {
+  const { nodes } = buildUiHierarchySnapshot(parseUiHierarchyTree(ROLE_FACTS_XML), undefined, {
+    raw,
+    interactiveOnly,
+  });
+  return (identifier: string) => nodes.find((node) => node.identifier === identifier);
+}
+
+test.each([
+  { raw: false, interactiveOnly: false },
+  { raw: true, interactiveOnly: false },
+  { raw: true, interactiveOnly: true },
+])(
+  'the heading flag and the role description reach snapshot nodes (raw=$raw, -i=$interactiveOnly)',
+  ({ raw, interactiveOnly }) => {
+    const byId = nodesById(raw, interactiveOnly);
+    expect(byId('inventory-header')?.heading).toBe(true);
+    expect(byId('section-tabs')?.roleDescription).toBe('tab list');
+    expect(byId('tab-fields')?.roleDescription).toBe('tab');
+  },
+);
+
+test('a node without either fact carries neither key once serialized', () => {
+  const byId = nodesById(false);
+  const label = JSON.parse(JSON.stringify(byId('plain-label')));
+  expect(label).not.toHaveProperty('heading');
+  expect(label).not.toHaveProperty('roleDescription');
+  // A heading is not a role description and a role description is not a heading.
+  expect(JSON.parse(JSON.stringify(byId('inventory-header')))).not.toHaveProperty(
+    'roleDescription',
+  );
+  expect(JSON.parse(JSON.stringify(byId('tab-fields')))).not.toHaveProperty('heading');
+});
+
+test('the class stays the type: a role description refines nothing on its own', () => {
+  const byId = nodesById(false);
+  expect(byId('tab-fields')?.type).toBe('android.view.View');
+  expect(byId('inventory-header')?.label).toBe('Inventory');
+});
diff --git a/packages/platform-android/src/ui-hierarchy-builder.ts b/packages/platform-android/src/ui-hierarchy-builder.ts
index ea608a2c5e..a3aed983f0 100644
--- a/packages/platform-android/src/ui-hierarchy-builder.ts
+++ b/packages/platform-android/src/ui-hierarchy-builder.ts
@@ -354,6 +354,8 @@ function createAndroidRawSnapshotNode(
     enabled: node.enabled,
     focused: node.focused,
     selected: node.selected,
+    heading: node.heading,
+    roleDescription: node.roleDescription,
     editable: node.editable,
     password: node.password,
     hintShowing: node.hintShowing,
diff --git a/packages/platform-android/src/ui-hierarchy-node.ts b/packages/platform-android/src/ui-hierarchy-node.ts
index c6e3138c32..4ac4a47a1f 100644
--- a/packages/platform-android/src/ui-hierarchy-node.ts
+++ b/packages/platform-android/src/ui-hierarchy-node.ts
@@ -17,6 +17,8 @@ export type AndroidUiHierarchy = {
   visibleToUser?: boolean;
   focused?: boolean;
   selected?: boolean;
+  heading?: boolean;
+  roleDescription?: string;
   editable?: boolean;
   password?: boolean;
   hintShowing?: boolean;
diff --git a/packages/platform-android/src/ui-hierarchy.ts b/packages/platform-android/src/ui-hierarchy.ts
index cf5933cec7..006502d9b3 100644
--- a/packages/platform-android/src/ui-hierarchy.ts
+++ b/packages/platform-android/src/ui-hierarchy.ts
@@ -35,6 +35,10 @@ export type AndroidUiNodeMetadata = {
   focusable?: boolean;
   focused?: boolean;
   selected?: boolean;
+  /** Helper-only: the accessibility heading flag an app set on the node (API 28 or later). */
+  heading?: boolean;
+  /** Helper-only: the localized role description an app set beside the class, verbatim. */
+  roleDescription?: string;
   password?: boolean;
   editable?: boolean;
   selectionStart?: number;
@@ -132,6 +136,15 @@ function readNodeAttributes(node: string): Omit<AndroidUiNodeMetadata, 'rect'> {
     const value = parseBounds(getAttr(name));
     return value === undefined ? {} : ({ [key]: value } as Pick<AndroidUiNodeMetadata, Key>);
   };
+  const optionalStringAttr = <Key extends keyof AndroidUiNodeMetadata>(
+    key: Key,
+    name: string,
+  ): Partial<Pick<AndroidUiNodeMetadata, Key>> => {
+    const value = getAttr(name);
+    return value === null || value === ''
+      ? {}
+      : ({ [key]: value } as Pick<AndroidUiNodeMetadata, Key>);
+  };
   const optionalBoolAttr = <Key extends keyof AndroidUiNodeMetadata>(
     key: Key,
     name: string,
@@ -157,6 +170,8 @@ function readNodeAttributes(node: string): Omit<AndroidUiNodeMetadata, 'rect'> {
     ...optionalBoolAttr('hintShowing', 'hint-showing'),
     ...optionalBoolAttr('visibleToUser', 'visible-to-user'),
     ...optionalBoolAttr('selected', 'selected'),
+    ...optionalBoolAttr('heading', 'heading'),
+    ...optionalStringAttr('roleDescription', 'role-description'),
     ...optionalNumberAttr('drawingOrder', 'drawing-order'),
     ...optionalBoolAttr('scrollable', 'scrollable'),
     ...optionalBoolAttr('canScrollForward', 'can-scroll-forward'),
@@ -311,6 +326,8 @@ function normalizeAndroidUiHierarchyNode(
       enabled: attrs.enabled,
       focused: attrs.focused,
       selected: attrs.selected,
+      heading: attrs.heading,
+      roleDescription: attrs.roleDescription,
       editable: attrs.editable,
       password: attrs.password,
       hintShowing: attrs.hintShowing,
diff --git a/src/__tests__/android-ui-hierarchy.test.ts b/src/__tests__/android-ui-hierarchy.test.ts
index 62a41f90c9..d9edc4296d 100644
--- a/src/__tests__/android-ui-hierarchy.test.ts
+++ b/src/__tests__/android-ui-hierarchy.test.ts
@@ -236,6 +236,42 @@ test('a published Android snapshot answers a selected-qualified read (#2462)', a
   );
 });
 
+// A React Native screen: the header role is a View flagged as a heading, the tab bar and its tabs
+// are Views with the role description the app set, and the helper writes neither on a plain label.
+const ANDROID_ROLE_FACTS_XML = `<hierarchy>
+  <node class="android.widget.FrameLayout" resource-id="com.example.app:id/root" bounds="[0,0][390,300]" enabled="true" visible-to-user="true">
+    <node class="android.view.View" resource-id="com.example.app:id/header" text="Inventory" heading="true" bounds="[0,0][390,60]" enabled="true" visible-to-user="true"/>
+    <node class="android.view.View" resource-id="com.example.app:id/tabs" role-description="tab list" bounds="[0,60][390,120]" enabled="true" visible-to-user="true">
+      <node class="android.view.View" resource-id="com.example.app:id/tab-fields" text="Fields" role-description="tab" bounds="[0,60][195,120]" clickable="true" enabled="true" visible-to-user="true"/>
+    </node>
+    <node class="android.widget.TextView" resource-id="com.example.app:id/label" text="Wi-Fi" bounds="[0,120][390,180]" enabled="true" visible-to-user="true"/>
+  </node>
+</hierarchy>`;
+
+test('a published Android snapshot carries the heading flag and the role description', () => {
+  const nodes = publishUiHierarchy(ANDROID_ROLE_FACTS_XML).nodes;
+  const byId = (identifier: string) => nodes.find((node) => node.identifier === identifier)!;
+
+  assert.equal(byId('com.example.app:id/header').heading, true);
+  assert.equal(byId('com.example.app:id/tabs').roleDescription, 'tab list');
+  assert.equal(byId('com.example.app:id/tab-fields').roleDescription, 'tab');
+  assert.equal(byId('com.example.app:id/label').heading, undefined);
+  assert.equal(byId('com.example.app:id/label').roleDescription, undefined);
+  assert.deepEqual(
+    Array.from(androidUiNodes(ANDROID_ROLE_FACTS_XML)).map((node) => [
+      node.heading,
+      node.roleDescription,
+    ]),
+    [
+      [undefined, undefined],
+      [true, undefined],
+      [undefined, 'tab list'],
+      [undefined, 'tab'],
+      [undefined, undefined],
+    ],
+  );
+});
+
 test('parseUiHierarchy discards stale inactive Android application windows', () => {
   const xml = `<hierarchy>
   <node class="android.widget.FrameLayout" package="com.example.app" bounds="[0,0][390,844]" window-index="0" window-type="1" window-layer="10" window-active="true" window-focused="true" window-bounds="[0,0][390,844]">
diff --git a/src/commands/capture/runtime/snapshot-unchanged.ts b/src/commands/capture/runtime/snapshot-unchanged.ts
index 61929117be..1ec07b70ee 100644
--- a/src/commands/capture/runtime/snapshot-unchanged.ts
+++ b/src/commands/capture/runtime/snapshot-unchanged.ts
@@ -112,6 +112,8 @@ const PRESENTATION_SCALAR_FIELDS = {
   enabled: true,
   selected: true,
   focused: true,
+  heading: true,
+  roleDescription: true,
   hittable: true,
   bundleId: true,
   appName: true,
diff --git a/src/daemon/response-views.ts b/src/daemon/response-views.ts
index 62ad99e599..2a21a34a12 100644
--- a/src/daemon/response-views.ts
+++ b/src/daemon/response-views.ts
@@ -115,6 +115,8 @@ const SELECTOR_DIGEST_NODE_FIELDS = [
   'enabled',
   'selected',
   'focused',
+  'heading',
+  'roleDescription',
   'editable',
   'password',
   'hintShowing',
diff --git a/website/docs/docs/snapshots.md b/website/docs/docs/snapshots.md
index 9a4a1a2492..f9ef3f34e0 100644
--- a/website/docs/docs/snapshots.md
+++ b/website/docs/docs/snapshots.md
@@ -117,15 +117,21 @@ the strategy owns which tiers it may use.
 ## Android node metadata
 
 Android snapshot nodes and `get attrs` (including the digest response) carry the native
-`selected`, `editable`, `password`, `hintShowing`, `selectionStart`, and `selectionEnd` facts
-whenever the accessibility tree reports them. Explicit `false` and `0` are kept; an absent field
-means the fact was unavailable, not false. `hintShowing` needs Android API 26 or later.
+`selected`, `heading`, `roleDescription`, `editable`, `password`, `hintShowing`, `selectionStart`,
+and `selectionEnd` facts whenever the accessibility tree reports them. Explicit `false` and `0` are
+kept; an absent field means the fact was unavailable, not false. `hintShowing` needs Android API 26
+or later, `heading` API 28 or later.
 
 - `selected` is the accessibility selected state an app sets on a control — the active bottom-tab or
   segmented-control item, or the chosen row of a list. Android reports it explicitly as `true` or
   `false`; an older helper APK omits the field, which means the answer is unavailable rather than
   unselected. Snapshot text marks the node `[selected]`, and `is selected`, a `selected=true`
   selector, and a Maestro `selected:` qualifier all match on it.
+- `heading` is the accessibility heading flag an app sets on a node, the way React Native's
+  `accessibilityRole="header"` does on a plain `View`; it is present only as `true`.
+- `roleDescription` is the localized role description an app sets beside the native class, verbatim
+  (React Native writes `Tab`, `Tab List`, `Radio Group`, `Link`, `Menu`), when the class alone would
+  not say what the control is. The `type` stays the class; a consumer maps the description to a role.
 - `value: ""` is an explicitly empty accessibility text; a missing `value` means no text was
   reported. The text of an empty field is its hint on modern Android, so check `hintShowing`
   before reading `value` as the entered contents.

From dc9ab863ad903b568f4a07ea484c8ff95b5f2659 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 24 Sep 2026 18:36:14 +0200
Subject: [PATCH 102/132] chore: remove CHANGELOG.md in favor of generated
 release notes (#2922)

---
 .github/workflows/android.yml           |   1 -
 .github/workflows/ci.yml                |   1 -
 .github/workflows/ios.yml               |   1 -
 .github/workflows/linux.yml             |   1 -
 .github/workflows/macos.yml             |   1 -
 .github/workflows/size.yml              |   1 -
 CHANGELOG.md                            | 944 ------------------------
 test/ci/root-docs-paths-ignore.test.ts  |  13 +-
 website/docs/docs/migrating-gestures.md |   4 +-
 9 files changed, 5 insertions(+), 962 deletions(-)
 delete mode 100644 CHANGELOG.md

diff --git a/.github/workflows/android.yml b/.github/workflows/android.yml
index 5b375ede7f..2f89157167 100644
--- a/.github/workflows/android.yml
+++ b/.github/workflows/android.yml
@@ -7,7 +7,6 @@ on:
       - 'website/**'
       - 'README.md'
       - 'AGENTS.md'
-      - 'CHANGELOG.md'
       - 'CONTEXT.md'
       - 'CONTRIBUTING.md'
       - 'LICENSE'
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index a29b930cae..7691398f68 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -7,7 +7,6 @@ on:
       - 'website/**'
       - 'README.md'
       - 'AGENTS.md'
-      - 'CHANGELOG.md'
       - 'CONTEXT.md'
       - 'CONTRIBUTING.md'
       - 'LICENSE'
diff --git a/.github/workflows/ios.yml b/.github/workflows/ios.yml
index 59c74bf5df..62c575390f 100644
--- a/.github/workflows/ios.yml
+++ b/.github/workflows/ios.yml
@@ -7,7 +7,6 @@ on:
       - 'website/**'
       - 'README.md'
       - 'AGENTS.md'
-      - 'CHANGELOG.md'
       - 'CONTEXT.md'
       - 'CONTRIBUTING.md'
       - 'LICENSE'
diff --git a/.github/workflows/linux.yml b/.github/workflows/linux.yml
index eec6b844bc..2d1c29d629 100644
--- a/.github/workflows/linux.yml
+++ b/.github/workflows/linux.yml
@@ -7,7 +7,6 @@ on:
       - 'website/**'
       - 'README.md'
       - 'AGENTS.md'
-      - 'CHANGELOG.md'
       - 'CONTEXT.md'
       - 'CONTRIBUTING.md'
       - 'LICENSE'
diff --git a/.github/workflows/macos.yml b/.github/workflows/macos.yml
index 32320e23d9..df86714a2b 100644
--- a/.github/workflows/macos.yml
+++ b/.github/workflows/macos.yml
@@ -7,7 +7,6 @@ on:
       - 'website/**'
       - 'README.md'
       - 'AGENTS.md'
-      - 'CHANGELOG.md'
       - 'CONTEXT.md'
       - 'CONTRIBUTING.md'
       - 'LICENSE'
diff --git a/.github/workflows/size.yml b/.github/workflows/size.yml
index e2014c1aa6..0163a4d1eb 100644
--- a/.github/workflows/size.yml
+++ b/.github/workflows/size.yml
@@ -7,7 +7,6 @@ on:
       - 'website/**'
       - 'README.md'
       - 'AGENTS.md'
-      - 'CHANGELOG.md'
       - 'CONTEXT.md'
       - 'CONTRIBUTING.md'
       - 'LICENSE'
diff --git a/CHANGELOG.md b/CHANGELOG.md
deleted file mode 100644
index 7ee85fc461..0000000000
--- a/CHANGELOG.md
+++ /dev/null
@@ -1,944 +0,0 @@
-# Changelog
-
-## Unreleased
-
-- Fixed (android): snapshot nodes and `get attrs` carry the accessibility `heading` flag and the
-  `roleDescription` an app set on a node. React Native puts a header, a tab, a tab list, a link, or a
-  menu on a plain `android.view.View` and tells the accessibility tree what it is through these two
-  facts; the helper never serialized either, so every one of them was a nameless `View` to an agent.
-  The helper now writes `heading` when the node reports it (API 28 or later) and `role-description`
-  when the app set one, and the parser, the Android hierarchy node, and the published snapshot node
-  carry them to `get attrs` and the selector digest. The class stays the `type`.
-- Fixed (ios): `perf cpu profile report --kind xctrace` on Xcode 27 no longer fails with
-  `Apple xctrace CPU report contained no samples` on a trace that holds thousands of samples. Xcode
-  27 exports each `time-profile` sample stack as `<tagged-backtrace>` instead of `<backtrace>`, and
-  the parser read only the old element, so every row resolved no stack at all. Both spellings now
-  parse through the same `id`/`ref` resolution, so a profile recorded with an older Xcode reports
-  what it did before. (#2860)
-- Fixed (ios): `alert get`, `accept`, or `dismiss` with no alert on screen no longer reads every
-  element of the app to look for a popover's dismiss region. That walk cost one XCTest round trip
-  per element, plus XCTest's retry cycle for each element that vanished mid-walk. On a loading
-  WebView it outran the 10 s alert budget and kept the runner's main thread busy for more than 30 s
-  after the command failed, so later commands failed with `RUNNER_BUSY`. The dismiss region is now
-  found with one predicate query per window set. (#2491)
-- Changed (apple): a read-only runner command is resent inside the same request only when the
-  runner refused it as `RUNNER_BUSY`. Before, any `COMMAND_FAILED` carrying `details.retriable:
-  true` was sent up to three times. That flag tells a caller's own poll, such as `wait`, to try
-  again. It does not mean a resend is safe inside one request. A runner startup that ran out of its
-  budget (`runner_phase_budget_exhausted`) or could not read the Xcode toolchain
-  (`apple_toolchain_probe_unavailable`) now fails once, not three times with a fresh startup budget
-  each time. A `retriable` failure from an external Apple runner provider is also no longer resent.
-  The error keeps `retriable: true`, so the caller's next request still tries again. (#2862)
-- Fixed (mobile): a `get`, `is`, `find`, or `wait` selector read no longer answers from a tree that
-  a later command outdated. Selector reads reuse the session's stored tree for 750 ms after its
-  capture. Two cases outdated that tree without replacing it: a `wait text` satisfied by the
-  owner's native text reading after an earlier miss capture, and a mutation that captured nothing
-  (for example a coordinate `press`). The next read then reused the pre-change tree and could
-  report `Selector did not match` for an element that was on screen. A side effect or a native read
-  now retires the stored tree, and the next read captures again.
-- Fixed (mobile): a read taken right after a `scroll`, `swipe`, or `gesture swipe` no longer reports
-  a definite miss when the surface never settled. When post-gesture stabilization ran out of budget
-  on a surface still moving, `is visible` answered a plain `selector_not_found` and `is absent`
-  passed. The capture now carries `postGestureOutcome` (`{ kind, gesture: { action, positionals } }`)
-  with `kind: "unsettled"`, and so does a re-capture taken at once to recover or widen it. A proven
-  no-effect gesture rides the same field with `kind: "no-effect"`; before, its warning reached only
-  `snapshot`. `is`, `get`, `find`, `wait`, and every interaction that captured it (`click`, `press`,
-  `fill`, and the other touch and gesture commands) report the field in `data` or `error.details`
-  with an appended warning; `snapshot` appends the warning. `is absent` refuses an unsettled capture
-  with `observation: "unsettled"`, `wait absent` keeps polling, and the next read captures afresh.
-  A failed read also carries `targetActivation` in `error.details`, and a failed interaction now
-  keeps the disclosure sentences in its hint.
-  passed. That capture now carries `unsettledGesture`: `is`, `get`, `find`, and `wait` report it (in
-  `error.details` or `data`) with an appended warning, `snapshot` appends the warning, `is absent`
-  refuses with `observation: "unsettled"`, `wait absent` keeps polling, and the next read captures
-  afresh. Click, press, and fill by selector do not disclose it yet. A failed read now also carries
-  `targetActivation` in `error.details`, the same place as `unsettledGesture`.
-- Fixed (ios): a synthesized tap step inside a runner `sequence` (for example `press x y --count N`)
-  now follows the standalone tap's policy instead of its own. When accessibility is unavailable or no
-  app window resolves, the step now falls back to an XCTest coordinate tap instead of failing the
-  step with `UNSUPPORTED_OPERATION`. One helper now owns the synthesize-then-fallback decision at
-  every synthesized tap site (#2788).
-- Fixed (ios): `open` on a local Simulator now waits for the launched app's discovery before it
-  decides whether the app is observable. On a loaded host `simctl spawn launchctl list` outlasts one
-  1.5 s discovery wait slice, and the launch observation read that slice as an unobservable app, so
-  the open returned before the discovery, the AX-bridge preparation or the first bridge connection.
-  The first `wait` after the open then paid all three in one poll, behind a runner `findText`, and on
-  CI it spent its whole 10 s budget there (`wait_capture_stalled` with `captures: 1`). The probe now
-  joins the running discovery, bounded by the discovery's own deadline, and then observes the launch
-  as before. A resolution failure other than a pending discovery still ends the probe at once.
-- Fixed (ios): `alert accept` and `alert dismiss` no longer land their tap after the command's
-  deadline when a notification banner is on screen. XCTest checks for SpringBoard banners and alerts
-  before every event and its default handler waited up to 15 s for a banner to leave, so the command
-  answered `ALERT_DEADLINE_EXCEEDED` ("The button was activated once") for a tap that arrived after
-  the caller was told it had failed (#2546's late tap, from the banner side). Alert activation now
-  opts out of XCTest's interruption handling, which also stops that handler from pressing a button of
-  its own choosing on an unrelated system alert while the command answers the alert it resolved.
-- Fixed (macos): `screenshot --fullscreen` on the `desktop`, `menubar`, or `frontmost-app` surface
-  now refuses with `INVALID_ARGS` (`details.reason:
-  SCREENSHOT_FULLSCREEN_MACOS_HELPER_SURFACE_FIXED_FRAME`) instead of being accepted and silently
-  ignored. Every one of those surfaces captures through the macOS helper, which always reads the
-  main display, so the flag never named a frame the capture could vary. A `.ad` script or project
-  config that sets `screenshotFullscreen` for one of those surfaces now fails instead of succeeding
-  with the same image it always produced; drop the flag there. macOS app sessions and every other
-  platform keep accepting `--fullscreen` unchanged. (#2799)
-- Fixed (ios): no runner read launches a session app that is not running anymore. The XCTest runner
-  repaired foreground loss by calling `activate()`, which launches an app that is not running. After
-  `open <app> --relaunch --launch-url <url>` on a Simulator, iOS can hold the launch behind an
-  "Open in …?" confirmation, and the first read of the waiting session launched the app without the
-  URL. Reads — `snapshot`, `wait`, `is`, `get`, a reading `find`, and an interaction's leading reads
-  (the viewport read a `gesture` starts with, the capture that resolves a selector `click`/`fill`) —
-  now refuse with `COMMAND_FAILED`, `details.runnerErrorCode: "APP_NOT_RUNNING"`, `retriable: true`
-  and a hint to answer the prompt with `alert accept` or relaunch with `open`. A `wait` polls
-  through the refusal; the runner transport never resends it. Interactions that mutate without a
-  leading read (`press`, a coordinate `fill`, `swipe`, `scroll`, hardware keys) keep the foreground
-  repair and still bring a stopped app up.
-- Fixed (ios): a local Simulator snapshot taken through the host AX bridge no longer publishes the
-  screens a modal presentation covers, so a selector resolves the control the user can reach instead
-  of the stale copy underneath it. UIKit appends each presentation as a later sibling of what it
-  presents over, and the bridge reports every sibling, so a React Navigation stack that presents its
-  pushed routes as sheets kept all three screens live: one capture of a three-screen stack published
-  567 nodes across three screens where the same app under the XCTest runner published 76 across the
-  top one. Maestro's visibility predicate is geometric, so `- tapOn: "Push article"` matched the
-  covered screen's button first and the flow failed on an assertion about the screen that never
-  arrived, and `presentation: "formSheet"` fields matched intermittently (#2638). Geometry cannot
-  close this: a sheet leaves most of the covered screen uncovered, and the occlusion pass only
-  treats floating chrome as a cover. The presentation cut now applies modal containment — when the
-  last transition view under a container carries UIKit's dimming view as its direct child and that
-  dimming view takes touches, the earlier transition views that dimmed area spans, and everything
-  under them, are cut from the regular and interactive snapshots. The bridge now reads
-  `userInteractionEnabled` on dimming views (source version v1.7.0) because a sheet resting at an
-  undimmed detent keeps its dimming view while the screen under it stays reachable; that sheet, and
-  any presentation UIKit does not dim, is left as it was, so the cut asserts containment only where
-  the producer states it. `snapshot --raw` still reports the covered screens, and producers that
-  report no UIKit class names — the XCTest runner, whose own queries answered 76 nodes for that same
-  state, plus `appium-source` and `limrun-ios-tree` — never trigger the cut. All 39 flows of React Navigation's Maestro suite pass on an iPhone 17 Simulator running
-  iOS 26.2 with this change, including two that never passed on the bridge.
-- Fixed (ios): runtime clang builds no longer compile with `-Werror`, so a new warning from a future
-  Xcode SDK cannot break the AX bridge or fold on a user's machine that this repository cannot fix
-  for them. The fold helper is now built through the same content- and toolchain-keyed build cache
-  as the AX bridge, so a fold call after the first serves a cached binary instead of recompiling
-  `Fold.m` on every call, and switching `DEVELOPER_DIR` busts the cache instead of serving a binary
-  built against a different SDK. A darwin-only CI step (`.github/workflows/ios.yml`) compiles each
-  build's production argv with `-Werror` appended whenever its sources change, so a new warning still
-  fails CI (#2796).
-- Fixed (ios): a local Simulator snapshot taken through the host AX bridge once again publishes the
-  geometric `hittable` fact, so `is hittable` and a `hittable:` selector resolve the same controls on
-  the bridge and the XCTest runner. The snapshot capability table has declared `hittable =
-  geometric-actionability` for every backend (#1933), and the runner has always stamped it; when 0.21.0
-  made the AX bridge the Simulator's snapshot source, the bridge reader mapped the traits word into
-  `enabled` and `selected` but handed over no hit result and disclosed `hittability` as unavailable on
-  every capture, so a `hittable:` selector matched nothing on the bridge that the runner would match.
-  The reader now derives `hittable` on its raw nodes from the same rule the runner's Swift uses — the
-  shared `isGeometricallyActionable`, `CGRect.contains` half-open edges and all — applied to the node's
-  own frame and the reported viewport, and discloses `hittability` as unavailable only when no viewport
-  is reported. Because it stamps the raw source rather than the fold, `snapshot --raw` matches too, and
-  the residue owner stays the fact owner (#2199). Closes the hittable-absence half of the AX-bridge
-  capture divergence (#2638).
-- Fixed (web): `press --double` and `press --hold` on a web session now answer with a typed reason
-  instead of an unclassified `UNSUPPORTED_OPERATION` naming an interactor member. The browser owner's
-  `tapPoint` cell admitted the whole press series, but the web click affordance is one immediate
-  pointer press per call: `--count` repeats it, and this owner composes neither a fused double-click
-  nor a timed hold. A hold is refused by the `longPressPoint` cell that already refuses `longpress`,
-  so both commands now carry the hint "A web click is one immediate pointer press; the browser backend
-  has no timed hold." and `press --hold` adds `details.reason: "unsupported-platform-leaf"`. A
-  double-click is refused by the fused mechanic the web interactor no longer carries, reporting
-  `details.reason: "owner-capability-missing"`; both refusals arrive when the press runs, after any
-  target selector was resolved. A repeated single-tap press (`--count 3`) keeps working on the same
-  session, and every owner that double-tapped or held before this change still does: Android, iOS,
-  Linux, HarmonyOS, Cloud WebDriver and Limrun keep their own mechanics, and an owner with a fused
-  point press keeps answering `--double` through it.
-- Fixed (ios): a local Simulator snapshot taken through the host AX bridge once again carries the
-  accessibility `selected` state, so `is selected`, a `selected=true` selector, and a Maestro
-  `selected:` qualifier match the active control. When 0.21.0 made the AX bridge the Simulator's
-  snapshot source, the bridge's node reader mapped the traits word into `enabled` but never into
-  `selected`, so an active bottom tab, chosen segment, or checked row published no `selected` field
-  and every `selected:` match failed on the iOS Simulator — a fact the 0.20.x XCTest tree had always
-  supplied and that `snapshots.md` still promises. The reader now derives `selected` from the
-  selected-trait bit of the same traits word, publishing `selected: true` only when set and omitting
-  it otherwise so the two producers cannot be told apart by a `selected:` selector. The bit is pinned
-  by the guest's real captured words, so a producer encoding change cannot drop the fact silently
-  again.
-- Fixed (ios): an interactive snapshot no longer drops the rows of a list whose row hosts a scroll
-  view of its own. Ownership of a scroll indicator is now read from its parent edge — a visible band
-  derives only when the indicator's parent is itself a scroll type — instead of walking ancestors for
-  the nearest scrollable or text node. #2740 closed the class for `TextView` alone; the walk still
-  misattributed the indicator of any other scroll-shaped host that publishes as a non-scroll type (a
-  `WebView`, a map view, a paged cell) to the enclosing list and clipped that list to the host's
-  one-line band. Ownership still passes up through ancestors that share the scroller's exact frame, so a
-  `WKWebView` page — whose indicator sits under `WebView` wrappers that fill the scroll view — keeps its
-  visible band; the walk stops at the first frame change, so a host smaller than its list still owns
-  nothing. ADR 0026.
-- Fixed (ios): `fold half-open` no longer reports a pose the hinge never held. The command accepted
-  the requested category as the answer whenever its four-read budget happened to end on a
-  `half-open` angle, so a hinge still sweeping from 180° toward 0° — which passes through every
-  half-open angle on the way — came back as a settled Book pose. An angle inside that open interval
-  proves the category and nothing else, so `half-open` now requires two consecutive readings that
-  both fall inside it and agree within 0.5°; a pair straddling the 179° boundary is two poses, not
-  one hinge at rest. A budget ending on an unsettled angle fails with `COMMAND_FAILED` and
-  `details.reason: "fold-pose-unsettled"`, carrying `requestedPose`, `observedPose`,
-  `hingeAngleDegrees` and the previous reading, and says the hinge was observed half-open and did
-  not settle rather than claiming it never got there. `fold-pose-unverified` still covers a budget
-  that ends on another pose. Supersedes ADR 0025's budget-end exception (#2730).
-- Fixed (ios): an interactive snapshot of a list whose row holds selectable text (a `TextView`) no
-  longer drops every row after that text. A UITextView is a scroll view too, and XCTest publishes
-  its scroll indicator inside the text; the presentation read that indicator onto the list around
-  it and clipped the list's viewport to one line, so a post thread whose root post is selectable
-  text showed the root and none of its replies, while the full snapshot showed all of them. An
-  indicator whose nearest scrolling ancestor is a text view now belongs to that text view and
-  derives no list viewport.
-- Fixed (ios): a foreground repair names the state the session app was really in. The decoder translated
-  the runner's raw `XCApplicationState` integer from a handwritten table that had
-  `runningBackgroundSuspended` (2) and `runningBackground` (3) the wrong way round, so a suspended app
-  was disclosed as merely backgrounded in `targetActivation.priorState` and in the appended warning —
-  as shipped in v0.21.7 and v0.21.8. The table now follows what the SDK declares, a runner XCTest pins
-  every integer against `XCUIApplication.State` itself, and the decoder test reads those pins, so the
-  two copies cannot drift apart unnoticed.
-- Fixed (macos): `press` and `click` on the `frontmost-app`, `desktop`, and `menubar` surfaces post
-  clicks the way a trackpad does. The helper posted the release in the same tick as the press, so
-  AppKit dropped it and controls never activated; each press is now held (`--hold-ms`, 60 ms by
-  default, 40 ms at least). `--count` is that many independent clicks and `--double-tap` posts each
-  as a double-click pair, the helper's deadline follows the click schedule instead of a fixed 30 s,
-  and every stop the host applies mid-hold — a cancelled request, a dropped client, the deadline —
-  reaches the helper as SIGTERM first so it releases the button before it exits; SIGKILL only
-  follows a helper that has not exited a second later.
-- Added (ios): `fold <closed|half-open|open>` and `client.command.fold({ pose })` put a foldable
-  iPhone simulator (iPhone Duo) into a hinge pose. ADR 0025 recorded that no official host API sets
-  the pose and left it to the operator; the pose is now set the way the operator did it, by pressing
-  the pose control in the Xcode Device Hub window through macOS accessibility, and it is confirmed
-  the way ADR 0025 asked for, by reading the hinge angle back from CoreDevice
-  (`devicectl device motion hinge-angle`) until it agrees with the request. The response reports
-  the verified pose, the hinge angle, and the panel the device now lights with its native panel point
-  size, so an agent can see the lit panel changed without another capture. The macOS helper
-  gained a `device-hub pose` subcommand that finds Device Hub in the process table (LaunchServices
-  registers the trampolined app with no pid), reopens its window when it shows none, and selects the
-  simulator through the sidebar row keyed by its UDID so two simulators sharing a name cannot be
-  confused. Simulator-only; a single-panel simulator refuses with `UNSUPPORTED_OPERATION`, and every
-  other platform states its own refusal cell.
-- Fixed (ios): the `fold` response's `screen` dimensions now match their coordinate-space contract. They
-  are the lit panel's own native points (pixels divided by its point scale, never rotated), so the
-  response carries the `coordinateSpace: "native-panel"` discriminator and the docs no longer claim
-  they are the next snapshot's coordinates. They cannot place a tap; take a fresh snapshot for the app
-  viewport.
-- Added (diff): `diff screenshot` accepts a JPEG baseline or current image. Both inputs had to be PNG,
-  so a capture exported by another tool had to be converted first and a HarmonyOS capture — which the
-  platform serves as JPEG under whatever name the command was given — could never be compared. Each
-  input is now decoded from its own bytes, so the container is sniffed and a `.png` name holding JPEG
-  decodes as JPEG. `png-transcode.ts` became `screenshot-image.ts`, the one owner of that sniffing for
-  both the decode and the provider transcode path, and the PNG worker gained a `decode-image` job that
-  answers pixels instead of PNG bytes. The `--out` diff image stays PNG, as do the crop, overlay, and
-  resize passes that rewrite a screenshot in place and could not survive a lossy container.
-
-- Added (maestro): `setPermissions` and `launchApp.permissions` support `all: allow|deny|unset`
-  on iOS simulators and Android, with specific entries overriding `all`. Both accept a
-  Maestro-style permissions map. Entries apply in order until the selected platform refuses one,
-  and the error then names what landed. Android's only allow level is while-in-use, so
-  `location: inuse|never` apply `allow`/`deny` there; `location: always` and `photos: limited`
-  stay Apple-only.
-- Fixed (ios): `settings permission` no longer refuses a privacy service that `simctl privacy`
-  accepts but omits from its own help text — Xcode 26 does that for `camera`, so
-  `settings permission grant camera` and a Maestro `camera: allow` failed as unsupported while
-  the raw command worked. Support is now `simctl privacy`'s own verdict per runtime, and a
-  service it refuses fails with `UNSUPPORTED_OPERATION`. This also drops the cached
-  `simctl privacy help` probe and the `privacy help` spawn before the first permission change.
-  iOS `all` still does not cover notifications: current runtimes have no notifications service,
-  so a targeted notifications change fails loudly and `all` leaves it unchanged.
-- Added (limrun): `record start` and `record stop` on Limrun iOS and Android direct sessions. The
-  runtime declared recording unavailable although the Limrun SDK exposes a server-side recorder.
-  Start asks the instance to record (`--quality medium` maps to Limrun quality 5, `high` to 8);
-  stop asks the instance to stop once, then downloads the served MP4 to the output path as a
-  separate bounded step, so a dropped transfer is retried by the next `record stop` without a
-  second remote stop. The capture is always the whole simulator or emulator screen; `--fps` and
-  `--hide-touches` are refused, and a recording cannot be reattached after a daemon restart. The
-  web recorder now shares the same transport-recording runtime.
-- Added (ios): `action-button` presses the iPhone or iPad Action Button once, and `client.command.actionButton()`
-  does the same. XCUITest exposes `XCUIDevice.press(.action)` with no hold-duration overload, so there is no
-  `long-press` and no `--duration-ms`, and the slide surface on the same edge is Camera Control, which this
-  command does not drive. The press is dispatched without the runner's app-activation preflight and with no
-  post-action observation, so the session app keeps the state the press found; the runner asks the device for
-  the button with `hasHardwareButton(.action)` and refuses with `UNSUPPORTED_OPERATION` on a model that has
-  none, and Android, HarmonyOS, Vega, Linux, web, tvOS, macOS, and visionOS each state their own refusal.
-  Simulators run no Shortcuts or App Intents, so what a press triggers is verifiable only on a physical
-  iPhone (#2699).
-- Changed (all): `home`, `app-switcher` and `action-button` are one system-button family in the
-  runtime contract. An owner without a button now refuses it with the family's hint (for example
-  `Android has no key event for this system button.`) rather than a per-button sentence, and a
-  Limrun or WebDriver session that is no longer active refuses `action-button` with that session's
-  own reason like every other cell; the command name still leads the `UNSUPPORTED_OPERATION`
-  message.
-- Fixed (android): `clipboard read` and `clipboard write` stop reporting success on a build whose
-  clipboard service has no shell command. Android 16 (API 36) answers every `adb shell cmd clipboard …`
-  with the framework default `Binder.handleShellCommand` — `No shell command implementation.` on
-  stderr and exit status 0 — and the exit status was consulted first, so a read reported `text: ""`,
-  a write reported "Clipboard updated", and `capabilities` advertised `clipboard` on a clipboard no
-  adb call ever touched. The response is now classified per stream into one typed verdict shared by
-  both legs and the capability probe: the service's own sentence on `stderr` outranks a clean exit
-  (a service that never ran wrote no payload to `stdout`), while `stdout` stays payload until the call
-  has failed. Such a device now refuses with `UNSUPPORTED_OPERATION` and a hint naming the substitute,
-  and the exported `readAndroidClipboardWithAdb` / `writeAndroidClipboardWithAdb` helpers reject
-  instead of resolving an empty string or nothing at all (#2674).
-- Fixed (limrun): `screenshot` on Limrun iOS direct sessions writes a PNG. Limrun serves its capture
-  as JPEG and the interactor wrote those bytes straight to the `.png` path, so every capture failed
-  downstream with "Screenshot file is not a valid PNG". The bytes are now sniffed and a JPEG is
-  transcoded to PNG before it is written; a PNG passes through unchanged.
-- Changed (ios): `open --device-hub`, the `deviceHub` option of `client.apps.open()`, and the
-  `deviceHub` config-file key are gone. The option has had no effect since 0.20.9: `open` surfaces
-  the standalone Simulator app after a cold boot either way. Each form is now handled like any
-  other unknown flag, option, or config key; drop it from scripts and `agent-device.json` (#2798).
-- Changed (ios): a regular `snapshot --depth N` on the XCTest runner is a presentation cut over a
-  full acquisition, not a bound on the walk. Acquisition publishes the frames the platform reported,
-  one normalization pass turns geometry into the app's orientation space and recomputes `hittable`,
-  and the visibility fold and depth cut run on that array. Presented trees are unchanged on the
-  screens measured; a boundary container under `--depth N` now carries its scroll hints from its real
-  children. The runner's regular-depth capability is `presentation-cut` (was `presented-frontier`),
-  and every `CGRect` becomes a `SnapshotRect` through one initializer (#2661).
-- Fixed (daemon): `close` now stops an active app-log stream (and audio probe / perf capture /
-  recording) on an implicitly cwd-scoped session. Teardown addressed those resources by
-  `session.name` (`default`) instead of the store address (`cwd:<hash>:default`), so the record
-  read as missing, the `log stream` child leaked, and the next `logs start` on that device failed
-  with "has not reached a confirmed terminal state" (#2647).
-- Fixed (ios): Simulator AX bridge snapshots report `enabled`. The bridge requested no state
-  attribute, so a disabled control — a React Native `Pressable` with `disabled`, for example — read
-  as a plain button while the XCTest runner answered the same screen with `enabled: false`. The
-  bridge now reads the element's accessibility traits (sent as a decimal string, since the word has
-  bits past 2^53) and derives `enabled` from `UIAccessibilityTraitNotEnabled`. Source version
-  `agent-device-simulator-ax-v1.6.0` rebuilds the cached bridge on first use.
-- Changed (ios): a node the source declares disabled is presented `hittable: false` even when the
-  capture has no hittability evidence, so on the Simulator bridge a disabled control stops counting
-  as an interactive node and as a Maestro atomic-dispatch candidate. The navigation title affordance
-  (a disabled title field presented as an enabled Button for the whole row) no longer carries the
-  field's `hittable: false`; on the XCTest runner path that Button now counts as interactive and
-  becomes a Maestro atomic-dispatch candidate where it was excluded before.
-- Fixed (ios): a landscape iPhone snapshot reports the system keyboard's rects in the app's own
-  orientation space. iOS hosts `UIRemoteKeyboardWindow` in the device's native portrait space, so its
-  whole subtree arrived quarter-turned — a key measured 45 pt wide and 72 pt tall at `x 154` in an
-  874 x 402 app, drawing a strip down the left edge where the screenshot shows a 724 x 204 band
-  docked at `y 198`. Rules that read those numbers refused app content the keyboard was nowhere near
-  and let a tap land on a key. The Apple runner now reads the app's interface orientation at capture
-  time and publishes every rect under a turned surface host in the app's space, using the exact
-  inverse of the rotation its synthesized touches already rotate through, so a reported rect and a
-  performed tap cannot disagree about which pixel is which. The Simulator AX bridge reader has no
-  interface orientation in its attribute set, so it refuses a capture holding a surface host reporting
-  the app box quarter-turned — `Simulator AX snapshot unavailable
-  (window-coordinate-space-unresolved); used XCTest for this capture, which reports captured geometry
-  in the app's own orientation space.` — and the route sends that one capture to the runner instead of
-  retiring the app generation, so the next capture of a healthy app still uses the bridge. One table
-  proves both languages apply one rule: `contracts/fixtures/window-coordinate-space.json` (#2612).
-- Changed (ios): the rotation table and the coordinate-space rule moved from the XCTest runner bundle
-  into the `AgentDeviceSnapshotPresentation` package, where `swift test` replays the golden table
-  without a simulator. No behaviour change.
-- Added (limrun): `longpress` on Limrun iOS direct sessions. The interactor refused it as
-  unsupported although the SDK exposes the HID primitives; it now holds one touch as a
-  `performActions` batch of `touchDown`, `wait`, `touchUp`, defaulting to the 800 ms the Android
-  and Linux interactors use when no duration is given.
-- Fixed (limrun): `press --double-tap` on Limrun iOS direct sessions sends both taps in one
-  `performActions` batch with an 80 ms on-device pause. The interactor issued two independent `tap`
-  requests, so a network round trip sat between the taps and iOS recognized them as two slow
-  single taps.
-- Added (ios): `type` and `fill` work in the Apple Pay sheet on iOS Simulator instead of failing
-  with `TEXT_INPUT_NOT_FOCUSED`. `com.apple.PassbookUIService` is served in place like the web
-  sign-in host (#2438).
-- Changed (ios): Simulator captures also probe for `com.apple.PassbookUIService`. It can keep
-  running after the Apple Pay sheet closes, so a later capture in that app can report
-  `system-surface-host-lingering` while the process stays alive.
-- Changed (ios): the in-place system surface disclosure now names the sheet kind. The web sign-in
-  sentence changed from "A system web sign-in sheet is presented over the app, so this snapshot
-  shows that sheet (hosted out of the app process)." to "This snapshot shows a system web sign-in
-  sheet presented over the app (hosted out of the app process), not app content". The payment host
-  says "the system Apple Pay sheet" instead.
-- Changed (android): a private adb server no longer absorbs a port its caller named. An adb request
-  that names a server other than the one its route holds — `-P 5037` in argv, or `serverPort` in the
-  call's options — is now refused with `managed-device-transport-mismatch` before anything is
-  dispatched, where previously a `-P` in argv was rewritten onto the route's own port. A caller that
-  asked for 5037 could read a zero exit as an answer about 5037 after the request had run on 15038.
-  It reaches `createLocalAndroidAdbProvider(device, { serverPort })`,
-  `runAndroidHostAdb(invocation, { serverPort })`, and the Limrun runtime dependency's adb calls. A
-  request that names no server, or names the one the route already holds, runs exactly as before, and
-  ambient adb is unchanged: with no private server named, the caller's argv is what runs, `-P`
-  included (#2632).
-- Fixed (android): a chunked `record stop` (recordings over 170 s) no longer warns that screenrecord
-  stopped before record stop at the 180 s limit. Rotation always ends every earlier chunk before
-  stop, so the warning now fires only when the last chunk's recorder had already exited.
-- Fixed (android): a snapshot helper that could not prove it released device automation no longer
-  refuses the next command on the strength of an `adb` call. The old code read the outcome of
-  `am force-stop` as the fact it was supposed to measure, and on a loaded host that round trip can
-  outlive its budget while the device is healthy — the shape of #2553 — so the helper process was
-  already gone and the command still failed with `Android automation helper is still holding device
-  automation ownership`. Ownership is read off the device now: the probe asks the device shell for
-  `pidof com.callstack.agentdevice.snapshothelper` and tells it to echo a marker when nothing matched.
-  A process id is `occupied`, the bare marker is `released`, and everything else is `unknown` —
-  `error: closed`, `cannot connect to daemon`, `device offline`, or an adb client killed by a signal
-  before it wrote anything. A release is therefore claimed only by an answer the transport cannot
-  produce about itself, and no exit status is trusted: `adb shell` answers 0 for a device command that
-  failed, and an adb that dies by signal leaves the executor inventing an exit code it never saw. A
-  refusal requires two reads that both name the process, which keeps a helper still inside Android's
-  exit path from costing a command. Scripts that match the failure reason see
-  `android_snapshot_helper_runtime_occupied`, which replaces
-  `android_snapshot_helper_retirement_unconfirmed`.
-- Changed (android): a snapshot helper session that reaches ready settles a release the previous
-  teardown could not prove. `am instrument` force-stops whatever is already instrumenting the helper
-  package, so a session that reported itself ready is the only helper process the device has left,
-  and the unproven release went away with the process that owed it; the next command no longer
-  force-stops the session it has just started because `pidof` happens to be unreadable. A helper start
-  that fails is also retried after a backoff scaled to how long it spent failing (10 s to 60 s)
-  instead of on every command, which had roughly doubled command time on hosts where the helper never
-  starts. And the wait for a started helper to announce itself no longer uses a fixed 10 s: it takes
-  half of the helper-command budget the capture was built with, 15 s today, which is what had been
-  pushing devices slower than a capture off the persistent path. On a host where the helper took 12 s
-  to announce itself, the command used to answer with the one-shot transport and now answers from the
-  session. The CLI's `--timeout` reaches that wait as its deadline aborting it, not as the number.
-
-- Fixed: an iOS snapshot whose XCTest query-sweep tier cannot read the screen no longer ends the
-  runner process. On a live React Native feed (Bluesky Home, images re-rendering) the AX server
-  rejects each of the sweep's 19 element-type queries with `kAXErrorIllegalArgument`, and XCTest
-  records every rejection as a test failure worded `Failed to resolve query: ...`. The runner muted
-  the sibling `Failed to get matching snapshot: ... kAXError...` wording and not this one, and XCTest
-  ends the test case as soon as the main-thread block that recorded an unmuted failure returns, so
-  the runner died right after (or in the middle of) every hostile snapshot and the next command
-  paid a full `xcodebuild` boot. Both wordings are now muted when they carry an AX server code; the
-  timeout and `Application X is not running` variants keep recording. The sweep also no longer runs
-  behind an abandoned read: every bounded main-thread dispatch that outlives its slice now counts
-  as occupying the main thread (one counter, where the tree XPC and the system-modal probe used a
-  second one of their own), so once the tree tier's viewport read grinds past its 1 s slice the plan
-  goes straight to private AX and answers instead of queueing the sweep, the post-snapshot mark, and
-  its own bookkeeping behind seconds of main-thread work. A capture that fails outright while that
-  work is still grinding queues its cached-target drop behind it instead of waiting a second for it,
-  and a fresh process's first capture is no longer penalized by the tree slice timeout, which had
-  bypassed the warmup exemption every other penalty honors. The per-bundle penalty and
-  accepted-depth memory that make later captures of the same screen cheap now survive, because the
-  runner does.
-- Changed (android): the snapshot helper release manifest no longer carries `installArgs`, and the
-  helper installs with a fixed `adb install -r` like the IME helper. The array only ever spelled
-  `install -r` plus the `-t` that #2603 retired with the `testOnly` flag, so the manifest → flag →
-  option → flag round trip and its allowlist carried nothing. Older manifests that still contain
-  the field parse unchanged; the field is ignored. The adb provider `install` capability now takes
-  only `replace` (#2364).
-- Changed (android, harmonyos): every `adb shell`, `adb exec-out`, and `hdc shell` command now goes
-  through one device-shell funnel that renders each argument for the quoting its transport applies
-  (#2026, #2611). The device shell re-parses the arguments it is handed, so an unquoted dynamic value
-  was a command injection: Android quoted a few sites by hand and HarmonyOS quoted none. The two
-  transports do not quote alike, which is why a caller names the transport (`'adb'` or `'hdc'`) rather
-  than choosing quoting. `adb` escapes nothing, so a word reaches the device inside whatever quotes it
-  is given. `hdc` wraps every element it forwards in double quotes, where a single quote is inert while
-  `$`, a backquote, and `"` stay live: on a nova 14, `fill` text containing `$(id)` came back as the
-  device's own `id` output and a `"` in the text ended its argument, so words on that transport are
-  escaped instead of wrapped. Four effects are visible on a device. HarmonyOS `type` and `fill` text now
-  reaches `uitest uiInput inputText` byte-identical, confirmed with a payload carrying quotes, a command
-  substitution, a pipe, and a redirection. On Android an empty argument renders as `''` rather than
-  vanishing from the command, so a command that read its own shift and its operand as two words no
-  longer misaligns; HDC drops an empty element on the way to the device and cannot carry one, so it is
-  refused with `details.reason` `hdc-empty-word-unsupported`, as is a script fragment, which could only
-  arrive there as literal text. A script body handed to `sh -c` on the adb transport arrives as one
-  argument. Custom adb executors and providers (SDK, MCP, and relay transports such as Limrun's) that
-  pass a raw `['shell', …]` or `['exec-out', …]` argv are now refused with `INVALID_ARGS` and
-  `details.reason` `unguarded-device-shell-argv`, because a command the transport is about to let the
-  device parse has to be one the funnel built. Build it with `runAndroidShell` / `runAndroidExecOut`
-  (a `DeviceInfo`) or `runAdbShell` / `runAdbExecOut` (an `AndroidAdbExecutor`), all exported from
-  `agent-device/android-adb`, and pass each dynamic value as its own word. SDK: `AndroidAdbExecutor`
-  and `AndroidAdbProvider.exec` now receive `readonly string[]`, so a custom executor annotated
-  `(args: string[])` must widen its parameter to take the command.
-- Fixed: BrowserStack sessions honour `--provider-project`, `--provider-build`, and
-  `--provider-session-name`. The capability builder emitted the legacy JSON Wire keys `device`,
-  `os_version`, and `app` at the top level next to the W3C `bstack:options` block; the hub treats a
-  request carrying any legacy key as a legacy session, reads the labels from the legacy top-level
-  `project`/`build`/`name` (never set), and ignores `bstack:options`, so every session landed in
-  "Untitled Project" / "Untitled Build" with an empty name — even after #2495 carried the flags to
-  the provider (#2494). The builder now emits `appium:deviceName`, `appium:platformVersion`, and
-  `appium:app` and no legacy key, verified against live App Automate sessions.
-- Added: `--provider-appium-version <version>` (alias `--appium-version`) pins the Appium server
-  BrowserStack runs for the session, as `bstack:options.appiumVersion`. Unset, BrowserStack falls
-  back to Appium 1.x, which predates the `mobile:` commands the interactor issues (`deepLink`,
-  `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 — 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
-  what no longer happens: when a slow
-  boot spends the whole prepare budget, the health check reports "prepare ios-runner timed out", and
-  that no longer wipes a restored `xcodebuild` artifact on the way to a rebuild — the runner session
-  is invalidated and prepare retries with the artifact intact. Only a failure that indicts the
-  artifact rebuilds it, so a runner that refuses the connection or never answers on any route still
-  wipes it and rebuilds, which is what that rule is for.
-- Added (record): `record stop` now answers the question a video cannot — whether its recorder
-  actually stopped — beside the export. The result carries `recorder` and `nativePathDisposition` on
-  CLI `--json`, the Node client, and MCP (ADR 0024). Today a stop says `confirmed`, or `lost` with
-  `owner-session-lost` for an Apple recording whose session was invalidated, and names its artifact
-  path `retirable` or `retired`; the wider vocabulary those two fields declare (`unconfirmed`, the
-  identity-mismatch reasons, `pending`) arrives with the later ADR 0024 steps that gain the probes
-  those states describe. Both are disclosures about the recorder and the path it writes to, not
-  failures: the export is served either way, and a stop with nothing to report — an older session's
-  replay, or a backend whose recorder writes the served file itself — omits them. No stop changes
-  outcome in this release; the fields land first so the coordinator can report what it already knows
-  before it starts acting on it.
-- Fixed (record): an Android stop credits the device with retiring its recording only when the
-  device proved the chunks gone. The probe read any failed `test -e` as "not there", so an adb that
-  timed out or a device dropped mid-call turned chunks that were still on the device into
-  `nativePathDisposition: "retired"`, and a reattach that could not question the device at all
-  declared the recording's artifact lost. A probe that never ran now answers uncertain: the path
-  stays `retirable` and the recording stays finishable until the device answers.
-- Changed (record): an iOS Simulator recording no longer has the recorder write the file the caller
-  asked for. `simctl` records to a `<name>.native.<ext>` sibling; `record stop` copies that file to a
-  `<name>.collected.<ext>` sibling, checks that the copy has an MP4 container, writes the caller's
-  `--out` path once from the copy, checks that export is a playable video, and retires the recorder's
-  own file (ADR 0024 2.3). An export the finalizer refuses is removed, so `--out` only ever holds a
-  video that passed that check. The
-  caller's path is never a file a recorder is still writing, and a stop that fails before the export
-  exists leaves it absent with the copy in place — so the next stop resumes from the copy instead of
-  signalling a recorder that already stopped. Both siblings are deleted on success, and a stop that
-  got that far answers `nativePathDisposition: retired` rather than the `retirable` it had to answer
-  while the recorder's file and the served file were one file. A recording whose stop fails and is
-  then abandoned (session close, daemon restart, forced cleanup) keeps its video in these siblings
-  beside `--out`, where the recorder used to leave it at `--out` itself; they are the only copy of that
-  video, so nothing deletes them.
-- Changed (record): an Android recording is no longer pulled onto the path the caller asked for.
-  `record stop` pulls the device's chunks to `<name>.collected.<ext>` siblings, retrying each pull
-  until it plays, then writes the caller's paths from copies of them and drops the collected set once the
-  finalization is journaled (ADR 0024 2.3). Chunk paths the finalizer refused are removed. A stop that dies before the export exists leaves it absent with the pulled set in
-  place, and the next stop resumes from that set instead of signalling a `screenrecord` process that
-  already stopped and pulling a file that may have moved since. The 180s platform-limit disclosure now
-  travels with the recorder's own observation rather than with the export, so a stop that has to be
-  driven again still says it; every disclosure is still in the one `warning`. A retried stop serves
-  every chunk and the `capturedDurationMs` its first attempt finalized, and measures the idle tail
-  against the instant that attempt signalled the recorder rather than the time of the retry. A stop
-  that fails and is then abandoned keeps the pulled set on the host beside `--out`. Chunk paths and
-  `--client-output-path` naming are unchanged.
-- Fixed: a process lock that could not be given back no longer waits for the daemon to restart. A
-  release that cannot verify ownership — a refused `unlink`, an unreadable record — left its record
-  standing and naming the live daemon, and the next acquire read that as a live owner and timed out
-  after 30 s on every runner build or launch until the process restarted. The claim inside is spent
-  the moment the release is asked for, so a reclaim here now reads it as dead and takes the path
-  back, and the failed release is recorded in the request log as `process_lock_release_unverified`.
-  A record is only read that way when this loading of the lock code issued it: a second bundled copy
-  of the module in the same process shares the pid and cannot have a live claim cleared under it.
-- Changed (lock errors): code that takes a process lock now answers one question in one helper, which
-  of its two failures the caller hears. The work inside the lock outranks a lock that could not be
-  handed back, so a build or a publish that failed keeps its own error instead of being replaced by
-  `Timed out waiting for …`, and work that succeeded still reports the lock it could not give back.
-  The Apple runner's artifact, cache, lease and disposal paths, the managed-allocation store, the
-  device-claim store, the iOS snapshot bridge cache, the Swift recording cache and the agent-browser setup
-  moved onto it, replacing hand-written try/catch pairs that each chose differently.
-- Fixed: the redirect of `~/Library/Developer/XCTestDevices` gives itself back in one order — restore
-  the host's own device set, then release the lock — and a restore that was refused is what the caller
-  is told, whichever give-back door a teardown used. The lock's own complaint used to replace it in a
-  `finally` and the best-effort door then dropped it, leaving the symlink pointed at the agent-device
-  simulator set with nothing said about why. A simulator whose set already is `XCTestDevices` is no
-  longer failed by a lock it could not verify, either. A leftover from an interrupted build — the host's
-  set renamed aside and `XCTestDevices` symlinked into a simulator's own set — is now put back before the
-  redirect decides whether it is needed, so the first build after an interruption still gets its own
-  device set instead of the host's. A redirect that could not be installed reports the restore that failed
-  with it, and names a backup path only when that backup is really on disk.
-- Changed (sessions): the implicit session is now keyed by workspace **and platform**, so one checkout
-
-  can drive iOS and Android without inventing a `--session` name for every command (#2580). An
-  implicit session was addressed by `cwd:<workspace>:default`, one slot per checkout, and it stayed
-  bound to the first device it touched. A repo that tests both platforms — a visual-regression run
-  across `react-native-paper` components, for example — could not open the second one at all: after
-  `open --platform ios`, `open --platform android` from the same directory failed with `INVALID_ARGS`
-  ("already bound to apple device \"iPhone 17\""), and so did `boot --platform android`, which binds
-  nothing and only needed a device to start. The hint was correct (`--session android` works), but
-  following it means threading a hand-written name through every command of both legs, and a script
-  that drops one flag silently talks to the other platform's device. `--platform` now selects the
-  implicit session, so the platform a script already declares is the only handle it needs:
-  `cwd:<workspace>:ios` and `cwd:<workspace>:android` coexist, each with its own device, app, and
-  artifact directory. Three rules keep the behavior that was already earned.
-  1. A platform-naming request joins the workspace's session only when it genuinely agrees with it,
-     so a session opened without `--platform` — which keeps the platform-less `default` leaf — stays
-     reachable from commands that do name a platform and keeps writing to its own artifact directory
-     instead of growing a twin beside it. A request that agrees on platform but names a different
-     device or target still gets the existing `INVALID_ARGS` refusal; it does not silently fork a
-     second same-platform session that one `--platform` would then have to disambiguate.
-  2. A request naming no platform joins the workspace's only implicit session — what every
-     single-platform script does today, so those are unaffected — and refuses with `AMBIGUOUS_MATCH`
-     when the workspace holds several, naming every address and the `--platform`/`--session` flag
-     that selects it, instead of choosing a platform by open order. Same for a broad selector such as
-     `--platform apple` that matches both this workspace's iPhone and its Mac.
-  3. Inventory commands — `session list`, `devices`, `doctor`, `capabilities`, `apps`, which the
-     registry classifies as `sessionKind: 'inventory'` — never claim a session and keep resolving an
-     address through the ambiguity. Refusing those would refuse the command an agent runs to resolve
-     it. `events` and `close` are deliberately not in that set: each reads or tears down one session,
-     and a silently-empty `events` or a `close` that closed nothing would be worse than the refusal.
-  Two adjacent repairs were required. A settling interaction published the live session under
-  `SessionState.name`, which for an implicit session is only `default` and not the address it answers
-  to, so `agent-device session list` already reported a phantom second row beside the real session;
-  under platform keying that phantom would also have read as a second session the caller has to
-  disambiguate, so the publisher now stores under the key the store itself owns, and workspace-session
-  counting collapses one session reachable under two addresses regardless of writer. And
-  `--session-lock`'s platform reaches `flags` only after routing has chosen the key, so routing now reads `meta.lockPlatform` too — otherwise a
-  lock-policy caller, the exact audience that avoids naming sessions, would land on the wrong leaf.
-  Explicit `--session <name>` is untouched and still addresses one session verbatim.
-
-- Fixed: a `record stop` that could not produce its export no longer destroys what its own retry reads
-  back (#2591). The shared coordinator compensated every failed finish by force-cleaning the resource,
-  which on Android deleted the device-side MP4 and the native manifest the hint just told you to re-pull:
-  the second `record stop` had nothing left to collect and the recording was gone. Each durable kind now
-  declares what its retry needs. `screen-recording` and `perf-capture` preserve, so a failed stop keeps
-  the device artifact, keeps the manifest `open`, returns its own error, and the next `record stop` in
-  that session exports it — proven on an emulator whose `adb pull` failed its first attempts and then
-  exported the 90 KB the first stop left on the device. `app-log` and `audio-probe` say
-  `dispose-on-failed-finish` themselves, because their retries re-read a log file and a status file that
-  cleanup never touches. A finish also states why it was asked for: `capture` may preserve, while
-  `disposal` — session teardown, the one caller that owns forced cleanup — disposes whatever a failed
-  finish left. Two Apple paths had to become genuinely retryable for that to be true: the runner path
-  memoized its refused stop and handed the same rejection to every later `record stop` without asking
-  the runner again, and the simulator path rejected a recording purely because `simctl recordVideo` had
-  exited non-zero — discarding a video the recorder had already written and leaving an exit code no
-  retry could change. A stopped recorder is now an observation rather than a failure: the exit is
-  disclosed on the completion and the file is collected, so those recordings export instead of erroring.
-  Expect one trade: while a preserved recording is open, `record start` on that device is refused until
-  its session runs `record stop` or closes. A simulator recording no retry can rescue now names the
-  exit that made it unreadable — `simctl recordVideo exited with code 1`, `was killed by SIGKILL`, plus
-  the recorder's stderr — drops its retriable flag, and points at closing the session, while a recorder
-  still finalizing its file keeps the retry hint. `perf stop` no longer memoizes a refused finish, so its
-  second attempt re-pulls the trace the first one preserved.
-
-- Changed: `record stop` no longer carries a start-trim step no recorder could arm. The trim cut the
-  interval between recorder start and target-app readiness, but the runner's `recordStart` answer has
-  never carried either timing and the simulator path supplies none, so every built-in recording took
-  the untrimmed branch while the packaged Swift trimmer, its contract fields, and the telemetry
-  timestamp shifting stayed shipped with it. Gesture telemetry now carries the timestamps it recorded;
-  recorded videos are byte-for-byte the videos those paths already produced. Overlay burn-in, output
-  stability checks, and the recorder-start gesture-clock anchor are unchanged (#2584).
-
-- Fixed: an iOS capture that no backend could read now says which backend was asked and what was on
-  screen, instead of failing on the internal `regular iOS snapshot presentation requires a valid
-  viewport` invariant alone (#2560). The runner declares such a payload sparse — backend, reason code,
-  and its own reason — and the daemon read that verdict, then discarded it while reconstructing a
-  viewport from a synthetic root that has none. A `snapshot --actions` capture of a web sign-in sheet
-  therefore reported a viewport problem and named neither the private-AX backend that cannot read an
-  out-of-process surface nor the surface presented over the app. The verdict now travels with the
-  refusal as `error.details.snapshotQuality`, and the hint composes the shared sparse-capture advice
-  with the bundle id of the surface host when one is presented. On `replay` and `test` the verdict now
-  survives into the `REPLAY_DIVERGENCE` details, which carried only four cause keys before. Captures
-  that used to succeed are untouched: a sparse payload whose tree presentation can still serve presents
-  exactly as before, and a payload the runner did not declare sparse keeps the plain invariant byte for
-  byte.
-
-- Fixed: skipped `optional: true` Maestro steps are no longer invisible on the human surface
-  (#2560). The warning a skip leaves now travels with the run whether it later passes or fails:
-  `replay` prints a `Warning:` line after its summary and repeats the run's warnings after a
-  failed run's error, `test` prints a `Warnings:` section after the suite summary naming each
-  test, and a failed test result gained the `warnings` array the passing result already had, so
-  `--json` and JUnit carry the skipped steps of a failing test too.
-- Fixed: an Apple runner presentation refusal now carries the registry identity of the system
-  surface the tree was acquired from as `error.details.systemSurface` (#2560). Previously a
-  selector-backed command failing at the capture boundary under `optional: true` gave nothing
-  naming that boundary — the web sign-in sheet out of `SafariViewService` was invisible in the
-  error, and the miss looked like a selector problem inside the app. The sparse-declared case
-  already names the surface host in its hint via #2572; this covers the provenance everywhere
-  the runner reports one.
-- Changed: a capture that a backend cut at one of its limits now says so in the snapshot's
-  warnings, on every platform, instead of only setting `truncated: true` in JSON. The text path
-  had no disclosure at all, so an agent read a screen missing its footer, tab bar, or the items
-  after a long list as complete — the backends walk the tree in document order, so what falls
-  off is what comes last, on screen or not. One shared warning renders from the shared flag; the
-  limit and dimension stay backend-side. The depth-cap warning no longer suggests `--scope` as a
-  way to read deeper: on iOS, scope narrows the presented view and acquisition stays scope-blind.
-- Changed: the iOS Simulator AX bridge caps a capture at 5000 nodes, up from 1500, the Android
-  helper's bound. Measured on a synthetic 600-row screen, acquisition time did not move with the
-  cap (the native read fetches the whole tree; the cap only stops conversion) while the 1500 cut
-  dropped the screen's on-screen footer.
-- Fixed: Android snapshots carry the accessibility `selected` state an app sets on a control, so
-  `is selected`, a `selected=true` selector, and a Maestro `selected:` qualifier work on Android
-  (#2462). The helper never serialized the attribute, and the host reads only the helper's XML, so
-  no later layer could recover it: `get attrs` had no `selected` field, no snapshot
-  node was marked selected, and the same assertion that passed on iOS failed on Android with
-  "Maestro visible condition did not match" for an element that is visible — while `selected: false`
-  matched every Android node. The helper now emits both answers, like `enabled` and `password`, so
-  an unselected control answers `false` and a helper older than the attribute answers nothing; the
-  host parser, the Android hierarchy node, and the published snapshot node carry it through to
-  `get attrs` and the `[selected]` marker in snapshot text. Snapshot lines now render that marker
-  whenever selection is rendered, not only when text surfaces are summarized: `--settle` and `diff`
-  already compared selection, and a line that compares a fact it cannot display turns a tab tap
-  into a changed pair whose two lines look identical.
-- Fixed: Replay test artifacts with colliding filenames retain distinct copies without overwriting
-  other diagnostics, replay sources, timing traces, or attempt manifests.
-- Fixed: Custom test reporters reject invalid exit codes, including values such as `256` that
-  could wrap to success and hide a failing suite. `getExitCode` accepts integers from `0` to `255`
-  or `undefined`; JSON output reports an invalid code as one `INVALID_ARGS` error.
-- Fixed: Android `record start` no longer refuses to begin after a reused emulator reassigned the
-  previous recorder's pid. A completed recording's native marker is retired only once its recorder is
-  proven gone, but only an absent pid counted as proof — a pid that now names an unrelated process,
-  or a recorder that exited and waits to be reaped, did not. `record start` then failed every later
-  attempt with `Android screenrecord completed evidence cannot be safely retired`, and `record stop`
-  could not return an already-finalized recording. Proven termination now retires the marker and
-  returns the stored completion; a live or unreadable recorder still blocks, and the unrelated
-  process is never signalled. A reused pid that runs a replacement `screenrecord` on the same
-  remote path proves the old recorder gone but not that the path is free, so that marker and
-  artifact are retained until the replacement ends, and neither is signalled (#2476).
-- Fixed: Android `record start` no longer refuses forever on an emulator re-adopted under a new
-  serial. The device-side marker records the device identity that wrote it and a later start retired it
-  only when that identity matched, so a marker left by an earlier session on the same AVD blocked every
-  recording on the re-adopted device with `Android screenrecord native recovery evidence already exists`
-  — reported as an internal error whose hint asked for a bug report — while `record stop` answered that
-  no recording was active and no session could reach the marker, because recovery always binds the
-  device identity its own record names. A marker now retires when its recording is terminal or when it
-  names a device identity this transport can no longer address, and only once every recorder it names
-  has provably released its artifact; an interrupted launch commits no recorder identity, so its
-  artifact is checked against the recorders running on the device first. A recorder that is still
-  writing is left alone: `record start` refuses with `DEVICE_IN_USE` and `details.writer` naming whether
-  the marker's own recorder or another one holds the path, and only the unmanaged one ends on its own at
-  Android's 180 second limit. A device that cannot answer that question — an unreadable process table,
-  or a candidate process whose identity cannot be read — is refused rather than assumed free, even when
-  other recorders writing that path were identified, so an artifact is never removed under a recorder
-  the probe failed to see. What still refuses — unreadable or undecodable evidence, a marker the other
-  transport mode wrote, and an open recording this device identity still owns — is now a typed error
-  naming the marker path and the command that clears it, `record stop --session <name>` or removing the
-  marker once no session owns it, instead of `UNKNOWN` (#2550).
-- Fixed: a polling `wait` no longer surrenders its whole budget the first time the iOS runner
-  answers `RUNNER_BUSY`. That code means an earlier command exceeded the runner's execution
-  watchdog and its abandoned main-thread work is still draining, which clears on its own, so a
-  `wait text ... 20000` could fail in under a second with a failure the runner itself asked the
-  caller to retry. A poll refused with a failure its producer marked retriable is now ridden out
-  like an unreadable capture: the wait keeps polling to its deadline, records the poll as
-  `retriable` in its timeout evidence, and surfaces the refusal only if no readable capture ever
-  completed. That surfaced refusal keeps the producer's code, message and retry details and now
-  also carries the wait's own `captures`, `readableCaptures`, `waitedMs` and `polls`, so a budget
-  spent entirely on refusals is distinguishable from one immediate refusal. A wedged runner
-  (`RUNNER_WEDGED`) is not retriable and still ends the wait at once.
-- Fixed: a runner failure recovered from the lifecycle journal after its transport response was
-  lost is now classified exactly like the same failure on a live response. `RUNNER_BUSY` reached
-  callers as a bare `RUNNER_BUSY` wire code without the `retriable` flag on that path, while the
-  live path published it as `COMMAND_FAILED` with `details.runnerErrorCode` and `retriable: true`;
-  both paths now read the runner's code through one classifier.
-- Fixed: iOS Simulator snapshots of Safari and of apps with a `WKWebView` stopped showing the
-  page in 0.21.0 — chrome plus empty `[webview]` nodes, no links, text, or form fields, so no ref
-  could reach the page (#2484). The host AX bridge that 0.21.0 made the Simulator's snapshot source
-  reads one process, and WebKit content lives in another; the bridge delivered the boundary as
-  an `AXRemoteElement` leaf and the tree was published as if that were the screen. The source now
-  refuses a tree whose on-screen web view ends at that leaf (`remote-content-boundary`) and the
-  route serves XCTest, which resolves remote elements, for the rest of that app generation — the
-  same path 0.20.x used. The snapshot discloses the switch through its warning, and a relaunch
-  re-enables the bridge.
-- Fixed: `test` expands relative globs from the caller's literal working directory, so directory
-  names containing glob characters no longer cause missing suites or select a different directory.
-  Missing non-glob inputs also retain their not-found error in these directories.
-- Fixed: JUnit reports remain readable when replay results contain characters forbidden by XML 1.0,
-  replacing them with U+FFFD while preserving legal Unicode and whitespace. Original suite values
-  remain available in JSON and other reporters.
-- Fixed: `replay export` preserves deep links without `//`, including `tel:` and `mailto:`, as
-  Maestro `openLink` commands in both standalone and app-plus-link `open` actions.
-- Changed: a command whose synopsis is generated names each option with the label its declaration
-  carries, so `snapshot` now shows `--depth, -d <depth>` and `--scope, -s <scope>` where it used to
-  show the short aliases, and `--record` is documented under `Command flags:` instead of inside the
-  `snapshot` and `is` synopsis lines. `snapshot`, `proxy`, `daemon`, `device`, `doctor`, `prepare`
-  and `tv-remote` no longer restate their option list in a hand-written usage string, so adding an
-  option to those commands updates `--help` on its own (#2444).
-- Fixed: iOS `--depth` on `snapshot`, `is`, `wait`, `get`, and `find` no longer fails with
-  `regular iOS snapshot presentation requires a valid viewport` when the runner plan is pinned or
-  deferred to the private AX backend (custom actions, a private AX verdict on the session, or the
-  XCTest channel penalty). The runner refused a regular depth-capped request on every backend but
-  the recursive tree, fell through to its synthetic sparse root, and the daemon rejected that root
-  as a missing viewport. Presentation applies the presented-depth cut to whatever hierarchy a
-  backend acquired, so every backend serves the request; the private AX declaration is now
-  `regular-depth=presentation-cut` and an acquisition that stopped short of the cut keeps
-  disclosing that through `truncated`/`effectiveDepth` as it does unscoped.
-- Fixed: repeated unfiltered Android snapshots stay compact when identical element bounds arrive
-  with a different property order. Changes to the bounds still re-emit the tree.
-- Fixed: iOS `network dump` no longer omits requests that reused a keep-alive connection.
-  CFNetwork logs a request URL only on the line that opens a connection, so a second request to
-  the same host produced no `url:` line and was dropped from the dump entirely — an "this endpoint
-  was called" check read as a definite fail. Such a request is now reported against the origin its
-  connection was opened for, with `pathUnavailable` set, its status, and its timing. A reused
-  request whose connection was opened before the scanned window cannot be named at all; those are
-  counted in the dump's `unnamedRequests`, so an empty result still reports that traffic was
-  observed. The identities behind that count reconcile the app-log and recovery windows internally
-  — so overlapping traffic is not double-counted and disjoint traffic is not under-reported — but
-  the response carries only the count, which stays bounded however large the scan window was. The notes say absence of an endpoint does not prove it was not called.
-- Fixed: a URL logged as a delimited `url: <value>,` field no longer keeps the separator the log
-  format put after it, so an entry's `url` compares equal to the endpoint under test. A bare URL
-  elsewhere is left alone, since nothing there establishes that trailing punctuation is not part of
-  the path.
-- Added: `replay export` supports flows that switch apps and return, preserving each
-  `open <appId>` target as an explicit Maestro `launchApp.appId`.
-- Added: `replay export` converts recorded `home` actions to Maestro `pressKey: Home`, allowing
-  app-to-home-to-app journeys to be exported.
-- Added: polling `wait` timeouts (`wait <selector>`, `wait text`, `wait @ref`, and `wait absent`
-  after a readable capture) carry a per-poll timeline in `error.details` (`captures`, `polls[]`
-  with `startedMs`, `durationMs`, and a typed `outcome`: readable, unreadable, deadline,
-  runner-restart) next to the unchanged `reason`, so a failure says where its budget went without
-  opening the request log. Long waits keep the first five and last twenty-five polls. The replay
-  landmark-mismatch refusal carries the same poll evidence next to its mismatch details; `wait
-  --stable` timeouts and a never-readable strict absence keep their existing diagnostics.
-- Fixed: Android `orientation` now returns once the display reports the requested rotation
-  (polling `dumpsys display`, up to 15s) instead of right after writing the settings. On a loaded
-  emulator the rotation takes seconds, during which accessibility reads hang, so the next command
-  paid for the transition; a `wait` issued right after `orientation` could spend its whole budget
-  there. A display that never reaches the requested rotation now fails the command with the
-  observed rotation instead of reporting success; a display that reports no rotation is left to
-  the setting as before.
-- Fixed: the iOS Simulator AX snapshot route bounds how long a capture waits for app discovery
-  and stops starting a discovery per capture. Discovery (`simctl launchctl list` through xcrun)
-  takes seconds on a loaded host; a capture now waits at most 1.5s for the one in-flight
-  discovery, takes the XCTest fallback, and the discovery keeps running under its own 15s
-  deadline for the captures that follow. Previously each capture ran its own probe with a 3s
-  timeout on its critical path, so a `wait` issued right after `open` could spend its budget on
-  probe timeouts and report `wait_capture_stalled` with the app already on screen.
-- Fixed: iOS snapshots no longer report `truncated: true` merely because a later backend produced
-  them. The runner stamped every recovered capture as truncated — including a complete private-AX
-  tree taken while the XCTest channel was penalized as slow — so a strict `is absent` / `wait absent`
-  refused it with "capture was truncated" on loaded CI hosts. `truncated` now tracks completeness
-  only: payload truncation, a depth-limited capture, or a sparse terminal payload.
-- Fixed: Android `alert accept` / `alert dismiss` return only once the dialog has left the
-  accessibility tree (a different alert taking its place counts as dismissed), matching the iOS
-  runner's re-check. Previously they returned right after the button press, so the next read could
-  still see only the dialog window. A dialog that stays visible past the action budget now fails with
-  `alert <action> did not dismiss the visible alert`.
-- Added strict `wait absent <selector> [timeoutMs]` polling for zero selector matches. Incomplete,
-  sparse, truncated, scoped, depth-limited, and Android unreadable captures cannot prove absence;
-  deadline diagnostics retain typed capture evidence and stable first-match details (#2236).
-- Added: the device-claim store can hold an allocator-held claim (schema v3) for a device an
-  allocator-managed pool owns. It has no owning process, so `device status` lists it in the normal
-  view (never as stale), `device release --stale` refuses it with `allocator-held-owner`, the
-  daemon-startup sweep and session close leave it alone, and a command that binds the device
-  ordinarily is refused `DEVICE_IN_USE` / `DEVICE_CLAIM_ALLOCATOR_HELD`. Process-owned claim files
-  are unchanged at schema v2. Two notes for mixed installations: a daemon older than this release
-  reads a v3 file as an unreadable claim record and fails closed rather than clearing it, and
-  `devices` reports no `claimedBy` for such a device until the managed-inventory filter lands.
-- Added the `harmonyos-instance` lease contract and CLI/runtime plumbing as a prerequisite for
-  HarmonyOS proxy support; provider/daemon allocation remains gated until its end-to-end lifecycle
-  is implemented and validated (#2266).
-
-- Fixed: `settings airplane on|off` now takes an Android device offline. It is applied through
-  the connectivity service (`cmd connectivity airplane-mode`), which drives the radios, instead of
-  writing `airplane_mode_on` and broadcasting `ACTION_AIRPLANE_MODE_CHANGED` — a broadcast Android
-  refuses for non-system callers, so the old path failed *after* writing the setting and left the
-  device reporting airplane mode with the network still up (#2223). The response now reports the
-   `airplaneMode` the connectivity service holds after the change, and an Android build that does not
-   expose that command is refused with `UNSUPPORTED_OPERATION` before anything is written.
-- Fixed: the MCP registry entry (`server.json`) now declares the fixed `mcp` subcommand via
-  `packageArguments`, so a registry-format launcher — the MCP Registry or the website's
-  `/.well-known/mcp.json` discovery manifest — starts the stdio MCP server. Previously it ran
-  `agent-device` with no subcommand, i.e. the bare CLI (#2275).
-- Breaking (0.21): iOS Appium/WebDriver snapshots now expose engine-owned acquisition facts and
-  typed fidelity warnings. The SDK snapshot `truncated` field is optional when Appium cannot report
-  hierarchy completeness; regular snapshots fail closed without valid viewport evidence, while
-  `snapshot --raw` remains available for diagnostics (#2195).
-- Security (daemon, remote/proxy HTTP only): when `AGENT_DEVICE_HTTP_AUTH_HOOK` is configured and a
-  request's hook result does not attest a `tenantId`, the request is now refused (401) outright — the
-  daemon no longer runs it as whichever tenant the client declared (RPC body `meta.tenantId` or
-  `flags.tenant`, or the `x-agent-device-tenant` header on the upload/artifact-download/diagnostics
-  routes) and no longer admits it unscoped when the client declares nothing either. This closes both
-  a shared-token impersonation path and an unscoped-access path to tenant-owned sessions/artifacts in
-  multi-tenant deployments. Deployments with no hook configured (the local loopback CLI) are
-  unaffected. A hook must attest `tenantId` on every request it wants the daemon to admit.
-- Breaking (0.21): removed aggregate performance compatibility (`perf`, `perf sample`, `perf metrics`, the `metrics` alias, optionless `client.observability.perf()`, and SDK `area: 'metrics'`). Use `perf frames`, `perf memory sample`, `perf cpu profile start|stop|report`, or `perf trace start|stop`; removed CLI and raw daemon forms fail with this migration guidance.
-- Breaking (0.21): removed legacy batch JSON steps with `positionals`/`flags`. Use `{"command":"...","input":{...}}`; rejected steps now include a concrete structured example.
-- Breaking (0.21): removed the deprecated Node client `command.rotate` wrapper and its `RotateCommandOptions` / `RotateCommandResult` exports. Use `command.orientation`; the already-removed CLI `rotate` form keeps its targeted migration error.
-- Security (MCP/AI-SDK tool surface): the operator-owned endpoint and path inputs — `daemonBaseUrl`,
-  the Metro `proxyBaseUrl`, `stateDir`, `cwd`, `iosSimulatorDeviceSet`, `iosXctestrunFile`,
-  `iosXctestDerivedDataPath`, `iosXctestEnvDir` — follow the credential inputs off the
-  model-writable tool surface: no longer advertised, refused as explicit input with guidance, and
-  resolved from env/config only (a model-writable `daemonBaseUrl`/`proxyBaseUrl` would redirect the
-  env-resolved token to an arbitrary server). Dropping these plus the credential fields shrinks
-  `tools/list` by roughly half. CLI flags and the SDK client options are unchanged.
-- MCP tool descriptions now declare their enforced client timeout envelope (90s default, 180s
-  install, 300s+ lease allocation, unbounded only for the streaming `test` runner), sourced from
-  the descriptor registry's timeout policy so the declared number cannot drift from the enforced
-  one.
-- Security (MCP/AI-SDK tool surface): the shared command-tool executor now enforces the advertised
-  tool schema as an admission boundary — every raw `tools/call` argument must appear in the tool's
-  advertised (`additionalProperties: false`) schema, or it is refused before config/env resolution.
-  Hiding a key from `tools/list` alone was insufficient: the router forwards raw arguments verbatim
-  and the MCP config resolver read `config`/`remoteConfig` as CLI flags, so a model-supplied config
-  file could load `daemonBaseUrl`/`daemonAuthToken` and redirect the operator's token to an
-  arbitrary endpoint. Deny-by-default closes that, the operator keys, and any unknown key at once;
-  operator env/config defaults still resolve (they never arrive as tool input). Retired keys are
-  still admitted so their migration guidance answers.
-- Security (MCP/AI-SDK tool surface): `daemonAuthToken` and the Metro `bearerToken` are no longer
-  advertised as tool input properties, and an explicit value is refused with guidance instead of
-  being forwarded. Credentials are operator-owned: set `AGENT_DEVICE_DAEMON_AUTH_TOKEN` (or
-  `daemonAuthToken` in `~/.agent-device/config.json`) and `AGENT_DEVICE_METRO_BEARER_TOKEN` on the
-  process serving the tools. The model both reads untrusted app UI text and picks tool arguments,
-  so a model-writable credential parameter was a prompt-injection exfiltration path. CLI flags
-  (`--daemon-auth-token`, `--bearer-token`) and env/config resolution are unchanged.
-- Release hygiene: after `npm publish`, `release:mark-dev` moves `main` to the next patch with a
-  `-dev` prerelease marker so the version on `main` never equals a published version (registry
-  scanners diff the tool surface per version string, and a moving surface under a released number
-  reads as a republish). `release:prepare` refuses to publish while the `-dev` marker is in place.
-- Windows `--platform web` works again. `agent-device web setup` no longer fails with
-  `npm not found in PATH`, and every web command — including `web doctor` — no longer fails with
-  `spawn EINVAL`. The managed `agent-browser` backend is now launched as `node <js-entry>` on every
-  platform instead of through its `node_modules/.bin` console shim, which is a `.cmd` file on
-  Windows that `child_process.spawn` refuses without a shell (CVE-2024-27980 hardening);
-  `shell: true` would only trade that for argument-quoting hazards and a `DEP0190` warning on every
-  command. Setup spawns `npm` from PATH unchanged on macOS and Linux, and runs npm's own
-  `npm-cli.js` under the current Node only on Windows, where a bare `npm` is not spawnable. A
-  managed install now counts as present only when the backend package itself is, and
-  `web setup --json` / `web doctor --json` gain `entryScript` and `packageDir`; the published
-  `binaryPath` is unchanged and still names npm's console shim, now informational rather than the
-  spawned command (#2022).
-- Parameterized `fill --record-as` protection is now recording-session-scoped instead of
-  fill-step-scoped (ADR 0017 amendment): a later, unrelated recorded action (`wait`, `is`, `get`) can no
-  longer re-serialize an app-rendered echo of an already-parameterized value into its own result or
-  `target-v1` identity evidence. An echoing `wait` landmark no longer qualifies as an ADR 0016
-  destination guard, so `session save-script` refuses it and directs the author to a stable landmark
-  instead of silently publishing the secret. The protection uses one small, explicit, ephemeral,
-  never-serialized per-session map populated only from values the author already opted to parameterize;
-  ordinary non-parameterized recordings are unaffected (#1398).
-- Android covered-state publication now has one owner: same-window surfaces remain visible for
-  diagnosis, while the daemon marks exactly ordered covered controls non-actionable with
-  `interactionBlocked: "covered"`. Helper-only `drawing-order` stays private rather than entering
-  the snapshot contract, sparse floating overlays remain usable, and API 23 fails conservative with
-  the existing `androidSnapshot.occlusionScanUnavailable` disclosure (#1832).
-- iOS regular `snapshot --depth` now measures depth after structural accessibility wrappers
-  collapse. The recursive-tree backend follows a bounded presented-depth frontier, so controls
-  that fit the requested regular depth are no longer lost behind raw wrappers; raw `--depth`
-  remains a traversal-depth limit. Flat query recovery is limited to one presented level, and
-  private AX does not claim deeper regular-depth completeness until it has a hierarchy-aware
-  frontier (#1797).
-- iOS regular snapshot nodes now publish presentation-owned effective geometry through the existing
-  `rect` field: backend-reported frames remain available to acquisition, while regular output uses
-  the viewport and declared scroll-clip intersection. Raw snapshots and direct element reads retain
-  reported geometry (#1797).
-- Android recording-session commands now warn when blocking-dialog readiness inspection fails open. The requested command still runs, but the successful response discloses that readiness could not be inspected and preserves the inspection error's actionable hint, including `pnpm build:android` when the snapshot helper is unavailable (#1895).
-- Breaking (device selection): when a command needs one concrete device, carries no `--device`/`--udid`/`--serial`, and more than one candidate is equally preferred, agent-device now refuses with `AMBIGUOUS_MATCH` and the candidate list instead of quietly picking one. Established preferences are unchanged — virtual over physical, booted over offline, and the Apple kind/target ranking — so a single booted emulator beside offline ones still resolves, an existing session binding still resolves (its identity is already fixed), and explicit selectors still resolve. What no longer happens is choosing between two equally booted devices by discovery order or alphabetically: that produced a **successful response describing a device the caller never selected**, and reads are no safer than writes there. `devices` and other genuinely multi-device commands never enter singular resolution and are unaffected. The error carries the bounded candidate list in the declared `devices` details domain, so CLI and MCP print it, with a hint naming the right selector for the platform (`--serial` for Android/HarmonyOS, `--udid` for Apple, or `--device "<name>"`).
-- `--udid` with `--platform android` (and `--serial` with an Apple platform) now fails as the flag mistake it is — `INVALID_ARGS` naming the right flag — instead of reaching device resolution and answering `No Apple device with UDID emulator-5580` for an explicitly Android request. `--udid` addresses Apple devices, `--serial` addresses Android and HarmonyOS; matching pairs and requests that name no platform are unchanged.
-- Breaking (`--session-lock strip`): a device selector that names a different device than the bound session is no longer silently discarded. `strip` exists to drop redundant platform/scope selectors; when it also dropped `--udid`/`--serial`/`--device`, the command kept running against the *bound* device instead of the one the caller named — a wrong-device action that looks like a success. Such a request now fails with `INVALID_ARGS` under both `reject` and `strip`, and the error carries the two identities structurally (`requestedDevice`, `boundDevice`) plus a hint offering the two real recoveries: close the bound session if the requested device is intended, or remove the selector if the bound device is. The hint no longer suggests `--session-lock strip` for an identity conflict, since following that advice is what produced the wrong-device run. Scope-only stripping (`--platform`, `--target`, `--ios-simulator-device-set`, `--android-device-allowlist`) is unchanged.
-- iOS regular snapshots now apply one backend-neutral eligibility rule after every capture backend: a node survives when its accessibility type is interactive or it carries a non-empty label, identifier, or value. This removes the tree backend's extra "hittable non-Other" membership path and drops unlabeled decorative nodes consistently; labeled images, identifier-only nodes, and value-only nodes still survive. Raw snapshot membership is unchanged.
-- iOS regular snapshots now run one shared clip fold inside presentation for every capture backend (#1797). Backends serialize reported facts -- every traversed node, at raw traversal depth -- and presentation alone decides what the viewport and scroll clips hide, books the scroll hints, and collapses depth; no backend carries its own copy of that interpretation anymore (the copies are what produced the scroll-overflow leak class, #1784). Three intentional edge deltas ride along, all in the direction of one backend-neutral rule: sub-pixel content-free decorations are now dropped by every backend (previously private-AX only); labeled offscreen Application/Window carriers now survive on every backend (previously tree only), still never hittable; and a query-sweep recovery snapshot without `-i` no longer lists offscreen elements. Nothing outside its clip, and nothing without geometry, is ever `hittable` in a regular snapshot, whatever the backend reported.
-- iOS `snapshot --raw` is now the acquired accessibility tree on every backend that can serve it (#1797). A raw request that recovered onto the private-AX backend — the route an app whose XCTest tree capture fails takes — returned the *regular* projection's viewport-pruned nodes labeled raw: everything scrolled out of the viewport, and every sub-pixel decoration, was missing from the one view whose purpose is showing what the pruned view hid. Raw now keeps every node the backend serialized, at traversal depth, and `--depth` still narrows it (for raw, presented depth *is* traversal depth). Two structural rules replace the hand-synchronized ones: the raw capture plan is derived from each backend's declared ability to serve raw, so the interactive query sweep — which has no hierarchy to return — cannot be planned for a raw request; and presentation refuses an acquisition captured for the other projection instead of relabeling it, dropping that tier with a structured failure. Breaking in the same direction: `snapshot --raw -i` now returns the acquired tree instead of an interactive-filtered one — `-i` narrows the regular projection, and the pair used to produce a third membership rule that differed per backend. Regular and `-i` output is unchanged. Backends now read one derived capture hint rather than the request itself, so what a capture is allowed to skip is stated once, next to the proof that skipping it keeps the projection complete.
-- Android `snapshot --raw` is now the acquired accessibility tree (#1832 C3): the regular-projection classifiers for nodes Android marks invisible and stale application windows no longer run at parse time, so `--raw` keeps everything the helper serialized (normalization only). Covered same-window surfaces are publication annotations rather than membership pruning. Also: Android blocking-dialog recovery now reads the same daemon presentation an agent's `snapshot` sees instead of a hand-rolled subset, and acts on its occlusion result — a stale "App isn't responding" surface left under the foreground one no longer triggers recovery, and a covered "Close app" is never tapped ahead of the visible one; the Android freshness route signature no longer keys on `role`, a field the Android backend never carries; and the Android helper's declared fidelity residues (no `checked`/`checkable`/`long-clickable`, 5000-node cap before scoping, API-level cache-reset divergence) are recorded in `CONTEXT.md`.
-- `agent-device mcp` now carries its own usage guidance, so MCP-only clients (Codex CLI, Cursor, custom agents) no longer depend on a separately installed skill (#1833). The handshake `instructions` — returned by both `server/discover` and, newly, the legacy `initialize` — is a compact (< 2 KB, the Claude Code truncation limit) workflow card: start with `open {app, foreground: true}` instead of probing, act with `settle: true` and continue from the diff, verify with `wait`/`is`/`get`/`find`, copy `@refs` byte-for-byte, recover from sparse/AX-unavailable, follow error hints, `close`. A new MCP-only `help` tool serves the full guides on demand: no `topic` returns the CLI's decision card; `topic` returns `agent-device help <topic|command>` verbatim (workflow, gestures, scripting, tv, macos, web, remote, debugging, …, or any tool name for its complete flag reference), prefixed with the one-line CLI→tool-property mapping. `help` is router-owned rather than a command descriptor, so it appears in `tools/list` only — not in the CLI, Node client, or `batch` — and its description tells the model it is not a startup step. Legacy `initialize` gains the optional `instructions` field; no other legacy field changes.
-- Android `snapshot --scope` (and every selector command's `--scope`, e.g. `press "Save" --scope Panel`) now resolves scope exactly once, inside the Android projection, under the shared scope specification: the scope root is the first node **in document order** whose label, value, or identifier contains the scope text (case-insensitive) **and whose subtree still has content in the projection you asked for**, the result is that subtree re-rooted at depth 0, and no match returns an empty snapshot (#1832). That second clause is what makes `snapshot -i --scope panel` return the button inside a structural container `-i` drops, and stops a decorative heading that happens to match from emptying the snapshot. Before, Android ran two passes with contradictory rules — a breadth-first platform match that fell back to the full tree on a miss, then the daemon's document-order pass — so a shallower later container could win over an earlier match, and an interaction capture whose scope reached only the daemon layer was silently unscoped. `--depth` under `--scope` counts from the scope root, filtering the depths the response prints (a node shown at depth 0 is never hidden by `--depth 0`), and ancestor context above the scope root (a clickable row, a list) still shapes `-i` membership inside it. The rule is pinned by `contracts/fixtures/snapshot-scope-policy.json`, the same golden table the iOS runner consumes (#1797).
-- New `hover <x y|@ref|selector>` command for `--platform web` (#1783). It moves the pointer over the target without pressing, so hover-gated UI — a message row's `...` toolbar, a menu that opens on pointer enter — becomes reachable through agent-device the way it already was through the underlying `agent-browser` backend (`mouse move`). It is a member of the targeted-touch family: same `@ref`/selector/coordinate targeting, occlusion and off-screen guards, and `--settle` (the settled diff carries the revealed controls with fresh refs, e.g. `+ @e4 [button] "Delete"`), but no `--verify`, since hover reveals rather than activates. `hover @ref` publishes as a portable selector line in recorded scripts, and the Node client exposes `interactions.hover`. Hover is a pointer state that touch platforms do not have, so `capabilities` advertises it on web only and iOS/Android/Linux reject it during admission with `UNSUPPORTED_OPERATION` and a hint naming `--platform web`; `longpress` remains the mobile hold-gesture verb.
-- Internal: session recording is now derived from the script-publication lifecycle instead of being stored beside it. `SessionState.recordSession` is removed; `isRecordingPublication` answers the question from the aggregate (ordinary authoring records only while ARMED, a repair transaction records for its whole lifetime). The stored flag was a second source of truth that handler surfaces set directly, which is how #1533's aborted-recording drift arose — no surface can now arm recording without moving the lifecycle that authorizes it, and the script writer's publication gate is answered entirely by the aggregate. Behavior-preserving: the derivation reproduces what the flag held at every transition.
-- Fixed: a script recording aborted by a second `open` is no longer published by a later bare `close` (#1533). `open <app> --save-script` followed by a second successful `open` terminates the recording and warns "Script publication was aborted…", and `close --save-script` correctly refuses it with "Retry with plain close; it will tear down the session without writing." But when that second `open` itself carried `--save-script`, the flag re-armed recording behind the terminal status, and a bare `close` then wrote the full session log to disk — publishing a recording the caller had been told was aborted, and breaking the promise the refusal makes. An aborted authoring lifecycle is now terminal by construction: `--save-script` arms nothing on any surface that handles it — the re-open builder, the close finalizer, and the recorded-action ingress — and the script writer refuses the lifecycle from every path that reaches it (bare `close`, teardown, idle-reap, active publication). This also stops an aborted session from paying recording-time costs it can never publish: a re-opened aborted recording no longer keeps the direct iOS selector fast paths for `click` and `get` disabled. Armed recordings, published recordings, and every repair transaction are unaffected.
-- `agent-device mcp` now serves the stateless MCP `2026-07-28` revision alongside the handshake-based revisions it already spoke, as the spec's "dual-era server". Modern clients probe `server/discover`, which advertises the supported revisions, the tools capability, and server identity; their requests declare a protocol version in `_meta`, and their results carry `resultType: "complete"` plus `_meta["io.modelcontextprotocol/serverInfo"]`. `tools/list` and `server/discover` now return the `ttlMs`/`cacheScope` cache hints, so a client can cache the 55-tool, ~223KB tool list for an hour instead of re-fetching it on every start; the list was already emitted in a deterministic (sorted) order, which is the other half of what makes it cacheable. Each revision is answered on its own wire contract: a request declaring `2025-11-25` or `2025-06-18` through modern framing still gets the legacy result shape, and `initialize` never agrees to `2026-07-28`, which has no handshake to establish. A declared revision this server does not implement is rejected with `UnsupportedProtocolVersionError` (`-32022`) naming the ones it does, rather than being served under a version the client did not ask for, and modern framing that omits its required `protocolVersion`/`clientCapabilities` metadata — or supplies a `clientInfo` that is not a valid `Implementation` — is rejected as invalid params. `initialize` and `ping` were removed in `2026-07-28`, so a modern-framed call to either is answered `-32601` rather than served inside a `resultType: "complete"` envelope. Responses to legacy clients are unchanged byte-for-byte — `initialize` and `ping` are still served, and no cache, `resultType`, or `_meta` field is added to their results. Nothing here affects the CLI, Node, or daemon surfaces: the stdio transport, the tool set, and every tool's input/output schema are untouched.
-- Fixed: the MCP `initialize` handshake now answers with the protocol revision the client requested when it is one this server implements, instead of always answering `2025-11-25`. A client pinned to `2025-06-18` was told to speak a revision it had not asked for, which the lifecycle contract answers by disconnecting.
-- `agent-device help workflow` is now a compact ~8KB card instead of a ~41KB dump; the same depth still exists, split into `help scripting` (save-script, secret-safe fills, batch JSON, replay divergence/repair, recording) and `help gestures` (multi-touch shapes and platform quirks), plus a few paragraphs folded into the topics that already owned the subject (`help debugging`, `help physical-device`, `help validate`). Every `help <topic>` first line is now `agent-device <version> — <topic>` so an agent can read the installed version from its mandatory first help read instead of a separate `agent-device --version` call.
-- Cloud iOS (BrowserStack, AWS Device Farm): `snapshot` and `diff` no longer fail with `SESSION_NOT_FOUND` on a live provider session (#1658). The app-session guard they ran belongs to the local XCUITest runner, which must attach to a target app; a cloud capture reads the provider's own driver session and needs no app identity, so the guard now applies to local Apple targets only. Relatedly, a cloud iOS `open com.example.app` now records that bundle id on the session — the provider path skips local app resolution (no simctl/devicectl reaches a hosted device), and used to drop an explicitly spelled bundle id along with it, leaving the session with no app identity at all. Opening a second bundle id replaces the first, matching the local path, where an explicitly spelled target always wins over the session's current app; deep links, display names, and bare `open` still keep the app already tracked.
-- Cloud `fill` (BrowserStack, AWS Device Farm) now witnesses that the field it tapped actually holds text-entry focus before sending its keys, instead of dispatching tap and keys in back-to-back requests (#1658). A WebView input — an OAuth/SSO page in a Safari view controller, for example — takes first responder asynchronously, so the keys used to land with nothing focused while `fill` still answered "Filled N chars"; tapping and filling as two separate commands worked only because the round trip between them gave the field time to focus. The witness is the focused element's own geometry: `fill` polls the active element and proceeds only once it contains the point it tapped, which is the one signal that identifies *which* field took focus. Keyboard visibility cannot — it reads the same before and after a second fill into an already-open form, so it could not tell a focused password field from the email field the previous fill left focused. The response discloses `textEntryReadiness`: `focused-element`, or `keyboard-shown` when the driver has no active-element route but the keyboard rose from hidden after the tap. Both describe a fill that witnessed focus before typing; there is deliberately no value for typing without evidence, because nothing renders this field and such a value would reach a caller as an ordinary success. Breaking: when focus cannot be witnessed, cloud `fill` now FAILS with `COMMAND_FAILED` / `text_entry_focus_not_observed` and sends no keys, instead of typing into whatever holds first responder and answering "Filled N chars" — a fill with no witness must not read as a filled field. That covers a tap that focused nothing, a keyboard already up on a driver that cannot name the focused field, and a driver that reports neither (`text_entry_focus_unobservable`, which points at `press` + `type` as the deliberate way to enter text unwitnessed). Only a positively classified unimplemented route counts as unsupported, so a dead session, an auth rejection, or a grid outage surfaces instead of degrading into a blind text entry.
-- Changed mutating selector ambiguity semantics (press/click/fill/longpress): duplicate accessibility wrappers collapse only when every match forms one ancestor-descendant chain resolving to the same actionable node. Matches in distinct subtrees now fail fast with `AMBIGUOUS_MATCH` and a bounded, immediately reusable candidate-ref frame; visible/depth/area geometry no longer silently picks a mutation target. The direct iOS XCTest path now counts raw exact matches before hittability and delegates ambiguity to the same runtime rule. AppControlBench provenance: element-14 ran on 0.20.5; this change is intended for 0.20.7+, and comparative benchmark reports should note that it can replace a wrong-success recovery loop with one candidate-pick turn while occasionally adding that turn for genuinely distinct duplicates.
-- `scroll` and `back` now accept `--settle` (with `--settle-quiet` and `--timeout`), collapsing scroll-then-observe and back-then-observe into one call (#1638). The response carries the same settled payload the touch commands return — verdict, changed-lines diff with fresh refs on added lines, the unchanged-interactive tail, and `refsGeneration` when the settled tree was stored — and is best-effort: it never fails the action. One difference is deliberate: `scroll`/`back` resolve no element, so the diff baseline is the session's stored pre-action tree ("the last tree you observed") rather than a freshly resolved pre-action capture. Both commands now also preserve the daemon on timeout, like the other settle-capable commands.
-- Security: repository `./agent-device.json` now accepts only project-safe automation defaults. It rejects daemon endpoint/auth/transport/server settings, tenant/run/lease selectors, provider/cloud and Metro connection fields, headers, executable reporter modules, local write destinations, and other operator-controlled values before local module loading or any daemon health/RPC request. Put remote endpoint and token together in protected CI environment variables, user config, an explicit `--config` file, or the existing `connect`/`--remote-config` workflow. Daemon auth tokens no longer travel in serialized command flags.
-- `viewport` is now rejected during capability admission on Apple targets instead of reaching the device and failing inside dispatch. No Apple backend can resize a screen — simulator and device geometry is fixed by the selected device type — so `viewport` on iOS/iPadOS/tvOS/macOS now fails with `UNSUPPORTED_OPERATION`, `viewport is not supported on this device`, and a hint pointing at `--platform web` and at picking a different simulator. `capabilities` no longer advertises `viewport` on Apple targets. Web viewport resizing (`agent-device viewport 1280 900 --platform web`) is unchanged, and Android was already denied.
-- `--save-script` is now accepted only by the commands that declare it — `open`, `close`, and `replay`. A hand-built daemon request (or a `batch` step) that set `saveScript` on any other command, such as `record` or `trace`, used to arm script publication and could write a `.ad` artifact; it is now rejected with `INVALID_ARGS` before the request reaches admission, the device, or any handler. CLI, Node, and MCP usage of `--save-script` on its documented commands is unchanged.
-- `diff screenshot` no longer runs the retired best-effort OCR and non-text analyzers. Their optional `ocr` and `nonTextDeltas` fields remain in the result type for source compatibility but are no longer emitted; use the baseline/current images and diff artifact with vision for qualitative interpretation.
-- Breaking: removed the deprecated `--session-locked` and `--session-lock-conflicts` flags. Use `--session-lock reject|strip` instead; passing either old flag now fails with `Unknown flag: ... Use --session-lock reject|strip instead.`
-- Breaking: removed the `replay export --format` flag. `replay export` always writes Maestro YAML.
-- Breaking: removed the unused `LeaseAllocatePayload`, `LeaseHeartbeatPayload`, and `LeaseReleasePayload` type exports from `agent-device/contracts`. Lease request metadata is fully described by `DaemonRequestMeta`.
-- Maestro compat: `assertVisible` and `assertNotVisible` now accept `childOf` for ancestor scoping, matching `tapOn` (#1294).
-- Breaking: removed deprecated gesture duration and rotate velocity inputs (#1218).
-  - `swipe x1 y1 x2 y2` no longer accepts a trailing `durationMs` positional; use `gesture pan x1 y1 (x2-x1) (y2-y1) durationMs` for deliberate timed drags.
-  - Maestro `swipe` operations with a duration continue to normalize to `gesture pan` with the `endpoint-hold` execution profile, preserving the Maestro-compatible fast-swipe-then-hold behavior on iOS.
-  - `gesture fling direction x y` no longer accepts a trailing `durationMs` positional; use `gesture pan` for timed movement.
-  - `gesture swipe preset` no longer accepts a trailing `durationMs` positional; use `gesture pan` for timed movement.
-  - `gesture rotate degrees [x] [y]` no longer accepts a trailing `velocity` positional; rotation pacing is derived from `degrees`.
-  - MCP/Node schemas no longer advertise `velocity` or `durationMs` on `swipe`/`fling`/`gesture swipe`; `durationMs` remains on `gesture pan` and `gesture transform`.
-  - A `.ad` script that still carries a removed positional now fails when the script is parsed, before the replay executes any device action, naming the line and its rewrite (for example `swipe accepts 4 arguments: x1 y1 x2 y2 (line 6). The trailing durationMs positional was removed: use "gesture pan 197 650 0 -350 300" ...`). Previously the script ran up to that step and then failed as a replay divergence.
-  - Published the [gesture migration guide](https://agent-device.dev/docs/migrating-gestures) covering CLI, Node.js, MCP, and saved `.ad` recordings, plus the deprecation policy the next such removal follows (#1216).
-  - `replay export` now writes an explicit `duration: 100` for `swipe` — the canonical fling duration — instead of omitting it and letting Maestro apply its own 400ms default. Maestro flows replayed by `agent-device` are unaffected; a timed Maestro `swipe` still normalizes to `gesture pan` with the `endpoint-hold` profile.
-- Breaking: the deprecated `rotate` CLI command alias has been removed. Use `orientation` instead; invoking `rotate` now fails with `rotate was renamed to orientation; for the two-finger gesture use: gesture rotate`.
-- Breaking (ADR 0014, session ref-frame lifetime): a mutation through an `@ref` now expires the session's ref frame, so a later ref mutation without a fresh observation fails closed with a typed `details.reason` (`ref_frame_expired`, `ref_generation_mismatch`, `plain_ref_requires_complete_frame`, or `ref_not_issued`) instead of acting on a possibly-navigated screen. A ref-oriented sequence that performs several mutations must re-`snapshot` between them, consume an honestly issued `--settle` ref in pinned `@eN~s<gen>` form, or use selectors. Enforcement applies on every platform, not just iOS. Legacy hand-written `.ad` scripts that reuse several bare refs from one snapshot must capture between mutations or use selectors.
-- Ref reads resolve against the authorized ref frame's source tree, so an internal read-only capture (including Android freshness) can no longer retarget an admitted `@ref` by positional coincidence. Read-only ref consumers keep the structured staleness warning while the frame retains the ref's evidence.
-
-## 0.15.0
-
-- Breaking: `apps` discovery and public app-list helpers now default to user-installed apps. Use `--all` or `filter: 'all'` to include system/OEM apps.
-- Breaking: removed the `agent-device/android-apps` public subpath. Use the Android app helpers from `agent-device/android-adb`.
-- Breaking: removed the `agent-device/daemon` public subpath. Use `agent-device/contracts` for daemon request/response types.
-- Breaking: removed public local ADB bypass/selection helpers such as `spawnAndroidAdbBySerial` and `resolveAndroidAdbProvider`; use `createLocalAndroidAdbProvider(device)` or pass providers directly to the helpers from `agent-device/android-adb`.
-- Added Android ADB provider helpers for exec, stream, clipboard, keyboard, app lifecycle, logcat, and port reverse workflows.
diff --git a/test/ci/root-docs-paths-ignore.test.ts b/test/ci/root-docs-paths-ignore.test.ts
index d7ad80e4b4..e4e177c524 100644
--- a/test/ci/root-docs-paths-ignore.test.ts
+++ b/test/ci/root-docs-paths-ignore.test.ts
@@ -1,5 +1,5 @@
-// Regression pin for #1781 A9: the six root-level docs files
-// (AGENTS.md, CHANGELOG.md, CONTEXT.md, CONTRIBUTING.md, LICENSE, SECURITY.md)
+// Regression pin for #1781 A9: the five root-level docs files
+// (AGENTS.md, CONTEXT.md, CONTRIBUTING.md, LICENSE, SECURITY.md)
 // must stay in the `pull_request` `paths-ignore` list of every workflow that
 // also ignores `docs/**`/`website/**`/`README.md` — the four device lanes plus
 // `ci.yml` and `size.yml`. Nothing else derives this: `check:gate-manifest`
@@ -22,14 +22,7 @@ const repoRoot = path.resolve(import.meta.dirname, '../..');
 
 const WORKFLOWS = ['ios.yml', 'android.yml', 'linux.yml', 'macos.yml', 'ci.yml', 'size.yml'];
 
-const ROOT_DOCS = [
-  'AGENTS.md',
-  'CHANGELOG.md',
-  'CONTEXT.md',
-  'CONTRIBUTING.md',
-  'LICENSE',
-  'SECURITY.md',
-];
+const ROOT_DOCS = ['AGENTS.md', 'CONTEXT.md', 'CONTRIBUTING.md', 'LICENSE', 'SECURITY.md'];
 
 type WorkflowDoc = {
   // A bare `on:` key can parse as the boolean key `true` under YAML 1.1
diff --git a/website/docs/docs/migrating-gestures.md b/website/docs/docs/migrating-gestures.md
index fe0b2217ed..dafd5c4ca1 100644
--- a/website/docs/docs/migrating-gestures.md
+++ b/website/docs/docs/migrating-gestures.md
@@ -167,8 +167,8 @@ flow runs at the speed the `.ad` script ran, rather than picking up Maestro's ow
 This is the process a public gesture input follows on its way out, and the bar the next removal has
 to clear:
 
-1. **Announce.** The input is documented as deprecated and recorded in `CHANGELOG.md` under
-   `Unreleased`, together with the replacement.
+1. **Announce.** The input is documented as deprecated, and the release notes name the
+   replacement.
 2. **Warn for one minor release.** The input keeps working and normalizes to the replacement, with a
    `deprecations` entry in the response so an agent sees the migration while the call still
    succeeds.

From d665e027bb80addef5d3ef39d340edd2142abb03 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 24 Sep 2026 18:44:42 +0200
Subject: [PATCH 103/132] refactor(ios-e2e): use canonical wait reasons in
 confirmation helper (#2919)

---
 .../ios-simulator-e2e-deep-link-confirmation.test.ts      | 7 ++++---
 .../ios-simulator-e2e/live-deep-link-confirmation.ts      | 8 +++++---
 2 files changed, 9 insertions(+), 6 deletions(-)

diff --git a/test/integration/ios-simulator-e2e-deep-link-confirmation.test.ts b/test/integration/ios-simulator-e2e-deep-link-confirmation.test.ts
index a07a38db8e..44ba5eef7e 100644
--- a/test/integration/ios-simulator-e2e-deep-link-confirmation.test.ts
+++ b/test/integration/ios-simulator-e2e-deep-link-confirmation.test.ts
@@ -1,6 +1,7 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
 
+import { WAIT_REASONS } from '@agent-device/contracts/wait';
 import type { CliJsonResult } from './cli-json.ts';
 import {
   answerDeepLinkConfirmation,
@@ -15,16 +16,16 @@ const LANDED = result(0, { success: true });
 const LAUNCH_PENDING = result(1, {
   error: {
     code: 'COMMAND_FAILED',
-    details: { reason: 'wait_capture_stalled', runnerErrorCode: 'APP_NOT_RUNNING' },
+    details: { reason: WAIT_REASONS.captureStalled, runnerErrorCode: 'APP_NOT_RUNNING' },
   },
 });
 const WRONG_ROUTE = result(1, {
-  error: { code: 'COMMAND_FAILED', details: { reason: 'wait_target_absent' } },
+  error: { code: 'COMMAND_FAILED', details: { reason: WAIT_REASONS.targetAbsent } },
 });
 const READABLE_TIMEOUT = result(1, {
   error: {
     code: 'COMMAND_FAILED',
-    details: { reason: 'wait_deadline_exceeded', readableCaptures: 5, captureTruncated: true },
+    details: { reason: WAIT_REASONS.deadlineExceeded, readableCaptures: 5, captureTruncated: true },
   },
 });
 const OPEN_PROMPT = result(0, {
diff --git a/test/integration/ios-simulator-e2e/live-deep-link-confirmation.ts b/test/integration/ios-simulator-e2e/live-deep-link-confirmation.ts
index cbeb4a4e64..71fd78e6ab 100644
--- a/test/integration/ios-simulator-e2e/live-deep-link-confirmation.ts
+++ b/test/integration/ios-simulator-e2e/live-deep-link-confirmation.ts
@@ -1,5 +1,6 @@
 import assert from 'node:assert/strict';
 
+import { WAIT_REASONS } from '@agent-device/contracts/wait';
 import type { CliJsonResult } from '../cli-json.ts';
 import { type LiveContext, runStep } from './live-harness.ts';
 
@@ -59,12 +60,13 @@ export async function answerDeepLinkConfirmation(
     const details = arrived.json?.error?.details;
     const launchPending = details?.runnerErrorCode === APP_NOT_RUNNING;
     const reason = details?.reason;
-    const readableMiss = reason === 'wait_target_absent' || reason === 'wait_deadline_exceeded';
+    const readableMiss =
+      reason === WAIT_REASONS.targetAbsent || reason === WAIT_REASONS.deadlineExceeded;
     const interruptedCapture =
-      reason === 'wait_capture_stalled' || reason === 'wait_runner_restart_exhausted';
+      reason === WAIT_REASONS.captureStalled || reason === WAIT_REASONS.runnerRestartExhausted;
     if (!launchPending && !readableMiss && !interruptedCapture) return;
     if (!answered) answered = await acceptOpenConfirmation(device);
-    if (!answered && reason === 'wait_target_absent') return;
+    if (!answered && reason === WAIT_REASONS.targetAbsent) return;
   }
 }
 

From 6508ef83347217ec5e518fd90704d8a3505a7b9c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Oskar=20Kwa=C5=9Bniewski?= <oskar@okwasniewski.com>
Date: Thu, 24 Sep 2026 18:45:12 +0200
Subject: [PATCH 104/132] test(android): a content description change
 invalidates snapshot reuse and survives the selector digest (#2920)

Review follow-up: `contentDescription` joined the presentation-equivalence key and the digest allowlist without a case in either table, so removing it later would have left both suites green.
---
 .../capture/runtime/snapshot-unchanged.test.ts       | 12 ++++++++++++
 src/daemon/__tests__/response-views.test.ts          |  2 ++
 2 files changed, 14 insertions(+)

diff --git a/src/commands/capture/runtime/snapshot-unchanged.test.ts b/src/commands/capture/runtime/snapshot-unchanged.test.ts
index c0ef723b71..c775416f77 100644
--- a/src/commands/capture/runtime/snapshot-unchanged.test.ts
+++ b/src/commands/capture/runtime/snapshot-unchanged.test.ts
@@ -70,6 +70,7 @@ test.each<Partial<SnapshotNode>>([
   { subrole: 'AXCloseButton' },
   { value: 'Draft' },
   { identifier: 'create' },
+  { contentDescription: 'Create a draft' },
   { enabled: false },
   { selected: true },
   { focused: true },
@@ -106,6 +107,17 @@ test.each<Partial<SnapshotNode>>([
   });
 });
 
+test('unchanged metadata keeps a content description that did not change', () => {
+  const described = () =>
+    snapshot('Create', {
+      nodes: [{ ...snapshot('Create').nodes[0]!, contentDescription: 'Create a draft' }],
+    });
+
+  expect(
+    buildUnchangedSnapshotMetadata({ previous: described(), current: described(), options: {} }),
+  ).toMatchObject({ nodeCount: 1 });
+});
+
 test('unchanged metadata detects node count, order and truncation changes', () => {
   const first = snapshot('Create').nodes[0]!;
   const second = { ...first, index: 1, ref: 'e2', label: 'Cancel' };
diff --git a/src/daemon/__tests__/response-views.test.ts b/src/daemon/__tests__/response-views.test.ts
index 73f7fde8ed..1ee1ef50de 100644
--- a/src/daemon/__tests__/response-views.test.ts
+++ b/src/daemon/__tests__/response-views.test.ts
@@ -203,6 +203,7 @@ const MATCHED_NODE = {
   label: 'Sign in',
   value: 'enabled',
   identifier: 'login-button',
+  contentDescription: 'Sign in to Demo',
   enabled: true,
   selected: false,
   focused: false,
@@ -227,6 +228,7 @@ const COMPACT_NODE = {
   label: 'Sign in',
   value: 'enabled',
   identifier: 'login-button',
+  contentDescription: 'Sign in to Demo',
   enabled: true,
   selected: false,
   focused: false,

From 5dee3becca5a35c80bac62876de24c4c5b26159d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 24 Sep 2026 18:45:42 +0200
Subject: [PATCH 105/132] fix(ios): carry the snapshot viewport across the
 runner boundary as a declared fact (#2908)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(ios): carry the snapshot viewport across the runner boundary as a declared fact

The runner spelled "viewport unknown" as CGRect.infinite, which
SnapshotGeometry.isGeometricallyActionable read as "everything is
actionable" before computing any center, while the host-AX path models
the same state as IosViewportEvidence and declines to publish the bit.
One state, two encodings, opposite directions, across a language
boundary.

SnapshotViewport now carries the three cases the host already uses --
reported, derived, and missing { reason } -- and refuses an unusable box
at declaration, so no caller has to re-check what it was handed. The
unknown-viewport policy is stated once, at the Swift decision site, and
fails CLOSED: no box means no supportable claim about where a tap lands.
Clipping stays a separate question from containment; a capture with no
box has no clip and no root clip for the cumulative invariant to
violate, which is an absent answer rather than an unbounded one.

* test(ios): pin the hittable predicate with a cross-language vector table

The fixed 320x240 fold fixture cannot reach an edge-of-viewport center, a
node rect neither language's null/empty check refuses, or an unknown
viewport, so the predicate's two implementations disagreed on two of
them: CGRect.infinite is built of finite Doubles and its center is (0,0),
and a negative width passes an empty check while its center lands inside
-- both actionable in Swift and not actionable in TypeScript. The private
AX bridge's JSON frame parser can hand over either.

contracts/fixtures/snapshot-actionability-policy.json is replayed by
ActionabilityPolicyTests (Swift) and by scripts/ios-snapshot-differential
.test.ts (TypeScript), which also asserts the host's own instrument:
resolveViewportEvidence refuses a regular presentation without a positive
finite viewport, which is why the TypeScript predicate has no unknown
viewport case. Rows come in pairs sharing one center so a `false` that
the guard, rather than containment, decides cannot go quiet.

* refactor(ios): plot the quarter-turn test through the shared rect predicate

`SnapshotGeometrySpace.isPlottable` and `SnapshotGeometry.isPositiveFinite`
were the same five comparisons, written twice in one package, which is how
#2891 started: one question with two encodings that can drift apart.
`.null`, an inverted box, and an infinite box are refused identically by
both, so the coordinate-space table needs no new rows.

* fix(ios): make the viewport type the only place a box becomes a fact

`SnapshotViewport.reported(box:)` normalised an unusable box to
`.missing(reason: .invalid)`, and the commit said no caller had to
re-check what it was handed — while `.reported(rect:)` stayed a public
case that accepted `CGRect.infinite` on the way past that claim. The
associated value is now a box with an internal initialiser, so outside
this package a viewport fact is only reachable through the two
factories, and the case labels cannot be named around them.
MSG2

* test(ios): write down the one input the two predicates cannot share

The table replayed `{"infinite": true}` as `CGRect.infinite` in Swift and as a
rect with infinite components in TypeScript, so its infinity row never put the
same number in front of both sides. `CGRect.infinite` is made of finite Doubles:
TypeScript would call those components actionable, and only the platform that can
name the value can refuse it. The row is now Swift-only and carries `asymmetry`
naming that, every row declares both `swift` and `typescript`, and a shared
non-finite row replaces it with numbers both sides actually see.

Also states three claims the code had not been checked against: a published
`hittable: false` is retained rather than filtered out, the runner's viewport fact
decides only runner bits because the host re-derives its own from the capture's
root node, and `viewportFromRoot` — not only `resolveViewportEvidence` — is what
makes the TypeScript `viewport` argument total.

* fix(ios): leave hittable absent without a viewport box; only a reported viewport anchors a rotation

A capture with no viewport box can still decide a disabled or degenerate
node, but not containment, so the runner now omits hittable instead of
declaring false, matching the host bridge's undefined bit. The interface
orientation moves into SnapshotViewport.reported, so a derived or missing
viewport cannot anchor a rotation, and SnapshotGeometrySpace takes the
viewport fact rather than a sentinel CGRect.

* chore(gates): route the actionability vector table to the differential lane

contracts/fixtures/snapshot-actionability-policy.json is read by both
sides of scripts/ios-snapshot-differential, and packages/kernel/src/rect.ts
holds the TypeScript predicate that table replays, so a change to either
must select that lane rather than rely on the generic golden-table rule
reaching only the unit and Swift builds.
---
 .../RunnerTests+AXSnapshotFallback.swift      |  35 ++-
 .../RunnerTests+Navigation.swift              |  14 +-
 .../RunnerTests+Snapshot.swift                |  27 +--
 .../RunnerTests+SnapshotAcquisition.swift     |  34 +--
 .../RunnerTests+SnapshotCapturePlan.swift     |   5 +-
 .../RunnerTests+AXSnapshotFallbackTests.swift |   5 +-
 ...nnerTests+PrivateAXPresentationTests.swift |  10 +-
 ...ts+SnapshotCapturePlanOccupancyTests.swift |   3 +-
 ...RunnerTests+SnapshotCapturePlanTests.swift |   2 +-
 ...RunnerTests+SnapshotHittabilityTests.swift |   2 +-
 ...SnapshotPresentationConformanceTests.swift |   2 +-
 ...ts+SnapshotPresentationGeometryTests.swift |   4 +-
 ...s+SnapshotPresentationInvariantTests.swift |  10 +-
 ...unnerTests+SnapshotPresentationTests.swift |  36 +--
 ...nerTests+SnapshotVisibilityFoldTests.swift |   6 +-
 .../SnapshotCoordinateSpace.swift             |  35 ++-
 .../SnapshotGeometry.swift                    |  30 ++-
 .../SnapshotModels.swift                      |  69 +++++-
 .../SnapshotPresentationInvariant.swift       |  22 +-
 .../SnapshotVisibilityFold.swift              |  21 +-
 .../main.swift                                |   3 +-
 .../ActionabilityPolicyTests.swift            | 118 ++++++++++
 .../ConformanceTests.swift                    |   2 +-
 .../CoordinateSpaceTests.swift                | 163 +++++++------
 .../FixtureRect.swift                         |  41 ++++
 .../InvariantTests.swift                      |   2 +-
 .../RegularDepthTests.swift                   |   2 +-
 .../snapshot-actionability-policy.json        | 220 ++++++++++++++++++
 .../adr/0004-ios-snapshot-backend-strategy.md |  10 +
 packages/kernel/src/rect.ts                   |  14 +-
 .../__tests__/snapshot-presentation.test.ts   |  27 +++
 scripts/check-affected/model.ts               |   4 +-
 scripts/ios-snapshot-differential.test.ts     | 108 +++++++++
 33 files changed, 837 insertions(+), 249 deletions(-)
 create mode 100644 apple/snapshot-presentation/Tests/AgentDeviceSnapshotPresentationTests/ActionabilityPolicyTests.swift
 create mode 100644 apple/snapshot-presentation/Tests/AgentDeviceSnapshotPresentationTests/FixtureRect.swift
 create mode 100644 contracts/fixtures/snapshot-actionability-policy.json

diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+AXSnapshotFallback.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+AXSnapshotFallback.swift
index 13244aeaf2..df933a24ab 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+AXSnapshotFallback.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+AXSnapshotFallback.swift
@@ -217,12 +217,11 @@ extension RunnerTests {
       }
 
       let rootFrame = privateAXRect(root["frame"])
-      let geometry = privateAXSnapshotGeometry(
+      let viewport = privateAXSnapshotViewport(
         app: app,
         bundleId: target.bundleId,
         rootFrame: rootFrame
       )
-      let viewport = geometry.viewport
       let nodes = privateAXAcquisition(
         rawRoot: root,
         hint: hint
@@ -259,8 +258,7 @@ extension RunnerTests {
         customActions: Self.privateAXCustomActionCoverage(
           response[RunnerAXSnapshotCustomActionsKey]
         ),
-        viewport: viewport,
-        interfaceOrientation: geometry.interfaceOrientation
+        viewport: viewport
       )
     #else
       return nil
@@ -275,37 +273,32 @@ extension RunnerTests {
     !hasAbandonedMainThreadWork() && !isSnapshotXCTestChannelPenalized(bundleId: bundleId)
   }
 
-  /// The geometry this tier may anchor a rotation on. The bridge's own root frame is one more
-  /// reported box rather than the app's frame, so a capture anchored on it reports no interface
-  /// orientation and normalizes nothing: rotated system surfaces then stay as reported, which the
-  /// consumers already treat as geometry they cannot measure (#2612).
-  private func privateAXSnapshotGeometry(
+  /// The app's reported viewport when XCTest can read it, else the bridge's own root frame declared
+  /// `.derived`, which cannot anchor a rotation: rotated system surfaces then stay as reported (#2612).
+  private func privateAXSnapshotViewport(
     app: XCUIApplication,
     bundleId: String?,
     rootFrame: CGRect
-  ) -> (viewport: CGRect, interfaceOrientation: Int) {
-    let fallback = rootFrame.isEmpty ? CGRect.infinite : rootFrame
+  ) -> SnapshotViewport {
+    let fallback = SnapshotViewport.derived(box: rootFrame)
     guard shouldReadPrivateAXViewportViaXCTest(bundleId: bundleId) else {
-      return (fallback, RunnerInterfaceOrientation.unknown)
+      return fallback
     }
     do {
-      let anchor = try runMainThreadWork(
+      let reported = try runMainThreadWork(
         "private_ax_viewport",
         timeout: 1,
         timeoutError: snapshotMainThreadTimeoutError("reading private AX viewport")
       ) {
-        (
-          viewport: self.safeSnapshotViewport(app: app),
-          interfaceOrientation: self.capturedInterfaceOrientation(app: app)
-        )
+        self.safeSnapshotViewport(app: app, readingOrientation: true)
       }
-      if anchor.viewport.isInfinite || anchor.viewport.isNull || anchor.viewport.isEmpty {
-        return (fallback, RunnerInterfaceOrientation.unknown)
+      if case .missing = reported {
+        return fallback
       }
-      return (anchor.viewport, anchor.interfaceOrientation)
+      return reported
     } catch {
       NSLog("AGENT_DEVICE_RUNNER_PRIVATE_AX_VIEWPORT_FALLBACK=%@", String(describing: error))
-      return (fallback, RunnerInterfaceOrientation.unknown)
+      return fallback
     }
   }
 
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Navigation.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Navigation.swift
index da185b037e..3ab477ff74 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Navigation.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Navigation.swift
@@ -1,3 +1,4 @@
+import AgentDeviceSnapshotPresentation
 import XCTest
 
 extension RunnerTests {
@@ -120,16 +121,9 @@ extension RunnerTests {
     return navigationBackKeywords.firstIndex { text.contains($0) }
   }
 
-  // isFinite/>0 alone don't reject CGRect.infinite — its origin (~-9e307) is finite.
-  static func isUsableNavigationFrame(_ frame: CGRect) -> Bool {
-    guard frame.width.isFinite, frame.height.isFinite, frame.width > 0, frame.height > 0 else {
-      return false
-    }
-    return !frame.isInfinite
-  }
-
   static func isTopNavigationControlFrame(_ candidate: CGRect, in window: CGRect) -> Bool {
-    guard isUsableNavigationFrame(candidate), isUsableNavigationFrame(window) else {
+    guard SnapshotGeometry.isPositiveFinite(candidate), SnapshotGeometry.isPositiveFinite(window)
+    else {
       return false
     }
     // Accept the compact navigation/search header band without matching deep content controls.
@@ -138,7 +132,7 @@ extension RunnerTests {
   }
 
   static func topLeadingNavigationFallbackPoint(in frame: CGRect) -> CGPoint? {
-    guard isUsableNavigationFrame(frame) else {
+    guard SnapshotGeometry.isPositiveFinite(frame) else {
       return nil
     }
     // Aim at the standard leading navigation slot, bounded for compact and tablet widths.
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Snapshot.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Snapshot.swift
index 3d469bf868..f87b5b0648 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Snapshot.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Snapshot.swift
@@ -21,9 +21,8 @@ extension RunnerTests {
   struct SnapshotTraversalContext {
     let queryRoot: XCUIElement
     let rootSnapshot: XCUIElementSnapshot
-    let viewport: CGRect
-    /** Which way the app's interface is turned from the device's native space (#2612). */
-    let interfaceOrientation: Int
+    /** Carries which way the app's interface is turned from the device's native space (#2612). */
+    let viewport: SnapshotViewport
     /**
      * The keyboard band this capture measured, published beside the tree so the daemon's tap guard
      * measures against the producer's own reading rather than a band it derives from these rects
@@ -278,8 +277,7 @@ extension RunnerTests {
       nodes: nodes,
       truncated: false,
       effectiveDepth: nil,
-      viewport: context.viewport,
-      interfaceOrientation: context.interfaceOrientation
+      viewport: context.viewport
     )
   }
 
@@ -435,8 +433,7 @@ extension RunnerTests {
       nodes: nodes,
       truncated: false,
       effectiveDepth: nil,
-      viewport: context.viewport,
-      interfaceOrientation: context.interfaceOrientation
+      viewport: context.viewport
     )
   }
 
@@ -455,14 +452,13 @@ extension RunnerTests {
           nodes: nodes,
           truncated: false,
           effectiveDepth: nil,
-          viewport: .infinite,
-          interfaceOrientation: RunnerInterfaceOrientation.unknown
+          viewport: .missing(reason: .notProvided)
         ),
         .completed
       )
     }
 
-    let viewport = safeSnapshotViewport(app: app)
+    let viewport = safeSnapshotViewport(app: app, readingOrientation: false)
     var seen = Set<String>()
     var candidates: [RawAXNode] = []
     let flatElements = flatInteractiveElements(app: app, deadline: deadline)
@@ -492,11 +488,9 @@ extension RunnerTests {
     }
 
     // The synthetic root doubles as the daemon's viewport (find.ts prefers on-screen matches
-    // inside nodes[0].rect): use the real screen viewport when capture produced a finite one,
-    // so off-screen candidates can never inflate the root and masquerade as on-screen.
-    let rootRect = viewport.isInfinite || viewport.isNull || viewport.isEmpty
-      ? interactiveRootFrame(for: candidates)
-      : viewport
+    // inside nodes[0].rect): use the real screen viewport when the capture resolved one, so
+    // off-screen candidates can never inflate the root and masquerade as on-screen.
+    let rootRect = viewport.rect ?? interactiveRootFrame(for: candidates)
     nodes[0] = interactiveRootNode(rect: rootRect)
     for candidate in candidates {
       nodes.append(
@@ -524,8 +518,7 @@ extension RunnerTests {
         nodes: nodes,
         truncated: outcome == .deadlineExhausted,
         effectiveDepth: nil,
-        viewport: viewport,
-        interfaceOrientation: RunnerInterfaceOrientation.unknown
+        viewport: viewport
       ),
       outcome
     )
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotAcquisition.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotAcquisition.swift
index 26572f56fa..7ebc82596f 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotAcquisition.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotAcquisition.swift
@@ -41,18 +41,13 @@ extension RunnerTests {
     // The viewport and the interface orientation are one hop: geometry that arrives in the device's
     // native space can only be placed relative to the app's own frame and rotation, and asking for
     // the pair twice would read them at two different moments of a rotation.
-    let geometry = try runMainThreadWork(
+    let viewport = try runMainThreadWork(
       "snapshot_viewport",
       timeout: min(1.0, max(0.1, captureDeadline.timeIntervalSinceNow)),
       timeoutError: snapshotMainThreadTimeoutError("preparing tree snapshot")
     ) {
-      (
-        viewport: self.safeSnapshotViewport(app: app),
-        interfaceOrientation: self.capturedInterfaceOrientation(app: app)
-      )
+      self.safeSnapshotViewport(app: app, readingOrientation: true)
     }
-    let viewport = geometry.viewport
-    let interfaceOrientation = geometry.interfaceOrientation
     let treeSliceBudget = treeCaptureSliceBudgetOverride ?? treeCaptureSliceBudget
     let slice = min(treeSliceBudget, max(0.5, captureDeadline.timeIntervalSinceNow))
     guard let rootSnapshot = try captureSnapshotRootBounded(app, sliceSeconds: slice) else {
@@ -70,7 +65,6 @@ extension RunnerTests {
       queryRoot: app,
       rootSnapshot: rootSnapshot,
       viewport: viewport,
-      interfaceOrientation: interfaceOrientation,
       keyboardBand: keyboardBand
     )
   }
@@ -140,8 +134,18 @@ extension RunnerTests {
     return nil
   }
 
-  func safeSnapshotViewport(app: XCUIApplication) -> CGRect {
-    safely("SNAPSHOT_VIEWPORT", CGRect.infinite) { snapshotViewport(app: app) }
+  /// The viewport as a declared fact; a read that raises is `.missing(reason: .notProvided)` (#2891).
+  /// `readingOrientation` reads the interface orientation in the same hop, for tiers whose frames can
+  /// arrive in the device's native space; without it the viewport cannot anchor a rotation.
+  func safeSnapshotViewport(app: XCUIApplication, readingOrientation: Bool) -> SnapshotViewport {
+    safely("SNAPSHOT_VIEWPORT", .missing(reason: .notProvided)) {
+      .reported(
+        box: snapshotAppFrame(app: app),
+        interfaceOrientation: readingOrientation
+          ? capturedInterfaceOrientation(app: app)
+          : RunnerInterfaceOrientation.unknown
+      )
+    }
   }
 
   private func describeSnapshotError(_ error: Error) -> String {
@@ -231,16 +235,12 @@ extension RunnerTests {
     return text.isEmpty ? nil : text
   }
 
-  private func snapshotViewport(app: XCUIApplication) -> CGRect {
+  private func snapshotAppFrame(app: XCUIApplication) -> CGRect {
 #if os(iOS)
-    let appFrame = onScreenWindowFrame(app: app)
+    return onScreenWindowFrame(app: app)
 #else
-    let appFrame = app.frame
+    return app.frame
 #endif
-    if !appFrame.isNull && !appFrame.isEmpty {
-      return appFrame
-    }
-    return .infinite
   }
 
   static func snapshotTraversalIdentity(
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotCapturePlan.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotCapturePlan.swift
index e7f3898652..f1547821ba 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotCapturePlan.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotCapturePlan.swift
@@ -513,8 +513,7 @@ extension RunnerTests {
     let normalizedAcquisition = acquisition.replacingNodes(
       SnapshotGeometrySpace.normalized(
         nodes: acquisition.nodes,
-        viewport: acquisition.viewport,
-        interfaceOrientation: acquisition.interfaceOrientation
+        viewport: acquisition.viewport
       )
     )
 
@@ -641,7 +640,7 @@ extension RunnerTests {
       guard Self.structuralOnlyNodeTypes.contains(node.type) else { return false }
       guard !isRootContainer else { return true }
 
-      let isFullScreenContainer = !node.hittable && rootRects.contains { rootRect in
+      let isFullScreenContainer = node.hittable != true && rootRects.contains { rootRect in
         rootRect.x == node.rect.x && rootRect.y == node.rect.y
           && rootRect.width == node.rect.width && rootRect.height == node.rect.height
       }
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+AXSnapshotFallbackTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+AXSnapshotFallbackTests.swift
index 82f6bec10b..4e4fd9ff44 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+AXSnapshotFallbackTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+AXSnapshotFallbackTests.swift
@@ -464,15 +464,14 @@ extension RunnerTests {
       interactiveOnly: true, customActions: false)
     let acquired = SnapshotGeometrySpace.normalized(
       nodes: privateAXAcquisition(rawRoot: tree, hint: hint),
-      viewport: viewport,
-      interfaceOrientation: RunnerInterfaceOrientation.portrait
+      viewport: .reported(box: viewport, interfaceOrientation: RunnerInterfaceOrientation.portrait)
     )
     // Acquisition serializes the drawer too; the shared fold is what hides it (#1797).
     XCTAssertTrue(acquired.compactMap(\.label).contains("Admin settings"))
 
     let capture = try SnapshotPresentation.presentRegular(
       SnapshotAcquisition(
-        hint: hint, nodes: acquired, truncated: false, effectiveDepth: nil, viewport: viewport),
+        hint: hint, nodes: acquired, truncated: false, effectiveDepth: nil, viewport: .reported(box: viewport)),
       options: PresentationOptions(interactiveOnly: true, depth: nil, scope: nil, raw: false),
       policy: .cursorProjected
     )
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+PrivateAXPresentationTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+PrivateAXPresentationTests.swift
index 23ee5db993..3dcd2908dd 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+PrivateAXPresentationTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+PrivateAXPresentationTests.swift
@@ -42,8 +42,11 @@ extension RunnerTests {
       interfaceOrientation: RunnerInterfaceOrientation.portrait)
     return try SnapshotPresentation.presentRegular(
       SnapshotAcquisition(
-        hint: hint, nodes: nodes, truncated: false, effectiveDepth: nil, viewport: viewport,
-        interfaceOrientation: RunnerInterfaceOrientation.portrait),
+        hint: hint, nodes: nodes, truncated: false, effectiveDepth: nil,
+        viewport: .reported(
+          box: viewport,
+          interfaceOrientation: RunnerInterfaceOrientation.portrait
+        )),
       options: PresentationOptions(
         interactiveOnly: interactiveOnly, depth: nil, scope: nil, raw: false),
       policy: .cursorProjected
@@ -59,8 +62,7 @@ extension RunnerTests {
   ) -> [RawAXNode] {
     SnapshotGeometrySpace.normalized(
       nodes: privateAXAcquisition(rawRoot: rawRoot, hint: hint),
-      viewport: viewport,
-      interfaceOrientation: interfaceOrientation
+      viewport: .reported(box: viewport, interfaceOrientation: interfaceOrientation)
     )
   }
 
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotCapturePlanOccupancyTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotCapturePlanOccupancyTests.swift
index edec6e8333..7f12cb87b6 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotCapturePlanOccupancyTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotCapturePlanOccupancyTests.swift
@@ -94,8 +94,7 @@ extension RunnerTests {
     XCTAssertFalse(app.frame.isEmpty)
     // The traversal context reads the viewport under a 1 s cap; a cold first read can overrun it
     // and abandon the wrong block, so pay it here, uncapped.
-    _ = safeSnapshotViewport(app: app)
-    _ = capturedInterfaceOrientation(app: app)
+    _ = safeSnapshotViewport(app: app, readingOrientation: true)
     currentApp = app
     currentBundleId = "com.callstack.agentdevice.runner.tree-capture-test"
     snapshotXCTestPenaltyWarmupExemption.isPending = true
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotCapturePlanTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotCapturePlanTests.swift
index a2c709eeb9..87d3ad061e 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotCapturePlanTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotCapturePlanTests.swift
@@ -282,7 +282,7 @@ extension RunnerTests {
         nodes: [],
         truncated: false,
         effectiveDepth: nil,
-        viewport: .infinite
+        viewport: .reported(box: CGRect(x: 0, y: 0, width: 402, height: 874))
       ),
       options: options
     )
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotHittabilityTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotHittabilityTests.swift
index 61e0024121..89828f62f7 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotHittabilityTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotHittabilityTests.swift
@@ -97,7 +97,7 @@ extension RunnerTests {
         nodes: nodes,
         truncated: false,
         effectiveDepth: nil,
-        viewport: CGRect(x: 0, y: 0, width: 100, height: 100)
+        viewport: .reported(box: CGRect(x: 0, y: 0, width: 100, height: 100))
       ),
       options: options
     )
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotPresentationConformanceTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotPresentationConformanceTests.swift
index 718eb5651f..2c16b49851 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotPresentationConformanceTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotPresentationConformanceTests.swift
@@ -97,7 +97,7 @@ extension RunnerTests {
         },
         truncated: false,
         effectiveDepth: nil,
-        viewport: fixture.viewport.cgRect
+        viewport: .reported(box: fixture.viewport.cgRect)
       )
       let options = PresentationOptions(
         interactiveOnly: false,
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotPresentationGeometryTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotPresentationGeometryTests.swift
index 087f00e510..db52ad5d2f 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotPresentationGeometryTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotPresentationGeometryTests.swift
@@ -6,7 +6,7 @@ extension RunnerTests {
   func testEffectiveGeometryIntersectsViewportAndAncestorClip() {
     let effective = SnapshotGeometry.effectiveFrame(
       reportedFrame: CGRect(x: 350, y: 80, width: 100, height: 100),
-      viewport: CGRect(x: 0, y: 0, width: 402, height: 874),
+      viewport: .reported(box: CGRect(x: 0, y: 0, width: 402, height: 874)),
       ancestorClip: CGRect(x: 300, y: 100, width: 80, height: 80)
     )
 
@@ -17,7 +17,7 @@ extension RunnerTests {
     let reported = CGRect(x: 500, y: 120, width: 100, height: 44)
     let effective = SnapshotGeometry.effectiveFrame(
       reportedFrame: reported,
-      viewport: CGRect(x: 0, y: 0, width: 402, height: 874),
+      viewport: .reported(box: CGRect(x: 0, y: 0, width: 402, height: 874)),
       ancestorClip: nil
     )
 
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotPresentationInvariantTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotPresentationInvariantTests.swift
index c0c739b86d..9aeea4f490 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotPresentationInvariantTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotPresentationInvariantTests.swift
@@ -97,7 +97,7 @@ extension RunnerTests {
       nodes: nodes,
       truncated: false,
       effectiveDepth: nil,
-      viewport: viewport
+      viewport: .reported(box: viewport)
     )
   }
 
@@ -147,7 +147,7 @@ extension RunnerTests {
       ],
       truncated: false,
       effectiveDepth: nil,
-      viewport: CGRect(x: 0, y: 0, width: 320, height: 240)
+      viewport: .reported(box: CGRect(x: 0, y: 0, width: 320, height: 240))
     )
 
     let options = PresentationOptions(
@@ -203,7 +203,7 @@ extension RunnerTests {
       ],
       truncated: false,
       effectiveDepth: nil,
-      viewport: CGRect(x: 0, y: 0, width: 320, height: 240)
+      viewport: .reported(box: CGRect(x: 0, y: 0, width: 320, height: 240))
     )
 
     let options = PresentationOptions(
@@ -254,7 +254,7 @@ extension RunnerTests {
           nodes: nodes,
           truncated: false,
           effectiveDepth: nil,
-          viewport: .infinite
+          viewport: .reported(box: CGRect(x: 0, y: 0, width: 100, height: 100))
         ),
         options: options
       ).nodes)
@@ -309,7 +309,7 @@ extension RunnerTests {
     XCTAssertThrowsError(
       try SnapshotPresentationInvariant.validateRegular(
         folded,
-        viewport: viewport,
+        viewport: .reported(box: viewport),
         policy: .cursorProjected
       )
     ) { error in
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotPresentationTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotPresentationTests.swift
index c103678186..855abbd25b 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotPresentationTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotPresentationTests.swift
@@ -40,7 +40,7 @@ extension RunnerTests {
           truncated: 0,
           blocked: false
         ),
-        viewport: .infinite
+        viewport: .reported(box: CGRect(x: 0, y: 0, width: 100, height: 100))
       ),
       options: PresentationOptions(
         interactiveOnly: true,
@@ -113,7 +113,7 @@ extension RunnerTests {
             projection: .regular, depth: nil, regularPresentedDepth: nil,
             interactiveOnly: false, customActions: false),
           nodes: acquired, truncated: false, effectiveDepth: nil,
-          viewport: CGRect(x: 0, y: 0, width: 1_000, height: 1_000)),
+          viewport: .reported(box: CGRect(x: 0, y: 0, width: 1_000, height: 1_000))),
         options: PresentationOptions(interactiveOnly: false, depth: nil, scope: nil, raw: false)
       ).nodes
     )
@@ -124,7 +124,7 @@ extension RunnerTests {
             projection: .regular, depth: nil, regularPresentedDepth: nil,
             interactiveOnly: true, customActions: false),
           nodes: acquired, truncated: false, effectiveDepth: nil,
-          viewport: CGRect(x: 0, y: 0, width: 1_000, height: 1_000)),
+          viewport: .reported(box: CGRect(x: 0, y: 0, width: 1_000, height: 1_000))),
         options: PresentationOptions(interactiveOnly: true, depth: nil, scope: nil, raw: false)
       ).nodes
     )
@@ -147,7 +147,8 @@ extension RunnerTests {
           hint: CaptureHint(
             projection: .raw, depth: nil, regularPresentedDepth: nil,
             interactiveOnly: false, customActions: false),
-          nodes: acquired, truncated: false, effectiveDepth: nil, viewport: .infinite),
+          nodes: acquired, truncated: false, effectiveDepth: nil,
+          viewport: .reported(box: CGRect(x: 0, y: 0, width: 1_000, height: 1_000)) ),
         options: PresentationOptions(interactiveOnly: true, depth: nil, scope: nil, raw: true)
       ).nodes
     )
@@ -176,7 +177,7 @@ extension RunnerTests {
       nodes: nodes,
       truncated: false,
       effectiveDepth: nil,
-      viewport: CGRect(x: 0, y: 0, width: 100, height: 100)
+      viewport: .reported(box: CGRect(x: 0, y: 0, width: 100, height: 100))
     )
 
     let presented = try SnapshotPresentation.presentRegular(
@@ -211,7 +212,7 @@ extension RunnerTests {
           nodes: acquired,
           truncated: false,
           effectiveDepth: nil,
-          viewport: viewport
+          viewport: .reported(box: viewport)
         ),
         options: regularOptions
       ).nodes
@@ -231,7 +232,7 @@ extension RunnerTests {
           nodes: acquired,
           truncated: false,
           effectiveDepth: nil,
-          viewport: .infinite
+          viewport: .reported(box: CGRect(x: 0, y: 0, width: 100, height: 100))
         ),
         options: rawOptions
       ).nodes
@@ -286,7 +287,7 @@ extension RunnerTests {
       ],
       truncated: false,
       effectiveDepth: nil,
-      viewport: CGRect(x: 0, y: 0, width: 1_000, height: 1_000)
+      viewport: .reported(box: CGRect(x: 0, y: 0, width: 1_000, height: 1_000))
     )
     let options = PresentationOptions(
       interactiveOnly: true,
@@ -313,7 +314,7 @@ extension RunnerTests {
           nodes: acquisition.nodes,
           truncated: false,
           effectiveDepth: nil,
-          viewport: .infinite
+          viewport: .reported(box: CGRect(x: 0, y: 0, width: 100, height: 100))
         ),
         options: PresentationOptions(
           interactiveOnly: true,
@@ -374,10 +375,11 @@ extension RunnerTests {
     let regularAcquisition = SnapshotAcquisition(
       hint: SnapshotPresentation.captureHint(for: regularRequest),
       nodes: nodes, truncated: false, effectiveDepth: nil,
-      viewport: CGRect(x: 0, y: 0, width: 100, height: 100))
+      viewport: .reported(box: CGRect(x: 0, y: 0, width: 100, height: 100)))
     let rawAcquisition = SnapshotAcquisition(
       hint: SnapshotPresentation.captureHint(for: rawRequest),
-      nodes: nodes, truncated: false, effectiveDepth: nil, viewport: .infinite)
+      nodes: nodes, truncated: false, effectiveDepth: nil,
+      viewport: .reported(box: CGRect(x: 0, y: 0, width: 100, height: 100)))
 
     let regularCaptureForRawRequest = try SnapshotPresentation.present(
       regularAcquisition, options: rawRequest)
@@ -470,7 +472,7 @@ extension RunnerTests {
           ],
           truncated: false,
           effectiveDepth: nil,
-          viewport: CGRect(x: 0, y: 0, width: 100, height: 100)
+          viewport: .reported(box: CGRect(x: 0, y: 0, width: 100, height: 100))
         ),
         options: options
       )
@@ -552,7 +554,7 @@ extension RunnerTests {
       nodes: nodes,
       truncated: false,
       effectiveDepth: nil,
-      viewport: viewport
+      viewport: .reported(box: viewport)
     )
     let presented = try XCTUnwrap(
       SnapshotPresentation.present(acquisition, options: options)?.nodes)
@@ -596,8 +598,10 @@ extension RunnerTests {
     ]
     let normalized = SnapshotGeometrySpace.normalized(
       nodes: acquired,
-      viewport: viewport,
-      interfaceOrientation: RunnerInterfaceOrientation.landscapeRight
+      viewport: .reported(
+        box: viewport,
+        interfaceOrientation: RunnerInterfaceOrientation.landscapeRight
+      )
     )
     let options = PresentationOptions(interactiveOnly: false, depth: 3, scope: nil, raw: false)
     let hint = SnapshotPresentation.captureHint(for: options)
@@ -608,7 +612,7 @@ extension RunnerTests {
           nodes: normalized,
           truncated: false,
           effectiveDepth: nil,
-          viewport: viewport
+          viewport: .reported(box: viewport)
         ),
         options: options
       )?.nodes
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotVisibilityFoldTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotVisibilityFoldTests.swift
index 2063c56f14..ee6c4400dd 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotVisibilityFoldTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotVisibilityFoldTests.swift
@@ -25,7 +25,11 @@ extension RunnerTests {
     policy: SnapshotVisibilityFold.Policy = .cursorProjected
   ) -> [SnapshotPresentationNode] {
     SnapshotVisibilityFold.fold(
-      nodes, viewport: viewport, interactiveOnly: interactiveOnly, policy: policy)
+      nodes,
+      viewport: .reported(box: viewport),
+      interactiveOnly: interactiveOnly,
+      policy: policy
+    )
   }
 
   func testRegularFoldClipsScrollOverflowReparentsAndBooksHints() {
diff --git a/apple/snapshot-presentation/Sources/AgentDeviceSnapshotPresentation/SnapshotCoordinateSpace.swift b/apple/snapshot-presentation/Sources/AgentDeviceSnapshotPresentation/SnapshotCoordinateSpace.swift
index 561861bc29..300b8c910e 100644
--- a/apple/snapshot-presentation/Sources/AgentDeviceSnapshotPresentation/SnapshotCoordinateSpace.swift
+++ b/apple/snapshot-presentation/Sources/AgentDeviceSnapshotPresentation/SnapshotCoordinateSpace.swift
@@ -105,7 +105,7 @@ public enum CoordinateSpaceRotation {
 
 public enum SnapshotGeometrySpace: Equatable {
   case appOrientation
-  case deviceNative(appFrame: CGRect, interfaceOrientation: Int)
+  case deviceNative(appFrame: SnapshotViewport.Box, interfaceOrientation: Int)
 
   public static let quarterTurnTolerance: Double = 1
 
@@ -116,22 +116,26 @@ public enum SnapshotGeometrySpace: Equatable {
     case .deviceNative(let appFrame, let interfaceOrientation):
       return CoordinateSpaceRotation.oriented(
         rect: reportedFrame,
-        in: appFrame,
+        in: appFrame.rect,
         interfaceOrientation: interfaceOrientation
       )
     }
   }
 
+  /// Only a `.reported` viewport carries an orientation, so only it can anchor a rotation.
   public static func space(
     reportedBySurfaceHost isSurfaceHost: Bool,
     reportedFrame: CGRect,
     inheritedFrom inherited: SnapshotGeometrySpace,
-    appFrame: CGRect,
-    interfaceOrientation: Int
+    viewport: SnapshotViewport
   ) -> SnapshotGeometrySpace {
     guard isSurfaceHost else { return inherited }
-    guard namesQuarterTurn(interfaceOrientation) else { return .appOrientation }
-    guard isQuarterTurned(reportedFrame, relativeTo: appFrame) else { return .appOrientation }
+    guard case .reported(let appFrame, let interfaceOrientation) = viewport,
+      namesQuarterTurn(interfaceOrientation),
+      isQuarterTurned(reportedFrame, relativeTo: appFrame.rect)
+    else {
+      return .appOrientation
+    }
     return .deviceNative(appFrame: appFrame, interfaceOrientation: interfaceOrientation)
   }
 
@@ -145,7 +149,7 @@ public enum SnapshotGeometrySpace: Equatable {
   }
 
   private static func isQuarterTurned(_ frame: CGRect, relativeTo appFrame: CGRect) -> Bool {
-    guard isPlottable(frame), isPlottable(appFrame),
+    guard SnapshotGeometry.isPositiveFinite(frame),
       abs(appFrame.width - appFrame.height) > quarterTurnTolerance
     else {
       return false
@@ -153,19 +157,12 @@ public enum SnapshotGeometrySpace: Equatable {
     return abs(frame.width - appFrame.height) <= quarterTurnTolerance
       && abs(frame.height - appFrame.width) <= quarterTurnTolerance
   }
-
-  private static func isPlottable(_ frame: CGRect) -> Bool {
-    frame.origin.x.isFinite && frame.origin.y.isFinite
-      && frame.width.isFinite && frame.height.isFinite
-      && frame.width > 0 && frame.height > 0
-  }
 }
 
 extension SnapshotGeometrySpace {
   public static func normalized(
     nodes: [RawAXNode],
-    viewport: CGRect,
-    interfaceOrientation: Int
+    viewport: SnapshotViewport
   ) -> [RawAXNode] {
     let carriers = SnapshotVisibilityFold.visibilityExemptCarrierTypes
     var spaces = [SnapshotGeometrySpace](repeating: .appOrientation, count: nodes.count)
@@ -180,16 +177,16 @@ extension SnapshotGeometrySpace {
         ),
         reportedFrame: node.rect.cgRect,
         inheritedFrom: parentIndex.map { spaces[$0] } ?? .appOrientation,
-        appFrame: viewport,
-        interfaceOrientation: interfaceOrientation
+        viewport: viewport
       )
       spaces[position] = nodeSpace
       let frame = nodeSpace.orientedFrame(of: node.rect.cgRect)
       result.append(
         node.replacing(
           rect: SnapshotRect(frame),
-          hittable: node.parentIndex != nil
-            && SnapshotGeometry.isGeometricallyActionable(
+          hittable: node.parentIndex == nil
+            ? false
+            : SnapshotGeometry.isGeometricallyActionable(
               enabled: node.enabled,
               frame: frame,
               viewport: viewport
diff --git a/apple/snapshot-presentation/Sources/AgentDeviceSnapshotPresentation/SnapshotGeometry.swift b/apple/snapshot-presentation/Sources/AgentDeviceSnapshotPresentation/SnapshotGeometry.swift
index ec8bc50863..d0db9a8e24 100644
--- a/apple/snapshot-presentation/Sources/AgentDeviceSnapshotPresentation/SnapshotGeometry.swift
+++ b/apple/snapshot-presentation/Sources/AgentDeviceSnapshotPresentation/SnapshotGeometry.swift
@@ -2,14 +2,23 @@ import Foundation
 import CoreGraphics
 
 public enum SnapshotGeometry {
+  /// Twin of `isPositiveFiniteRect` in `packages/kernel/src/rect.ts`. `CGRect.infinite` is built
+  /// from finite components, so it is refused by identity.
+  public static func isPositiveFinite(_ rect: CGRect) -> Bool {
+    !rect.isInfinite
+      && rect.origin.x.isFinite && rect.origin.y.isFinite
+      && rect.size.width.isFinite && rect.size.height.isFinite
+      && rect.size.width > 0 && rect.size.height > 0
+  }
+
   public static func effectiveFrame(
     reportedFrame: CGRect,
-    viewport: CGRect,
+    viewport: SnapshotViewport,
     ancestorClip: CGRect?
   ) -> CGRect {
     var frame = reportedFrame
-    if !viewport.isInfinite {
-      frame = clipped(frame, to: viewport)
+    if let box = viewport.rect {
+      frame = clipped(frame, to: box)
     }
     if let ancestorClip {
       frame = clipped(frame, to: ancestorClip)
@@ -34,15 +43,18 @@ public enum SnapshotGeometry {
     )
   }
 
+  /// The shared `hittable` predicate (#1933), twin of `isGeometricallyActionable` in
+  /// `packages/kernel/src/rect.ts`, with `CGRect.contains`'s half-open right and bottom edges.
+  /// `nil` when only containment is left to decide and the capture has no viewport box: the node's
+  /// `hittable` is then absent on the wire, as it is on the host bridge (#2891).
   public static func isGeometricallyActionable(
     enabled: Bool,
     frame: CGRect,
-    viewport: CGRect
-  ) -> Bool {
-    guard enabled, !frame.isNull, !frame.isEmpty else { return false }
-    if viewport.isInfinite { return true }
-    let center = CGPoint(x: frame.midX, y: frame.midY)
-    return viewport.contains(center)
+    viewport: SnapshotViewport
+  ) -> Bool? {
+    guard enabled, isPositiveFinite(frame) else { return false }
+    guard let box = viewport.rect else { return nil }
+    return box.contains(CGPoint(x: frame.midX, y: frame.midY))
   }
 
   private static func clipped(_ frame: CGRect, to clip: CGRect) -> CGRect {
diff --git a/apple/snapshot-presentation/Sources/AgentDeviceSnapshotPresentation/SnapshotModels.swift b/apple/snapshot-presentation/Sources/AgentDeviceSnapshotPresentation/SnapshotModels.swift
index 95a3cf39d7..d0421aab6d 100644
--- a/apple/snapshot-presentation/Sources/AgentDeviceSnapshotPresentation/SnapshotModels.swift
+++ b/apple/snapshot-presentation/Sources/AgentDeviceSnapshotPresentation/SnapshotModels.swift
@@ -38,7 +38,8 @@ public struct RawAXNode: Equatable {
   public let enabled: Bool
   public let focused: Bool?
   public let selected: Bool?
-  public var hittable: Bool
+  /// Geometric actionability; `nil` when the capture has no viewport box to decide it against.
+  public var hittable: Bool?
   public let depth: Int
   public let parentIndex: Int?
   public let hiddenContentAbove: Bool?
@@ -55,7 +56,7 @@ public struct RawAXNode: Equatable {
     enabled: Bool,
     focused: Bool?,
     selected: Bool?,
-    hittable: Bool,
+    hittable: Bool?,
     depth: Int,
     parentIndex: Int?,
     hiddenContentAbove: Bool?,
@@ -79,7 +80,7 @@ public struct RawAXNode: Equatable {
     self.actions = actions
   }
 
-  func replacing(rect: SnapshotRect, hittable: Bool) -> RawAXNode {
+  func replacing(rect: SnapshotRect, hittable: Bool?) -> RawAXNode {
     var updated = self
     updated.rect = rect
     updated.hittable = hittable
@@ -153,15 +154,65 @@ public struct PresentationOptions: Equatable {
   }
 }
 
+/// What a capture knows about the viewport hosting its tree: the three cases of the host's
+/// `IosViewportEvidence` (#2891). No rectangle stands for "unknown".
+public enum SnapshotViewport: Equatable {
+  /// A box `SnapshotGeometry.isPositiveFinite` accepted. Only the factories below construct one.
+  public struct Box: Equatable {
+    public let rect: CGRect
+
+    init(positiveFinite rect: CGRect) {
+      self.rect = rect
+    }
+  }
+
+  /// The platform's box for the app's surface, with the interface orientation read in the same hop.
+  /// Only this case can anchor a rotation (#2612).
+  case reported(Box, interfaceOrientation: Int)
+  /// A box the capture inferred from its own root element. It clips and contains, and carries no
+  /// orientation, so it cannot anchor a rotation.
+  case derived(Box)
+  case missing(reason: MissingReason)
+
+  public enum MissingReason: Equatable {
+    /// The read was skipped or raised.
+    case notProvided
+    /// The box read is one `SnapshotGeometry.isPositiveFinite` refuses.
+    case invalid
+  }
+
+  public var rect: CGRect? {
+    switch self {
+    case .reported(let box, _), .derived(let box):
+      return box.rect
+    case .missing:
+      return nil
+    }
+  }
+
+  public static func reported(
+    box: CGRect,
+    interfaceOrientation: Int = RunnerInterfaceOrientation.unknown
+  ) -> SnapshotViewport {
+    SnapshotGeometry.isPositiveFinite(box)
+      ? .reported(Box(positiveFinite: box), interfaceOrientation: interfaceOrientation)
+      : .missing(reason: .invalid)
+  }
+
+  public static func derived(box: CGRect) -> SnapshotViewport {
+    SnapshotGeometry.isPositiveFinite(box)
+      ? .derived(Box(positiveFinite: box))
+      : .missing(reason: .invalid)
+  }
+}
+
 public struct SnapshotAcquisition {
   public let hint: CaptureHint
   public var nodes: [RawAXNode]
   public let truncated: Bool
   public let effectiveDepth: Int?
   public var customActions: SnapshotCustomActionCoverage?
-  public let viewport: CGRect
-  /// The app's interface orientation, consumed by the one `normalized` pass; `unknown` turns nothing.
-  public let interfaceOrientation: Int
+  public let viewport: SnapshotViewport
 
   public init(
     hint: CaptureHint,
@@ -169,8 +220,7 @@ public struct SnapshotAcquisition {
     truncated: Bool,
     effectiveDepth: Int?,
     customActions: SnapshotCustomActionCoverage? = nil,
-    viewport: CGRect,
-    interfaceOrientation: Int = 0
+    viewport: SnapshotViewport
   ) {
     self.hint = hint
     self.nodes = nodes
@@ -178,7 +228,6 @@ public struct SnapshotAcquisition {
     self.effectiveDepth = effectiveDepth
     self.customActions = customActions
     self.viewport = viewport
-    self.interfaceOrientation = interfaceOrientation
   }
 
   public func replacingNodes(_ nodes: [RawAXNode]) -> SnapshotAcquisition {
@@ -226,7 +275,7 @@ public struct PresentedNode: Codable, Equatable {
   public let enabled: Bool
   public let focused: Bool?
   public let selected: Bool?
-  public let hittable: Bool
+  public let hittable: Bool?
   public let depth: Int
   public let parentIndex: Int?
   public let hiddenContentAbove: Bool?
diff --git a/apple/snapshot-presentation/Sources/AgentDeviceSnapshotPresentation/SnapshotPresentationInvariant.swift b/apple/snapshot-presentation/Sources/AgentDeviceSnapshotPresentation/SnapshotPresentationInvariant.swift
index 7ce2f25589..a28ba33b2c 100644
--- a/apple/snapshot-presentation/Sources/AgentDeviceSnapshotPresentation/SnapshotPresentationInvariant.swift
+++ b/apple/snapshot-presentation/Sources/AgentDeviceSnapshotPresentation/SnapshotPresentationInvariant.swift
@@ -1,6 +1,7 @@
 import Foundation
 import CoreGraphics
 
+/// With no viewport box the cumulative clip has no root, so containment has nothing to violate.
 public enum SnapshotPresentationInvariant {
   struct ValidationStats: Equatable {
     let parentClipLookups: Int
@@ -12,7 +13,7 @@ public enum SnapshotPresentationInvariant {
 
   public static func validateRegular(
     _ nodes: [SnapshotPresentationNode],
-    viewport: CGRect,
+    viewport: SnapshotViewport,
     policy: SnapshotVisibilityFold.Policy
   ) throws {
     _ = try validateRegularWithStats(nodes, viewport: viewport, policy: policy)
@@ -20,24 +21,25 @@ public enum SnapshotPresentationInvariant {
 
   static func validateRegularWithStats(
     _ nodes: [SnapshotPresentationNode],
-    viewport: CGRect,
+    viewport: SnapshotViewport,
     policy: SnapshotVisibilityFold.Policy
   ) throws -> ValidationStats {
     var parentClipLookups = 0
-    var clipIncludingNodeByIndex: [Int: CGRect] = [:]
+    var clipIncludingNodeByIndex: [Int: CGRect?] = [:]
     clipIncludingNodeByIndex.reserveCapacity(nodes.count)
+    let rootClip = viewport.rect
 
     for node in nodes {
-      let ancestorClip: CGRect
+      let ancestorClip: CGRect?
       if let parentIndex = node.raw.parentIndex {
         parentClipLookups += 1
-        ancestorClip = clipIncludingNodeByIndex[parentIndex] ?? viewport
+        ancestorClip = clipIncludingNodeByIndex[parentIndex] ?? rootClip
       } else {
-        ancestorClip = viewport
+        ancestorClip = rootClip
       }
 
       let frame = node.effectiveRect.cgRect
-      let clipIncludingNode: CGRect
+      let clipIncludingNode: CGRect?
       if policy == .cursorProjected,
         SnapshotVisibilityFold.scrollContainerTypeNames.contains(node.raw.type),
         !frame.isNull,
@@ -50,7 +52,7 @@ public enum SnapshotPresentationInvariant {
       clipIncludingNodeByIndex[node.raw.index] = clipIncludingNode
 
       guard !frame.isNull, !frame.isEmpty else {
-        if node.raw.hittable {
+        if node.raw.hittable == true {
           throw SnapshotPresentationFailure.regularDegenerateNodeIsActionable(
             index: node.raw.index,
             frame: node.effectiveRect
@@ -59,11 +61,11 @@ public enum SnapshotPresentationInvariant {
         continue
       }
 
-      guard contains(frame, in: ancestorClip) else {
+      if let clip = ancestorClip, !contains(frame, in: clip) {
         throw SnapshotPresentationFailure.regularNodeOutsideCumulativeClip(
           index: node.raw.index,
           frame: node.effectiveRect,
-          clip: SnapshotRect(ancestorClip)
+          clip: SnapshotRect(clip)
         )
       }
     }
diff --git a/apple/snapshot-presentation/Sources/AgentDeviceSnapshotPresentation/SnapshotVisibilityFold.swift b/apple/snapshot-presentation/Sources/AgentDeviceSnapshotPresentation/SnapshotVisibilityFold.swift
index afd0b479c4..9f9a4d3ea3 100644
--- a/apple/snapshot-presentation/Sources/AgentDeviceSnapshotPresentation/SnapshotVisibilityFold.swift
+++ b/apple/snapshot-presentation/Sources/AgentDeviceSnapshotPresentation/SnapshotVisibilityFold.swift
@@ -100,7 +100,7 @@ public enum SnapshotVisibilityFold {
   public static func traversalDecision(
     for node: RawAXNode,
     parent: TraversalState,
-    viewport: CGRect,
+    viewport: SnapshotViewport,
     interactiveOnly: Bool,
     hasChildren: Bool,
     policy: Policy
@@ -153,7 +153,7 @@ public enum SnapshotVisibilityFold {
 
   public static func fold(
     _ nodes: [RawAXNode],
-    viewport: CGRect,
+    viewport: SnapshotViewport,
     interactiveOnly: Bool,
     policy: Policy
   ) -> [SnapshotPresentationNode] {
@@ -203,12 +203,17 @@ public enum SnapshotVisibilityFold {
               enabled: node.enabled,
               focused: node.focused,
               selected: node.selected,
-              hittable: node.parentIndex != nil && node.hittable
-                && SnapshotGeometry.isGeometricallyActionable(
-                  enabled: node.enabled,
-                  frame: decision.effectiveFrame,
-                  viewport: viewport
-                ),
+              hittable: node.parentIndex == nil
+                ? false
+                : node.hittable.flatMap { sourceHittable in
+                  sourceHittable
+                    ? SnapshotGeometry.isGeometricallyActionable(
+                      enabled: node.enabled,
+                      frame: decision.effectiveFrame,
+                      viewport: viewport
+                    )
+                    : false
+                },
               depth: outDepth,
               parentIndex: keptIndex,
               hiddenContentAbove: node.hiddenContentAbove,
diff --git a/apple/snapshot-presentation/Sources/SnapshotPresentationConformance/main.swift b/apple/snapshot-presentation/Sources/SnapshotPresentationConformance/main.swift
index 89bd98c4a1..005386ba10 100644
--- a/apple/snapshot-presentation/Sources/SnapshotPresentationConformance/main.swift
+++ b/apple/snapshot-presentation/Sources/SnapshotPresentationConformance/main.swift
@@ -75,7 +75,8 @@ private func acquisition(for input: ConformanceInput) -> SnapshotAcquisition {
     },
     truncated: false,
     effectiveDepth: nil,
-    viewport: input.viewport.cgRect
+    // The host engine refuses to fold without a viewport, so the differential always reports one.
+    viewport: .reported(box: input.viewport.cgRect)
   )
 }
 
diff --git a/apple/snapshot-presentation/Tests/AgentDeviceSnapshotPresentationTests/ActionabilityPolicyTests.swift b/apple/snapshot-presentation/Tests/AgentDeviceSnapshotPresentationTests/ActionabilityPolicyTests.swift
new file mode 100644
index 0000000000..27882e1442
--- /dev/null
+++ b/apple/snapshot-presentation/Tests/AgentDeviceSnapshotPresentationTests/ActionabilityPolicyTests.swift
@@ -0,0 +1,118 @@
+import AgentDeviceSnapshotPresentation
+import CoreGraphics
+import Foundation
+import XCTest
+
+/// Replays `contracts/fixtures/snapshot-actionability-policy.json` against the Swift predicate. The
+/// TypeScript twin replays the same rows in `scripts/ios-snapshot-differential.test.ts`.
+final class ActionabilityPolicyTests: XCTestCase {
+  private struct Table: Decodable {
+    let cases: [PolicyCase]
+  }
+
+  private struct ViewportFact: Decodable {
+    private enum CodingKeys: String, CodingKey {
+      case kind, rect, reason
+    }
+
+    let declaredKind: String
+    let viewport: SnapshotViewport
+
+    /// A row whose box the factory refuses would silently test `missing` under another label.
+    var matchesDeclaredKind: Bool {
+      switch (declaredKind, viewport) {
+      case ("reported", .reported), ("derived", .derived), ("missing", .missing):
+        return true
+      default:
+        return false
+      }
+    }
+
+    init(from decoder: Decoder) throws {
+      let container = try decoder.container(keyedBy: CodingKeys.self)
+      let kind = try container.decode(String.self, forKey: .kind)
+      self.declaredKind = kind
+      switch kind {
+      case "reported":
+        self.viewport = .reported(box: try container.decode(FixtureRect.self, forKey: .rect).cgRect)
+      case "derived":
+        self.viewport = .derived(box: try container.decode(FixtureRect.self, forKey: .rect).cgRect)
+      case "missing":
+        switch try container.decode(String.self, forKey: .reason) {
+        case "not-provided":
+          self.viewport = .missing(reason: .notProvided)
+        case "invalid":
+          self.viewport = .missing(reason: .invalid)
+        default:
+          throw DecodingError.dataCorruptedError(
+            forKey: .reason,
+            in: container,
+            debugDescription: "unknown missing-viewport reason"
+          )
+        }
+      default:
+        throw DecodingError.dataCorruptedError(
+          forKey: .kind,
+          in: container,
+          debugDescription: "unknown viewport kind"
+        )
+      }
+    }
+  }
+
+  private struct PolicyCase: Decodable {
+    let name: String
+    let swift: Bool
+    let typescript: Bool
+    let asymmetry: String?
+    let enabled: Bool
+    let node: FixtureRect
+    let viewport: ViewportFact
+    /// `nil` is the absent bit.
+    let hittable: Bool?
+    let nodeRectGuardPasses: Bool
+
+    var declaresItsAsymmetry: Bool {
+      (swift && typescript) != (asymmetry?.isEmpty == false)
+    }
+  }
+
+  func testActionabilityPolicyAgreesWithEveryGoldenVector() throws {
+    let table = try JSONDecoder().decode(
+      Table.self,
+      from: Data(contentsOf: contractsFixtureURL("snapshot-actionability-policy.json"))
+    )
+    XCTAssertEqual(Set(table.cases.map(\.name)).count, table.cases.count, "names must be unique")
+    let swiftCases = table.cases.filter(\.swift)
+    XCTAssertEqual(
+      Set(swiftCases.map(\.viewport.declaredKind)),
+      ["reported", "derived", "missing"]
+    )
+    for testCase in table.cases {
+      XCTAssertTrue(
+        testCase.declaresItsAsymmetry,
+        "\(testCase.name): a row both languages do not share must name the asymmetry"
+      )
+    }
+    for testCase in swiftCases {
+      XCTAssertTrue(
+        testCase.viewport.matchesDeclaredKind,
+        "\(testCase.name): declared \(testCase.viewport.declaredKind) must survive declaration"
+      )
+      XCTAssertEqual(
+        SnapshotGeometry.isPositiveFinite(testCase.node.cgRect),
+        testCase.nodeRectGuardPasses,
+        "\(testCase.name): node-rect guard"
+      )
+      XCTAssertEqual(
+        SnapshotGeometry.isGeometricallyActionable(
+          enabled: testCase.enabled,
+          frame: testCase.node.cgRect,
+          viewport: testCase.viewport.viewport
+        ),
+        testCase.hittable,
+        testCase.name
+      )
+    }
+  }
+}
diff --git a/apple/snapshot-presentation/Tests/AgentDeviceSnapshotPresentationTests/ConformanceTests.swift b/apple/snapshot-presentation/Tests/AgentDeviceSnapshotPresentationTests/ConformanceTests.swift
index 2e526095bf..d99fdda405 100644
--- a/apple/snapshot-presentation/Tests/AgentDeviceSnapshotPresentationTests/ConformanceTests.swift
+++ b/apple/snapshot-presentation/Tests/AgentDeviceSnapshotPresentationTests/ConformanceTests.swift
@@ -49,7 +49,7 @@ final class ConformanceTests: XCTestCase {
         ],
         truncated: false,
         effectiveDepth: nil,
-        viewport: CGRect(x: 0, y: 0, width: 100, height: 100)
+        viewport: .reported(box: CGRect(x: 0, y: 0, width: 100, height: 100))
       ),
       options: options,
       policy: .cursorProjected
diff --git a/apple/snapshot-presentation/Tests/AgentDeviceSnapshotPresentationTests/CoordinateSpaceTests.swift b/apple/snapshot-presentation/Tests/AgentDeviceSnapshotPresentationTests/CoordinateSpaceTests.swift
index 90e67e938d..c5df2bc22c 100644
--- a/apple/snapshot-presentation/Tests/AgentDeviceSnapshotPresentationTests/CoordinateSpaceTests.swift
+++ b/apple/snapshot-presentation/Tests/AgentDeviceSnapshotPresentationTests/CoordinateSpaceTests.swift
@@ -7,30 +7,7 @@ import XCTest
 /// without a simulator, and the runner's walkers are tested separately for threading it through.
 final class CoordinateSpaceTests: XCTestCase {
   private struct WindowCoordinateSpaceFixture: Decodable {
-    /// A frame as JSON can carry one. Infinity has no JSON spelling, so the unusable box a platform
-    /// hands back is named `{"infinite": true}`: `CGRect.infinite` here, and an infinite rect in the
-    /// vitest twin.
-    struct Frame: Decodable {
-      private enum CodingKeys: String, CodingKey {
-        case x, y, width, height, infinite
-      }
-
-      let cgRect: CGRect
-
-      init(from decoder: Decoder) throws {
-        let container = try decoder.container(keyedBy: CodingKeys.self)
-        guard try container.decodeIfPresent(Bool.self, forKey: .infinite) != true else {
-          self.cgRect = .infinite
-          return
-        }
-        self.cgRect = CGRect(
-          x: try container.decode(Double.self, forKey: .x),
-          y: try container.decode(Double.self, forKey: .y),
-          width: try container.decode(Double.self, forKey: .width),
-          height: try container.decode(Double.self, forKey: .height)
-        )
-      }
-    }
+    typealias Frame = FixtureRect
 
     struct Constants: Decodable {
       let quarterTurnTolerance: Double
@@ -161,10 +138,9 @@ final class CoordinateSpaceTests: XCTestCase {
       reportedBySurfaceHost: true,
       reportedFrame: CGRect(x: 0, y: 0, width: 402, height: 874),
       inheritedFrom: .appOrientation,
-      appFrame: appFrame,
-      interfaceOrientation: landscape
+      viewport: .reported(box: appFrame, interfaceOrientation: landscape)
     )
-    XCTAssertEqual(space, .deviceNative(appFrame: appFrame, interfaceOrientation: landscape))
+    XCTAssertEqual(space, deviceNative(appFrame, landscape))
 
     // Reported on iPhone 17 Pro (iOS 26.2), landscape, system keyboard over the fixture's form.
     XCTAssertEqual(
@@ -198,8 +174,10 @@ final class CoordinateSpaceTests: XCTestCase {
       reportedBySurfaceHost: true,
       reportedFrame: rotated,
       inheritedFrom: .appOrientation,
-      appFrame: appFrame,
-      interfaceOrientation: RunnerInterfaceOrientation.landscapeRight
+      viewport: .reported(
+        box: appFrame,
+        interfaceOrientation: RunnerInterfaceOrientation.landscapeRight
+      )
     )
 
     // The app's own window reports the app's box, and so does a hosted surface that already
@@ -209,8 +187,10 @@ final class CoordinateSpaceTests: XCTestCase {
         reportedBySurfaceHost: true,
         reportedFrame: appFrame,
         inheritedFrom: nativeSpace,
-        appFrame: appFrame,
-        interfaceOrientation: RunnerInterfaceOrientation.landscapeRight
+        viewport: .reported(
+          box: appFrame,
+          interfaceOrientation: RunnerInterfaceOrientation.landscapeRight
+        )
       ),
       .appOrientation
     )
@@ -223,8 +203,10 @@ final class CoordinateSpaceTests: XCTestCase {
         ),
         reportedFrame: CGRect(x: 154, y: 77, width: 45, height: 72),
         inheritedFrom: nativeSpace,
-        appFrame: appFrame,
-        interfaceOrientation: RunnerInterfaceOrientation.landscapeRight
+        viewport: .reported(
+          box: appFrame,
+          interfaceOrientation: RunnerInterfaceOrientation.landscapeRight
+        )
       ),
       nativeSpace
     )
@@ -234,8 +216,7 @@ final class CoordinateSpaceTests: XCTestCase {
       reportedBySurfaceHost: true,
       reportedFrame: rotated,
       inheritedFrom: .appOrientation,
-      appFrame: appFrame,
-      interfaceOrientation: RunnerInterfaceOrientation.unknown
+      viewport: .reported(box: appFrame, interfaceOrientation: RunnerInterfaceOrientation.unknown)
     )
     XCTAssertEqual(unnamed, .appOrientation)
     XCTAssertEqual(
@@ -248,22 +229,26 @@ final class CoordinateSpaceTests: XCTestCase {
         reportedBySurfaceHost: true,
         reportedFrame: rotated,
         inheritedFrom: .appOrientation,
-        appFrame: CGRect(x: 16, y: 24, width: 874, height: 402),
-        interfaceOrientation: RunnerInterfaceOrientation.portrait
-      ),
-      .appOrientation
-    )
-    // An app frame the capture could not resolve cannot anchor a rotation.
-    XCTAssertEqual(
-      SnapshotGeometrySpace.space(
-        reportedBySurfaceHost: true,
-        reportedFrame: rotated,
-        inheritedFrom: .appOrientation,
-        appFrame: .infinite,
-        interfaceOrientation: RunnerInterfaceOrientation.landscapeRight
+        viewport: .reported(
+          box: CGRect(x: 16, y: 24, width: 874, height: 402),
+          interfaceOrientation: RunnerInterfaceOrientation.portrait
+        )
       ),
       .appOrientation
     )
+    // Only a reported viewport carries an orientation: no box, or a box the capture derived from
+    // its own root, cannot anchor a rotation (#2891).
+    for viewport in [SnapshotViewport.missing(reason: .notProvided), .derived(box: appFrame)] {
+      XCTAssertEqual(
+        SnapshotGeometrySpace.space(
+          reportedBySurfaceHost: true,
+          reportedFrame: rotated,
+          inheritedFrom: .appOrientation,
+          viewport: viewport
+        ),
+        .appOrientation
+      )
+    }
     // A square app cannot be told from its own quarter turn, so its geometry is left alone.
     let square = CGRect(x: 0, y: 0, width: 800, height: 800)
     XCTAssertEqual(
@@ -271,8 +256,10 @@ final class CoordinateSpaceTests: XCTestCase {
         reportedBySurfaceHost: true,
         reportedFrame: square,
         inheritedFrom: .appOrientation,
-        appFrame: square,
-        interfaceOrientation: RunnerInterfaceOrientation.landscapeRight
+        viewport: .reported(
+          box: square,
+          interfaceOrientation: RunnerInterfaceOrientation.landscapeRight
+        )
       ),
       .appOrientation
     )
@@ -293,18 +280,16 @@ final class CoordinateSpaceTests: XCTestCase {
       reportedBySurfaceHost: true,
       reportedFrame: appFrame,
       inheritedFrom: .appOrientation,
-      appFrame: appFrame,
-      interfaceOrientation: landscape
+      viewport: .reported(box: appFrame, interfaceOrientation: landscape)
     )
     XCTAssertEqual(windowSpace, .appOrientation)
     let surfaceSpace = SnapshotGeometrySpace.space(
       reportedBySurfaceHost: true,
       reportedFrame: turned,
       inheritedFrom: windowSpace,
-      appFrame: appFrame,
-      interfaceOrientation: landscape
+      viewport: .reported(box: appFrame, interfaceOrientation: landscape)
     )
-    XCTAssertEqual(surfaceSpace, .deviceNative(appFrame: appFrame, interfaceOrientation: landscape))
+    XCTAssertEqual(surfaceSpace, deviceNative(appFrame, landscape))
     // Deep in the tree a turned box is content reporting large bounds, not a hosted surface: it keeps
     // the space it inherited rather than rewriting the space below it.
     XCTAssertEqual(
@@ -312,8 +297,7 @@ final class CoordinateSpaceTests: XCTestCase {
         reportedBySurfaceHost: false,
         reportedFrame: turned,
         inheritedFrom: windowSpace,
-        appFrame: appFrame,
-        interfaceOrientation: landscape
+        viewport: .reported(box: appFrame, interfaceOrientation: landscape)
       ),
       .appOrientation
     )
@@ -340,15 +324,14 @@ final class CoordinateSpaceTests: XCTestCase {
         RunnerInterfaceOrientation.landscapeRight, RunnerInterfaceOrientation.landscapeLeft
       ] {
         let expected: SnapshotGeometrySpace = testCase.quarterTurned
-          ? .deviceNative(appFrame: appFrame, interfaceOrientation: interfaceOrientation)
+          ? deviceNative(appFrame, interfaceOrientation)
           : .appOrientation
         XCTAssertEqual(
           SnapshotGeometrySpace.space(
             reportedBySurfaceHost: true,
             reportedFrame: testCase.window.cgRect,
             inheritedFrom: .appOrientation,
-            appFrame: appFrame,
-            interfaceOrientation: interfaceOrientation
+            viewport: .reported(box: appFrame, interfaceOrientation: interfaceOrientation)
           ),
           expected,
           "\(testCase.name) (interfaceOrientation \(interfaceOrientation))"
@@ -368,16 +351,15 @@ final class CoordinateSpaceTests: XCTestCase {
     }
   }
 
+  private func deviceNative(_ appFrame: CGRect, _ interfaceOrientation: Int) -> SnapshotGeometrySpace {
+    guard case .reported(let box, _) = SnapshotViewport.reported(box: appFrame) else {
+      preconditionFailure("\(appFrame) is not a viewport box")
+    }
+    return .deviceNative(appFrame: box, interfaceOrientation: interfaceOrientation)
+  }
+
   private func loadWindowCoordinateSpaceFixture() throws -> WindowCoordinateSpaceFixture {
-    let fixtureURL = URL(fileURLWithPath: #filePath)
-      .deletingLastPathComponent() // AgentDeviceSnapshotPresentationTests
-      .deletingLastPathComponent() // Tests
-      .deletingLastPathComponent() // snapshot-presentation
-      .deletingLastPathComponent() // apple
-      .deletingLastPathComponent() // repo root
-      .appendingPathComponent("contracts")
-      .appendingPathComponent("fixtures")
-      .appendingPathComponent("window-coordinate-space.json")
+    let fixtureURL = contractsFixtureURL("window-coordinate-space.json")
     return try JSONDecoder().decode(
       WindowCoordinateSpaceFixture.self,
       from: Data(contentsOf: fixtureURL)
@@ -421,8 +403,7 @@ final class CoordinateSpaceTests: XCTestCase {
       let expected = (namesQuarterTurn && !squareApp) ? testCase.oriented : testCase.native
       let normalized = SnapshotGeometrySpace.normalized(
         nodes: turnedSubtree(app: app, reportedLeaf: testCase.native.cgRect),
-        viewport: app,
-        interfaceOrientation: testCase.interfaceOrientation
+        viewport: .reported(box: app, interfaceOrientation: testCase.interfaceOrientation)
       )
       XCTAssertEqual(normalized.count, 4)
       XCTAssertEqual(normalized[3].rect.cgRect, expected.cgRect, testCase.name)
@@ -443,8 +424,7 @@ final class CoordinateSpaceTests: XCTestCase {
     ]
     let normalized = SnapshotGeometrySpace.normalized(
       nodes: acquired,
-      viewport: app,
-      interfaceOrientation: RunnerInterfaceOrientation.landscapeRight
+      viewport: .reported(box: app, interfaceOrientation: RunnerInterfaceOrientation.landscapeRight)
     )
     XCTAssertEqual(
       normalized.first { $0.label == "planeBand" }?.rect,
@@ -470,8 +450,7 @@ final class CoordinateSpaceTests: XCTestCase {
     ]
     let normalized = SnapshotGeometrySpace.normalized(
       nodes: acquired,
-      viewport: app,
-      interfaceOrientation: RunnerInterfaceOrientation.unknown
+      viewport: .reported(box: app, interfaceOrientation: RunnerInterfaceOrientation.unknown)
     )
     XCTAssertEqual(normalized.map(\.rect), acquired.map(\.rect))
     XCTAssertEqual(normalized[1].hittable, true)
@@ -479,12 +458,42 @@ final class CoordinateSpaceTests: XCTestCase {
     XCTAssertEqual(normalized[0].hittable, false)
   }
 
+  /// Without a viewport box the pass turns nothing and cannot decide containment, so a child's
+  /// `hittable` is absent rather than declared; a disabled child is still declared `false` (#2891).
+  func testNormalizedWithoutAViewportLeavesContainmentUndecided() {
+    let app = CGRect(x: 0, y: 0, width: 874, height: 402)
+    let acquired = turnedSubtree(app: app, reportedLeaf: CGRect(x: 100, y: 100, width: 40, height: 20))
+    let normalized = SnapshotGeometrySpace.normalized(
+      nodes: acquired,
+      viewport: .missing(reason: .notProvided)
+    )
+    XCTAssertEqual(normalized.map(\.rect), acquired.map(\.rect))
+    XCTAssertEqual(normalized[0].hittable, false)
+    XCTAssertNil(normalized[3].hittable)
+
+    let disabled = RawAXNode(
+      index: 1, type: "Button", label: nil, identifier: nil, value: nil,
+      rect: SnapshotRect(x: 100, y: 100, width: 40, height: 20),
+      enabled: false, focused: nil, selected: nil, hittable: true,
+      depth: 1, parentIndex: 0, hiddenContentAbove: nil, hiddenContentBelow: nil
+    )
+    XCTAssertEqual(
+      SnapshotGeometrySpace.normalized(
+        nodes: [acquired[0], disabled],
+        viewport: .missing(reason: .notProvided)
+      )[1].hittable,
+      false
+    )
+  }
+
   func testNormalizedOfAnEmptyArrayIsEmpty() {
     XCTAssertEqual(
       SnapshotGeometrySpace.normalized(
         nodes: [],
-        viewport: CGRect(x: 0, y: 0, width: 874, height: 402),
-        interfaceOrientation: RunnerInterfaceOrientation.landscapeRight
+        viewport: .reported(
+          box: CGRect(x: 0, y: 0, width: 874, height: 402),
+          interfaceOrientation: RunnerInterfaceOrientation.landscapeRight
+        )
       ),
       []
     )
diff --git a/apple/snapshot-presentation/Tests/AgentDeviceSnapshotPresentationTests/FixtureRect.swift b/apple/snapshot-presentation/Tests/AgentDeviceSnapshotPresentationTests/FixtureRect.swift
new file mode 100644
index 0000000000..f3152d43b4
--- /dev/null
+++ b/apple/snapshot-presentation/Tests/AgentDeviceSnapshotPresentationTests/FixtureRect.swift
@@ -0,0 +1,41 @@
+import CoreGraphics
+import Foundation
+
+/// A rect as a `contracts/fixtures/` table spells it. JSON has no infinity, so the two unusable
+/// boxes are named: `{"infinite": true}` is `CGRect.infinite`, and `{"nonFinite": true}` is a
+/// box whose components are infinite.
+struct FixtureRect: Decodable {
+  private enum CodingKeys: String, CodingKey {
+    case x, y, width, height, infinite, nonFinite
+  }
+
+  let cgRect: CGRect
+
+  init(from decoder: Decoder) throws {
+    let container = try decoder.container(keyedBy: CodingKeys.self)
+    if try container.decodeIfPresent(Bool.self, forKey: .infinite) == true {
+      self.cgRect = .infinite
+    } else if try container.decodeIfPresent(Bool.self, forKey: .nonFinite) == true {
+      self.cgRect = CGRect(x: -.infinity, y: -.infinity, width: .infinity, height: .infinity)
+    } else {
+      self.cgRect = CGRect(
+        x: try container.decode(Double.self, forKey: .x),
+        y: try container.decode(Double.self, forKey: .y),
+        width: try container.decode(Double.self, forKey: .width),
+        height: try container.decode(Double.self, forKey: .height)
+      )
+    }
+  }
+}
+
+func contractsFixtureURL(_ name: String, from filePath: String = #filePath) -> URL {
+  URL(fileURLWithPath: filePath)
+    .deletingLastPathComponent() // AgentDeviceSnapshotPresentationTests
+    .deletingLastPathComponent() // Tests
+    .deletingLastPathComponent() // snapshot-presentation
+    .deletingLastPathComponent() // apple
+    .deletingLastPathComponent() // repo root
+    .appendingPathComponent("contracts")
+    .appendingPathComponent("fixtures")
+    .appendingPathComponent(name)
+}
diff --git a/apple/snapshot-presentation/Tests/AgentDeviceSnapshotPresentationTests/InvariantTests.swift b/apple/snapshot-presentation/Tests/AgentDeviceSnapshotPresentationTests/InvariantTests.swift
index 6b06f8c5a4..2a2eee8f48 100644
--- a/apple/snapshot-presentation/Tests/AgentDeviceSnapshotPresentationTests/InvariantTests.swift
+++ b/apple/snapshot-presentation/Tests/AgentDeviceSnapshotPresentationTests/InvariantTests.swift
@@ -28,7 +28,7 @@ final class InvariantTests: XCTestCase {
 
     let stats = try SnapshotPresentationInvariant.validateRegularWithStats(
       nodes,
-      viewport: viewport,
+      viewport: .reported(box: viewport),
       policy: .cursorProjected
     )
 
diff --git a/apple/snapshot-presentation/Tests/AgentDeviceSnapshotPresentationTests/RegularDepthTests.swift b/apple/snapshot-presentation/Tests/AgentDeviceSnapshotPresentationTests/RegularDepthTests.swift
index 6d7bc3f529..5589a9c304 100644
--- a/apple/snapshot-presentation/Tests/AgentDeviceSnapshotPresentationTests/RegularDepthTests.swift
+++ b/apple/snapshot-presentation/Tests/AgentDeviceSnapshotPresentationTests/RegularDepthTests.swift
@@ -21,7 +21,7 @@ final class RegularDepthTests: XCTestCase {
       nodes: nodes,
       truncated: false,
       effectiveDepth: nil,
-      viewport: viewport
+      viewport: .reported(box: viewport)
     )
 
     let result = try XCTUnwrap(SnapshotPresentation.present(acquisition, options: options))
diff --git a/contracts/fixtures/snapshot-actionability-policy.json b/contracts/fixtures/snapshot-actionability-policy.json
new file mode 100644
index 0000000000..5a567f6495
--- /dev/null
+++ b/contracts/fixtures/snapshot-actionability-policy.json
@@ -0,0 +1,220 @@
+{
+  "description": "Golden vector table for the shared `hittable` predicate (#1933, #2891), for input shapes the fixed 320x240 fold fixture in ios-snapshot-engine-conformance.json cannot reach. RULE: a node is actionable when it is enabled, its own rect is positive and finite, and its center falls inside the viewport box, half-open on the right and bottom edges. Implementations: SnapshotGeometry.isGeometricallyActionable (Swift, replayed by ActionabilityPolicyTests) and isGeometricallyActionable in packages/kernel/src/rect.ts (replayed by scripts/ios-snapshot-differential.test.ts). The viewport is the declared fact `reported`, `derived`, or `missing` (IosViewportEvidence). `hittable: null` is the absent bit: with no viewport box, containment is undecided. Every row declares `swift` and `typescript`; a row one side skips carries `asymmetry`.",
+  "cases": [
+    {
+      "name": "a center strictly inside the reported box is actionable",
+      "swift": true,
+      "typescript": true,
+      "enabled": true,
+      "node": { "x": 100, "y": 100, "width": 40, "height": 20 },
+      "viewport": { "kind": "reported", "rect": { "x": 0, "y": 0, "width": 320, "height": 240 } },
+      "hittable": true,
+      "nodeRectGuardPasses": true
+    },
+    {
+      "name": "a center one point short of the right edge is actionable",
+      "swift": true,
+      "typescript": true,
+      "enabled": true,
+      "node": { "x": 239, "y": 110, "width": 160, "height": 20 },
+      "viewport": { "kind": "reported", "rect": { "x": 0, "y": 0, "width": 320, "height": 240 } },
+      "hittable": true,
+      "nodeRectGuardPasses": true
+    },
+    {
+      "name": "a center landing exactly on the right edge is not actionable: the edge is half-open",
+      "swift": true,
+      "typescript": true,
+      "enabled": true,
+      "node": { "x": 240, "y": 110, "width": 160, "height": 20 },
+      "viewport": { "kind": "reported", "rect": { "x": 0, "y": 0, "width": 320, "height": 240 } },
+      "hittable": false,
+      "nodeRectGuardPasses": true
+    },
+    {
+      "name": "a center one point short of the bottom edge is actionable",
+      "swift": true,
+      "typescript": true,
+      "enabled": true,
+      "node": { "x": 100, "y": 159, "width": 40, "height": 160 },
+      "viewport": { "kind": "reported", "rect": { "x": 0, "y": 0, "width": 320, "height": 240 } },
+      "hittable": true,
+      "nodeRectGuardPasses": true
+    },
+    {
+      "name": "a center landing exactly on the bottom edge is not actionable: the edge is half-open",
+      "swift": true,
+      "typescript": true,
+      "enabled": true,
+      "node": { "x": 100, "y": 160, "width": 40, "height": 160 },
+      "viewport": { "kind": "reported", "rect": { "x": 0, "y": 0, "width": 320, "height": 240 } },
+      "hittable": false,
+      "nodeRectGuardPasses": true
+    },
+    {
+      "name": "a center landing exactly on the left edge is actionable: that edge is inclusive",
+      "swift": true,
+      "typescript": true,
+      "enabled": true,
+      "node": { "x": -20, "y": 100, "width": 40, "height": 20 },
+      "viewport": { "kind": "reported", "rect": { "x": 0, "y": 0, "width": 320, "height": 240 } },
+      "hittable": true,
+      "nodeRectGuardPasses": true
+    },
+    {
+      "name": "a center landing exactly on the top edge is actionable: that edge is inclusive",
+      "swift": true,
+      "typescript": true,
+      "enabled": true,
+      "node": { "x": 100, "y": -10, "width": 40, "height": 20 },
+      "viewport": { "kind": "reported", "rect": { "x": 0, "y": 0, "width": 320, "height": 240 } },
+      "hittable": true,
+      "nodeRectGuardPasses": true
+    },
+    {
+      "name": "a disabled node is not actionable even with its center inside the box",
+      "swift": true,
+      "typescript": true,
+      "enabled": false,
+      "node": { "x": 100, "y": 100, "width": 40, "height": 20 },
+      "viewport": { "kind": "reported", "rect": { "x": 0, "y": 0, "width": 320, "height": 240 } },
+      "hittable": false,
+      "nodeRectGuardPasses": true
+    },
+    {
+      "name": "a center inside the box reached through a canonical box is actionable",
+      "swift": true,
+      "typescript": true,
+      "enabled": true,
+      "node": { "x": 80, "y": 100, "width": 20, "height": 20 },
+      "viewport": { "kind": "reported", "rect": { "x": 0, "y": 0, "width": 320, "height": 240 } },
+      "hittable": true,
+      "nodeRectGuardPasses": true
+    },
+    {
+      "name": "the same center reached through a negative width is not actionable: the node guard decides, and Swift used to answer actionable",
+      "swift": true,
+      "typescript": true,
+      "enabled": true,
+      "node": { "x": 100, "y": 100, "width": -20, "height": 20 },
+      "viewport": { "kind": "reported", "rect": { "x": 0, "y": 0, "width": 320, "height": 240 } },
+      "hittable": false,
+      "nodeRectGuardPasses": false
+    },
+    {
+      "name": "a center inside the box reached through a zero width is not actionable",
+      "swift": true,
+      "typescript": true,
+      "enabled": true,
+      "node": { "x": 100, "y": 110, "width": 0, "height": 20 },
+      "viewport": { "kind": "reported", "rect": { "x": 0, "y": 0, "width": 320, "height": 240 } },
+      "hittable": false,
+      "nodeRectGuardPasses": false
+    },
+    {
+      "name": "that zero-area box's center reached through a canonical box is actionable",
+      "swift": true,
+      "typescript": true,
+      "enabled": true,
+      "node": { "x": 90, "y": 110, "width": 20, "height": 20 },
+      "viewport": { "kind": "reported", "rect": { "x": 0, "y": 0, "width": 320, "height": 240 } },
+      "hittable": true,
+      "nodeRectGuardPasses": true
+    },
+    {
+      "name": "Apple's no-box sentinel is not actionable: CGRect.infinite is made of finite Doubles whose center is (0,0), so only the platform that owns that value can refuse it by identity",
+      "swift": true,
+      "typescript": false,
+      "asymmetry": "Swift decodes {\"infinite\": true} as CGRect.infinite; TypeScript has no such value, and frameFromGuest in packages/platform-apple/src/snapshot-source/tree.ts refuses a frame whose components are not Number.isFinite before the predicate ever sees it, which is the row below. The sentinel's components are finite, so TypeScript would call them actionable: the refusal belongs to the producer that parses an Apple frame, not to a magic value inside the shared rule.",
+      "enabled": true,
+      "node": { "infinite": true },
+      "viewport": { "kind": "reported", "rect": { "x": 0, "y": 0, "width": 320, "height": 240 } },
+      "hittable": false,
+      "nodeRectGuardPasses": false
+    },
+    {
+      "name": "a node rect whose components are not finite is not actionable on either producer, and the component checks refuse it before any center is computed",
+      "swift": true,
+      "typescript": true,
+      "enabled": true,
+      "node": { "nonFinite": true },
+      "viewport": { "kind": "reported", "rect": { "x": 0, "y": 0, "width": 320, "height": 240 } },
+      "hittable": false,
+      "nodeRectGuardPasses": false
+    },
+    {
+      "name": "the center a box spelled infinite lands on is actionable when a real box reaches it",
+      "swift": true,
+      "typescript": true,
+      "enabled": true,
+      "node": { "x": -10, "y": -10, "width": 20, "height": 20 },
+      "viewport": { "kind": "reported", "rect": { "x": 0, "y": 0, "width": 320, "height": 240 } },
+      "hittable": true,
+      "nodeRectGuardPasses": true
+    },
+    {
+      "name": "the same node whose center sits inside a reported box has no hittable bit once the viewport goes missing",
+      "swift": true,
+      "typescript": false,
+      "asymmetry": "The TypeScript predicate takes a box. Without one, each host path withholds the bit before asking it: the bridge reader publishes derived hittability only for a reported viewport, and resolveViewportEvidence refuses to fold a regular presentation.",
+      "enabled": true,
+      "node": { "x": 100, "y": 100, "width": 40, "height": 20 },
+      "viewport": { "kind": "missing", "reason": "not-provided" },
+      "hittable": null,
+      "nodeRectGuardPasses": true
+    },
+    {
+      "name": "a viewport declared invalid leaves the bit absent the same way",
+      "swift": true,
+      "typescript": false,
+      "asymmetry": "The TypeScript predicate takes a box. Without one, each host path withholds the bit before asking it: the bridge reader publishes derived hittability only for a reported viewport, and resolveViewportEvidence refuses to fold a regular presentation.",
+      "enabled": true,
+      "node": { "x": 100, "y": 100, "width": 40, "height": 20 },
+      "viewport": { "kind": "missing", "reason": "invalid" },
+      "hittable": null,
+      "nodeRectGuardPasses": true
+    },
+    {
+      "name": "a disabled node is not actionable without a viewport: that half of the rule needs no box",
+      "swift": true,
+      "typescript": false,
+      "asymmetry": "The TypeScript predicate takes a box. Without one, each host path withholds the bit before asking it: the bridge reader publishes derived hittability only for a reported viewport, and resolveViewportEvidence refuses to fold a regular presentation.",
+      "enabled": false,
+      "node": { "x": 100, "y": 100, "width": 40, "height": 20 },
+      "viewport": { "kind": "missing", "reason": "not-provided" },
+      "hittable": false,
+      "nodeRectGuardPasses": true
+    },
+    {
+      "name": "a zero-area node is not actionable without a viewport: the node guard needs no box",
+      "swift": true,
+      "typescript": false,
+      "asymmetry": "The TypeScript predicate takes a box. Without one, each host path withholds the bit before asking it: the bridge reader publishes derived hittability only for a reported viewport, and resolveViewportEvidence refuses to fold a regular presentation.",
+      "enabled": true,
+      "node": { "x": 100, "y": 100, "width": 0, "height": 20 },
+      "viewport": { "kind": "missing", "reason": "not-provided" },
+      "hittable": false,
+      "nodeRectGuardPasses": false
+    },
+    {
+      "name": "a derived box the capture read from its own root still answers containment",
+      "swift": true,
+      "typescript": true,
+      "enabled": true,
+      "node": { "x": 100, "y": 100, "width": 40, "height": 20 },
+      "viewport": { "kind": "derived", "rect": { "x": 0, "y": 0, "width": 320, "height": 240 } },
+      "hittable": true,
+      "nodeRectGuardPasses": true
+    },
+    {
+      "name": "a derived box still refuses a node whose center is off that box",
+      "swift": true,
+      "typescript": true,
+      "enabled": true,
+      "node": { "x": 900, "y": 10, "width": 40, "height": 20 },
+      "viewport": { "kind": "derived", "rect": { "x": 0, "y": 0, "width": 320, "height": 240 } },
+      "hittable": false,
+      "nodeRectGuardPasses": true
+    }
+  ]
+}
diff --git a/docs/adr/0004-ios-snapshot-backend-strategy.md b/docs/adr/0004-ios-snapshot-backend-strategy.md
index dc46f6db6c..9610cc8bb9 100644
--- a/docs/adr/0004-ios-snapshot-backend-strategy.md
+++ b/docs/adr/0004-ios-snapshot-backend-strategy.md
@@ -304,6 +304,16 @@ a typed `IOS_SNAPSHOT_PRESENTATION_FAILED` capture failure with the named `prese
 snapshot-quality reason, preserved through recovery and the existing TypeScript verdict/warning
 contract.
 
+Inside the runner the viewport is a declared fact, not a rectangle: `SnapshotViewport` is
+`reported(box, interfaceOrientation)`, `derived(box)`, or `missing(reason)`, the cases of the host's
+`IosViewportEvidence` (#2891). Only `reported` carries an orientation, so only it can anchor a
+rotation in `SnapshotGeometrySpace`. With no box the clip skips, the cumulative-clip invariant has no
+root clip to violate, and a node whose actionability depends on containment has no `hittable` on the
+wire, as on the host bridge; disabled or degenerate nodes stay declared `false`. The runner route's
+host evidence comes from the payload's root nodes (`resolveIosViewportEvidenceFromRoots` in
+`packages/capture-kit/src/ios-snapshot-acquisition.ts`). `contracts/fixtures/snapshot-actionability-policy.json`
+pins the predicate for shapes the 320x240 fold fixture cannot reach.
+
 A regular `--depth` request is a presentation cut, not an acquisition bound. `CaptureHint` keeps raw
 traversal depth (`--raw --depth`) separate from regular presented depth, but the recursive tree walk
 no longer reads presented depth (or any geometry) while descending: for a regular capture it
diff --git a/packages/kernel/src/rect.ts b/packages/kernel/src/rect.ts
index fe25acfe7d..a6ebb19bc5 100644
--- a/packages/kernel/src/rect.ts
+++ b/packages/kernel/src/rect.ts
@@ -1,5 +1,6 @@
 import type { Rect } from './snapshot.ts';
 
+/** Twin of `SnapshotGeometry.isPositiveFinite` on the runner (#2891). */
 export function isPositiveFiniteRect(rect: Rect | undefined): rect is Rect {
   return Boolean(
     rect &&
@@ -29,13 +30,12 @@ export function containsPoint(rect: Rect, x: number, y: number): boolean {
 
 /**
  * The shared `hittable` predicate every iOS snapshot producer publishes (#1933): an enabled node
- * with a positive frame whose center falls inside the viewport. It is the TypeScript twin of the
- * runner's Swift `SnapshotGeometry.isGeometricallyActionable`, including `CGRect.contains`'s
- * half-open right/bottom edges — a center landing exactly on the viewport's right or bottom edge is
- * not hittable on either producer. The host AX bridge derives the source bit from the node's own
- * frame and the fold intersects it with the clipped frame, so a `hittable:` selector cannot tell the
- * two producers apart. Kept here so both packages read one definition rather than each re-encoding
- * the rule.
+ * with a positive finite frame whose center falls inside the viewport. It is the TypeScript twin of
+ * the runner's Swift `SnapshotGeometry.isGeometricallyActionable`, including `CGRect.contains`'s
+ * half-open right/bottom edges; `contracts/fixtures/snapshot-actionability-policy.json` pins both.
+ * Callers without a viewport box withhold the bit instead of asking. The host AX bridge derives the
+ * source bit from the node's own frame and the fold intersects it with the clipped frame, so a
+ * `hittable:` selector cannot tell the two producers apart.
  */
 export function isGeometricallyActionable(
   enabled: boolean,
diff --git a/packages/platform-apple/src/runner/__tests__/snapshot-presentation.test.ts b/packages/platform-apple/src/runner/__tests__/snapshot-presentation.test.ts
index a21f130552..917efddbd9 100644
--- a/packages/platform-apple/src/runner/__tests__/snapshot-presentation.test.ts
+++ b/packages/platform-apple/src/runner/__tests__/snapshot-presentation.test.ts
@@ -207,6 +207,33 @@ test('a healthy payload with valid viewport roots still presents', () => {
   );
 });
 
+// A runner capture with no viewport box omits `hittable` on the nodes it could not decide (#2891);
+// the host presents them undecided rather than minting a value.
+test('a runner payload with the hittable bit absent presents without declaring it', () => {
+  const nodes: RawSnapshotNode[] = [
+    {
+      index: 0,
+      type: 'Application',
+      rect: { x: 0, y: 0, width: 390, height: 844 },
+      hittable: false,
+    },
+    { index: 1, parentIndex: 0, type: 'Other', rect: { x: 0, y: 0, width: 390, height: 844 } },
+    {
+      index: 2,
+      parentIndex: 1,
+      type: 'Button',
+      label: 'Not Now',
+      rect: { x: 16, y: 400, width: 80, height: 32 },
+    },
+  ];
+  for (const interactiveOnly of [false, true]) {
+    const presented = presentAppleRunnerSnapshot('device-1', { interactiveOnly }, { nodes });
+    const button = presented.find((node) => node.label === 'Not Now');
+    assert.ok(button, `interactiveOnly=${interactiveOnly}: the undecided button is presented`);
+    assert.equal('hittable' in button, false);
+  }
+});
+
 // The keyboard band the runner measured for a capture (#2660). The reader is the only place a wire
 // fact becomes a daemon fact, so it owns the whole strictness budget: what cannot be placed is
 // restated as `unmeasurable` with a reason, never as a band and never as silence.
diff --git a/scripts/check-affected/model.ts b/scripts/check-affected/model.ts
index d21e10de21..259e53fb68 100644
--- a/scripts/check-affected/model.ts
+++ b/scripts/check-affected/model.ts
@@ -453,7 +453,9 @@ const BUILD_OWNERSHIP: ReadonlyArray<{
     owns: (file) =>
       file.startsWith('packages/capture-kit/src/ios-snapshot-engine/') ||
       file.startsWith('apple/snapshot-presentation/') ||
-      file === 'contracts/fixtures/ios-snapshot-engine-conformance.json',
+      file === 'packages/kernel/src/rect.ts' ||
+      file === 'contracts/fixtures/ios-snapshot-engine-conformance.json' ||
+      file === 'contracts/fixtures/snapshot-actionability-policy.json',
   },
   // Both platform builds compile the same runner sources, and each is a separate
   // gate in a separate lane, so a Swift change owns both.
diff --git a/scripts/ios-snapshot-differential.test.ts b/scripts/ios-snapshot-differential.test.ts
index a8c8d30414..60f3fdf8bc 100644
--- a/scripts/ios-snapshot-differential.test.ts
+++ b/scripts/ios-snapshot-differential.test.ts
@@ -1,6 +1,10 @@
 import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
 import { test } from 'node:test';
 import fc from 'fast-check';
+import { isGeometricallyActionable, isPositiveFiniteRect } from '@agent-device/kernel/rect';
+import type { Rect } from '@agent-device/kernel/snapshot';
 import {
   compareDifferentialCases,
   swiftToolchainAvailable,
@@ -124,3 +128,107 @@ function assertWithinKillCriterion(startedAt: number, seed: number): void {
       String(seed),
   );
 }
+
+type ActionabilityRect = Readonly<{ x: number; y: number; width: number; height: number }>;
+type ActionabilityUnusableRect = Readonly<{ infinite: true }> | Readonly<{ nonFinite: true }>;
+type ActionabilityViewport =
+  | Readonly<{ kind: 'reported' | 'derived'; rect: ActionabilityRect }>
+  | Readonly<{ kind: 'missing'; reason: 'not-provided' | 'invalid' }>;
+type ActionabilityVector = Readonly<{
+  name: string;
+  swift: boolean;
+  typescript: boolean;
+  asymmetry?: string;
+  enabled: boolean;
+  node: ActionabilityRect | ActionabilityUnusableRect;
+  viewport: ActionabilityViewport;
+  /** `null` is the absent bit. */
+  hittable: boolean | null;
+  nodeRectGuardPasses: boolean;
+}>;
+
+const ACTIONABILITY_POLICY_PATH = path.resolve(
+  import.meta.dirname,
+  '..',
+  'contracts',
+  'fixtures',
+  'snapshot-actionability-policy.json',
+);
+
+/** A box whose components are not numbers anything may plot. JSON has no literal for infinity. */
+const NON_FINITE_RECT: Rect = {
+  x: Number.NEGATIVE_INFINITY,
+  y: Number.NEGATIVE_INFINITY,
+  width: Number.POSITIVE_INFINITY,
+  height: Number.POSITIVE_INFINITY,
+};
+
+function declaresItsAsymmetry(vector: ActionabilityVector): boolean {
+  const hasReason = typeof vector.asymmetry === 'string' && vector.asymmetry.length > 0;
+  return (vector.swift && vector.typescript) !== hasReason;
+}
+
+function readActionabilityVectors(): readonly ActionabilityVector[] {
+  const table = JSON.parse(fs.readFileSync(ACTIONABILITY_POLICY_PATH, 'utf8')) as {
+    cases: readonly ActionabilityVector[];
+  };
+  assert.ok(table.cases.length > 0, 'actionability vector table must not be empty');
+  assert.equal(
+    new Set(table.cases.map((vector) => vector.name)).size,
+    table.cases.length,
+    'actionability vector names must be unique',
+  );
+  for (const vector of table.cases) {
+    assert.equal(typeof vector.swift, 'boolean', `${vector.name}: row must declare the Swift side`);
+    assert.equal(
+      typeof vector.typescript,
+      'boolean',
+      `${vector.name}: row must declare the TypeScript side`,
+    );
+    assert.ok(
+      declaresItsAsymmetry(vector),
+      `${vector.name}: a row both languages do not share must name the asymmetry`,
+    );
+  }
+  return table.cases;
+}
+
+function toRect(node: ActionabilityVector['node']): Rect {
+  if ('nonFinite' in node) return NON_FINITE_RECT;
+  if ('infinite' in node) {
+    throw new Error(
+      "CGRect.infinite is Apple's value and no row reaching TypeScript may stand for it: " +
+        'that row belongs to the Swift side alone',
+    );
+  }
+  return node;
+}
+
+// The Swift twin of these rows is ActionabilityPolicyTests, run by `swift test --package-path
+// apple/snapshot-presentation` in this same command.
+test('the shared hittable predicate agrees with every golden actionability vector', () => {
+  for (const vector of readActionabilityVectors().filter((row) => row.typescript)) {
+    const node = toRect(vector.node);
+    assert.equal(
+      isPositiveFiniteRect(node),
+      vector.nodeRectGuardPasses,
+      `${vector.name}: node-rect guard`,
+    );
+    if (vector.viewport.kind === 'missing') {
+      throw new Error(`${vector.name}: the TypeScript predicate takes a box`);
+    }
+    assert.equal(
+      isGeometricallyActionable(vector.enabled, node, vector.viewport.rect),
+      vector.hittable,
+      vector.name,
+    );
+  }
+});
+
+test('the TypeScript rows cover every viewport kind that carries a box', () => {
+  const vectors = readActionabilityVectors().filter((row) => row.typescript);
+  assert.deepEqual([...new Set(vectors.map((vector) => vector.viewport.kind))].sort(), [
+    'derived',
+    'reported',
+  ]);
+});

From cdfbad61836902ad04c3276ec8cf8e461a384ae5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 24 Sep 2026 18:46:04 +0200
Subject: [PATCH 106/132] refactor(ios): brand the simctl builders and require
 the brand where runXcrun runs simctl (#2917)

* refactor(platform-apple): brand the simctl command that runXcrun runs

buildSimctlArgsForAddress and buildSimctlArgsForDevice now return a
ScopedSimctlCommand, minted in core/tool-provider.ts from set-scoped
arguments. runXcrun takes that command or an argv whose tool is a named
non-simctl tool (devicectl, xcdevice, xctrace), so a literal, const-held,
string-typed or copied simctl argv is a type error. The simctl branch
unwraps the command to its scoped arguments; the ScopedSimctlArgs double
cast is gone.

The Apple tool host hands a simctl request's scoped args straight to the
simctl provider. The set-scope primitive is private to core/simctl.ts;
doctor and inventory use the named mints simctlAvailabilityProbeArgs and
simctlListDevicesArgs. Every argv stays byte-identical.

Refs #2878

* chore(gates): narrow R79 to the simctl bypasses tsc cannot reject

Drop the '--set' literal ban, the global ArrayExpression clause, the
set-scope identifier check and the tool-provider argv exemption. R79 now
checks the argv at an xcrun invocation (a call with an 'xcrun' argument
or an executable: 'xcrun' spec), which must name its tool as a literal
other than simctl, and refuses casts to the scope brands outside the two
modules that mint them.

Refs #2878

* chore(gates): refuse a simctl argv array outside the brand mints however it reaches an executor

runCmd, runCmdBackground and an executable: 'xcrun' spec take any string
argv, so the runXcrun brand does not reach them. R79 again flags every
array whose first element names simctl (literal, quasi-only template, or
a same-file binding of either) outside core/simctl.ts and
core/tool-provider.ts, so a variable-held, aliased or spread simctl argv
fails the gate as the inline form does.

* refactor(platform-apple): run every simctl executor through one argv form

* chore(gates): refuse a simctl tool named after leading xcrun options
---
 .../src/core/__tests__/simctl.test.ts         |  24 ++-
 .../__tests__/simulator-booted-memo.test.ts   |   3 +-
 .../src/core/__tests__/tool-provider.test.ts  |  80 +++++++-
 .../platform-apple/src/core/app-launch.ts     |   4 +-
 packages/platform-apple/src/core/devicectl.ts |   8 +-
 .../platform-apple/src/core/hinge-angle.ts    |   2 +-
 .../platform-apple/src/core/perf-target.ts    |  27 +--
 .../platform-apple/src/core/perf-xctrace.ts   |   4 +-
 .../src/core/physical-device-control.ts       |   8 +-
 .../src/core/settings-parsing.ts              |   2 +-
 packages/platform-apple/src/core/simctl.ts    |  41 ++--
 .../platform-apple/src/core/tool-provider.ts  |  42 +++-
 .../platform-apple/src/logs/doctor.test.ts    |   9 +-
 packages/platform-apple/src/logs/doctor.ts    |   4 +-
 .../platform-apple/src/logs/log-predicate.ts  |   3 +-
 packages/platform-apple/src/simctl-facade.ts  |   3 +-
 .../src/simulator-inventory.test.ts           |   7 +-
 .../platform-apple/src/simulator-inventory.ts |   9 +-
 .../apple-simulator-scope-policy.test.ts      | 159 ++++++++-------
 .../layering/apple-simulator-scope-policy.ts  | 193 +++++++++++-------
 scripts/layering/check.ts                     |   8 +-
 .../request-platform-providers.test.ts        |  11 +-
 src/platform-runtime-apple-tool-host.test.ts  |  21 ++
 src/platform-runtime-apple-tool-host.ts       |  11 +-
 src/platform-runtime-device-inventory.test.ts |   5 +-
 25 files changed, 428 insertions(+), 260 deletions(-)

diff --git a/packages/platform-apple/src/core/__tests__/simctl.test.ts b/packages/platform-apple/src/core/__tests__/simctl.test.ts
index d24f1ce197..294e1120f4 100644
--- a/packages/platform-apple/src/core/__tests__/simctl.test.ts
+++ b/packages/platform-apple/src/core/__tests__/simctl.test.ts
@@ -5,8 +5,9 @@ import {
   buildSimctlArgsForDevice,
   readSimctlDevicesByRuntime,
   readSimctlDeviceState,
-  scopeSimctlArgs,
   scopeSimctlArgsForDevice,
+  simctlAvailabilityProbeArgs,
+  simctlListDevicesArgs,
   simulatorAddressFor,
   type SimulatorAddress,
 } from '../simctl.ts';
@@ -59,19 +60,20 @@ test('buildSimctlArgsForDevice leaves non-simulator commands unchanged', () => {
   assert.deepEqual(args, ['simctl', 'bootstatus', 'sim-1', '-b']);
 });
 
-test('scopeSimctlArgs prefixes a trimmed simulator set and omits a blank one', () => {
-  assert.deepEqual(scopeSimctlArgs(['list', 'devices', '-j'], { simulatorSetPath: ' /tmp/set ' }), [
+test('simctlListDevicesArgs prefixes a trimmed simulator set and omits a blank one', () => {
+  assert.deepEqual(simctlListDevicesArgs(' /tmp/set '), [
     '--set',
     '/tmp/set',
     'list',
     'devices',
     '-j',
   ]);
-  assert.deepEqual(scopeSimctlArgs(['list', 'devices', '-j'], { simulatorSetPath: '  ' }), [
-    'list',
-    'devices',
-    '-j',
-  ]);
+  assert.deepEqual(simctlListDevicesArgs('  '), ['list', 'devices', '-j']);
+  assert.deepEqual(simctlListDevicesArgs(undefined), ['list', 'devices', '-j']);
+});
+
+test('simctlAvailabilityProbeArgs names no set', () => {
+  assert.deepEqual(simctlAvailabilityProbeArgs(), ['help']);
 });
 
 test('scopeSimctlArgsForDevice scopes simulators only', () => {
@@ -105,11 +107,13 @@ test('simulatorAddressFor carries the set of iOS-family simulators only', () =>
 });
 
 function compileTimeSimulatorScopeProof(): void {
-  // @ts-expect-error A set-scope call states its set; leaving it out does not mean the default set.
-  void scopeSimctlArgs(['list']);
   // @ts-expect-error A simulator address is minted from its DeviceInfo, never written by hand.
   const forged: SimulatorAddress = { udid: 'sim-1', simulatorSetPath: undefined };
   void forged;
+  // @ts-expect-error Set scope is private; a call that names no device goes through a named mint.
+  type SetScope = (typeof import('../simctl.ts'))['scopeSimctlArgs'];
+  const setScope: SetScope | undefined = undefined;
+  void setScope;
 }
 void compileTimeSimulatorScopeProof;
 
diff --git a/packages/platform-apple/src/core/__tests__/simulator-booted-memo.test.ts b/packages/platform-apple/src/core/__tests__/simulator-booted-memo.test.ts
index 7e1afe7671..541f30b9eb 100644
--- a/packages/platform-apple/src/core/__tests__/simulator-booted-memo.test.ts
+++ b/packages/platform-apple/src/core/__tests__/simulator-booted-memo.test.ts
@@ -9,7 +9,8 @@ import {
 } from '../simulator.ts';
 import { runXcrun } from '../tool-provider.ts';
 
-vi.mock('../tool-provider.ts', () => ({
+vi.mock('../tool-provider.ts', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('../tool-provider.ts')>()),
   runAppleToolCommand: vi.fn(async () => ({ stdout: '', stderr: '', exitCode: 0 })),
   runXcrun: vi.fn(),
 }));
diff --git a/packages/platform-apple/src/core/__tests__/tool-provider.test.ts b/packages/platform-apple/src/core/__tests__/tool-provider.test.ts
index 43584b19f9..88cc233ad1 100644
--- a/packages/platform-apple/src/core/__tests__/tool-provider.test.ts
+++ b/packages/platform-apple/src/core/__tests__/tool-provider.test.ts
@@ -6,12 +6,49 @@ import {
   resolveAppleToolProvider,
   runAppleToolCommand,
   runXcrun,
+  simctlCommand,
   withAppleToolProvider,
+  type ScopedSimctlCommand,
 } from '../tool-provider.ts';
-
-function compileTimeScopedSimctlProof(): void {
+import { buildSimctlArgsForDevice, scopeSimctlArgsForDevice } from '../simctl.ts';
+import type { AppleToolRequest } from '@agent-device/contracts/platform-runtime-host';
+import type { DeviceInfo } from '@agent-device/kernel/device';
+
+const IOS_SIMULATOR: DeviceInfo = {
+  platform: 'apple',
+  id: 'sim-1',
+  name: 'iPhone 17',
+  kind: 'simulator',
+  target: 'mobile',
+};
+const LAUNCH_COMMAND = buildSimctlArgsForDevice(IOS_SIMULATOR, [
+  'launch',
+  'sim-1',
+  'com.example.app',
+]);
+
+function compileTimeScopedSimctlProof(request: AppleToolRequest, argv: string[]): void {
   // @ts-expect-error Raw simctl argv cannot reach the provider; scope it in core/simctl.ts.
   void resolveAppleToolProvider().simctl.run(['spawn', 'sim-1', 'bridge']);
+  // @ts-expect-error A literal simctl argv is not a ScopedSimctlCommand.
+  void runXcrun(['simctl', 'spawn', 'sim-1', 'bridge']);
+  const tool = 'simctl';
+  // @ts-expect-error A tool name held in a const keeps its literal type, so it is refused too.
+  void runXcrun([tool, 'spawn', 'sim-1', 'bridge']);
+  const widenedTool: string = 'simctl';
+  // @ts-expect-error runXcrun names every other tool it runs, so a string tool name is refused.
+  void runXcrun([widenedTool, 'spawn', 'sim-1', 'bridge']);
+  // @ts-expect-error An argv typed string[] may start with simctl, so it is refused.
+  void runXcrun(argv);
+  // @ts-expect-error Copying a scoped command drops its brand.
+  void runXcrun([...LAUNCH_COMMAND]);
+  // @ts-expect-error A request whose tool may be simctl goes to the simctl provider with its scoped args.
+  void runXcrun([request.tool, ...request.args]);
+  // @ts-expect-error A hand-built simctl argv is not a ScopedSimctlCommand.
+  const handBuilt: ScopedSimctlCommand = ['simctl', 'boot', 'sim-1'];
+  void handBuilt;
+  // @ts-expect-error simctlCommand takes set-scoped arguments, never a raw argv.
+  void simctlCommand(['boot', 'sim-1']);
 }
 void compileTimeScopedSimctlProof;
 
@@ -24,10 +61,7 @@ test('scoped Apple tool provider handles xcrun execution', async () => {
     },
   });
 
-  const result = await withAppleToolProvider(
-    provider,
-    async () => await runXcrun(['simctl', 'launch', 'sim-1', 'com.example.app']),
-  );
+  const result = await withAppleToolProvider(provider, async () => await runXcrun(LAUNCH_COMMAND));
 
   assert.equal(result.stdout, 'ok');
   assert.deepEqual(calls, [['xcrun', ['simctl', 'launch', 'sim-1', 'com.example.app']]]);
@@ -56,7 +90,7 @@ test('scoped Apple tool provider prefers semantic simctl and devicectl hooks', a
 
   const simctlResult = await withAppleToolProvider(
     provider,
-    async () => await runXcrun(['simctl', 'launch', 'sim-1', 'com.example.app']),
+    async () => await runXcrun(LAUNCH_COMMAND),
   );
   const devicectlResult = await withAppleToolProvider(
     provider,
@@ -71,6 +105,38 @@ test('scoped Apple tool provider prefers semantic simctl and devicectl hooks', a
   ]);
 });
 
+test('simctlCommand prefixes set-scoped arguments with the tool name and freezes the argv', () => {
+  const command = simctlCommand(
+    scopeSimctlArgsForDevice({ ...IOS_SIMULATOR, simulatorSetPath: '/tmp/tenant/simulator-set' }, [
+      'boot',
+      'sim-1',
+    ]),
+  );
+
+  assert.deepEqual(command, ['simctl', '--set', '/tmp/tenant/simulator-set', 'boot', 'sim-1']);
+  assert.ok(Object.isFrozen(command));
+});
+
+test('runXcrun hands a scoped simctl command to the simctl provider with its set intact', async () => {
+  const received: Array<readonly string[]> = [];
+  const provider = createLocalAppleToolProvider({
+    simctl: {
+      run: async (args) => {
+        received.push(args);
+        return { exitCode: 0, stdout: '', stderr: '' };
+      },
+    },
+  });
+  const command = buildSimctlArgsForDevice(
+    { ...IOS_SIMULATOR, simulatorSetPath: '/tmp/tenant/simulator-set' },
+    ['boot', 'sim-1'],
+  );
+
+  await withAppleToolProvider(provider, async () => await runXcrun(command));
+
+  assert.deepEqual(received, [['--set', '/tmp/tenant/simulator-set', 'boot', 'sim-1']]);
+});
+
 test('scoped Apple tool provider exposes plist JSON reads as semantic operation', async () => {
   const provider = createLocalAppleToolProvider({
     runCommand: async () => {
diff --git a/packages/platform-apple/src/core/app-launch.ts b/packages/platform-apple/src/core/app-launch.ts
index 652eeb3ab4..0d133040dd 100644
--- a/packages/platform-apple/src/core/app-launch.ts
+++ b/packages/platform-apple/src/core/app-launch.ts
@@ -27,7 +27,7 @@ import {
   launchFailureHint,
 } from './launch-diagnostics.ts';
 import { ensureBootedSimulator } from './simulator.ts';
-import { runXcrun } from './tool-provider.ts';
+import { runXcrun, type ScopedSimctlCommand } from './tool-provider.ts';
 import { closeMacOsApp, openMacOsApp } from '../os/macos/apps.ts';
 import { resolveIosApp } from './app-resolution.ts';
 import { buildSimctlArgsForDevice, runSimctlForDevice } from './simctl.ts';
@@ -301,7 +301,7 @@ function buildIosSimulatorLaunchArgs(
 }
 
 async function runIosSimulatorConsoleLaunch(
-  launchArgs: string[],
+  launchArgs: ScopedSimctlCommand,
   logPath: string,
 ): Promise<Awaited<ReturnType<typeof runXcrun>>> {
   await ensureHostDirectory(path.dirname(logPath));
diff --git a/packages/platform-apple/src/core/devicectl.ts b/packages/platform-apple/src/core/devicectl.ts
index 3403b37068..92ec8ea808 100644
--- a/packages/platform-apple/src/core/devicectl.ts
+++ b/packages/platform-apple/src/core/devicectl.ts
@@ -60,7 +60,7 @@ export async function runIosDevicectl(
     tolerateOutput?: (stdout: string, stderr: string) => boolean;
   } = {},
 ): Promise<void> {
-  const fullArgs = ['devicectl', ...args];
+  const fullArgs: ['devicectl', ...string[]] = ['devicectl', ...args];
   const result = await runXcrun(fullArgs, {
     allowFailure: true,
     signal: options.signal,
@@ -202,7 +202,7 @@ export type IosDevicectlJsonOutcome =
  */
 export async function runIosDevicectlJsonRequest(options: {
   jsonPrefix: string;
-  args: string[];
+  args: ['devicectl', ...string[]];
   timeoutMs?: number;
   signal?: AbortSignal;
   tolerateFailurePayload?: (payload: unknown) => boolean;
@@ -211,7 +211,7 @@ export async function runIosDevicectlJsonRequest(options: {
     hostTemporaryDirectory(),
     `${options.jsonPrefix}-${hostProcessId()}-${Date.now()}-${Math.random().toString(36).slice(2)}.json`,
   );
-  const args = [...options.args, '--json-output', jsonPath];
+  const args: ['devicectl', ...string[]] = [...options.args, '--json-output', jsonPath];
   try {
     const result = await runXcrun(args, {
       allowFailure: true,
@@ -248,7 +248,7 @@ async function runIosDevicectlJsonCommand(
   device: DeviceInfo,
   options: {
     jsonPrefix: string;
-    args: string[];
+    args: ['devicectl', ...string[]];
     failureMessage: string;
     parseFailureMessage: string;
     fallbackHint?: string;
diff --git a/packages/platform-apple/src/core/hinge-angle.ts b/packages/platform-apple/src/core/hinge-angle.ts
index d7d8a1531b..bd864847dc 100644
--- a/packages/platform-apple/src/core/hinge-angle.ts
+++ b/packages/platform-apple/src/core/hinge-angle.ts
@@ -28,7 +28,7 @@ export async function readAppleHingeAngle(
   device: DeviceInfo,
   options: { signal?: AbortSignal } = {},
 ): Promise<number> {
-  const args = [
+  const args: ['devicectl', ...string[]] = [
     'devicectl',
     'device',
     'motion',
diff --git a/packages/platform-apple/src/core/perf-target.ts b/packages/platform-apple/src/core/perf-target.ts
index facc6e8650..120bc5f90e 100644
--- a/packages/platform-apple/src/core/perf-target.ts
+++ b/packages/platform-apple/src/core/perf-target.ts
@@ -8,7 +8,7 @@ import type { IosDeviceProcessInfo } from './app-info.ts';
 import { resolveIosPhysicalDeviceControl } from './physical-device-control.ts';
 import { readInfoPlistString } from './plist.ts';
 import { buildSimctlArgsForDevice } from './simctl.ts';
-import { runAppleToolCommand, runXcrun } from './tool-provider.ts';
+import { runAppleToolCommand, runXcrun, type ScopedSimctlCommand } from './tool-provider.ts';
 
 const APPLE_PERF_TIMEOUT_MS = 15_000;
 
@@ -152,25 +152,26 @@ export async function readAppleProcessSamples(
   device: DeviceInfo,
   executable: { executableName: string; executablePath?: string },
 ): Promise<AppleProcessSample[]> {
-  const args = isMacOs(device)
-    ? ['-axo', 'pid=,%cpu=,rss=,command=']
-    : buildSimctlArgsForDevice(device, [
-        'spawn',
-        device.id,
-        'ps',
-        '-axo',
-        'pid=,%cpu=,rss=,command=',
-      ]);
   const result = isMacOs(device)
-    ? await runAppleToolCommand('ps', args, { timeoutMs: APPLE_PERF_TIMEOUT_MS })
-    : await runAppleSimulatorProcessCommand(args);
+    ? await runAppleToolCommand('ps', ['-axo', 'pid=,%cpu=,rss=,command='], {
+        timeoutMs: APPLE_PERF_TIMEOUT_MS,
+      })
+    : await runAppleSimulatorProcessCommand(
+        buildSimctlArgsForDevice(device, [
+          'spawn',
+          device.id,
+          'ps',
+          '-axo',
+          'pid=,%cpu=,rss=,command=',
+        ]),
+      );
   const { matchesAppleExecutableProcess } = await import('./perf-process-identity.ts');
   return parseApplePsOutput(result.stdout).filter((processInfo) =>
     matchesAppleExecutableProcess(processInfo.command, executable),
   );
 }
 
-async function runAppleSimulatorProcessCommand(args: string[]): Promise<ExecResult> {
+async function runAppleSimulatorProcessCommand(args: ScopedSimctlCommand): Promise<ExecResult> {
   const result = await runXcrun(args, {
     allowFailure: true,
     timeoutMs: APPLE_PERF_TIMEOUT_MS,
diff --git a/packages/platform-apple/src/core/perf-xctrace.ts b/packages/platform-apple/src/core/perf-xctrace.ts
index 44602afbc4..03fc3f0d9d 100644
--- a/packages/platform-apple/src/core/perf-xctrace.ts
+++ b/packages/platform-apple/src/core/perf-xctrace.ts
@@ -306,7 +306,7 @@ export async function exportAppleXctraceData(params: {
   failureMessage: string;
   failureDetails: Record<string, unknown>;
 }): Promise<string> {
-  const exportArgs = [
+  const exportArgs: ['xctrace', ...string[]] = [
     'xctrace',
     'export',
     '--input',
@@ -376,7 +376,7 @@ function buildAppleXctraceRecordArgs(params: {
   target: AppleXctraceRecordTarget;
   timeLimit?: string;
   outPath: string;
-}): string[] {
+}): ['xctrace', ...string[]] {
   return [
     'xctrace',
     'record',
diff --git a/packages/platform-apple/src/core/physical-device-control.ts b/packages/platform-apple/src/core/physical-device-control.ts
index 9d174219c1..54ddb3651f 100644
--- a/packages/platform-apple/src/core/physical-device-control.ts
+++ b/packages/platform-apple/src/core/physical-device-control.ts
@@ -159,7 +159,13 @@ async function rejectXctestRunnerFileCopy(device: DeviceInfo): Promise<never> {
 
 async function ensureXctestDeviceReady(device: DeviceInfo, signal?: AbortSignal): Promise<void> {
   const timeoutSeconds = Math.max(1, Math.ceil(IOS_DEVICE_READY_TIMEOUT_MS / 1000));
-  const args = ['xcdevice', 'wait', '--both', `--timeout=${timeoutSeconds}`, device.id];
+  const args: ['xcdevice', ...string[]] = [
+    'xcdevice',
+    'wait',
+    '--both',
+    `--timeout=${timeoutSeconds}`,
+    device.id,
+  ];
   const result = await runXcrun(args, {
     allowFailure: true,
     signal,
diff --git a/packages/platform-apple/src/core/settings-parsing.ts b/packages/platform-apple/src/core/settings-parsing.ts
index 2f6eccff0b..fe98413908 100644
--- a/packages/platform-apple/src/core/settings-parsing.ts
+++ b/packages/platform-apple/src/core/settings-parsing.ts
@@ -21,7 +21,7 @@ export function parseSettingState(state: string): boolean {
 
 // fallow-ignore-next-line code-duplication
 export type CommandAttemptFailure = {
-  args: string[];
+  args: readonly string[];
   stdout: string;
   stderr: string;
   exitCode: number;
diff --git a/packages/platform-apple/src/core/simctl.ts b/packages/platform-apple/src/core/simctl.ts
index eddb2d7933..6c156bdd60 100644
--- a/packages/platform-apple/src/core/simctl.ts
+++ b/packages/platform-apple/src/core/simctl.ts
@@ -2,10 +2,7 @@ import { isIosFamily, type DeviceInfo } from '@agent-device/kernel/device';
 import { type ExecOptions, type ExecResult } from '@agent-device/host-kit/command';
 import { resolveIosSimulatorDeviceSetPath } from '@agent-device/kernel/device-isolation';
 import type { ScopedSimctlArgs } from '@agent-device/contracts/platform-runtime-host';
-import { runXcrun } from './tool-provider.ts';
-
-/** The set of a simctl call that names no device; `undefined` names the default set on purpose. */
-export type SimulatorSetScope = Readonly<{ simulatorSetPath: string | undefined }>;
+import { runXcrun, simctlCommand, type ScopedSimctlCommand } from './tool-provider.ts';
 
 declare const simulatorAddress: unique symbol;
 /** A simulator udid with the set that holds it; minted only from a DeviceInfo. */
@@ -19,22 +16,23 @@ export function simulatorAddressFor(device: DeviceInfo): SimulatorAddress {
   return Object.freeze({ udid: device.id, simulatorSetPath }) as SimulatorAddress;
 }
 
-/** Arguments that follow the `simctl` tool name for a call that names no device. */
-export function scopeSimctlArgs(
+function scopeSimctlArgs(
+  simulatorSetPath: string | undefined,
   args: readonly string[],
-  scope: SimulatorSetScope,
 ): ScopedSimctlArgs {
-  const simulatorSetPath = resolveIosSimulatorDeviceSetPath(scope.simulatorSetPath);
-  const scoped = simulatorSetPath ? ['--set', simulatorSetPath, ...args] : [...args];
+  const resolvedSetPath = resolveIosSimulatorDeviceSetPath(simulatorSetPath);
+  const scoped = resolvedSetPath ? ['--set', resolvedSetPath, ...args] : [...args];
   return Object.freeze(scoped) as ScopedSimctlArgs;
 }
 
-/** Arguments that follow the `simctl` tool name, scoped to the set holding the addressed simulator. */
-export function scopeSimctlArgsForAddress(
-  address: SimulatorAddress,
-  args: readonly string[],
-): ScopedSimctlArgs {
-  return scopeSimctlArgs(args, { simulatorSetPath: address.simulatorSetPath });
+/** `simctl help`: probes that simctl runs at all, so it names no set. */
+export function simctlAvailabilityProbeArgs(): ScopedSimctlArgs {
+  return scopeSimctlArgs(undefined, ['help']);
+}
+
+/** `simctl list devices -j` over one simulator set; `undefined` lists the default set. */
+export function simctlListDevicesArgs(simulatorSetPath: string | undefined): ScopedSimctlArgs {
+  return scopeSimctlArgs(simulatorSetPath, ['list', 'devices', '-j']);
 }
 
 /** Arguments that follow the `simctl` tool name, scoped to the simulator set holding the device. */
@@ -42,18 +40,21 @@ export function scopeSimctlArgsForDevice(
   device: DeviceInfo,
   args: readonly string[],
 ): ScopedSimctlArgs {
-  return scopeSimctlArgsForAddress(simulatorAddressFor(device), args);
+  return scopeSimctlArgs(simulatorAddressFor(device).simulatorSetPath, args);
 }
 
 export function buildSimctlArgsForAddress(
   address: SimulatorAddress,
   args: readonly string[],
-): string[] {
-  return ['simctl', ...scopeSimctlArgsForAddress(address, args)];
+): ScopedSimctlCommand {
+  return simctlCommand(scopeSimctlArgs(address.simulatorSetPath, args));
 }
 
-export function buildSimctlArgsForDevice(device: DeviceInfo, args: readonly string[]): string[] {
-  return ['simctl', ...scopeSimctlArgsForDevice(device, args)];
+export function buildSimctlArgsForDevice(
+  device: DeviceInfo,
+  args: readonly string[],
+): ScopedSimctlCommand {
+  return buildSimctlArgsForAddress(simulatorAddressFor(device), args);
 }
 
 export function runSimctlForDevice(
diff --git a/packages/platform-apple/src/core/tool-provider.ts b/packages/platform-apple/src/core/tool-provider.ts
index 1850f4abef..8e0667e32b 100644
--- a/packages/platform-apple/src/core/tool-provider.ts
+++ b/packages/platform-apple/src/core/tool-provider.ts
@@ -28,6 +28,28 @@ export type {
   AppleXcrunToolProvider,
 } from './tool-provider-types.ts';
 
+declare const scopedSimctlCommand: unique symbol;
+/** The xcrun argv of one simctl call: `simctl` followed by arguments already scoped to their set. */
+export type ScopedSimctlCommand = readonly ['simctl', ...string[]] & {
+  readonly [scopedSimctlCommand]: true;
+};
+
+export function simctlCommand(args: ScopedSimctlArgs): ScopedSimctlCommand {
+  return Object.freeze(['simctl', ...args] as const) as ScopedSimctlCommand;
+}
+
+async function runSimctlCommand(
+  runCommand: AppleToolCommandExecutor,
+  args: ScopedSimctlArgs,
+  options?: ExecOptions,
+): Promise<ExecResult> {
+  return await runCommand('xcrun', [...simctlCommand(args)], options);
+}
+
+function simctlCommandArgs(command: ScopedSimctlCommand): ScopedSimctlArgs {
+  return Object.freeze(command.slice(1)) as ScopedSimctlArgs;
+}
+
 export type AppleToolProvider = {
   runCommand: AppleToolCommandExecutor;
   simctl: AppleSimctlToolProvider;
@@ -41,7 +63,7 @@ export type AppleToolProvider = {
 const localAppleToolProvider: AppleToolProvider = {
   runCommand: runCmd,
   simctl: {
-    run: async (args, options) => await runCmd('xcrun', ['simctl', ...args], options),
+    run: async (args, options) => await runSimctlCommand(runCmd, args, options),
   },
   devicectl: {
     run: async (args, options) => await runCmd('xcrun', ['devicectl', ...args], options),
@@ -76,7 +98,7 @@ export function createLocalAppleToolProvider(
   return {
     ...merged,
     simctl: provider.simctl ?? {
-      run: async (args, options) => await merged.runCommand('xcrun', ['simctl', ...args], options),
+      run: async (args, options) => await runSimctlCommand(merged.runCommand, args, options),
     },
     devicectl: provider.devicectl ?? {
       run: async (args, options) =>
@@ -115,16 +137,22 @@ export async function runAppleToolCommand(
   return await resolveAppleToolProvider().runCommand(cmd, args, options);
 }
 
-export async function runXcrun(args: string[], options?: ExecOptions): Promise<ExecResult> {
+/** An xcrun argv for a tool other than simctl; a simctl argv is a ScopedSimctlCommand. */
+type XcrunToolArgs = readonly ['devicectl' | 'xcdevice' | 'xctrace', ...string[]];
+
+export async function runXcrun(
+  args: ScopedSimctlCommand | XcrunToolArgs,
+  options?: ExecOptions,
+): Promise<ExecResult> {
   const provider = resolveAppleToolProvider();
-  const [tool, ...toolArgs] = args;
-  if (tool === 'simctl') {
-    return await provider.simctl.run(toolArgs as unknown as ScopedSimctlArgs, options);
+  if (args[0] === 'simctl') {
+    return await provider.simctl.run(simctlCommandArgs(args), options);
   }
+  const [tool, ...toolArgs] = args;
   if (tool === 'devicectl') {
     return await provider.devicectl.run(toolArgs, options);
   }
-  return await runAppleToolCommand('xcrun', args, options);
+  return await runAppleToolCommand('xcrun', [...args], options);
 }
 
 export async function readApplePlistJson(
diff --git a/packages/platform-apple/src/logs/doctor.test.ts b/packages/platform-apple/src/logs/doctor.test.ts
index f9747bc00b..fede82780f 100644
--- a/packages/platform-apple/src/logs/doctor.test.ts
+++ b/packages/platform-apple/src/logs/doctor.test.ts
@@ -1,4 +1,5 @@
 import { expect, test, vi } from 'vitest';
+import { scopeSimctlArgsForDevice } from '../core/simctl.ts';
 import { doctorAppleAppLogs } from './doctor.ts';
 import { appleDevice, hostFixture } from './runtime.fixtures.ts';
 
@@ -24,12 +25,10 @@ test('simulator doctor routes the exact simctl probe through appleTools', async
 test('simulator doctor probes simctl without a set, even for a scoped-set simulator', async () => {
   const appleToolRun = vi.fn(async () => ({ stdout: 'simctl help', stderr: '', exitCode: 0 }));
   const fixture = hostFixture({ appleToolRun });
+  const device = appleDevice({ simulatorSetPath: '/tmp/scoped-set' });
+  expect(scopeSimctlArgsForDevice(device, ['help'])).toEqual(['--set', '/tmp/scoped-set', 'help']);
 
-  await doctorAppleAppLogs(
-    fixture.host,
-    appleDevice({ simulatorSetPath: '/tmp/scoped-set' }),
-    'com.example.app',
-  );
+  await doctorAppleAppLogs(fixture.host, device, 'com.example.app');
   expect(appleToolRun).toHaveBeenCalledWith(
     { tool: 'simctl', args: ['help'], allowFailure: true },
     undefined,
diff --git a/packages/platform-apple/src/logs/doctor.ts b/packages/platform-apple/src/logs/doctor.ts
index 2414566351..56a6f1dfc6 100644
--- a/packages/platform-apple/src/logs/doctor.ts
+++ b/packages/platform-apple/src/logs/doctor.ts
@@ -1,7 +1,7 @@
 import { isMacOs, type DeviceInfo } from '@agent-device/kernel/device';
 import type { AppLogRuntimeHost } from '@agent-device/contracts/app-log-runtime';
 import { appLogCommandSucceeded, bestEffortAppLogCheck } from '@agent-device/capture-kit';
-import { scopeSimctlArgs } from '../core/simctl.ts';
+import { simctlAvailabilityProbeArgs } from '../core/simctl.ts';
 import { APPLE_XCTEST_LOGS_HINT, backendForAppleDevice } from './backend.ts';
 import {
   checkCoreDeviceConsoleCaptureSupport,
@@ -28,7 +28,7 @@ export async function doctorAppleAppLogs(
           await host.appleTools.run(
             {
               tool: 'simctl',
-              args: scopeSimctlArgs(['help'], { simulatorSetPath: undefined }),
+              args: simctlAvailabilityProbeArgs(),
               allowFailure: true,
             },
             signal,
diff --git a/packages/platform-apple/src/logs/log-predicate.ts b/packages/platform-apple/src/logs/log-predicate.ts
index 15893d2f2b..b967fa55ac 100644
--- a/packages/platform-apple/src/logs/log-predicate.ts
+++ b/packages/platform-apple/src/logs/log-predicate.ts
@@ -1,5 +1,6 @@
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import { buildSimctlArgsForDevice } from '../core/simctl.ts';
+import type { ScopedSimctlCommand } from '../core/tool-provider.ts';
 
 export function buildAppleLogPredicate(appBundleId: string, executableName?: string): string {
   const escapedBundleId = escapePredicateString(appBundleId);
@@ -25,7 +26,7 @@ export function buildAppleLogPredicate(appBundleId: string, executableName?: str
 export function buildIosSimulatorLogStreamArgs(
   device: DeviceInfo,
   params: { appBundleId: string; executableName?: string },
-): string[] {
+): ScopedSimctlCommand {
   return buildSimctlArgsForDevice(device, [
     'spawn',
     device.id,
diff --git a/packages/platform-apple/src/simctl-facade.ts b/packages/platform-apple/src/simctl-facade.ts
index c1d5a806c3..752e1ad262 100644
--- a/packages/platform-apple/src/simctl-facade.ts
+++ b/packages/platform-apple/src/simctl-facade.ts
@@ -1,6 +1,7 @@
 import type { DeviceInfo } from '@agent-device/kernel/device';
 
 import { buildSimctlArgsForDevice } from './core/simctl.ts';
+import type { ScopedSimctlCommand } from './core/tool-provider.ts';
 
 export { buildSimctlArgsForDevice };
 
@@ -19,7 +20,7 @@ export async function buildAppleSimulatorRecordVideoArgs(
   device: DeviceInfo,
   outputPath: string,
   options: { timeoutMs?: number; signal?: AbortSignal } = {},
-): Promise<string[]> {
+): Promise<ScopedSimctlCommand> {
   const { appleSimulatorDisplayArgvFragment, resolveAppleCaptureDisplay } =
     await import('./core/display-inventory.ts');
   const display = await resolveAppleCaptureDisplay(device, options);
diff --git a/packages/platform-apple/src/simulator-inventory.test.ts b/packages/platform-apple/src/simulator-inventory.test.ts
index bf2c66c02d..17ab04e6bd 100644
--- a/packages/platform-apple/src/simulator-inventory.test.ts
+++ b/packages/platform-apple/src/simulator-inventory.test.ts
@@ -1,11 +1,7 @@
 import assert from 'node:assert/strict';
 import { test } from 'vitest';
 import { AppError } from '@agent-device/kernel/errors';
-import {
-  buildSimctlListArgs,
-  listAppleSimulators,
-  parseSimctlAppleDevices,
-} from './simulator-inventory.ts';
+import { listAppleSimulators, parseSimctlAppleDevices } from './simulator-inventory.ts';
 import { commandResult, createInventoryHost, inventoryScope } from './inventory.fixtures.ts';
 
 const simulatorPayload = {
@@ -118,7 +114,6 @@ test('simulator inventory scopes bounded simctl and reports fresh booted observa
     ['iphone-1', 'tv-1'],
   );
   assert.deepEqual(observed, ['iphone-1']);
-  assert.deepEqual(buildSimctlListArgs(undefined), ['list', 'devices', '-j']);
 });
 
 test('simulator inventory classifies malformed native output as a command failure', async () => {
diff --git a/packages/platform-apple/src/simulator-inventory.ts b/packages/platform-apple/src/simulator-inventory.ts
index dcdc03147e..1c2a57730a 100644
--- a/packages/platform-apple/src/simulator-inventory.ts
+++ b/packages/platform-apple/src/simulator-inventory.ts
@@ -2,11 +2,10 @@ import type { DeviceInventoryRequest } from '@agent-device/contracts/device';
 import type {
   DeviceInventoryHostFor,
   PlatformRequestScope,
-  ScopedSimctlArgs,
 } from '@agent-device/contracts/platform-runtime-host';
 import { sortAppleDevicesForSelection, type DeviceInfo } from '@agent-device/kernel/device';
 import { AppError } from '@agent-device/kernel/errors';
-import { scopeSimctlArgs } from './core/simctl.ts';
+import { simctlListDevicesArgs } from './core/simctl.ts';
 import {
   isSupportedAppleRuntime,
   resolveAppleOs,
@@ -27,10 +26,6 @@ type SimctlListDevicesPayload = {
 
 const BOOTED_SIMULATOR_PROBE_TIMEOUT_MS = 3_000;
 
-export function buildSimctlListArgs(simulatorSetPath: string | undefined): ScopedSimctlArgs {
-  return scopeSimctlArgs(['list', 'devices', '-j'], { simulatorSetPath });
-}
-
 export function parseSimctlAppleDevices(
   payload: SimctlListDevicesPayload,
   simulatorSetPath: string | undefined,
@@ -65,7 +60,7 @@ export async function listAppleSimulators(
   const result = await host.appleTools.run(
     {
       tool: 'simctl',
-      args: buildSimctlListArgs(simulatorSetPath),
+      args: simctlListDevicesArgs(simulatorSetPath),
       ...(request.booted === true ? { timeoutMs: BOOTED_SIMULATOR_PROBE_TIMEOUT_MS } : {}),
     },
     scope.signal,
diff --git a/scripts/layering/apple-simulator-scope-policy.test.ts b/scripts/layering/apple-simulator-scope-policy.test.ts
index 652633518d..f0f8d6ffe4 100644
--- a/scripts/layering/apple-simulator-scope-policy.test.ts
+++ b/scripts/layering/apple-simulator-scope-policy.test.ts
@@ -6,10 +6,12 @@ import {
 } from './apple-simulator-scope-policy.ts';
 
 const APPLE_SRC = 'packages/platform-apple/src/';
-const ARGV_MESSAGE =
-  /^builds or forges simctl argv outside core\/simctl\.ts; use scopeSimctlArgsForDevice\/runSimctlForDevice or a SimulatorAddress from simulatorAddressFor\(device\)$/;
-const SET_SCOPE_MESSAGE =
-  /^set-scope simctl builder outside its owners; a call that names a udid takes its set from the device \(scopeSimctlArgsForDevice\) or its SimulatorAddress$/;
+const SIMCTL_ARGV_MESSAGE =
+  /^builds a simctl argv outside core\/simctl\.ts and core\/tool-provider\.ts; build it with buildSimctlArgsForDevice or buildSimctlArgsForAddress$/;
+const HAND_BUILT_MESSAGE =
+  /^hands xcrun an argv whose tool is not a literal non-simctl name; build a simctl argv with buildSimctlArgsForDevice or buildSimctlArgsForAddress$/;
+const FORGED_MESSAGE =
+  /^forges a simulator-scope brand outside core\/simctl\.ts and core\/tool-provider\.ts; mint it with simulatorAddressFor, scopeSimctlArgsForDevice or buildSimctlArgsForDevice$/;
 
 function violationsFor(file: string, source: string) {
   return appleSimulatorScopeViolations(new Map([[file, source]]));
@@ -23,80 +25,101 @@ function assertFlagged(file: string, source: string, message: RegExp): void {
   assert.match(violations[0]!.message, message);
 }
 
-const HAND_BUILT_SPAWN = "runXcrun(['simctl', 'spawn', udid, binary]);\n";
 const HAND_BUILT_BRIDGE = "runCmdBackground('xcrun', ['simctl', 'spawn', udid, bridge]);\n";
-const EXPLICIT_DEFAULT_SET =
-  "scopeSimctlArgs(['spawn', udid, bin], { simulatorSetPath: undefined });\n";
-const ALIASED_SET_SCOPE = "import { scopeSimctlArgs as scope } from '../core/simctl.ts';\n";
 const FORGED_ARGV =
   "resolveAppleToolProvider().simctl.run(['spawn', udid, bin] as unknown as ScopedSimctlArgs);\n";
 const FORGED_ADDRESS = 'const address = { udid, simulatorSetPath } as SimulatorAddress;\n';
-const HAND_PREFIX = "const args = ['--set', path, ...args];\n";
 
-test('the two #2818 hand-built simctl spawns are refused', () => {
-  assertFlagged(`${APPLE_SRC}foldable/simulator-hid.ts`, HAND_BUILT_SPAWN, ARGV_MESSAGE);
-  assertFlagged(`${APPLE_SRC}snapshot-source/host.ts`, HAND_BUILT_BRIDGE, ARGV_MESSAGE);
+test('the #2818 bridge spawn through a plain xcrun executor is refused', () => {
+  assertFlagged(`${APPLE_SRC}snapshot-source/host.ts`, HAND_BUILT_BRIDGE, SIMCTL_ARGV_MESSAGE);
 });
 
-test('the set-scope builder is refused outside its owners, aliased or not', () => {
-  assertFlagged(`${APPLE_SRC}foldable/simulator-hid.ts`, EXPLICIT_DEFAULT_SET, SET_SCOPE_MESSAGE);
-  assertFlagged(`${APPLE_SRC}snapshot-source/host.ts`, ALIASED_SET_SCOPE, SET_SCOPE_MESSAGE);
+test('a simctl argv is refused however it reaches an executor', () => {
+  for (const source of [
+    "const argv = ['simctl', 'spawn', udid, bin];\nrunCmd('xcrun', argv);\n",
+    "const argv = ['simctl', 'spawn', udid, bridge];\nrunCmdBackground('xcrun', argv, { detached: true });\n",
+    "const argv = ['simctl', 'spawn', udid, 'log', 'stream'];\nhost.commands.run({ executable: 'xcrun', args: argv });\n",
+    "const argv = ['simctl', 'boot', udid];\nconst alias = argv;\nrunCmd('xcrun', alias);\n",
+    "const argv = ['simctl', 'boot', udid];\nrunCmd('xcrun', [...argv]);\n",
+    "const head = ['simctl'];\nrunCmd('xcrun', [...head, 'boot', udid]);\n",
+    "const tool = 'simctl';\nconst argv = [tool, 'spawn', udid, bin];\nrunCmd('xcrun', argv);\n",
+    "const tool = `simctl`;\nrunCmdBackground('xcrun', [tool, 'spawn', udid, bin]);\n",
+    "runCmd('xcrun', [`simctl`, 'boot', udid]);\n",
+    "host.commands.run({ executable: 'xcrun', args: ['simctl', 'spawn', udid, 'log', 'stream'] });\n",
+    "const tools = ['simctl', 'devicectl'];\n",
+    "runCmd('xcrun', ['--sdk', 'iphonesimulator', 'simctl', 'boot', udid]);\n",
+    "const tool = 'simctl';\nconst argv = ['-v', tool, 'spawn', udid, bin];\nrunCmd('xcrun', argv);\n",
+  ]) {
+    assertFlagged(`${APPLE_SRC}logs/start.ts`, source, SIMCTL_ARGV_MESSAGE);
+  }
 });
 
-test('a forged scoped argv or simulator address is refused', () => {
-  assertFlagged('src/platform-runtime-planted.ts', FORGED_ARGV, ARGV_MESSAGE);
-  assertFlagged(`${APPLE_SRC}foldable/simulator-hid.ts`, FORGED_ADDRESS, ARGV_MESSAGE);
+test('an inline xcrun argv must name its tool as a literal other than simctl', () => {
+  for (const source of [
+    "runCmd('xcrun', [tool, 'spawn', udid, bin]);\n",
+    "runCmd('xcrun', [`${tool}`, 'boot', udid]);\n",
+    "host.commands.run({ executable: 'xcrun', args: [request.tool, ...request.args] });\n",
+  ]) {
+    assertFlagged(`${APPLE_SRC}logs/start.ts`, source, HAND_BUILT_MESSAGE);
+  }
+});
+
+test('the tool provider has no exemption for a hand-built simctl argv', () => {
+  assertFlagged(
+    `${APPLE_SRC}core/tool-provider.ts`,
+    "runCmd('xcrun', ['simctl', ...args]);\n",
+    HAND_BUILT_MESSAGE,
+  );
+});
+
+test('a cast to a simulator-scope brand is refused outside the mint modules', () => {
+  assertFlagged('src/platform-runtime-planted.ts', FORGED_ARGV, FORGED_MESSAGE);
+  assertFlagged(
+    `${APPLE_SRC}core/simulator.ts`,
+    'return argv as ScopedSimctlCommand;\n',
+    FORGED_MESSAGE,
+  );
+  assertFlagged(`${APPLE_SRC}foldable/simulator-hid.ts`, FORGED_ADDRESS, FORGED_MESSAGE);
   assertFlagged(
     `${APPLE_SRC}foldable/simulator-hid.ts`,
     'const address = <SimulatorAddress>{ udid, simulatorSetPath };\n',
-    ARGV_MESSAGE,
+    FORGED_MESSAGE,
   );
 });
 
-test('a hand-rolled --set prefix is refused outside core/simctl.ts', () => {
-  assertFlagged(`${APPLE_SRC}foldable/simulator-hid.ts`, HAND_PREFIX, ARGV_MESSAGE);
+test('the mint modules may build and cast to the brands they mint', () => {
+  const mintSource =
+    FORGED_ARGV +
+    FORGED_ADDRESS +
+    "return Object.freeze(['simctl', ...args] as const) as ScopedSimctlCommand;\n";
+  for (const mint of [`${APPLE_SRC}core/simctl.ts`, `${APPLE_SRC}core/tool-provider.ts`]) {
+    assert.deepEqual(violationsFor(mint, mintSource), [], mint);
+  }
 });
 
-test('the argv owners may build, prefix and mint', () => {
-  const owner = `${APPLE_SRC}core/simctl.ts`;
-  for (const source of [
-    HAND_BUILT_SPAWN,
-    HAND_BUILT_BRIDGE,
-    EXPLICIT_DEFAULT_SET,
-    ALIASED_SET_SCOPE,
-    FORGED_ARGV,
-    FORGED_ADDRESS,
-    HAND_PREFIX,
-  ]) {
-    assert.deepEqual(violationsFor(owner, source), [], source);
-  }
+test('named tools, builder output, pass-through argv and simctl text elsewhere are not violations', () => {
   assert.deepEqual(
     violationsFor(
       `${APPLE_SRC}core/tool-provider.ts`,
-      "provider.simctl.run(toolArgs as unknown as ScopedSimctlArgs, options);\nrunCmd('xcrun', ['simctl', ...args]);\n",
+      [
+        "runCmd('xcrun', ['devicectl', ...args]);",
+        "runCmd('xcrun', ['--find', name]);",
+        "runCmd('xcrun', ['--sdk', sdkName, '--show-sdk-version']);",
+        "runCmd('xcrun', simctlCommand(args));",
+        "runCmd('xcrun', [...argv]);",
+        "runCmdBackground('xcrun', args);",
+        "runCmdBackground('xcrun', buildSimctlArgsForAddress(simulator, ['spawn', simulator.udid]));",
+        "host.commands.run({ executable: 'log', args: ['stream'] });",
+        "host.appleTools.run({ tool: 'simctl', args: scopeSimctlArgsForDevice(device, ['boot', id]) });",
+        "const tools = ['devicectl', 'simctl'];",
+        "const tool = 'simctl';",
+        "if (args.includes('--set') || tool === 'simctl') note(tool);",
+      ].join('\n'),
     ),
     [],
   );
 });
 
-test('the tool provider may not forge an address or a --set prefix', () => {
-  assertFlagged(`${APPLE_SRC}core/tool-provider.ts`, FORGED_ADDRESS, ARGV_MESSAGE);
-  assertFlagged(`${APPLE_SRC}core/tool-provider.ts`, HAND_PREFIX, ARGV_MESSAGE);
-});
-
-test('the calls that name no device may take set scope', () => {
-  for (const file of [`${APPLE_SRC}simulator-inventory.ts`, `${APPLE_SRC}logs/doctor.ts`]) {
-    assert.deepEqual(
-      violationsFor(
-        file,
-        "import { scopeSimctlArgs } from './core/simctl.ts';\nscopeSimctlArgs(['help'], { simulatorSetPath: undefined });\n",
-      ),
-      [],
-      file,
-    );
-  }
-});
-
 test('tests, fixtures and scripts are not policed', () => {
   for (const file of [
     `${APPLE_SRC}foldable/simulator-hid.test.ts`,
@@ -106,38 +129,16 @@ test('tests, fixtures and scripts are not policed', () => {
     'test/integration/provider-scenarios/providers.ts',
   ]) {
     assert.equal(isPolicedSimulatorScopeFile(file), false, file);
-    assert.deepEqual(violationsFor(file, HAND_BUILT_SPAWN + EXPLICIT_DEFAULT_SET), [], file);
+    assert.deepEqual(violationsFor(file, HAND_BUILT_BRIDGE + FORGED_ADDRESS), [], file);
   }
   assert.equal(isPolicedSimulatorScopeFile(`${APPLE_SRC}foldable/simulator-hid.ts`), true);
   assert.equal(isPolicedSimulatorScopeFile('src/platform-runtime-apple-tool-host.ts'), true);
 });
 
-test('devicectl argv and scoped device calls are not simctl violations', () => {
-  assert.deepEqual(
-    violationsFor(
-      `${APPLE_SRC}deployment/runtime.ts`,
-      [
-        "host.appleTools.run({ tool: 'devicectl', args: ['device', 'install', 'app', '--device', id] });",
-        "host.appleTools.run({ tool: 'simctl', args: scopeSimctlArgsForDevice(device, ['boot', device.id]) });",
-        "runXcrun(buildSimctlArgsForAddress(simulatorAddressFor(device), ['spawn', device.id]));",
-      ].join('\n'),
-    ),
-    [],
-  );
-});
-
-test('an unaliased import of the set-scope builder is one violation', () => {
-  assertFlagged(
-    `${APPLE_SRC}snapshot-source/host.ts`,
-    "import { scopeSimctlArgs } from '../core/simctl.ts';\n",
-    SET_SCOPE_MESSAGE,
-  );
-});
-
-test('a violation reports the line of the offending node', () => {
+test('a violation reports the line of the offending argv', () => {
   const [violation] = violationsFor(
-    `${APPLE_SRC}foldable/simulator-hid.ts`,
-    `const a = 1;\n\n${HAND_BUILT_SPAWN}`,
+    `${APPLE_SRC}snapshot-source/host.ts`,
+    `const a = 1;\n\n${HAND_BUILT_BRIDGE}`,
   );
   assert.equal(violation!.line, 3);
 });
diff --git a/scripts/layering/apple-simulator-scope-policy.ts b/scripts/layering/apple-simulator-scope-policy.ts
index b83f4dd67a..3ac7446298 100644
--- a/scripts/layering/apple-simulator-scope-policy.ts
+++ b/scripts/layering/apple-simulator-scope-policy.ts
@@ -1,46 +1,47 @@
-// Catches: a simctl argv that addresses a simulator without the set that holds it -- built by hand
-//   (`['simctl', 'spawn', udid, ...]` into runXcrun, runCmdBackground or an `executable: 'xcrun'`
-//   spec), prefixed by hand (`'--set'`), forged through a cast to `ScopedSimctlArgs` or
-//   `SimulatorAddress`, or scoped through the set-scope builder with the set written out as
-//   `undefined`. Every form type-checks where the brand does not reach (plain argv executors) or
-//   where the set-scope builder accepts an explicit `undefined`, and every form runs against the
-//   default CoreSimulator set: `Invalid device` for a simulator in a scoped set, or a different
-//   simulator with the same udid.
+// Catches: the simctl scope bypasses `tsc` cannot reject. `runXcrun` accepts only a
+//   `ScopedSimctlCommand` or a named non-simctl tool, but the plain executors (`runCmd`,
+//   `runCmdBackground`, an `executable: 'xcrun'` spec) take any string argv, so every simctl argv
+//   reaching them must be builder output. (1) An array whose tool names simctl (the literal, a
+//   quasi-only template, or a same-file binding of either; the first element, or any element
+//   after leading xcrun options such as `--sdk`) outside the brand mints, however it later
+//   travels: inline, held in a variable, aliased or spread. (2) At an xcrun
+//   invocation, an inline argv whose tool is not a string literal other than `simctl`. (3) A cast
+//   to `ScopedSimctlArgs`, `ScopedSimctlCommand` or `SimulatorAddress` outside the brand mints.
+//   Every form runs against the default CoreSimulator set: `Invalid device` for a simulator in a
+//   scoped set, or a different simulator with the same udid.
 // Evidence: #2784 (fixed by #2818): the AX snapshot bridge (`snapshot-source/host.ts`) and the
 //   fold HID helper (`foldable/simulator-hid.ts`) built `['simctl', 'spawn', udid, ...]` from a
 //   bare udid and lost the set; #2824 moved every call site onto `core/simctl.ts` and checked it
-//   with a manual `git grep "'--set'"`, which this rule turns into a gate.
-// Cost: 271 LOC (128 rule + 143 test).
+//   with a manual `git grep "'--set'"`.
+// Cost: 311 LOC (167 rule + 144 test).
 // Kill criterion: none enforced today; retire only by maintainer decision that scoped simulator
-//   sets (`--ios-simulator-device-set`) are no longer supported, or when every simctl executor
-//   takes an argv type that only `core/simctl.ts` can mint.
+//   sets (`--ios-simulator-device-set`) are no longer supported, or when no production xcrun
+//   executor takes a plain string argv.
 
 import { parseSync } from 'oxc-parser';
-import { visitAst } from './layering-ast.ts';
+import { propertyName, visitAst } from './layering-ast.ts';
 import type { LayeringViolation } from './model.ts';
 
 type AstNode = Record<string, unknown>;
 
 const RULE = 'R79 apple-simulator-scope';
 
-const APPLE_SRC = 'packages/platform-apple/src/';
-const SIMCTL_OWNER = `${APPLE_SRC}core/simctl.ts`;
-const TOOL_PROVIDER = `${APPLE_SRC}core/tool-provider.ts`;
-const ARGV_OWNERS = new Set([SIMCTL_OWNER, TOOL_PROVIDER]);
-/** The owners whose simctl calls name no device, so they take set scope. */
-const SET_SCOPE_OWNERS = new Set([
-  SIMCTL_OWNER,
-  `${APPLE_SRC}simulator-inventory.ts`,
-  `${APPLE_SRC}logs/doctor.ts`,
+/** The modules that mint the simulator-scope brands; a cast to a brand anywhere else forges it. */
+const BRAND_MINTS = new Set([
+  'packages/platform-apple/src/core/simctl.ts',
+  'packages/platform-apple/src/core/tool-provider.ts',
 ]);
-const SET_SCOPE_BUILDER = 'scopeSimctlArgs';
+const BRANDS = new Set(['ScopedSimctlArgs', 'ScopedSimctlCommand', 'SimulatorAddress']);
 
-const ARGV_MESSAGE =
-  'builds or forges simctl argv outside core/simctl.ts; use scopeSimctlArgsForDevice/runSimctlForDevice ' +
-  'or a SimulatorAddress from simulatorAddressFor(device)';
-const SET_SCOPE_MESSAGE =
-  'set-scope simctl builder outside its owners; a call that names a udid takes its set from the ' +
-  'device (scopeSimctlArgsForDevice) or its SimulatorAddress';
+const SIMCTL_ARGV_MESSAGE =
+  'builds a simctl argv outside core/simctl.ts and core/tool-provider.ts; build it with ' +
+  'buildSimctlArgsForDevice or buildSimctlArgsForAddress';
+const HAND_BUILT_MESSAGE =
+  'hands xcrun an argv whose tool is not a literal non-simctl name; build a simctl argv with ' +
+  'buildSimctlArgsForDevice or buildSimctlArgsForAddress';
+const FORGED_MESSAGE =
+  'forges a simulator-scope brand outside core/simctl.ts and core/tool-provider.ts; mint it ' +
+  'with simulatorAddressFor, scopeSimctlArgsForDevice or buildSimctlArgsForDevice';
 
 /** Production TypeScript under `packages/*\/src/` and `src/`; tests and fixtures are exempt. */
 export function isPolicedSimulatorScopeFile(file: string): boolean {
@@ -58,71 +59,109 @@ export function appleSimulatorScopeViolations(
   const violations: LayeringViolation[] = [];
   for (const [file, source] of sources) {
     if (!isPolicedSimulatorScopeFile(file)) continue;
-    const reported = new Set<string>();
-    const report = (node: AstNode, message: string) => {
-      const offset = Number(node.start ?? 0);
-      if (reported.has(`${offset}:${message}`)) return;
-      reported.add(`${offset}:${message}`);
-      violations.push({ rule: RULE, file, line: lineAt(source, offset), message });
+    const program = parseSync(file, source).program;
+    const simctlBindings = simctlNameBindings(program);
+    const isMint = BRAND_MINTS.has(file);
+    const isSimctl = (element: AstNode | null) =>
+      namesSimctl(element ?? undefined) ||
+      (element?.type === 'Identifier' && simctlBindings.has(element.name));
+    const buildsSimctlArgv = (array: AstNode) => {
+      if (isMint) return false;
+      const elements = array.elements as (AstNode | null)[];
+      const [tool] = elements;
+      return isSimctl(tool ?? null) || (isXcrunOption(tool) && elements.some(isSimctl));
     };
-    visitAst(parseSync(file, source).program, (node) => {
-      if (
-        !ARGV_OWNERS.has(file) &&
-        node.type === 'ArrayExpression' &&
-        isStringLiteral((node.elements as unknown[])[0], 'simctl')
-      ) {
-        report(node, ARGV_MESSAGE);
-      }
-      if (file.startsWith(APPLE_SRC) && file !== SIMCTL_OWNER && isStringLiteral(node, '--set')) {
-        report(node, ARGV_MESSAGE);
-      }
-      if (
-        (node.type === 'TSAsExpression' || node.type === 'TSTypeAssertion') &&
-        forgesBrand(file, node.typeAnnotation)
-      ) {
-        report(node, ARGV_MESSAGE);
+    const report = (node: AstNode, message: string) =>
+      violations.push({ rule: RULE, file, line: lineAt(source, node.start), message });
+    visitAst(program, (node) => {
+      if (node.type === 'ArrayExpression' && buildsSimctlArgv(node)) {
+        report(node, SIMCTL_ARGV_MESSAGE);
       }
+      const argv = xcrunArgv(node);
       if (
-        !SET_SCOPE_OWNERS.has(file) &&
-        node.type === 'Identifier' &&
-        node.name === SET_SCOPE_BUILDER
+        argv?.type === 'ArrayExpression' &&
+        !buildsSimctlArgv(argv) &&
+        !namesNonSimctlTool(argv)
       ) {
-        report(node, SET_SCOPE_MESSAGE);
+        report(argv, HAND_BUILT_MESSAGE);
       }
+      if (!isMint && castsToBrand(node)) report(node, FORGED_MESSAGE);
     });
   }
   return violations;
 }
 
-function forgesBrand(file: string, typeAnnotation: unknown): boolean {
-  const names = referencedTypeNames(typeAnnotation);
-  return (
-    (file !== SIMCTL_OWNER && names.has('SimulatorAddress')) ||
-    (!ARGV_OWNERS.has(file) && names.has('ScopedSimctlArgs'))
-  );
+/** The argv of `f('xcrun', argv, …)` or of an `{ executable: 'xcrun', args }` spec. */
+function xcrunArgv(node: AstNode): AstNode | undefined {
+  if (node.type === 'CallExpression') {
+    const args = node.arguments as AstNode[];
+    const index = args.findIndex((arg) => isLiteral(arg, 'xcrun'));
+    return index >= 0 ? args[index + 1] : undefined;
+  }
+  if (node.type !== 'ObjectExpression') return undefined;
+  const properties = node.properties as AstNode[];
+  const valueOf = (key: string) =>
+    properties.find((property) => propertyName(property.key) === key)?.value as AstNode | undefined;
+  return isLiteral(valueOf('executable'), 'xcrun') ? valueOf('args') : undefined;
+}
+
+/** A spread passes an argv through like a variable; any other first element must name the tool. */
+function namesNonSimctlTool(argv: AstNode): boolean {
+  const tool = firstElement(argv);
+  if (tool?.type === 'SpreadElement') return true;
+  return tool?.type === 'Literal' && typeof tool.value === 'string' && tool.value !== 'simctl';
 }
 
-function referencedTypeNames(typeAnnotation: unknown): Set<string> {
-  const names = new Set<string>();
-  visitAst(typeAnnotation, (node) => {
-    if (node.type !== 'TSTypeReference') return;
-    const typeName = node.typeName as AstNode | undefined;
+/** A leading `-` literal is an xcrun option (`--sdk`, `--find`), so the tool name comes later. */
+function isXcrunOption(node: AstNode | null | undefined): boolean {
+  return node?.type === 'Literal' && typeof node.value === 'string' && node.value.startsWith('-');
+}
+
+function firstElement(array: AstNode): AstNode | undefined {
+  return (array.elements as (AstNode | null)[])[0] ?? undefined;
+}
+
+/** `'simctl'` or `` `simctl` ``, the two spellings of the tool name as a constant. */
+function namesSimctl(node: AstNode | undefined): boolean {
+  if (isLiteral(node, 'simctl')) return true;
+  if (node?.type !== 'TemplateLiteral' || (node.expressions as unknown[]).length > 0) return false;
+  const [quasi] = node.quasis as AstNode[];
+  return (quasi?.value as { cooked?: string } | undefined)?.cooked === 'simctl';
+}
+
+/** Names bound anywhere in the file to a constant spelling of `simctl`, whatever their scope. */
+function simctlNameBindings(program: unknown): Set<unknown> {
+  const bindings = new Set<unknown>();
+  visitAst(program, (node) => {
+    const id = node.id as AstNode | undefined;
+    if (
+      node.type === 'VariableDeclarator' &&
+      id?.type === 'Identifier' &&
+      namesSimctl(node.init as AstNode)
+    ) {
+      bindings.add(id.name);
+    }
+  });
+  return bindings;
+}
+
+function castsToBrand(node: AstNode): boolean {
+  if (node.type !== 'TSAsExpression' && node.type !== 'TSTypeAssertion') return false;
+  let names = false;
+  visitAst(node.typeAnnotation, (typeNode) => {
+    if (typeNode.type !== 'TSTypeReference') return;
+    const typeName = typeNode.typeName as AstNode;
     const name =
-      typeName?.type === 'TSQualifiedName' ? (typeName.right as AstNode).name : typeName?.name;
-    if (typeof name === 'string') names.add(name);
+      typeName.type === 'TSQualifiedName' ? (typeName.right as AstNode).name : typeName.name;
+    names ||= BRANDS.has(name as string);
   });
   return names;
 }
 
-function isStringLiteral(node: unknown, value: string): boolean {
-  return (
-    node !== null &&
-    typeof node === 'object' &&
-    (node as AstNode).type === 'Literal' &&
-    (node as AstNode).value === value
-  );
+function isLiteral(node: AstNode | undefined, value: string): boolean {
+  return node?.type === 'Literal' && node.value === value;
 }
 
-function lineAt(source: string, offset: number): number {
-  return source.slice(0, offset).split('\n').length;
+function lineAt(source: string, offset: unknown): number {
+  return source.slice(0, Number(offset ?? 0)).split('\n').length;
 }
diff --git a/scripts/layering/check.ts b/scripts/layering/check.ts
index bf09d3b43a..b3512b504f 100644
--- a/scripts/layering/check.ts
+++ b/scripts/layering/check.ts
@@ -40,9 +40,11 @@
 //     directly (R77) — the subtree sits in the eager closure of seven Apple façade entries the
 //     eager-closure-budgets gate holds at a fixed size, so a direct host-kit edge grows all seven;
 //     host-kit reaches the runner only through `runner/host.ts`, bound in `core/runner-host.ts`.
-//   - Over SIMCTL ARGV in production source: only `core/simctl.ts` (and the provider executors in
-//     `core/tool-provider.ts`) build, prefix or mint scoped simctl argv, and only the calls that
-//     name no device take set scope (R79), so a udid never runs outside the set that holds it.
+//   - Over SIMCTL ARGV in production source: `tsc` holds `runXcrun` and the Apple tool port to
+//     branded simctl argv. The plain executors take any string argv, so R79 refuses every array
+//     that names simctl first outside `core/simctl.ts` and `core/tool-provider.ts`, however it
+//     reaches an executor, holds an inline xcrun argv to a literal non-simctl tool name, and keeps
+//     brand casts inside those two modules, so a udid never runs outside the set that holds it.
 //   - Over REQUEST-BOUND RUNTIME EXECUTION: facts remain the only admission authority and daemon
 //     code cannot manufacture or repair a narrowed runtime proof (R66).
 //   - Over CONTRACTS PRODUCTION SOURCE: contracts owns vocabulary only — host, process, and timer
diff --git a/src/daemon/__tests__/request-platform-providers.test.ts b/src/daemon/__tests__/request-platform-providers.test.ts
index 693a2b7acb..61cafbc5b4 100644
--- a/src/daemon/__tests__/request-platform-providers.test.ts
+++ b/src/daemon/__tests__/request-platform-providers.test.ts
@@ -14,6 +14,7 @@ import {
 } from '../../__tests__/test-utils/session-factories.ts';
 import { withTestDeviceInventoryProvider as withTargetDeviceResolutionScope } from '../../__tests__/test-utils/device-inventory-gateways.ts';
 import { createLocalAppleToolProvider, runXcrun } from '@agent-device/platform-apple/tool-provider';
+import { buildSimctlArgsForDevice } from '@agent-device/platform-apple/simctl';
 import type { AndroidAdbExecutor } from '@agent-device/platform-android/mechanics';
 import { resolveWebProvider, type WebProvider } from '@agent-device/platform-web';
 import {
@@ -67,7 +68,7 @@ test('request platform provider scope applies Apple tool provider only for Apple
         },
       },
     },
-    async () => await runXcrun(['simctl', 'list', 'devices', '-j']),
+    async () => await runXcrun(buildSimctlArgsForDevice(IOS_SIMULATOR, ['list', 'devices', '-j'])),
   );
 
   assert.equal(result.stdout, 'simctl-ok');
@@ -104,7 +105,10 @@ test('request platform provider scope follows explicit apps selector for existin
             },
           },
         },
-        async () => await runXcrun(['simctl', 'listapps', OTHER_IOS_SIMULATOR.id]),
+        async () =>
+          await runXcrun(
+            buildSimctlArgsForDevice(OTHER_IOS_SIMULATOR, ['listapps', OTHER_IOS_SIMULATOR.id]),
+          ),
       ),
   );
 
@@ -207,7 +211,8 @@ test('request platform provider scopes stay isolated across concurrent requests'
           }),
       },
     },
-    async () => (await runXcrun(['simctl', 'list', 'devices', '-j'])).stdout,
+    async () =>
+      (await runXcrun(buildSimctlArgsForDevice(IOS_SIMULATOR, ['list', 'devices', '-j']))).stdout,
   );
 
   assert.deepEqual(await Promise.all([androidTask, appleTask]), ['android-ok', 'apple-ok']);
diff --git a/src/platform-runtime-apple-tool-host.test.ts b/src/platform-runtime-apple-tool-host.test.ts
index 0f59de4daa..39daddf034 100644
--- a/src/platform-runtime-apple-tool-host.test.ts
+++ b/src/platform-runtime-apple-tool-host.test.ts
@@ -4,6 +4,7 @@ import {
   type AppleToolProvider,
   withAppleToolProvider,
 } from '@agent-device/platform-apple/tool-provider';
+import type { ScopedSimctlArgs } from '@agent-device/contracts/platform-runtime-host';
 import { createAppleToolHost } from './platform-runtime-apple-tool-host.ts';
 
 test('Apple tool host uses a full scoped provider when local xcrun is unavailable', async () => {
@@ -42,6 +43,26 @@ test('Apple tool host uses a full scoped provider when local xcrun is unavailabl
   });
 });
 
+test('Apple tool host hands a simctl request to the simctl provider with its scoped args intact', async () => {
+  const run = vi.fn(async () => ({ stdout: 'booted', stderr: '', exitCode: 0 }));
+  const runCommand = vi.fn();
+  const provider = createLocalAppleToolProvider({ runCommand, simctl: { run } });
+  const args = Object.freeze(['--set', '/tmp/set', 'boot', 'sim-1']) as ScopedSimctlArgs;
+
+  await withAppleToolProvider(provider, async () => {
+    await expect(
+      createAppleToolHost().run({ tool: 'simctl', args, allowFailure: true }, undefined),
+    ).resolves.toEqual({ stdout: 'booted', stderr: '', exitCode: 0 });
+  });
+
+  expect(run).toHaveBeenCalledWith(['--set', '/tmp/set', 'boot', 'sim-1'], {
+    allowFailure: true,
+    signal: undefined,
+    timeoutMs: undefined,
+  });
+  expect(runCommand).not.toHaveBeenCalled();
+});
+
 test('Apple tool host rejects pre-aborted requests before invoking the provider', async () => {
   const reason = new Error('cancelled');
   const controller = new AbortController();
diff --git a/src/platform-runtime-apple-tool-host.ts b/src/platform-runtime-apple-tool-host.ts
index 5d013ef4b9..8acdaebd3c 100644
--- a/src/platform-runtime-apple-tool-host.ts
+++ b/src/platform-runtime-apple-tool-host.ts
@@ -15,17 +15,16 @@ export function createAppleToolHost(): AppleToolHost {
       return available;
     },
     run: async (request, signal) => {
-      const { runXcrun } = await awaitPreservingAbortReason(
+      const { resolveAppleToolProvider, runXcrun } = await awaitPreservingAbortReason(
         async () => await import('@agent-device/platform-apple/tool-provider'),
         signal,
       );
+      const options = { allowFailure: request.allowFailure, signal, timeoutMs: request.timeoutMs };
       const result = await awaitPreservingAbortReason(
         async () =>
-          await runXcrun([request.tool, ...request.args], {
-            allowFailure: request.allowFailure,
-            signal,
-            timeoutMs: request.timeoutMs,
-          }),
+          request.tool === 'simctl'
+            ? await resolveAppleToolProvider().simctl.run(request.args, options)
+            : await runXcrun([request.tool, ...request.args], options),
         signal,
       );
       return {
diff --git a/src/platform-runtime-device-inventory.test.ts b/src/platform-runtime-device-inventory.test.ts
index 95404b0e7c..f096122288 100644
--- a/src/platform-runtime-device-inventory.test.ts
+++ b/src/platform-runtime-device-inventory.test.ts
@@ -22,7 +22,10 @@ const simctl = vi.hoisted(() => ({
   calls: [] as string[],
 }));
 
-vi.mock('../packages/platform-apple/src/core/tool-provider.ts', () => ({
+vi.mock('../packages/platform-apple/src/core/tool-provider.ts', async (importOriginal) => ({
+  ...(await importOriginal<
+    typeof import('../packages/platform-apple/src/core/tool-provider.ts')
+  >()),
   runXcrun: async (args: string[]) => {
     const idx = args.indexOf('listapps');
     const deviceId = idx >= 0 ? args[idx + 1] : undefined;

From 2c7856d560c2f9948f1d7fe45aded6566ed46a31 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 24 Sep 2026 18:47:02 +0200
Subject: [PATCH 107/132] perf(ios): shorten smoke critical path with affected
 XCTest selection (#2896)

* perf(ios): reduce smoke critical path with affected XCTest selection

* chore(gates): enforce iOS XCTest impact selection coverage

* fix(ci): run bridge proof after macOS live replay

* chore(gates): guard macOS replay before bridge proof

* chore(gates): derive iOS XCTest selection from Swift guards and ownership

* chore(gates): resolve shallow PR impact and iOS screenshot coverage
---
 .../setup-apple-runner-build/action.yml       |   2 +-
 .github/workflows/ios.yml                     | 191 ++++--------------
 .github/workflows/macos.yml                   |  19 ++
 ...rTests+ApplicationStateRawValueTests.swift |   4 +-
 .../RunnerTests+LifecycleTests.swift          |   5 +
 docs/agents/testing.md                        |   2 +
 scripts/__tests__/apple-ci-impact.test.ts     | 156 ++++++++++++++
 scripts/__tests__/xctest-declarations.test.ts |  44 ++++
 scripts/__tests__/xctest-selection.test.ts    | 183 ++++++++++++-----
 scripts/apple-ci-impact.ts                    |  88 ++++++++
 scripts/check-affected/model.ts               |  14 +-
 scripts/check-xctest-selection.ts             | 174 ++++++++++++++--
 scripts/xctest-declarations.ts                | 108 ++++++++--
 .../replays/ios/simulator/01-settings.ad      |   3 -
 vitest.config.ts                              |   6 +-
 15 files changed, 747 insertions(+), 252 deletions(-)
 create mode 100644 scripts/__tests__/apple-ci-impact.test.ts
 create mode 100644 scripts/apple-ci-impact.ts

diff --git a/.github/actions/setup-apple-runner-build/action.yml b/.github/actions/setup-apple-runner-build/action.yml
index aad21ef883..c05ecd9326 100644
--- a/.github/actions/setup-apple-runner-build/action.yml
+++ b/.github/actions/setup-apple-runner-build/action.yml
@@ -44,7 +44,7 @@ runs:
       id: source-hash
       run: |
         set -euo pipefail
-        echo "value=${{ hashFiles('apple/runner/**', 'apple/snapshot-presentation/**', 'scripts/build-xcuitest-apple.sh', 'scripts/swift-toolchain-tmpdir.ts', 'scripts/patch-xcuitest-runner-icon.ts', 'scripts/write-xcuitest-cache-metadata.mjs', 'packages/platform-apple/src/runner/apple-runner-platform.ts', 'packages/platform-apple/src/runner/runner-cache-metadata.ts', 'packages/platform-apple/src/runner/runner-icon.ts', 'packages/platform-apple/src/runner/runner-xctestrun.ts', 'packages/platform-apple/src/runner/runner-xctestrun-products.ts', '.github/actions/setup-apple-runner-build/action.yml') }}" >> "$GITHUB_OUTPUT"
+        echo "value=${{ hashFiles('apple/runner/**', 'apple/snapshot-presentation/**', 'scripts/build-xcuitest-apple.sh', 'scripts/swift-toolchain-tmpdir.ts', 'scripts/patch-xcuitest-runner-icon.ts', 'scripts/write-xcuitest-cache-metadata.mjs', 'packages/platform-apple/src/runner/**', '!packages/platform-apple/src/runner/__tests__/**', '.github/actions/setup-apple-runner-build/action.yml') }}" >> "$GITHUB_OUTPUT"
       shell: bash
 
     - name: Resolve Apple runner build variant
diff --git a/.github/workflows/ios.yml b/.github/workflows/ios.yml
index 62c575390f..56e58d838e 100644
--- a/.github/workflows/ios.yml
+++ b/.github/workflows/ios.yml
@@ -97,6 +97,16 @@ jobs:
             pnpm-lock.yaml
             examples/test-app/pnpm-lock.yaml
 
+      - name: Select iOS runner XCTests
+        id: xctest-impact
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+        run: |
+          if [ "${{ github.event_name }}" = 'pull_request' ]; then
+            git fetch origin "$BASE_SHA" --depth=1 || echo 'Base fetch failed; XCTest selection will fail open.'
+          fi
+          node --experimental-strip-types scripts/apple-ci-impact.ts xctest
+
       - name: Establish host focus canary
         id: host-focus-canary
         run: |
@@ -125,151 +135,23 @@ jobs:
           runtime-version: ${{ env.IOS_RUNTIME_VERSION }}
           preferred-device-name: iPhone 17 Pro
 
-      - name: Verify clean-installed Simulator snapshot bridge preparation and the fold-helper -Werror gate
-        if: github.event_name == 'pull_request'
-        env:
-          BASE_SHA: ${{ github.event.pull_request.base.sha }}
-        run: |
-          git fetch origin "$BASE_SHA" --depth=1
-          if git diff --quiet "$BASE_SHA"...HEAD -- \
-            apple/snapshot-bridge \
-            apple/fold-helper \
-            packages/platform-apple/src/snapshot-source \
-            packages/platform-apple/src/foldable \
-            scripts/check-package.ts \
-            scripts/size-report-install.mjs \
-            scripts/size-report-package.mjs; then
-            echo "Snapshot bridge and fold-helper sources are unchanged; skipping preparation proof."
-            exit 0
-          fi
-          pnpm build
-          pnpm exec vitest run \
-            packages/platform-apple/src/snapshot-source/native-runtime.test.ts \
-            packages/platform-apple/src/foldable/fold-helper-cache.test.ts
-          pnpm check:package -- --verify-snapshot-bridge-preparation
-
       - name: Run targeted iOS runner XCTest regressions
+        id: ios-xctest
+        if: steps.xctest-impact.outputs.run != 'false'
         run: |
-          set -o pipefail
+          set -euo pipefail
           XCTESTRUN_PATH="$(find "$AGENT_DEVICE_IOS_RUNNER_DERIVED_PATH/Build/Products" -maxdepth 1 -name '*.xctestrun' -print -quit)"
           test -n "$XCTESTRUN_PATH"
+          IOS_PR_TEST_ARGS=()
+          IOS_PR_TEST_IDS="$(node --experimental-strip-types scripts/check-xctest-selection.ts --ios-pr-tests)"
+          while IFS= read -r test_id; do
+            IOS_PR_TEST_ARGS+=("-only-testing:$test_id")
+          done <<< "$IOS_PR_TEST_IDS"
+          test "${#IOS_PR_TEST_ARGS[@]}" -gt 0
           xcodebuild test-without-building \
             -xctestrun "$XCTESTRUN_PATH" \
             -destination "platform=iOS Simulator,id=${{ steps.ios-simulator.outputs.simulator-udid }}" \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testSinglePointerFlingFallsBackToXCTestCoordinateDragWhenPrivateSynthesisFails \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testSynthesizedSequenceTapFallsBackToXCTestCoordinateTapWhenAccessibilityIsUnavailable \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testRecordStartThrowsTheCaptureRefusalItReceived \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testAlertDispatchResolvesItsOwnModalWithoutCoordinateTapRoutingProbe \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testAlertResolutionCannotBypassRequestedDeadline \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testReadRefusesToLaunchANotRunningSessionApp \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testNonReadCommandStillLaunchesANotRunningSessionApp \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testTypeWithoutResolvedInputReturnsTypedFailureBeforeDispatchingText \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testBareTypeUsesTappedInputWhenSoftwareKeyboardIsHidden \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testHardwareKeyboardResponderConfirmsItsOwnKeyboardFocus \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testPenalizedCoordinateTapOnNonTextControlDoesNotAuthorizeBareType \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testBareDelayedTypeFailsWhenTappedInputDisappearsMidCommand \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testBareSubmitKeyUsesSynthesizedFirstResponderAfterHiddenKeyboardTap \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testBareSubmitKeyRefusesWhenPrivateSynthesisIsUnavailable \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testEmptyReplacementWithoutResolvableTargetFailsClosed \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testTextEntryTapWitnessIsBoundToTargetIdentity \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testCoordinateTapTextInputProbeSkipsPenalizedXCTestChannel \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testScrollViewportKeyboardClipMatchesGoldenParityTable \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testScrollViewportPolicyUsesParityTableConstants \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testScrollViewportDispatchKeepsTheUnclippedFrameAsItsCoordinateRotationBasis \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testSynthesizedGesturePoliciesMatchCommandContracts \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testFreshCoordinateTapContainsUnavailableTextInputProbe \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testTextInputProbeIssueScopeIsThreadBound \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testTextInputProbePreservesEnclosingRunnerWait \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testSuppressedAxIssueMakesTextInputProbeUnavailable \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testHealthyCoordinateTapPreservesBareTypingWitness \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testTextInputProbeContainmentExcludesRequiredReadsAndLaterIssues \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testCoordinateTextInputCandidateMustBeEnabledAndContainTheTouchPoint \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testQuerySelectorPrefersHittableMatchOverNonHittableDuplicate \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testActivateTargetSkipsForegroundAndActivatesNonForegroundApplication \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testApplicationStateRawValuesMatchTheActivationDecoder \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testMissingBundleCommandInvalidatesCompleteCachedTargetState \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testCachedTargetInvalidationClearsProcessBoundState \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testScreenshotDisplayFactsReEncodeEveryGoldenTableRowUnderTheTablesKey \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testScreenshotResultCarriesNoDisplayFactsWhenNothingResolved \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testAlertResolutionCannotBypassRequestedDeadline \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testAlertAcceptTreatsOpenAsAffirmative \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testAlertAcceptDoesNotActivateAReplacementWithASharedButton \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testAlertDismissDoesNotActivateAReplacementWithTheSameTitle \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testAlertCannotProveAnIdenticalReplacementAndDoesNotActivateIt \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testAlertDeadlineBeforeActivationLeavesTheOriginalUntouched \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testAlertHittableProbeCompletingAfterDeadlineLeavesTheOriginalUntouched \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testAlertActivationIgnoresAnAppThatNeverSettlesBeforeTheDeadline \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testAlertActivationDoesNotWaitOutANotificationBanner \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testAlertResolutionWithoutAnAlertDoesNotReadEveryElementOfTheScreen \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testAlertResolutionFindsADismissPopupMarkerOnACrowdedScreen \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testAlertResolutionFindsAWindowThatIsItselfTheDismissPopupMarker \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testSystemModalProbeSliceSharesAndClampsToPlanDeadline \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testDispatchRecoverySkipsBookkeepingWhileXCTestChannelOccupied \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testBoundedSystemModalProbeTimeoutRecoversThenReleasesOnDrain \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testBoundedSystemModalProbeTimeoutRecoversThenReleasesOnDrainForSnapshotRaw \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testSnapshotTraversalIdentityPreservesSameOriginNodesWithDifferentBounds \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testSnapshotPresentationPreservesCurrentWireShape \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testRegularPresentationKeepsNestedClipGeometryCumulative \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testRegularPresentationKeepsFramelessSemanticCarriersNonActionableAndNonClipping \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testRawPresentationKeepsReportedOffscreenAndFramelessFacts \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testFixedSeedRegularPresentationMaintainsCumulativeClipInvariant \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testPresentationFailureKeepsItsNamedSnapshotQualityReason \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testRegularPresentationPublishesEffectiveRectWhileRawKeepsReportedFrame \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testSnapshotPresentationOwnsBackendNeutralEligibility \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testSnapshotPresentationOwnsScopeAndRelativeDepth \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testPresentationRefusesAnAcquisitionCapturedForTheOtherProjection \
-             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testCaptureHintIsTheOnlyAcquisitionViewOfARequest \
-             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testRegularDepthCutsPresentationNotAcquisition \
-             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testVisibilityFoldKeepsIndependentChildPastClippedParent \
-             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testRegularDepthKeepsTurnedKeyboardSubtreeAfterOneNormalizationPass \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testRegularFoldClipsScrollOverflowReparentsAndBooksHints \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testRegularFoldKeepsWindowCarriersButNeverHittableOutsideClip \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testRegularFoldDropsSubPixelContentlessDecorationOnEveryBackend \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testPlainViewportPolicyFoldsWithoutAncestorCursor \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testPlainViewportPolicyDoesNotClipToScrollAncestor \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testEffectiveGeometryIntersectsViewportAndAncestorClip \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testEffectiveGeometryKeepsReportedOriginWhenFullyClipped \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testRegularPresentationRoutesThroughVisibilityFold \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testRegularPresentationPublishesGeometricActionabilityWithoutOcclusionOrTypeGate \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testSnapshotAcquisitionDoesNotReintroduceRunnerOcclusionScan \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testSnapshotScopePolicyMatchesGoldenParityTable \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testScrollContainerTypeNamesMatchElementTypeSet \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testPrivateAXDepthLimitedRequiresEveryFrontierResolved \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testDeepExtensionCountsMissedFrontiers \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testPreferredPrivateAXBackendPlansAsPenalized \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testPreferredTreeBackendPinsRegularPlanAndLeavesStructuredEvidence \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testRawDiagnosticPlanCarriesOnlyBackendsThatCanServeRaw \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testSnapshotBackendDeclarationsMatchCapabilityFixture \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testProjectionMismatchFailureIsStructuredAndNotAnAxFailure \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testPrivateAXRegularPresentationProjectsToViewportAndKeepsScrollHint \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testPrivateAXRawProjectionKeepsEveryAcquiredNode \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testPrivateAXRawProjectionAppliesRequestedTraversalDepth \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testPrivateAXPresentationKeepsOffscreenSubtreeExcludedWhenChildFramesAreClamped \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testPrivateAXGeometrylessSemanticsAreNeverActionableOrScrollContexts \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testPrivateAXAcquisitionDoesNotInterpretScope \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testPrivateAXInteractiveFiltersLoginLikeHiddenDrawer \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testDecodedPreferredBackendReachesOptionsAndApplicablePlan \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testSparsePayloadReasonMatrix \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testStampedPayloadTruncationTracksCompletenessNotRecoveryProvenance \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testRunnerScreenshotStabilitySettledNeedsEnoughSamples \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testRunnerScreenshotStabilitySettledTrueWhenWindowMatches \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testRunnerScreenshotStabilitySettledFalseOnMidWindowMismatch \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testRunnerScreenshotStabilitySettledFalseOnFailedCapture \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testRunnerScreenshotStabilitySettledOnlyLooksAtTheTrailingWindow \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testRunnerScreenshotStabilitySettledRejectsDegenerateRequirement \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testCustomActionsRequestPinsPrivateAXBackend \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testPrivateAXNodesCarryAnnotatedCustomActions \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testRequestPinnedBackendReportsItsOwnReason \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testCustomActionCoverageParsesOnlyCompletePairs \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testStampedPayloadCarriesDisclosuresOnlyInTheVerdict \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testActionNamesAreCappedPerElementAndReported \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testHungCustomActionReadIsContainedAndRecovers \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testAbandonedTreeCaptureSkipsQuerySweepAndHonorsWarmupExemption \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testNonInteractiveQuerySweepStopsAtTheSliceItsCallerWaitsFor \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testQuerySweepThatEndsOnItsSliceDeadlinePenalizesChannelAndReachesPrivateAX \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testCoordinateTapRoutingPenalizesTheIdentityMainSettledOnWhileTheWriteWasPending \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testBlockingModalSnapshotLeavesWarmupExemptionForTheFirstCapturePlan \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testPrivateAXPinnedRegularDepthReachesAcquisitionAndPresentation 2>&1 | tee /tmp/agent-device-runner-regressions.log
+            "${IOS_PR_TEST_ARGS[@]}" 2>&1 | tee /tmp/agent-device-runner-regressions.log
           node --input-type=module -e '
             import { readFileSync } from "node:fs";
             const log = readFileSync("/tmp/agent-device-runner-regressions.log", "utf8");
@@ -299,17 +181,6 @@ jobs:
         run: |
           echo "Fixture app source: ${{ steps.fixture-app.outputs.source }}" >> "$GITHUB_STEP_SUMMARY"
 
-      - name: Run fixture-backed iOS simulator E2E smoke
-        env:
-          AGENT_DEVICE_FIXTURE_APP_ID: ${{ steps.fixture-app.outputs.app-id }}
-          AGENT_DEVICE_FIXTURE_APP_PATH: ${{ steps.fixture-app.outputs.app-path }}
-          AGENT_DEVICE_IOS_E2E: '1'
-          AGENT_DEVICE_IOS_E2E_TIER: smoke
-          AGENT_DEVICE_IOS_UDID: ${{ steps.ios-simulator.outputs.simulator-udid }}
-        run: |
-          pnpm gate build
-          node --experimental-strip-types scripts/node-test-tmpdir.ts --test test/integration/smoke-ios-simulator-coverage.test.ts test/integration/smoke-ios-simulator.test.ts
-
       # #1584: isolated, cheap automatic guard for the #1562 class of regression (iOS silently
       # ignoring a `gesture pan` duration). Split out of gesture-lab.ad, which stays full-tier
       # (dispatch-only via replays-manual.yml) because its multi-touch commands are a separate,
@@ -324,6 +195,17 @@ jobs:
           node --experimental-strip-types src/bin.ts test examples/test-app/replays/gesture-pan-duration.ad --udid "${{ steps.ios-simulator.outputs.simulator-udid }}" --timeout 180000 --retries 2 --artifacts-dir test/artifacts/replays-ios-gesture-pan-duration --report-junit test/artifacts/replays-ios-gesture-pan-duration.junit.xml
           pnpm clean:daemon
 
+      - name: Run fixture-backed iOS simulator E2E smoke
+        env:
+          AGENT_DEVICE_FIXTURE_APP_ID: ${{ steps.fixture-app.outputs.app-id }}
+          AGENT_DEVICE_FIXTURE_APP_PATH: ${{ steps.fixture-app.outputs.app-path }}
+          AGENT_DEVICE_IOS_E2E: '1'
+          AGENT_DEVICE_IOS_E2E_TIER: smoke
+          AGENT_DEVICE_IOS_UDID: ${{ steps.ios-simulator.outputs.simulator-udid }}
+        run: |
+          pnpm gate build
+          node --experimental-strip-types scripts/node-test-tmpdir.ts --test test/integration/smoke-ios-simulator-coverage.test.ts test/integration/smoke-ios-simulator.test.ts
+
       - name: Assert simulator automation preserved host focus
         if: ${{ always() }}
         run: |
@@ -340,6 +222,17 @@ jobs:
           pnpm clean:daemon
           node --experimental-strip-types src/bin.ts test test/integration/replays/ios/device/01-physical-lifecycle.ad --udid "$IOS_UDID" --retries 2 --artifacts-dir test/artifacts/replays-ios-device-smoke --report-junit test/artifacts/replays-ios-device-smoke.junit.xml
 
+      - name: Assert iOS XCTest selection was honored
+        if: always()
+        env:
+          SELECTED: ${{ steps.xctest-impact.outputs.run }}
+          OUTCOME: ${{ steps.ios-xctest.outcome }}
+        run: |
+          if [ "$SELECTED" = 'true' ] && [ "$OUTCOME" = 'skipped' ]; then
+            echo '::error::iOS runner XCTest was selected but its step was skipped.'
+            exit 1
+          fi
+
       - name: Upload iOS artifacts
         if: always()
         uses: ./.github/actions/upload-agent-device-artifacts
diff --git a/.github/workflows/macos.yml b/.github/workflows/macos.yml
index df86714a2b..8093217e6c 100644
--- a/.github/workflows/macos.yml
+++ b/.github/workflows/macos.yml
@@ -151,6 +151,25 @@ jobs:
             --report-junit
             test/artifacts/replays-macos.junit.xml
 
+      # Clean-install verification may raise macOS local-network permission UI; keep it after replay.
+      - name: Select Apple bridge proof
+        if: github.event_name == 'pull_request'
+        id: bridge-impact
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+        run: |
+          git fetch origin "$BASE_SHA" --depth=1 || echo 'Base fetch failed; bridge proof selection will fail open.'
+          node --experimental-strip-types scripts/apple-ci-impact.ts bridge
+
+      - name: Verify clean-installed Simulator snapshot bridge preparation and the fold-helper -Werror gate
+        if: github.event_name == 'pull_request' && steps.bridge-impact.outputs.run != 'false'
+        run: |
+          pnpm build
+          pnpm exec vitest run \
+            packages/platform-apple/src/snapshot-source/native-runtime.test.ts \
+            packages/platform-apple/src/foldable/fold-helper-cache.test.ts
+          pnpm check:package -- --verify-snapshot-bridge-preparation
+
       - name: Upload macOS artifacts
         if: always()
         uses: ./.github/actions/upload-agent-device-artifacts
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+ApplicationStateRawValueTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+ApplicationStateRawValueTests.swift
index 02375b2a99..84c8f2b472 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+ApplicationStateRawValueTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+ApplicationStateRawValueTests.swift
@@ -7,8 +7,8 @@ extension RunnerTests {
   /// against a second handwritten table: the decoder maps the integer the runner stamps, and #2726
   /// shipped `runningBackground` and `runningBackgroundSuspended` reversed.
   ///
-  /// The host lane runs this on every PR, and `.github/workflows/ios.yml` lists it for the simulator
-  /// lane so the suspended case — compiled out of the macOS build below — is pinned on every PR too.
+  /// The host lane runs this on every PR; the simulator lane derives it from the platform branch
+  /// below so the suspended case, compiled out of the macOS build, is pinned on every PR too.
   /// `packages/platform-apple/src/runner/__tests__/target-activation.test.ts` reads these calls back
   /// and compares them with its decode table, so a table that drifts from them fails on any host
   /// instead of waiting for a lane to report a mislabelled repair.
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+LifecycleTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+LifecycleTests.swift
index a4e75fe198..352cdbce1c 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+LifecycleTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+LifecycleTests.swift
@@ -97,6 +97,11 @@ extension RunnerTests {
     // into the runner's temporary directory.
     let fileName = URL(fileURLWithPath: message).lastPathComponent
     XCTAssertTrue(message.hasSuffix(fileName), message)
+#if os(iOS)
+    XCTAssertTrue(message.hasPrefix("tmp/"), message)
+#elseif os(macOS)
+    XCTAssertTrue(message.hasPrefix("/"), message)
+#endif
     let storedPath = (NSTemporaryDirectory() as NSString).appendingPathComponent(fileName)
     XCTAssertEqual(try Data(contentsOf: URL(fileURLWithPath: storedPath)), pngData)
     XCTAssertEqual(response.data?.screenshotMetadata?.pixelsPerPoint, 3)
diff --git a/docs/agents/testing.md b/docs/agents/testing.md
index b3b5318ccf..f0dbb77db8 100644
--- a/docs/agents/testing.md
+++ b/docs/agents/testing.md
@@ -45,6 +45,8 @@ provider, and coverage tests mock the typed HDC seam. Real validation is local h
 Apple runner changes run `pnpm check:xctest-selection` and build the affected target. The source
 `#if` guard is the XCTest lane classification — never maintain a second test-name list. Pure runner
 decisions use the macOS host lane; iOS/XCTest semantics need a simulator lane.
+The iOS PR lane derives platform-specific XCTests from Swift guards for runner changes;
+nightly runs the full suite.
 
 Local host-lane XCTest may need signing and automation permission:
 
diff --git a/scripts/__tests__/apple-ci-impact.test.ts b/scripts/__tests__/apple-ci-impact.test.ts
new file mode 100644
index 0000000000..ea0834195d
--- /dev/null
+++ b/scripts/__tests__/apple-ci-impact.test.ts
@@ -0,0 +1,156 @@
+import fs from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import os from 'node:os';
+import path from 'node:path';
+import { expect, test } from 'vitest';
+import { parse } from 'yaml';
+import { selectAppleBridgeProof, selectIosXctests } from '../apple-ci-impact.ts';
+import { selectChecks } from '../check-affected/model.ts';
+
+const repoRoot = path.resolve(import.meta.dirname, '../..');
+
+function cacheInputs(action: string): string[] {
+  const doc = parse(action) as { runs?: { steps?: Array<{ id?: string; run?: string }> } };
+  const sourceHash = doc.runs?.steps?.find((step) => step.id === 'source-hash')?.run ?? '';
+  const expressions = [...sourceHash.matchAll(/hashFiles\(([\s\S]*?)\)/g)];
+  expect(expressions.length).toBeGreaterThan(0);
+  return expressions.flatMap((expression) =>
+    [...expression[1]!.matchAll(/'([^']+)'/g)].map((match) => match[1]!),
+  );
+}
+
+test('every runner build-cache input triggers the PR XCTest lane', () => {
+  const action = fs.readFileSync(
+    path.join(repoRoot, '.github/actions/setup-apple-runner-build/action.yml'),
+    'utf8',
+  );
+  expect(cacheInputs(action)).toContain('packages/platform-apple/src/runner/**');
+  expect(cacheInputs(action)).toContain('!packages/platform-apple/src/runner/__tests__/**');
+  const uncovered = (text: string) =>
+    cacheInputs(text)
+      .filter((input) => !input.startsWith('!'))
+      .filter((input) => {
+        const path = input.replace(/\*\*?$/, 'probe.ts');
+        const plan = selectChecks({ changedFiles: [path] });
+        return !plan.failOpen && !plan.checks.includes('swift-runner-ios');
+      });
+  expect(uncovered(action)).toEqual([]);
+  expect(
+    uncovered(action.replace('apple/runner/**', 'packages/platform-apple/src/snapshot-source/**')),
+  ).toEqual(['packages/platform-apple/src/snapshot-source/**']);
+  expect(
+    uncovered(
+      action.replace(
+        'hashFiles(',
+        "hashFiles('packages/platform-apple/src/foldable/**',\n          ",
+      ),
+    ),
+  ).toEqual(['packages/platform-apple/src/foldable/**']);
+});
+
+test('the PR workflow applies the impact decision to the XCTest step', () => {
+  const workflow = fs.readFileSync(path.join(repoRoot, '.github/workflows/ios.yml'), 'utf8');
+  expect(workflow).toContain('node --experimental-strip-types scripts/apple-ci-impact.ts xctest');
+  expect(workflow).toMatch(
+    /- name: Run targeted iOS runner XCTest regressions\n\s+id: ios-xctest\n\s+if: steps\.xctest-impact\.outputs\.run != 'false'/,
+  );
+  expect(workflow).toContain('if [ "$SELECTED" = \'true\' ] && [ "$OUTCOME" = \'skipped\' ]');
+});
+
+test('macOS clean-install proof follows live UI replay', () => {
+  const workflow = fs.readFileSync(path.join(repoRoot, '.github/workflows/macos.yml'), 'utf8');
+  const replay = workflow.indexOf('- name: Run macOS integration test');
+  const proof = workflow.indexOf(
+    '- name: Verify clean-installed Simulator snapshot bridge preparation',
+  );
+  expect(replay).toBeGreaterThan(-1);
+  expect(proof).toBeGreaterThan(replay);
+  expect(workflow).toContain('node --experimental-strip-types scripts/apple-ci-impact.ts bridge');
+  expect(workflow).toContain("steps.bridge-impact.outputs.run != 'false'");
+});
+
+test('native runner and golden-table changes run XCTest; TypeScript runtime changes use live E2E', () => {
+  for (const file of [
+    'apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift',
+    'apple/snapshot-presentation/Sources/Presenter.swift',
+    'packages/platform-apple/src/runner/runner-icon.ts',
+    'contracts/fixtures/scroll-gesture.json',
+    '.github/workflows/ios.yml',
+    'scripts/apple-ci-impact.ts',
+  ]) {
+    expect(selectIosXctests('pull_request', [file]).run, file).toBe(true);
+  }
+  for (const file of [
+    'packages/platform-apple/src/snapshot-source/cache.ts',
+    'packages/platform-apple/src/runner/__tests__/runner-icon.test.ts',
+    'apple/fold-helper/fold-helper.c',
+    'test/integration/ios-simulator-e2e/live-runner.ts',
+  ]) {
+    expect(selectIosXctests('pull_request', [file]), file).toMatchObject({ run: false });
+  }
+});
+
+test('pushes and uncertain diffs keep the full XCTest selection', () => {
+  expect(selectIosXctests('push', ['src/index.ts']).run).toBe(true);
+  expect(selectIosXctests('pull_request', null).run).toBe(true);
+  expect(selectIosXctests('pull_request', []).run).toBe(true);
+  expect(selectIosXctests('pull_request', ['src/index.ts', 'package.json']).run).toBe(true);
+});
+
+test('bridge proof runs for its owning sources and uncertain tooling changes', () => {
+  for (const file of [
+    'apple/snapshot-bridge/Bridge.c',
+    'apple/fold-helper/Helper.c',
+    'apple/new-native-module/Source.m',
+    'packages/platform-apple/src/snapshot-source/native-runtime.ts',
+    'packages/platform-apple/src/foldable/fold-helper-cache.ts',
+    'packages/platform-apple/src/new-module/runtime.ts',
+    'scripts/check-package.ts',
+    '.github/workflows/macos.yml',
+  ]) {
+    expect(selectAppleBridgeProof([file]).run, file).toBe(true);
+  }
+  expect(selectAppleBridgeProof(['src/index.ts']).run).toBe(false);
+  expect(selectAppleBridgeProof(null).run).toBe(true);
+  expect(selectAppleBridgeProof([]).run).toBe(true);
+});
+
+test('a shallow PR merge still yields a known change set for both selectors', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'apple-ci-impact-'));
+  const source = path.join(root, 'source');
+  const shallow = path.join(root, 'shallow');
+  fs.mkdirSync(source);
+  const git = (cwd: string, ...args: string[]) =>
+    execFileSync('git', args, { cwd, encoding: 'utf8' }).trim();
+  try {
+    git(source, 'init', '-q', '-b', 'main');
+    git(source, 'config', 'user.email', 'test@example.com');
+    git(source, 'config', 'user.name', 'Test');
+    git(source, 'commit', '--allow-empty', '-qm', 'base');
+    const base = git(source, 'rev-parse', 'HEAD');
+    git(source, 'checkout', '-qb', 'feature');
+    fs.mkdirSync(path.join(source, 'src'));
+    fs.writeFileSync(path.join(source, 'src', 'feature.ts'), 'export const feature = true;\n');
+    git(source, 'add', '.');
+    git(source, 'commit', '-qm', 'feature');
+    git(source, 'checkout', '-q', 'main');
+    git(source, 'merge', '-q', '--no-ff', '-m', 'merge', 'feature');
+    git(root, 'clone', '-q', '--depth=1', '--branch', 'main', `file://${source}`, shallow);
+    git(shallow, 'fetch', '-q', 'origin', base, '--depth=1');
+    expect(git(shallow, 'rev-parse', '--is-shallow-repository')).toBe('true');
+    const select = (target: string) =>
+      execFileSync(
+        process.execPath,
+        ['--experimental-strip-types', path.join(repoRoot, 'scripts/apple-ci-impact.ts'), target],
+        {
+          cwd: shallow,
+          encoding: 'utf8',
+          env: { ...process.env, BASE_SHA: base, GITHUB_EVENT_NAME: 'pull_request' },
+        },
+      );
+    expect(select('xctest')).toContain('skip;');
+    expect(select('bridge')).toContain('skip;');
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
diff --git a/scripts/__tests__/xctest-declarations.test.ts b/scripts/__tests__/xctest-declarations.test.ts
index 70edbdd68b..e1f77fab14 100644
--- a/scripts/__tests__/xctest-declarations.test.ts
+++ b/scripts/__tests__/xctest-declarations.test.ts
@@ -67,6 +67,50 @@ describe('the declaration scan', () => {
     ).toEqual([`${TARGET}/RunnerTests/testGolden`]);
   });
 
+  test('discovers tests in indented extensions and new files without a name list', () => {
+    expect(
+      parseDeclaredTests(TARGET, [
+        {
+          file: 'UnitTests/NewScreenCaptureTests.swift',
+          text:
+            '#if os(iOS)\n' +
+            '  extension RunnerTests {\n' +
+            '    func testObservedScreenCapture() {}\n' +
+            '  }\n' +
+            '#endif\n',
+        },
+        {
+          file: 'NewTests.swift',
+          text: '    extension RunnerTests {\n        func testAnotherIndent() {}\n    }\n',
+        },
+      ]),
+    ).toEqual([
+      `${TARGET}/RunnerTests/testAnotherIndent`,
+      `${TARGET}/RunnerTests/testObservedScreenCapture`,
+    ]);
+  });
+
+  test('fails closed when a test-shaped declaration cannot be classified', () => {
+    expect(() => parseDeclaredTests(TARGET, source('func testOutsideAType() {}\n'))).toThrow(
+      'RunnerTests+Fixture.swift:1: unrecognized XCTest declaration',
+    );
+    expect(() =>
+      parseDeclaredTests(
+        TARGET,
+        source('extension RunnerTests {\n  func testGeneric<T>() {}\n}\n'),
+      ),
+    ).toThrow('RunnerTests+Fixture.swift:2: unrecognized XCTest declaration');
+    expect(() =>
+      parseDeclaredTests(TARGET, source('extension RunnerTests { func testInline() {} }\n')),
+    ).toThrow('RunnerTests+Fixture.swift:1: unrecognized XCTest declaration');
+    expect(() =>
+      parseDeclaredTests(
+        TARGET,
+        source('extension RunnerTests {\n  @available(iOS 17, *) func testAttributed() {}\n}\n'),
+      ),
+    ).toThrow('RunnerTests+Fixture.swift:2: unrecognized XCTest declaration');
+  });
+
   test('attributes each declared method to the platforms that compile it', () => {
     expect(
       parseDeclaredTestsByPlatform(
diff --git a/scripts/__tests__/xctest-selection.test.ts b/scripts/__tests__/xctest-selection.test.ts
index 20f282fdea..af59b84761 100644
--- a/scripts/__tests__/xctest-selection.test.ts
+++ b/scripts/__tests__/xctest-selection.test.ts
@@ -1,8 +1,8 @@
 // The check that keeps the runner XCTest lanes honest is itself only as good as its
 // parsers, and all of its inputs are files nobody edits with this check in mind. So: the
-// real tree must pass, a planted typo in the real workflow text must fail — in both flag
-// directions, because an unknown `-skip-testing:` entry re-arms a whole-bundle lane's
-// 24-hour hang on `RunnerTests/testCommand` — and a planted guard that compiles a test out
+// real tree must pass, a broken generated PR selector and a planted typo in a whole-bundle
+// `-skip-testing:` flag must fail (the latter re-arms the 24-hour `testCommand` hang), and a
+// planted guard that compiles a test out
 // of every lane must fail as "dark". Synthetic sources cover the shapes the real tree
 // happens not to contain today.
 
@@ -17,6 +17,7 @@ import {
   formatSummary,
   GUARDED_WORKFLOWS,
   HOST_WORKFLOW_FILE,
+  iosPrTestIdentifiers,
   LANES,
   loadReport,
   NIGHTLY_WORKFLOW_FILE,
@@ -48,12 +49,18 @@ function realSources() {
   return readSwiftSources(path.join(repoRoot, RUNNER_TESTS_DIR));
 }
 
-/** Workflow texts that skip the entry point on both whole-bundle lanes and list `pr` on the PR lane. */
-function laneWorkflows(pr: readonly string[] = []): WorkflowSource[] {
+/** Workflow texts that skip the entry point and consume the guard-derived PR selection. */
+function laneWorkflows(): WorkflowSource[] {
   return [
     { workflow: HOST_WORKFLOW_FILE, text: `-skip-testing:${ENTRY_POINT}` },
     { workflow: NIGHTLY_WORKFLOW_FILE, text: `-skip-testing:${ENTRY_POINT}` },
-    { workflow: PR_WORKFLOW_FILE, text: pr.map((id) => `-only-testing:${id}`).join('\n') },
+    {
+      workflow: PR_WORKFLOW_FILE,
+      text:
+        'node --experimental-strip-types scripts/check-xctest-selection.ts --ios-pr-tests\n' +
+        'IOS_PR_TEST_ARGS+=("-only-testing:$test_id")\n' +
+        'xcodebuild "${IOS_PR_TEST_ARGS[@]}"',
+    },
   ];
 }
 
@@ -69,8 +76,9 @@ describe('the real tree', () => {
     const { declared, host, pr, nightly, dark } = counts(report);
     // Not pinned to today's exact numbers; the invariants are the shape. The host lane
     // (macOS) and the nightly (iOS) both skip only the entry point, so together with the
-    // simulator-only guard they cover everything else; the PR list is a proper subset of
-    // the nightly; and the entry point is the only method outside every lane.
+    // simulator-only guard they cover everything else; the PR lane runs iOS-only methods
+    // and shared methods with platform-dependent bodies. The entry point is the only method
+    // outside every lane.
     expect(host).toBeGreaterThan(0);
     expect(nightly).toBeGreaterThan(pr);
     expect(pr).toBeGreaterThan(0);
@@ -79,6 +87,19 @@ describe('the real tree', () => {
     expect(reachedAnywhere.size).toBe(declared - 1);
     expect(reachedAnywhere.has(ENTRY_POINT)).toBe(false);
     for (const id of report.reach.pr) expect(report.reach.nightly.has(id)).toBe(true);
+    expect(iosPrTestIdentifiers(report.declaredTests, report.sharedPlatformBranchIds)).toEqual([
+      ...report.reach.pr,
+    ]);
+    expect(
+      report.reach.pr.has(
+        `${TARGET}/RunnerTests/testSnapshotTraversalIdentityPreservesSameOriginNodesWithDifferentBounds`,
+      ),
+    ).toBe(true);
+    expect(
+      report.reach.pr.has(
+        `${TARGET}/RunnerTests/testApplicationStateRawValuesMatchTheActivationDecoder`,
+      ),
+    ).toBe(true);
   });
 
   test('the whole-bundle lanes skip the runner server entry point, which is not a test', () => {
@@ -110,7 +131,8 @@ describe('the real tree', () => {
 
   test('the declared set covers every addressable method in the target directory', () => {
     // Derived independently of the check: the directory is globbed here, with this test's
-    // own regex, because the Xcode project uses a PBXFileSystemSynchronizedRootGroup — every
+    // own loose declaration count, because the Xcode project uses a
+    // PBXFileSystemSynchronizedRootGroup — every
     // .swift file in it is a member. Reusing the check's own file filter would make this
     // tautological, and a name-based filter is exactly the bug it caught
     // (RunnerTapPointPolicy.swift declared a test and does not start with "RunnerTests").
@@ -121,7 +143,9 @@ describe('the real tree', () => {
         if (entry.isDirectory()) return total + countAddressableMethods(entryPath);
         if (!entry.isFile() || !entry.name.endsWith('.swift')) return total;
         const text = fs.readFileSync(entryPath, 'utf8');
-        return total + (text.match(/^ {2}(?:[\w@]+ )*func test/gm)?.length ?? 0);
+        return (
+          total + (text.match(/^[ \t]*(?:[\w@]+[ \t]+)*func[ \t]+test\w*[ \t]*\(/gm)?.length ?? 0)
+        );
       }, 0);
     const counted = countAddressableMethods(directory);
 
@@ -164,24 +188,36 @@ describe('the real tree', () => {
 });
 
 describe('a planted typo', () => {
-  test('a renamed test in the PR `-only-testing:` list is reported with its line', () => {
-    const workflow = fs.readFileSync(path.join(repoRoot, PR_WORKFLOW_FILE), 'utf8');
-    const first = parseFlaggedTests(PR_WORKFLOW_FILE, workflow).find(
-      (entry) => entry.flag === 'only-testing',
+  test('a disconnected PR selector fails the workflow wiring check', () => {
+    const workflow = laneWorkflows().find((entry) => entry.workflow === PR_WORKFLOW_FILE);
+    if (!workflow?.text) throw new Error('Missing synthetic PR workflow');
+    const report = buildReport(
+      TARGET,
+      source(
+        `${ENTRY_SOURCE}#if os(iOS)\nextension RunnerTests {\n  func testIosOnly() {}\n}\n#endif\n`,
+      ),
+      laneWorkflows().map((entry) =>
+        entry.workflow === PR_WORKFLOW_FILE
+          ? { ...entry, text: workflow.text?.replace('--ios-pr-tests', '--wrong-mode') ?? null }
+          : entry,
+      ),
     );
-    if (!first) throw new Error('ios.yml has no -only-testing entries to plant a typo in');
-    const typo = `${first.identifier}Renamed`;
+    expect(reportFailures(report).join('\n')).toContain('does not invoke');
+  });
 
+  test('a handwritten PR identifier cannot silently narrow the generated selection', () => {
     const report = buildReport(
       TARGET,
-      realSources(),
-      realWorkflows({ [PR_WORKFLOW_FILE]: workflow.replace(first.identifier, typo) }),
+      source(
+        `${ENTRY_SOURCE}#if os(iOS)\nextension RunnerTests {\n  func testIosOnly() {}\n}\n#endif\n`,
+      ),
+      laneWorkflows().map((entry) =>
+        entry.workflow === PR_WORKFLOW_FILE
+          ? { ...entry, text: `${entry.text}\n-only-testing:${TARGET}/RunnerTests/testIosOnly` }
+          : entry,
+      ),
     );
-
-    expect(report.unknown).toEqual([
-      { workflow: PR_WORKFLOW_FILE, flag: 'only-testing', identifier: typo, line: first.line },
-    ]);
-    expect(reportFailures(report).join('\n')).toContain(typo);
+    expect(reportFailures(report).join('\n')).toContain('hand-maintained XCTest selection');
   });
 
   test.each([
@@ -209,38 +245,77 @@ describe('a planted typo', () => {
     },
   );
 
-  test('a deleted test is reported even though the surviving list still passes', () => {
-    const kept = `${ENTRY_SOURCE}extension RunnerTests {\n  func testKept() {}\n}\n`;
-    const workflows = laneWorkflows([
-      `${TARGET}/RunnerTests/testKept`,
-      `${TARGET}/RunnerTests/testGone`,
-    ]);
-
+  test('adding or removing an iOS-only method changes the PR selection automatically', () => {
+    const iosMethod = '#if os(iOS)\nextension RunnerTests {\n  func testIosOnly() {}\n}\n#endif\n';
+    const id = `${TARGET}/RunnerTests/testIosOnly`;
     expect(
-      buildReport(
+      buildReport(TARGET, source(`${ENTRY_SOURCE}${iosMethod}`), laneWorkflows()).reach.pr.has(id),
+    ).toBe(true);
+    expect(buildReport(TARGET, source(ENTRY_SOURCE), laneWorkflows()).reach.pr.has(id)).toBe(false);
+  });
+
+  test.each(['os(iOS)', 'canImport(UIKit)', 'targetEnvironment(simulator)'])(
+    'a shared method with an in-body %s branch enters the generated PR selection',
+    (condition) => {
+      const report = buildReport(
         TARGET,
-        source(`${kept}extension RunnerTests {\n  func testGone() {}\n}\n`),
-        workflows,
-      ).unknown,
-    ).toEqual([]);
-    expect(
-      buildReport(TARGET, source(kept), workflows).unknown.map((entry) => entry.identifier),
-    ).toEqual([`${TARGET}/RunnerTests/testGone`]);
+        source(
+          `${ENTRY_SOURCE}extension RunnerTests {\n  func testSharedBranch() {\n#if ${condition}\n    XCTAssertTrue(true)\n#else\n    XCTAssertFalse(true)\n#endif\n  }\n}\n`,
+        ),
+        laneWorkflows(),
+      );
+      const id = `${TARGET}/RunnerTests/testSharedBranch`;
+      expect(report.declaredTests.find((test) => test.identifier === id)?.platforms).toEqual([
+        'iOS',
+        'macOS',
+        'tvOS',
+      ]);
+      expect(report.sharedPlatformBranchIds).toEqual([id]);
+      expect(report.reach.pr.has(id)).toBe(true);
+      expect(reportFailures(report)).toEqual([]);
+    },
+  );
+
+  test('a platform-neutral in-body compile flag does not duplicate a host test', () => {
+    const report = buildReport(
+      TARGET,
+      source(
+        `${ENTRY_SOURCE}extension RunnerTests {\n  func testSharedDebug() {\n#if DEBUG\n    XCTAssertTrue(true)\n#endif\n  }\n}\n`,
+      ),
+      laneWorkflows(),
+    );
+    expect(report.sharedPlatformBranchIds).toEqual([]);
+    expect(report.reach.pr.has(`${TARGET}/RunnerTests/testSharedDebug`)).toBe(false);
+  });
+
+  test('ambiguous shared method names fail closed instead of losing platform branches', () => {
+    const report = buildReport(
+      TARGET,
+      source(
+        `${ENTRY_SOURCE}extension RunnerTests {\n  func testSameName() {}\n}\nfinal class OtherTests: XCTestCase {\n  func testSameName() {}\n}\n`,
+      ),
+      laneWorkflows(),
+    );
+    expect(reportFailures(report).join('\n')).toContain(
+      'ambiguous shared XCTest method testSameName',
+    );
   });
 
-  test('a listed test the PR lane platform never compiles is reported, not silently unmatched', () => {
-    // Declared, so the rename check passes — but ios.yml builds for iOS, and an
-    // `os(macOS)` guard means the identifier matches nothing there.
+  test('a skip flag naming a test that its lane cannot compile is reported', () => {
     const report = buildReport(
       TARGET,
       source(
-        `${ENTRY_SOURCE}extension RunnerTests {\n#if os(macOS)\n  func testHostOnly() {}\n#endif\n}\n`,
+        `${ENTRY_SOURCE}#if os(iOS)\nextension RunnerTests {\n  func testIosOnly() {}\n}\n#endif\n`,
+      ),
+      laneWorkflows().map((entry) =>
+        entry.workflow === HOST_WORKFLOW_FILE
+          ? { ...entry, text: `${entry.text}\n-skip-testing:${TARGET}/RunnerTests/testIosOnly` }
+          : entry,
       ),
-      laneWorkflows([`${TARGET}/RunnerTests/testHostOnly`]),
     );
     expect(report.unknown).toEqual([]);
     expect(report.uncompiled.map((entry) => entry.identifier)).toEqual([
-      `${TARGET}/RunnerTests/testHostOnly`,
+      `${TARGET}/RunnerTests/testIosOnly`,
     ]);
     expect(reportFailures(report).join('\n')).toContain('never compiles');
   });
@@ -276,7 +351,7 @@ describe('a planted guard', () => {
     const id = `${TARGET}/RunnerTests/testLaunchesApp`;
     expect(report.reach.host.has(id)).toBe(false);
     expect(report.reach.nightly.has(id)).toBe(true);
-    expect(report.reach.pr.has(id)).toBe(false);
+    expect(report.reach.pr.has(id)).toBe(true);
     expect(reportFailures(report)).toEqual([]);
   });
 
@@ -284,15 +359,19 @@ describe('a planted guard', () => {
     const report = buildReport(TARGET, source(ENTRY_SOURCE), [
       { workflow: HOST_WORKFLOW_FILE, text: 'run: xcodebuild test-without-building' },
       { workflow: NIGHTLY_WORKFLOW_FILE, text: `-skip-testing:${ENTRY_POINT}` },
-      { workflow: PR_WORKFLOW_FILE, text: `-only-testing:${TARGET}/RunnerTests/testOther` },
+      laneWorkflows().find((entry) => entry.workflow === PR_WORKFLOW_FILE)!,
     ]);
     expect(report.entryPointReachedBy).toEqual(['host']);
     expect(reportFailures(report).join('\n')).toContain('reachable by lane(s): host');
   });
 
-  test('the PR list naming the entry point is reported too', () => {
-    const report = buildReport(TARGET, source(ENTRY_SOURCE), laneWorkflows([ENTRY_POINT]));
-    expect(report.entryPointReachedBy).toEqual(['pr']);
+  test('the generated PR selection excludes the entry point even under an iOS-only guard', () => {
+    const report = buildReport(
+      TARGET,
+      source(`#if os(iOS)\n${ENTRY_SOURCE}#endif\n`),
+      laneWorkflows(),
+    );
+    expect(report.reach.pr.has(ENTRY_POINT)).toBe(false);
   });
 });
 
@@ -386,9 +465,7 @@ describe('the blind-parse guards', () => {
 
   test('a guarded workflow that no longer exists fails instead of leaving a stale claim', () => {
     const report = buildReport(TARGET, oneTest(), [
-      ...laneWorkflows([`${TARGET}/RunnerTests/testOne`]).filter(
-        (entry) => entry.workflow !== NIGHTLY_WORKFLOW_FILE,
-      ),
+      ...laneWorkflows().filter((entry) => entry.workflow !== NIGHTLY_WORKFLOW_FILE),
       { workflow: NIGHTLY_WORKFLOW_FILE, text: null },
     ]);
     expect(reportFailures(report).join('\n')).toContain(NIGHTLY_WORKFLOW_FILE);
@@ -411,7 +488,7 @@ describe('the summary line', () => {
     const { declared, host, pr, nightly, dark } = counts(report);
     const summary = formatSummary(report);
     expect(summary).toContain(`${declared} declared`);
-    expect(summary).toContain(`reaches ${host}, PR list`);
+    expect(summary).toContain(`reaches ${host}, PR iOS-specific lane`);
     expect(summary).toContain(`selects ${pr}, nightly`);
     expect(summary).toContain(`reaches ${nightly};`);
     expect(summary).toContain(`${dark} reachable by no lane`);
diff --git a/scripts/apple-ci-impact.ts b/scripts/apple-ci-impact.ts
new file mode 100644
index 0000000000..e696acdd83
--- /dev/null
+++ b/scripts/apple-ci-impact.ts
@@ -0,0 +1,88 @@
+import fs from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
+import { selectChecks } from './check-affected/model.ts';
+
+type Selection = { run: boolean; reason: string };
+
+function checkOwnership(
+  changedPaths: readonly string[] | null,
+): { early: Selection; plan?: never } | { early?: never; plan: ReturnType<typeof selectChecks> } {
+  if (changedPaths === null) {
+    return { early: { run: true, reason: 'the PR change set could not be established' } };
+  }
+  if (changedPaths.length === 0) {
+    return { early: { run: true, reason: 'the PR diff is empty' } };
+  }
+  const plan = selectChecks({ changedFiles: changedPaths });
+  if (plan.failOpen) {
+    return {
+      early: {
+        run: true,
+        reason: `affected-check ownership is uncertain: ${plan.failOpenReasons[0]?.path}`,
+      },
+    };
+  }
+  return { plan };
+}
+
+export function selectIosXctests(
+  eventName: string,
+  changedPaths: readonly string[] | null,
+): Selection {
+  if (eventName !== 'pull_request')
+    return { run: true, reason: 'main and manual runs exercise XCTest' };
+  const checked = checkOwnership(changedPaths);
+  if (checked.early) return checked.early;
+  const input = checked.plan.reasons.find((entry) => entry.check === 'swift-runner-ios');
+  return input
+    ? { run: true, reason: `XCTest input changed: ${input.path}` }
+    : { run: false, reason: 'the affected-check model selected no iOS runner build' };
+}
+
+export function selectAppleBridgeProof(changedPaths: readonly string[] | null): Selection {
+  const checked = checkOwnership(changedPaths);
+  if (checked.early) return checked.early;
+  const input = changedPaths.find(
+    (file) => file.startsWith('apple/') || file.startsWith('packages/platform-apple/src/'),
+  );
+  return input
+    ? { run: true, reason: `Apple implementation changed: ${input}` }
+    : { run: false, reason: 'the PR changed no Apple implementation or gate tooling' };
+}
+
+function changedPathsFromGit(baseSha: string): string[] | null {
+  if (!/^[a-f0-9]{40}$/.test(baseSha)) return null;
+  const result = spawnSync('git', ['diff', '--name-only', '-z', baseSha, 'HEAD'], {
+    encoding: 'utf8',
+  });
+  if (result.error || result.status !== 0 || result.stdout === null) return null;
+  return result.stdout.split('\0').filter(Boolean);
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+  const target = process.argv[2];
+  if (target !== 'xctest' && target !== 'bridge') {
+    process.stderr.write('Expected xctest or bridge target\n');
+    process.exitCode = 2;
+  } else {
+    const eventName = process.env.GITHUB_EVENT_NAME ?? '';
+    const changedPaths =
+      eventName === 'pull_request' ? changedPathsFromGit(process.env.BASE_SHA ?? '') : [];
+    const selection =
+      target === 'xctest'
+        ? selectIosXctests(eventName, changedPaths)
+        : selectAppleBridgeProof(changedPaths);
+    const label = target === 'xctest' ? 'iOS XCTest' : 'Apple bridge proof';
+    process.stdout.write(`${label}: ${selection.run ? 'run' : 'skip'}; ${selection.reason}\n`);
+    if (process.env.GITHUB_OUTPUT) {
+      fs.appendFileSync(process.env.GITHUB_OUTPUT, `run=${selection.run}\n`);
+    }
+    if (process.env.GITHUB_STEP_SUMMARY) {
+      fs.appendFileSync(
+        process.env.GITHUB_STEP_SUMMARY,
+        `### ${label} selection\n\n${selection.run ? 'Run' : 'Skip'}: ${selection.reason}.\n`,
+      );
+    }
+  }
+}
diff --git a/scripts/check-affected/model.ts b/scripts/check-affected/model.ts
index 259e53fb68..74db165f0c 100644
--- a/scripts/check-affected/model.ts
+++ b/scripts/check-affected/model.ts
@@ -440,6 +440,12 @@ const daemonWireCompatOwnership: OwnershipRule = ({ file }) => {
   ];
 };
 
+const ownsAppleRunnerBuildSource = (file: string): boolean =>
+  file.startsWith('apple/runner/') ||
+  file.startsWith('apple/snapshot-presentation/') ||
+  (file.startsWith('packages/platform-apple/src/runner/') && !file.includes('/__tests__/')) ||
+  file.endsWith('.swift');
+
 const BUILD_OWNERSHIP: ReadonlyArray<{
   check: CheckId;
   rule: string;
@@ -457,19 +463,19 @@ const BUILD_OWNERSHIP: ReadonlyArray<{
       file === 'contracts/fixtures/ios-snapshot-engine-conformance.json' ||
       file === 'contracts/fixtures/snapshot-actionability-policy.json',
   },
-  // Both platform builds compile the same runner sources, and each is a separate
-  // gate in a separate lane, so a Swift change owns both.
+  // The native runner cache hashes these source trees for both Apple targets.
+  // Keep the build owner broader than the current file extensions.
   {
     check: 'swift-runner-ios',
     rule: 'own:swift',
     detail: 'Swift runner sources require the iOS XCUITest build',
-    owns: (file) => file.startsWith('apple/runner/') || file.endsWith('.swift'),
+    owns: ownsAppleRunnerBuildSource,
   },
   {
     check: 'swift-runner-macos',
     rule: 'own:swift',
     detail: 'Swift runner sources require the macOS XCUITest build',
-    owns: (file) => file.startsWith('apple/runner/') || file.endsWith('.swift'),
+    owns: ownsAppleRunnerBuildSource,
   },
   // The PR lane names each runner XCTest method it runs, so renaming or deleting one
   // silently shrinks that lane. Selected here so the drift shows up on the change that
diff --git a/scripts/check-xctest-selection.ts b/scripts/check-xctest-selection.ts
index 6b8c36bbd1..f8c8a2b523 100644
--- a/scripts/check-xctest-selection.ts
+++ b/scripts/check-xctest-selection.ts
@@ -8,7 +8,7 @@
 //   - host    macos.yml, macOS host, every PR: the whole bundle as compiled for macOS, minus
 //             `-skip-testing:` — the pure runner-decision tests, whose guard is
 //             `#if AGENT_DEVICE_RUNNER_UNIT_TESTS` alone.
-//   - pr      ios.yml, iOS Simulator, every PR: the hand-written `-only-testing:` list.
+//   - pr      ios.yml, iOS Simulator: tests with iOS-specific Swift bodies, when selected.
 //   - nightly xctest-nightly.yml, iOS Simulator, scheduled: the whole bundle as compiled for
 //             iOS, minus `-skip-testing:` — includes the simulator-only tests, whose guard is
 //             `… && os(iOS)` (they launch the host app, route through SpringBoard, or assert an
@@ -18,12 +18,8 @@
 // platform rather than treating a source-level `func test…` as running everywhere. What it
 // holds:
 //
-//   1. Every `-only-testing:`/`-skip-testing:` identifier names a declared method that
-//      compiles for that lane's platform. `xcodebuild` treats an identifier matching nothing
-//      as an empty set rather than an error, in BOTH directions: an unknown `-only-testing:`
-//      drops a test from the PR lane silently, and an unknown `-skip-testing:` re-admits
-//      `RunnerTests/testCommand` — not a test but the runner's server entry point, which opens
-//      an NWListener and waits 24 hours — into a whole-bundle lane and hangs it.
+//   1. Every `-skip-testing:` identifier compiles for its lane. An unknown skip re-admits
+//      `RunnerTests/testCommand`, the server entry point that waits 24 hours.
 //   2. Every declared method is reachable by at least one lane. A test gated to a platform
 //      no lane runs (the tvOS-only pair this check found) is dark from the day it is written.
 //   3. The entry point is reachable by no lane at all.
@@ -36,7 +32,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { runCmdSync } from '@agent-device/host-kit/command';
-import type { Platform } from './swift-conditional-compilation.ts';
+import { activeSource, type Platform } from './swift-conditional-compilation.ts';
 import {
   parseDeclaredTestsByPlatform,
   readSwiftSources,
@@ -51,7 +47,6 @@ const packageAppleRunnerScript = path.join(repoRoot, 'scripts/package-apple-runn
 /** The macOS host lane, which runs the whole macOS-compiled bundle on every PR. */
 export const HOST_WORKFLOW_FILE = '.github/workflows/macos.yml';
 
-/** The PR lane, whose `-only-testing:` list decides what every pull request runs on the simulator. */
 export const PR_WORKFLOW_FILE = '.github/workflows/ios.yml';
 
 /** The nightly lane, whose `-skip-testing:` list decides what the full simulator suite leaves out. */
@@ -63,8 +58,8 @@ export type Lane = {
   readonly id: LaneId;
   readonly workflow: string;
   readonly platform: Platform;
-  /** `whole`: everything compiled minus `-skip-testing:`; `list`: the `-only-testing:` entries. */
-  readonly selection: 'whole' | 'list';
+  /** `whole`: everything compiled minus `-skip-testing:`; `ios-specific`: derived from guards. */
+  readonly selection: 'whole' | 'ios-specific';
   /** The job-summary heading the lane's reporter prints. */
   readonly title: string;
 };
@@ -81,8 +76,8 @@ export const LANES: readonly Lane[] = [
     id: 'pr',
     workflow: PR_WORKFLOW_FILE,
     platform: 'iOS',
-    selection: 'list',
-    title: 'iOS runner PR XCTest list',
+    selection: 'ios-specific',
+    title: 'iOS-specific runner PR XCTest lane',
   },
   {
     id: 'nightly',
@@ -158,6 +153,9 @@ export type SelectionReport = {
   readonly dark: readonly string[];
   /** Lanes that reach the entry point — a failure (a 24-hour hang). */
   readonly entryPointReachedBy: readonly LaneId[];
+  readonly prWorkflowWiringFailures: readonly string[];
+  readonly sharedPlatformBranchIds: readonly string[];
+  readonly sharedPlatformBranchFailures: readonly string[];
 };
 
 export type WorkflowSource = { readonly workflow: string; readonly text: string | null };
@@ -193,23 +191,140 @@ function laneReach(
   entry: Lane,
   declaredTests: readonly DeclaredTest[],
   flagged: readonly FlaggedTest[],
+  sharedPlatformBranchIds: readonly string[],
 ): Set<string> {
-  const only = identifiers(flagged, entry.workflow, 'only-testing');
+  if (entry.selection === 'ios-specific')
+    return new Set(iosPrTestIdentifiers(declaredTests, sharedPlatformBranchIds));
   const skipped = identifiers(flagged, entry.workflow, 'skip-testing');
   return new Set(
     declaredTests
       .filter((test) => test.platforms.includes(entry.platform))
       .map((test) => test.identifier)
-      .filter((id) => (entry.selection === 'whole' || only.has(id)) && !skipped.has(id)),
+      .filter((id) => !skipped.has(id)),
   );
 }
 
+export function iosPrTestIdentifiers(
+  declaredTests: readonly DeclaredTest[],
+  sharedPlatformBranchIds: readonly string[],
+): string[] {
+  const branchSensitive = new Set(sharedPlatformBranchIds);
+  return declaredTests
+    .filter(
+      (test) =>
+        test.platforms.includes('iOS') &&
+        (!test.platforms.includes('macOS') || branchSensitive.has(test.identifier)),
+    )
+    .map((test) => test.identifier)
+    .filter((id) => !id.endsWith(`/${ENTRY_POINT_METHOD}`))
+    .sort();
+}
+
+type SharedMethodBody = { id: string; body: string; file: string };
+type SharedMethodScan = { bodies: SharedMethodBody[]; failures: string[] };
+
+function sharedMethodsByName(shared: readonly DeclaredTest[]): Map<string, string[]> {
+  const byMethod = new Map<string, string[]>();
+  for (const test of shared) {
+    const method = test.identifier.split('/').at(-1)!;
+    byMethod.set(method, [...(byMethod.get(method) ?? []), test.identifier]);
+  }
+  return byMethod;
+}
+
+function methodBody(lines: readonly string[], index: number, indent: number): string | undefined {
+  const start = lines[index]!;
+  const end = /\{[ \t]*}[ \t]*(?:\/\/.*)?$/.test(start)
+    ? index
+    : lines.findIndex(
+        (candidate, candidateIndex) =>
+          candidateIndex > index &&
+          (candidate.match(/^[ \t]*/)?.[0].length ?? 0) === indent &&
+          /^[ \t]*}[ \t]*(?:\/\/.*)?$/.test(candidate),
+      );
+  return end < index ? undefined : lines.slice(index, end + 1).join('\n');
+}
+
+function inspectSharedMethods(
+  source: SwiftSource,
+  byMethod: ReadonlyMap<string, readonly string[]>,
+): SharedMethodScan {
+  const lines = source.text.split('\n');
+  const bodies: SharedMethodBody[] = [];
+  const failures: string[] = [];
+  for (const [index, line] of lines.entries()) {
+    const declaration = /^([ \t]*)(?:[\w@]+[ \t]+)*func[ \t]+(test\w*)[ \t]*\(/.exec(line);
+    if (!declaration) continue;
+    const matching = byMethod.get(declaration[2]!);
+    if (!matching) continue;
+    if (matching.length !== 1) {
+      failures.push(
+        `${source.file}:${index + 1}: ambiguous shared XCTest method ${declaration[2]}.`,
+      );
+      continue;
+    }
+    const body = methodBody(lines, index, declaration[1]!.length);
+    if (body === undefined) {
+      failures.push(
+        `${source.file}:${index + 1}: cannot inspect shared XCTest method ${matching[0]}.`,
+      );
+      continue;
+    }
+    bodies.push({ id: matching[0]!, body, file: source.file });
+  }
+  return { bodies, failures };
+}
+
+function scanSharedPlatformBranches(
+  sources: readonly SwiftSource[],
+  declaredTests: readonly DeclaredTest[],
+): { ids: string[]; failures: string[] } {
+  const shared = declaredTests.filter(
+    (test) => test.platforms.includes('iOS') && test.platforms.includes('macOS'),
+  );
+  const byMethod = sharedMethodsByName(shared);
+  const scans = sources.map((source) => inspectSharedMethods(source, byMethod));
+  const bodies = scans.flatMap((scan) => scan.bodies);
+  const failures = scans.flatMap((scan) => scan.failures);
+  for (const test of shared) {
+    if (bodies.filter((body) => body.id === test.identifier).length !== 1) {
+      failures.push(`${test.identifier}: expected one inspectable shared XCTest method body.`);
+    }
+  }
+  const ids = bodies
+    .filter(
+      ({ body, file }) => activeSource(body, 'iOS', file) !== activeSource(body, 'macOS', file),
+    )
+    .map(({ id }) => id);
+  return { ids: [...new Set(ids)].sort(), failures };
+}
+
+function prWorkflowWiringFailures(text: string | null): string[] {
+  if (text === null) return [];
+  const active = text
+    .split('\n')
+    .filter((line) => !YAML_COMMENT.test(line))
+    .join('\n');
+  const failures: string[] = [];
+  if (!active.includes('scripts/check-xctest-selection.ts --ios-pr-tests')) {
+    failures.push('PR workflow does not invoke the generated iOS-specific XCTest selector.');
+  }
+  if (!active.includes('-only-testing:$test_id') || !active.includes('"${IOS_PR_TEST_ARGS[@]}"')) {
+    failures.push('PR workflow does not pass each generated XCTest identifier to xcodebuild.');
+  }
+  if (parseFlaggedTests(PR_WORKFLOW_FILE, active).length > 0) {
+    failures.push('PR workflow still contains hand-maintained XCTest selection identifiers.');
+  }
+  return failures;
+}
+
 export function buildReport(
   target: string,
   sources: readonly SwiftSource[],
   workflows: readonly WorkflowSource[],
 ): SelectionReport {
   const declaredTests = parseDeclaredTestsByPlatform(target, sources);
+  const sharedBranches = scanSharedPlatformBranches(sources, declaredTests);
   const declared = declaredTests.map((test) => test.identifier);
   const known = new Map(declaredTests.map((test) => [test.identifier, test]));
   const flagged = workflows.flatMap((entry) =>
@@ -220,10 +335,11 @@ export function buildReport(
   // and cannot speak for anything else a workflow might select.
   const owned = flagged.filter((entry) => entry.identifier.startsWith(`${target}/`));
   const reach = Object.fromEntries(
-    LANES.map((entry) => [entry.id, laneReach(entry, declaredTests, flagged)]),
+    LANES.map((entry) => [entry.id, laneReach(entry, declaredTests, flagged, sharedBranches.ids)]),
   ) as Record<LaneId, ReadonlySet<string>>;
   const entryPoint = `${target}/${ENTRY_POINT_METHOD}`;
   const reachedAnywhere = new Set(LANES.flatMap((entry) => [...reach[entry.id]]));
+  const prWorkflow = workflows.find((entry) => entry.workflow === PR_WORKFLOW_FILE);
   return {
     target,
     declared,
@@ -241,6 +357,9 @@ export function buildReport(
     entryPointReachedBy: LANES.filter((entry) => reach[entry.id].has(entryPoint)).map(
       (entry) => entry.id,
     ),
+    prWorkflowWiringFailures: prWorkflowWiringFailures(prWorkflow?.text ?? null),
+    sharedPlatformBranchIds: sharedBranches.ids,
+    sharedPlatformBranchFailures: sharedBranches.failures,
   };
 }
 
@@ -322,14 +441,16 @@ export function reportFailures(report: SelectionReport): string[] {
       'widen the guard.',
     );
   }
+  failures.push(...report.prWorkflowWiringFailures);
+  failures.push(...report.sharedPlatformBranchFailures);
   if (report.dark.length > 0) {
     failures.push(
       `${report.dark.length} declared XCTest method(s) are reachable by no lane:`,
       ...report.dark.map((identifier) => `  - ${identifier}`),
       'The host lane runs everything the macOS build compiles, the nightly everything the iOS',
-      'build compiles, and the PR list names its methods; a method outside all three — usually',
+      'build compiles, and the PR lane selects iOS-specific methods; a method outside all three — usually',
       'a guard naming a platform no lane runs — is dark from the day it is written. Widen the',
-      'guard, list it, or delete it.',
+      'guard or delete it.',
     );
   }
   if (report.entryPointReachedBy.length > 0) {
@@ -338,7 +459,7 @@ export function reportFailures(report: SelectionReport): string[] {
         `${report.entryPointReachedBy.join(', ')}.`,
       'It is not a test: it opens an NWListener and waits 24 hours for a client, so a lane that',
       'runs it hangs until timeout-minutes. Whole-bundle lanes must keep their -skip-testing:',
-      'entry for it; the PR list must not name it.',
+      'entry for it; the PR selector must exclude it.',
     );
   }
   return failures;
@@ -348,8 +469,8 @@ export function formatSummary(report: SelectionReport): string {
   const { declared, host, pr, nightly, dark } = counts(report);
   return (
     `xctest selection: ${declared} declared ${report.target} methods — host lane ` +
-    `(${HOST_WORKFLOW_FILE}, macOS, every PR) reaches ${host}, PR list (${PR_WORKFLOW_FILE}, ` +
-    `iOS Simulator, every PR) selects ${pr}, nightly (${NIGHTLY_WORKFLOW_FILE}, iOS Simulator) ` +
+    `(${HOST_WORKFLOW_FILE}, macOS, every PR) reaches ${host}, PR iOS-specific lane (${PR_WORKFLOW_FILE}, ` +
+    `iOS Simulator, selected PRs and main) selects ${pr}, nightly (${NIGHTLY_WORKFLOW_FILE}, iOS Simulator) ` +
     `reaches ${nightly}; ${dark} reachable by no lane; ${ENTRY_POINT_METHOD} skipped everywhere.\n`
   );
 }
@@ -368,6 +489,17 @@ export function runnerPackageSourceFailures(root: string = repoRoot): string[] {
 
 function main(): number {
   const report = loadReport();
+  if (process.argv.slice(2).includes('--ios-pr-tests')) {
+    const failures = reportFailures(report);
+    if (report.reach.pr.size === 0)
+      failures.push('The PR lane selected no iOS-specific XCTest methods.');
+    if (failures.length > 0) {
+      process.stderr.write(`${failures.join('\n')}\n`);
+      return 1;
+    }
+    process.stdout.write(`${[...report.reach.pr].sort().join('\n')}\n`);
+    return 0;
+  }
   const failures = [...reportFailures(report), ...runnerPackageSourceFailures()];
   process.stdout.write(formatSummary(report));
   if (failures.length === 0) return 0;
diff --git a/scripts/xctest-declarations.ts b/scripts/xctest-declarations.ts
index 59ef490648..d7e7fbc4d8 100644
--- a/scripts/xctest-declarations.ts
+++ b/scripts/xctest-declarations.ts
@@ -18,15 +18,13 @@ export const RUNNER_TESTS_DIR = 'apple/runner/AgentDeviceRunner/AgentDeviceRunne
 // file's name says nothing about whether it declares addressable tests.
 const SWIFT_SOURCE = /\.swift$/;
 
-// One ordered pass over the source. A column-0 type declaration moves the enclosing type;
-// a `func test…` indented exactly one level binds to it. Position carries the meaning
-// rather than brace counting, which would have to know which `{` sits inside a string
-// literal. It is also the more precise rule: only a method declared directly in a
-// top-level `class`/`extension` block is addressable as `Target/Class/method`, so a
-// helper type nested inside a test body (`final class ResultBox` — several of these
-// exist) contributes no test identifiers, and neither does a closure-local `func test…`.
-const DECLARATION =
-  /^(?:[\w@]+[ \t]+)*(?:class|extension|struct|enum|actor|protocol)[ \t]+([A-Za-z_]\w*)|^ {2}(?:[\w@]+[ \t]+)*func[ \t]+(test\w*)[ \t]*\(/gm;
+// Swift ignores indentation, but the runner tests use it consistently to distinguish
+// methods from functions local to a method. The type and method may each be indented by
+// a surrounding #if block; requiring column zero or exactly two spaces misses valid tests.
+const TYPE_DECLARATION =
+  /^([ \t]*)(?:[\w@]+[ \t]+)*(?:class|extension|struct|enum|actor|protocol)[ \t]+([A-Za-z_]\w*)\b/;
+const FUNCTION_DECLARATION = /^([ \t]*)(?:[\w@]+[ \t]+)*func[ \t]+([A-Za-z_]\w*)/;
+const TEST_DECLARATION = /^([ \t]*)(?:[\w@]+[ \t]+)*func[ \t]+(test\w*)[ \t]*\(/;
 
 export type SwiftSource = { readonly file: string; readonly text: string };
 
@@ -59,15 +57,91 @@ function collectSwiftSourcePaths(directory: string, relativeDirectory: string, f
 
 /** Every `Target/Class/method` identifier the sources declare, sorted, guards ignored. */
 export function parseDeclaredTests(target: string, sources: readonly SwiftSource[]): string[] {
-  const declared = new Set<string>();
-  for (const source of sources) {
-    let enclosing = '';
-    for (const [, type, method] of source.text.matchAll(DECLARATION)) {
-      if (type !== undefined) enclosing = type;
-      else if (method !== undefined && enclosing) declared.add(`${target}/${enclosing}/${method}`);
-    }
+  return [...new Set(sources.flatMap((source) => declarationsInSource(target, source)))].sort();
+}
+
+type DeclarationScope = {
+  enclosing?: { name: string; indent: number };
+  nestedTypeIndent?: number;
+  functionIndent?: number;
+};
+
+function declarationsInSource(target: string, source: SwiftSource): string[] {
+  const scope: DeclarationScope = {};
+  const declared: string[] = [];
+  for (const [index, line] of source.text.split('\n').entries()) {
+    if (/^[ \t]*(?:\/\/|\/\*|\*)/.test(line)) continue;
+    const indent = line.match(/^[ \t]*/)?.[0].length ?? 0;
+    const error = () => unrecognizedDeclaration(source.file, index + 1, line);
+    if (/\bfunc[ \t]+test\w*/.test(line) && !FUNCTION_DECLARATION.test(line)) throw error();
+    closeScopes(scope, line, indent);
+    if (readTypeDeclaration(scope, line, indent)) continue;
+    const method = readTestDeclaration(scope, line, indent, error);
+    if (method) declared.push(`${target}/${method}`);
   }
-  return [...declared].sort();
+  return declared;
+}
+
+function unrecognizedDeclaration(file: string, lineNumber: number, line: string): Error {
+  return new Error(`${file}:${lineNumber}: unrecognized XCTest declaration: ${line.trim()}`);
+}
+
+function closeScopes(scope: DeclarationScope, line: string, indent: number): void {
+  if (!/^[ \t]*}/.test(line)) return;
+  if (scope.functionIndent !== undefined && indent <= scope.functionIndent)
+    scope.functionIndent = undefined;
+  if (scope.nestedTypeIndent !== undefined && indent <= scope.nestedTypeIndent)
+    scope.nestedTypeIndent = undefined;
+  if (scope.enclosing && indent <= scope.enclosing.indent) scope.enclosing = undefined;
+}
+
+function readTypeDeclaration(scope: DeclarationScope, line: string, indent: number): boolean {
+  const type = TYPE_DECLARATION.exec(line);
+  if (!type) return false;
+  if (!scope.enclosing) scope.enclosing = { name: type[2]!, indent };
+  else if (indent > scope.enclosing.indent && scope.functionIndent === undefined)
+    scope.nestedTypeIndent = indent;
+  return true;
+}
+
+function readTestDeclaration(
+  scope: DeclarationScope,
+  line: string,
+  indent: number,
+  error: () => Error,
+): string | undefined {
+  const func = FUNCTION_DECLARATION.exec(line);
+  if (!func) return undefined;
+  const local = isLocalFunction(scope, indent);
+  markFunctionScope(scope, indent, local);
+  const name = func[2]!;
+  if (local || !name.startsWith('test')) return undefined;
+  return checkedTestName(scope, line, indent, name, error);
+}
+
+function isLocalFunction(scope: DeclarationScope, indent: number): boolean {
+  return (
+    (scope.functionIndent !== undefined && indent > scope.functionIndent) ||
+    (scope.nestedTypeIndent !== undefined && indent > scope.nestedTypeIndent)
+  );
+}
+
+function markFunctionScope(scope: DeclarationScope, indent: number, local: boolean): void {
+  if (!scope.enclosing || indent <= scope.enclosing.indent) return;
+  if (scope.functionIndent !== undefined || local) return;
+  scope.functionIndent = indent;
+}
+
+function checkedTestName(
+  scope: DeclarationScope,
+  line: string,
+  indent: number,
+  name: string,
+  error: () => Error,
+): string {
+  const enclosing = scope.enclosing;
+  if (!enclosing || indent <= enclosing.indent || !TEST_DECLARATION.test(line)) throw error();
+  return `${enclosing.name}/${name}`;
 }
 
 /** The declared identifiers, each with the platforms whose unit-test build compiles it. */
diff --git a/test/integration/replays/ios/simulator/01-settings.ad b/test/integration/replays/ios/simulator/01-settings.ad
index 418401db19..226d8ddcb5 100644
--- a/test/integration/replays/ios/simulator/01-settings.ad
+++ b/test/integration/replays/ios/simulator/01-settings.ad
@@ -1,12 +1,9 @@
 # Dogfood iOS Settings flow through the replay suite runner.
 context platform=ios target=mobile
 open com.apple.Preferences --relaunch
-screenshot "./test/screenshots/replays/ios-settings.png"
-snapshot -i
 appstate
 click "role=cell label=General || role=button label=General"
 wait "label=About || label=\"Software Update\" || text=\"Manage your overall setup and preferences\"" 5000
-snapshot
 is exists "label=About || label=\"Software Update\" || text=\"Manage your overall setup and preferences\""
 find text "Software Update" exists
 back
diff --git a/vitest.config.ts b/vitest.config.ts
index 77b2793122..bcddac82e9 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -125,9 +125,11 @@ export default defineConfig({
             'scripts/__tests__/agent-setup-startup-contract.test.ts',
             'scripts/__tests__/npm-skills-exclusion.test.ts',
             'scripts/__tests__/simulator-skills-contract.test.ts',
-            // Parses ios.yml and the runner's Swift sources: no Xcode, no simulator, and
-            // the check it guards is what keeps the PR lane's `-only-testing:` list honest.
+            // Parse Swift guards and declarations before deriving the simulator selection.
+            'scripts/__tests__/swift-conditional-compilation.test.ts',
+            'scripts/__tests__/xctest-declarations.test.ts',
             'scripts/__tests__/xctest-selection.test.ts',
+            'scripts/__tests__/apple-ci-impact.test.ts',
             // The nightly XCTest lane's reporter/liveness check, which otherwise only ever
             // executes on a macOS runner at 04:30.
             'scripts/__tests__/xctest-run-summary.test.ts',

From 622435ecc52d3c8c8aca124aec93758efc68d7a2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 24 Sep 2026 18:49:45 +0200
Subject: [PATCH 108/132] 0.21.14

---
 package.json | 2 +-
 server.json  | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/package.json b/package.json
index f54bd19536..5c04326b9a 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "agent-device",
-  "version": "0.21.13",
+  "version": "0.21.14",
   "description": "Mobile app automation and verification for AI coding agents. CLI, MCP server, and typed Node.js API for iOS, Android, HarmonyOS, TV, web, macOS, and Linux.",
   "mcpName": "io.github.callstack/agent-device",
   "license": "MIT",
diff --git a/server.json b/server.json
index 6693cea7ea..1158968b9c 100644
--- a/server.json
+++ b/server.json
@@ -7,12 +7,12 @@
     "url": "https://github.com/callstack/agent-device",
     "source": "github"
   },
-  "version": "0.21.13",
+  "version": "0.21.14",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "agent-device",
-      "version": "0.21.13",
+      "version": "0.21.14",
       "transport": {
         "type": "stdio"
       },

From 14bf77b9894e1b9d8faa7066f8234fdbd1a944d7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Oskar=20Kwa=C5=9Bniewski?= <oskar@okwasniewski.com>
Date: Thu, 24 Sep 2026 19:39:22 +0200
Subject: [PATCH 109/132] fix(android): carry the field's hint text on the
 snapshot node as placeholder (#2927)

The helper wrote hint-showing but never the hint itself, and text holds the
hint only while the field is empty, so a filled field's placeholder was
readable nowhere. The helper now writes hint (getHintText, API 26+), the
node carries it as placeholder whether or not it is showing, and the fact
joins the unchanged map and the find/get digest. Value and label are
unchanged.
---
 .../snapshothelper/AccessibilityTreeXml.java  |  3 ++
 packages/kernel/src/snapshot.ts               |  5 ++
 .../ui-hierarchy-placeholder.test.ts          | 53 +++++++++++++++++++
 .../src/ui-hierarchy-builder.ts               |  1 +
 .../platform-android/src/ui-hierarchy-node.ts |  1 +
 packages/platform-android/src/ui-hierarchy.ts |  4 ++
 .../runtime/snapshot-unchanged.test.ts        |  1 +
 .../capture/runtime/snapshot-unchanged.ts     |  1 +
 src/daemon/__tests__/response-views.test.ts   |  1 +
 src/daemon/response-views.ts                  |  1 +
 website/docs/docs/snapshots.md                | 11 ++--
 11 files changed, 78 insertions(+), 4 deletions(-)
 create mode 100644 packages/platform-android/src/__tests__/ui-hierarchy-placeholder.test.ts

diff --git a/android/snapshot-helper/src/main/java/com/callstack/agentdevice/snapshothelper/AccessibilityTreeXml.java b/android/snapshot-helper/src/main/java/com/callstack/agentdevice/snapshothelper/AccessibilityTreeXml.java
index 802cd38bb1..c5c1da5249 100644
--- a/android/snapshot-helper/src/main/java/com/callstack/agentdevice/snapshothelper/AccessibilityTreeXml.java
+++ b/android/snapshot-helper/src/main/java/com/callstack/agentdevice/snapshothelper/AccessibilityTreeXml.java
@@ -43,6 +43,9 @@ static void appendNode(
     // (#2063 empty-fill verification).
     if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
       appendAttribute(xml, "hint-showing", Boolean.toString(node.isShowingHintText()));
+      // The hint itself, whether or not the field is showing it: `text` holds the hint only while
+      // the field is empty, so a filled field's placeholder is readable nowhere else.
+      appendNonEmptyAttribute(xml, "hint", node.getHintText());
     }
     appendAttribute(xml, "editable", Boolean.toString(node.isEditable()));
     // Accessibility selection offsets, not a measurement of the value's length. Read-only
diff --git a/packages/kernel/src/snapshot.ts b/packages/kernel/src/snapshot.ts
index eace66eba8..b6b817433d 100644
--- a/packages/kernel/src/snapshot.ts
+++ b/packages/kernel/src/snapshot.ts
@@ -246,6 +246,11 @@ export type RawSnapshotNode = {
   editable?: boolean;
   password?: boolean;
   hintShowing?: boolean;
+  /**
+   * Placeholder text of a text field (the Android hint), whether or not the field is showing it.
+   * Absent when the field has none or the producer did not read it.
+   */
+  placeholder?: string;
   /** Accessibility selection offsets, never a character count or proof of value equality. */
   selectionStart?: number;
   selectionEnd?: number;
diff --git a/packages/platform-android/src/__tests__/ui-hierarchy-placeholder.test.ts b/packages/platform-android/src/__tests__/ui-hierarchy-placeholder.test.ts
new file mode 100644
index 0000000000..c72a64418b
--- /dev/null
+++ b/packages/platform-android/src/__tests__/ui-hierarchy-placeholder.test.ts
@@ -0,0 +1,53 @@
+import { expect, test } from 'vitest';
+import { buildUiHierarchySnapshot, parseUiHierarchyTree } from '../ui-hierarchy.ts';
+
+// A form: an empty field shows its hint (and reports the hint as its text), a filled field no longer
+// shows it but still has one, and a label has none.
+const PLACEHOLDER_XML = `<hierarchy>
+  <node class="android.widget.FrameLayout" resource-id="root" bounds="[0,0][400,800]"
+    window-index="0" window-type="1" window-layer="1" window-active="true" window-focused="true"
+    window-bounds="[0,0][400,800]" visible-to-user="true" enabled="true">
+    <node class="android.widget.TextView" resource-id="name-label" text="Name"
+      bounds="[0,0][400,60]" enabled="true" visible-to-user="true" />
+    <node class="android.widget.EditText" resource-id="name-input" text="Key echo" hint="Key echo"
+      hint-showing="true" editable="true" bounds="[0,60][400,120]" clickable="true" focusable="true"
+      enabled="true" visible-to-user="true" />
+    <node class="android.widget.EditText" resource-id="email-input" text="ada@example.com"
+      hint="Email address" hint-showing="false" editable="true" bounds="[0,120][400,180]"
+      clickable="true" focusable="true" enabled="true" visible-to-user="true" />
+  </node>
+</hierarchy>`;
+
+function nodesById(raw: boolean, interactiveOnly = false) {
+  const { nodes } = buildUiHierarchySnapshot(parseUiHierarchyTree(PLACEHOLDER_XML), undefined, {
+    raw,
+    interactiveOnly,
+  });
+  return (identifier: string) => nodes.find((node) => node.identifier === identifier);
+}
+
+test.each([
+  { raw: false, interactiveOnly: false },
+  { raw: true, interactiveOnly: false },
+  { raw: true, interactiveOnly: true },
+])(
+  'the placeholder reaches snapshot nodes whether or not the field shows it (raw=$raw, -i=$interactiveOnly)',
+  ({ raw, interactiveOnly }) => {
+    const byId = nodesById(raw, interactiveOnly);
+    expect(byId('name-input')?.placeholder).toBe('Key echo');
+    expect(byId('name-input')?.hintShowing).toBe(true);
+    expect(byId('email-input')?.placeholder).toBe('Email address');
+    expect(byId('email-input')?.hintShowing).toBe(false);
+  },
+);
+
+test('the value stays what the platform reported: the hint while showing, the text once filled', () => {
+  const byId = nodesById(false);
+  expect(byId('name-input')?.value).toBe('Key echo');
+  expect(byId('email-input')?.value).toBe('ada@example.com');
+});
+
+test('a node without a hint carries no placeholder key once serialized', () => {
+  const byId = nodesById(false);
+  expect(JSON.parse(JSON.stringify(byId('name-label')))).not.toHaveProperty('placeholder');
+});
diff --git a/packages/platform-android/src/ui-hierarchy-builder.ts b/packages/platform-android/src/ui-hierarchy-builder.ts
index a3aed983f0..e4f0ffaffb 100644
--- a/packages/platform-android/src/ui-hierarchy-builder.ts
+++ b/packages/platform-android/src/ui-hierarchy-builder.ts
@@ -359,6 +359,7 @@ function createAndroidRawSnapshotNode(
     editable: node.editable,
     password: node.password,
     hintShowing: node.hintShowing,
+    placeholder: node.placeholder,
     selectionStart: node.selectionStart,
     selectionEnd: node.selectionEnd,
     visibleToUser: node.visibleToUser,
diff --git a/packages/platform-android/src/ui-hierarchy-node.ts b/packages/platform-android/src/ui-hierarchy-node.ts
index 4ac4a47a1f..205c56ef4a 100644
--- a/packages/platform-android/src/ui-hierarchy-node.ts
+++ b/packages/platform-android/src/ui-hierarchy-node.ts
@@ -22,6 +22,7 @@ export type AndroidUiHierarchy = {
   editable?: boolean;
   password?: boolean;
   hintShowing?: boolean;
+  placeholder?: string;
   selectionStart?: number;
   selectionEnd?: number;
   // Two independent facts, never collapsed, and never undefined: the helper omits false attributes
diff --git a/packages/platform-android/src/ui-hierarchy.ts b/packages/platform-android/src/ui-hierarchy.ts
index 006502d9b3..7317d057ba 100644
--- a/packages/platform-android/src/ui-hierarchy.ts
+++ b/packages/platform-android/src/ui-hierarchy.ts
@@ -48,6 +48,8 @@ export type AndroidUiNodeMetadata = {
    * `getText()` returns the hint on modern Android). Absent in raw uiautomator dumps.
    */
   hintShowing?: boolean;
+  /** Helper-only: the field's hint text (API 26 or later), whether or not it is showing. */
+  hint?: string;
   scrollable?: boolean;
   canScrollForward?: boolean;
   canScrollBackward?: boolean;
@@ -168,6 +170,7 @@ function readNodeAttributes(node: string): Omit<AndroidUiNodeMetadata, 'rect'> {
     ...optionalNumberAttr('selectionStart', 'selection-start'),
     ...optionalNumberAttr('selectionEnd', 'selection-end'),
     ...optionalBoolAttr('hintShowing', 'hint-showing'),
+    ...optionalStringAttr('hint', 'hint'),
     ...optionalBoolAttr('visibleToUser', 'visible-to-user'),
     ...optionalBoolAttr('selected', 'selected'),
     ...optionalBoolAttr('heading', 'heading'),
@@ -331,6 +334,7 @@ function normalizeAndroidUiHierarchyNode(
       editable: attrs.editable,
       password: attrs.password,
       hintShowing: attrs.hintShowing,
+      placeholder: attrs.hint,
       selectionStart: attrs.selectionStart,
       selectionEnd: attrs.selectionEnd,
       visibleToUser: attrs.visibleToUser,
diff --git a/src/commands/capture/runtime/snapshot-unchanged.test.ts b/src/commands/capture/runtime/snapshot-unchanged.test.ts
index c775416f77..1b3cf7ce6f 100644
--- a/src/commands/capture/runtime/snapshot-unchanged.test.ts
+++ b/src/commands/capture/runtime/snapshot-unchanged.test.ts
@@ -74,6 +74,7 @@ test.each<Partial<SnapshotNode>>([
   { enabled: false },
   { selected: true },
   { focused: true },
+  { placeholder: 'Key echo' },
   { hittable: false },
   { bundleId: 'com.example.app' },
   { appName: 'Example' },
diff --git a/src/commands/capture/runtime/snapshot-unchanged.ts b/src/commands/capture/runtime/snapshot-unchanged.ts
index 1ec07b70ee..da581313bc 100644
--- a/src/commands/capture/runtime/snapshot-unchanged.ts
+++ b/src/commands/capture/runtime/snapshot-unchanged.ts
@@ -114,6 +114,7 @@ const PRESENTATION_SCALAR_FIELDS = {
   focused: true,
   heading: true,
   roleDescription: true,
+  placeholder: true,
   hittable: true,
   bundleId: true,
   appName: true,
diff --git a/src/daemon/__tests__/response-views.test.ts b/src/daemon/__tests__/response-views.test.ts
index 1ee1ef50de..4d7cea294d 100644
--- a/src/daemon/__tests__/response-views.test.ts
+++ b/src/daemon/__tests__/response-views.test.ts
@@ -322,6 +322,7 @@ test('attrs digest keeps explicit false/zero/empty field facts; unavailable ones
     editable: false,
     password: false,
     hintShowing: false,
+    placeholder: 'Key echo',
     selectionStart: 0,
     selectionEnd: 0,
   };
diff --git a/src/daemon/response-views.ts b/src/daemon/response-views.ts
index 2a21a34a12..2454c8c59a 100644
--- a/src/daemon/response-views.ts
+++ b/src/daemon/response-views.ts
@@ -120,6 +120,7 @@ const SELECTOR_DIGEST_NODE_FIELDS = [
   'editable',
   'password',
   'hintShowing',
+  'placeholder',
   'selectionStart',
   'selectionEnd',
   'hittable',
diff --git a/website/docs/docs/snapshots.md b/website/docs/docs/snapshots.md
index f9ef3f34e0..99b08b5bf1 100644
--- a/website/docs/docs/snapshots.md
+++ b/website/docs/docs/snapshots.md
@@ -117,10 +117,10 @@ the strategy owns which tiers it may use.
 ## Android node metadata
 
 Android snapshot nodes and `get attrs` (including the digest response) carry the native
-`selected`, `heading`, `roleDescription`, `editable`, `password`, `hintShowing`, `selectionStart`,
-and `selectionEnd` facts whenever the accessibility tree reports them. Explicit `false` and `0` are
-kept; an absent field means the fact was unavailable, not false. `hintShowing` needs Android API 26
-or later, `heading` API 28 or later.
+`selected`, `heading`, `roleDescription`, `editable`, `password`, `hintShowing`, `placeholder`,
+`selectionStart`, and `selectionEnd` facts whenever the accessibility tree reports them. Explicit
+`false` and `0` are kept; an absent field means the fact was unavailable, not false. `hintShowing`
+and `placeholder` need Android API 26 or later, `heading` API 28 or later.
 
 - `selected` is the accessibility selected state an app sets on a control — the active bottom-tab or
   segmented-control item, or the chosen row of a list. Android reports it explicitly as `true` or
@@ -135,6 +135,9 @@ or later, `heading` API 28 or later.
 - `value: ""` is an explicitly empty accessibility text; a missing `value` means no text was
   reported. The text of an empty field is its hint on modern Android, so check `hintShowing`
   before reading `value` as the entered contents.
+- `placeholder` is the field's hint text itself, present whether the field is empty or filled: an
+  empty field shows it (`hintShowing: true`, and `value` repeats it), a filled field no longer does.
+  A field without a hint omits it.
 - `selectionStart`/`selectionEnd` are accessibility selection offsets. They are independent of
   `editable` (read-only selectable text exposes them too), they are not a character count, and
   they do not prove that a masked or secure value equals expected text.

From 438b43cf69081d57a2caf9355ea93924761b5045 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 24 Sep 2026 19:41:23 +0200
Subject: [PATCH 110/132] fix(timeouts): prove request envelopes cover their
 worst-case work (#2916)

* fix(ios): derive the fold request envelope from a worst-case ledger test

FOLD_REQUEST_TIMEOUT_MS was a literal whose basis lived only in a
comment, and that comment kept drifting from the route: it first cited
one 30s helper build and four 20s hinge reads, missing two 5s
display-inventory reads and the HID-dispatch guard/grace, then #2858
hand-summed the route again for its own preparation-phase change and
landed a fresh hand-summed figure with the same failure mode.

Add a ledger test that drives fold through the public client and
daemon against a fake Apple tool provider recording each call's
timeoutMs, including the fold-helper cache's toolchain probes and
build. A calibration run learns the route's hinge-settle-attempt count
from an oscillating angle that never settles; a measured run uses the
same oscillation but lands the last allowed read on target, so it
succeeds after making exactly as many reads. Summing every call's
timeout (minus 1ms, plus any kill grace) gives the route's worst case
that still succeeds, asserted against the resolved command envelope
with the usual 30s daemon-result margin. The test imports no
platform-apple step figure other than MAX_FOLD_DURATION_MS, so it
keeps proving the bound however the route's steps change next.

Widen FOLD_REQUEST_TIMEOUT_MS to 255_000 (the smallest 5s multiple at
least ledger + margin) and point both the constant's comment and the
descriptor-timeout-policy pinning test at the ledger test instead of a
hand-summed figure.

* fix(ios): keep a daemon-result margin over prepare's default runner budget

readPrepareIosRunnerTimeoutMs's fallback and the client envelope both
resolved to PREPARE_REQUEST_TIMEOUT_MS (240_000), so with no
--timeout the daemon-side runner budget and the client envelope were
identical: a slow cold runner build ended in a client-side timeout and
daemon reset instead of the daemon's own typed runner_phase_budget
result. Every other bounded command keeps a 30s margin between its
daemon-side budget and its envelope; prepare's explicit-timeout case
already widened past its own base by that same margin
(widenToUserBudget), only the default case had none.

Split the daemon-side runner budget out as PREPARE_STARTUP_BUDGET_MS
(240_000, unchanged) and derive PREPARE_REQUEST_TIMEOUT_MS from it
plus the margin (270_000). The handler falls back to the startup
budget, not the now-wider request timeout.

Add a handler-level test that calls handlePrepareCommand directly with
a fake runner binding recording the timeoutMs it receives, then checks
that value plus the margin against the same request's resolved client
envelope for the no-flag, --timeout above default, and --timeout below
default cases - the rule the fix proves, not just the constants it
compiles to.

* fix(ios): fail the fold ledger test on an unbounded provider call

The fold worst-case ledger fake defaulted an unset timeoutMs to 0, so a
provider call reaching it with no bound cost 0 virtual ms instead of
exposing the true unbounded worst case. Its runCommand handler also
skipped `open -a Simulator` before recording, dropping any such call
from the ledger with no error.

Build the ledger on the shared recording provider and assert every
call carries a finite, positive timeoutMs, so an unbounded call fails
the test instead of passing silently.

* test(ios): give the fold ledger test a cold-import budget

The ledger test runs two cold folds through a fresh daemon each. After a
platform-apple source change the first import is untransformed, and the
test ran past vitest's 5 s default, which hid the ledger printout behind a
timeout. Match the provider-scenario precedent of an explicit budget.
---
 .../command-registry/src/timeout-policy.ts    |  20 +-
 .../command-descriptor-timeout-policy.test.ts |  12 +-
 .../__tests__/session-prepare.test.ts         | 130 ++++++++
 src/daemon/handlers/session-prepare.ts        |   4 +-
 .../provider-scenarios/ios-fold.test.ts       | 295 ++++++++++++++++--
 5 files changed, 417 insertions(+), 44 deletions(-)
 create mode 100644 src/daemon/handlers/__tests__/session-prepare.test.ts

diff --git a/packages/command-registry/src/timeout-policy.ts b/packages/command-registry/src/timeout-policy.ts
index ca17ee37b7..30e6f58f61 100644
--- a/packages/command-registry/src/timeout-policy.ts
+++ b/packages/command-registry/src/timeout-policy.ts
@@ -5,7 +5,6 @@ import type { CommandTimeoutBudget, CommandTimeoutPolicy } from './types.ts';
 // declared per command on the descriptors, so their values live beside them.
 
 const DAEMON_REQUEST_TIMEOUT_MS = 90_000;
-export const PREPARE_REQUEST_TIMEOUT_MS = 240_000;
 
 // Keep this above the longest platform install subprocess timeout so the client
 // envelope does not abort a still-progressing device install first.
@@ -16,6 +15,12 @@ export const INSTALL_REQUEST_TIMEOUT_MS = 180_000;
 // envelope below the command's declared base.
 const REQUEST_TIMEOUT_BUDGET_MARGIN_MS = 30_000;
 
+/** Daemon-side runner budget for `prepare` without `--timeout` (`readPrepareIosRunnerTimeoutMs`). */
+export const PREPARE_STARTUP_BUDGET_MS = 240_000;
+
+export const PREPARE_REQUEST_TIMEOUT_MS =
+  PREPARE_STARTUP_BUDGET_MS + REQUEST_TIMEOUT_BUDGET_MARGIN_MS;
+
 /**
  * How long a lease lifecycle provider may spend allocating one lease (cloud
  * device allocation: BrowserStack iOS ~45–90s, AWS remote access ~2 min to
@@ -43,16 +48,11 @@ export const DEFAULT_TIMEOUT_POLICY: CommandTimeoutPolicy = {
 };
 
 /**
- * `fold`'s worst case sums every step budget on the route (platform-apple owns the constants;
- * command-registry does not import them, so the figures below are copied, not derived):
- *   - display-inventory query (foldable check):        5s
- *   - fold-helper preparation (toolchain probe + build): 60s
- *   - HID dispatch (60s max keyframe duration + 10s):   70s
- *   - hinge settle reads (4 attempts x 20s):            80s
- *   - lit-panel display-inventory query:                 5s
- *   total: 220s. The envelope below covers that with margin.
+ * Covers the fold route's worst-case ledger (display inventory, fold-helper preparation, HID
+ * dispatch, hinge settle reads, final display inventory) plus the daemon-result margin. Proven by
+ * the ledger test: `test/integration/provider-scenarios/ios-fold.test.ts`.
  */
-const FOLD_REQUEST_TIMEOUT_MS = 240_000;
+const FOLD_REQUEST_TIMEOUT_MS = 255_000;
 
 export const FOLD_TIMEOUT_POLICY: CommandTimeoutPolicy = {
   budget: { source: 'none' },
diff --git a/src/__tests__/command-descriptor-timeout-policy.test.ts b/src/__tests__/command-descriptor-timeout-policy.test.ts
index 906cf289c0..d8d444d278 100644
--- a/src/__tests__/command-descriptor-timeout-policy.test.ts
+++ b/src/__tests__/command-descriptor-timeout-policy.test.ts
@@ -138,15 +138,15 @@ test('settle timeout policy default matches the runtime settle loop default', ()
 
 test('request envelopes deviating from the default are bounded, reviewed sets', () => {
   const EXPECTED_ENVELOPES: Record<string, number | 'unbounded'> = {
-    prepare: 240_000,
+    // prepare: daemon-side runner budget (PREPARE_STARTUP_BUDGET_MS) plus the daemon-result margin.
+    prepare: 270_000,
     install: 180_000,
     reinstall: 180_000,
     install_source: 180_000,
     longpress: 210_000,
-    // fold: display-inventory query + fold-helper preparation + HID dispatch + hinge settle
-    // reads + lit-panel display-inventory query can sum to 220s worst case; the policy covers
-    // that with margin.
-    fold: 240_000,
+    // fold: proven by the worst-case ledger test in
+    // test/integration/provider-scenarios/ios-fold.test.ts.
+    fold: 255_000,
     // #1774: base allocation budget (300s) + client/daemon race margin (30s).
     lease_allocate: 330_000,
     test: 'unbounded',
@@ -318,7 +318,7 @@ test('snapshot uses the standard daemon request timeout with an explicit overrid
       ...base,
       positionals: ['ios-runner'],
     }),
-    240_000,
+    270_000,
   );
   assert.equal(
     resolveCommandRequestTimeoutMs(resolveCommandTimeoutPolicy('test'), { ...base }),
diff --git a/src/daemon/handlers/__tests__/session-prepare.test.ts b/src/daemon/handlers/__tests__/session-prepare.test.ts
new file mode 100644
index 0000000000..5804f8e8b5
--- /dev/null
+++ b/src/daemon/handlers/__tests__/session-prepare.test.ts
@@ -0,0 +1,130 @@
+import { expect, test, vi } from 'vitest';
+import type { CommandFlags } from '@agent-device/contracts/command';
+import { resolveCommandTimeoutPolicy } from '@agent-device/command-registry/registry';
+import { resolveCommandRequestTimeoutMs } from '@agent-device/command-registry/timeout-policy';
+import {
+  localRuntimeOwner,
+  narrowDeviceBinding,
+  type RuntimeFacts,
+} from '@agent-device/contracts/platform-runtime';
+import type { PlatformRuntimeOperations } from '@agent-device/contracts/platform-runtime-operations';
+import { IOS_SIMULATOR } from '../../../__tests__/test-utils/device-fixtures.ts';
+import { makeSessionStore } from '../../../__tests__/test-utils/store-factory.ts';
+import { createUnavailableRuntimeFactsForTest } from '../../../__tests__/test-utils/runtime-operation-facts.ts';
+import type {
+  BindDeviceRuntime,
+  InspectDeviceRuntimeFacts,
+} from '../../request-runtime-binding.ts';
+import { handlePrepareCommand } from '../session-prepare.ts';
+
+// `resolveCommandDevice` widens to `resolveTargetDevice` for an explicit selector (this test
+// always supplies `--udid`), which otherwise reaches the real device-selection dispatcher.
+vi.mock('@agent-device/device-selection/dispatch-resolve', async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import('@agent-device/device-selection/dispatch-resolve')>();
+  return { ...actual, resolveTargetDevice: vi.fn(async () => IOS_SIMULATOR) };
+});
+
+// Matches REQUEST_TIMEOUT_BUDGET_MARGIN_MS, packages/command-registry/src/timeout-policy.ts. Not
+// imported: it is not exported (fallow would flag an export used only by a test).
+const REQUIRED_DAEMON_RESULT_MARGIN_MS = 30_000;
+
+function prepareRuntimeFacts(): RuntimeFacts<PlatformRuntimeOperations> {
+  const unavailableFacts = createUnavailableRuntimeFactsForTest(
+    IOS_SIMULATOR,
+    localRuntimeOwner('apple'),
+  );
+  return {
+    ...unavailableFacts,
+    operations: { ...unavailableFacts.operations, prepareAppleRunner: { available: true } },
+  };
+}
+
+/**
+ * Runs `prepare ios-runner` through the production handler with a fake runner binding that
+ * records the `timeoutMs` it was handed, then checks that value (plus the daemon-result margin)
+ * against the same request's resolved client envelope — the rule 1d proves, not just the
+ * constants it happens to compile to.
+ */
+async function runPrepare(flags: { timeoutMs?: number }): Promise<{
+  handlerTimeoutMs: number;
+  envelopeMs: number | undefined;
+}> {
+  const sessionName = 'prepare-envelope-margin';
+  const sessionStore = makeSessionStore('agent-device-prepare-handler-');
+  sessionStore.set(sessionName, {
+    name: sessionName,
+    device: IOS_SIMULATOR,
+    createdAt: Date.now(),
+    actions: [],
+  });
+
+  let handlerTimeoutMs: number | undefined;
+  const inspectFacts: InspectDeviceRuntimeFacts = async () => prepareRuntimeFacts();
+  const bindDevice: BindDeviceRuntime = async (device, use) =>
+    narrowDeviceBinding(
+      {
+        device,
+        owner: localRuntimeOwner('apple'),
+        facts: prepareRuntimeFacts(),
+        operations: {
+          prepareAppleRunner: async (input: { timeoutMs: number }) => {
+            handlerTimeoutMs = input.timeoutMs;
+            return { runner: {}, connectMs: 1, healthCheckMs: 1 };
+          },
+        },
+        [Symbol.asyncDispose]: async () => {},
+      },
+      use,
+    );
+
+  const positionals = ['ios-runner'];
+  const requestFlags: CommandFlags = {
+    udid: IOS_SIMULATOR.id,
+    platform: 'ios',
+    ...flags,
+  };
+  const response = await handlePrepareCommand({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'prepare',
+      positionals,
+      flags: requestFlags,
+    },
+    sessionName,
+    logPath: '/dev/null',
+    sessionStore,
+    inspectFacts,
+    bindDevice,
+  });
+
+  expect(response?.ok, JSON.stringify(response)).toBe(true);
+  expect(handlerTimeoutMs).toBeDefined();
+
+  const envelopeMs = resolveCommandRequestTimeoutMs(resolveCommandTimeoutPolicy('prepare'), {
+    positionals,
+    flags: requestFlags,
+  });
+  return { handlerTimeoutMs: handlerTimeoutMs!, envelopeMs };
+}
+
+test('prepare ios-runner with no --timeout keeps the daemon-result margin under the envelope', async () => {
+  const { handlerTimeoutMs, envelopeMs } = await runPrepare({});
+  expect(envelopeMs).toBeDefined();
+  expect(handlerTimeoutMs + REQUIRED_DAEMON_RESULT_MARGIN_MS).toBeLessThanOrEqual(envelopeMs!);
+});
+
+test('prepare ios-runner --timeout 300000 keeps the daemon-result margin under the envelope', async () => {
+  const { handlerTimeoutMs, envelopeMs } = await runPrepare({ timeoutMs: 300_000 });
+  expect(envelopeMs).toBeDefined();
+  expect(handlerTimeoutMs).toBe(300_000);
+  expect(handlerTimeoutMs + REQUIRED_DAEMON_RESULT_MARGIN_MS).toBeLessThanOrEqual(envelopeMs!);
+});
+
+test('prepare ios-runner --timeout 60000 keeps the daemon-result margin under the envelope', async () => {
+  const { handlerTimeoutMs, envelopeMs } = await runPrepare({ timeoutMs: 60_000 });
+  expect(envelopeMs).toBeDefined();
+  expect(handlerTimeoutMs).toBe(60_000);
+  expect(handlerTimeoutMs + REQUIRED_DAEMON_RESULT_MARGIN_MS).toBeLessThanOrEqual(envelopeMs!);
+});
diff --git a/src/daemon/handlers/session-prepare.ts b/src/daemon/handlers/session-prepare.ts
index 88e3f15623..0a6944b5fd 100644
--- a/src/daemon/handlers/session-prepare.ts
+++ b/src/daemon/handlers/session-prepare.ts
@@ -1,7 +1,7 @@
 import { prepareAppleRunnerRuntimeUse } from '@agent-device/contracts/application-lifecycle-runtime-plan';
 import type { BoundDeviceRuntime } from '@agent-device/contracts/platform-runtime';
 import { PUBLIC_COMMANDS } from '@agent-device/command-registry/catalog';
-import { PREPARE_REQUEST_TIMEOUT_MS } from '@agent-device/command-registry/timeout-policy';
+import { PREPARE_STARTUP_BUDGET_MS } from '@agent-device/command-registry/timeout-policy';
 import { publicPlatformString, type DeviceInfo } from '@agent-device/kernel/device';
 import { resolveRunnerLogicalLeaseContext } from '../lease-context.ts';
 import type { DaemonRequest, DaemonResponse } from '../daemon-request.ts';
@@ -87,7 +87,7 @@ function readPrepareIosRunnerTimeoutMs(req: DaemonRequest): number {
   const value = req.flags?.timeoutMs;
   return typeof value === 'number' && Number.isFinite(value) && value > 0
     ? value
-    : PREPARE_REQUEST_TIMEOUT_MS;
+    : PREPARE_STARTUP_BUDGET_MS;
 }
 
 function prepareIosRunnerResponseData(
diff --git a/test/integration/provider-scenarios/ios-fold.test.ts b/test/integration/provider-scenarios/ios-fold.test.ts
index 49beb7d31e..9fcd044559 100644
--- a/test/integration/provider-scenarios/ios-fold.test.ts
+++ b/test/integration/provider-scenarios/ios-fold.test.ts
@@ -1,13 +1,18 @@
 import { formatPortableActionLine, parseReplayScriptDetailed } from '@agent-device/ad-script';
+import { resolveCommandTimeoutPolicy } from '@agent-device/command-registry/registry';
+import { resolveCommandRequestTimeoutMs } from '@agent-device/command-registry/timeout-policy';
+import { MAX_FOLD_DURATION_MS } from '@agent-device/contracts/device';
+import type { AppleToolProvider } from '@agent-device/platform-apple/tool-provider';
+import type { ExecResult } from '@agent-device/host-kit/command';
 import { recordActionEntry } from '../../../src/daemon/session-action-recorder.ts';
-import { assertRpcOk } from './assertions.ts';
+import { assertRpcError, assertRpcOk } from './assertions.ts';
 import { makeIosAppSession } from '../../../src/__tests__/test-utils/session-factories.ts';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { afterEach, beforeEach, test } from 'vitest';
-import { createProviderScenarioHarness } from './harness.ts';
+import { afterEach, beforeEach, test, vi } from 'vitest';
+import { createProviderScenarioHarness, type ProviderScenarioRpcResult } from './harness.ts';
 import { createRecordingAppleToolProvider } from './providers.ts';
 import { PROVIDER_SCENARIO_IOS_SIMULATOR } from './fixtures.ts';
 
@@ -30,6 +35,38 @@ afterEach(() => {
   fs.rmSync(isolatedHome, { recursive: true, force: true });
 });
 
+/** Writes the `devicectl … displays --json-output <path>` result both fold fakes below answer. */
+function writeDisplayInventoryFixture(jsonOutputPath: string): void {
+  const displays = [0, 1].map((displayId) => ({
+    name: `LCD-${displayId}`,
+    displayId,
+    nativeSize: [2007, 2853],
+    pointScale: 3,
+    type: { integrated: {} },
+    active: displayId === 1,
+  }));
+  fs.writeFileSync(jsonOutputPath, JSON.stringify({ result: { displays } }));
+}
+
+/**
+ * Answers the host-toolchain probe (`xcodebuild -version`, `sw_vers`, `uname -m`) the fold-helper
+ * build cache (`fold-helper-cache.ts`) reads before it builds or reuses a cached binary. Both fold
+ * fakes below route these calls through the same `runCommand`.
+ */
+function toolchainProbeAnswer(cmd: string, args: readonly string[]): ExecResult | undefined {
+  if (cmd === 'xcodebuild')
+    return { stdout: 'Xcode 16.4\nBuild version 16F6', stderr: '', exitCode: 0 };
+  if (cmd === 'sw_vers') {
+    return {
+      stdout: args.includes('-buildVersion') ? '24G90' : '15.6',
+      stderr: '',
+      exitCode: 0,
+    };
+  }
+  if (cmd === 'uname') return { stdout: 'arm64', stderr: '', exitCode: 0 };
+  return undefined;
+}
+
 test('timed fold keyframes reach simulator HID through the public client and daemon', async () => {
   const trajectory = [
     { atMs: 0, angle: 0 },
@@ -49,18 +86,7 @@ test('timed fold keyframes reach simulator HID through the public client and dae
     devicectl: async (args) => {
       if (args.includes('hinge-angle')) return { ...ok, stdout: `Angle: ${angle}°`, exitCode: 1 };
       assert.ok(args.includes('displays'));
-      const displays = [0, 1].map((displayId) => ({
-        name: `LCD-${displayId}`,
-        displayId,
-        nativeSize: [2007, 2853],
-        pointScale: 3,
-        type: { integrated: {} },
-        active: displayId === 1,
-      }));
-      fs.writeFileSync(
-        args[args.indexOf('--json-output') + 1]!,
-        JSON.stringify({ result: { displays } }),
-      );
+      writeDisplayInventoryFixture(args[args.indexOf('--json-output') + 1]!);
       return ok;
     },
   });
@@ -70,17 +96,8 @@ test('timed fold keyframes reach simulator HID through the public client and dae
     appleToolProvider: () => ({
       ...tool.provider,
       runCommand: async (command, args) => {
-        if (command === 'xcodebuild') {
-          return { stdout: 'Xcode 16.4\nBuild version 16F6', stderr: '', exitCode: 0 };
-        }
-        if (command === 'sw_vers') {
-          return {
-            stdout: args.includes('-buildVersion') ? '24G90' : '15.6',
-            stderr: '',
-            exitCode: 0,
-          };
-        }
-        if (command === 'uname') return { stdout: 'arm64', stderr: '', exitCode: 0 };
+        const probeAnswer = toolchainProbeAnswer(command, args);
+        if (probeAnswer) return probeAnswer;
         assert.equal(command, 'xcrun');
         assert.ok(args.includes('clang'));
         builds++;
@@ -124,3 +141,229 @@ test('timed fold keyframes reach simulator HID through the public client and dae
     await daemon.close();
   }
 });
+
+// The fold request envelope (`FOLD_REQUEST_TIMEOUT_MS`, packages/command-registry/src/
+// timeout-policy.ts) must cover the route's worst-case wall time plus the daemon-result margin
+// (REQUEST_TIMEOUT_BUDGET_MARGIN_MS, same file), or a still-progressing fold trips the client
+// envelope and resets the daemon before the route's own typed result arrives. This test proves
+// that bound against the real route rather than a hand-summed comment: it never imports a
+// platform-apple step figure, so it stays true however the route's steps change.
+type FoldLedgerCall = Readonly<{
+  tool: 'runCommand' | 'simctl' | 'devicectl';
+  args: readonly string[];
+  timeoutMs: number;
+  graceMs?: number;
+}>;
+
+/** Two readings this far apart never settle (`IOS_FOLD_POSE_STABLE_DEGREES` is 0.5°), though each
+ * one alone matches the 100° target within it — the hinge keeps oscillating without resting. */
+function alternatingHingeAngle(readIndex: number): number {
+  return readIndex % 2 === 0 ? 99.6 : 100.4;
+}
+
+function createFoldLedgerAppleToolProvider(params: {
+  hingeAngleAt: (readIndex: number) => number;
+  onCall: (call: FoldLedgerCall) => void;
+}): { provider: AppleToolProvider; ledger: FoldLedgerCall[]; hingeReadCount: () => number } {
+  const ledger: FoldLedgerCall[] = [];
+  let hingeReads = 0;
+  const ok = { stdout: '', stderr: '', exitCode: 0 };
+  // Every real call on the fold route (packages/platform-apple/src/foldable/simulator-hid.ts,
+  // core/tool-provider.ts, core/simctl.ts) carries a bounded timeoutMs. A call reaching this fake
+  // with none is not a worst case the envelope assertion below can see, so it must fail the test
+  // rather than cost 0 virtual ms.
+  const record = (
+    tool: FoldLedgerCall['tool'],
+    args: readonly string[],
+    options?: { timeoutMs?: number; kill?: { graceMs: number } },
+  ): void => {
+    assert.ok(
+      Number.isFinite(options?.timeoutMs) && options!.timeoutMs! > 0,
+      `fold ledger call has no bounded timeoutMs: ${tool} ${args.join(' ')}`,
+    );
+    const call: FoldLedgerCall = {
+      tool,
+      args,
+      timeoutMs: options!.timeoutMs!,
+      ...(options?.kill ? { graceMs: options.kill.graceMs } : {}),
+    };
+    ledger.push(call);
+    params.onCall(call);
+  };
+  // Built on the shared recording provider so any call this route does not script (macosHelper,
+  // macosHost, plist, or an unexpected runCommand) throws instead of being silently answered.
+  const recording = createRecordingAppleToolProvider({
+    simctl: async (args, options) => {
+      record('simctl', args, options);
+      return ok;
+    },
+    devicectl: async (args, options) => {
+      record('devicectl', args, options);
+      if (args.includes('hinge-angle')) {
+        const angle = params.hingeAngleAt(hingeReads);
+        hingeReads += 1;
+        return { ...ok, stdout: `Angle: ${angle}°`, exitCode: 1 };
+      }
+      assert.ok(args.includes('displays'), `unexpected devicectl call: ${args.join(' ')}`);
+      writeDisplayInventoryFixture(args[args.indexOf('--json-output') + 1]!);
+      return ok;
+    },
+  });
+  const provider: AppleToolProvider = {
+    ...recording.provider,
+    runCommand: async (cmd, args, options) => {
+      record('runCommand', [cmd, ...args], options);
+      const probeAnswer = toolchainProbeAnswer(cmd, args);
+      if (probeAnswer) return probeAnswer;
+      assert.equal(cmd, 'xcrun', `unexpected runCommand call: ${cmd} ${args.join(' ')}`);
+      assert.ok(args.includes('clang'), `unexpected xcrun call: ${args.join(' ')}`);
+      fs.writeFileSync(args.at(-1)!, 'fold-helper-binary');
+      return ok;
+    },
+  };
+  return { provider, ledger, hingeReadCount: () => hingeReads };
+}
+
+/**
+ * Runs `fn` under its own throwaway `HOME`, so the fold-helper build cache under it
+ * (`~/.agent-device/fold-helper`) starts empty: the calibration and measured ledger runs each
+ * need a cold cache, not the outer per-test `HOME` the file's `beforeEach` already scoped, because
+ * a warm cache would skip the build phase and shrink the measured ledger.
+ */
+async function withColdFoldHelperCache<T>(fn: () => Promise<T>): Promise<T> {
+  const outerHome = process.env.HOME;
+  const runHome = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-fold-run-home-'));
+  process.env.HOME = runHome;
+  try {
+    return await fn();
+  } finally {
+    if (outerHome === undefined) delete process.env.HOME;
+    else process.env.HOME = outerHome;
+    fs.rmSync(runHome, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Runs one cold fold through the public client and daemon against a fake Apple tool provider that
+ * records `{ tool, args, timeoutMs, graceMs }` per call. When `withVirtualClock` is set, `Date.now`
+ * is spied so every deadline the route reads (host-kit `Deadline`, snapshot-source/deadline.ts)
+ * sees each call as having spent `timeoutMs - 1` plus any kill grace: the worst case that still
+ * succeeds, never an actual timeout.
+ */
+async function runFoldLedgerScenario(params: {
+  hingeAngleAt: (readIndex: number) => number;
+  withVirtualClock: boolean;
+}): Promise<{
+  response: ProviderScenarioRpcResult;
+  ledger: FoldLedgerCall[];
+  hingeReadCount: number;
+  virtualElapsedMs: number;
+}> {
+  return withColdFoldHelperCache(async () => {
+    const trajectory = [
+      { atMs: 0, angle: 0 },
+      { atMs: MAX_FOLD_DURATION_MS, angle: 100 },
+    ];
+    let virtualElapsedMs = 0;
+    const originNowMs = Date.now();
+    const dateSpy = params.withVirtualClock
+      ? vi.spyOn(Date, 'now').mockImplementation(() => originNowMs + virtualElapsedMs)
+      : undefined;
+    const { provider, ledger, hingeReadCount } = createFoldLedgerAppleToolProvider({
+      hingeAngleAt: params.hingeAngleAt,
+      onCall: (call) => {
+        virtualElapsedMs += Math.max(0, call.timeoutMs - 1) + (call.graceMs ?? 0);
+      },
+    });
+    const daemon = await createProviderScenarioHarness({
+      deviceInventoryProvider: async () => [PROVIDER_SCENARIO_IOS_SIMULATOR],
+      appleToolProvider: () => provider,
+    });
+    daemon.setSession(
+      'default',
+      makeIosAppSession('default', { device: PROVIDER_SCENARIO_IOS_SIMULATOR }),
+    );
+    try {
+      const response = await daemon.callCommand('fold', [], {
+        platform: 'ios',
+        udid: PROVIDER_SCENARIO_IOS_SIMULATOR.id,
+        keyframes: JSON.stringify(trajectory),
+      });
+      return { response, ledger, hingeReadCount: hingeReadCount(), virtualElapsedMs };
+    } finally {
+      dateSpy?.mockRestore();
+      await daemon.close();
+    }
+  });
+}
+
+function assertFoldLedgerPhaseCoverage(ledger: readonly FoldLedgerCall[]): void {
+  const isBuild = (call: FoldLedgerCall) =>
+    call.tool === 'runCommand' && call.args.includes('clang');
+  const isSpawn = (call: FoldLedgerCall) => call.tool === 'simctl' && call.args.includes('spawn');
+  const isHingeRead = (call: FoldLedgerCall) =>
+    call.tool === 'devicectl' && call.args.includes('hinge-angle');
+  const isDisplayInventory = (call: FoldLedgerCall) =>
+    call.tool === 'devicectl' && call.args.includes('displays');
+
+  assert.ok(ledger.some(isBuild), 'ledger is missing the helper-build phase');
+  assert.ok(ledger.some(isSpawn), 'ledger is missing the HID-dispatch (simctl spawn) phase');
+  assert.ok(ledger.some(isHingeRead), 'ledger is missing the hinge-settle-read phase');
+  assert.equal(
+    ledger.filter(isDisplayInventory).length,
+    2,
+    'ledger must record both the foldable-check and the lit-panel display inventory reads',
+  );
+}
+
+test('fold worst-case ledger covers the client envelope with the daemon-result margin', async () => {
+  // Matches REQUEST_TIMEOUT_BUDGET_MARGIN_MS, packages/command-registry/src/timeout-policy.ts.
+  // Not imported: it is not exported (fallow would flag an export used only by a test).
+  const REQUIRED_DAEMON_RESULT_MARGIN_MS = 30_000;
+
+  // Calibration: learns the route's settle-attempt budget (N) instead of assuming it. Needs no
+  // virtual clock, because only the read count is asserted here.
+  const calibration = await runFoldLedgerScenario({
+    hingeAngleAt: alternatingHingeAngle,
+    withVirtualClock: false,
+  });
+  const calibrationError = assertRpcError(
+    calibration.response,
+    'COMMAND_FAILED',
+    /did not settle/,
+  ) as { details?: { reason?: unknown } };
+  assert.equal(calibrationError.details?.reason, 'fold-pose-unsettled');
+  const settleAttempts = calibration.hingeReadCount;
+  assert.ok(
+    settleAttempts >= 2,
+    `calibration run made ${settleAttempts} hinge reads; expected at least 2`,
+  );
+
+  // Measured: the same alternation for every read but the last, which lands exactly on target so
+  // the route settles on the very last read it allows — the worst case that still succeeds.
+  const measured = await runFoldLedgerScenario({
+    hingeAngleAt: (readIndex) =>
+      readIndex === settleAttempts - 1 ? 100 : alternatingHingeAngle(readIndex),
+    withVirtualClock: true,
+  });
+  const measuredData = assertRpcOk(measured.response);
+  assert.equal(measuredData.hingeAngleDegrees, 100);
+  assert.equal(
+    measured.hingeReadCount,
+    settleAttempts,
+    'the measured run must make exactly as many hinge reads as the calibration run',
+  );
+
+  assertFoldLedgerPhaseCoverage(measured.ledger);
+
+  const envelopeMs = resolveCommandRequestTimeoutMs(resolveCommandTimeoutPolicy('fold'), {
+    positionals: [],
+    flags: {},
+  });
+  assert.ok(envelopeMs !== undefined, 'fold must declare a bounded envelope');
+  assert.ok(
+    measured.virtualElapsedMs + REQUIRED_DAEMON_RESULT_MARGIN_MS <= envelopeMs!,
+    `fold ledger worst case (${measured.virtualElapsedMs}ms) + ${REQUIRED_DAEMON_RESULT_MARGIN_MS}ms margin ` +
+      `exceeds the ${envelopeMs}ms envelope.\nLedger:\n${JSON.stringify(measured.ledger, null, 2)}`,
+  );
+}, 20_000);

From 4260aa756c62edf2e004bd58d9ebdec78103e13d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 24 Sep 2026 19:41:42 +0200
Subject: [PATCH 111/132] fix(android): return from an app open only after the
 launched app is readable (#2895)

* fix(android): return from an app open only after the launched app is readable

am start -W returns when the activity draws its first frame, which can be a
splash or an empty root while a React Native app still mounts. The first
capture after a cold open --relaunch then saw a content-poor tree and spent
its own budget on re-captures. The open now captures the launched app through
the interactor snapshot path, whose content verdict and bounded re-capture
decide readiness, and reports postOpenObservation. An app that stays
unreadable, or a failed capture, still opens as unobservable.

Refs #1571 (iOS half: #2838).

* fix(android): bound and type the launch observation of an app open

The open's launch capture now runs behind an injected launch observation
port with a fixed 6 s window of its own, separate from the caller's
cancellation. Only a content verdict, a system surface over the app, or
the window running out reads as unobservable. Any other capture failure
is a typed probe-failed result that the open reports and survives.

The capture is transient: it borrows a running helper session and stops
only a session it started, installs no helper, and does not retire the
helper after a content verdict. A URL open reports no observation, and
an app open whose package cannot be read reports app-unidentified.
PostOpenObservation is one documented union in the lifecycle contract,
shared with the Apple owner.

Refs #1571

* fix(android): let the launch settle window end re-captures, never helper work

The open's 6 s window reached the snapshot helper as an abort, so a
window that closed during a cold helper start or a borrowed capture tore
the helper down and left the next read to recover it. The window is now a
settle deadline on the transient capture: the content re-capture loop
starts no attempt after it, while helper start, capture and teardown keep
their own budgets and only the caller's signal cancels them.

The transient read replaces the injected port, the borrow session scope
and the interactor-side install mapping: the capture itself keeps a session
it found, releases one it started, installs no helper and does not retire
it after a content verdict.

Refs #1571

* fix(android): keep a missing-helper refusal out of capture failure recovery

A transient capture on a device without the current helper refused at the
install check, and that refusal went through the capture failure handler,
which logged an error and force-stopped the helper runtime on every new
device's first open. The refusal now reaches the caller directly.

The transient-capture tests move to their own file, so snapshot.test.ts
stays under the test-file size ratchet.

Refs #1571
---
 .../src/application-lifecycle-runtime.ts      |  35 ++-
 packages/contracts/src/interactor-types.ts    |   6 +
 .../__tests__/snapshot-helper-install.test.ts |  25 ++
 .../snapshot-helper-session.fixtures.ts       |  75 +++---
 .../snapshot-transient-capture.test.ts        | 217 ++++++++++++++++++
 .../src/__tests__/snapshot.test.ts            |  13 +-
 .../src/launch-observation.test.ts            | 167 ++++++++++++++
 .../src/launch-observation.ts                 |  54 +++++
 .../platform-android/src/lifecycle.test.ts    | 155 +++++++++++--
 packages/platform-android/src/lifecycle.ts    |  25 +-
 .../src/snapshot-helper-install.ts            |  21 +-
 .../src/snapshot-helper-types.ts              |   7 +-
 packages/platform-android/src/snapshot.ts     |  72 ++++--
 .../src/snapshot-observability.ts             |  14 +-
 src/core/interactors/android.test.ts          |  17 ++
 src/core/interactors/android.ts               |   1 +
 .../android-test-suite.test.ts                |  22 +-
 .../provider-scenarios/android-world.ts       |   4 +
 18 files changed, 841 insertions(+), 89 deletions(-)
 create mode 100644 packages/platform-android/src/__tests__/snapshot-transient-capture.test.ts
 create mode 100644 packages/platform-android/src/launch-observation.test.ts
 create mode 100644 packages/platform-android/src/launch-observation.ts

diff --git a/packages/contracts/src/application-lifecycle-runtime.ts b/packages/contracts/src/application-lifecycle-runtime.ts
index f13cb2347d..98504a649b 100644
--- a/packages/contracts/src/application-lifecycle-runtime.ts
+++ b/packages/contracts/src/application-lifecycle-runtime.ts
@@ -124,8 +124,39 @@ export type OpenApplicationTiming = Readonly<{
   openDispatchDurationMs?: number;
   launchUrlDurationMs?: number;
   postOpenSettleDurationMs?: number;
-  /** What a Simulator open learned about the launched app before returning (see the Apple owner). */
-  postOpenObservation?: 'observable' | 'unobservable' | 'not-eligible';
+  /** Unset when the open had no launched app to observe, such as a URL or deep-link target. */
+  postOpenObservation?: PostOpenObservation;
+  /** Why the observation could not run; present exactly when it is `probe-failed`. */
+  postOpenObservationFailure?: PostOpenObservationFailure;
+}>;
+
+/**
+ * What an app open learned about the launched app before it returned. A local iOS Simulator asks
+ * its host AX bridge; a local Android device captures the app through the snapshot helper. Each
+ * owner bounds the observation, and the open succeeds whatever the value is.
+ *
+ * - `observable`: the launched app's tree was readable.
+ * - `unobservable`: the app stayed unreadable within the owner's bounded window: a launch transition
+ *   or AX-server state that did not clear, a system surface over the app, a content verdict after
+ *   the capture's own re-captures, or the window ran out.
+ * - `probe-failed`: the observation could not run (Android: the helper is not installed at the
+ *   current version, or adb or the accessibility service failed). `postOpenObservationFailure`
+ *   carries the typed failure.
+ * - `app-unidentified`: the open targeted an app, but the owner could not read which package it
+ *   launched, so nothing was observed.
+ * - `not-eligible`: the device has no observation path.
+ */
+export type PostOpenObservation =
+  | 'observable'
+  | 'unobservable'
+  | 'probe-failed'
+  | 'app-unidentified'
+  | 'not-eligible';
+
+/** The typed failure of a `probe-failed` observation: the error code and its typed reason. */
+export type PostOpenObservationFailure = Readonly<{
+  code: string;
+  reason?: string;
 }>;
 
 export type OpenApplicationOutcome = Readonly<{
diff --git a/packages/contracts/src/interactor-types.ts b/packages/contracts/src/interactor-types.ts
index d6905eee8f..15670d675b 100644
--- a/packages/contracts/src/interactor-types.ts
+++ b/packages/contracts/src/interactor-types.ts
@@ -175,6 +175,12 @@ export type SnapshotOptions = BaseSnapshotOptions & {
   surface?: SessionSurface;
   /** Internal capture purpose; action outcomes always require the full tree. */
   acquisitionIntent?: 'full' | 'surface-observation';
+  /**
+   * A one-off read, such as an open's launch observation. It may use a capture host the session
+   * already keeps warm, but it never installs one or leaves running one that it started. It starts
+   * no re-capture after `settleBy` (epoch ms); only `signal` cancels work already started.
+   */
+  transient?: Readonly<{ settleBy: number }>;
 };
 
 /**
diff --git a/packages/platform-android/src/__tests__/snapshot-helper-install.test.ts b/packages/platform-android/src/__tests__/snapshot-helper-install.test.ts
index 2f7a66405f..d3f31e17a9 100644
--- a/packages/platform-android/src/__tests__/snapshot-helper-install.test.ts
+++ b/packages/platform-android/src/__tests__/snapshot-helper-install.test.ts
@@ -86,6 +86,31 @@ test('an exec-shaped helper install timeout names the dialog, not a wedged adb s
   );
 });
 
+test('a current-only helper check refuses a missing helper without installing it', async () => {
+  const apkPath = await writeHelperApk('snapshot-helper-current-only-');
+  let installs = 0;
+  const adbProvider = missingPackageProvider(async () => {
+    installs += 1;
+    return { exitCode: 0, stdout: 'Success', stderr: '' };
+  });
+
+  await assert.rejects(
+    () =>
+      ensureAndroidSnapshotHelper({
+        adb: adbProvider.exec,
+        adbProvider,
+        artifact: { apkPath, manifest: { ...manifest, sha256: sha256Text('helper-apk') } },
+        deviceKey: 'android:emulator-5554',
+        installPolicy: 'current-only',
+      }),
+    (error) => {
+      assert.equal((error as AppError).details?.reason, 'android-snapshot-helper-not-current');
+      return true;
+    },
+  );
+  assert.equal(installs, 0);
+});
+
 function adbInstallTimeout(): AppError {
   // An unattended first install on ColorOS: adb blocks on the system install-confirmation dialog
   // and the exec layer kills the command, so stdout/stderr stay empty.
diff --git a/packages/platform-android/src/__tests__/snapshot-helper-session.fixtures.ts b/packages/platform-android/src/__tests__/snapshot-helper-session.fixtures.ts
index ac00d736f8..181f5846e2 100644
--- a/packages/platform-android/src/__tests__/snapshot-helper-session.fixtures.ts
+++ b/packages/platform-android/src/__tests__/snapshot-helper-session.fixtures.ts
@@ -62,6 +62,10 @@ export type PersistentSnapshotHelperProviderOptions = {
   oneShotXml?: string;
   /** Make the device-side stop fail the way an unhealthy transport answers. */
   runtimeStopFailure?: boolean;
+  /** How long a started session takes to report ready. */
+  sessionReadyDelayMs?: number;
+  /** How long a session takes to answer its `snapshotCount`th capture. */
+  captureResponseDelayMs?: (snapshotCount: number) => number;
 };
 
 export function createPersistentSnapshotHelperProvider(
@@ -104,36 +108,40 @@ export function createPersistentSnapshotHelperProvider(
           const body = options.sessionXml
             ? options.sessionXml(sessionIndex, snapshotCount)
             : `<hierarchy><node text="persistent helper snapshot ${snapshotCount}" bounds="[0,0][10,10]" /></hierarchy>`;
-          socket.end(
-            sessionResponse({
-              requestId,
-              body,
-              metadata: {
-                waitForIdleTimeoutMs: '500',
-                waitForIdleQuietMs: '100',
-                timeoutMs: '5000',
-                maxDepth: '128',
-                maxNodes: '5000',
-                rootPresent: 'true',
-                captureMode: 'interactive-windows',
-                windowCount: '1',
-                nodeCount: '1',
-                truncated: 'false',
-                elapsedMs: '8',
-              },
-            }),
-          );
+          const answer = () =>
+            socket.end(
+              sessionResponse({
+                requestId,
+                body,
+                metadata: {
+                  waitForIdleTimeoutMs: '500',
+                  waitForIdleQuietMs: '100',
+                  timeoutMs: '5000',
+                  maxDepth: '128',
+                  maxNodes: '5000',
+                  rootPresent: 'true',
+                  captureMode: 'interactive-windows',
+                  windowCount: '1',
+                  nodeCount: '1',
+                  truncated: 'false',
+                  elapsedMs: '8',
+                },
+              }),
+            );
+          setTimeout(answer, options.captureResponseDelayMs?.(snapshotCount) ?? 0);
         });
       });
       server.listen(port, '127.0.0.1', () => {
-        process.stdout.write(
-          [
-            'INSTRUMENTATION_STATUS: agentDeviceProtocol=android-snapshot-helper-v1',
-            'INSTRUMENTATION_STATUS: sessionReady=true',
-            'INSTRUMENTATION_STATUS_CODE: 2',
-            '',
-          ].join('\n'),
-        );
+        setTimeout(() => {
+          process.stdout.write(
+            [
+              'INSTRUMENTATION_STATUS: agentDeviceProtocol=android-snapshot-helper-v1',
+              'INSTRUMENTATION_STATUS: sessionReady=true',
+              'INSTRUMENTATION_STATUS_CODE: 2',
+              '',
+            ].join('\n'),
+          );
+        }, options.sessionReadyDelayMs ?? 0);
       });
       process.onKill = () => {
         server.close(() => process.emitExit(0, null));
@@ -513,3 +521,16 @@ function readSessionPort(args: readonly string[]): number {
   assert.notEqual(index, -1);
   return Number(args[index + 1]);
 }
+
+/** A capture holding only system-UI chrome: the helper answered, but no app content. */
+export function androidSystemWindowOnlyXml(): string {
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<hierarchy rotation="0">',
+    '  <node window-index="0" window-type="3" window-layer="30" window-active="true" window-focused="true" class="android.widget.FrameLayout" package="com.android.systemui" bounds="[0,0][390,844]" enabled="true" visible-to-user="true">',
+    '    <node content-desc="Back" class="android.widget.ImageButton" package="com.android.systemui" bounds="[0,792][96,844]" clickable="true" enabled="true" focusable="true" visible-to-user="true" />',
+    '    <node content-desc="Home" class="android.widget.ImageButton" package="com.android.systemui" bounds="[147,792][243,844]" clickable="true" enabled="true" focusable="true" visible-to-user="true" />',
+    '  </node>',
+    '</hierarchy>',
+  ].join('\n');
+}
diff --git a/packages/platform-android/src/__tests__/snapshot-transient-capture.test.ts b/packages/platform-android/src/__tests__/snapshot-transient-capture.test.ts
new file mode 100644
index 0000000000..b76e1d8f5e
--- /dev/null
+++ b/packages/platform-android/src/__tests__/snapshot-transient-capture.test.ts
@@ -0,0 +1,217 @@
+import { afterEach, beforeEach, test, vi } from 'vitest';
+import assert from 'node:assert/strict';
+
+vi.mock('../adb.ts', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../adb.ts')>();
+  return { ...actual, sleep: vi.fn(async () => {}) };
+});
+
+import { isUnreadableCaptureContentError } from '@agent-device/contracts/android-snapshot-quality';
+import type { DeviceInfo } from '@agent-device/kernel/device';
+import type { AppError } from '@agent-device/kernel/errors';
+import { snapshotAndroid } from '../snapshot.ts';
+import { resetAndroidSnapshotHelperInstallCache } from '../snapshot-helper-install.ts';
+import { resetAndroidSnapshotHelperSessions } from '../snapshot-helper-session-lifecycle.ts';
+import type { AndroidAdbExecutor } from '../snapshot-helper.ts';
+import { ANDROID_SNAPSHOT_HELPER_FIXTURE_ARTIFACT } from './test-utils/android-snapshot-helper.ts';
+import {
+  androidSystemWindowOnlyXml,
+  createPersistentSnapshotHelperProvider,
+  isAndroidHelperRuntimeForceStop as isHelperRuntimeReset,
+  type FakeAndroidProcess,
+} from './snapshot-helper-session.fixtures.ts';
+
+const device: DeviceInfo = {
+  platform: 'android',
+  id: 'emulator-5554',
+  name: 'Pixel',
+  kind: 'emulator',
+  booted: true,
+};
+
+const helperArtifact = ANDROID_SNAPSHOT_HELPER_FIXTURE_ARTIFACT;
+
+beforeEach(async () => {
+  await resetAndroidSnapshotHelperSessions();
+  resetAndroidSnapshotHelperInstallCache();
+});
+
+afterEach(async () => {
+  await resetAndroidSnapshotHelperSessions();
+});
+
+function openSettleWindow(): { settleBy: number } {
+  return { settleBy: Date.now() + 60_000 };
+}
+
+function isHelperVersionProbe(args: readonly string[]): boolean {
+  return args.includes('--show-versioncode');
+}
+
+test('a transient capture releases a helper session it had to start', async () => {
+  const adbCalls: (readonly string[])[] = [];
+  const spawnArgs: (readonly string[])[] = [];
+  const processes: FakeAndroidProcess[] = [];
+  const provider = createPersistentSnapshotHelperProvider({
+    calls: adbCalls,
+    spawnArgs,
+    processes,
+  });
+
+  await snapshotAndroid(device, {
+    helperAdb: provider,
+    helperArtifact,
+    transient: openSettleWindow(),
+  });
+
+  assert.equal(spawnArgs.length, 1);
+  assert.equal(processes[0]?.exitCode, 0);
+  assert.equal(
+    adbCalls.some((args) => args[0] === 'forward' && args[1] === '--remove'),
+    true,
+  );
+});
+
+test('a transient capture leaves a warm daemon-session helper running', async () => {
+  const adbCalls: (readonly string[])[] = [];
+  const spawnArgs: (readonly string[])[] = [];
+  const processes: FakeAndroidProcess[] = [];
+  const provider = createPersistentSnapshotHelperProvider({
+    calls: adbCalls,
+    spawnArgs,
+    processes,
+  });
+
+  await snapshotAndroid(device, {
+    helperAdb: provider,
+    helperArtifact,
+    helperSessionScope: 'daemon-session',
+  });
+  const borrowed = await snapshotAndroid(device, {
+    helperAdb: provider,
+    helperArtifact,
+    transient: openSettleWindow(),
+  });
+
+  assert.equal(borrowed.androidSnapshot.helperSessionReused, true);
+  assert.equal(spawnArgs.length, 1);
+  assert.equal(processes[0]?.exitCode, null);
+  assert.equal(
+    adbCalls.some((args) => args[0] === 'forward' && args[1] === '--remove'),
+    false,
+  );
+});
+
+test('a transient capture reports its content verdict without retiring the warm helper', async () => {
+  const adbCalls: (readonly string[])[] = [];
+  const spawnArgs: (readonly string[])[] = [];
+  const processes: FakeAndroidProcess[] = [];
+  const provider = createPersistentSnapshotHelperProvider({
+    calls: adbCalls,
+    spawnArgs,
+    processes,
+    sessionXml: (_sessionIndex, snapshotCount) =>
+      snapshotCount === 1
+        ? '<hierarchy><node text="warm helper" bounds="[0,0][10,10]" /></hierarchy>'
+        : androidSystemWindowOnlyXml(),
+  });
+  await snapshotAndroid(device, {
+    helperAdb: provider,
+    helperArtifact,
+    helperSessionScope: 'daemon-session',
+  });
+
+  await assert.rejects(
+    snapshotAndroid(device, { helperAdb: provider, helperArtifact, transient: openSettleWindow() }),
+    (error: unknown) => isUnreadableCaptureContentError(error),
+  );
+
+  assert.equal(processes[0]?.exitCode, null, 'the session helper is still running');
+  assert.equal(adbCalls.some(isHelperRuntimeReset), false);
+  assert.equal(spawnArgs.length, 1);
+});
+
+test('a settle window that passes during the helper start never cancels the start', async () => {
+  const adbCalls: (readonly string[])[] = [];
+  const spawnArgs: (readonly string[])[] = [];
+  const processes: FakeAndroidProcess[] = [];
+  const provider = createPersistentSnapshotHelperProvider({
+    calls: adbCalls,
+    spawnArgs,
+    processes,
+    sessionXml: () => androidSystemWindowOnlyXml(),
+    sessionReadyDelayMs: 150,
+  });
+
+  await assert.rejects(
+    snapshotAndroid(device, {
+      helperAdb: provider,
+      helperArtifact,
+      transient: { settleBy: Date.now() + 30 },
+    }),
+    (error: unknown) =>
+      isUnreadableCaptureContentError(error) && (error as AppError).details?.attempts === 1,
+  );
+
+  assert.equal(spawnArgs.length, 1);
+  assert.equal(processes[0]?.killed, false, 'the started helper was not signalled');
+  assert.equal(processes[0]?.exitCode, 0, 'the started helper quit on its own');
+  assert.equal(adbCalls.some(isHelperRuntimeReset), false);
+});
+
+test('a settle window that passes during a warm session capture leaves the session running', async () => {
+  const adbCalls: (readonly string[])[] = [];
+  const spawnArgs: (readonly string[])[] = [];
+  const processes: FakeAndroidProcess[] = [];
+  const provider = createPersistentSnapshotHelperProvider({
+    calls: adbCalls,
+    spawnArgs,
+    processes,
+    sessionXml: (_sessionIndex, snapshotCount) =>
+      snapshotCount === 1
+        ? '<hierarchy><node text="warm helper" bounds="[0,0][10,10]" /></hierarchy>'
+        : androidSystemWindowOnlyXml(),
+    captureResponseDelayMs: (snapshotCount) => (snapshotCount === 1 ? 0 : 150),
+  });
+  await snapshotAndroid(device, {
+    helperAdb: provider,
+    helperArtifact,
+    helperSessionScope: 'daemon-session',
+  });
+
+  await assert.rejects(
+    snapshotAndroid(device, {
+      helperAdb: provider,
+      helperArtifact,
+      transient: { settleBy: Date.now() + 30 },
+    }),
+    (error: unknown) =>
+      isUnreadableCaptureContentError(error) && (error as AppError).details?.attempts === 1,
+  );
+
+  assert.equal(spawnArgs.length, 1);
+  assert.equal(processes[0]?.killed, false);
+  assert.equal(processes[0]?.exitCode, null, 'the session helper is still running');
+  assert.equal(adbCalls.some(isHelperRuntimeReset), false);
+});
+
+test('a transient capture on a device without the current helper installs and resets nothing', async () => {
+  const adbCalls: (readonly string[])[] = [];
+  const helperAdb: AndroidAdbExecutor = async (args) => {
+    adbCalls.push(args);
+    if (isHelperVersionProbe(args)) return { exitCode: 1, stdout: '', stderr: 'not found' };
+    return { exitCode: 0, stdout: '', stderr: '' };
+  };
+
+  await assert.rejects(
+    snapshotAndroid(device, { helperAdb, helperArtifact, transient: openSettleWindow() }),
+    (error: unknown) =>
+      (error as AppError).details?.reason === 'android-snapshot-helper-not-current',
+  );
+
+  assert.equal(
+    adbCalls.some((args) => args.includes('install') || args.includes('instrument')),
+    false,
+  );
+  assert.equal(adbCalls.some(isHelperRuntimeReset), false, 'a refusal is not a helper failure');
+});
diff --git a/packages/platform-android/src/__tests__/snapshot.test.ts b/packages/platform-android/src/__tests__/snapshot.test.ts
index 2930772704..c1c05f7f07 100644
--- a/packages/platform-android/src/__tests__/snapshot.test.ts
+++ b/packages/platform-android/src/__tests__/snapshot.test.ts
@@ -34,6 +34,7 @@ import {
   createPersistentSnapshotHelperProvider,
   isAndroidHelperRuntimeForceStop as isHelperRuntimeReset,
   ANDROID_HELPER_INSTALLED_VERSION_PROBE as installedHelperProbe,
+  androidSystemWindowOnlyXml,
   type FakeAndroidProcess,
 } from './snapshot-helper-session.fixtures.ts';
 import { withAndroidAdbProvider, type AndroidAdbProvider } from '../adb-executor.ts';
@@ -188,18 +189,6 @@ test('screenshotAndroid throws when PNG payload is truncated', async () => {
   });
 });
 
-function androidSystemWindowOnlyXml(): string {
-  return [
-    '<?xml version="1.0" encoding="UTF-8"?>',
-    '<hierarchy rotation="0">',
-    '  <node window-index="0" window-type="3" window-layer="30" window-active="true" window-focused="true" class="android.widget.FrameLayout" package="com.android.systemui" bounds="[0,0][390,844]" enabled="true" visible-to-user="true">',
-    '    <node content-desc="Back" class="android.widget.ImageButton" package="com.android.systemui" bounds="[0,792][96,844]" clickable="true" enabled="true" focusable="true" visible-to-user="true" />',
-    '    <node content-desc="Home" class="android.widget.ImageButton" package="com.android.systemui" bounds="[147,792][243,844]" clickable="true" enabled="true" focusable="true" visible-to-user="true" />',
-    '  </node>',
-    '</hierarchy>',
-  ].join('\n');
-}
-
 function androidContentPoorFabricAppWindowXml(): string {
   return [
     '<?xml version="1.0" encoding="UTF-8"?>',
diff --git a/packages/platform-android/src/launch-observation.test.ts b/packages/platform-android/src/launch-observation.test.ts
new file mode 100644
index 0000000000..58ae7abc1b
--- /dev/null
+++ b/packages/platform-android/src/launch-observation.test.ts
@@ -0,0 +1,167 @@
+import crypto from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { expect, test } from 'vitest';
+import './__tests__/test-utils/android-host-test-setup.ts';
+import type { Interactor, SnapshotOptions } from '@agent-device/contracts/interactor-types';
+import { AppError, createRequestCanceledError } from '@agent-device/kernel/errors';
+import { mkdtempForTest } from './__tests__/test-utils/tmp-dir.ts';
+import { ANDROID_LAUNCH_SETTLE_WINDOW_MS, observeAndroidLaunch } from './launch-observation.ts';
+import { androidHelperContentUnavailableError } from './snapshot.ts';
+import {
+  ensureAndroidSnapshotHelper,
+  resetAndroidSnapshotHelperInstallCache,
+} from './snapshot-helper-install.ts';
+
+type ObserveFixture = Readonly<{
+  snapshotOptions: SnapshotOptions[];
+  observe: (signal?: AbortSignal) => ReturnType<typeof observeAndroidLaunch>;
+}>;
+
+function createObservation(
+  snapshot: (options: SnapshotOptions) => Promise<unknown>,
+): ObserveFixture {
+  const snapshotOptions: SnapshotOptions[] = [];
+  const interactor = {
+    snapshot: async (options: SnapshotOptions) => {
+      snapshotOptions.push(options);
+      return await snapshot(options);
+    },
+  } as unknown as Pick<Interactor, 'snapshot'>;
+  return {
+    snapshotOptions,
+    observe: async (signal = new AbortController().signal) =>
+      await observeAndroidLaunch(interactor, 'com.example.app', signal),
+  };
+}
+
+/** What the capture throws once its re-captures still see an unmounted app. */
+function contentVerdict(): AppError {
+  return androidHelperContentUnavailableError(
+    {
+      reason: 'content-poor-app-window',
+      failureReason: 'Android snapshot helper returned insufficient foreground app content',
+      diagnostics: {
+        helperNodeCount: 3,
+        helperSystemUiNodeCount: 0,
+        helperWindowRootCount: 1,
+        helperApplicationWindowRootCount: 1,
+        helperMeaningfulNodeCount: 0,
+        helperApplicationMeaningfulNodeCount: 0,
+        helperNonSystemMeaningfulNodeCount: 0,
+        helperInputMethodMeaningfulNodeCount: 0,
+        helperWindowTypes: [1],
+      },
+    },
+    3,
+  );
+}
+
+/** What a transient capture's install step throws on a device without the current helper. */
+async function helperNotCurrentError(): Promise<unknown> {
+  resetAndroidSnapshotHelperInstallCache();
+  const apkPath = path.join(await mkdtempForTest('launch-observation-helper-'), 'helper.apk');
+  await fs.writeFile(apkPath, 'helper-apk');
+  const sha256 = crypto.createHash('sha256').update('helper-apk').digest('hex');
+  try {
+    await ensureAndroidSnapshotHelper({
+      adb: async () => ({ exitCode: 1, stdout: '', stderr: 'not found' }),
+      artifact: {
+        apkPath,
+        manifest: {
+          name: 'android-snapshot-helper',
+          version: '0.13.3',
+          apkUrl: null,
+          sha256,
+          packageName: 'com.callstack.agentdevice.snapshothelper',
+          versionCode: 13003,
+          instrumentationRunner:
+            'com.callstack.agentdevice.snapshothelper/.SnapshotInstrumentation',
+          minSdk: 23,
+          targetSdk: 36,
+          outputFormat: 'uiautomator-xml',
+          statusProtocol: 'android-snapshot-helper-v1',
+        },
+      },
+      deviceKey: 'android:emulator-5554',
+      installPolicy: 'current-only',
+    });
+  } catch (error) {
+    return error;
+  }
+  throw new Error('a current-only check on a device without the helper must reject');
+}
+
+test('a readable launched app is observable through one transient capture', async () => {
+  const observation = createObservation(async () => ({ nodes: [] }));
+  const startedAt = Date.now();
+
+  await expect(observation.observe()).resolves.toEqual({ observation: 'observable' });
+  expect(observation.snapshotOptions).toHaveLength(1);
+  const settleBy = observation.snapshotOptions[0]?.transient?.settleBy ?? 0;
+  expect(settleBy - startedAt).toBeGreaterThanOrEqual(ANDROID_LAUNCH_SETTLE_WINDOW_MS);
+  expect(settleBy - Date.now()).toBeLessThanOrEqual(ANDROID_LAUNCH_SETTLE_WINDOW_MS);
+});
+
+test('the capture runs under the caller signal alone, so the window never cancels it', async () => {
+  const observation = createObservation(async () => ({ nodes: [] }));
+  const signal = new AbortController().signal;
+
+  await observation.observe(signal);
+
+  expect(observation.snapshotOptions[0]?.signal).toBe(signal);
+});
+
+test('a content verdict after the capture re-captures is unobservable', async () => {
+  const observation = createObservation(async () => {
+    throw contentVerdict();
+  });
+
+  await expect(observation.observe()).resolves.toEqual({ observation: 'unobservable' });
+});
+
+test('a system surface covering the launched app is unobservable', async () => {
+  const observation = createObservation(async () => ({
+    nodes: [],
+    androidSnapshot: { backend: 'android-helper', systemSurfaceOnly: true },
+  }));
+
+  await expect(observation.observe()).resolves.toEqual({ observation: 'unobservable' });
+});
+
+test('a capture mechanism failure is a failed probe with its typed reason', async () => {
+  const observation = createObservation(async () => {
+    throw new AppError('COMMAND_FAILED', 'Android snapshot helper failed: accessibility timeout', {
+      androidSnapshotHelperFailureReason: 'Android snapshot helper failed: accessibility timeout',
+      androidCaptureFailureReason: 'accessibility-timeout',
+    });
+  });
+
+  await expect(observation.observe()).resolves.toEqual({
+    observation: 'probe-failed',
+    failure: { code: 'COMMAND_FAILED', reason: 'accessibility-timeout' },
+  });
+});
+
+test('a device without the current helper is a failed probe', async () => {
+  const notCurrent = await helperNotCurrentError();
+  const observation = createObservation(async () => {
+    throw notCurrent;
+  });
+
+  await expect(observation.observe()).resolves.toEqual({
+    observation: 'probe-failed',
+    failure: { code: 'COMMAND_FAILED', reason: 'android-snapshot-helper-not-current' },
+  });
+});
+
+test('a cancelled open rejects with its cancellation, not an observation', async () => {
+  const controller = new AbortController();
+  const canceled = createRequestCanceledError();
+  const observation = createObservation(async () => {
+    controller.abort(canceled);
+    throw canceled;
+  });
+
+  await expect(observation.observe(controller.signal)).rejects.toBe(canceled);
+});
diff --git a/packages/platform-android/src/launch-observation.ts b/packages/platform-android/src/launch-observation.ts
new file mode 100644
index 0000000000..1004eac55e
--- /dev/null
+++ b/packages/platform-android/src/launch-observation.ts
@@ -0,0 +1,54 @@
+import type {
+  PostOpenObservation,
+  PostOpenObservationFailure,
+} from '@agent-device/contracts/application-lifecycle-runtime';
+import {
+  isUnreadableCaptureContentError,
+  readAndroidCaptureFailureReason,
+} from '@agent-device/contracts/android-snapshot-quality';
+import type { Interactor } from '@agent-device/contracts/interactor-types';
+import { normalizeError } from '@agent-device/kernel/errors';
+
+/**
+ * Longer than the unmounted window measured after `am start -W` on a loaded emulator (up to 5.4 s).
+ * It only stops further re-captures; helper start and capture keep their own budgets.
+ */
+export const ANDROID_LAUNCH_SETTLE_WINDOW_MS = 6_000;
+
+export type AndroidLaunchObservation =
+  | Readonly<{ observation: Extract<PostOpenObservation, 'observable' | 'unobservable'> }>
+  | Readonly<{ observation: 'probe-failed'; failure: PostOpenObservationFailure }>;
+
+/**
+ * `am start -W` returns at the first frame, which can precede the app's mounted views. This
+ * captures the launched app transiently and lets the capture's content verdict and re-captures
+ * decide readiness. Only a content verdict or a system surface over the app reads as
+ * `unobservable`; any other capture failure is `probe-failed` with its typed reason. Only the
+ * caller's signal cancels the capture.
+ */
+export async function observeAndroidLaunch(
+  interactor: Pick<Interactor, 'snapshot'>,
+  appBundleId: string,
+  signal: AbortSignal,
+): Promise<AndroidLaunchObservation> {
+  try {
+    const capture = await interactor.snapshot({
+      appBundleId,
+      signal,
+      transient: { settleBy: Date.now() + ANDROID_LAUNCH_SETTLE_WINDOW_MS },
+    });
+    const systemSurfaceOnly =
+      'androidSnapshot' in capture && capture.androidSnapshot?.systemSurfaceOnly === true;
+    return { observation: systemSurfaceOnly ? 'unobservable' : 'observable' };
+  } catch (error) {
+    signal.throwIfAborted();
+    if (isUnreadableCaptureContentError(error)) return { observation: 'unobservable' };
+    return { observation: 'probe-failed', failure: typedFailure(error) };
+  }
+}
+
+function typedFailure(error: unknown): PostOpenObservationFailure {
+  const normalized = normalizeError(error);
+  const reason = readAndroidCaptureFailureReason(normalized) ?? normalized.details?.reason;
+  return typeof reason === 'string' ? { code: normalized.code, reason } : { code: normalized.code };
+}
diff --git a/packages/platform-android/src/lifecycle.test.ts b/packages/platform-android/src/lifecycle.test.ts
index 0245284910..d8c6aca244 100644
--- a/packages/platform-android/src/lifecycle.test.ts
+++ b/packages/platform-android/src/lifecycle.test.ts
@@ -1,8 +1,12 @@
 import { afterEach, expect, test, vi } from 'vitest';
-import type { LocalApplicationInteractorHost } from '@agent-device/contracts/application-lifecycle-runtime';
+import type {
+  LocalApplicationInteractorHost,
+  OpenApplicationInput,
+} from '@agent-device/contracts/application-lifecycle-runtime';
 import type { PlatformRuntimeHost } from '@agent-device/contracts/platform-runtime-operations';
-import type { Interactor } from '@agent-device/contracts/interactor-types';
+import type { Interactor, SnapshotOptions } from '@agent-device/contracts/interactor-types';
 import type { DeviceInfo } from '@agent-device/kernel/device';
+import { AppError, createRequestCanceledError } from '@agent-device/kernel/errors';
 import { bindAndroidApplicationLifecycle } from './lifecycle.ts';
 
 const device: DeviceInfo = {
@@ -18,17 +22,32 @@ afterEach(() => {
   vi.restoreAllMocks();
 });
 
-test('preserves a runtime launch URL duration after the admitted Android follow-up open', async () => {
-  const opens: string[] = [];
+type LifecycleFixture = Readonly<{
+  calls: string[];
+  lifecycle: ReturnType<typeof bindAndroidApplicationLifecycle>;
+}>;
+
+function createLifecycle(
+  params: Readonly<{
+    snapshot?: (options: SnapshotOptions) => Promise<unknown>;
+    openedAppBundleId?: string;
+    signal?: AbortSignal;
+  }> = {},
+): LifecycleFixture {
+  const calls: string[] = [];
   const localInteractors: LocalApplicationInteractorHost = {
     resolve: async () =>
       ({
         open: async (app: string) => {
-          opens.push(app);
+          calls.push(`open:${app}`);
         },
         openDevice: async () => {},
         close: async () => {},
         setSetting: async () => {},
+        snapshot: async (options: SnapshotOptions) => {
+          calls.push(`observe:${options.appBundleId}`);
+          return await (params.snapshot?.(options) ?? Promise.resolve({ nodes: [] }));
+        },
       }) as unknown as Interactor,
   };
   const host = {
@@ -41,7 +60,8 @@ test('preserves a runtime launch URL duration after the admitted Android follow-
     },
     androidApplications: {
       resolveOpenTarget: async () => ({}),
-      inferOpenedAppBundleId: async () => 'com.example.app',
+      inferOpenedAppBundleId: async () =>
+        'openedAppBundleId' in params ? params.openedAppBundleId : 'com.example.app',
       resetFramePerfStats: async () => {},
       applyRuntimeHints: async () => {},
       clearRuntimeHints: async () => {},
@@ -60,21 +80,18 @@ test('preserves a runtime launch URL duration after the admitted Android follow-
     | 'localInteractors'
     | 'toolchains'
   >;
-  vi.spyOn(Date, 'now')
-    .mockReturnValueOnce(10)
-    .mockReturnValueOnce(20)
-    .mockReturnValueOnce(30)
-    .mockReturnValueOnce(50);
   const lifecycle = bindAndroidApplicationLifecycle({
     host,
     device,
-    signal: new AbortController().signal,
+    signal: params.signal ?? new AbortController().signal,
   });
+  return { calls, lifecycle };
+}
 
-  const outcome = await lifecycle.openApplication({
+function openInput(overrides: Partial<OpenApplicationInput> = {}): OpenApplicationInput {
+  return {
     target: 'com.example.app',
     positionals: ['com.example.app'],
-    runtimeLaunchUrl: 'example://after-open',
     appBundleId: 'com.example.app',
     surface: 'app',
     hasExistingSession: false,
@@ -84,8 +101,114 @@ test('preserves a runtime launch URL duration after the admitted Android follow-
     stateDir: '/state',
     runtimeHints: {},
     execution: {},
-  });
+    ...overrides,
+  };
+}
 
-  expect(opens).toEqual(['com.example.app', 'example://after-open']);
+test('preserves a runtime launch URL duration after the admitted Android follow-up open', async () => {
+  const { calls, lifecycle } = createLifecycle();
+  vi.spyOn(Date, 'now')
+    .mockReturnValueOnce(10)
+    .mockReturnValueOnce(20)
+    .mockReturnValueOnce(30)
+    .mockReturnValueOnce(50);
+
+  const outcome = await lifecycle.openApplication(
+    openInput({ runtimeLaunchUrl: 'example://after-open' }),
+  );
+
+  expect(calls.filter((call) => call.startsWith('open:'))).toEqual([
+    'open:com.example.app',
+    'open:example://after-open',
+  ]);
   expect(outcome.timing.launchUrlDurationMs).toBe(20);
 });
+
+test('an Android app open returns only after the launched app observation settles', async () => {
+  let finishCapture: () => void = () => {};
+  const { calls, lifecycle } = createLifecycle({
+    openedAppBundleId: 'com.example.opened',
+    snapshot: async () => {
+      await new Promise<void>((resolve) => {
+        finishCapture = resolve;
+      });
+      return { nodes: [], androidSnapshot: { backend: 'android-helper', systemSurfaceOnly: true } };
+    },
+  });
+
+  let settled = false;
+  const opening = lifecycle.openApplication(openInput()).then((outcome) => {
+    settled = true;
+    return outcome;
+  });
+  await vi.waitFor(() => expect(calls).toContain('observe:com.example.opened'));
+  await Promise.resolve();
+  expect(settled).toBe(false);
+  finishCapture();
+  const outcome = await opening;
+
+  expect(calls).toEqual(['open:com.example.app', 'observe:com.example.opened']);
+  expect(outcome.appBundleId).toBe('com.example.opened');
+  expect(outcome.timing.postOpenObservation).toBe('unobservable');
+  expect(outcome.timing.postOpenObservationFailure).toBeUndefined();
+  expect(outcome.timing.postOpenSettleDurationMs).toEqual(expect.any(Number));
+});
+
+test('a failed launch probe reports its typed failure and the open still succeeds', async () => {
+  const { lifecycle } = createLifecycle({
+    snapshot: async () => {
+      throw new AppError('COMMAND_FAILED', 'Android snapshot helper failed', {
+        androidCaptureFailureReason: 'accessibility-timeout',
+      });
+    },
+  });
+
+  const outcome = await lifecycle.openApplication(openInput({ relaunch: true }));
+
+  expect(outcome.timing.postOpenObservation).toBe('probe-failed');
+  expect(outcome.timing.postOpenObservationFailure).toEqual({
+    code: 'COMMAND_FAILED',
+    reason: 'accessibility-timeout',
+  });
+});
+
+test('a cancelled open rejects with its cancellation', async () => {
+  const controller = new AbortController();
+  const canceled = createRequestCanceledError();
+  const { lifecycle } = createLifecycle({
+    signal: controller.signal,
+    snapshot: async (options) => {
+      expect(options.signal).toBe(controller.signal);
+      controller.abort(canceled);
+      throw canceled;
+    },
+  });
+
+  await expect(lifecycle.openApplication(openInput())).rejects.toBe(canceled);
+});
+
+test('a URL open has no launched app to observe and leaves the observation unset', async () => {
+  const { calls, lifecycle } = createLifecycle({ openedAppBundleId: 'com.example.browser' });
+
+  const outcome = await lifecycle.openApplication(
+    openInput({
+      target: 'https://example.com',
+      positionals: ['https://example.com'],
+      appBundleId: undefined,
+    }),
+  );
+
+  expect(calls).toEqual(['open:https://example.com']);
+  expect(outcome.timing.postOpenObservation).toBeUndefined();
+});
+
+test('an app open whose launched package cannot be identified reports it unidentified', async () => {
+  const { calls, lifecycle } = createLifecycle({ openedAppBundleId: undefined });
+
+  const outcome = await lifecycle.openApplication(
+    openInput({ target: 'Example', positionals: ['Example'], appBundleId: undefined }),
+  );
+
+  expect(calls).toEqual(['open:Example']);
+  expect(outcome.timing.postOpenObservation).toBe('app-unidentified');
+});
diff --git a/packages/platform-android/src/lifecycle.ts b/packages/platform-android/src/lifecycle.ts
index cab32f52f6..d6db533324 100644
--- a/packages/platform-android/src/lifecycle.ts
+++ b/packages/platform-android/src/lifecycle.ts
@@ -2,6 +2,7 @@ import {
   type ApplicationLifecycleRuntimeOperations,
   type OpenApplicationInput,
   type OpenApplicationOutcome,
+  type OpenApplicationTiming,
   hasRuntimeTransportHintValues,
 } from '@agent-device/contracts/application-lifecycle-runtime';
 import type { PlatformRuntimeHost } from '@agent-device/contracts/platform-runtime-operations';
@@ -11,6 +12,8 @@ import {
   invokeApplicationClose,
   invokeApplicationOpen,
 } from '@agent-device/contracts/application-lifecycle-interaction';
+import { isDeepLinkTarget } from '@agent-device/contracts/command';
+import { observeAndroidLaunch } from './launch-observation.ts';
 import { ensureAndroidReady } from './readiness/runtime.ts';
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import { AppError } from '@agent-device/kernel/errors';
@@ -164,10 +167,30 @@ async function openAndroidApplication(
   if (appBundleId) {
     await host.androidApplications.resetFramePerfStats(binding.device, appBundleId);
   }
-  timing.postOpenSettleDurationMs = 0;
+  const settleStartedAtMs = Date.now();
+  Object.assign(timing, await observeOpenedApp(binding, input, appBundleId));
+  timing.postOpenSettleDurationMs = elapsed(settleStartedAtMs);
   return { appBundleId, timing };
 }
 
+/** A URL or deep-link open has no launched app of its own to observe, so it reports nothing. */
+async function observeOpenedApp(
+  binding: ReturnType<typeof bindLocalApplicationLifecycleInteractor>,
+  input: OpenApplicationInput,
+  appBundleId: string | undefined,
+): Promise<Pick<OpenApplicationTiming, 'postOpenObservation' | 'postOpenObservationFailure'>> {
+  if (!input.target || isDeepLinkTarget(input.target)) return {};
+  if (!appBundleId) return { postOpenObservation: 'app-unidentified' };
+  const launch = await observeAndroidLaunch(
+    await binding.resolveInteractor(input.execution, appBundleId),
+    appBundleId,
+    binding.signal,
+  );
+  return launch.observation === 'probe-failed'
+    ? { postOpenObservation: 'probe-failed', postOpenObservationFailure: launch.failure }
+    : { postOpenObservation: launch.observation };
+}
+
 function elapsed(startedAtMs: number): number {
   return Math.max(0, Date.now() - startedAtMs);
 }
diff --git a/packages/platform-android/src/snapshot-helper-install.ts b/packages/platform-android/src/snapshot-helper-install.ts
index b3e7624704..c12df35185 100644
--- a/packages/platform-android/src/snapshot-helper-install.ts
+++ b/packages/platform-android/src/snapshot-helper-install.ts
@@ -1,4 +1,4 @@
-import { asAppError, type AppError } from '@agent-device/kernel/errors';
+import { AppError, asAppError } from '@agent-device/kernel/errors';
 import {
   inspectInstalledAndroidHelper,
   installAndroidHelperPackage,
@@ -32,6 +32,13 @@ export function forgetAndroidSnapshotHelperInstall(options: {
 /**
  * @internal Test isolation hook for process-global snapshot helper install cache.
  */
+const ANDROID_SNAPSHOT_HELPER_NOT_CURRENT = 'android-snapshot-helper-not-current';
+
+/** A `current-only` check found no current helper: nothing ran, so there is nothing to recover. */
+export function isAndroidSnapshotHelperNotCurrentError(error: unknown): boolean {
+  return asAppError(error).details?.reason === ANDROID_SNAPSHOT_HELPER_NOT_CURRENT;
+}
+
 export function resetAndroidSnapshotHelperInstallCache(): void {
   installedSnapshotHelpers.clear();
 }
@@ -142,6 +149,18 @@ export async function ensureAndroidSnapshotHelper(options: {
       reason,
     };
   }
+  if (installPolicy === 'current-only') {
+    throw new AppError(
+      'COMMAND_FAILED',
+      'Android snapshot helper is not installed at the current version',
+      {
+        reason: ANDROID_SNAPSHOT_HELPER_NOT_CURRENT,
+        packageName,
+        versionCode,
+        installedVersionCode,
+      },
+    );
+  }
 
   let result: Awaited<ReturnType<AndroidAdbExecutor>>;
   try {
diff --git a/packages/platform-android/src/snapshot-helper-types.ts b/packages/platform-android/src/snapshot-helper-types.ts
index cee1b6bf6d..b0581b0b02 100644
--- a/packages/platform-android/src/snapshot-helper-types.ts
+++ b/packages/platform-android/src/snapshot-helper-types.ts
@@ -45,7 +45,12 @@ export type {
   AndroidSnapshotHelperManifest,
 } from './helper-artifacts.ts';
 
-export type AndroidSnapshotHelperInstallPolicy = 'missing-or-outdated' | 'always' | 'never';
+/** `current-only` uses an installed helper at the artifact's version and refuses to install one. */
+export type AndroidSnapshotHelperInstallPolicy =
+  | 'missing-or-outdated'
+  | 'always'
+  | 'never'
+  | 'current-only';
 
 export type AndroidSnapshotHelperInstallResult = {
   packageName: string;
diff --git a/packages/platform-android/src/snapshot.ts b/packages/platform-android/src/snapshot.ts
index 008e30913a..4d25cedbb5 100644
--- a/packages/platform-android/src/snapshot.ts
+++ b/packages/platform-android/src/snapshot.ts
@@ -6,6 +6,7 @@ import {
 } from '@agent-device/kernel/errors';
 import path from 'node:path';
 import { emitDiagnostic, withDiagnosticTimer } from '@agent-device/host-kit/diagnostics';
+import type { SnapshotOptions as InteractorSnapshotOptions } from '@agent-device/contracts/interactor-types';
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import {
   attachRefs,
@@ -43,6 +44,8 @@ import {
   type AndroidSnapshotHelperInstallResult,
   type AndroidSnapshotHelperOutput,
 } from './snapshot-helper.ts';
+import { getLiveAndroidSnapshotHelperSession } from './snapshot-helper-session-lifecycle.ts';
+import { isAndroidSnapshotHelperNotCurrentError } from './snapshot-helper-install.ts';
 import {
   getAndroidSnapshotHelperSessionDeviceKey,
   isAndroidSnapshotHelperRuntimeOccupiedError,
@@ -87,6 +90,8 @@ export type AndroidSnapshotOptions = SnapshotOptions & {
   helperArtifact?: AndroidSnapshotHelperArtifact;
   helperInstallPolicy?: AndroidSnapshotHelperInstallPolicy;
   helperSessionScope?: AndroidHelperSessionScope;
+  /** The interactor contract's one-off read: no install, no kept session, no re-capture after `settleBy`. */
+  transient?: InteractorSnapshotOptions['transient'];
   helperAdb?: AndroidAdbExecutor | AndroidAdbProvider;
   includeHiddenContentHints?: boolean;
   androidPresentation?: AndroidSnapshotPresentationOptions;
@@ -277,7 +282,7 @@ async function captureAndroidUiHierarchyWithHelper(
 ): Promise<{ xml: string; metadata: AndroidSnapshotBackendMetadata }> {
   const helperDeviceKey = getAndroidSnapshotHelperSessionDeviceKey(device);
   const adbProvider = resolveAndroidAdbProvider(device, options.helperAdb);
-  const commandScopedHelperSession = options.helperSessionScope !== 'daemon-session';
+  const releaseHelperSession = releasesHelperSessionAfterCapture(options, helperDeviceKey);
   try {
     let previousContentReason: AndroidContentRecoveryReason | undefined;
     for (let attempt = 0; ; attempt += 1) {
@@ -292,7 +297,10 @@ async function captureAndroidUiHierarchyWithHelper(
         previousContentReason,
       });
       if (settled.outcome === 'captured') return settled.capture;
-      if (attempt + 1 >= HELPER_CONTENT_CAPTURE_ATTEMPTS) {
+      if (
+        attempt + 1 >= HELPER_CONTENT_CAPTURE_ATTEMPTS ||
+        (options.transient !== undefined && Date.now() >= options.transient.settleBy)
+      ) {
         return await rejectAndroidHelperContentUnavailable({
           contentRecovery: settled.decision,
           attempts: attempt + 1,
@@ -300,17 +308,36 @@ async function captureAndroidUiHierarchyWithHelper(
           artifact,
           adb,
           signal: options.signal,
+          retireHelper: options.transient === undefined,
         });
       }
       previousContentReason = settled.decision.reason;
     }
   } finally {
-    if (commandScopedHelperSession) {
+    if (releaseHelperSession) {
       await stopAndroidSnapshotHelperSession(helperDeviceKey);
     }
   }
 }
 
+/** A transient read keeps a session it found running and releases one it had to start. */
+function releasesHelperSessionAfterCapture(
+  options: AndroidSnapshotOptions,
+  helperDeviceKey: string,
+): boolean {
+  if (options.transient) return getLiveAndroidSnapshotHelperSession(helperDeviceKey) === undefined;
+  return options.helperSessionScope !== 'daemon-session';
+}
+
+/** A transient read never installs the helper; it uses one that is already current. */
+function resolveHelperInstallPolicy(
+  options: AndroidSnapshotOptions,
+): AndroidSnapshotHelperInstallPolicy {
+  return options.transient
+    ? 'current-only'
+    : (options.helperInstallPolicy ?? 'missing-or-outdated');
+}
+
 async function installAndroidSnapshotHelper(
   options: AndroidSnapshotOptions,
   adb: AndroidAdbExecutor,
@@ -326,14 +353,14 @@ async function installAndroidSnapshotHelper(
         adbProvider,
         artifact,
         deviceKey,
-        installPolicy: options.helperInstallPolicy,
+        installPolicy: resolveHelperInstallPolicy(options),
         timeoutMs: HELPER_INSTALL_TIMEOUT_MS,
         signal: options.signal,
       }),
     {
       packageName: artifact.manifest.packageName,
       versionCode: artifact.manifest.versionCode,
-      installPolicy: options.helperInstallPolicy ?? 'missing-or-outdated',
+      installPolicy: resolveHelperInstallPolicy(options),
     },
   );
   emitDiagnostic({
@@ -466,6 +493,7 @@ async function captureAndroidHelperContentAttempt(params: {
     helperCapture = formatAndroidHelperCaptureResult(capture, artifact, install.reason);
   } catch (error) {
     options.signal?.throwIfAborted();
+    if (isAndroidSnapshotHelperNotCurrentError(error)) throw error;
     return {
       outcome: 'captured',
       capture: await rejectAndroidHelperCaptureFailure({
@@ -517,6 +545,8 @@ async function rejectAndroidHelperContentUnavailable(params: {
   artifact: AndroidSnapshotHelperArtifact;
   adb: AndroidAdbExecutor;
   signal?: AbortSignal;
+  /** A transient capture does not own the helper, so its content verdict leaves the helper alone. */
+  retireHelper: boolean;
 }): Promise<{ xml: string; metadata: AndroidSnapshotBackendMetadata }> {
   emitDiagnostic({
     level: 'error',
@@ -528,17 +558,27 @@ async function rejectAndroidHelperContentUnavailable(params: {
       ...params.contentRecovery.diagnostics,
     },
   });
-  await retireAndroidSnapshotHelperAfterContentFailure({
-    adb: params.adb,
-    deviceKey: params.helperDeviceKey,
-    packageName: params.artifact.manifest.packageName,
-    signal: params.signal,
-    cause: params.contentRecovery.failureReason,
-  });
-  throw new AppError('COMMAND_FAILED', params.contentRecovery.failureReason, {
-    ...params.contentRecovery.diagnostics,
-    androidSnapshotHelperFailureReason: params.contentRecovery.reason,
-    attempts: params.attempts,
+  if (params.retireHelper) {
+    await retireAndroidSnapshotHelperAfterContentFailure({
+      adb: params.adb,
+      deviceKey: params.helperDeviceKey,
+      packageName: params.artifact.manifest.packageName,
+      signal: params.signal,
+      cause: params.contentRecovery.failureReason,
+    });
+  }
+  throw androidHelperContentUnavailableError(params.contentRecovery, params.attempts);
+}
+
+/** The retriable content verdict a capture reports once its re-captures still see no content. */
+export function androidHelperContentUnavailableError(
+  contentRecovery: AndroidHelperContentRecoveryDecision,
+  attempts: number,
+): AppError {
+  return new AppError('COMMAND_FAILED', contentRecovery.failureReason, {
+    ...contentRecovery.diagnostics,
+    androidSnapshotHelperFailureReason: contentRecovery.reason,
+    attempts,
     retriable: true,
     hint: 'Retry after the app UI stabilizes. If this persists, capture a screenshot and report the helper diagnostics; agent-device does not substitute a second snapshot engine.',
   });
diff --git a/packages/platform-apple/src/snapshot-observability.ts b/packages/platform-apple/src/snapshot-observability.ts
index 91ff821b3d..117218b2d4 100644
--- a/packages/platform-apple/src/snapshot-observability.ts
+++ b/packages/platform-apple/src/snapshot-observability.ts
@@ -3,6 +3,7 @@ import {
   deriveIosCaptureHint,
 } from '@agent-device/capture-kit/ios-snapshot-planning';
 import { emitDiagnostic } from '@agent-device/host-kit/diagnostics';
+import type { PostOpenObservation } from '@agent-device/contracts/application-lifecycle-runtime';
 import type { PlatformRuntimeHost } from '@agent-device/contracts/platform-runtime-operations';
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import type { SimulatorSnapshotSource } from './snapshot-source-facade.ts';
@@ -12,14 +13,11 @@ import {
   type SimulatorSnapshotTargetResolver,
 } from './snapshot-target.ts';
 
-/**
- * What an `open` learned about the app it just launched on a local Simulator: `observable` means
- * the host AX bridge published its tree, so the first observation will not pay a launch
- * transition; `unobservable` means the bridge reported a state that will not clear within its
- * grace (a system dialog, a lost AX server) or the grace ran out; `not-eligible` means the device
- * has no bridge to ask.
- */
-export type LaunchObservation = 'observable' | 'unobservable' | 'not-eligible';
+/** The observations a local Simulator's host AX bridge can report for a launched app. */
+export type LaunchObservation = Extract<
+  PostOpenObservation,
+  'observable' | 'unobservable' | 'not-eligible'
+>;
 
 export type LaunchObservationPort = Readonly<{
   awaitObservable(
diff --git a/src/core/interactors/android.test.ts b/src/core/interactors/android.test.ts
index a5707432fa..fa58f526a8 100644
--- a/src/core/interactors/android.test.ts
+++ b/src/core/interactors/android.test.ts
@@ -94,3 +94,20 @@ test('a device-only session releases the helper after fill and scroll', async ()
     helperSessionScope: 'command',
   });
 });
+
+test('a transient snapshot reaches the Android capture with its settle deadline', async () => {
+  snapshotAndroidMock.mockResolvedValue(makeAndroidSnapshotCapture([]));
+
+  await createAndroidInteractor(device).snapshot({
+    appBundleId: 'com.example.app',
+    transient: { settleBy: 1_000 },
+  });
+
+  expect(snapshotAndroidMock).toHaveBeenCalledWith(
+    device,
+    expect.objectContaining({
+      appBundleId: 'com.example.app',
+      transient: { settleBy: 1_000 },
+    }),
+  );
+});
diff --git a/src/core/interactors/android.ts b/src/core/interactors/android.ts
index fff5d3f126..84e1684ac5 100644
--- a/src/core/interactors/android.ts
+++ b/src/core/interactors/android.ts
@@ -105,6 +105,7 @@ export function createAndroidInteractor(
             raw: snapshotOptions.raw,
             includeHiddenContentHints: snapshotOptions.includeHiddenContentHints,
             helperSessionScope: androidHelperSessionScope(snapshotOptions.appBundleId),
+            transient: snapshotOptions.transient,
           }),
         { backend: 'android' },
       );
diff --git a/test/integration/provider-scenarios/android-test-suite.test.ts b/test/integration/provider-scenarios/android-test-suite.test.ts
index 18fd2238d2..53b5c2d84a 100644
--- a/test/integration/provider-scenarios/android-test-suite.test.ts
+++ b/test/integration/provider-scenarios/android-test-suite.test.ts
@@ -81,13 +81,21 @@ test(
   'Provider-backed integration Android Maestro refreshes action geometry and preserves authored swipe points',
   async () => {
     let snapshots = 0;
+    let capturesSinceLaunch = 0;
     await withProviderScenarioResource(
       async () =>
         await createAndroidSettingsWorld({
+          onAdbExec: (args) => {
+            if (args.slice(0, 3).join(' ') === 'shell am start') capturesSinceLaunch = 0;
+          },
+          // The helper is not installed yet when the flow opens the app, so the open's launch
+          // probe fails before it captures. The flow's assertion reads the first capture after
+          // `am start`, which carries the geometry the tap must not reuse.
           snapshotXml: () => {
             snapshots += 1;
+            capturesSinceLaunch += 1;
             return androidMaestroReplayXml(
-              snapshots === 1 ? '[16,24][374,80]' : '[100,300][260,360]',
+              capturesSinceLaunch === 1 ? '[16,24][374,80]' : '[100,300][260,360]',
             );
           },
         }),
@@ -135,7 +143,8 @@ test(
         assert.deepEqual(swipePlan.pointers[0]?.samples[0]?.point, { x: 351, y: 300 });
         assert.deepEqual(swipePlan.pointers[0]?.samples.at(-1)?.point, { x: 39, y: 300 });
         assert.equal(world.gestureViewportCalls, 1);
-        // Assertion, launch/tap stability comparisons, and fresh tap geometry share retained baselines.
+        // Assertion, launch/tap stability comparisons, and fresh tap geometry share retained
+        // baselines; the open's launch probe adds no capture here.
         assert.equal(snapshots, 4);
       },
     );
@@ -187,11 +196,14 @@ test(
           ['shell', 'input', 'tap', '180', '330'],
         );
         assert.equal(
-          world.adbCalls.filter((call) => call.slice(0, 3).join(' ') === 'shell am force-stop')
-            .length,
+          world.adbCalls.filter(
+            (call) => call.join(' ') === 'shell am force-stop com.android.settings',
+          ).length,
           2,
         );
-        assertSnapshotCountInRange(snapshots, 2, 3);
+        // The second flow's open finds the helper the first flow installed, so its launch probe
+        // adds one capture.
+        assertSnapshotCountInRange(snapshots, 3, 4);
       },
     );
   },
diff --git a/test/integration/provider-scenarios/android-world.ts b/test/integration/provider-scenarios/android-world.ts
index 5032259e23..ae6f242eb4 100644
--- a/test/integration/provider-scenarios/android-world.ts
+++ b/test/integration/provider-scenarios/android-world.ts
@@ -15,6 +15,7 @@ import {
   androidSnapshotHelperOutput,
 } from '../../../src/__tests__/test-utils/android-snapshot-helper.ts';
 import { runCmd, runCmdBackground } from '@agent-device/host-kit/command';
+import { resetAndroidSnapshotHelperInstallCache } from '@agent-device/platform-android/mechanics';
 import { validPng } from './assertions.ts';
 import { PROVIDER_SCENARIO_ANDROID } from './fixtures.ts';
 import {
@@ -65,6 +66,9 @@ export async function createAndroidSettingsWorld(options?: {
   dumpsysWindow?: () => string;
   onAdbExec?: (args: readonly string[]) => void;
 }): Promise<AndroidSettingsWorld> {
+  // The world's helper version probe always reports no helper, so no install may be remembered
+  // from an earlier world on the same serial.
+  resetAndroidSnapshotHelperInstallCache();
   const hostAdbGuard = installFakeHostAdbGuard();
   const adbCalls: string[][] = [];
   const textInjectionCalls: AndroidSettingsWorld['textInjectionCalls'] = [];

From 3e5af3a44f9c27f264d8992cb473e6bef308157f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 24 Sep 2026 19:42:01 +0200
Subject: [PATCH 112/132] fix(wait): report readiness work that consumed the
 wait budget (#2893)

* fix(wait): report readiness work that consumed the wait budget

A wait whose deadline cancels a poll while the iOS XCTest runner is still
starting, or while the Simulator app is still being discovered, now fails
with wait_readiness_exhausted and details.readinessPhase instead of
wait_capture_stalled. The platform names the phase on the cancellation it
throws; the wait classifies the cancelled poll as readiness.

Refs #2343

* fix(wait): tag only running discovery as readiness and keep platform imports type-only

* fix(wait): keep an earlier retriable refusal ahead of the readiness verdict

* test(ios): type the route test tool mocks against readonly simctl args

* refactor(ios): name the route's cancelled target-resolution rethrow

* test(ios): pin the resolver's discovery and re-check cancellations
---
 packages/contracts/src/wait.ts                |  20 +++
 .../__tests__/runner-recovery-wiring.test.ts  |  64 +++++++-
 .../src/runner/runner-lifecycle.ts            |  26 +++-
 .../platform-apple/src/snapshot-route.test.ts | 128 ++++++++++++++++
 packages/platform-apple/src/snapshot-route.ts |  12 +-
 .../src/snapshot-target.test.ts               |  28 +++-
 .../platform-apple/src/snapshot-target.ts     |  19 ++-
 .../interaction/runtime/wait-absent.ts        |   9 +-
 .../interaction/runtime/wait-polling.ts       | 119 +++++++++++----
 src/daemon/__tests__/wait-runtime.test.ts     | 140 +++++++++++++++++-
 website/docs/docs/commands.md                 |   4 +-
 11 files changed, 519 insertions(+), 50 deletions(-)

diff --git a/packages/contracts/src/wait.ts b/packages/contracts/src/wait.ts
index 6ba07ad602..9528c11f22 100644
--- a/packages/contracts/src/wait.ts
+++ b/packages/contracts/src/wait.ts
@@ -6,6 +6,9 @@
  * `wait_capture_stalled` means no readable capture established an observation
  * before the deadline and is retriable. `wait_deadline_exceeded` means a later
  * capture consumed the remaining budget after at least one readable capture.
+ * `wait_readiness_exhausted` means the deadline cancelled a poll that was still
+ * making the target observable; `details.readinessPhase` names the work, and
+ * `wait_runner_restart_exhausted` is the same verdict for a runner restart.
  * `wait_target_absent` is the ordinary timeout reason for a selector that was
  * never found. `wait_target_present` is the strict-absence timeout reason when
  * valid captures still contain matches. The remaining reasons describe
@@ -15,6 +18,7 @@ export const WAIT_REASONS = {
   captureStalled: 'wait_capture_stalled',
   deadlineExceeded: 'wait_deadline_exceeded',
   runnerRestartExhausted: 'wait_runner_restart_exhausted',
+  readinessExhausted: 'wait_readiness_exhausted',
   targetAbsent: 'wait_target_absent',
   targetPresent: 'wait_target_present',
   stableTimeout: 'wait_stable_timeout',
@@ -23,6 +27,22 @@ export const WAIT_REASONS = {
 
 export type WaitReason = (typeof WAIT_REASONS)[keyof typeof WAIT_REASONS];
 
+/**
+ * Work a platform does before it can observe the target at all: starting the Apple XCTest runner,
+ * or discovering the Simulator app process the host AX bridge reads. Only the code doing that work
+ * at the moment of cancellation names it, as `details.readinessPhase` on the error it throws.
+ */
+const READINESS_PHASES = ['runner-start', 'target-discovery'] as const;
+
+export type ReadinessPhase = (typeof READINESS_PHASES)[number];
+
+export function readinessPhaseOf(
+  details: Readonly<Record<string, unknown>> | undefined,
+): ReadinessPhase | undefined {
+  const phase = details?.readinessPhase;
+  return READINESS_PHASES.find((candidate) => candidate === phase);
+}
+
 /**
  * Public daemon result for `wait`. The runtime-local result carries a `kind`
  * discriminant, but `toDaemonWaitData` intentionally projects the normal daemon
diff --git a/packages/platform-apple/src/runner/__tests__/runner-recovery-wiring.test.ts b/packages/platform-apple/src/runner/__tests__/runner-recovery-wiring.test.ts
index b71fe25732..ca7ce87fa5 100644
--- a/packages/platform-apple/src/runner/__tests__/runner-recovery-wiring.test.ts
+++ b/packages/platform-apple/src/runner/__tests__/runner-recovery-wiring.test.ts
@@ -1,6 +1,8 @@
 import assert from 'node:assert/strict';
 import { afterEach, beforeEach, expect, test, vi } from 'vitest';
-import { AppError } from '@agent-device/kernel/errors';
+import http from 'node:http';
+import type { AddressInfo } from 'node:net';
+import { AppError, createRequestCanceledError } from '@agent-device/kernel/errors';
 import { resetAllProcessMemosForTests } from '@agent-device/kernel/ttl-memo';
 import { IOS_SIMULATOR } from './device-fixtures.ts';
 import type { ExecResult } from '@agent-device/host-kit/command';
@@ -220,6 +222,66 @@ test('a failed restart preserves the invalidated runner evidence', async () => {
   }
 });
 
+// A runner that has not answered yet is readiness work, not observation: a caller whose deadline
+// lands there needs to know the start consumed it, so the cancellation names the phase (#2343).
+test('a cancellation during a runner start names the start as the readiness phase', async () => {
+  const unanswered = await startFakeRunnerServer([]);
+  await unanswered.close();
+  const starting = { ...makeRunnerSession(unanswered.port), state: 'starting' as const };
+  ensureRunnerSessionMock.mockResolvedValue(starting);
+  const controller = new AbortController();
+  setTimeout(() => controller.abort(), 50);
+
+  await expect(
+    runAppleRunnerCommand(IOS_SIMULATOR, { command: 'snapshot' }, { signal: controller.signal }),
+  ).rejects.toMatchObject({
+    details: { reason: 'request_canceled', readinessPhase: 'runner-start' },
+  });
+  expect(invalidateRunnerSessionMock).toHaveBeenCalledWith(
+    starting,
+    'runner_startup_request_canceled',
+  );
+});
+
+test('a cancellation before any runner session exists names the start as the readiness phase', async () => {
+  ensureRunnerSessionMock.mockImplementation(
+    async (_device: unknown, options: { signal?: AbortSignal }) =>
+      await new Promise((_resolve, reject) => {
+        options.signal?.addEventListener('abort', () => reject(createRequestCanceledError()), {
+          once: true,
+        });
+      }),
+  );
+  const controller = new AbortController();
+  setTimeout(() => controller.abort(), 20);
+
+  await expect(
+    runAppleRunnerCommand(IOS_SIMULATOR, { command: 'snapshot' }, { signal: controller.signal }),
+  ).rejects.toMatchObject({ details: { readinessPhase: 'runner-start' } });
+});
+
+test('a cancellation of a command on a ready runner is not readiness work', async () => {
+  const silent = http.createServer(() => {});
+  await new Promise<void>((resolve) => silent.listen(0, '127.0.0.1', resolve));
+  try {
+    seedSession((silent.address() as AddressInfo).port);
+    const controller = new AbortController();
+    setTimeout(() => controller.abort(), 50);
+
+    const command = runAppleRunnerCommand(
+      IOS_SIMULATOR,
+      { command: 'snapshot' },
+      { signal: controller.signal },
+    );
+
+    await expect(command).rejects.toMatchObject({ details: { reason: 'request_canceled' } });
+    await expect(command).rejects.not.toHaveProperty('details.readinessPhase');
+  } finally {
+    silent.closeAllConnections();
+    await new Promise<void>((resolve) => silent.close(() => resolve()));
+  }
+});
+
 test('an exact-session command never dispatches to a replacement runner', async () => {
   server = await startFakeRunnerServer({ recordStop: [{ kind: 'ok', data: {} }] });
   const replacement = seedSession(server.port);
diff --git a/packages/platform-apple/src/runner/runner-lifecycle.ts b/packages/platform-apple/src/runner/runner-lifecycle.ts
index 1cb4884a6f..5d50e464e9 100644
--- a/packages/platform-apple/src/runner/runner-lifecycle.ts
+++ b/packages/platform-apple/src/runner/runner-lifecycle.ts
@@ -1,5 +1,11 @@
-import { AppError, asAppError, isRequestCanceledError } from '@agent-device/kernel/errors';
+import {
+  AppError,
+  asAppError,
+  createRequestCanceledError,
+  isRequestCanceledError,
+} from '@agent-device/kernel/errors';
 import type { DeviceInfo } from '@agent-device/kernel/device';
+import type { ReadinessPhase } from '@agent-device/contracts/wait';
 import { emitDiagnostic } from './host.ts';
 import { RUNNER_STARTUP_TIMEOUT_MS } from './runner-startup-transport.ts';
 import { RUNNER_COMMAND_TIMEOUT_MS } from './runner-transport.ts';
@@ -265,15 +271,15 @@ export async function executeRunnerCommand(
   const recycleKey = runnerRecycleLedgerKey(options, command);
   let session: RunnerSession | undefined;
   let recycleBootBegun = false;
+  const livenessAtEntry = readRunnerSessionLiveness(device.id)?.liveness ?? 'gone';
   try {
     // A request that already used a runner session and finds no runner process is about to pay
     // for a recycle boot (~25s): bound that to the per-request recycle budget so a hostile screen
     // fails fast with a preserved session instead of stacking runner boots (#1105).
     // `gone` and `stopped` are the two liveness answers that mean no runner is answering now, so
     // this command is the one that would start a process (#2662).
-    const liveness = readRunnerSessionLiveness(device.id)?.liveness ?? 'gone';
     if (
-      (liveness === 'gone' || liveness === 'stopped') &&
+      (livenessAtEntry === 'gone' || livenessAtEntry === 'stopped') &&
       hasRunnerRequestTouchedSession(recycleKey)
     ) {
       if (!tryBeginRunnerRecycle(recycleKey)) {
@@ -301,9 +307,17 @@ export async function executeRunnerCommand(
   } catch (error) {
     if (options.expectedRunnerSessionId !== undefined) throw error;
     const appErr = asAppError(error, 'COMMAND_FAILED');
-    if (session && session.state === 'starting' && isRequestCanceledError(appErr)) {
-      await invalidateRunnerSessionBestEffort(session, 'runner_startup_request_canceled');
-      throw error;
+    const runnerNeverAnswered = session
+      ? session.state === 'starting'
+      : livenessAtEntry !== 'ready';
+    if (runnerNeverAnswered && isRequestCanceledError(appErr)) {
+      if (session) {
+        await invalidateRunnerSessionBestEffort(session, 'runner_startup_request_canceled');
+      }
+      throw createRequestCanceledError(
+        { ...appErr.details, readinessPhase: 'runner-start' satisfies ReadinessPhase },
+        appErr,
+      );
     }
     if (shouldRestartRunnerBeforeCommandSend(appErr) && session) {
       assertRunnerRequestActive(options.requestId);
diff --git a/packages/platform-apple/src/snapshot-route.test.ts b/packages/platform-apple/src/snapshot-route.test.ts
index d1be189ac7..fc92a2be74 100644
--- a/packages/platform-apple/src/snapshot-route.test.ts
+++ b/packages/platform-apple/src/snapshot-route.test.ts
@@ -1,5 +1,6 @@
 import { expect, test, vi } from 'vitest';
 import type { DeviceInfo } from '@agent-device/kernel/device';
+import { createRequestCanceledError } from '@agent-device/kernel/errors';
 
 // Keep the route tests hermetic: the default system-surface presence probe shells out to `ps`, which
 // never resolves under the fake timers these tests drive. Tests that exercise the bypass inject
@@ -783,3 +784,130 @@ test('a slow app discovery keeps observation on the bridge while no runner can a
     vi.useRealTimers();
   }
 });
+
+test.for(['rejects', 'exits'] as const)(
+  'a deadline during the cached target re-check is not readiness work (ps %s)',
+  async (psOnAbort) => {
+    // A known target is re-checked with one `ps` per capture; no discovery runs. A deadline that
+    // lands there must stay a plain cancellation, or a wait would report readiness exhaustion over
+    // evidence its earlier polls already gathered (#2343 review).
+    const run = vi.fn(async (args: readonly string[]) => ({
+      stdout:
+        args[0] === 'spawn'
+          ? `42\t0\tUIKitApplication:${input.options.appBundleId}[launch-a][rb-legacy]`
+          : JSON.stringify({
+              devices: { 'com.apple.CoreSimulator.SimRuntime.iOS-26-0': [{ udid: ios.id }] },
+            }),
+      stderr: '',
+      exitCode: 0,
+    }));
+    let recheckStarted!: () => void;
+    const recheck = new Promise<void>((resolve) => {
+      recheckStarted = resolve;
+    });
+    let psCalls = 0;
+    const runCommand = vi.fn(
+      async (cmd: string, args: readonly string[], options?: { signal?: AbortSignal }) => {
+        if (cmd !== 'ps' || ++psCalls === 1) return { stdout: 'start-a', stderr: '', exitCode: 0 };
+        recheckStarted();
+        return await new Promise<{ stdout: string; stderr: string; exitCode: number }>(
+          (resolve, reject) => {
+            options?.signal?.addEventListener(
+              'abort',
+              () =>
+                psOnAbort === 'rejects'
+                  ? reject(createRequestCanceledError({ cmd, args }))
+                  : resolve({ stdout: '', stderr: '', exitCode: 1 }),
+              { once: true },
+            );
+          },
+        );
+      },
+    );
+    const fallback = vi.fn(async () => runnerResult());
+    const baseHost = platformRuntimeHostFixture();
+    const route = createAppleSnapshotRoute(
+      {
+        ...baseHost,
+        appleApplications: {
+          ...baseHost.appleApplications,
+          hasLiveRunnerSession: async () => false,
+        },
+        snapshot: {
+          captureSurface: vi.fn(),
+          presentIosAcquisition: vi.fn(async () => ({
+            backend: 'xctest' as const,
+            producer: 'simulator-ax-bridge' as const,
+            nodes: [{ index: 0, type: 'Application' }],
+          })),
+        },
+      },
+      {
+        source: sourceReturning(bridgeAcquisition()),
+        resolveTarget: createSimulatorSnapshotTargetResolver(),
+      },
+    );
+    await withAppleToolProvider(
+      createLocalAppleToolProvider({ simctl: { run }, runCommand }),
+      async () => {
+        await route.capture(ios, input, signal(), fallback);
+        const deadline = new AbortController();
+        const capture = route.capture(ios, input, deadline.signal, fallback);
+        await recheck;
+        deadline.abort(new DOMException('Wait deadline exceeded', 'TimeoutError'));
+
+        await expect(capture).rejects.not.toHaveProperty('details.readinessPhase');
+        expect(run.mock.calls.filter(([args]) => args[0] === 'spawn')).toHaveLength(1);
+        expect(fallback).not.toHaveBeenCalled();
+      },
+    );
+  },
+);
+
+test('a deadline during a slow app discovery names the discovery as the readiness phase', async () => {
+  // The capture never reached the bridge or the runner: its whole cost was finding the target, so
+  // the cancellation says so instead of reading as a capture that produced nothing (#2343).
+  const run = vi.fn(async (args: readonly string[]) => {
+    if (args[0] === 'spawn') await new Promise<never>(() => {});
+    return {
+      stdout: JSON.stringify({
+        devices: { 'com.apple.CoreSimulator.SimRuntime.iOS-26-0': [{ udid: ios.id }] },
+      }),
+      stderr: '',
+      exitCode: 0,
+    };
+  });
+  const runCommand = vi.fn(async () => ({ stdout: 'start-a', stderr: '', exitCode: 0 }));
+  const fallback = vi.fn(async () => runnerResult());
+  const baseHost = platformRuntimeHostFixture();
+  const route = createAppleSnapshotRoute(
+    {
+      ...baseHost,
+      appleApplications: { ...baseHost.appleApplications, hasLiveRunnerSession: async () => false },
+    },
+    {
+      source: sourceReturning(bridgeAcquisition()),
+      resolveTarget: createSimulatorSnapshotTargetResolver(),
+    },
+  );
+  const deadline = new AbortController();
+  vi.useFakeTimers();
+  try {
+    await withAppleToolProvider(
+      createLocalAppleToolProvider({ simctl: { run }, runCommand }),
+      async () => {
+        const capture = route.capture(ios, input, deadline.signal, fallback);
+        const settled = expect(capture).rejects.toMatchObject({
+          code: 'COMMAND_FAILED',
+          details: { reason: 'request_canceled', readinessPhase: 'target-discovery' },
+        });
+        await vi.advanceTimersByTimeAsync(3_000);
+        deadline.abort(new DOMException('Wait deadline exceeded', 'TimeoutError'));
+        await settled;
+        expect(fallback).not.toHaveBeenCalled();
+      },
+    );
+  } finally {
+    vi.useRealTimers();
+  }
+});
diff --git a/packages/platform-apple/src/snapshot-route.ts b/packages/platform-apple/src/snapshot-route.ts
index 9bed7d9eb6..526b6dbe69 100644
--- a/packages/platform-apple/src/snapshot-route.ts
+++ b/packages/platform-apple/src/snapshot-route.ts
@@ -16,7 +16,7 @@ import {
   deriveIosCaptureHint,
 } from '@agent-device/capture-kit/ios-snapshot-planning';
 import { emitDiagnostic, withDiagnosticTimer } from '@agent-device/host-kit/diagnostics';
-import { AppError } from '@agent-device/kernel/errors';
+import { AppError, isRequestCanceledError } from '@agent-device/kernel/errors';
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import {
   createSimulatorSnapshotSource,
@@ -140,7 +140,7 @@ export function createAppleSnapshotRoute(
       try {
         target = await resolveTargetForObservation(host, resolveTarget, device, input, signal);
       } catch (error) {
-        signal.throwIfAborted();
+        rethrowIfResolutionCancelled(signal, error);
         emitRouteDiagnostic('target-resolution-failed', device, undefined, error);
         return await runFallback(
           device.id,
@@ -247,6 +247,14 @@ async function resolveTargetForObservation(
   }
 }
 
+/**
+ * A cancelled target resolution rethrows the resolver's own cancellation, which names the readiness
+ * phase only when the resolver was waiting on a running discovery.
+ */
+function rethrowIfResolutionCancelled(signal: AbortSignal, error: unknown): void {
+  if (signal.aborted) throw isRequestCanceledError(error) ? error : signal.reason;
+}
+
 function isEligible(device: DeviceInfo, input: CaptureSnapshotInput): boolean {
   return (
     device.platform === 'apple' &&
diff --git a/packages/platform-apple/src/snapshot-target.test.ts b/packages/platform-apple/src/snapshot-target.test.ts
index 09093a9c23..bb6ea0a1a8 100644
--- a/packages/platform-apple/src/snapshot-target.test.ts
+++ b/packages/platform-apple/src/snapshot-target.test.ts
@@ -217,8 +217,14 @@ test('a cancelled caller leaves discovery running for the next capture', async (
   await withAppleToolProvider(fixture.provider, async () => {
     const controller = new AbortController();
     const cancelled = fixture.resolve(ios, app, controller.signal);
-    controller.abort(new Error('request-ended'));
-    await expect(cancelled).rejects.toThrow('request-ended');
+    const reason = new Error('request-ended');
+    controller.abort(reason);
+    // The caller spent its time waiting on discovery, so its cancellation names that readiness
+    // work (#2343) and keeps the caller's own reason as the cause.
+    await expect(cancelled).rejects.toMatchObject({
+      details: { reason: 'request_canceled', readinessPhase: 'target-discovery' },
+      cause: reason,
+    });
 
     release();
     expect(await fixture.resolve(ios, app, signal())).toMatchObject({ pid: 42 });
@@ -226,6 +232,24 @@ test('a cancelled caller leaves discovery running for the next capture', async (
   });
 });
 
+test('a cancelled re-check of a known target keeps it and names no readiness work', async () => {
+  const fixture = targetFixture();
+  await withAppleToolProvider(fixture.provider, async () => {
+    await fixture.resolve(ios, app, signal());
+    const controller = new AbortController();
+    const reason = new Error('wait-deadline');
+    fixture.runCommand.mockImplementationOnce(async () => {
+      controller.abort(reason);
+      return { stdout: '', stderr: '', exitCode: 1 };
+    });
+
+    await expect(fixture.resolve(ios, app, controller.signal)).rejects.toBe(reason);
+
+    expect(await fixture.resolve(ios, app, signal())).toMatchObject({ pid: 42 });
+    expect(fixture.discoveryCount()).toBe(1);
+  });
+});
+
 test('one discovery shares a single deadline across its simctl probes and the identity read', async () => {
   const fixture = targetFixture();
   const release = deferredSpawn(fixture);
diff --git a/packages/platform-apple/src/snapshot-target.ts b/packages/platform-apple/src/snapshot-target.ts
index dfca5792c5..6da124b762 100644
--- a/packages/platform-apple/src/snapshot-target.ts
+++ b/packages/platform-apple/src/snapshot-target.ts
@@ -1,5 +1,6 @@
 import type { DeviceInfo } from '@agent-device/kernel/device';
-import { AppError } from '@agent-device/kernel/errors';
+import { AppError, createRequestCanceledError } from '@agent-device/kernel/errors';
+import type { ReadinessPhase } from '@agent-device/contracts/wait';
 import { createDetachedAttempts, waitForDetachedAttempt } from './detached-attempt.ts';
 import {
   readSimctlDevicesByRuntime,
@@ -57,6 +58,7 @@ export function createSimulatorSnapshotTargetResolver(): SimulatorSnapshotTarget
         signal,
         timeoutMs: TARGET_IDENTITY_TIMEOUT_MS,
       });
+      signal.throwIfAborted();
       if (observed === cached.processStartTime) return cached;
     }
     targets.delete(key);
@@ -67,12 +69,25 @@ export function createSimulatorSnapshotTargetResolver(): SimulatorSnapshotTarget
         return target;
       },
       wait: (waitMs, stop) =>
-        waitForDetachedAttempt({ waitMs, signal, stop, cancelled: () => signal.reason }),
+        waitForDetachedAttempt({
+          waitMs,
+          signal,
+          stop,
+          cancelled: () => discoveryCancelled(signal),
+        }),
       pending: () => targetError(TARGET_DISCOVERY_PENDING, device, appBundleId),
     });
   };
 }
 
+/** A caller cancelled while it waited on a running discovery: its time went to readiness work. */
+function discoveryCancelled(signal: AbortSignal): AppError {
+  return createRequestCanceledError(
+    { readinessPhase: 'target-discovery' satisfies ReadinessPhase },
+    signal.reason,
+  );
+}
+
 /**
  * Whether a resolver failure only says the discovery is still running. The discovery keeps going
  * under its own deadline, so asking again joins it rather than starting another.
diff --git a/src/commands/interaction/runtime/wait-absent.ts b/src/commands/interaction/runtime/wait-absent.ts
index afcd08970f..4c8a667a99 100644
--- a/src/commands/interaction/runtime/wait-absent.ts
+++ b/src/commands/interaction/runtime/wait-absent.ts
@@ -22,6 +22,7 @@ import type {
 } from './selector-wait.ts';
 import {
   createWaitPolling,
+  isSelfReportedWaitDeadline,
   type WaitFailureEvidence,
   waitTimeoutError,
   type WaitPollDeadline,
@@ -88,10 +89,10 @@ export async function waitForAbsent<Runtime extends SelectorWaitRuntime>(
     await polling.sleepUntilNextPoll();
   }
 
-  // A runner restart is the authoritative deadline cause even when an earlier
-  // readable poll saw the target. Returning stale target-present evidence would
-  // hide the retriable restart and make callers stop retrying the wrong reason.
-  if (deadline === 'runner-restart-exhausted') {
+  // A self-reported deadline cause is authoritative even when an earlier readable
+  // poll saw the target. Returning stale target-present evidence would hide the
+  // retriable cause and make callers stop retrying for the wrong reason.
+  if (isSelfReportedWaitDeadline(deadline)) {
     throw waitTimeoutError(
       `wait absent timed out for selector: ${selectorExpression}`,
       polling,
diff --git a/src/commands/interaction/runtime/wait-polling.ts b/src/commands/interaction/runtime/wait-polling.ts
index ea7d5655e4..e45cd778ca 100644
--- a/src/commands/interaction/runtime/wait-polling.ts
+++ b/src/commands/interaction/runtime/wait-polling.ts
@@ -1,5 +1,10 @@
 import { AppError, asAppError, type AppErrorDetails } from '@agent-device/kernel/errors';
-import { WAIT_REASONS, type WaitReason } from '@agent-device/contracts/wait';
+import {
+  readinessPhaseOf,
+  WAIT_REASONS,
+  type ReadinessPhase,
+  type WaitReason,
+} from '@agent-device/contracts/wait';
 import { isUnreadableCaptureContentError } from '@agent-device/contracts/android-snapshot-quality';
 import { selectorPollBudget } from '@agent-device/selectors/selector-pipeline';
 import {
@@ -15,20 +20,25 @@ import { runWithinWaitDeadline } from './wait-deadline.ts';
  */
 export const DEFAULT_WAIT_TIMEOUT_MS = SELECTOR_PIPELINE_POLICIES.wait.poll.defaultTimeoutMs;
 
-export type WaitPollDeadline = 'capture-stalled' | 'capture-truncated' | 'runner-restart-exhausted';
+export type WaitPollDeadline =
+  | 'capture-stalled'
+  | 'capture-truncated'
+  | 'runner-restart-exhausted'
+  | 'readiness-exhausted';
 
 /**
  * How one poll ended: a readable capture, an unreadable content verdict the wait rode out, a
  * producer refusal the wait rode out because the producer itself classified it as retriable, the
- * deadline cancelling the capture in flight, or that cancellation carrying runner-restart
- * evidence. Whether a readable capture matched is the caller's verdict, not the poll's.
+ * deadline cancelling the capture in flight, or that cancellation landing in a runner restart or
+ * in readiness work. Whether a readable capture matched is the caller's verdict, not the poll's.
  */
 export type WaitPollOutcome =
   | 'readable'
   | 'unreadable'
   | 'retriable'
   | 'deadline'
-  | 'runner-restart';
+  | 'runner-restart'
+  | 'readiness';
 
 /** One poll on the wait's own clock: when it started after the wait began and how long it ran. */
 export type WaitPollRecord = {
@@ -54,6 +64,7 @@ export type WaitFailureEvidence = {
   runnerRestartCommandId?: string;
   runnerInvalidatedSessionId?: string;
   runnerRestartSessionId?: string;
+  readinessPhase?: ReadinessPhase;
   logPath?: string;
   diagnosticId?: string;
 };
@@ -139,15 +150,12 @@ export function createWaitPolling(
         recordPoll(completedPollOutcome(captureWasReadable, unobserved.lastUnobservedCause()));
         return result;
       }
-      const runnerRestart = runnerRestartTimeoutEvidence(result.error);
-      recordPoll(runnerRestart ? 'runner-restart' : 'deadline');
-      timeoutEvidence = runnerRestart ?? {};
+      const cancelled = cancelledPoll(result.error, unobserved.readableCaptures());
+      recordPoll(cancelled.outcome);
+      timeoutEvidence = cancelled.evidence;
       // A capture that only becomes readable after its deadline is not evidence for this wait.
       // Count only captures that completed before runWithinWaitDeadline returned a timeout.
-      return {
-        timedOut: true as const,
-        deadline: timedOutDeadline(runnerRestart !== undefined, unobserved.readableCaptures()),
-      };
+      return { timedOut: true as const, deadline: cancelled.deadline };
     },
     hasTimeRemaining: () => remainingMs() > 0,
     failureEvidence: (): WaitFailureEvidence => ({
@@ -177,14 +185,37 @@ function completedPollOutcome(
 }
 
 /**
- * Why the deadline, not the target, ended the wait. A poll is a backend stall when no completed
+ * Why the deadline, not the target, ended the wait. A cancellation that landed in a runner restart
+ * or in readiness work says so itself. Otherwise a poll is a backend stall when no completed
  * capture established a readable observation; the poll index is not evidence. This remains true
  * after one or more unreadable content verdicts followed by a capture that consumes the remaining
  * budget.
  */
-function timedOutDeadline(runnerRestarted: boolean, readableCaptures: number): WaitPollDeadline {
-  if (runnerRestarted) return 'runner-restart-exhausted';
-  return readableCaptures === 0 ? 'capture-stalled' : 'capture-truncated';
+function cancelledPoll(
+  error: unknown,
+  readableCaptures: number,
+): {
+  outcome: WaitPollOutcome;
+  deadline: WaitPollDeadline;
+  evidence: Partial<WaitFailureEvidence>;
+} {
+  const runnerRestart = runnerRestartTimeoutEvidence(error);
+  if (runnerRestart) {
+    return {
+      outcome: 'runner-restart',
+      deadline: 'runner-restart-exhausted',
+      evidence: runnerRestart,
+    };
+  }
+  const readinessPhase = readinessPhaseOf(error instanceof AppError ? error.details : undefined);
+  if (readinessPhase) {
+    return { outcome: 'readiness', deadline: 'readiness-exhausted', evidence: { readinessPhase } };
+  }
+  return {
+    outcome: 'deadline',
+    deadline: readableCaptures === 0 ? 'capture-stalled' : 'capture-truncated',
+    evidence: {},
+  };
 }
 
 function compactPollTimeline(polls: readonly WaitPollRecord[]): WaitPollRecord[] {
@@ -212,6 +243,15 @@ function waitRunnerRestartExhaustedError(message: string, evidence: WaitFailureE
   });
 }
 
+function waitReadinessExhaustedError(message: string, evidence: WaitFailureEvidence): AppError {
+  return new AppError('COMMAND_FAILED', message, {
+    reason: WAIT_REASONS.readinessExhausted,
+    ...evidence,
+    retriable: true,
+    hint: `The wait timeout ended during readiness work (${evidence.readinessPhase}), before that poll could capture the screen. Retry with a timeout long enough to cover it.`,
+  });
+}
+
 function waitDeadlineExceededError(message: string, evidence: WaitFailureEvidence): AppError {
   return new AppError('COMMAND_FAILED', message, {
     reason: WAIT_REASONS.deadlineExceeded,
@@ -276,21 +316,42 @@ export function waitTimeoutError(
   deadline: WaitPollDeadline | undefined,
 ): AppError {
   const evidence = polling.failureEvidence();
-  if (deadline === 'runner-restart-exhausted') {
-    return waitRunnerRestartExhaustedError(message, evidence);
+  switch (deadline) {
+    case 'runner-restart-exhausted':
+      return waitRunnerRestartExhaustedError(message, evidence);
+    case 'readiness-exhausted':
+      // A refusal an earlier poll hit (the app is not running, say) is an answer the readiness
+      // work on the final poll does not replace.
+      rethrowNeverReadableCause(polling, evidence, false);
+      return waitReadinessExhaustedError(message, evidence);
+    case 'capture-stalled':
+      // Whether a content verdict outranks the stall verdict is the caller's policy; a refusal is
+      // preserved either way.
+      rethrowNeverReadableCause(polling, evidence, polling.preserveUnreadableOnStall === true);
+      return waitCaptureStalledError(message, evidence);
+    case 'capture-truncated':
+      return waitDeadlineExceededError(message, evidence);
+    case undefined:
+      rethrowNeverReadableCause(polling, evidence, true);
+      return evidence.readableCaptures === 0
+        ? waitCaptureStalledError(message, evidence)
+        : waitTargetAbsentError(message, evidence);
+    default:
+      return assertNever(deadline);
   }
-  if (deadline === 'capture-stalled') {
-    // Whether a content verdict outranks the stall verdict is the caller's policy; a refusal is
-    // preserved either way.
-    rethrowNeverReadableCause(polling, evidence, polling.preserveUnreadableOnStall === true);
-    return waitCaptureStalledError(message, evidence);
-  }
-  if (deadline === 'capture-truncated') return waitDeadlineExceededError(message, evidence);
+}
+
+/**
+ * Whether the deadline's cause was reported by the work it cancelled — a runner restart or
+ * readiness work — rather than inferred from the captures. Such a cause outranks evidence an
+ * earlier readable capture left behind.
+ */
+export function isSelfReportedWaitDeadline(deadline: WaitPollDeadline | undefined): boolean {
+  return deadline === 'runner-restart-exhausted' || deadline === 'readiness-exhausted';
+}
 
-  rethrowNeverReadableCause(polling, evidence, true);
-  return evidence.readableCaptures === 0
-    ? waitCaptureStalledError(message, evidence)
-    : waitTargetAbsentError(message, evidence);
+function assertNever(value: never): never {
+  throw new Error(`Unhandled wait deadline: ${String(value)}`);
 }
 
 function runnerRestartTimeoutEvidence(error: unknown): Partial<WaitFailureEvidence> | undefined {
diff --git a/src/daemon/__tests__/wait-runtime.test.ts b/src/daemon/__tests__/wait-runtime.test.ts
index fe84f4fa1c..6fab968aba 100644
--- a/src/daemon/__tests__/wait-runtime.test.ts
+++ b/src/daemon/__tests__/wait-runtime.test.ts
@@ -1,6 +1,6 @@
 import { expect, test, vi } from 'vitest';
-import { WAIT_REASONS } from '@agent-device/contracts/wait';
-import { AppError } from '@agent-device/kernel/errors';
+import { WAIT_REASONS, type ReadinessPhase } from '@agent-device/contracts/wait';
+import { AppError, createRequestCanceledError } from '@agent-device/kernel/errors';
 import {
   type DeviceBinding,
   type RuntimeFacts,
@@ -743,6 +743,142 @@ test('strict wait absent does not mask a runner restart after an earlier present
   expect(response.error.details?.reason).not.toBe(WAIT_REASONS.targetPresent);
 });
 
+/**
+ * The platform's cancellation as production throws it when the wait deadline lands mid-capture.
+ * With a phase, the runner start or the Simulator app discovery was still running; without one,
+ * the capture was cancelled in steady-state work such as the cached target re-check.
+ */
+function cancelledCapture(phase: ReadinessPhase | undefined, beforeStall: SnapshotResult[] = []) {
+  const readable = [...beforeStall];
+  return vi.fn(async (input: CaptureSnapshotInput) => {
+    const next = readable.shift();
+    if (next) return next;
+    const signal = input.signal;
+    if (!signal) throw new Error('the poll deadline never reached the platform');
+    await new Promise<void>((resolve) => {
+      if (signal.aborted) return resolve();
+      signal.addEventListener('abort', () => resolve(), { once: true });
+    });
+    throw createRequestCanceledError(phase ? { readinessPhase: phase } : {}, signal.reason);
+  });
+}
+
+test.for(['runner-start', 'target-discovery'] as const)(
+  'a %s that outlasts the wait reports readiness exhaustion, not a capture stall',
+  async (phase) => {
+    const harness = waitRuntimeHarness({ captureSnapshot: cancelledCapture(phase) });
+
+    const { response } = await runWait(['text', 'Ready', '50'], harness);
+
+    expect(response.ok).toBe(false);
+    if (response.ok) return;
+    expect(response.error.details).toMatchObject({
+      reason: WAIT_REASONS.readinessExhausted,
+      readinessPhase: phase,
+      retriable: true,
+      readableCaptures: 0,
+      captures: 1,
+      polls: [{ startedMs: 0, outcome: 'readiness' }],
+    });
+    expect(response.error.details?.captureStalled).toBeUndefined();
+  },
+);
+
+test('strict wait absent reports readiness exhaustion over an earlier present capture', async () => {
+  const captureSnapshot = cancelledCapture('target-discovery', [
+    {
+      nodes: [{ index: 0, depth: 0, type: 'Button', label: 'Ready', hittable: true }],
+      backend: 'web',
+      producer: 'agent-browser',
+    },
+  ]);
+  const harness = waitRuntimeHarness({ captureSnapshot });
+
+  const { response } = await runWait(['absent', 'label="Ready"', '800'], harness);
+
+  expect(response.ok).toBe(false);
+  if (response.ok) return;
+  expect(response.error.details).toMatchObject({
+    reason: WAIT_REASONS.readinessExhausted,
+    readinessPhase: 'target-discovery',
+    readableCaptures: 1,
+  });
+});
+
+test('an earlier retriable refusal outranks readiness work on the final poll', async () => {
+  // Live on iOS: the runner answered APP_NOT_RUNNING, then the next poll's app discovery was cut by
+  // the deadline. The refusal is the actionable answer; readiness stays in the evidence.
+  const notRunning = new AppError('COMMAND_FAILED', "app 'com.example.app' is not running", {
+    runnerErrorCode: 'APP_NOT_RUNNING',
+    retriable: true,
+  });
+  let poll = 0;
+  const readiness = cancelledCapture('target-discovery');
+  const captureSnapshot = vi.fn(async (input: CaptureSnapshotInput) => {
+    if (poll++ === 0) throw notRunning;
+    return await readiness(input);
+  });
+  const harness = waitRuntimeHarness({ captureSnapshot });
+
+  const { response } = await runWait(['text', 'Ready', '800'], harness);
+
+  expect(response.ok).toBe(false);
+  if (response.ok) return;
+  expect(response.error.message).toContain('is not running');
+  expect(response.error.details).toMatchObject({
+    reason: WAIT_REASONS.captureStalled,
+    runnerErrorCode: 'APP_NOT_RUNNING',
+    readinessPhase: 'target-discovery',
+    readableCaptures: 0,
+  });
+  expect(response.error.details?.polls).toMatchObject([
+    { outcome: 'retriable' },
+    { outcome: 'readiness' },
+  ]);
+});
+
+test('strict wait absent keeps its present evidence when a steady-state capture is cancelled', async () => {
+  const captureSnapshot = cancelledCapture(undefined, [
+    {
+      nodes: [{ index: 0, depth: 0, type: 'Button', label: 'Ready', hittable: true }],
+      backend: 'web',
+      producer: 'agent-browser',
+    },
+  ]);
+  const harness = waitRuntimeHarness({ captureSnapshot });
+
+  const { response } = await runWait(['absent', 'label="Ready"', '800'], harness);
+
+  expect(response.ok).toBe(false);
+  if (response.ok) return;
+  expect(response.error.details).toMatchObject({
+    reason: WAIT_REASONS.targetPresent,
+    readableCaptures: 1,
+  });
+  expect(response.error.details?.readinessPhase).toBeUndefined();
+});
+
+test('a positive wait whose steady-state capture is cancelled reports the deadline, not readiness', async () => {
+  const captureSnapshot = cancelledCapture(undefined, [
+    {
+      nodes: [{ index: 0, depth: 0, type: 'Button', label: 'Checkout', hittable: true }],
+      backend: 'web',
+      producer: 'agent-browser',
+    },
+  ]);
+  const harness = waitRuntimeHarness({ captureSnapshot });
+
+  const { response } = await runWait(['text', 'Ready', '800'], harness);
+
+  expect(response.ok).toBe(false);
+  if (response.ok) return;
+  expect(response.error.details).toMatchObject({
+    reason: WAIT_REASONS.deadlineExceeded,
+    readableCaptures: 1,
+  });
+  expect(response.error.details?.readinessPhase).toBeUndefined();
+});
+
 test('a readable capture that lacks the target stays target-absent, not capture-stalled', async () => {
   const harness = waitRuntimeHarness({
     nodesPerPoll: [[{ index: 0, depth: 0, type: 'Button', label: 'Checkout', hittable: true }]],
diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md
index e5b2974062..8a74a11cbb 100644
--- a/website/docs/docs/commands.md
+++ b/website/docs/docs/commands.md
@@ -442,8 +442,8 @@ agent-device alert dismiss
 - `wait @ref` resolves the ref to its label/text from that stored snapshot, then polls for that text; it does not track the original node identity.
 - Because `wait @ref` is text-based after resolution, duplicate labels can match a different element than the original ref target.
 - `wait` shares the selector/snapshot resolution flow used by `click`, `fill`, `get`, and `is`.
-- Wait failures carry a structured `error.details.reason` in `--json` output: `wait_target_absent` proves a positive wait never found a match; `wait_target_present` means strict `wait absent` reached its deadline with valid captures that still contained matches; `predicate_failed` means strict `wait absent` could not prove absence because no valid capture arrived, with the final observation/diagnostic preserved; `wait_capture_stalled` means no readable capture arrived and is retriable; `wait_deadline_exceeded` means a later capture consumed the remaining budget after an earlier readable capture; `wait_landmark_identity_mismatch` is a replay destination-guard refusal; and `wait_stable_timeout` means the UI did not settle. Use `readableCaptures`, `waitedMs`, `matches`, and `firstMatch` instead of parsing error text. `firstMatch` carries identity/text evidence only; absence failures do not claim visibility or rect evidence.
-- Polling wait timeouts (`wait <selector>`, `wait text`, `wait @ref`, and `wait absent` once a readable capture has been seen) also carry `captures` (every poll attempted), `readableCaptures`, and `polls`, one entry per poll with `startedMs` on the wait's own clock, `durationMs`, and `outcome` (`readable`, `unreadable`, `retriable` for a poll the producer refused with a failure it marked retriable, `deadline`, or `runner-restart`), so a timeout says where its budget went; long waits keep the first five and last twenty-five polls. A replayed selector wait refused for a recorded landmark mismatch (`wait_landmark_identity_mismatch`) carries the same poll evidence next to its mismatch details. A wait that never saw a readable capture reports the cause its polls hit instead of a generic timeout: a content verdict is preserved as its producer wrote it, while a refusal the producer marked retriable keeps its code, message and retry details **and** carries the poll evidence above, so an exhausted budget stays distinguishable from a single immediate refusal. `wait --stable` timeouts and a never-readable strict absence keep their own diagnostics. `logPath` links the full request log.
+- Wait failures carry a structured `error.details.reason` in `--json` output: `wait_target_absent` proves a positive wait never found a match; `wait_target_present` means strict `wait absent` reached its deadline with valid captures that still contained matches; `predicate_failed` means strict `wait absent` could not prove absence because no valid capture arrived, with the final observation/diagnostic preserved; `wait_capture_stalled` means no readable capture arrived and is retriable; `wait_deadline_exceeded` means a later capture consumed the remaining budget after an earlier readable capture; `wait_readiness_exhausted` means the deadline ended a poll that was still getting the iOS runner to answer its first command or finding the Simulator app, named by `readinessPhase` (`runner-start` or `target-discovery`), so a retry needs a timeout that covers that work; `wait_landmark_identity_mismatch` is a replay destination-guard refusal; and `wait_stable_timeout` means the UI did not settle. Use `readableCaptures`, `waitedMs`, `matches`, and `firstMatch` instead of parsing error text. `firstMatch` carries identity/text evidence only; absence failures do not claim visibility or rect evidence.
+- Polling wait timeouts (`wait <selector>`, `wait text`, `wait @ref`, and `wait absent` once a readable capture has been seen) also carry `captures` (every poll attempted), `readableCaptures`, and `polls`, one entry per poll with `startedMs` on the wait's own clock, `durationMs`, and `outcome` (`readable`, `unreadable`, `retriable` for a poll the producer refused with a failure it marked retriable, `deadline`, `runner-restart`, or `readiness`), so a timeout says where its budget went; long waits keep the first five and last twenty-five polls. A replayed selector wait refused for a recorded landmark mismatch (`wait_landmark_identity_mismatch`) carries the same poll evidence next to its mismatch details. A wait that never saw a readable capture reports the cause its polls hit instead of a generic timeout: a content verdict is preserved as its producer wrote it, while a refusal the producer marked retriable keeps its code, message and retry details **and** carries the poll evidence above, so an exhausted budget stays distinguishable from a single immediate refusal. `wait --stable` timeouts and a never-readable strict absence keep their own diagnostics. `logPath` links the full request log.
 - `alert` inspects or handles system alerts on iOS simulator, macOS desktop, and Android native/runtime permission dialogs.
 - `alert` without an action is equivalent to `alert get`.
 - `accept` and `dismiss` are sent once on every platform. A lost or unconfirmed response is reported as an error and never replayed; run `alert get` before acting again.

From d7a1f2cc5da9c372ddd593c20dc86840f1b09163 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 24 Sep 2026 19:42:17 +0200
Subject: [PATCH 113/132] refactor(ios-runner): make the snapshot quality
 verdict state a closed enum (#2888)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* refactor(ios-runner): close the snapshot quality verdict state vocabulary

The runner wrote the verdict `state` as a free String while the host accepts only
healthy | recovered | sparse, and the contracts annotation reader cast any string state into
the verdict type. A typo or a one-sided rename therefore dropped the verdict and its
disclosure.

`SnapshotQualityState` now owns the runner side, raw-value Codable keeps the wire JSON
unchanged, and `reasonCode` stays open. The kernel states the vocabulary once as
`SNAPSHOT_QUALITY_STATES` with `isSnapshotQualityState`; capture-kit and contracts both read
through it, so neither keeps a second accepted-state set and the annotation reader rejects an
unknown state instead of casting it. `contracts/fixtures/ios-snapshot-quality-states.json` is
the table the Swift `allCases` order and the kernel tuple are each pinned to.

* refactor(substrate): hold the verdict state map in each eager-frozen reader

The readers reached the vocabulary through `isSnapshotQualityState` in `kernel/snapshot.ts`, which
made that module eager in six entry closures the eager-closure gate holds at its merge-base size —
the contracts capture façade at 9 modules, capture-kit's verdict reader at 2. The only module those
two closures already evaluate is the one whose edge the gate rejects, so no single runtime home for
the set exists.

Each reader now keys a `Record<SnapshotQualityState, true>` over the kernel union, the home the
gate prescribes for code that has to live where it is already evaluated. Membership goes through
`Object.hasOwn`, so an inherited key is never a state, and a state added to the tuple without a key
in a reader is a compile error there: the guarantee the shared import was bought for, without the
eager edge. Both reader tests walk the tuple and the kernel test still pins it to the fixture.

* refactor(snapshot): gate the backend name, and stop pinning vocabulary order

The annotation reader was one predicate plus a blanket cast. `backend` names the recovery strategy
in the warning line, so it goes through a declared map keyed against the kernel union now, and
capture-kit lost both of its `as` casts on the way: the strategy is gated on the capability table it
already imports, the reason code on an exhaustive map over its union.

A full projection in contracts was tried and the repo's own gates refuse it — fallow reports a
4-group, 104-line clone family against capture-kit's normalizer, on top of the eager-closure gate
that already forbids a shared reader. The re-read stays in the shape `readTargetActivation` in the
same file uses: check the two names that decide presentation, forward what this module published, and
pin the pair payload-by-payload from capture-kit's test.

Order pinning drops out. The fixture is compared as a set on both sides, the stamping test asserts
each case's own raw value, and the unread 28-line capture builder and its import are gone.

* refactor(contracts): name the verdict re-read apart from the strict reader

Two same-named readers with different trust levels is how the half-migration read as validating more
than it does. This module's version checks the two load-bearing names and forwards what this repo
published, in the shape `readTargetActivation` uses, so it is now `readPublishedSnapshotQualityVerdict`
and the strict per-field reading keeps the plain name for capture-kit's untrusted-payload reader.

* refactor(snapshot): answer the review round on sharing, parity, and evidence

The eager-closure refusal the review asked to be pointed at or filed is not a table of budgets: the
gate ratchets every entry's closure against the committed merge-base tree, so the numbers to read are
9 for `facades/capture.ts` and 2 for `snapshot-quality-verdict.ts`. Re-installing one shared kernel
predicate for both readers on this head fails six entries and names both of those, which is why the
vocabulary stays a map per reader; recorded on #2872 as the accepted deviation.

The `android-helper` asymmetry is not real: `SNAPSHOT_QUALITY_BACKEND_CAPABILITIES` merges the
Android declaration, so both readers accept that strategy and the parity table now carries the row
instead of omitting it. The client-side drop of an unknown state or backend gets its CHANGELOG entry,
the justification comments shrink to one constraint sentence each, the kernel test keeps only its
`@ts-expect-error`, and the word left dangling by the last rename goes.
---
 .../RunnerTests+Snapshot.swift                |  2 +-
 .../RunnerTests+SnapshotCapturePlan.swift     | 26 ++++---
 ...ts+SnapshotCapturePlanOccupancyTests.swift |  4 +-
 ...RunnerTests+SnapshotCapturePlanTests.swift | 22 +++---
 ...unnerTests+SnapshotQualityStateTests.swift | 68 ++++++++++++++++++
 .../UnitTests/RunnerTests+SnapshotTests.swift |  2 +-
 .../fixtures/ios-snapshot-quality-states.json |  1 +
 .../src/snapshot-quality-verdict.test.ts      | 58 +++++++++++++++
 .../src/snapshot-quality-verdict.ts           | 71 +++++++++----------
 .../src/snapshot-capture-annotations.test.ts  | 58 +++++++++++++++
 .../src/snapshot-capture-annotations.ts       | 50 +++++++++++--
 .../src/snapshot-quality-states.test.ts       | 38 ++++++++++
 packages/kernel/src/snapshot.ts               | 20 +++++-
 13 files changed, 351 insertions(+), 69 deletions(-)
 create mode 100644 apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotQualityStateTests.swift
 create mode 100644 contracts/fixtures/ios-snapshot-quality-states.json
 create mode 100644 packages/kernel/src/snapshot-quality-states.test.ts

diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Snapshot.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Snapshot.swift
index f87b5b0648..b21d55b1da 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Snapshot.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Snapshot.swift
@@ -535,7 +535,7 @@ extension RunnerTests {
     return sparseTruncatedSnapshotPayload(
       message: recoveredSnapshotMessage(failure),
       snapshotQuality: SnapshotQuality(
-        state: "sparse",
+        state: .sparse,
         backend: SnapshotBackendKind.recursiveTree.rawValue,
         reason: failure.message,
         reasonCode: "ax-rejected",
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotCapturePlan.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotCapturePlan.swift
index f1547821ba..770dde5524 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotCapturePlan.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotCapturePlan.swift
@@ -8,11 +8,21 @@ import AgentDeviceSnapshotPresentation
 // stamp the outcome with a structured quality verdict so the daemon renders state instead of
 // re-deriving it from node shapes. Recovery ordering is data here, never a per-call-site branch.
 
+/// The closed set of verdict states the host accepts. The wire strings are the shared table at
+/// `contracts/fixtures/ios-snapshot-quality-states.json`, which `allCases` is pinned to; `reasonCode`
+/// stays open because an unknown one costs only its wording, never the verdict.
+enum SnapshotQualityState: String, Codable, CaseIterable {
+  /// First backend produced a usable tree.
+  case healthy
+  /// A later backend did.
+  case recovered
+  /// No backend produced a usable tree; the best attempt is returned as-is.
+  case sparse
+}
+
 /// Structured quality verdict shipped with every iOS snapshot payload.
 struct SnapshotQuality: Codable {
-  /// healthy: first backend produced a usable tree. recovered: a later backend did.
-  /// sparse: no backend produced a usable tree; the best attempt is returned as-is.
-  let state: String
+  let state: SnapshotQualityState
   /// Backend that produced the returned payload: tree | queries | private-ax.
   let backend: String
   /// Why recovery ran (first failure), why the payload is degraded, or why an internal backend
@@ -391,7 +401,7 @@ extension RunnerTests {
       return stampedSnapshotPayload(
         capture,
         backend: kind,
-        state: recovered ? "recovered" : "healthy",
+        state: recovered ? .recovered : .healthy,
         reason: recovered || firstFailure?.code == "requested-backend" ? firstFailure : nil
       )
     }
@@ -416,11 +426,11 @@ extension RunnerTests {
     }
 
     let fallbackPayload =
-      best.map { stampedSnapshotPayload($0.capture, backend: $0.kind, state: "sparse", reason: firstFailure) }
+      best.map { stampedSnapshotPayload($0.capture, backend: $0.kind, state: .sparse, reason: firstFailure) }
       ?? stampedSnapshotPayload(
         SnapshotBackendCapture(payload: sparseTruncatedSnapshotPayload(), effectiveDepth: nil),
         backend: effectivePlan.last ?? plan.last ?? .recursiveTree,
-        state: "sparse",
+        state: .sparse,
         reason: firstFailure
       )
     return fallbackPayload
@@ -679,7 +689,7 @@ extension RunnerTests {
   func stampedSnapshotPayload(
     _ capture: SnapshotBackendCapture,
     backend: SnapshotBackendKind,
-    state: String,
+    state: SnapshotQualityState,
     reason: (reason: String, code: String)?
   ) -> DataPayload {
     let health: RunnerAccessibilityHealth = reason?.code == "ax-rejected" ? .unavailable : .healthy
@@ -704,7 +714,7 @@ extension RunnerTests {
       // "recovered") stays untruncated, so strict absence reads can trust it. Only a real cap
       // (payload truncation, a depth-limited private AX capture) or a sparse terminal payload
       // is truncated.
-      truncated: payload.truncated == true || state == "sparse" || capture.effectiveDepth != nil,
+      truncated: payload.truncated == true || state == .sparse || capture.effectiveDepth != nil,
       qualityPayload: capture.qualityPayload.flatMap { quality in
         guard let nodes = quality.nodes else { return nil }
         return SnapshotQualityPayload(nodes: nodes, truncated: quality.truncated == true)
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotCapturePlanOccupancyTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotCapturePlanOccupancyTests.swift
index 7f12cb87b6..b191787fb5 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotCapturePlanOccupancyTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotCapturePlanOccupancyTests.swift
@@ -148,7 +148,7 @@ extension RunnerTests {
     XCTAssertNil(box.error)
     let quality = try XCTUnwrap(box.payload?.snapshotQuality)
     XCTAssertEqual(quality.backend, SnapshotBackendKind.privateAX.rawValue)
-    XCTAssertEqual(quality.state, "recovered")
+    XCTAssertEqual(quality.state, .recovered)
     XCTAssertTrue(
       quality.reason?.contains("tree capture exceeded") == true,
       "the tree XPC, not the viewport read, must be the abandoned block: \(quality.reason ?? "nil")"
@@ -344,7 +344,7 @@ extension RunnerTests {
       SnapshotBackendKind.privateAX.rawValue,
       "a sweep that ended on its slice deadline is a tier timeout, not an accepted capture"
     )
-    XCTAssertEqual(quality?.state, "recovered")
+    XCTAssertEqual(quality?.state, .recovered)
     XCTAssertGreaterThan(box.payload?.nodes?.count ?? 0, 1, "private AX answers with a real tree")
     XCTAssertFalse(box.abandonedAtReturn, "the sweep must answer inside its own main-thread hop")
     XCTAssertTrue(
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotCapturePlanTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotCapturePlanTests.swift
index 87d3ad061e..b1ea3656d3 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotCapturePlanTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotCapturePlanTests.swift
@@ -162,7 +162,7 @@ extension RunnerTests {
     let payload = stampedSnapshotPayload(
       capture,
       backend: .recursiveTree,
-      state: "healthy",
+      state: .healthy,
       reason: nil
     )
 
@@ -187,7 +187,7 @@ extension RunnerTests {
         customActions: coverage
       ),
       backend: .recursiveTree,
-      state: "healthy",
+      state: .healthy,
       reason: nil
     )
     XCTAssertNil(silent.message)
@@ -200,7 +200,7 @@ extension RunnerTests {
         effectiveDepth: 4
       ),
       backend: .privateAX,
-      state: "recovered",
+      state: .recovered,
       reason: (reason: "tree capture timed out", code: "budget")
     )
     XCTAssertEqual(underlying.message, "underlying")
@@ -224,24 +224,24 @@ extension RunnerTests {
     // The CI signature behind `is absent ... capture was truncated`: a complete private AX
     // tree selected while the XCTest channel is penalized is whole, and must say so.
     let recovered = stampedSnapshotPayload(
-      complete, backend: .privateAX, state: "recovered", reason: deferred)
-    XCTAssertEqual(recovered.snapshotQuality?.state, "recovered")
+      complete, backend: .privateAX, state: .recovered, reason: deferred)
+    XCTAssertEqual(recovered.snapshotQuality?.state, .recovered)
     XCTAssertEqual(recovered.truncated, false)
 
     let depthLimited = stampedSnapshotPayload(
       SnapshotBackendCapture(payload: complete.payload, effectiveDepth: 56),
-      backend: .privateAX, state: "recovered", reason: deferred)
+      backend: .privateAX, state: .recovered, reason: deferred)
     XCTAssertEqual(depthLimited.truncated, true)
 
     let cappedPayload = stampedSnapshotPayload(
       SnapshotBackendCapture(
         payload: DataPayload(nodes: complete.payload.nodes ?? [], truncated: true),
         effectiveDepth: nil),
-      backend: .recursiveTree, state: "healthy", reason: nil)
+      backend: .recursiveTree, state: .healthy, reason: nil)
     XCTAssertEqual(cappedPayload.truncated, true)
 
     let sparse = stampedSnapshotPayload(
-      complete, backend: .querySweep, state: "sparse",
+      complete, backend: .querySweep, state: .sparse,
       reason: ("snapshot returned no semantic controls or content", "sparse-tree"))
     XCTAssertEqual(sparse.truncated, true)
   }
@@ -260,7 +260,7 @@ extension RunnerTests {
     let payload = stampedSnapshotPayload(
       capture,
       backend: .recursiveTree,
-      state: "healthy",
+      state: .healthy,
       reason: nil
     )
 
@@ -291,7 +291,7 @@ extension RunnerTests {
     let payload = stampedSnapshotPayload(
       capture,
       backend: .recursiveTree,
-      state: "healthy",
+      state: .healthy,
       reason: nil
     )
 
@@ -507,7 +507,7 @@ extension RunnerTests {
 
     let quality = try XCTUnwrap(capped.snapshotQuality)
     XCTAssertEqual(quality.backend, SnapshotBackendKind.privateAX.rawValue)
-    XCTAssertNotEqual(quality.state, "sparse")
+    XCTAssertNotEqual(quality.state, .sparse)
     let nodes = try XCTUnwrap(capped.nodes)
     XCTAssertGreaterThan(nodes.count, 1)
     XCTAssertEqual(nodes.map(\.depth).max(), 1)
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotQualityStateTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotQualityStateTests.swift
new file mode 100644
index 0000000000..8ef84b8fc8
--- /dev/null
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotQualityStateTests.swift
@@ -0,0 +1,68 @@
+import XCTest
+
+#if AGENT_DEVICE_RUNNER_UNIT_TESTS
+extension RunnerTests {
+  private struct StampedWireVerdict: Decodable {
+    struct Quality: Decodable {
+      let state: String
+    }
+    let snapshotQuality: Quality
+  }
+
+  private func loadSnapshotQualityStatesFixture() throws -> [String] {
+    let fixtureURL = URL(fileURLWithPath: #filePath)
+      .deletingLastPathComponent() // UnitTests
+      .deletingLastPathComponent() // AgentDeviceRunnerUITests
+      .deletingLastPathComponent() // AgentDeviceRunner
+      .deletingLastPathComponent() // runner
+      .deletingLastPathComponent() // apple
+      .deletingLastPathComponent() // repo root
+      .appendingPathComponent("contracts")
+      .appendingPathComponent("fixtures")
+      .appendingPathComponent("ios-snapshot-quality-states.json")
+    return try JSONDecoder().decode([String].self, from: Data(contentsOf: fixtureURL))
+  }
+
+  /// The one claim of this file: the runner's closed enum and the shared TypeScript table name the
+  /// same states. The kernel's `SNAPSHOT_QUALITY_STATES` is pinned to it too, so the two runtimes
+  /// cannot drift into a verdict the host drops along with its disclosure. Compared as a set: the
+  /// names are the contract, and a reordering of `allCases` cannot produce a wrong verdict.
+  func testSnapshotQualityStatesMatchSharedWireFixture() throws {
+    XCTAssertEqual(
+      Set(try loadSnapshotQualityStatesFixture()),
+      Set(SnapshotQualityState.allCases.map(\.rawValue)),
+      "update the fixture and the kernel tuple together with the enum"
+    )
+  }
+
+  /// What the daemon receives for each state, taken from the production stamping path rather than a
+  /// hand-built verdict: the wire string is the case's own raw value, so a change of
+  /// representation — an `Int` backing, a nested object — goes red here on the actual payload, and
+  /// a renamed raw value goes red in the fixture test above.
+  func testStampedVerdictEncodesTheCaseRawValue() throws {
+    let capture = SnapshotBackendCapture(
+      payload: DataPayload(nodes: [], truncated: false),
+      effectiveDepth: nil
+    )
+    for state in SnapshotQualityState.allCases {
+      let payload = stampedSnapshotPayload(
+        capture,
+        backend: .recursiveTree,
+        state: state,
+        reason: nil
+      )
+      let wire = try JSONDecoder().decode(
+        StampedWireVerdict.self,
+        from: JSONEncoder().encode(payload)
+      )
+      XCTAssertEqual(wire.snapshotQuality.state, state.rawValue)
+    }
+  }
+
+  /// Closed in both directions: a wire string nobody declared never becomes a verdict.
+  func testVerdictStateRejectsAnUndeclaredWireString() throws {
+    let json = Data(#"{"state":"degraded","backend":"tree"}"#.utf8)
+    XCTAssertThrowsError(try JSONDecoder().decode(SnapshotQuality.self, from: json))
+  }
+}
+#endif
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotTests.swift
index c679bbcbde..20b3b9631e 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotTests.swift
@@ -23,7 +23,7 @@ extension RunnerTests {
     XCTAssertEqual(payload.runnerFatalReason, Self.axSnapshotUnavailableReason)
     // The planned terminal result carries the structured verdict like every other planned
     // snapshot — downstream sparse handling keys off it, not off node shapes.
-    XCTAssertEqual(payload.snapshotQuality?.state, "sparse")
+    XCTAssertEqual(payload.snapshotQuality?.state, .sparse)
     XCTAssertEqual(payload.snapshotQuality?.reasonCode, "ax-rejected")
     XCTAssertEqual(payload.snapshotQuality?.reason, Self.axSnapshotFailureMessage)
     XCTAssertNil(currentApp)
diff --git a/contracts/fixtures/ios-snapshot-quality-states.json b/contracts/fixtures/ios-snapshot-quality-states.json
new file mode 100644
index 0000000000..ab9c625897
--- /dev/null
+++ b/contracts/fixtures/ios-snapshot-quality-states.json
@@ -0,0 +1 @@
+["healthy", "recovered", "sparse"]
diff --git a/packages/capture-kit/src/snapshot-quality-verdict.test.ts b/packages/capture-kit/src/snapshot-quality-verdict.test.ts
index ea8afbc157..0c27cf5588 100644
--- a/packages/capture-kit/src/snapshot-quality-verdict.test.ts
+++ b/packages/capture-kit/src/snapshot-quality-verdict.test.ts
@@ -1,6 +1,8 @@
 import { test } from 'vitest';
 import assert from 'node:assert/strict';
 
+import { readSerializedSnapshotCaptureAnnotations } from '@agent-device/contracts/capture';
+import { SNAPSHOT_QUALITY_STATES } from '@agent-device/kernel/snapshot';
 import {
   isSparseSnapshotQualityVerdict,
   preferredSnapshotBackendForVerdict,
@@ -47,6 +49,22 @@ test('readSnapshotQualityVerdict rejects unknown state or backend as verdict-abs
   assert.equal(readSnapshotQualityVerdict({ state: 'sparse', backend: 'mystery' }), undefined);
   assert.equal(readSnapshotQualityVerdict({ backend: 'tree' }), undefined);
   assert.equal(readSnapshotQualityVerdict(null), undefined);
+  // An inherited key is not a declared state: membership stays on the map's own keys.
+  assert.equal(readSnapshotQualityVerdict({ state: 'constructor', backend: 'tree' }), undefined);
+});
+
+test('readSnapshotQualityVerdict reads every declared wire state', () => {
+  for (const state of SNAPSHOT_QUALITY_STATES) {
+    assert.deepEqual(readSnapshotQualityVerdict({ state, backend: 'tree' }), {
+      state,
+      backend: 'tree',
+      reason: undefined,
+      reasonCode: undefined,
+      customActions: undefined,
+      effectiveDepth: undefined,
+      collapsedLeafIndexes: undefined,
+    });
+  }
 });
 
 test('readSnapshotQualityVerdict keeps the verdict but drops an unknown reasonCode', () => {
@@ -98,3 +116,43 @@ test('preferredSnapshotBackendForVerdict pins only private-ax captures', () => {
   );
   assert.equal(preferredSnapshotBackendForVerdict(undefined), undefined);
 });
+
+/**
+ * Two readings of one verdict exist on purpose: this module normalizes an untrusted runner payload,
+ * while contracts re-publishes what this repo published and normalizes nothing (the eager-closure
+ * gate forbids either reaching a shared module, and the duplication gate refuses a second
+ * normalization). They must still agree on which payloads are a verdict at all: a name one version
+ * cannot speak is verdict-absent on both sides of the daemon boundary.
+ */
+const VERDICT_PAYLOADS: unknown[] = [
+  { state: 'sparse', backend: 'private-ax' },
+  { state: 'healthy', backend: 'tree', reason: 'ok', reasonCode: 'requested-backend' },
+  { state: 'recovered', backend: 'queries', reason: 42, effectiveDepth: '56' },
+  { state: 'sparse', backend: 'tree', collapsedLeafIndexes: [3, 'four'] },
+  { state: 'sparse', backend: 'tree', customActions: { read: 12 } },
+  { state: 'sparse', backend: 'tree', customActions: { read: 12, candidates: 19 } },
+  { state: 'sparse', backend: 'tree', timing: { acquisitionMs: 12.5 } },
+  { state: 'sparse', backend: 'tree', timing: { acquisitionMs: 12.5, presentationMs: 34.75 } },
+  { state: 'sparse', backend: 'tree', reasonCode: 'future-code' },
+  { state: 'recovered', backend: 'android-helper', reasonCode: 'requested-backend' },
+  { state: 'degraded', backend: 'tree' },
+  { state: 'sparse', backend: 'uiautomator' },
+  { state: 'constructor', backend: 'constructor' },
+  { backend: 'tree' },
+  { state: 'sparse' },
+  null,
+  'verdict',
+];
+
+test('the contracts re-read calls a verdict a verdict on every payload', () => {
+  for (const payload of VERDICT_PAYLOADS) {
+    const reRead = readSerializedSnapshotCaptureAnnotations({
+      snapshotQuality: payload,
+    }).snapshotQuality;
+    assert.equal(
+      reRead === undefined,
+      readSnapshotQualityVerdict(payload) === undefined,
+      JSON.stringify(payload),
+    );
+  }
+});
diff --git a/packages/capture-kit/src/snapshot-quality-verdict.ts b/packages/capture-kit/src/snapshot-quality-verdict.ts
index 2913abe32f..475d09009f 100644
--- a/packages/capture-kit/src/snapshot-quality-verdict.ts
+++ b/packages/capture-kit/src/snapshot-quality-verdict.ts
@@ -1,24 +1,35 @@
-import type { SnapshotQualityVerdict } from '@agent-device/kernel/snapshot';
+import type { SnapshotQualityState, SnapshotQualityVerdict } from '@agent-device/kernel/snapshot';
 import { SNAPSHOT_QUALITY_BACKEND_CAPABILITIES } from './snapshot-quality-backend-capabilities.ts';
 
-const SNAPSHOT_QUALITY_STATES = new Set<SnapshotQualityVerdict['state']>([
-  'healthy',
-  'recovered',
-  'sparse',
-]);
-const SNAPSHOT_QUALITY_BACKENDS = new Set<SnapshotQualityVerdict['backend']>(
-  Object.keys(SNAPSHOT_QUALITY_BACKEND_CAPABILITIES) as SnapshotQualityVerdict['backend'][],
-);
-const SNAPSHOT_QUALITY_REASON_CODES = new Set<NonNullable<SnapshotQualityVerdict['reasonCode']>>([
-  'ax-rejected',
-  'sparse-tree',
-  'budget',
-  'no-nodes',
-  'capture-failed',
-  'presentation-failed',
-  'deferred',
-  'requested-backend',
-]);
+/**
+ * The verdict names this version can speak, keyed against the kernel unions so a map cannot fall
+ * behind one. They cannot be one shared kernel predicate: this module's eager closure is frozen at
+ * its merge-base size (#2872). The strategies need no map — `SNAPSHOT_QUALITY_BACKEND_CAPABILITIES`
+ * is already keyed by exactly those names.
+ */
+const DECLARED_STATES: Record<SnapshotQualityState, true> = {
+  healthy: true,
+  recovered: true,
+  sparse: true,
+};
+
+const DECLARED_REASON_CODES: Record<NonNullable<SnapshotQualityVerdict['reasonCode']>, true> = {
+  'ax-rejected': true,
+  'sparse-tree': true,
+  budget: true,
+  'no-nodes': true,
+  'capture-failed': true,
+  'presentation-failed': true,
+  deferred: true,
+  'requested-backend': true,
+};
+
+function isDeclared<Key extends string, Value>(
+  vocabulary: Record<Key, Value>,
+  value: unknown,
+): value is Key {
+  return typeof value === 'string' && Object.hasOwn(vocabulary, value);
+}
 
 export function readSnapshotQualityVerdict(value: unknown): SnapshotQualityVerdict | undefined {
   if (!value || typeof value !== 'object') return undefined;
@@ -27,31 +38,19 @@ export function readSnapshotQualityVerdict(value: unknown): SnapshotQualityVerdi
   // verdict this version understands, so it falls through as verdict-absent and the legacy
   // node-shape detectors run instead of being silently suppressed by a malformed payload.
   if (
-    typeof raw.state !== 'string' ||
-    !SNAPSHOT_QUALITY_STATES.has(raw.state as SnapshotQualityVerdict['state'])
-  ) {
-    return undefined;
-  }
-  if (
-    typeof raw.backend !== 'string' ||
-    !SNAPSHOT_QUALITY_BACKENDS.has(raw.backend as SnapshotQualityVerdict['backend'])
+    !isDeclared(DECLARED_STATES, raw.state) ||
+    !isDeclared(SNAPSHOT_QUALITY_BACKEND_CAPABILITIES, raw.backend)
   ) {
     return undefined;
   }
   const timing = readSnapshotQualityTiming(raw.timing);
   return {
-    state: raw.state as SnapshotQualityVerdict['state'],
-    backend: raw.backend as SnapshotQualityVerdict['backend'],
+    state: raw.state,
+    backend: raw.backend,
     reason: typeof raw.reason === 'string' ? raw.reason : undefined,
     // An unknown reasonCode is dropped, not rejected: a forward-version runner that adds one
     // still yields a usable verdict (only the budget-specific wording is keyed off it).
-    reasonCode:
-      typeof raw.reasonCode === 'string' &&
-      SNAPSHOT_QUALITY_REASON_CODES.has(
-        raw.reasonCode as NonNullable<SnapshotQualityVerdict['reasonCode']>,
-      )
-        ? (raw.reasonCode as SnapshotQualityVerdict['reasonCode'])
-        : undefined,
+    reasonCode: isDeclared(DECLARED_REASON_CODES, raw.reasonCode) ? raw.reasonCode : undefined,
     customActions: readCustomActionCoverage(raw.customActions),
     effectiveDepth: typeof raw.effectiveDepth === 'number' ? raw.effectiveDepth : undefined,
     collapsedLeafIndexes: Array.isArray(raw.collapsedLeafIndexes)
diff --git a/packages/contracts/src/snapshot-capture-annotations.test.ts b/packages/contracts/src/snapshot-capture-annotations.test.ts
index 2deeb0f761..0a9dff237e 100644
--- a/packages/contracts/src/snapshot-capture-annotations.test.ts
+++ b/packages/contracts/src/snapshot-capture-annotations.test.ts
@@ -1,5 +1,6 @@
 import assert from 'node:assert/strict';
 import { test } from 'vitest';
+import { SNAPSHOT_QUALITY_STATES } from '@agent-device/kernel/snapshot';
 import { readResponseWarnings } from '@agent-device/kernel/success-text';
 import { readSerializedSnapshotCaptureAnnotations } from './snapshot-capture-annotations.ts';
 
@@ -29,3 +30,60 @@ test('absent or non-array warnings stay absent on the serialized annotations', (
     undefined,
   );
 });
+
+test('every wire verdict state survives the serialized annotations', () => {
+  for (const state of SNAPSHOT_QUALITY_STATES) {
+    const verdict = {
+      state,
+      backend: 'private-ax',
+      reason: 'tree capture timed out',
+      reasonCode: 'budget',
+      effectiveDepth: 56,
+      collapsedLeafIndexes: [3],
+      customActions: { read: 12, candidates: 19, truncated: 1, blocked: false },
+      timing: { acquisitionMs: 12.5, presentationMs: 34.75 },
+    };
+    assert.deepEqual(
+      readSerializedSnapshotCaptureAnnotations({ snapshotQuality: verdict }).snapshotQuality,
+      verdict,
+    );
+  }
+});
+
+/**
+ * This reader runs on the daemon's serialized response, and it used to project any string into the
+ * verdict type. A state the declared vocabulary does not name now reads as verdict-absent, which is
+ * what lets the shape-based fallback stay in charge instead of a disclosure for nothing.
+ */
+test('a state outside the declared vocabulary drops the serialized verdict', () => {
+  for (const state of [
+    'heathy',
+    'healthy ',
+    'Sparse',
+    'degraded',
+    'constructor',
+    '',
+    42,
+    null,
+    undefined,
+  ]) {
+    const annotations = readSerializedSnapshotCaptureAnnotations({
+      snapshotQuality: { state, backend: 'tree' },
+    });
+    assert.equal(annotations.snapshotQuality, undefined, JSON.stringify(state));
+  }
+});
+
+/**
+ * `backend` names the recovery strategy in the user-facing warning line, so it goes through the
+ * declared strategies too: a strategy this version cannot name is not a verdict it can present. The
+ * optional fields are forwarded as published (see the reader); normalizing them is capture-kit.
+ */
+test('an undeclared backend drops the serialized verdict', () => {
+  for (const backend of ['uiautomator', 'tree ', 'Tree', 'constructor', '', 42, null, undefined]) {
+    const annotations = readSerializedSnapshotCaptureAnnotations({
+      snapshotQuality: { state: 'sparse', backend },
+    });
+    assert.equal(annotations.snapshotQuality, undefined, JSON.stringify(backend));
+  }
+});
diff --git a/packages/contracts/src/snapshot-capture-annotations.ts b/packages/contracts/src/snapshot-capture-annotations.ts
index da90cae94f..7ad86290cd 100644
--- a/packages/contracts/src/snapshot-capture-annotations.ts
+++ b/packages/contracts/src/snapshot-capture-annotations.ts
@@ -1,6 +1,28 @@
-import type { IosTargetActivation, SnapshotQualityVerdict } from '@agent-device/kernel/snapshot';
+import type {
+  IosTargetActivation,
+  SnapshotCaptureBackend,
+  SnapshotQualityState,
+  SnapshotQualityVerdict,
+} from '@agent-device/kernel/snapshot';
 import type { AndroidSnapshotBackendMetadata } from './snapshot-types.ts';
 
+/**
+ * The verdict names this host has to speak, each keyed against its kernel union so a name added
+ * there without a key here is a compile error. They cannot be one shared kernel predicate: the
+ * eager-closure gate keeps `kernel/snapshot.ts` out of `facades/capture.ts` (#2872).
+ */
+const DECLARED_STATES: Record<SnapshotQualityState, true> = {
+  healthy: true,
+  recovered: true,
+  sparse: true,
+};
+const DECLARED_BACKENDS: Record<SnapshotCaptureBackend, true> = {
+  tree: true,
+  queries: true,
+  'private-ax': true,
+  'android-helper': true,
+};
+
 export type SnapshotCaptureAnalysis = {
   rawNodeCount: number;
   maxDepth: number;
@@ -33,7 +55,7 @@ export type PublicSnapshotCaptureAnnotations = Pick<
 export function snapshotCaptureAnnotationsFrom(
   source: Partial<Omit<SnapshotCaptureAnnotations, 'quality'>> & { quality?: unknown },
 ): SnapshotCaptureAnnotations {
-  const quality = readSnapshotQualityVerdict(source.quality);
+  const quality = readPublishedSnapshotQualityVerdict(source.quality);
   return {
     ...(source.analysis ? { analysis: source.analysis } : {}),
     ...(source.androidSnapshot ? { androidSnapshot: source.androidSnapshot } : {}),
@@ -67,7 +89,7 @@ export function readSerializedSnapshotCaptureAnnotations(
   const warnings = Array.isArray(data.warnings)
     ? data.warnings.filter((entry): entry is string => typeof entry === 'string')
     : undefined;
-  const quality = readSnapshotQualityVerdict(data.snapshotQuality);
+  const quality = readPublishedSnapshotQualityVerdict(data.snapshotQuality);
   const targetActivation = readTargetActivation(data.targetActivation);
   return publicSnapshotCaptureAnnotations({
     ...(androidSnapshot
@@ -88,12 +110,26 @@ function readTargetActivation(value: unknown): IosTargetActivation | undefined {
     : undefined;
 }
 
-function readSnapshotQualityVerdict(value: unknown): SnapshotQualityVerdict | undefined {
+/**
+ * Re-read of a fact this module published, in the shape `readTargetActivation` above uses: the two
+ * names that decide presentation are checked, the rest is forwarded as published. capture-kit's
+ * `readSnapshotQualityVerdict` normalizes an untrusted runner payload field by field; the two
+ * readings are pinned to each other in `snapshot-quality-verdict.test.ts`.
+ */
+function readPublishedSnapshotQualityVerdict(value: unknown): SnapshotQualityVerdict | undefined {
   if (!value || typeof value !== 'object') return undefined;
   const raw = value as Record<string, unknown>;
-  return typeof raw.state === 'string' && typeof raw.backend === 'string'
-    ? (raw as SnapshotQualityVerdict)
-    : undefined;
+  if (!isDeclared(DECLARED_STATES, raw.state) || !isDeclared(DECLARED_BACKENDS, raw.backend)) {
+    return undefined;
+  }
+  return raw as SnapshotQualityVerdict;
+}
+
+function isDeclared<Key extends string, Value>(
+  vocabulary: Record<Key, Value>,
+  value: unknown,
+): value is Key {
+  return typeof value === 'string' && Object.hasOwn(vocabulary, value);
 }
 
 function readObject(value: unknown): Record<string, unknown> | undefined {
diff --git a/packages/kernel/src/snapshot-quality-states.test.ts b/packages/kernel/src/snapshot-quality-states.test.ts
new file mode 100644
index 0000000000..45fdbb4e2a
--- /dev/null
+++ b/packages/kernel/src/snapshot-quality-states.test.ts
@@ -0,0 +1,38 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { test } from 'vitest';
+import { SNAPSHOT_QUALITY_STATES, type SnapshotQualityState } from './snapshot.ts';
+
+const SNAPSHOT_QUALITY_STATES_FIXTURE_PATH = path.resolve(
+  import.meta.dirname,
+  '..',
+  '..',
+  '..',
+  'contracts',
+  'fixtures',
+  'ios-snapshot-quality-states.json',
+);
+
+function readSnapshotQualityStatesFixture(): string[] {
+  return JSON.parse(fs.readFileSync(SNAPSHOT_QUALITY_STATES_FIXTURE_PATH, 'utf8')) as string[];
+}
+
+/**
+ * The tuple's own claim, stated on `SNAPSHOT_QUALITY_STATES`: the fixture is its wire vocabulary,
+ * and the runner's `SnapshotQualityState.allCases` is pinned to the same file by a unit test. As a
+ * set: the names are the contract, and a reordering breaks no verdict anywhere.
+ */
+test('the declared verdict states are the shared wire vocabulary', () => {
+  assert.deepEqual(
+    new Set(readSnapshotQualityStatesFixture()),
+    new Set(SNAPSHOT_QUALITY_STATES),
+    'update the fixture and the Swift enum together with the tuple',
+  );
+});
+
+test('the verdict state type admits exactly the declared states', () => {
+  // @ts-expect-error a state nobody declared cannot enter the verdict type
+  const undeclared: SnapshotQualityState = 'degraded';
+  void undeclared;
+});
diff --git a/packages/kernel/src/snapshot.ts b/packages/kernel/src/snapshot.ts
index b6b817433d..a6a108d9c9 100644
--- a/packages/kernel/src/snapshot.ts
+++ b/packages/kernel/src/snapshot.ts
@@ -3,8 +3,9 @@
  * The daemon renders it; it never re-derives degradation from node shapes.
  *
  * Defined here (the foundational snapshot type module) rather than in
- * snapshot-quality/verdict.ts so SnapshotNode can reference it without a cyclic import;
- * snapshot-quality/verdict.ts owns the validation logic.
+ * capture-kit's snapshot-quality-verdict.ts so SnapshotNode can reference it without a cyclic
+ * import. Ownership splits three ways: this module owns the vocabularies below, capture-kit parses
+ * an untrusted runner payload into them, and contracts re-hydrates a verdict this repo published.
  */
 /**
  * Which capture STRATEGY produced a snapshot, within one platform's plan —
@@ -23,8 +24,21 @@ export type SnapshotQualityTiming = {
   presentationMs: number;
 };
 
+/**
+ * The verdict states a capture plan may stamp. This tuple is the ONE declaration of that
+ * vocabulary, and `SnapshotQualityVerdict['state']` is its projection; readers hold exhaustive maps
+ * over the union instead of importing this module, because the eager-closure gate freezes their
+ * loading shape (#2872). This tuple and the Apple runner's `SnapshotQualityState.allCases` are each
+ * pinned as a set to `contracts/fixtures/ios-snapshot-quality-states.json`, so a state one side
+ * renames, adds, or deletes without the other goes red there instead of arriving as a verdict the
+ * host cannot name — which reads as verdict-absent and drops the disclosure with it.
+ */
+export const SNAPSHOT_QUALITY_STATES = ['healthy', 'recovered', 'sparse'] as const;
+
+export type SnapshotQualityState = (typeof SNAPSHOT_QUALITY_STATES)[number];
+
 export type SnapshotQualityVerdict = {
-  state: 'healthy' | 'recovered' | 'sparse';
+  state: SnapshotQualityState;
   backend: SnapshotCaptureBackend;
   reason?: string;
   // 'deferred' = the penalty circuit breaker pre-selected a non-XCTest backend; nothing new

From fa1082dd1497e9a640bac11f07e58f8486c6e150 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 24 Sep 2026 19:42:38 +0200
Subject: [PATCH 114/132] refactor(macos): derive macOS surface routing from
 one owner table (#2886)

* test(platform-apple): rename the macOS surface interactor test

* fix(macos): derive surface routing and crop classification from one owner

Add a SessionSurface-keyed MACOS_SURFACE_BACKENDS table in contracts with
macOsSurfaceBackend and a table-derived MacOsHelperSurface brand. The
platform-apple snapshot, screenshot, readText, press, runtime capture and
native find sites, and the daemon crop classifier, now read it.

The crop classifier now reports frontmost-app as macos-helper (the helper
captures it) and a surface-less macOS session as macos-app-window (every
route serves it through the runner). Helper entry points require an
owner-routed surface.

Fixes #2880

* test(macos): assert the surface loader's refusal message, not only its class
---
 packages/contracts/src/facades/session.ts     |  13 +-
 .../contracts/src/session-surface.test.ts     |  23 +++
 packages/contracts/src/session-surface.ts     |  32 ++++
 .../interactor-macos-surface.test.ts          | 181 ++++++++++++++++++
 .../screenshot-macos-surface.test.ts          |  92 ---------
 packages/platform-apple/src/interactions.ts   |  11 +-
 packages/platform-apple/src/interactor.ts     |  54 ++----
 .../src/os/macos/helper.test.ts               |  38 +++-
 .../platform-apple/src/os/macos/helper.ts     |  14 +-
 .../src/os/macos/surface-snapshot.ts          |   8 +-
 .../platform-apple/src/runtime-snapshot.ts    |  16 +-
 packages/platform-apple/src/runtime.test.ts   |  50 +++--
 .../__tests__/screenshot-crop-target.test.ts  |  26 ++-
 src/daemon/screenshot-crop-target.ts          |   4 +-
 src/platform-runtime-operation-host.test.ts   |  38 +++-
 src/platform-runtime-operation-host.ts        |   7 +-
 16 files changed, 428 insertions(+), 179 deletions(-)
 create mode 100644 packages/contracts/src/session-surface.test.ts
 create mode 100644 packages/platform-apple/src/__tests__/interactor-macos-surface.test.ts
 delete mode 100644 packages/platform-apple/src/__tests__/screenshot-macos-surface.test.ts

diff --git a/packages/contracts/src/facades/session.ts b/packages/contracts/src/facades/session.ts
index 6750c38f76..264075cdc0 100644
--- a/packages/contracts/src/facades/session.ts
+++ b/packages/contracts/src/facades/session.ts
@@ -1,4 +1,13 @@
 export type { SessionAction } from '../session-action.ts';
 export type { SessionScope } from '../session-scope.ts';
-export { SESSION_SURFACES, parseSessionSurface } from '../session-surface.ts';
-export type { SessionSurface } from '../session-surface.ts';
+export {
+  SESSION_SURFACES,
+  macOsHelperSurface,
+  macOsSurfaceBackend,
+  parseSessionSurface,
+} from '../session-surface.ts';
+export type {
+  MacOsHelperSurface,
+  MacOsSurfaceBackend,
+  SessionSurface,
+} from '../session-surface.ts';
diff --git a/packages/contracts/src/session-surface.test.ts b/packages/contracts/src/session-surface.test.ts
new file mode 100644
index 0000000000..eb42f1cf9e
--- /dev/null
+++ b/packages/contracts/src/session-surface.test.ts
@@ -0,0 +1,23 @@
+import { expect, test } from 'vitest';
+import {
+  SESSION_SURFACES,
+  macOsHelperSurface,
+  macOsSurfaceBackend,
+  type MacOsSurfaceBackend,
+  type SessionSurface,
+} from './session-surface.ts';
+
+const EXPECTED_BACKENDS: Record<SessionSurface, MacOsSurfaceBackend> = {
+  app: 'xctest',
+  'frontmost-app': 'macos-helper',
+  desktop: 'macos-helper',
+  menubar: 'macos-helper',
+};
+
+test.each([
+  ...SESSION_SURFACES.map((surface) => [surface, EXPECTED_BACKENDS[surface]] as const),
+  [undefined, 'xctest'] as const,
+])('the macOS %s surface is served by %s', (surface, backend) => {
+  expect(macOsSurfaceBackend(surface)).toBe(backend);
+  expect(macOsHelperSurface(surface)).toBe(backend === 'macos-helper' ? surface : undefined);
+});
diff --git a/packages/contracts/src/session-surface.ts b/packages/contracts/src/session-surface.ts
index d5728edb62..ab3ddcb9b5 100644
--- a/packages/contracts/src/session-surface.ts
+++ b/packages/contracts/src/session-surface.ts
@@ -1,3 +1,4 @@
+import type { SnapshotBackend } from '@agent-device/kernel/snapshot';
 import { defineStringEnum } from './string-enum.ts';
 
 export const SESSION_SURFACES = ['app', 'frontmost-app', 'desktop', 'menubar'] as const;
@@ -10,3 +11,34 @@ const SESSION_SURFACE_ENUM = defineStringEnum(SESSION_SURFACES, {
 export function parseSessionSurface(value: string | undefined): SessionSurface {
   return SESSION_SURFACE_ENUM.parse(value);
 }
+
+/** The backend that serves every operation on a macOS surface. */
+export type MacOsSurfaceBackend = Extract<SnapshotBackend, 'xctest' | 'macos-helper'>;
+
+const MACOS_SURFACE_BACKENDS = {
+  app: 'xctest',
+  'frontmost-app': 'macos-helper',
+  desktop: 'macos-helper',
+  menubar: 'macos-helper',
+} as const satisfies Record<SessionSurface, MacOsSurfaceBackend>;
+
+/** An absent surface is an app session, the reading every route already gives it. */
+export function macOsSurfaceBackend(surface: SessionSurface | undefined): MacOsSurfaceBackend {
+  return MACOS_SURFACE_BACKENDS[surface ?? 'app'];
+}
+
+type HelperRoutedSurface = {
+  [S in SessionSurface]: (typeof MACOS_SURFACE_BACKENDS)[S] extends 'macos-helper' ? S : never;
+}[SessionSurface];
+
+declare const helperSurface: unique symbol;
+/** A surface the owner routed to the macOS helper; only `macOsHelperSurface` produces one. */
+export type MacOsHelperSurface = HelperRoutedSurface & { readonly [helperSurface]: true };
+
+export function macOsHelperSurface(
+  surface: SessionSurface | undefined,
+): MacOsHelperSurface | undefined {
+  return surface !== undefined && macOsSurfaceBackend(surface) === 'macos-helper'
+    ? (surface as MacOsHelperSurface)
+    : undefined;
+}
diff --git a/packages/platform-apple/src/__tests__/interactor-macos-surface.test.ts b/packages/platform-apple/src/__tests__/interactor-macos-surface.test.ts
new file mode 100644
index 0000000000..b0f5dc97b8
--- /dev/null
+++ b/packages/platform-apple/src/__tests__/interactor-macos-surface.test.ts
@@ -0,0 +1,181 @@
+import { beforeEach, expect, test, vi } from 'vitest';
+import type { DeviceInfo } from '@agent-device/kernel/device';
+import { SCREENSHOT_FULLSCREEN_REASONS } from '@agent-device/contracts/capture';
+import type { PressPointOptions } from '@agent-device/contracts/interactor-types';
+import {
+  SESSION_SURFACES,
+  type MacOsSurfaceBackend,
+  type SessionSurface,
+} from '@agent-device/contracts/session';
+
+vi.mock('../os/macos/helper.ts', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../os/macos/helper.ts')>();
+  return {
+    ...actual,
+    runMacOsScreenshotAction: vi.fn(async (outPath: string) => ({ path: outPath })),
+    runMacOsSnapshotAction: vi.fn(async (surface: SessionSurface) => ({
+      surface,
+      nodes: [],
+      truncated: false,
+      backend: 'macos-helper' as const,
+    })),
+    runMacOsReadTextAction: vi.fn(async () => ({ text: 'helper' })),
+    runMacOsPressAction: vi.fn(async (x: number, y: number) => ({ x, y })),
+  };
+});
+
+vi.mock('../core/screenshot.ts', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../core/screenshot.ts')>();
+  return {
+    ...actual,
+    captureScreenshotViaRunner: vi.fn(),
+    screenshotIos: vi.fn(),
+  };
+});
+
+vi.mock('../core/runner-client.ts', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../core/runner-client.ts')>();
+  return {
+    ...actual,
+    runAppleRunnerCommand: vi.fn(async () => ({})),
+  };
+});
+
+import { createAppleInteractor } from '../interactor.ts';
+import {
+  runMacOsPressAction,
+  runMacOsReadTextAction,
+  runMacOsScreenshotAction,
+  runMacOsSnapshotAction,
+} from '../os/macos/helper.ts';
+import { captureScreenshotViaRunner, screenshotIos } from '../core/screenshot.ts';
+import { runAppleRunnerCommand } from '../core/runner-client.ts';
+
+const macOsDevice: DeviceInfo = {
+  platform: 'apple',
+  appleOs: 'macos',
+  id: 'host-mac',
+  name: 'Host Mac',
+  kind: 'device',
+  target: 'desktop',
+  booted: true,
+};
+
+const MACOS_SURFACE_BACKENDS: Record<SessionSurface, MacOsSurfaceBackend> = {
+  app: 'xctest',
+  'frontmost-app': 'macos-helper',
+  desktop: 'macos-helper',
+  menubar: 'macos-helper',
+};
+
+const SURFACE_ROWS = [
+  ...SESSION_SURFACES.map((surface) => [surface, MACOS_SURFACE_BACKENDS[surface]] as const),
+  [undefined, 'xctest'] as const,
+];
+
+const HELPER_ROWS = SESSION_SURFACES.filter(
+  (surface) => MACOS_SURFACE_BACKENDS[surface] === 'macos-helper',
+);
+
+const PRIMARY_PRESS: Omit<PressPointOptions, 'surface'> = {
+  button: 'primary',
+  count: 1,
+  intervalMs: 0,
+  holdMs: 0,
+  jitterPx: 0,
+  doubleTap: false,
+};
+
+const helperEntryPoints = [
+  runMacOsScreenshotAction,
+  runMacOsSnapshotAction,
+  runMacOsReadTextAction,
+  runMacOsPressAction,
+];
+const runnerEntryPoints = [runAppleRunnerCommand, screenshotIos, captureScreenshotViaRunner];
+
+function clearEntryPoints(): void {
+  for (const entry of [...helperEntryPoints, ...runnerEntryPoints]) vi.mocked(entry).mockClear();
+}
+
+beforeEach(clearEntryPoints);
+
+function reachedBackend(): MacOsSurfaceBackend {
+  const helper = helperEntryPoints.some((entry) => vi.mocked(entry).mock.calls.length > 0);
+  const runner = runnerEntryPoints.some((entry) => vi.mocked(entry).mock.calls.length > 0);
+  expect(helper !== runner).toBe(true);
+  return helper ? 'macos-helper' : 'xctest';
+}
+
+test.each(SURFACE_ROWS)(
+  'every macOS operation on the %s surface reaches the %s backend',
+  async (surface, backend) => {
+    const interactor = createAppleInteractor(macOsDevice, {});
+    const operations: Record<string, () => Promise<unknown>> = {
+      screenshot: async () => await interactor.screenshot('/tmp/out.png', { surface }),
+      snapshot: async () => await interactor.snapshot({ surface }),
+      readTextAtPoint: async () => await interactor.readTextAtPoint?.({ x: 1, y: 2 }, { surface }),
+      pressPoint: async () =>
+        await interactor.pressPoint?.({ x: 1, y: 2 }, { ...PRIMARY_PRESS, surface }),
+    };
+    const reached: Record<string, MacOsSurfaceBackend> = {};
+    for (const [name, run] of Object.entries(operations)) {
+      clearEntryPoints();
+      await run();
+      reached[name] = reachedBackend();
+    }
+    expect(reached).toEqual({
+      screenshot: backend,
+      snapshot: backend,
+      readTextAtPoint: backend,
+      pressPoint: backend,
+    });
+  },
+);
+
+test.each(HELPER_ROWS)(
+  'refuses an explicit --fullscreen on the macOS %s surface before any capture',
+  async (surface) => {
+    const interactor = createAppleInteractor(macOsDevice, {});
+
+    await expect(
+      interactor.screenshot('/tmp/out.png', { surface, fullscreen: true }),
+    ).rejects.toMatchObject({
+      code: 'INVALID_ARGS',
+      details: expect.objectContaining({
+        reason: SCREENSHOT_FULLSCREEN_REASONS.macOsHelperSurfaceFixedFrame,
+        surface,
+      }),
+    });
+
+    expect(runMacOsScreenshotAction).not.toHaveBeenCalled();
+  },
+);
+
+test.each(HELPER_ROWS)(
+  'captures the %s surface through the helper when --fullscreen is not requested',
+  async (surface) => {
+    const interactor = createAppleInteractor(macOsDevice, {});
+
+    await interactor.screenshot('/tmp/out.png', { surface });
+
+    expect(runMacOsScreenshotAction).toHaveBeenCalledOnce();
+    const [, options] = vi.mocked(runMacOsScreenshotAction).mock.calls[0]!;
+    expect(options).toEqual({ surface });
+    expect(Object.hasOwn(options ?? {}, 'fullscreen')).toBe(false);
+  },
+);
+
+test('keeps a macOS app session on the runner path with --fullscreen unchanged', async () => {
+  const interactor = createAppleInteractor(macOsDevice, {});
+
+  await interactor.screenshot('/tmp/out.png', { surface: 'app', fullscreen: true });
+
+  expect(runMacOsScreenshotAction).not.toHaveBeenCalled();
+  expect(screenshotIos).toHaveBeenCalledOnce();
+  expect(screenshotIos).toHaveBeenCalledWith(
+    macOsDevice,
+    '/tmp/out.png',
+    expect.objectContaining({ fullscreen: true }),
+  );
+});
diff --git a/packages/platform-apple/src/__tests__/screenshot-macos-surface.test.ts b/packages/platform-apple/src/__tests__/screenshot-macos-surface.test.ts
deleted file mode 100644
index 3d41e5d0d1..0000000000
--- a/packages/platform-apple/src/__tests__/screenshot-macos-surface.test.ts
+++ /dev/null
@@ -1,92 +0,0 @@
-import { beforeEach, expect, test, vi } from 'vitest';
-import type { DeviceInfo } from '@agent-device/kernel/device';
-import { SCREENSHOT_FULLSCREEN_REASONS } from '@agent-device/contracts/capture';
-import { SESSION_SURFACES } from '@agent-device/contracts/session';
-
-vi.mock('../os/macos/helper.ts', async (importOriginal) => {
-  const actual = await importOriginal<typeof import('../os/macos/helper.ts')>();
-  return {
-    ...actual,
-    runMacOsScreenshotAction: vi.fn(async (outPath: string) => ({ path: outPath })),
-  };
-});
-
-vi.mock('../core/screenshot.ts', async (importOriginal) => {
-  const actual = await importOriginal<typeof import('../core/screenshot.ts')>();
-  return {
-    ...actual,
-    captureScreenshotViaRunner: vi.fn(),
-    screenshotIos: vi.fn(),
-  };
-});
-
-import { createAppleInteractor } from '../interactor.ts';
-import { runMacOsScreenshotAction } from '../os/macos/helper.ts';
-import { screenshotIos } from '../core/screenshot.ts';
-
-const macOsDevice: DeviceInfo = {
-  platform: 'apple',
-  appleOs: 'macos',
-  id: 'host-mac',
-  name: 'Host Mac',
-  kind: 'device',
-  target: 'desktop',
-  booted: true,
-};
-
-beforeEach(() => {
-  vi.mocked(runMacOsScreenshotAction).mockClear();
-  vi.mocked(screenshotIos).mockClear();
-});
-
-// The helper-routed domain, derived from the same condition `usesMacOsSurfaceScreenshot` applies
-// (every session surface except `app`) rather than a hand-picked list — so adding a surface to
-// `SESSION_SURFACES` extends this coverage automatically instead of silently falling outside it.
-const helperRoutedSurfaces = SESSION_SURFACES.filter((surface) => surface !== 'app');
-
-test.each(helperRoutedSurfaces)(
-  'refuses an explicit --fullscreen on the macOS %s surface before any capture',
-  async (surface) => {
-    const interactor = createAppleInteractor(macOsDevice, {});
-
-    await expect(
-      interactor.screenshot('/tmp/out.png', { surface, fullscreen: true }),
-    ).rejects.toMatchObject({
-      code: 'INVALID_ARGS',
-      details: expect.objectContaining({
-        reason: SCREENSHOT_FULLSCREEN_REASONS.macOsHelperSurfaceFixedFrame,
-        surface,
-      }),
-    });
-
-    expect(runMacOsScreenshotAction).not.toHaveBeenCalled();
-  },
-);
-
-test.each(helperRoutedSurfaces)(
-  'captures the %s surface through the helper when --fullscreen is not requested',
-  async (surface) => {
-    const interactor = createAppleInteractor(macOsDevice, {});
-
-    await interactor.screenshot('/tmp/out.png', { surface });
-
-    expect(runMacOsScreenshotAction).toHaveBeenCalledOnce();
-    const [, options] = vi.mocked(runMacOsScreenshotAction).mock.calls[0]!;
-    expect(options).toEqual({ surface });
-    expect(Object.hasOwn(options ?? {}, 'fullscreen')).toBe(false);
-  },
-);
-
-test('keeps a macOS app session on the runner path with --fullscreen unchanged', async () => {
-  const interactor = createAppleInteractor(macOsDevice, {});
-
-  await interactor.screenshot('/tmp/out.png', { surface: 'app', fullscreen: true });
-
-  expect(runMacOsScreenshotAction).not.toHaveBeenCalled();
-  expect(screenshotIos).toHaveBeenCalledOnce();
-  expect(screenshotIos).toHaveBeenCalledWith(
-    macOsDevice,
-    '/tmp/out.png',
-    expect.objectContaining({ fullscreen: true }),
-  );
-});
diff --git a/packages/platform-apple/src/interactions.ts b/packages/platform-apple/src/interactions.ts
index e6048040a0..a770e19f3d 100644
--- a/packages/platform-apple/src/interactions.ts
+++ b/packages/platform-apple/src/interactions.ts
@@ -10,6 +10,7 @@ import {
   type TextEntryRoute,
   type TypeTextBackendResult,
 } from '@agent-device/contracts/interactor-types';
+import { macOsHelperSurface, type MacOsHelperSurface } from '@agent-device/contracts/session';
 import {
   SCROLL_DURATION_MAX_MS,
   normalizeScrollDurationMs,
@@ -194,8 +195,9 @@ async function runApplePressPoint(
   point: { x: number; y: number },
   options: PressPointOptions,
 ): Promise<Record<string, unknown>> {
-  if (isMacOs(device) && options.surface && options.surface !== 'app') {
-    return await runMacOsSurfacePress(context, point, options);
+  const helper = isMacOs(device) ? macOsHelperSurface(options.surface) : undefined;
+  if (helper) {
+    return await runMacOsSurfacePress(context, point, options, helper);
   }
   if (options.button !== 'primary') {
     return await runAppleAlternateClick(device, context, runnerOpts, point, options.button);
@@ -216,11 +218,12 @@ async function runMacOsSurfacePress(
   context: RunnerContext,
   point: { x: number; y: number },
   options: PressPointOptions,
+  surface: MacOsHelperSurface,
 ): Promise<Record<string, unknown>> {
   if (options.button !== 'primary') {
     throw new AppError(
       'UNSUPPORTED_OPERATION',
-      `${options.button} click is not supported on macOS ${options.surface} sessions.`,
+      `${options.button} click is not supported on macOS ${surface} sessions.`,
     );
   }
   const { runMacOsPressAction } = await import('./os/macos/helper.ts');
@@ -228,7 +231,7 @@ async function runMacOsSurfacePress(
   // the same reading every other platform gives the two flags.
   const posted = await runMacOsPressAction(point.x, point.y, {
     bundleId: context.appBundleId,
-    surface: options.surface,
+    surface,
     holdMs: options.holdMs,
     clicks: options.count,
     doubleClick: options.doubleTap,
diff --git a/packages/platform-apple/src/interactor.ts b/packages/platform-apple/src/interactor.ts
index 945a32309f..0d960fea39 100644
--- a/packages/platform-apple/src/interactor.ts
+++ b/packages/platform-apple/src/interactor.ts
@@ -14,7 +14,7 @@ import {
 } from './runner/index.ts';
 import { toAppleTvRemoteButton } from '@agent-device/contracts/tv-remote';
 import { SCREENSHOT_FULLSCREEN_REASONS } from '@agent-device/contracts/capture';
-import type { SessionSurface } from '@agent-device/contracts/session';
+import { macOsHelperSurface, type MacOsHelperSurface } from '@agent-device/contracts/session';
 import { DEVICE_ROTATIONS, type DeviceRotation } from '@agent-device/contracts/device';
 import { normalizeSnapshotScope } from '@agent-device/contracts/snapshot';
 import { withDiagnosticTimer } from '@agent-device/host-kit/diagnostics';
@@ -68,12 +68,14 @@ export function createAppleInteractor(
     close: (app) => closeIosApp(device, app, runnerOpts),
     screenshot: (outPath, options) => runAppleScreenshot(device, outPath, options, runnerOpts),
     snapshot: async (options) => await captureAppleSnapshot(device, options, runnerOpts),
-    // The live text at a point: helper for macOS desktop/menubar surfaces, XCTest runner for
+    // The live text at a point: helper for a helper-routed macOS surface, XCTest runner for
     // every other Apple leaf including a macOS app session.
-    readTextAtPoint: async (point, options) =>
-      usesMacOsHelperSurface(device, options?.surface)
-        ? await readMacOsSurfaceTextAtPoint(point, options)
-        : await readRunnerTextAtPoint(device, point, options, runnerOpts),
+    readTextAtPoint: async (point, options) => {
+      const helper = isMacOs(device) ? macOsHelperSurface(options?.surface) : undefined;
+      return helper
+        ? await readMacOsSurfaceTextAtPoint(point, helper, options?.appBundleId)
+        : await readRunnerTextAtPoint(device, point, options, runnerOpts);
+    },
     // The XCTest runner's own text reading: it observes the live accessibility hierarchy
     // directly, so it answers without the cost — and without the pruning — of a tree capture.
     // Only a positive answer is authoritative; see `FindTextResult`.
@@ -209,8 +211,9 @@ async function captureAppleSnapshot(
   options: SnapshotOptions | undefined,
   runnerOpts: RunnerCallOptions,
 ) {
-  if (isMacOs(device) && options?.surface && options.surface !== 'app') {
-    return await captureMacOsSurfaceSnapshot(options, options.signal);
+  const helper = isMacOs(device) ? macOsHelperSurface(options?.surface) : undefined;
+  if (helper) {
+    return await captureMacOsSurfaceSnapshot({ ...options, surface: helper }, options?.signal);
   }
   return await captureAppleRunnerSnapshot(device, options, runnerOpts);
 }
@@ -386,20 +389,19 @@ async function runAppleScreenshot(
   options: ScreenshotOptions = {},
   runnerOpts: RunnerCallOptions,
 ): Promise<void> {
-  if (usesMacOsSurfaceScreenshot(device, options.surface)) {
+  const helper = isMacOs(device) ? macOsHelperSurface(options.surface) : undefined;
+  if (helper) {
     if (options.fullscreen) {
       throw new AppError(
         'INVALID_ARGS',
-        `screenshot --fullscreen is not accepted on the macOS ${options.surface} surface: it always captures the main display`,
+        `screenshot --fullscreen is not accepted on the macOS ${helper} surface: it always captures the main display`,
         {
           reason: SCREENSHOT_FULLSCREEN_REASONS.macOsHelperSurfaceFixedFrame,
-          surface: options.surface,
+          surface: helper,
         },
       );
     }
-    await runMacOsScreenshotAction(outPath, {
-      surface: options.surface,
-    });
+    await runMacOsScreenshotAction(outPath, { surface: helper });
     return;
   }
   if (options.captureBackend === 'runner') {
@@ -424,31 +426,15 @@ async function runAppleScreenshot(
   });
 }
 
-/**
- * Every surface this admits captures through the macOS helper's fixed main-display frame, so
- * `runAppleScreenshot` also keys its `--fullscreen` refusal directly off this predicate: whichever
- * surface routes here cannot vary its captured frame, helper-routed today or added later.
- */
-function usesMacOsSurfaceScreenshot(
-  device: DeviceInfo,
-  surface: ScreenshotOptions['surface'],
-): surface is Exclude<ScreenshotOptions['surface'], undefined | 'app'> {
-  return isMacOs(device) && surface !== undefined && surface !== 'app';
-}
-
-/** Only non-app macOS surfaces are helper-read; an app session is runner-read like any leaf. */
-function usesMacOsHelperSurface(device: DeviceInfo, surface: SessionSurface | undefined): boolean {
-  return isMacOs(device) && surface !== undefined && surface !== 'app';
-}
-
 async function readMacOsSurfaceTextAtPoint(
   point: Point,
-  options?: { appBundleId?: string; surface?: SessionSurface },
+  surface: MacOsHelperSurface,
+  appBundleId: string | undefined,
 ): Promise<string | undefined> {
   const { runMacOsReadTextAction } = await import('./os/macos/helper.ts');
   const result = await runMacOsReadTextAction(point.x, point.y, {
-    bundleId: options?.appBundleId,
-    surface: options?.surface,
+    bundleId: appBundleId,
+    surface,
   });
   return result.text;
 }
diff --git a/packages/platform-apple/src/os/macos/helper.test.ts b/packages/platform-apple/src/os/macos/helper.test.ts
index 483483d494..a6d129fbe6 100644
--- a/packages/platform-apple/src/os/macos/helper.test.ts
+++ b/packages/platform-apple/src/os/macos/helper.test.ts
@@ -1,13 +1,19 @@
 import assert from 'node:assert/strict';
 import { test } from 'vitest';
+import { macOsHelperSurface } from '@agent-device/contracts/session';
 import { createLocalAppleToolProvider, withAppleToolProvider } from '../../core/tool-provider.ts';
 import {
   macOsClickScheduleMs,
   runMacOsPressAction,
+  runMacOsReadTextAction,
   runMacOsScreenshotAction,
   runMacOsSnapshotAction,
 } from './helper.ts';
 
+const desktop = macOsHelperSurface('desktop')!;
+const menubar = macOsHelperSurface('menubar')!;
+const frontmostApp = macOsHelperSurface('frontmost-app')!;
+
 test('macOS helper snapshot passes cancellation to the helper process', async () => {
   const controller = new AbortController();
   let receivedSignal: AbortSignal | undefined;
@@ -34,7 +40,7 @@ test('macOS helper snapshot passes cancellation to the helper process', async ()
 
   await withAppleToolProvider(
     provider,
-    async () => await runMacOsSnapshotAction('desktop', { signal: controller.signal }),
+    async () => await runMacOsSnapshotAction(desktop, { signal: controller.signal }),
   );
 
   assert.equal(receivedSignal, controller.signal);
@@ -63,7 +69,7 @@ test('macOS helper press carries the hold, repeat count, and interval to the cli
     provider,
     async () =>
       await runMacOsPressAction(12, 34, {
-        surface: 'menubar',
+        surface: menubar,
         bundleId: 'com.example.Menu',
         holdMs: 800,
         clicks: 2,
@@ -104,7 +110,7 @@ test('macOS helper press carries an explicit zero interval instead of dropping i
 
   await withAppleToolProvider(
     provider,
-    async () => await runMacOsPressAction(7, 8, { surface: 'desktop', clicks: 2, intervalMs: 0 }),
+    async () => await runMacOsPressAction(7, 8, { surface: desktop, clicks: 2, intervalMs: 0 }),
   );
 
   assert.ok(receivedArgs.includes('--clicks'), receivedArgs.join(' '));
@@ -131,7 +137,7 @@ test('macOS helper press keeps repeats independent and names a double-click expl
   await withAppleToolProvider(
     provider,
     async () =>
-      await runMacOsPressAction(7, 8, { surface: 'frontmost-app', clicks: 3, doubleClick: true }),
+      await runMacOsPressAction(7, 8, { surface: frontmostApp, clicks: 3, doubleClick: true }),
   );
 
   // `--count 3 --double-tap` is three double-clicks: the count stays the press count and the
@@ -163,7 +169,7 @@ test('macOS helper press outlives its own click schedule and forwards cancellati
     provider,
     async () =>
       await runMacOsPressAction(1, 2, {
-        surface: 'desktop',
+        surface: desktop,
         holdMs: 10_000,
         clicks: 4,
         intervalMs: 120,
@@ -205,7 +211,7 @@ test('macOS helper press stays a single held click when nothing is repeated', as
 
   await withAppleToolProvider(
     provider,
-    async () => await runMacOsPressAction(5, 6, { surface: 'frontmost-app' }),
+    async () => await runMacOsPressAction(5, 6, { surface: frontmostApp }),
   );
 
   assert.equal(receivedArgs.includes('--clicks'), false);
@@ -226,8 +232,26 @@ test('macOS helper screenshot argv carries only --out and --surface', async () =
 
   await withAppleToolProvider(
     provider,
-    async () => await runMacOsScreenshotAction('/tmp/out.png', { surface: 'desktop' }),
+    async () => await runMacOsScreenshotAction('/tmp/out.png', { surface: desktop }),
   );
 
   assert.deepEqual(receivedArgs, ['screenshot', '--out', '/tmp/out.png', '--surface', 'desktop']);
 });
+
+test('helper entry points accept only an owner-routed surface', () => {
+  // Never invoked: each directive fails typecheck once its entry point widens back to an
+  // unbranded or optional surface.
+  const widenedCalls = async (out: string) => {
+    // @ts-expect-error a bare literal skips the routing owner
+    await runMacOsSnapshotAction('desktop');
+    // @ts-expect-error a bare literal skips the routing owner
+    await runMacOsScreenshotAction(out, { surface: 'menubar' });
+    // @ts-expect-error the surface is required
+    await runMacOsReadTextAction(1, 2, { bundleId: 'com.example' });
+    // @ts-expect-error the surface is required
+    await runMacOsPressAction(1, 2, {});
+    // @ts-expect-error the surface is required
+    await runMacOsScreenshotAction(out);
+  };
+  assert.equal(typeof widenedCalls, 'function');
+});
diff --git a/packages/platform-apple/src/os/macos/helper.ts b/packages/platform-apple/src/os/macos/helper.ts
index b807ab1589..599a51e82a 100644
--- a/packages/platform-apple/src/os/macos/helper.ts
+++ b/packages/platform-apple/src/os/macos/helper.ts
@@ -25,7 +25,7 @@ import {
   runCmdBackground,
   type ExecBackgroundResult,
 } from '@agent-device/host-kit/command';
-import type { SessionSurface } from '@agent-device/contracts/session';
+import type { MacOsHelperSurface, SessionSurface } from '@agent-device/contracts/session';
 import {
   hasScopedAppleToolProvider,
   resolveAppleToolProvider,
@@ -372,10 +372,10 @@ export async function runMacOsAlertAction(
 }
 
 export async function runMacOsSnapshotAction(
-  surface: Exclude<SessionSurface, 'app'>,
+  surface: MacOsHelperSurface,
   options: { bundleId?: string; signal?: AbortSignal } = {},
 ): Promise<{
-  surface: Exclude<SessionSurface, 'app'>;
+  surface: SessionSurface;
   nodes: MacOsSnapshotNode[];
   truncated: boolean;
   backend: 'macos-helper';
@@ -388,7 +388,7 @@ export async function runMacOsSnapshotAction(
 export async function runMacOsReadTextAction(
   x: number,
   y: number,
-  options: { bundleId?: string; surface?: SessionSurface } = {},
+  options: { surface: MacOsHelperSurface; bundleId?: string },
 ): Promise<{
   text: string;
 }> {
@@ -430,8 +430,8 @@ export async function runMacOsPressAction(
   x: number,
   y: number,
   options: {
+    surface: MacOsHelperSurface;
     bundleId?: string;
-    surface?: SessionSurface;
     holdMs?: number;
     /** Independent presses, each a single click; `--count` on every platform. */
     clicks?: number;
@@ -439,7 +439,7 @@ export async function runMacOsPressAction(
     doubleClick?: boolean;
     intervalMs?: number;
     signal?: AbortSignal;
-  } = {},
+  },
 ): Promise<{
   x: number;
   y: number;
@@ -473,7 +473,7 @@ export async function runMacOsPressAction(
 
 export async function runMacOsScreenshotAction(
   outPath: string,
-  options: { surface?: SessionSurface } = {},
+  options: { surface: MacOsHelperSurface },
 ): Promise<{
   path: string;
   surface?: SessionSurface;
diff --git a/packages/platform-apple/src/os/macos/surface-snapshot.ts b/packages/platform-apple/src/os/macos/surface-snapshot.ts
index 47d0899eb7..28df3a9693 100644
--- a/packages/platform-apple/src/os/macos/surface-snapshot.ts
+++ b/packages/platform-apple/src/os/macos/surface-snapshot.ts
@@ -1,16 +1,16 @@
 import type { CaptureSnapshotInput } from '@agent-device/contracts/snapshot-runtime';
+import type { MacOsHelperSurface } from '@agent-device/contracts/session';
 import { shapeDesktopSurfaceSnapshot } from '@agent-device/capture-kit/snapshot-desktop-projection';
 
-type SnapshotSurfaceOptions = NonNullable<CaptureSnapshotInput['options']>;
+type SnapshotSurfaceOptions = Omit<NonNullable<CaptureSnapshotInput['options']>, 'surface'> & {
+  surface: MacOsHelperSurface;
+};
 
 export async function captureMacOsSurfaceSnapshot(
   options: SnapshotSurfaceOptions,
   signal?: AbortSignal,
 ) {
   const surface = options.surface;
-  if (!surface || surface === 'app') {
-    throw new TypeError('Apple surface capture requires a non-app macOS surface');
-  }
   const { runMacOsSnapshotAction } = await import('./helper.ts');
   const result = await runMacOsSnapshotAction(surface, {
     bundleId: surface === 'menubar' ? options.appBundleId : undefined,
diff --git a/packages/platform-apple/src/runtime-snapshot.ts b/packages/platform-apple/src/runtime-snapshot.ts
index e394c48ab0..c3608e6b49 100644
--- a/packages/platform-apple/src/runtime-snapshot.ts
+++ b/packages/platform-apple/src/runtime-snapshot.ts
@@ -11,6 +11,7 @@ import type {
   PlatformRuntimeHost,
   PlatformRuntimeOperations,
 } from '@agent-device/contracts/platform-runtime-operations';
+import { macOsSurfaceBackend, type SessionSurface } from '@agent-device/contracts/session';
 import { isMacOs, type DeviceInfo } from '@agent-device/kernel/device';
 import { hasSimulatorBridge } from './snapshot-observability.ts';
 import type { AppleSnapshotRoute } from './snapshot-route.ts';
@@ -27,11 +28,7 @@ export function bindAppleSnapshotRuntime(
     resolveInteractor: host.localInteractors.resolve,
   });
   const captureSnapshot = async (input: CaptureSnapshotInput) => {
-    if (
-      isMacOs(request.device) &&
-      input.options?.surface !== undefined &&
-      input.options.surface !== 'app'
-    ) {
+    if (isMacOs(request.device) && macOsSurfaceBackend(input.options?.surface) === 'macos-helper') {
       return await host.snapshot.captureSurface(
         request.device,
         input.options,
@@ -66,7 +63,7 @@ type SnapshotRuntimeOperation = Pick<
  *
  * - No tracked app bundle id: the runner query is scoped to an application, so there is nothing
  *   to ask about.
- * - macOS on an explicit non-app surface: the runner reads the *application*, so a positive
+ * - macOS on a helper-routed surface: the runner reads the *application*, so a positive
  *   answer would describe the wrong surface. Reporting `false` sends the poll to the desktop
  *   surface capture, which is the reading that matches the request.
  *
@@ -106,15 +103,16 @@ async function admitAppleNativeFind(
   host: Pick<PlatformRuntimeHost, 'appleApplications'>,
   request: Readonly<{ device: DeviceInfo; signal: AbortSignal }>,
   input: Readonly<{
-    options?: Readonly<{ appBundleId?: string; surface?: string }>;
+    options?: Readonly<{ appBundleId?: string; surface?: SessionSurface }>;
     execution?: Readonly<{ requestId?: string }>;
     signal?: AbortSignal;
   }>,
 ): Promise<AdmittedAppleNativeFind | undefined> {
   const appBundleId = input.options?.appBundleId;
   if (appBundleId === undefined) return undefined;
-  const surface = input.options?.surface;
-  if (isMacOs(request.device) && surface !== undefined && surface !== 'app') return undefined;
+  if (isMacOs(request.device) && macOsSurfaceBackend(input.options?.surface) === 'macos-helper') {
+    return undefined;
+  }
   const signal = input.signal ? AbortSignal.any([request.signal, input.signal]) : request.signal;
   signal.throwIfAborted();
   if (!(await runnerCanAnswerNow(host, request.device, input.execution))) return undefined;
diff --git a/packages/platform-apple/src/runtime.test.ts b/packages/platform-apple/src/runtime.test.ts
index fcd1b6ed25..233190dda6 100644
--- a/packages/platform-apple/src/runtime.test.ts
+++ b/packages/platform-apple/src/runtime.test.ts
@@ -9,6 +9,11 @@ import { listIosApps } from './core/app-resolution.ts';
 import type { DeviceBinding, RuntimeFacts } from '@agent-device/contracts/platform-runtime';
 import type { PlatformRuntimeOperations } from '@agent-device/contracts/platform-runtime-operations';
 import type { SnapshotRuntimeHost } from '@agent-device/contracts/snapshot-runtime';
+import {
+  SESSION_SURFACES,
+  type MacOsSurfaceBackend,
+  type SessionSurface,
+} from '@agent-device/contracts/session';
 import { HOVER_UNAVAILABLE_HINT } from '@agent-device/contracts/touch-runtime';
 import type { AppleOS, DeviceInfo } from '@agent-device/kernel/device';
 import { createApplePlatformRuntime } from './runtime.ts';
@@ -396,9 +401,19 @@ function expectTvRemoteFact(
   }
 }
 
-test.each(['frontmost-app', 'desktop', 'menubar'] as const)(
-  'routes the macOS %s surface through the exact Apple surface host',
-  async (surface) => {
+const MACOS_SURFACE_BACKENDS: Record<SessionSurface, MacOsSurfaceBackend> = {
+  app: 'xctest',
+  'frontmost-app': 'macos-helper',
+  desktop: 'macos-helper',
+  menubar: 'macos-helper',
+};
+
+test.each([
+  ...SESSION_SURFACES.map((surface) => [surface, MACOS_SURFACE_BACKENDS[surface]] as const),
+  [undefined, 'xctest'] as const,
+])(
+  'the macOS %s surface captures and finds text through the %s backend',
+  async (surface, backend) => {
     const host = platformRuntimeHostFixture();
     const captureSurface = vi.fn(async () => ({
       backend: 'macos-helper' as const,
@@ -406,7 +421,14 @@ test.each(['frontmost-app', 'desktop', 'menubar'] as const)(
       nodes: [],
       truncated: false,
     }));
-    const resolve = vi.fn(async () => ({}) as never);
+    const snapshot = vi.fn(async () => ({
+      backend: 'xctest' as const,
+      producer: 'apple-runner' as const,
+      nodes: [],
+      truncated: false,
+    }));
+    const findText = vi.fn(async () => ({ found: true }));
+    const resolve = vi.fn(async () => ({ snapshot, findText }) as never);
     const binding = await createApplePlatformRuntime({
       ...host,
       localInteractors: { resolve },
@@ -420,18 +442,18 @@ test.each(['frontmost-app', 'desktop', 'menubar'] as const)(
         progress: { report: () => {} },
       },
     });
+    const options = { surface, appBundleId: 'com.example.app', depth: 3 };
 
-    await expect(
-      binding.operations.captureSnapshot?.({
-        options: { surface, appBundleId: 'com.example.app', depth: 3 },
-      }),
-    ).resolves.toMatchObject({ backend: 'macos-helper' });
-    expect(captureSurface).toHaveBeenCalledWith(
-      leaves.macos,
-      { surface, appBundleId: 'com.example.app', depth: 3 },
-      expect.any(AbortSignal),
+    await binding.operations.captureSnapshot?.({ options });
+    const found = await binding.operations.findText?.({ text: 'Settings', options });
+
+    const helperRouted = backend === 'macos-helper';
+    expect(captureSurface.mock.calls).toEqual(
+      helperRouted ? [[leaves.macos, options, expect.any(AbortSignal)]] : [],
     );
-    expect(resolve).not.toHaveBeenCalled();
+    expect(snapshot).toHaveBeenCalledTimes(helperRouted ? 0 : 1);
+    expect(findText).toHaveBeenCalledTimes(helperRouted ? 0 : 1);
+    expect(found).toEqual({ found: !helperRouted });
   },
 );
 
diff --git a/src/daemon/__tests__/screenshot-crop-target.test.ts b/src/daemon/__tests__/screenshot-crop-target.test.ts
index 7eb0fcc91b..0b9ef7f36f 100644
--- a/src/daemon/__tests__/screenshot-crop-target.test.ts
+++ b/src/daemon/__tests__/screenshot-crop-target.test.ts
@@ -9,7 +9,11 @@ import {
   WEB_DESKTOP_DEVICE,
 } from '../../__tests__/test-utils/device-fixtures.ts';
 import { SCREENSHOT_CROP_REASONS } from '@agent-device/contracts/capture';
-import type { SessionSurface } from '@agent-device/contracts/session';
+import {
+  SESSION_SURFACES,
+  type MacOsSurfaceBackend,
+  type SessionSurface,
+} from '@agent-device/contracts/session';
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import { expect, test } from 'vitest';
 import {
@@ -31,7 +35,7 @@ const CROP_TARGET_DEVICES: readonly CropTargetDevice[] = [
   { target: 'android-device', device: ANDROID_DEVICE, surface: undefined },
   { target: 'macos-app-window', device: MACOS_DEVICE, surface: 'app' },
   { target: 'ios-physical', device: IOS_DEVICE, surface: undefined },
-  { target: 'macos-helper', device: MACOS_DEVICE, surface: undefined },
+  { target: 'macos-helper', device: MACOS_DEVICE, surface: 'desktop' },
   { target: 'web', device: WEB_DESKTOP_DEVICE, surface: undefined },
   { target: 'linux', device: LINUX_DEVICE, surface: undefined },
   { target: 'tvos', device: TVOS_SIMULATOR, surface: undefined },
@@ -67,6 +71,24 @@ test('the classifier and the acceptance matrix agree one-to-one, and the accepte
   }
 });
 
+const MACOS_SURFACE_BACKENDS: Record<SessionSurface, MacOsSurfaceBackend> = {
+  app: 'xctest',
+  'frontmost-app': 'macos-helper',
+  desktop: 'macos-helper',
+  menubar: 'macos-helper',
+};
+const MACOS_CROP_TARGETS: Record<MacOsSurfaceBackend, CropTargetDevice['target']> = {
+  xctest: 'macos-app-window',
+  'macos-helper': 'macos-helper',
+};
+
+test.each([
+  ...SESSION_SURFACES.map((surface) => [surface, MACOS_SURFACE_BACKENDS[surface]] as const),
+  [undefined, 'xctest'] as const,
+])('a macOS %s session crops in the frame of the backend that captures it', (surface, backend) => {
+  expect(classifyScreenshotCropTarget(MACOS_DEVICE, surface)).toBe(MACOS_CROP_TARGETS[backend]);
+});
+
 test('an apple device with an unpopulated reserved OS is a typed refusal, not a guess', () => {
   const device: DeviceInfo = {
     platform: 'apple',
diff --git a/src/daemon/screenshot-crop-target.ts b/src/daemon/screenshot-crop-target.ts
index 066f68ca2d..8d71e342cf 100644
--- a/src/daemon/screenshot-crop-target.ts
+++ b/src/daemon/screenshot-crop-target.ts
@@ -2,7 +2,7 @@ import {
   SCREENSHOT_CROP_REASONS,
   type ScreenshotCropReason,
 } from '@agent-device/contracts/capture';
-import type { SessionSurface } from '@agent-device/contracts/session';
+import { macOsSurfaceBackend, type SessionSurface } from '@agent-device/contracts/session';
 import { resolveDeviceAppleOs, type DeviceInfo } from '@agent-device/kernel/device';
 import { AppError } from '@agent-device/kernel/errors';
 import { validateSelectorExpression } from '@agent-device/selectors';
@@ -99,7 +99,7 @@ function classifyAppleCropTarget(
 }
 
 function classifyMacOsCropTarget(surface: SessionSurface | undefined): CropTarget {
-  return surface === 'app' || surface === 'frontmost-app' ? 'macos-app-window' : 'macos-helper';
+  return macOsSurfaceBackend(surface) === 'macos-helper' ? 'macos-helper' : 'macos-app-window';
 }
 
 function cropRefusal(target: string, rejectionReason?: ScreenshotCropReason): AppError {
diff --git a/src/platform-runtime-operation-host.test.ts b/src/platform-runtime-operation-host.test.ts
index 07d0ed9deb..d8611ab95f 100644
--- a/src/platform-runtime-operation-host.test.ts
+++ b/src/platform-runtime-operation-host.test.ts
@@ -19,8 +19,21 @@ vi.mock('./platform-runtime-apple-tool-host.ts', () => ({
 vi.mock('./platform-runtime-toolchain-host.ts', () => ({
   createHostToolchainPreparer: () => capabilities.toolchains,
 }));
+vi.mock('@agent-device/platform-apple/macos', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('@agent-device/platform-apple/macos')>()),
+  captureMacOsSurfaceSnapshot: vi.fn(async () => ({
+    backend: 'macos-helper' as const,
+    producer: 'macos-helper' as const,
+    nodes: [],
+    truncated: false,
+  })),
+}));
 
-import { createPlatformRuntimeHost } from './platform-runtime-operation-host.ts';
+import { captureMacOsSurfaceSnapshot } from '@agent-device/platform-apple/macos';
+import {
+  createPlatformRuntimeHost,
+  loadMacOsSurfaceSnapshot,
+} from './platform-runtime-operation-host.ts';
 
 const snapshot = {
   captureSurface: async () => ({
@@ -71,3 +84,26 @@ test('composes focused deployment executors instead of a cross-family deployment
   expect(source).not.toContain('appDeployment:');
   expect(existsSync(join(directory, 'platform-runtime-app-deployment-host.ts'))).toBe(false);
 });
+
+test.each([undefined, 'app'] as const)(
+  'the macOS surface loader refuses a %s surface the owner routes to the runner',
+  async (surface) => {
+    vi.mocked(captureMacOsSurfaceSnapshot).mockClear();
+    const refusal = loadMacOsSurfaceSnapshot({ surface });
+    await expect(refusal).rejects.toBeInstanceOf(TypeError);
+    await expect(refusal).rejects.toThrow(
+      'Apple surface capture requires a helper-routed macOS surface',
+    );
+    expect(captureMacOsSurfaceSnapshot).not.toHaveBeenCalled();
+  },
+);
+
+test('the macOS surface loader forwards a helper-routed surface unchanged', async () => {
+  vi.mocked(captureMacOsSurfaceSnapshot).mockClear();
+  const signal = new AbortController().signal;
+  await loadMacOsSurfaceSnapshot({ surface: 'frontmost-app', depth: 2 }, signal);
+  expect(captureMacOsSurfaceSnapshot).toHaveBeenCalledWith(
+    { surface: 'frontmost-app', depth: 2 },
+    signal,
+  );
+});
diff --git a/src/platform-runtime-operation-host.ts b/src/platform-runtime-operation-host.ts
index cf005779a1..309b7fafec 100644
--- a/src/platform-runtime-operation-host.ts
+++ b/src/platform-runtime-operation-host.ts
@@ -5,6 +5,7 @@ import type {
   OwnedProcessRecordWriter,
 } from '@agent-device/contracts/platform-runtime-host';
 import type { PlatformRuntimeHost } from '@agent-device/contracts/platform-runtime-operations';
+import { macOsHelperSurface } from '@agent-device/contracts/session';
 import type {
   CaptureSnapshotInput,
   SnapshotResult,
@@ -41,8 +42,12 @@ export async function loadMacOsSurfaceSnapshot(
   options: CaptureSnapshotInput['options'],
   signal?: AbortSignal,
 ): Promise<SnapshotResult> {
+  const surface = macOsHelperSurface(options?.surface);
+  if (!surface) {
+    throw new TypeError('Apple surface capture requires a helper-routed macOS surface');
+  }
   const { captureMacOsSurfaceSnapshot } = await import('@agent-device/platform-apple/macos');
-  return await captureMacOsSurfaceSnapshot(options ?? {}, signal);
+  return await captureMacOsSurfaceSnapshot({ ...options, surface }, signal);
 }
 
 export function createPlatformRuntimeHost(options: {

From 9b085435eec35fdf97feb070c0a2107c14c19e8f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Oskar=20Kwa=C5=9Bniewski?= <oskar@okwasniewski.com>
Date: Thu, 24 Sep 2026 20:14:31 +0200
Subject: [PATCH 115/132] fix(android): fill verification samples until a
 deadline instead of three fixed points (#2926)

* fix(android): fill verification samples until a deadline instead of three fixed points

The typed text reaches the accessibility tree when the app renders it,
which a React Native controlled input on a loaded emulator did later than
the three fixed samples allowed (at 0, 150 and 500 ms elapsed: sleeps of
0, 150 and 350 ms before each): an otherwise passing fill failed twice on
a 4-vCPU CI emulator while the field still showed its hint. Sampling now
continues every 150 ms until the text has held for two consecutive samples
or 1.5 s have passed, and the sample taken at the deadline is the answer.
A fast device confirms after two samples, one fewer than before.

* test(android): the fill sampler paces itself by an injectable clock, so its tests advance time instead of waiting it out

* docs(android): the fill sampler's comment states the sampling rule, not the history behind it
---
 .../src/__tests__/fill-verification.test.ts   | 90 ++++++++++++++++---
 .../src/__tests__/text-input-fill.test.ts     |  4 +-
 .../platform-android/src/fill-verification.ts | 50 ++++++-----
 3 files changed, 105 insertions(+), 39 deletions(-)

diff --git a/packages/platform-android/src/__tests__/fill-verification.test.ts b/packages/platform-android/src/__tests__/fill-verification.test.ts
index 170cb44bfe..7699829df4 100644
--- a/packages/platform-android/src/__tests__/fill-verification.test.ts
+++ b/packages/platform-android/src/__tests__/fill-verification.test.ts
@@ -1,8 +1,9 @@
-// Fill reads the live hierarchy four times per attempt (one pre-action target read plus the
-// 0/150/350 ms settling samples). `am instrument` force-stops whatever is already instrumenting the
-// helper package, so a command-scoped capture stops the automation-helper session after every one of
-// those reads and the next read pays a fresh `am instrument` start. These tests pin who owns the
-// helper session across the samples — not what the samples conclude, which
+// Fill reads the live hierarchy at least three times per attempt: one pre-action target read plus
+// the settling samples, every 150 ms until the text has held for two of them or the deadline has
+// passed. `am instrument` force-stops whatever is already instrumenting the helper package, so a
+// command-scoped capture stops the automation-helper session after every one of those reads and the
+// next read pays a fresh `am instrument` start. These tests pin who owns the helper session across
+// the samples and how long the samples keep coming — not what one sample concludes, which
 // fill-diagnostics/input-actions-fill own.
 
 import { afterEach, beforeEach, test } from 'vitest';
@@ -14,6 +15,7 @@ import { ANDROID_SNAPSHOT_HELPER_FIXTURE_ARTIFACT } from './test-utils/android-s
 import {
   readAndroidFillTargetBeforeMutation,
   verifyAndroidFilledText,
+  type FillVerificationClock,
 } from '../fill-verification.ts';
 import { resetAndroidSnapshotHelperSessions } from '../snapshot-helper-session-lifecycle.ts';
 import {
@@ -50,7 +52,7 @@ test('daemon-session verification samples reuse one warm helper session', async
   );
 
   assert.equal(verification.ok, true);
-  assert.equal(session.captureCount(), 3);
+  assert.equal(session.captureCount(), 2, 'the text held for two samples');
   assert.equal(session.spawnArgs.length, 1, 'one instrumentation start for every sample');
   assert.equal(session.processes[0]?.exitCode, null, 'the session must outlive the command');
   assert.equal(session.forwardRemovals(), 0);
@@ -64,15 +66,15 @@ test('command-scoped verification samples release the helper after every sample'
     async () => await verifyAndroidFilledText(device, 10, 10, 'chips'),
   );
 
-  assert.equal(session.captureCount(), 3);
-  assert.equal(session.spawnArgs.length, 3, 'each sample pays its own instrumentation start');
-  assert.equal(session.forwardRemovals(), 3);
+  assert.equal(session.captureCount(), 2);
+  assert.equal(session.spawnArgs.length, 2, 'each sample pays its own instrumentation start');
+  assert.equal(session.forwardRemovals(), 2);
 });
 
 test('verification samples re-read the hierarchy instead of sharing one capture', async () => {
-  // The 0/150/350 ms samples exist to observe settling. Sharing the session must not turn into
-  // sharing its capture: replaying the first sample's still-settling text would report a mismatch
-  // for a field that did take the value.
+  // The samples exist to observe settling. Sharing the session must not turn into sharing its
+  // capture: replaying the first sample's still-settling text would report a mismatch for a field
+  // that did take the value.
   const settlingText = ['chi', 'chip', 'chips'];
   const session = createFillHelperSession({
     textForCapture: (captureIndex) => settlingText[captureIndex - 1] ?? 'chips',
@@ -86,11 +88,71 @@ test('verification samples re-read the hierarchy instead of sharing one capture'
       }),
   );
 
-  assert.equal(session.captureCount(), 3);
+  assert.equal(session.captureCount(), 4, 'two settling samples, then the text held for two');
   assert.equal(verification.actual, 'chips', 'the last sample is read from its own capture');
   assert.equal(verification.ok, true);
 });
 
+test('a value the app renders late still verifies, as long as it lands before the deadline', async () => {
+  // Six samples of the hint before the value shows, 900 ms in and inside the deadline.
+  const session = createFillHelperSession({
+    textForCapture: (captureIndex) => (captureIndex <= 6 ? 'Key echo' : 'chips'),
+  });
+  const clock = createFakeClock();
+
+  const verification = await withFillHelperProvider(
+    session.provider,
+    async () =>
+      await verifyAndroidFilledText(
+        device,
+        10,
+        10,
+        'chips',
+        { helperSessionScope: 'daemon-session' },
+        clock,
+      ),
+  );
+
+  assert.equal(verification.ok, true);
+  assert.equal(session.captureCount(), 8, 'six hint samples, then the value held for two');
+  assert.equal(clock.now(), 1050, 'the value held from the 900 ms sample to the 1050 ms one');
+});
+
+test('a value that never lands is a mismatch at the deadline, not before it', async () => {
+  const session = createFillHelperSession({ textForCapture: () => 'Key echo' });
+  const clock = createFakeClock();
+
+  const verification = await withFillHelperProvider(
+    session.provider,
+    async () =>
+      await verifyAndroidFilledText(
+        device,
+        10,
+        10,
+        'chips',
+        { helperSessionScope: 'daemon-session' },
+        clock,
+      ),
+  );
+
+  assert.equal(verification.ok, false);
+  assert.equal(verification.reason, 'text_mismatch');
+  assert.equal(verification.actual, 'Key echo', 'the sample at the deadline is the answer');
+  assert.equal(clock.now(), 1500, 'sampling ran to the deadline and not past it');
+  assert.equal(session.captureCount(), 11, 'a sample every 150 ms from 0 to 1500');
+});
+
+/** A clock the sampler advances by sleeping, so the deadline is reached without waiting it out. */
+function createFakeClock(): FillVerificationClock & { now(): number } {
+  let elapsed = 0;
+  return {
+    now: () => elapsed,
+    sleep: async (milliseconds) => {
+      elapsed += milliseconds;
+    },
+  };
+}
+
 test('the pre-action target read shares the daemon-session helper with the samples', async () => {
   const session = createFillHelperSession();
 
@@ -105,7 +167,7 @@ test('the pre-action target read shares the daemon-session helper with the sampl
   });
 
   assert.equal(target?.resourceId, 'com.example:id/field');
-  assert.equal(session.captureCount(), 4);
+  assert.equal(session.captureCount(), 3);
   assert.equal(session.spawnArgs.length, 1);
   assert.equal(session.forwardRemovals(), 0);
 });
diff --git a/packages/platform-android/src/__tests__/text-input-fill.test.ts b/packages/platform-android/src/__tests__/text-input-fill.test.ts
index ae4e8af8b1..f5f171ca5c 100644
--- a/packages/platform-android/src/__tests__/text-input-fill.test.ts
+++ b/packages/platform-android/src/__tests__/text-input-fill.test.ts
@@ -628,8 +628,8 @@ test('fillAndroid runs the whole attempt on one warm daemon-session helper', asy
     },
   );
 
-  // One pre-action target read plus the three settling samples.
-  assert.equal(captureCount, 4);
+  // One pre-action target read plus the two settling samples the text held for.
+  assert.equal(captureCount, 3);
   assert.equal(spawnArgs.length, 1);
   assert.equal(calls.filter(isAndroidHelperForwardRemoval).length, 0);
   assert.equal(processes[0]?.exitCode, null);
diff --git a/packages/platform-android/src/fill-verification.ts b/packages/platform-android/src/fill-verification.ts
index 7570a5d7d3..085b18b4e8 100644
--- a/packages/platform-android/src/fill-verification.ts
+++ b/packages/platform-android/src/fill-verification.ts
@@ -43,44 +43,48 @@ type AndroidFillVerificationContext = {
   activeInputMethodPackage?: string | null;
 };
 
+/**
+ * The sampling rule that verifies a fill: a hierarchy sample every 150 ms until the typed text has
+ * held for two consecutive samples or the deadline has passed, and the sample taken at the deadline
+ * is the answer. The typed text reaches the accessibility tree when the app renders it, and a
+ * React Native controlled input on a loaded emulator renders it late.
+ */
+const FILL_VERIFICATION_SAMPLE_INTERVAL_MS = 150;
+const FILL_VERIFICATION_DEADLINE_MS = 1500;
+
+/** The clock the sampler paces itself by; a test hands in one it advances instead of waiting. */
+export type FillVerificationClock = Readonly<{
+  now(): number;
+  sleep(milliseconds: number): Promise<void>;
+}>;
+
+const wallClock: FillVerificationClock = Object.freeze({ now: () => Date.now(), sleep });
+
 export async function verifyAndroidFilledText(
   device: DeviceInfo,
   x: number,
   y: number,
   expected: string,
   helper: AndroidHelperSessionOptions = {},
+  clock: FillVerificationClock = wallClock,
 ): Promise<AndroidFillVerification> {
-  const verificationDelaysMs = [0, 150, 350];
-  let lastVerification: AndroidFillVerification | null = null;
-  let stableVerification: AndroidFillVerification | null = null;
   const context = await readAndroidFillVerificationContext(device);
+  const deadline = clock.now() + FILL_VERIFICATION_DEADLINE_MS;
+  let previous: AndroidFillVerification | null = null;
 
-  for (const delayMs of verificationDelaysMs) {
-    if (delayMs > 0) {
-      await sleep(delayMs);
-    }
+  for (;;) {
     const verification = await inspectAndroidFilledText(device, x, y, expected, context, helper);
-    lastVerification = verification;
     if (verification.reason === 'ime_capture') {
       return verification;
     }
-    if (verification.ok) {
-      stableVerification = verification;
-    } else {
-      stableVerification = null;
+    const remainingMs = deadline - clock.now();
+    if ((verification.ok && previous?.ok) || remainingMs <= 0) {
+      return verification;
     }
+    previous = verification;
+    // The last sleep ends at the deadline, so the final sample starts there and not an interval later.
+    await clock.sleep(Math.min(FILL_VERIFICATION_SAMPLE_INTERVAL_MS, remainingMs));
   }
-
-  return (
-    stableVerification ??
-    lastVerification ?? {
-      ok: false,
-      actual: null,
-      reason: 'text_mismatch',
-      targetInput: null,
-      actualInput: null,
-    }
-  );
 }
 
 export async function readAndroidTextAtPoint(

From 2db7c42a8bbdf293195f0d55105f203b8be0022c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Oskar=20Kwa=C5=9Bniewski?= <oskar@okwasniewski.com>
Date: Thu, 24 Sep 2026 20:29:36 +0200
Subject: [PATCH 116/132] fix(android): carry the checked state of a checkable
 control on the snapshot node (#2913)

* fix(android): carry the checked state of a checkable control on the snapshot node

The snapshot helper never serialized `checked` or `checkable`, and the host reads only the helper's XML, so no later layer could recover it: a switch, checkbox, or radio button looked the same on or off, `get attrs` had no `checked` field, and snapshot text showed the control as plain. The helper now writes `checked` on every node Android reports as checkable, with both answers, so an unchecked switch reads `false`, a node that cannot be checked reads nothing, and so does a helper older than the attribute. The parser, the Android hierarchy node, and the published snapshot node carry it to `get attrs`, the unchanged-snapshot comparison, the selector digest, and the `[checked]` and `[unchecked]` markers in snapshot text. Both answers render because the diff compares the state and a checkable control rendered as plain would hide that it toggles.

* fix(daemon): the interaction outcome weighs the states stateMarkers prints, and a scroll's container check matches content by identity

Review follow-up. The interaction surface key folded enabled and selected but not checked, so a tap whose only effect was a toggle read as a no-op on the outcome lane while the diff called it a change, and a no-change retry would tap the switch straight back. The key now spreads stateMarkers, so the outcome lane, the unchanged-snapshot comparison, and the diff weigh one list.

With checked in the key, a flip inside a scroll container beside an unrelated change elsewhere (the status clock) read as content moving within the container. discriminatingSurfaceChangedWithinRect now matches entries on the flip-tolerant identity where one exists, told apart by document order when repeated, so a state flip at the same rect is not movement.

Tests: a checked-only flip is a change on the outcome lane; a flip at the same rect is not movement and a moved row is; the scroll claim is withheld for a flipped toggle inside the container; checked in both answers invalidates snapshot reuse and survives the selector digest.

* test(daemon): the capture-retry fixtures spell the interaction key with state markers

The two hand-written pre-signatures carried the literal enabled and unselected segments the key no longer writes for a plain node, so the post-tap capture read as changed and the retry never fired.

* fix(daemon): a surface entry carries a state-free content key, so an anonymous toggle is not movement

Review follow-up. The within-container movement check fell back to `key` for an entry without an identity, and `key` carries the checked state, so an unlabelled switch a swipe brushed still read as content moving. Every entry now carries `content`: the identity where the node has one, else its type and role; the check compares on that alone.

* fix(maestro): the snapshot signature weighs checked, so a toggle tap is not a no-op to retap

maestroSnapshotSignature hashed label, value, enabled, selected, focused
and bounds; a switch, checkbox or radio whose only observable effect is
its checked state produced the same signature before and after the tap,
so the settle and the no-change retry read the tap as a no-op and could
tap it back. checked joins the hashed object the way the interaction
outcome key already weighs it.
---
 .../snapshothelper/AccessibilityTreeXml.java  | 11 ++-
 .../__tests__/snapshot-diff-checked.test.ts   | 49 +++++++++++++
 .../capture-kit/src/snapshot/snapshot-diff.ts | 10 +--
 .../snapshot/snapshot-freshness/android.ts    | 11 +--
 .../src/snapshot/snapshot-lines.ts            | 23 ++++--
 packages/kernel/src/snapshot.ts               |  2 +
 .../daemon-runtime-port-observation.test.ts   | 14 ++++
 .../daemon-runtime-port-observation.ts        |  1 +
 .../__tests__/ui-hierarchy-checked.test.ts    | 70 +++++++++++++++++++
 .../src/ui-hierarchy-builder.ts               |  1 +
 .../platform-android/src/ui-hierarchy-node.ts |  1 +
 packages/platform-android/src/ui-hierarchy.ts |  4 ++
 src/__tests__/android-ui-hierarchy.test.ts    | 23 ++++++
 .../runtime/snapshot-unchanged.test.ts        |  2 +
 .../capture/runtime/snapshot-unchanged.ts     |  1 +
 src/commands/output/snapshot.test.ts          | 25 +++++++
 .../interaction-outcome-policy.test.ts        | 52 ++++++++++++++
 src/daemon/__tests__/response-views.test.ts   | 12 ++++
 src/daemon/__tests__/scroll-movement.test.ts  | 28 ++++++++
 .../snapshot-handler-capture-retry.test.ts    |  8 ++-
 src/daemon/interaction-outcome-policy.ts      | 52 ++++++++++----
 src/daemon/response-views.ts                  |  1 +
 src/daemon/session-state.ts                   |  7 ++
 website/docs/docs/commands.md                 |  4 +-
 website/docs/docs/snapshots.md                | 13 ++--
 25 files changed, 384 insertions(+), 41 deletions(-)
 create mode 100644 packages/capture-kit/src/snapshot/__tests__/snapshot-diff-checked.test.ts
 create mode 100644 packages/platform-android/src/__tests__/ui-hierarchy-checked.test.ts

diff --git a/android/snapshot-helper/src/main/java/com/callstack/agentdevice/snapshothelper/AccessibilityTreeXml.java b/android/snapshot-helper/src/main/java/com/callstack/agentdevice/snapshothelper/AccessibilityTreeXml.java
index c5c1da5249..775d622f7b 100644
--- a/android/snapshot-helper/src/main/java/com/callstack/agentdevice/snapshothelper/AccessibilityTreeXml.java
+++ b/android/snapshot-helper/src/main/java/com/callstack/agentdevice/snapshothelper/AccessibilityTreeXml.java
@@ -69,6 +69,12 @@ static void appendNode(
     // unselected control reports selected=false and a helper older than this attribute reports
     // nothing at all.
     appendAttribute(xml, "selected", Boolean.toString(node.isSelected()));
+    // Present only on a checkable control, with both answers: an unchecked switch reports
+    // checked=false, while a node that cannot be checked reports nothing, like a helper older than
+    // this attribute.
+    if (node.isCheckable()) {
+      appendAttribute(xml, "checked", Boolean.toString(node.isChecked()));
+    }
     boolean scrollable = node.isScrollable();
     if (scrollable) {
       appendAttribute(xml, "scrollable", "true");
@@ -164,9 +170,8 @@ private static boolean isHeading(AccessibilityNodeInfo node) {
     return Build.VERSION.SDK_INT >= Build.VERSION_CODES.P && node.isHeading();
   }
 
-  // Declared residue (agent-device #1832): checked / checkable / long-clickable are not serialized,
-  // so toggle state is invisible to agents. Adding them is a helper protocol change (new attributes
-  // + host parser + fields on the wire node), tracked there.
+  // Declared residue (agent-device #1832): long-clickable is not serialized. Adding it is a helper
+  // protocol change (new attribute + host parser + field on the wire node).
   private static void appendDrawingOrderAttribute(StringBuilder xml, AccessibilityNodeInfo node) {
     if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.N) {
       appendAttribute(xml, "drawing-order", Integer.toString(node.getDrawingOrder()));
diff --git a/packages/capture-kit/src/snapshot/__tests__/snapshot-diff-checked.test.ts b/packages/capture-kit/src/snapshot/__tests__/snapshot-diff-checked.test.ts
new file mode 100644
index 0000000000..bf95506373
--- /dev/null
+++ b/packages/capture-kit/src/snapshot/__tests__/snapshot-diff-checked.test.ts
@@ -0,0 +1,49 @@
+import assert from 'node:assert/strict';
+import { test } from 'vitest';
+import type { SnapshotNode } from '@agent-device/kernel/snapshot';
+import { buildSnapshotDiff } from '../snapshot-diff.ts';
+
+function toggle(checked?: boolean): SnapshotNode {
+  return {
+    ref: 'e12',
+    index: 0,
+    depth: 0,
+    type: 'android.widget.Switch',
+    label: 'Wi-Fi switch',
+    enabled: true,
+    hittable: true,
+    ...(checked === undefined ? {} : { checked }),
+  };
+}
+
+test('a checked-only flip diffs as changed lines that read differently', () => {
+  const diff = buildSnapshotDiff([toggle(false)], [toggle(true)]);
+  const changed = diff.lines.filter((line) => line.kind !== 'unchanged');
+
+  assert.equal(diff.summary.unchanged, 0);
+  assert.equal(changed.length > 0, true);
+  // The comparable key carries the checked state, so the rendered line has to as well, and both
+  // answers render: the pair reads `[unchecked]` -> `[checked]`, not two identical lines.
+  assert.match(changed[0]!.text, /\[unchecked\]/);
+  assert.match(changed.at(-1)!.text, /\[checked\]/);
+});
+
+test.each([
+  ['both unchecked', [toggle(false)], [toggle(false)]],
+  ['both unreported', [toggle()], [toggle()]],
+])('a still toggle with %s diffs as unchanged', (_label, previous, current) => {
+  const diff = buildSnapshotDiff(previous, current);
+
+  assert.equal(
+    diff.lines.every((line) => line.kind === 'unchanged'),
+    true,
+  );
+});
+
+test('a node that cannot be checked never reads as unchecked', () => {
+  const diff = buildSnapshotDiff([toggle()], [toggle()]);
+  assert.equal(
+    diff.lines.every((line) => !line.text.includes('checked')),
+    true,
+  );
+});
diff --git a/packages/capture-kit/src/snapshot/snapshot-diff.ts b/packages/capture-kit/src/snapshot/snapshot-diff.ts
index 3c7bf020b8..2b28a9198b 100644
--- a/packages/capture-kit/src/snapshot/snapshot-diff.ts
+++ b/packages/capture-kit/src/snapshot/snapshot-diff.ts
@@ -5,6 +5,7 @@ import {
   displayLabel,
   formatRole,
   formatSnapshotLine,
+  stateMarkers,
 } from './snapshot-lines.ts';
 
 export type SnapshotDiffResult = {
@@ -27,8 +28,9 @@ type SnapshotComparableLine = {
 function snapshotNodeToComparableLine(node: SnapshotNode, depthOverride?: number): string {
   const role = formatRole(node.type ?? 'Element');
   const textPart = displayLabel(node, role);
-  const enabledPart = node.enabled === false ? 'disabled' : 'enabled';
-  const selectedPart = node.selected === true ? 'selected' : 'unselected';
+  // The states the rendered line prints are the states the key compares, from one function, so a
+  // fact the diff weighs is always visible in the line it prints.
+  const statePart = stateMarkers(node).join(',');
   const hittablePart = node.hittable === true ? 'hittable' : 'not-hittable';
   const depthPart = String(depthOverride ?? node.depth ?? 0);
   // The rendered line carries the actions list, so the comparable key has to as
@@ -36,9 +38,7 @@ function snapshotNodeToComparableLine(node: SnapshotNode, depthOverride?: number
   // silently differs from the baseline's. JSON-encoded because the names are
   // app-authored and may contain the field separator.
   const actionsPart = node.actions ? JSON.stringify(node.actions) : '';
-  return [depthPart, role, textPart, enabledPart, selectedPart, hittablePart, actionsPart].join(
-    '|',
-  );
+  return [depthPart, role, textPart, statePart, hittablePart, actionsPart].join('|');
 }
 
 export function buildSnapshotDiff(
diff --git a/packages/capture-kit/src/snapshot/snapshot-freshness/android.ts b/packages/capture-kit/src/snapshot/snapshot-freshness/android.ts
index 8421f6236c..26955e8ab5 100644
--- a/packages/capture-kit/src/snapshot/snapshot-freshness/android.ts
+++ b/packages/capture-kit/src/snapshot/snapshot-freshness/android.ts
@@ -28,11 +28,12 @@ export function isNavigationSensitiveAction(command: string): boolean {
 
 /**
  * Route signature of an Android snapshot, from the fields the Android backend actually carries.
- * The helper serializes no `role`, `checked` or `long-clickable` (declared residue,
- * #1832), so a signature keying on them would compare constants and claim discrimination it does
- * not have. `selected` is left out as a judgement call rather than an inability: a tab-bar tap
- * flips it on two nodes, which the 90%-identical threshold below absorbs at every tree size this
- * check runs on, so keying on it would only add capture retries.
+ * The helper serializes no `role` or `long-clickable` (declared residue, #1832), so a signature
+ * keying on them would compare constants and claim discrimination it does not have. `selected`
+ * and `checked` are left out as a judgement call rather than an inability: a tab-bar tap flips
+ * selection on two nodes and a toggle tap flips one checked state, which the 90%-identical
+ * threshold below absorbs at every tree size this check runs on, so keying on them would only add
+ * capture retries.
  */
 export function buildSnapshotSignatures(nodes: SnapshotState['nodes']): string[] {
   return nodes.map((node) =>
diff --git a/packages/capture-kit/src/snapshot/snapshot-lines.ts b/packages/capture-kit/src/snapshot/snapshot-lines.ts
index f6004dc995..0a2c598579 100644
--- a/packages/capture-kit/src/snapshot/snapshot-lines.ts
+++ b/packages/capture-kit/src/snapshot/snapshot-lines.ts
@@ -195,6 +195,21 @@ export function formatRole(type: string): string {
   return lookupRoleLabel(normalized) || normalized || 'element';
 }
 
+/**
+ * The state markers every rendering path prints, and the states a snapshot diff compares: the diff
+ * renders its lines without text-surface summarizing, and a fact it weighs has to be visible in the
+ * line it prints, or a flip reads as a changed pair whose two lines look identical. Both checked
+ * answers render, since a checkable control shown plain would hide that it toggles; a node that
+ * cannot be checked carries neither.
+ */
+export function stateMarkers(node: SnapshotNode): string[] {
+  const markers: string[] = [];
+  if (node.enabled === false) markers.push('disabled');
+  if (node.selected === true) markers.push('selected');
+  if (node.checked !== undefined) markers.push(node.checked ? 'checked' : 'unchecked');
+  return markers;
+}
+
 function lookupRoleLabel(normalized: string): string | undefined {
   return Object.prototype.hasOwnProperty.call(ROLE_LABELS, normalized)
     ? ROLE_LABELS[normalized]
@@ -238,13 +253,7 @@ function buildLineMetadata(
   options: SnapshotLineFormatOptions,
   textSurface: { text: string; isLargeSurface: boolean; shouldSummarize: boolean },
 ): string[] {
-  const metadata: string[] = [];
-  if (node.enabled === false) metadata.push('disabled');
-  // Selection is a state a snapshot diff can report as changed, and the diff renders its lines
-  // without text-surface summarizing. A fact the diff compares has to be visible in the line it
-  // prints, or a selection flip reads as a changed pair whose two lines look identical.
-  if (node.selected === true) metadata.push('selected');
-  metadata.push(...(node.presentationHints ?? []));
+  const metadata = [...stateMarkers(node), ...(node.presentationHints ?? [])];
   if (!options.summarizeTextSurfaces) {
     return uniqueMetadata(metadata);
   }
diff --git a/packages/kernel/src/snapshot.ts b/packages/kernel/src/snapshot.ts
index a6a108d9c9..e1367ff19b 100644
--- a/packages/kernel/src/snapshot.ts
+++ b/packages/kernel/src/snapshot.ts
@@ -251,6 +251,8 @@ export type RawSnapshotNode = {
   rect?: Rect;
   enabled?: boolean;
   selected?: boolean;
+  /** Checked state of a checkable control (switch, checkbox, radio); absent means not checkable or unavailable. */
+  checked?: boolean;
   focused?: boolean;
   /** Accessibility heading flag an app set on the node; absent means not a heading or unavailable. */
   heading?: boolean;
diff --git a/packages/maestro/src/daemon-port/__tests__/daemon-runtime-port-observation.test.ts b/packages/maestro/src/daemon-port/__tests__/daemon-runtime-port-observation.test.ts
index 8d58d117d0..22e6b64b19 100644
--- a/packages/maestro/src/daemon-port/__tests__/daemon-runtime-port-observation.test.ts
+++ b/packages/maestro/src/daemon-port/__tests__/daemon-runtime-port-observation.test.ts
@@ -359,12 +359,26 @@ test('normalizes absent attributes like Maestro iOS hierarchy mapping', () => {
       enabled: false,
       selected: false,
       focused: false,
+      checked: false,
     },
   ]);
 
   expect(maestroSnapshotSignature(first)).toBe(maestroSnapshotSignature(second));
 });
 
+test('a checked-only flip changes the snapshot signature', () => {
+  // An Android switch tapped on: nothing about it moves or renames, only `checked` flips. The
+  // same signature before and after would read the tap as a no-op and retap it off again.
+  const off = makeSnapshot([
+    { index: 0, type: 'android.widget.Switch', label: 'Wi-Fi', checked: false },
+  ]);
+  const on = makeSnapshot([
+    { index: 0, type: 'android.widget.Switch', label: 'Wi-Fi', checked: true },
+  ]);
+
+  expect(maestroSnapshotSignature(off)).not.toBe(maestroSnapshotSignature(on));
+});
+
 test('excludes agent-device presentation metadata from Maestro hierarchy signatures', () => {
   const first = makeSnapshot([
     {
diff --git a/packages/maestro/src/daemon-port/daemon-runtime-port-observation.ts b/packages/maestro/src/daemon-port/daemon-runtime-port-observation.ts
index c90f173917..f6ce5ffd6d 100644
--- a/packages/maestro/src/daemon-port/daemon-runtime-port-observation.ts
+++ b/packages/maestro/src/daemon-port/daemon-runtime-port-observation.ts
@@ -408,6 +408,7 @@ export function maestroSnapshotSignature(snapshot: SnapshotState): string {
             enabled: node.enabled ?? false,
             selected: node.selected ?? false,
             focused: node.focused ?? false,
+            checked: node.checked ?? false,
             bounds: maestroSnapshotBounds(node.rect),
           })),
       ),
diff --git a/packages/platform-android/src/__tests__/ui-hierarchy-checked.test.ts b/packages/platform-android/src/__tests__/ui-hierarchy-checked.test.ts
new file mode 100644
index 0000000000..fe0d5b29d9
--- /dev/null
+++ b/packages/platform-android/src/__tests__/ui-hierarchy-checked.test.ts
@@ -0,0 +1,70 @@
+import { expect, test } from 'vitest';
+import { buildUiHierarchySnapshot, parseUiHierarchyTree } from '../ui-hierarchy.ts';
+
+// A settings row: a switch the helper reports as checkable beside a label that is not. The helper
+// writes `checked` only on the checkable node, with both answers.
+function togglesXml(wifiChecked: boolean): string {
+  return `<hierarchy>
+    <node class="android.widget.LinearLayout" resource-id="toggles" bounds="[0,0][400,200]"
+      window-index="0" window-type="1" window-layer="1" window-active="true" window-focused="true"
+      window-bounds="[0,0][400,800]" visible-to-user="true" enabled="true">
+      <node class="android.widget.TextView" resource-id="wifi-label" text="Wi-Fi"
+        bounds="[0,0][200,100]" enabled="true" visible-to-user="true" />
+      <node class="android.widget.Switch" resource-id="wifi-switch" content-desc="Wi-Fi switch"
+        bounds="[200,0][400,100]" clickable="true" enabled="true" visible-to-user="true"
+        checked="${wifiChecked}" />
+      <node class="android.widget.RadioButton" resource-id="size-small" text="Small"
+        bounds="[0,100][400,200]" clickable="true" enabled="true" visible-to-user="true"
+        checked="false" />
+    </node>
+  </hierarchy>`;
+}
+
+// A helper older than the `checked` attribute, or a switch it did not report as checkable.
+const UNREPORTED_CHECKED_XML =
+  '<hierarchy><node class="android.widget.Switch" resource-id="legacy-switch" content-desc="Wi-Fi"' +
+  ' bounds="[200,0][400,100]" clickable="true" enabled="true" visible-to-user="true" /></hierarchy>';
+
+function toggleNodes(raw: boolean, interactiveOnly = false, wifiChecked = true) {
+  const { nodes } = buildUiHierarchySnapshot(
+    parseUiHierarchyTree(togglesXml(wifiChecked)),
+    undefined,
+    { raw, interactiveOnly },
+  );
+  const byId = (identifier: string) => nodes.find((node) => node.identifier === identifier);
+  return { label: byId('wifi-label'), wifi: byId('wifi-switch'), small: byId('size-small') };
+}
+
+test.each([
+  { raw: false, interactiveOnly: false },
+  { raw: false, interactiveOnly: true },
+  { raw: true, interactiveOnly: false },
+  { raw: true, interactiveOnly: true },
+])(
+  'checked state reaches snapshot nodes in every projection (raw=$raw, -i=$interactiveOnly)',
+  ({ raw, interactiveOnly }) => {
+    const { wifi, small } = toggleNodes(raw, interactiveOnly);
+    expect(wifi?.checked).toBe(true);
+    expect(small?.checked).toBe(false);
+  },
+);
+
+test.each([true, false])('the switch answers the state the helper observed (%s)', (wifiChecked) => {
+  expect(toggleNodes(false, false, wifiChecked).wifi?.checked).toBe(wifiChecked);
+});
+
+test('attrs answer explicit false where a node that cannot be checked answers nothing', () => {
+  // Serialized, because that is the answer an agent reads: an unavailable fact drops the key
+  // while JSON encodes an observed `false`.
+  const { label, small } = toggleNodes(false);
+  expect(JSON.parse(JSON.stringify(small)).checked).toBe(false);
+  expect(JSON.parse(JSON.stringify(label))).not.toHaveProperty('checked');
+});
+
+test('an unreported checked state stays unknown instead of becoming false', () => {
+  const node = buildUiHierarchySnapshot(parseUiHierarchyTree(UNREPORTED_CHECKED_XML), undefined, {
+    raw: false,
+  }).nodes.find((node) => node.identifier === 'legacy-switch');
+  expect(node).toBeDefined();
+  expect(node?.checked).toBeUndefined();
+});
diff --git a/packages/platform-android/src/ui-hierarchy-builder.ts b/packages/platform-android/src/ui-hierarchy-builder.ts
index e4f0ffaffb..087fb44bf2 100644
--- a/packages/platform-android/src/ui-hierarchy-builder.ts
+++ b/packages/platform-android/src/ui-hierarchy-builder.ts
@@ -356,6 +356,7 @@ function createAndroidRawSnapshotNode(
     selected: node.selected,
     heading: node.heading,
     roleDescription: node.roleDescription,
+    checked: node.checked,
     editable: node.editable,
     password: node.password,
     hintShowing: node.hintShowing,
diff --git a/packages/platform-android/src/ui-hierarchy-node.ts b/packages/platform-android/src/ui-hierarchy-node.ts
index 205c56ef4a..9dfb81cbc5 100644
--- a/packages/platform-android/src/ui-hierarchy-node.ts
+++ b/packages/platform-android/src/ui-hierarchy-node.ts
@@ -19,6 +19,7 @@ export type AndroidUiHierarchy = {
   selected?: boolean;
   heading?: boolean;
   roleDescription?: string;
+  checked?: boolean;
   editable?: boolean;
   password?: boolean;
   hintShowing?: boolean;
diff --git a/packages/platform-android/src/ui-hierarchy.ts b/packages/platform-android/src/ui-hierarchy.ts
index 7317d057ba..508939aa37 100644
--- a/packages/platform-android/src/ui-hierarchy.ts
+++ b/packages/platform-android/src/ui-hierarchy.ts
@@ -39,6 +39,8 @@ export type AndroidUiNodeMetadata = {
   heading?: boolean;
   /** Helper-only: the localized role description an app set beside the class, verbatim. */
   roleDescription?: string;
+  /** Helper-only, present on a checkable control: the checked state of a switch, checkbox, or radio. */
+  checked?: boolean;
   password?: boolean;
   editable?: boolean;
   selectionStart?: number;
@@ -175,6 +177,7 @@ function readNodeAttributes(node: string): Omit<AndroidUiNodeMetadata, 'rect'> {
     ...optionalBoolAttr('selected', 'selected'),
     ...optionalBoolAttr('heading', 'heading'),
     ...optionalStringAttr('roleDescription', 'role-description'),
+    ...optionalBoolAttr('checked', 'checked'),
     ...optionalNumberAttr('drawingOrder', 'drawing-order'),
     ...optionalBoolAttr('scrollable', 'scrollable'),
     ...optionalBoolAttr('canScrollForward', 'can-scroll-forward'),
@@ -331,6 +334,7 @@ function normalizeAndroidUiHierarchyNode(
       selected: attrs.selected,
       heading: attrs.heading,
       roleDescription: attrs.roleDescription,
+      checked: attrs.checked,
       editable: attrs.editable,
       password: attrs.password,
       hintShowing: attrs.hintShowing,
diff --git a/src/__tests__/android-ui-hierarchy.test.ts b/src/__tests__/android-ui-hierarchy.test.ts
index d9edc4296d..e9149fd58c 100644
--- a/src/__tests__/android-ui-hierarchy.test.ts
+++ b/src/__tests__/android-ui-hierarchy.test.ts
@@ -272,6 +272,29 @@ test('a published Android snapshot carries the heading flag and the role descrip
   );
 });
 
+// A settings screen: the helper writes `checked` on the checkable switch and radio, with both
+// answers, and nothing on the label beside them.
+const ANDROID_TOGGLES_XML = `<hierarchy>
+  <node class="android.widget.LinearLayout" resource-id="com.example.app:id/toggles" bounds="[0,0][390,200]" enabled="true" visible-to-user="true">
+    <node class="android.widget.TextView" resource-id="com.example.app:id/wifi-label" text="Wi-Fi" bounds="[0,0][195,100]" enabled="true" visible-to-user="true"/>
+    <node class="android.widget.Switch" resource-id="com.example.app:id/wifi-switch" content-desc="Wi-Fi switch" bounds="[195,0][390,100]" clickable="true" enabled="true" visible-to-user="true" checked="true"/>
+    <node class="android.widget.RadioButton" resource-id="com.example.app:id/size-small" text="Small" bounds="[0,100][390,200]" clickable="true" enabled="true" visible-to-user="true" checked="false"/>
+  </node>
+</hierarchy>`;
+
+test('a published Android snapshot carries the checked state of checkable controls only', () => {
+  const nodes = publishUiHierarchy(ANDROID_TOGGLES_XML).nodes;
+  const byId = (identifier: string) => nodes.find((node) => node.identifier === identifier)!;
+
+  assert.equal(byId('com.example.app:id/wifi-switch').checked, true);
+  assert.equal(byId('com.example.app:id/size-small').checked, false);
+  assert.equal(byId('com.example.app:id/wifi-label').checked, undefined);
+  assert.deepEqual(
+    Array.from(androidUiNodes(ANDROID_TOGGLES_XML)).map((node) => node.checked),
+    [undefined, undefined, true, false],
+  );
+});
+
 test('parseUiHierarchy discards stale inactive Android application windows', () => {
   const xml = `<hierarchy>
   <node class="android.widget.FrameLayout" package="com.example.app" bounds="[0,0][390,844]" window-index="0" window-type="1" window-layer="10" window-active="true" window-focused="true" window-bounds="[0,0][390,844]">
diff --git a/src/commands/capture/runtime/snapshot-unchanged.test.ts b/src/commands/capture/runtime/snapshot-unchanged.test.ts
index 1b3cf7ce6f..32f5adfd61 100644
--- a/src/commands/capture/runtime/snapshot-unchanged.test.ts
+++ b/src/commands/capture/runtime/snapshot-unchanged.test.ts
@@ -73,6 +73,8 @@ test.each<Partial<SnapshotNode>>([
   { contentDescription: 'Create a draft' },
   { enabled: false },
   { selected: true },
+  { checked: true },
+  { checked: false },
   { focused: true },
   { placeholder: 'Key echo' },
   { hittable: false },
diff --git a/src/commands/capture/runtime/snapshot-unchanged.ts b/src/commands/capture/runtime/snapshot-unchanged.ts
index da581313bc..c03287df28 100644
--- a/src/commands/capture/runtime/snapshot-unchanged.ts
+++ b/src/commands/capture/runtime/snapshot-unchanged.ts
@@ -111,6 +111,7 @@ const PRESENTATION_SCALAR_FIELDS = {
   identifier: true,
   enabled: true,
   selected: true,
+  checked: true,
   focused: true,
   heading: true,
   roleDescription: true,
diff --git a/src/commands/output/snapshot.test.ts b/src/commands/output/snapshot.test.ts
index 8440986243..ccaff38177 100644
--- a/src/commands/output/snapshot.test.ts
+++ b/src/commands/output/snapshot.test.ts
@@ -820,3 +820,28 @@ test('formatSnapshotLine marks selection anywhere, and keeps text-surface metada
   assert.doesNotMatch(line, /\[editable\]/);
   assert.doesNotMatch(line, /\[scrollable\]/);
 });
+
+test.each([
+  [true, /\[checked\]/],
+  [false, /\[unchecked\]/],
+])(
+  'formatSnapshotLine renders both checked answers on the default path (%s)',
+  (checked, marker) => {
+    const line = formatSnapshotLine(
+      {
+        ref: 'e2',
+        index: 0,
+        depth: 0,
+        type: 'Switch',
+        label: 'Wi-Fi switch',
+        enabled: true,
+        checked,
+      },
+      0,
+      false,
+    );
+    // A checkable control rendered as plain would hide that it toggles, and the diff compares the
+    // state, so the line prints whichever answer the helper observed.
+    assert.match(line, marker);
+  },
+);
diff --git a/src/daemon/__tests__/interaction-outcome-policy.test.ts b/src/daemon/__tests__/interaction-outcome-policy.test.ts
index 9cd0d34c5a..20ef6154b2 100644
--- a/src/daemon/__tests__/interaction-outcome-policy.test.ts
+++ b/src/daemon/__tests__/interaction-outcome-policy.test.ts
@@ -467,3 +467,55 @@ test('discriminatingSurfaceChangedWithinRect counts content appearing inside the
 
   assert.equal(discriminatingSurfaceChangedWithinRect(before, after, LIST_RECT), true);
 });
+
+// Android is the only producer of `checked`, and a tap whose only effect is a toggle changes nothing
+// else on a screen without a mirrored label. The outcome lane has to read the flip as a change, or a
+// no-change retry taps the switch straight back.
+test('classifyInteractionSurfaceChange reads a checked-only flip as a change', () => {
+  const before = buildInteractionSurfaceSignature(makeToggleSnapshot(false).nodes);
+  const after = buildInteractionSurfaceSignature(makeToggleSnapshot(true).nodes);
+
+  assert.equal(classifyInteractionSurfaceChange(before, after), 'changed');
+});
+
+test.each([
+  { anonymous: false, label: 'a labelled switch' },
+  { anonymous: true, label: 'an anonymous switch' },
+])(
+  'discriminatingSurfaceChangedWithinRect reads a flip of $label at the same rect as no movement, and a moved one as movement',
+  ({ anonymous }) => {
+    const rect = { x: 0, y: 0, width: 390, height: 844 };
+    const signature = (checked: boolean, y?: number) =>
+      buildInteractionSurfaceSignature(makeToggleSnapshot(checked, y, anonymous).nodes);
+
+    assert.equal(
+      discriminatingSurfaceChangedWithinRect(signature(false), signature(true), rect),
+      false,
+    );
+    assert.equal(
+      discriminatingSurfaceChangedWithinRect(signature(false, 300), signature(false, 200), rect),
+      true,
+    );
+  },
+);
+
+// An anonymous switch has no identity, so its content is its type: the flip still changes only the
+// key, and a swipe that brushed it must not read as the list moving.
+function makeToggleSnapshot(checked: boolean, y = 300, anonymous = false): SnapshotState {
+  const base = makeSnapshot('Inbox');
+  return {
+    ...base,
+    nodes: [
+      ...base.nodes,
+      {
+        ref: 'e3',
+        index: 2,
+        parentIndex: 0,
+        type: 'android.widget.Switch',
+        ...(anonymous ? {} : { identifier: 'wifi-switch', label: 'Wi-Fi switch' }),
+        checked,
+        rect: { x: 300, y, width: 60, height: 40 },
+      },
+    ],
+  };
+}
diff --git a/src/daemon/__tests__/response-views.test.ts b/src/daemon/__tests__/response-views.test.ts
index 4d7cea294d..4b3a103026 100644
--- a/src/daemon/__tests__/response-views.test.ts
+++ b/src/daemon/__tests__/response-views.test.ts
@@ -338,6 +338,18 @@ test('attrs digest keeps explicit false/zero/empty field facts; unavailable ones
   }
 });
 
+test('attrs digest carries both checked answers, and none for a node that cannot be checked', () => {
+  for (const checked of [true, false]) {
+    const digest = getView!({ ref: 'e7', node: { ...MATCHED_NODE, checked } }, 'digest');
+    expect(digest.node).toEqual({ ...COMPACT_NODE, checked });
+  }
+  const plain = getView!({ ref: 'e7', node: MATCHED_NODE }, 'digest').node as Record<
+    string,
+    unknown
+  >;
+  expect('checked' in plain).toBe(false);
+});
+
 test('find/get default and full return today’s shape unchanged (same reference)', () => {
   const data: DaemonResponseData = { ref: '@e7', text: 'Sign in', node: MATCHED_NODE };
   expect(findView!(data, 'default')).toBe(data);
diff --git a/src/daemon/__tests__/scroll-movement.test.ts b/src/daemon/__tests__/scroll-movement.test.ts
index bf46f3cbdc..1097fa2ad3 100644
--- a/src/daemon/__tests__/scroll-movement.test.ts
+++ b/src/daemon/__tests__/scroll-movement.test.ts
@@ -388,6 +388,34 @@ test('a difference outside the scrolled container does not buy the movement clai
   assert.equal(spy.calls(), 1);
 });
 
+// Android reports `checked`, and a swipe that starts on a switch can flip it. On its own the flip is
+// identity-invariant and reads as an unchanged surface. Beside a change elsewhere, such as the status
+// clock ticking, the pair reads as changed, and the within-container check then sees a switch whose
+// key differs at the same rect: a state flip, not the list moving, so it buys no movement claim.
+test('a toggle the swipe flipped inside the container does not buy the movement claim', async () => {
+  const chrome = {
+    type: 'Image',
+    identifier: 'status-clock',
+    label: '2:40',
+    rect: { x: 20, y: 20, width: 60, height: 20 },
+  } as SnapshotNode;
+  const toggle = (checked: boolean) =>
+    ({
+      type: 'android.widget.Switch',
+      identifier: 'wifi-switch',
+      label: 'Wi-Fi switch',
+      checked,
+      rect: { x: 300, y: 320, width: 60, height: 40 },
+    }) as SnapshotNode;
+  const { observation } = observe({
+    baseline: baselineOf([...screen(0), chrome, toggle(false)]),
+    screens: [[...screen(0), { ...chrome, label: '2:41' } as SnapshotNode, toggle(true)]],
+  });
+
+  assert.equal(await observation, 'unobserved');
+  assertWithheld('change-outside-container');
+});
+
 test('a surface with no container to confine the claim to keeps the whole-surface answer', async () => {
   const rowsOnly = (offset: number) => screen(offset).filter((node) => node.type !== 'ScrollView');
   const { observation } = observe({
diff --git a/src/daemon/handlers/__tests__/snapshot-handler-capture-retry.test.ts b/src/daemon/handlers/__tests__/snapshot-handler-capture-retry.test.ts
index 59350cb063..0d00967083 100644
--- a/src/daemon/handlers/__tests__/snapshot-handler-capture-retry.test.ts
+++ b/src/daemon/handlers/__tests__/snapshot-handler-capture-retry.test.ts
@@ -96,7 +96,9 @@ test('captureSnapshot lazily retries pending no-change touch before returning fr
     attemptsRemaining: 2,
     preSignature: [
       {
-        key: 'open-feed|Open feed||Button||enabled|unselected|hittable|#0',
+        key: 'open-feed|Open feed||Button||hittable|#0',
+        identity: 'open-feed|Open feed||Button',
+        content: 'open-feed|Open feed||Button',
         x: 20,
         y: 120,
         width: 160,
@@ -239,7 +241,9 @@ test('captureSnapshot retries pending tap outcome before post-gesture stabilizat
     attemptsRemaining: 2,
     preSignature: [
       {
-        key: '|Navigate to Third||android.widget.Button||enabled|unselected|hittable|#0',
+        key: '|Navigate to Third||android.widget.Button||hittable|#0',
+        identity: '|Navigate to Third||android.widget.Button',
+        content: '|Navigate to Third||android.widget.Button',
         x: 302,
         y: 1301,
         width: 476,
diff --git a/src/daemon/interaction-outcome-policy.ts b/src/daemon/interaction-outcome-policy.ts
index 3519a01e83..40c78cea55 100644
--- a/src/daemon/interaction-outcome-policy.ts
+++ b/src/daemon/interaction-outcome-policy.ts
@@ -2,6 +2,7 @@ import type { CommandFlags } from '@agent-device/contracts/command';
 import { isMobilePlatform } from '@agent-device/kernel/device';
 import type { Rect, SnapshotNode, SnapshotState } from '@agent-device/kernel/snapshot';
 import { collectKeyboardChromeRefs } from '@agent-device/capture-kit/snapshot-chrome';
+import { stateMarkers } from '@agent-device/capture-kit/snapshot-lines';
 import { emitDiagnostic } from '@agent-device/host-kit/diagnostics';
 import { isViewportRootNode } from '@agent-device/contracts/snapshot';
 import { contextFromFlags, type DaemonCommandContext } from './context.ts';
@@ -465,8 +466,11 @@ export function summarizeDiscriminatingSurfaceDivergence(
 }
 
 /**
- * Whether the DISCRIMINATING entries inside `rect` differ across a gesture, on the same key-matched,
- * rect-tolerant view `haveIdenticalDiscriminatingSurfaces` uses — restricted to one region.
+ * Whether the DISCRIMINATING entries inside `rect` moved across a gesture: one left or entered the
+ * region, or its rect moved beyond tolerance. Entries match on `content`: the flip-tolerant
+ * `identity` where they have one, the type and role of an anonymous node otherwise, told apart by
+ * document order when repeated. A scroll moves content, while a state flip inside the container (a
+ * switch the swipe brushed, a row it selected) changes the key at the same rect and is not movement.
  *
  * A whole-surface difference is not automatically the gesture's doing. A captured tree carries system
  * chrome with it, and on Android the status bar clocks and icons change on their own while the app's
@@ -478,17 +482,29 @@ export function discriminatingSurfaceChangedWithinRect(
   after: InteractionSurfaceSignature,
   rect: Rect,
 ): boolean {
-  const beforeInRect = discriminatingEntriesWithinRect(before, rect);
-  const afterByKey = new Map(
-    discriminatingEntriesWithinRect(after, rect).map((entry) => [entry.key, entry]),
-  );
-  for (const entry of beforeInRect) {
-    const other = afterByKey.get(entry.key);
+  const beforeInRect = contentKeyed(discriminatingEntriesWithinRect(before, rect));
+  const afterInRect = contentKeyed(discriminatingEntriesWithinRect(after, rect));
+  for (const [content, entry] of beforeInRect) {
+    const other = afterInRect.get(content);
     if (!other) return true;
     if (!rectsWithinTolerance(entry, other)) return true;
-    afterByKey.delete(entry.key);
+    afterInRect.delete(content);
+  }
+  return afterInRect.size > 0;
+}
+
+/** Entries by what they are rather than the state they are in; repeated content is told apart by document order. */
+function contentKeyed(
+  entries: InteractionSurfaceSignature,
+): Map<string, InteractionSurfaceSignature[number]> {
+  const occurrences = new Map<string, number>();
+  const keyed = new Map<string, InteractionSurfaceSignature[number]>();
+  for (const entry of entries) {
+    const occurrence = occurrences.get(entry.content) ?? 0;
+    occurrences.set(entry.content, occurrence + 1);
+    keyed.set(`${entry.content}|#${occurrence}`, entry);
   }
-  return afterByKey.size > 0;
+  return keyed;
 }
 
 function discriminatingEntriesWithinRect(
@@ -541,6 +557,7 @@ function buildInteractionSurfaceEntry(
   return {
     key: `${semanticKey}|#${occurrence}`,
     ...(identity ? { identity } : {}),
+    content: interactionSurfaceContent(node, identity),
     x: Math.round(node.rect.x),
     y: Math.round(node.rect.y),
     width: Math.round(node.rect.width),
@@ -549,10 +566,15 @@ function buildInteractionSurfaceEntry(
   };
 }
 
+/** What the element is without the state it is in: its identity, else the type and role of an anonymous node. */
+function interactionSurfaceContent(node: SnapshotNode, identity: string | undefined): string {
+  return identity ?? `${node.type ?? ''}|${node.role ?? ''}`;
+}
+
 /**
  * What the element IS — never where it sits, and never volatile state a gesture
  * is expected to change. `interactionSurfaceSemanticKey` deliberately folds in
- * `hittable`/`enabled`/`selected` and an occurrence index, which is right for
+ * the states `stateMarkers` prints, `hittable`, and an occurrence index, which is right for
  * "did these two back-to-back captures agree" and wrong for "is this the same
  * element as before the gesture": scrolling flips `hittable` the moment a
  * node's centre leaves the viewport, so keying on it evicts precisely the
@@ -584,6 +606,11 @@ function isNonDiscriminatingSurfaceNode(
   return isViewportRootNode(node) || (node.ref !== undefined && keyboardChromeRefs.has(node.ref));
 }
 
+/**
+ * What the element is and the state it is in. The states are the ones `stateMarkers` prints, so the
+ * outcome lane, the unchanged-snapshot comparison, and the diff weigh one list: a tap whose only
+ * effect is a toggle is a change here, not a no-op to retry.
+ */
 function interactionSurfaceSemanticKey(node: SnapshotNode): string | undefined {
   const semanticKey = [
     node.identifier,
@@ -591,8 +618,7 @@ function interactionSurfaceSemanticKey(node: SnapshotNode): string | undefined {
     node.value,
     node.type,
     node.role,
-    node.enabled === false ? 'disabled' : 'enabled',
-    node.selected === true ? 'selected' : 'unselected',
+    ...stateMarkers(node),
     node.hittable === true ? 'hittable' : 'not-hittable',
   ]
     .map((value) => (typeof value === 'string' ? value.trim() : ''))
diff --git a/src/daemon/response-views.ts b/src/daemon/response-views.ts
index 2454c8c59a..ee18e4a8c7 100644
--- a/src/daemon/response-views.ts
+++ b/src/daemon/response-views.ts
@@ -114,6 +114,7 @@ const SELECTOR_DIGEST_NODE_FIELDS = [
   'identifier',
   'enabled',
   'selected',
+  'checked',
   'focused',
   'heading',
   'roleDescription',
diff --git a/src/daemon/session-state.ts b/src/daemon/session-state.ts
index d7ef7e626d..354b928636 100644
--- a/src/daemon/session-state.ts
+++ b/src/daemon/session-state.ts
@@ -53,6 +53,13 @@ export type InteractionSurfaceEntry = {
    * comparison entirely.
    */
   identity?: string;
+  /**
+   * What the element is without the state it is in: `identity` where the node
+   * has one, else its type and role. A within-container movement check compares
+   * entries on this, in document order when repeated, because a state flip
+   * changes `key` at the same rect and is not movement.
+   */
+  content: string;
   x: number;
   y: number;
   width: number;
diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md
index 8a74a11cbb..d9eb54e337 100644
--- a/website/docs/docs/commands.md
+++ b/website/docs/docs/commands.md
@@ -391,8 +391,8 @@ agent-device get attrs @e1
   act on stale React Native screens. API 23 cannot report sibling `drawing-order`, so this scan fails
   conservative and `androidSnapshot.occlusionScanUnavailable: true` discloses the difference.
   Android `--raw` is the acquired tree: it also keeps nodes Android marks invisible and stale
-  application windows. The helper does not report `checked`/`checkable` state, and it caps
-  captures at 5000 nodes before any `--scope` applies (`truncated: true`).
+  application windows. The helper caps captures at 5000 nodes before any `--scope` applies
+  (`truncated: true`).
 - `truncated: true` means the backend cut the capture at one of its limits — the Android helper
   and the iOS Simulator AX bridge at 5000 nodes, the XCTest runner and the web provider at their
   own bounds. Every backend walks the tree in document order, so what falls off is what comes
diff --git a/website/docs/docs/snapshots.md b/website/docs/docs/snapshots.md
index 99b08b5bf1..f07adc2541 100644
--- a/website/docs/docs/snapshots.md
+++ b/website/docs/docs/snapshots.md
@@ -117,16 +117,21 @@ the strategy owns which tiers it may use.
 ## Android node metadata
 
 Android snapshot nodes and `get attrs` (including the digest response) carry the native
-`selected`, `heading`, `roleDescription`, `editable`, `password`, `hintShowing`, `placeholder`,
-`selectionStart`, and `selectionEnd` facts whenever the accessibility tree reports them. Explicit
-`false` and `0` are kept; an absent field means the fact was unavailable, not false. `hintShowing`
-and `placeholder` need Android API 26 or later, `heading` API 28 or later.
+`selected`, `checked`, `heading`, `roleDescription`, `editable`, `password`, `hintShowing`,
+`placeholder`, `selectionStart`, and `selectionEnd` facts whenever the accessibility tree reports
+them. Explicit `false` and `0` are kept; an absent field means the fact was unavailable, not false.
+`hintShowing` and `placeholder` need Android API 26 or later, `heading` API 28 or later.
 
 - `selected` is the accessibility selected state an app sets on a control — the active bottom-tab or
   segmented-control item, or the chosen row of a list. Android reports it explicitly as `true` or
   `false`; an older helper APK omits the field, which means the answer is unavailable rather than
   unselected. Snapshot text marks the node `[selected]`, and `is selected`, a `selected=true`
   selector, and a Maestro `selected:` qualifier all match on it.
+- `checked` is the checked state of a checkable control — a switch, a checkbox, a radio button, or a
+  view an app marked checkable. Android reports it as `true` or `false` on those nodes only; a node
+  that cannot be checked, or an older helper APK, omits the field. Snapshot text marks the node
+  `[checked]` or `[unchecked]`, so a toggle that reads as plain text is one Android did not report as
+  checkable.
 - `heading` is the accessibility heading flag an app sets on a node, the way React Native's
   `accessibilityRole="header"` does on a plain `View`; it is present only as `true`.
 - `roleDescription` is the localized role description an app sets beside the native class, verbatim

From 86f0697d8374b93569c05405bbcc5153ea4d66db Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 24 Sep 2026 20:41:14 +0200
Subject: [PATCH 117/132] test(android): drop byte-identical duplicate
 text-input cases (#2931)

Six of the sixteen `test()` registrations in this file were byte-identical
copies of three others: "keeps delayed typing in typed-input mode" appeared
twice, and "tolerates delayed React Native text verification" and "reports
clear error when unicode input is unsupported" appeared three and four times.
Block-level diffing confirms one distinct body per name, so the extra copies
registered extra passes that no production change could distinguish.

They arrived already duplicated in 6dd7d406c and survived two file moves.
Deleting them removes ~3s of repeated fake-adb wall clock from the file.

Verified the surviving copy still owns the delayed-typing contract: dropping
`chunkSize: delayMs > 0 ? 1 : ANDROID_INPUT_TEXT_CHUNK_SIZE` in text-input.ts
turns "fillAndroid keeps delayed typing in typed-input mode" red, and no other
test in the family catches that decision.
---
 .../src/__tests__/text-input.test.ts          | 171 ------------------
 1 file changed, 171 deletions(-)

diff --git a/packages/platform-android/src/__tests__/text-input.test.ts b/packages/platform-android/src/__tests__/text-input.test.ts
index 74a58e994a..353ad6294b 100644
--- a/packages/platform-android/src/__tests__/text-input.test.ts
+++ b/packages/platform-android/src/__tests__/text-input.test.ts
@@ -234,177 +234,6 @@ test('typeAndroid reports clear error when unicode input is unsupported', async
   );
 });
 
-test('fillAndroid keeps delayed typing in typed-input mode', async () => {
-  let state = '';
-  await withFakeAdb(
-    (args) => {
-      const helperResponse = snapshotHelperResponse(args, () => state);
-      if (helperResponse !== undefined) return helperResponse;
-      if (isShellInput(args, 'tap')) return undefined;
-      if (isShellKeyevent(args, 'KEYCODE_MOVE_END')) return undefined;
-      if (isShellKeyevent(args, 'KEYCODE_DEL')) {
-        state = '';
-        return undefined;
-      }
-      if (isShellInput(args, 'text')) {
-        state += args[3] ?? '';
-        return undefined;
-      }
-      return { stderr: `unexpected args: ${args.join(' ')}`, exitCode: 1 };
-    },
-    async ({ calls, device }) => {
-      await fillAndroid(device, 10, 10, 'go', 1);
-      assert.equal(shellInputTextCalls(calls).length, 2);
-      assert.equal(
-        calls.some((args) => args.join(' ').startsWith('shell cmd clipboard set text')),
-        false,
-      );
-      assert.equal(
-        calls.some((args) => args.includes('KEYCODE_PASTE')),
-        false,
-      );
-    },
-    {
-      provider: { snapshotHelperArtifact: ANDROID_SNAPSHOT_HELPER_FIXTURE_ARTIFACT },
-    },
-  );
-}, 15_000);
-
-test('fillAndroid tolerates delayed React Native text verification', async () => {
-  // The first hierarchy dump reports a stale truncated value (React Native
-  // committing late); the later stability dumps report the real text.
-  let state = '';
-  let dumpCount = 0;
-  await withFakeAdb(
-    (args) => {
-      const helperResponse = snapshotHelperResponse(args, () => {
-        dumpCount += 1;
-        return dumpCount === 1 ? 'sent the updat' : state;
-      });
-      if (helperResponse !== undefined) return helperResponse;
-      if (isShellInput(args, 'tap')) return undefined;
-      if (isShellKeyevent(args, 'KEYCODE_MOVE_END')) return undefined;
-      if (isShellKeyevent(args, 'KEYCODE_DEL')) {
-        state = '';
-        return undefined;
-      }
-      if (isShellInput(args, 'text')) {
-        state += (args[3] ?? '').replaceAll('%s', ' ');
-        return undefined;
-      }
-      return { stderr: `unexpected args: ${args.join(' ')}`, exitCode: 1 };
-    },
-    async ({ device }) => {
-      await fillAndroid(device, 10, 10, 'sent the update');
-    },
-    {
-      provider: { snapshotHelperArtifact: ANDROID_SNAPSHOT_HELPER_FIXTURE_ARTIFACT },
-    },
-  );
-}, 10_000);
-
-test('typeAndroid reports clear error when unicode input is unsupported', async () => {
-  await withFakeAdb(
-    (args) => {
-      if (args.join(' ').startsWith('shell cmd clipboard set text')) {
-        return 'No shell command implementation.';
-      }
-      if (isShellInput(args, 'text')) {
-        return {
-          stderr: "Exception occurred while executing 'text':\njava.lang.NullPointerException\n",
-          exitCode: 255,
-        };
-      }
-      return { stderr: `unexpected args: ${args.join(' ')}`, exitCode: 1 };
-    },
-    async ({ device }) => {
-      await assertRejectsAppError(() => typeAndroid(device, '很'), {
-        code: 'COMMAND_FAILED',
-        message: /provider-native text injection/i,
-      });
-    },
-  );
-});
-
-test('fillAndroid tolerates delayed React Native text verification', async () => {
-  // The first hierarchy dump reports a stale truncated value (React Native
-  // committing late); the later stability dumps report the real text.
-  let state = '';
-  let dumpCount = 0;
-  await withFakeAdb(
-    (args) => {
-      const helperResponse = snapshotHelperResponse(args, () => {
-        dumpCount += 1;
-        return dumpCount === 1 ? 'sent the updat' : state;
-      });
-      if (helperResponse !== undefined) return helperResponse;
-      if (isShellInput(args, 'tap')) return undefined;
-      if (isShellKeyevent(args, 'KEYCODE_MOVE_END')) return undefined;
-      if (isShellKeyevent(args, 'KEYCODE_DEL')) {
-        state = '';
-        return undefined;
-      }
-      if (isShellInput(args, 'text')) {
-        state += (args[3] ?? '').replaceAll('%s', ' ');
-        return undefined;
-      }
-      return { stderr: `unexpected args: ${args.join(' ')}`, exitCode: 1 };
-    },
-    async ({ device }) => {
-      await fillAndroid(device, 10, 10, 'sent the update');
-    },
-    {
-      provider: { snapshotHelperArtifact: ANDROID_SNAPSHOT_HELPER_FIXTURE_ARTIFACT },
-    },
-  );
-}, 10_000);
-
-test('typeAndroid reports clear error when unicode input is unsupported', async () => {
-  await withFakeAdb(
-    (args) => {
-      if (args.join(' ').startsWith('shell cmd clipboard set text')) {
-        return 'No shell command implementation.';
-      }
-      if (isShellInput(args, 'text')) {
-        return {
-          stderr: "Exception occurred while executing 'text':\njava.lang.NullPointerException\n",
-          exitCode: 255,
-        };
-      }
-      return { stderr: `unexpected args: ${args.join(' ')}`, exitCode: 1 };
-    },
-    async ({ device }) => {
-      await assertRejectsAppError(() => typeAndroid(device, '很'), {
-        code: 'COMMAND_FAILED',
-        message: /provider-native text injection/i,
-      });
-    },
-  );
-});
-
-test('typeAndroid reports clear error when unicode input is unsupported', async () => {
-  await withFakeAdb(
-    (args) => {
-      if (args.join(' ').startsWith('shell cmd clipboard set text')) {
-        return 'No shell command implementation.';
-      }
-      if (isShellInput(args, 'text')) {
-        return {
-          stderr: "Exception occurred while executing 'text':\njava.lang.NullPointerException\n",
-          exitCode: 255,
-        };
-      }
-      return { stderr: `unexpected args: ${args.join(' ')}`, exitCode: 1 };
-    },
-    async ({ device }) => {
-      await assertRejectsAppError(() => typeAndroid(device, '很'), {
-        code: 'COMMAND_FAILED',
-        message: /provider-native text injection/i,
-      });
-    },
-  );
-});
-
 function shellInputTextCalls(calls: (readonly string[])[]): (readonly string[])[] {
   return calls.filter((args) => isShellInput(args, 'text'));
 }

From a4f72f0e3deb1071222b3586b772d4073764360c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Oskar=20Kwa=C5=9Bniewski?= <oskar@okwasniewski.com>
Date: Thu, 24 Sep 2026 20:41:31 +0200
Subject: [PATCH 118/132] feat(android): a helper capture carries the display's
 pixel density in its snapshot metadata (#2928)

Android bounds are physical pixels and so are the points press and the
gestures take; nothing said what a pixel was worth, so a consumer that
lays out in dp had no way to place a tap or read a size. The helper now
reports DisplayMetrics.density beside its capture metadata (the same
configuration the framework lays out with, a wm density override
included), and the host publishes it as androidSnapshot.pixelDensity,
the display's physical pixels per dp (2.625 on a 420 dpi phone). Rects
stay in physical pixels; an older helper omits the field.
---
 .../snapshothelper/SnapshotInstrumentation.java            | 6 ++++++
 packages/contracts/src/snapshot-types.ts                   | 7 +++++++
 .../src/__tests__/snapshot-helper-session-protocol.test.ts | 2 ++
 .../platform-android/src/__tests__/snapshot-helper.test.ts | 1 +
 packages/platform-android/src/snapshot-helper-capture.ts   | 1 +
 .../src/snapshot-helper-session-protocol.ts                | 1 +
 packages/platform-android/src/snapshot-helper-types.ts     | 2 ++
 packages/platform-android/src/snapshot-types.ts            | 7 +++++++
 packages/platform-android/src/snapshot.ts                  | 1 +
 website/docs/docs/snapshots.md                             | 7 +++++++
 10 files changed, 35 insertions(+)

diff --git a/android/snapshot-helper/src/main/java/com/callstack/agentdevice/snapshothelper/SnapshotInstrumentation.java b/android/snapshot-helper/src/main/java/com/callstack/agentdevice/snapshothelper/SnapshotInstrumentation.java
index 9abf3bdb85..6f7742a186 100644
--- a/android/snapshot-helper/src/main/java/com/callstack/agentdevice/snapshothelper/SnapshotInstrumentation.java
+++ b/android/snapshot-helper/src/main/java/com/callstack/agentdevice/snapshothelper/SnapshotInstrumentation.java
@@ -2,6 +2,7 @@
 
 import android.app.Instrumentation;
 import android.app.UiAutomation;
+import android.content.res.Resources;
 import android.os.Bundle;
 import android.util.Base64;
 import java.io.BufferedReader;
@@ -120,6 +121,11 @@ private static void putCaptureMetadata(
     result.putString("nodeCount", Integer.toString(capture.nodeCount));
     result.putString("truncated", Boolean.toString(capture.truncated));
     result.putString("elapsedMs", Long.toString(elapsedMs));
+    // Physical pixels per dp of the display the bounds above were measured on, from the same
+    // configuration the framework lays out with (a `wm density` override included), so a host that
+    // works in dp has the factor beside the pixels instead of a second adb round trip.
+    result.putString(
+        "pixelDensity", Float.toString(Resources.getSystem().getDisplayMetrics().density));
   }
 
   private void runOneShotViewport(Bundle result) {
diff --git a/packages/contracts/src/snapshot-types.ts b/packages/contracts/src/snapshot-types.ts
index 5d2fa4e0a0..713916d259 100644
--- a/packages/contracts/src/snapshot-types.ts
+++ b/packages/contracts/src/snapshot-types.ts
@@ -43,6 +43,13 @@ export type BackendSnapshotOptions = SnapshotOptions & {
 };
 export type AndroidSnapshotBackendMetadata = {
   backend: 'android-helper';
+  /**
+   * Physical pixels per density-independent pixel of the display the bounds are measured on, as
+   * the helper's `DisplayMetrics` report it (2.625 on a 420 dpi phone). Node rects and the points
+   * `press` takes stay in physical pixels; a consumer that lays out in dp divides by it. Absent on
+   * an older helper.
+   */
+  pixelDensity?: number;
   helperVersion?: string;
   helperApiVersion?: string;
   helperTransport?: string;
diff --git a/packages/platform-android/src/__tests__/snapshot-helper-session-protocol.test.ts b/packages/platform-android/src/__tests__/snapshot-helper-session-protocol.test.ts
index 557e6c634b..ce47d3199f 100644
--- a/packages/platform-android/src/__tests__/snapshot-helper-session-protocol.test.ts
+++ b/packages/platform-android/src/__tests__/snapshot-helper-session-protocol.test.ts
@@ -16,6 +16,7 @@ test('parses the session envelope and snapshot metadata', () => {
       captureMode: 'interactive-windows',
       windowCount: '2',
       nodeCount: '1',
+      pixelDensity: '2.625',
     },
   });
 
@@ -27,6 +28,7 @@ test('parses the session envelope and snapshot metadata', () => {
       captureMode: 'interactive-windows',
       windowCount: 2,
       nodeCount: 1,
+      pixelDensity: 2.625,
       waitForIdleTimeoutMs: undefined,
       waitForIdleQuietMs: undefined,
       timeoutMs: undefined,
diff --git a/packages/platform-android/src/__tests__/snapshot-helper.test.ts b/packages/platform-android/src/__tests__/snapshot-helper.test.ts
index a7084badbf..aa4d479d2f 100644
--- a/packages/platform-android/src/__tests__/snapshot-helper.test.ts
+++ b/packages/platform-android/src/__tests__/snapshot-helper.test.ts
@@ -81,6 +81,7 @@ test('parseAndroidSnapshotHelperOutput reconstructs XML chunks and metadata', ()
     nodeCount: 1,
     truncated: false,
     elapsedMs: 42,
+    pixelDensity: undefined,
     transport: 'instrumentation',
   });
 });
diff --git a/packages/platform-android/src/snapshot-helper-capture.ts b/packages/platform-android/src/snapshot-helper-capture.ts
index 028d217606..f4a2d710b0 100644
--- a/packages/platform-android/src/snapshot-helper-capture.ts
+++ b/packages/platform-android/src/snapshot-helper-capture.ts
@@ -486,6 +486,7 @@ function readHelperMetadata(finalResult: Record<string, string>): AndroidSnapsho
     nodeCount: readOptionalNumber(finalResult.nodeCount),
     truncated: readOptionalBoolean(finalResult.truncated),
     elapsedMs: readOptionalNumber(finalResult.elapsedMs),
+    pixelDensity: readOptionalNumber(finalResult.pixelDensity),
   };
 }
 
diff --git a/packages/platform-android/src/snapshot-helper-session-protocol.ts b/packages/platform-android/src/snapshot-helper-session-protocol.ts
index 05fb4ab5f3..f0e36ed205 100644
--- a/packages/platform-android/src/snapshot-helper-session-protocol.ts
+++ b/packages/platform-android/src/snapshot-helper-session-protocol.ts
@@ -303,5 +303,6 @@ function readSessionMetadata(headers: Record<string, string>): AndroidSnapshotHe
     nodeCount: readInstrumentationResultNumber(headers.nodeCount),
     truncated: readInstrumentationResultBoolean(headers.truncated),
     elapsedMs: readInstrumentationResultNumber(headers.elapsedMs),
+    pixelDensity: readInstrumentationResultNumber(headers.pixelDensity),
   };
 }
diff --git a/packages/platform-android/src/snapshot-helper-types.ts b/packages/platform-android/src/snapshot-helper-types.ts
index b0581b0b02..9431f3f21d 100644
--- a/packages/platform-android/src/snapshot-helper-types.ts
+++ b/packages/platform-android/src/snapshot-helper-types.ts
@@ -95,6 +95,8 @@ export type AndroidSnapshotHelperMetadata = {
   nodeCount?: number;
   truncated?: boolean;
   elapsedMs?: number;
+  /** Physical pixels per dp of the captured display, as the helper's own `DisplayMetrics` say. */
+  pixelDensity?: number;
   transport?: AndroidSnapshotHelperTransport;
   sessionReused?: boolean;
 };
diff --git a/packages/platform-android/src/snapshot-types.ts b/packages/platform-android/src/snapshot-types.ts
index 0525449187..8b93b638bc 100644
--- a/packages/platform-android/src/snapshot-types.ts
+++ b/packages/platform-android/src/snapshot-types.ts
@@ -6,6 +6,13 @@ import type {
 
 export type AndroidSnapshotBackendMetadata = {
   backend: 'android-helper';
+  /**
+   * Physical pixels per density-independent pixel of the display the bounds are measured on, as
+   * the helper's `DisplayMetrics` report it (2.625 on a 420 dpi phone). Node rects and the points
+   * `press` takes stay in physical pixels; a consumer that lays out in dp divides by it. Absent on
+   * an older helper.
+   */
+  pixelDensity?: number;
   helperVersion?: string;
   helperApiVersion?: string;
   helperTransport?: AndroidSnapshotHelperTransport;
diff --git a/packages/platform-android/src/snapshot.ts b/packages/platform-android/src/snapshot.ts
index 4d25cedbb5..0ed1b5e1fb 100644
--- a/packages/platform-android/src/snapshot.ts
+++ b/packages/platform-android/src/snapshot.ts
@@ -437,6 +437,7 @@ function formatAndroidHelperCaptureResult(
     xml: capture.xml,
     metadata: {
       backend: 'android-helper',
+      pixelDensity: capture.metadata.pixelDensity,
       helperVersion: artifact.manifest.version,
       helperApiVersion: capture.metadata.helperApiVersion,
       helperTransport: capture.metadata.transport,
diff --git a/website/docs/docs/snapshots.md b/website/docs/docs/snapshots.md
index f07adc2541..31662eaaac 100644
--- a/website/docs/docs/snapshots.md
+++ b/website/docs/docs/snapshots.md
@@ -116,6 +116,13 @@ the strategy owns which tiers it may use.
 
 ## Android node metadata
 
+Android bounds are physical pixels, as the accessibility tree reports them, and so are the points
+`press`, `fill`, and the gesture commands take. `androidSnapshot.pixelDensity` on a helper capture
+is the display's physical pixels per density-independent pixel, as the helper's `DisplayMetrics`
+report it (a 420 dpi phone reports `2.625`, a `wm density` override included); a consumer that works
+in dp divides rects by it and multiplies its points. An older helper omits it. iOS reports points
+already, so it carries no such factor.
+
 Android snapshot nodes and `get attrs` (including the digest response) carry the native
 `selected`, `checked`, `heading`, `roleDescription`, `editable`, `password`, `hintShowing`,
 `placeholder`, `selectionStart`, and `selectionEnd` facts whenever the accessibility tree reports

From 0fb15772644760c4ab528ab41fe330f331ecd6c5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 24 Sep 2026 20:41:42 +0200
Subject: [PATCH 119/132] refactor(provider-webdriver): remove superseded cloud
 runtime factories (#2930)

The `@internal` AWS Device Farm and BrowserStack factory pairs claimed to be
"used by integration tests" while no test or production module referenced them.
`createCloudWebDriverProviderDefinitions` composes each provider's runtime
directly and is the only construction path, so both factories were the
superseded pre-definitions shape.

Removing them also removes `resolveConfiguredBrowserStackCapabilities`, whose
webdriverCapabilities-shadowing precedence the live path never applied: it
passes `buildCloudWebDriverBaseCapabilities(platform, deviceName)` as
`configured` instead.
---
 .../provider-webdriver/src/aws-device-farm.ts |  68 +---------
 .../provider-webdriver/src/browserstack.ts    | 124 +-----------------
 2 files changed, 6 insertions(+), 186 deletions(-)

diff --git a/packages/provider-webdriver/src/aws-device-farm.ts b/packages/provider-webdriver/src/aws-device-farm.ts
index e7cbfeda10..23e259d574 100644
--- a/packages/provider-webdriver/src/aws-device-farm.ts
+++ b/packages/provider-webdriver/src/aws-device-farm.ts
@@ -1,11 +1,6 @@
+import type { CloudWebDriverCapabilityOverrides } from './capabilities.ts';
+import { buildCloudWebDriverBaseCapabilities } from './runtime.ts';
 import {
-  createCloudWebDriverCapabilities,
-  type CloudWebDriverCapabilityOverrides,
-  type CloudWebDriverProviderCapabilities,
-} from './capabilities.ts';
-import { buildCloudWebDriverBaseCapabilities, createCloudWebDriverRuntime } from './runtime.ts';
-import {
-  listAwsDeviceFarmCloudArtifacts,
   readAwsArtifacts,
   type AwsDeviceFarmArtifact,
   type AwsDeviceFarmArtifactGroup,
@@ -15,18 +10,12 @@ import type {
   CloudWebDriverRuntimeOptions,
   CloudWebDriverPrepareSession,
 } from './runtime.ts';
-import type {
-  DeviceLease,
-  LeaseLifecycleContext,
-  ProviderDeviceRuntime,
-} from '@agent-device/contracts/device';
+import type { DeviceLease, LeaseLifecycleContext } from '@agent-device/contracts/device';
 import { setTimeout as sleep } from 'node:timers/promises';
 import { AppError } from '@agent-device/kernel/errors';
 import type { RunHostCommand } from './dependencies.ts';
-import { CLOUD_WEBDRIVER_PROVIDERS } from './providers.ts';
 import { releaseOnFailure, resolveLeaseValue, type LeaseValue } from './webdriver-utils.ts';
 
-const AWS_DEVICE_FARM_PROVIDER = CLOUD_WEBDRIVER_PROVIDERS.awsDeviceFarm;
 export const AWS_DEVICE_FARM_CAPABILITY_OVERRIDES = {
   install: {
     support: 'unsupported',
@@ -104,57 +93,6 @@ export type AwsDeviceFarmWebDriverRuntimeOptions = {
   prepareSession?: CloudWebDriverRuntimeOptions['prepareSession'];
 };
 
-/**
- * @internal AWS Device Farm capability builder used by integration tests.
- */
-export function getAwsDeviceFarmWebDriverCapabilities(
-  platform: CloudWebDriverPlatform,
-): CloudWebDriverProviderCapabilities {
-  return createCloudWebDriverCapabilities({
-    provider: AWS_DEVICE_FARM_PROVIDER,
-    platform,
-    overrides: AWS_DEVICE_FARM_CAPABILITY_OVERRIDES,
-  });
-}
-
-/**
- * @internal AWS Device Farm runtime factory used by integration tests.
- */
-export function createAwsDeviceFarmWebDriverRuntime(
-  options: AwsDeviceFarmWebDriverRuntimeOptions,
-): ProviderDeviceRuntime {
-  if (!options.client) {
-    throw new AppError(
-      'INVALID_ARGS',
-      'AWS Device Farm runtime construction requires a client from the package facade.',
-    );
-  }
-  const client = options.client;
-  const platform = options.platform ?? 'android';
-  const deviceName = options.deviceName ?? 'AWS Device Farm device';
-  return createCloudWebDriverRuntime({
-    clientVersion: options.clientVersion,
-    provider: AWS_DEVICE_FARM_PROVIDER,
-    endpoint: 'http://127.0.0.1/',
-    platform,
-    deviceName,
-    webdriverCapabilities: options.webdriverCapabilities,
-    prepareSession:
-      options.prepareSession ??
-      createAwsDeviceFarmPrepareSession({
-        ...options,
-        platform,
-        deviceName,
-        client,
-      }),
-    listArtifacts: async ({ provider, providerSessionId }) =>
-      await listAwsDeviceFarmCloudArtifacts(provider, providerSessionId, client),
-    deviceId: options.deviceId,
-    requestPolicy: options.requestPolicy,
-    capabilityOverrides: AWS_DEVICE_FARM_CAPABILITY_OVERRIDES,
-  });
-}
-
 export type AwsCliDeviceFarmClientOptions = {
   runHostCommand: RunHostCommand;
   region?: string;
diff --git a/packages/provider-webdriver/src/browserstack.ts b/packages/provider-webdriver/src/browserstack.ts
index ca845ea93f..6c8d10fd4b 100644
--- a/packages/provider-webdriver/src/browserstack.ts
+++ b/packages/provider-webdriver/src/browserstack.ts
@@ -1,34 +1,13 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import type { CloudArtifact, CloudArtifactsResult } from '@agent-device/contracts/observability';
-import {
-  createCloudWebDriverCapabilities,
-  type CloudWebDriverCapabilityOverrides,
-  type CloudWebDriverProviderCapabilities,
-} from './capabilities.ts';
-import {
-  createCloudWebDriverRuntime,
-  type CloudWebDriverPlatform,
-  type CloudWebDriverRuntimeOptions,
-  type CloudWebDriverUploadApp,
-} from './runtime.ts';
-import type { DeviceLease, ProviderDeviceRuntime } from '@agent-device/contracts/device';
+import type { CloudWebDriverCapabilityOverrides } from './capabilities.ts';
+import type { CloudWebDriverUploadApp } from './runtime.ts';
 import { AppError } from '@agent-device/kernel/errors';
-import { CLOUD_WEBDRIVER_PROVIDERS } from './providers.ts';
-import {
-  buildBrowserStackDeviceFeatureCapabilities,
-  type BrowserStackDeviceFeatureFields,
-} from './browserstack-device-features.ts';
 import { agentDeviceRequestHeaders } from './request-headers.ts';
 import { cloudArtifactsReadyOrPending } from './artifact-results.ts';
-import {
-  basicAuthHeader,
-  resolveLeaseValue,
-  trimTrailingSlash,
-  type LeaseValue,
-} from './webdriver-utils.ts';
+import { basicAuthHeader, trimTrailingSlash } from './webdriver-utils.ts';
 
-const BROWSERSTACK_PROVIDER = CLOUD_WEBDRIVER_PROVIDERS.browserStack;
 export const BROWSERSTACK_APP_AUTOMATE_ENDPOINT = 'https://hub-cloud.browserstack.com/wd/hub/';
 export const BROWSERSTACK_APP_UPLOAD_ENDPOINT =
   'https://api-cloud.browserstack.com/app-automate/upload';
@@ -49,29 +28,6 @@ export const BROWSERSTACK_CAPABILITY_OVERRIDES = {
   },
 } as const satisfies CloudWebDriverCapabilityOverrides;
 
-export type BrowserStackWebDriverRuntimeOptions = {
-  clientVersion: string;
-  username: string;
-  accessKey: string;
-  platform: CloudWebDriverPlatform;
-  deviceName: string;
-  osVersion: string;
-  app?: string;
-  projectName?: string;
-  buildName?: LeaseValue<string>;
-  sessionName?: LeaseValue<string>;
-  deviceFeatures?: BrowserStackDeviceFeatureFields;
-  webdriverCapabilities?:
-    | Record<string, unknown>
-    | ((lease: DeviceLease) => Record<string, unknown>);
-  endpoint?: string | URL;
-  uploadEndpoint?: string | URL;
-  sessionDetailsEndpoint?: string | URL;
-  deviceId?: CloudWebDriverRuntimeOptions['deviceId'];
-  requestPolicy?: CloudWebDriverRuntimeOptions['requestPolicy'];
-  prepareSession?: CloudWebDriverRuntimeOptions['prepareSession'];
-};
-
 export type BrowserStackCapabilitiesOptions = {
   deviceName: string;
   osVersion: string;
@@ -84,71 +40,6 @@ export type BrowserStackCapabilitiesOptions = {
   configured?: Record<string, unknown>;
 };
 
-/**
- * @internal BrowserStack capability builder used by integration tests.
- */
-export function getBrowserStackWebDriverCapabilities(
-  platform: CloudWebDriverPlatform,
-): CloudWebDriverProviderCapabilities {
-  return createCloudWebDriverCapabilities({
-    provider: BROWSERSTACK_PROVIDER,
-    platform,
-    overrides: BROWSERSTACK_CAPABILITY_OVERRIDES,
-  });
-}
-
-/**
- * @internal BrowserStack runtime factory used by integration tests.
- */
-export function createBrowserStackWebDriverRuntime(
-  options: BrowserStackWebDriverRuntimeOptions,
-): ProviderDeviceRuntime {
-  const uploadEndpoint = options.uploadEndpoint ?? BROWSERSTACK_APP_UPLOAD_ENDPOINT;
-  const artifactOptions = {
-    clientVersion: options.clientVersion,
-    username: options.username,
-    accessKey: options.accessKey,
-    endpoint: options.sessionDetailsEndpoint ?? BROWSERSTACK_SESSION_DETAILS_ENDPOINT,
-  };
-  return createCloudWebDriverRuntime({
-    clientVersion: options.clientVersion,
-    provider: BROWSERSTACK_PROVIDER,
-    endpoint: options.endpoint ?? BROWSERSTACK_APP_AUTOMATE_ENDPOINT,
-    platform: options.platform,
-    deviceName: options.deviceName,
-    auth: {
-      username: options.username,
-      accessKey: options.accessKey,
-    },
-    webdriverCapabilities: (lease) =>
-      buildBrowserStackCapabilities({
-        deviceName: options.deviceName,
-        osVersion: options.osVersion,
-        app: options.app,
-        projectName: options.projectName,
-        buildName: resolveLeaseValue(options.buildName, lease) ?? lease.runId,
-        sessionName: resolveLeaseValue(options.sessionName, lease) ?? lease.leaseId,
-        deviceFeatures: buildBrowserStackDeviceFeatureCapabilities(
-          options.deviceFeatures ?? {},
-          options.platform,
-        ),
-        configured: resolveConfiguredBrowserStackCapabilities(options, lease),
-      }),
-    uploadApp: createBrowserStackUploadApp({
-      clientVersion: options.clientVersion,
-      username: options.username,
-      accessKey: options.accessKey,
-      endpoint: uploadEndpoint,
-    }),
-    listArtifacts: async ({ provider, providerSessionId }) =>
-      await listBrowserStackCloudArtifacts(provider, providerSessionId, artifactOptions),
-    deviceId: options.deviceId,
-    prepareSession: options.prepareSession,
-    requestPolicy: options.requestPolicy,
-    capabilityOverrides: BROWSERSTACK_CAPABILITY_OVERRIDES,
-  });
-}
-
 export type BrowserStackSessionDetailsOptions = {
   clientVersion: string;
   username: string;
@@ -258,15 +149,6 @@ function asRecord(value: unknown): Record<string, unknown> {
     : {};
 }
 
-function resolveConfiguredBrowserStackCapabilities(
-  options: BrowserStackWebDriverRuntimeOptions,
-  lease: DeviceLease,
-): Record<string, unknown> {
-  return typeof options.webdriverCapabilities === 'function'
-    ? options.webdriverCapabilities(lease)
-    : (options.webdriverCapabilities ?? {});
-}
-
 async function fetchBrowserStackSessionDetails(
   sessionId: string,
   options: BrowserStackSessionDetailsOptions,

From 6428c548537d6dd8c263cda3a3da084faab51130 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 24 Sep 2026 20:42:08 +0200
Subject: [PATCH 120/132] test(ios-runner): pin production-built runner
 requests in a golden table TS and Swift both verify (#2900)

* test(apple-runner): pin production-built runner requests in a golden table

Add contracts/fixtures/runner-requests.json: one entry per production
request site, captured at its real entry point. Three producer tests own
the entries: the platform-apple request sites, the runner-internal sites
(real HTTP bodies from the fake runner), and the two recording modules.
runner-contract.test.ts asserts every RunnerCommand has an entry, names
are sorted and unique, and the drive code builds no request itself.

Refs #2881

* test(apple-runner): verify the runner request golden table in Swift

Every fixture request decodes as Command and re-encodes with the same key
set, every CommandType case has a request, and every stored field of
Command, SequenceStep and RunnerGesturePlan appears in some request.
CommandType becomes CaseIterable for the case check.

Refs #2881

* chore(gates): keep runner-requests.json entries on one line each

Refs #2881

* test(apple-runner): pin the macOS desktopScroll pixels request

* test(apple-runner): share the runner-requests fixture check with root tests

Export the fixture reader as @agent-device/platform-apple/runner/requests-fixtures
so root producers pin requests through the same commandId normalization, and derive
the request-literal guard's sources from the producers the fixture declares.

Refs #2881

* test(apple-runner): drive root recording requests from a dedicated golden file

The request-literal guard scans every fixture producer, so root behavior
tests that doubled as producers had to weaken their exact request
assertions. Move the root recording drives into
src/__tests__/screen-recording-runner-requests.test.ts, restore the
original literals, and pin the recordStop sent without an app bundle.

Producers must now be *runner-requests.test.ts files that call
assertProducedRunnerRequests(import.meta.filename, ...), so a comment no
longer satisfies the check. The runner-internal drive moves to
runner/__tests__/runner-requests.test.ts to follow that rule.

Refs #2881
---
 .oxfmtrc.json                                 |   4 +-
 .../RunnerTests+Models.swift                  |   2 +-
 .../UnitTests/RunnerTests+ModelsTests.swift   | 110 ++++++++
 apple/runner/RUNNER_PROTOCOL.md               |   1 +
 contracts/fixtures/runner-requests.json       |  70 +++++
 packages/platform-apple/package.json          |   4 +
 .../interactor-runner-provider.test.ts        |  69 +----
 .../__tests__/recording-runner-provider.ts    |  72 +++++
 .../src/__tests__/runner-requests.test.ts     | 266 ++++++++++++++++++
 .../runner/__tests__/runner-requests.test.ts  | 176 ++++++++++++
 .../src/runner/runner-requests.fixtures.ts    |  47 ++++
 scripts/layering/package-boundaries.test.ts   |   2 +
 .../layering/platform-package-policy.test.ts  |   1 +
 scripts/layering/platform-package-policy.ts   |   1 +
 .../screen-recording-runner-requests.test.ts  |  72 +++++
 15 files changed, 833 insertions(+), 64 deletions(-)
 create mode 100644 contracts/fixtures/runner-requests.json
 create mode 100644 packages/platform-apple/src/__tests__/recording-runner-provider.ts
 create mode 100644 packages/platform-apple/src/__tests__/runner-requests.test.ts
 create mode 100644 packages/platform-apple/src/runner/__tests__/runner-requests.test.ts
 create mode 100644 packages/platform-apple/src/runner/runner-requests.fixtures.ts
 create mode 100644 src/__tests__/screen-recording-runner-requests.test.ts

diff --git a/.oxfmtrc.json b/.oxfmtrc.json
index ef771b1b35..00e66b8708 100644
--- a/.oxfmtrc.json
+++ b/.oxfmtrc.json
@@ -10,6 +10,8 @@
     "node_modules/**",
     "**/*.md",
     "scripts/maestro-conformance/corpus/**",
-    "fallow-baselines/**"
+    "fallow-baselines/**",
+    // One entry per line, so each pinned runner request changes as one reviewable diff line.
+    "contracts/fixtures/runner-requests.json"
   ]
 }
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift
index 2a4b84de27..d33303a79f 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift
@@ -2,7 +2,7 @@ import AgentDeviceSnapshotPresentation
 
 // MARK: - Wire Models
 
-enum CommandType: String, Codable {
+enum CommandType: String, Codable, CaseIterable {
   case tap
   case mouseClick
   case longPress
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+ModelsTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+ModelsTests.swift
index eab82171dc..1931498727 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+ModelsTests.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+ModelsTests.swift
@@ -32,5 +32,115 @@ extension RunnerTests {
   func runnerCommandFixture(_ json: String) throws -> Command {
     try JSONDecoder().decode(Command.self, from: Data(json.utf8))
   }
+
+  func testProductionRunnerRequestsDecodeWithoutDroppingAKey() throws {
+    for (name, request) in try productionRunnerRequests() {
+      let command = try decodeProductionRunnerRequest(request, name)
+      XCTAssertEqual(command.command.rawValue, request["command"] as? String, name)
+      let reencoded = try JSONSerialization.jsonObject(with: JSONEncoder().encode(command))
+      XCTAssertEqual(runnerRequestKeyPaths(reencoded), runnerRequestKeyPaths(request), name)
+    }
+  }
+
+  func testEveryRunnerCommandTypeHasAProductionRequest() throws {
+    let produced = Set(try productionRunnerRequests().compactMap { $0.request["command"] as? String })
+    let orphaned = CommandType.allCases.map(\.rawValue).filter { !produced.contains($0) }
+    XCTAssertEqual(orphaned, [], "CommandType cases with no production request")
+  }
+
+  func testEveryRunnerRequestFieldHasAProductionRequest() throws {
+    let entries = try productionRunnerRequests()
+    let requests = entries.map(\.request)
+    let steps = requests.flatMap { $0["steps"] as? [[String: Any]] ?? [] }
+    let plans = requests.compactMap { $0["gesturePlan"] as? [String: Any] }
+    let pointers = plans.flatMap { $0["pointers"] as? [[String: Any]] ?? [] }
+    let samples = pointers.flatMap { $0["samples"] as? [[String: Any]] ?? [] }
+    let commands = try entries.map { try decodeProductionRunnerRequest($0.request, $0.name) }
+    let command = try XCTUnwrap(commands.first, "no production request")
+    let plan = try XCTUnwrap(
+      commands.compactMap(\.gesturePlan).first,
+      "no production request carries a gesturePlan"
+    )
+    let step = try JSONDecoder().decode(SequenceStep.self, from: Data(#"{"kind":"tap"}"#.utf8))
+    let sample = try XCTUnwrap(plan.pointers.first?.samples.first)
+    assertEveryStoredField(of: command, appearsIn: requests, "Command")
+    assertEveryStoredField(of: step, appearsIn: steps, "SequenceStep")
+    assertEveryStoredField(of: plan, appearsIn: plans, "RunnerGesturePlan")
+    assertEveryStoredField(
+      of: plan.viewport,
+      appearsIn: plans.compactMap { $0["viewport"] as? [String: Any] },
+      "RunnerGestureViewport"
+    )
+    assertEveryStoredField(of: plan.pointers[0], appearsIn: pointers, "RunnerGesturePointer")
+    assertEveryStoredField(of: sample, appearsIn: samples, "RunnerGestureSample")
+    assertEveryStoredField(
+      of: sample.point,
+      appearsIn: samples.compactMap { $0["point"] as? [String: Any] },
+      "RunnerGesturePoint"
+    )
+  }
+
+  private func productionRunnerRequests() throws -> [(name: String, request: [String: Any])] {
+    let fixtureURL = URL(fileURLWithPath: #filePath)
+      .deletingLastPathComponent()
+      .deletingLastPathComponent()
+      .deletingLastPathComponent()
+      .deletingLastPathComponent()
+      .deletingLastPathComponent()
+      .deletingLastPathComponent()
+      .appendingPathComponent("contracts/fixtures/runner-requests.json")
+    let entries = try XCTUnwrap(
+      JSONSerialization.jsonObject(with: Data(contentsOf: fixtureURL)) as? [[String: Any]]
+    )
+    return try entries.map { entry in
+      (
+        name: try XCTUnwrap(entry["name"] as? String),
+        request: try XCTUnwrap(entry["request"] as? [String: Any], "\(entry["name"] ?? "?")")
+      )
+    }
+  }
+
+  private func decodeProductionRunnerRequest(_ request: [String: Any], _ name: String) throws
+    -> Command
+  {
+    do {
+      return try JSONDecoder().decode(
+        Command.self,
+        from: JSONSerialization.data(withJSONObject: request)
+      )
+    } catch {
+      XCTFail("\(name) does not decode as Command: \(error)")
+      throw error
+    }
+  }
+
+  private func runnerRequestKeyPaths(_ value: Any, _ prefix: String = "") -> Set<String> {
+    if let object = value as? [String: Any] {
+      return object.reduce(into: Set<String>()) { paths, field in
+        paths.insert(prefix + field.key)
+        paths.formUnion(runnerRequestKeyPaths(field.value, "\(prefix)\(field.key)."))
+      }
+    }
+    if let array = value as? [Any] {
+      return array.reduce(into: Set<String>()) { paths, element in
+        paths.formUnion(runnerRequestKeyPaths(element, "\(prefix)[]."))
+      }
+    }
+    return []
+  }
+
+  private func assertEveryStoredField(
+    of value: Any,
+    appearsIn objects: [[String: Any]],
+    _ level: String
+  ) {
+    let fields = Set(Mirror(reflecting: value).children.compactMap(\.label))
+    let produced = Set(objects.flatMap(\.keys))
+    XCTAssertEqual(
+      fields.subtracting(produced).sorted(),
+      [],
+      "\(level) fields with no production request"
+    )
+  }
 }
 #endif
diff --git a/apple/runner/RUNNER_PROTOCOL.md b/apple/runner/RUNNER_PROTOCOL.md
index aa80ffac1e..24a9d5d35b 100644
--- a/apple/runner/RUNNER_PROTOCOL.md
+++ b/apple/runner/RUNNER_PROTOCOL.md
@@ -14,6 +14,7 @@ The daemon probes `http://127.0.0.1:<port>/command` for simulator and desktop fl
 ## Request Shape
 
 Every request includes a `command` field. Additional fields depend on the command family.
+The request vocabulary is `contracts/fixtures/runner-requests.json`: the requests production builds.
 
 Examples:
 
diff --git a/contracts/fixtures/runner-requests.json b/contracts/fixtures/runner-requests.json
new file mode 100644
index 0000000000..9a5ce46a00
--- /dev/null
+++ b/contracts/fixtures/runner-requests.json
@@ -0,0 +1,70 @@
+[
+  {"name": "ios-device.physical-device-control.activate", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "activate", "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "ios-device.physical-device-control.terminate", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "terminate", "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "ios-device.physical-device-screenshot.coredevice-file", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "screenshot", "appBundleId": "com.example.app", "fullscreen": true, "inlineScreenshot": false, "commandId": "<commandId>"}},
+  {"name": "ios-device.physical-device-screenshot.xctest-inline", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "screenshot", "appBundleId": "com.example.app", "inlineScreenshot": true, "commandId": "<commandId>"}},
+  {"name": "ios-device.recording-start-abort.stop", "producer": "src/__tests__/screen-recording-runner-requests.test.ts", "request": {"command": "recordStop", "appBundleId": "com.example.app"}},
+  {"name": "ios-device.recording-start.fps", "producer": "src/__tests__/screen-recording-runner-requests.test.ts", "request": {"command": "recordStart", "outPath": "agent-device-recording-1700000000000.mp4", "fps": 30, "appBundleId": "com.example.app"}},
+  {"name": "ios-device.recording-stop.no-app", "producer": "src/__tests__/screen-recording-runner-requests.test.ts", "request": {"command": "recordStop"}},
+  {"name": "ios-device.recording-stop.session", "producer": "src/__tests__/screen-recording-runner-requests.test.ts", "request": {"command": "recordStop", "appBundleId": "com.example.app"}},
+  {"name": "ios-simulator.alert.accept", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "alert", "action": "accept", "appBundleId": "com.example.app", "timeoutMs": 10000, "commandId": "<commandId>"}},
+  {"name": "ios-simulator.alert.dismiss", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "alert", "action": "dismiss", "appBundleId": "com.example.app", "timeoutMs": 10000, "commandId": "<commandId>"}},
+  {"name": "ios-simulator.alert.get", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "alert", "action": "get", "appBundleId": "com.example.app", "timeoutMs": 10000, "commandId": "<commandId>"}},
+  {"name": "ios-simulator.interactions-double-tap.single", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "sequence", "steps": [{"kind": "doubleTap", "x": 10, "y": 20}], "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "ios-simulator.interactions-fill.non-hittable-fallback", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "type", "x": 10, "y": 20, "text": "hello", "textEntryMode": "replace", "allowNonHittableCoordinateFallback": true, "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "ios-simulator.interactions-fill.replace", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "type", "x": 10, "y": 20, "text": "hello", "delayMs": 10, "textEntryMode": "replace", "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "ios-simulator.interactions-focus.synthesized", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "tap", "x": 10, "y": 20, "synthesized": true, "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "ios-simulator.interactions-gesture-viewport.read", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "gestureViewport", "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "ios-simulator.interactions-gesture.single", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "gesture", "gesturePlan": {"topology": "single", "intent": "pan", "executionProfile": "timed-pan", "durationMs": 120, "viewport": {"x": 0, "y": 0, "width": 390, "height": 844}, "pointers": [{"pointerId": 0, "samples": [{"offsetMs": 0, "point": {"x": 100, "y": 400}}, {"offsetMs": 120, "point": {"x": 100, "y": 200}}]}]}, "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "ios-simulator.interactions-gesture.two", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "gesture", "gesturePlan": {"topology": "two", "intent": "pinch", "durationMs": 250, "viewport": {"x": 0, "y": 0, "width": 390, "height": 844}, "pointers": [{"pointerId": 0, "samples": [{"offsetMs": 0, "point": {"x": 150, "y": 422}}, {"offsetMs": 250, "point": {"x": 100, "y": 422}}]}, {"pointerId": 1, "samples": [{"offsetMs": 0, "point": {"x": 240, "y": 422}}, {"offsetMs": 250, "point": {"x": 290, "y": 422}}]}]}, "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "ios-simulator.interactions-long-press.duration", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "longPress", "x": 10, "y": 20, "durationMs": 600, "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "ios-simulator.interactions-press-series.double-tap", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "sequence", "steps": [{"kind": "doubleTap", "x": 10, "y": 20, "pauseMs": 50}, {"kind": "doubleTap", "x": 10, "y": 20}], "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "ios-simulator.interactions-press-series.long-press", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "sequence", "steps": [{"kind": "longPress", "x": 10, "y": 20, "durationMs": 600, "pauseMs": 50}, {"kind": "longPress", "x": 10, "y": 20, "durationMs": 600}], "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "ios-simulator.interactions-press-series.tap", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "sequence", "steps": [{"kind": "tap", "x": 10, "y": 20, "synthesized": true, "pauseMs": 50}, {"kind": "tap", "x": 10, "y": 20, "synthesized": true}], "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "ios-simulator.interactions-scroll.amount", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "scroll", "direction": "down", "amount": 0.65, "durationMs": 400, "scrollReleaseBehavior": "controlled", "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "ios-simulator.interactions-scroll.inertial", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "scroll", "direction": "left", "amount": 0.5, "durationMs": 400, "scrollReleaseBehavior": "inertial", "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "ios-simulator.interactions-scroll.pixels", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "scroll", "direction": "up", "pixels": 200, "durationMs": 300, "scrollReleaseBehavior": "controlled", "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "ios-simulator.interactions-single-press-double-tap.single", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "sequence", "steps": [{"kind": "doubleTap", "x": 10, "y": 20}], "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "ios-simulator.interactions-single-press-long-press.hold", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "longPress", "x": 10, "y": 20, "durationMs": 600, "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "ios-simulator.interactions-single-press-tap.synthesized", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "tap", "x": 10, "y": 20, "synthesized": true, "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "ios-simulator.interactions-tap-element-selector.expected-point", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "tap", "selectorKey": "label", "selectorValue": "Go", "allowNonHittableCoordinateFallback": true, "x": 10, "y": 20, "synthesized": true, "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "ios-simulator.interactions-tap.synthesized", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "tap", "x": 10, "y": 20, "synthesized": true, "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "ios-simulator.interactions-type.append", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "type", "text": "hello", "delayMs": 10, "textEntryMode": "append", "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "ios-simulator.interactions-type.newline", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "type", "text": "\n", "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "ios-simulator.interactor-action-button.press", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "actionButton", "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "ios-simulator.interactor-app-switcher.open", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "appSwitcher", "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "ios-simulator.interactor-back.in-app", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "backInApp", "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "ios-simulator.interactor-back.system", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "backSystem", "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "ios-simulator.interactor-find-text.text", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "findText", "text": "Ready", "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "ios-simulator.interactor-home.press", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "home", "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "ios-simulator.interactor-keyboard-dismiss.dismiss", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "keyboardDismiss", "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "ios-simulator.interactor-keyboard-enter.return", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "keyboardReturn", "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "ios-simulator.interactor-read-text.point", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "readText", "x": 10, "y": 20, "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "ios-simulator.interactor-set-orientation.rotate", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "rotate", "orientation": "landscape-left", "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "ios-simulator.interactor-snapshot.every-option", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "snapshot", "appBundleId": "com.example.app", "interactiveOnly": true, "preferredBackend": "tree", "customActions": true, "depth": 3, "scope": "Go", "raw": true, "commandId": "<commandId>"}},
+  {"name": "ios-simulator.recording-clock-anchor.snapshot", "producer": "src/__tests__/screen-recording-runner-requests.test.ts", "request": {"command": "snapshot", "appBundleId": "com.example.app", "interactiveOnly": true, "depth": 1}},
+  {"name": "ios-simulator.recording-start.default", "producer": "src/__tests__/screen-recording-runner-requests.test.ts", "request": {"command": "recordStart", "outPath": "capture.mp4", "appBundleId": "com.example.app"}},
+  {"name": "ios-simulator.runner-adoption.uptime", "producer": "packages/platform-apple/src/runner/__tests__/runner-requests.test.ts", "request": {"command": "uptime", "commandId": "<commandId>"}},
+  {"name": "ios-simulator.runner-client-prepare.uptime", "producer": "packages/platform-apple/src/runner/__tests__/runner-requests.test.ts", "request": {"command": "uptime", "commandId": "<commandId>"}},
+  {"name": "ios-simulator.runner-client-target-reset.relaunch", "producer": "packages/platform-apple/src/runner/__tests__/runner-requests.test.ts", "request": {"command": "targetReset", "commandId": "<commandId>"}},
+  {"name": "ios-simulator.runner-command-recovery.status", "producer": "packages/platform-apple/src/runner/__tests__/runner-requests.test.ts", "request": {"command": "status", "statusCommandId": "<commandId>"}},
+  {"name": "ios-simulator.runner-disposal.shutdown", "producer": "packages/platform-apple/src/runner/__tests__/runner-requests.test.ts", "request": {"command": "shutdown", "commandId": "<commandId>"}},
+  {"name": "ios-simulator.runner-lifecycle-prepare.uptime", "producer": "packages/platform-apple/src/runner/__tests__/runner-requests.test.ts", "request": {"command": "uptime", "commandId": "<commandId>"}},
+  {"name": "ios-simulator.runner-selector-query.label", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "querySelector", "selectorKey": "label", "selectorValue": "Go", "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "ios-simulator.runner-session-readiness.uptime", "producer": "packages/platform-apple/src/runner/__tests__/runner-requests.test.ts", "request": {"command": "uptime", "commandId": "<commandId>"}},
+  {"name": "macos.desktop-scroll.amount", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "desktopScroll", "direction": "down", "amount": 0.5, "durationMs": 300, "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "macos.desktop-scroll.pixels", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "desktopScroll", "direction": "up", "pixels": 200, "durationMs": 300, "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "macos.interactions-drag.single", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "drag", "x": 100, "y": 400, "x2": 100, "y2": 200, "durationMs": 120, "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "macos.interactions-focus.coordinate", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "tap", "x": 10, "y": 20, "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "macos.interactions-mouse-click.middle", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "mouseClick", "x": 10, "y": 20, "button": "middle", "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "macos.interactions-mouse-click.secondary", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "mouseClick", "x": 10, "y": 20, "button": "secondary", "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "macos.interactions-single-press-tap.coordinate", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "tap", "x": 10, "y": 20, "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "macos.interactions-tap.coordinate", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "tap", "x": 10, "y": 20, "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "macos.recording-start.output-path", "producer": "src/__tests__/screen-recording-runner-requests.test.ts", "request": {"command": "recordStart", "outPath": "/tmp/capture.mp4", "appBundleId": "com.example.app"}},
+  {"name": "macos.screenshot-runner.fullscreen", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "screenshot", "appBundleId": "com.example.app", "fullscreen": true, "inlineScreenshot": false, "commandId": "<commandId>"}},
+  {"name": "tvos.interactions-scroll.remote-press", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "remotePress", "remoteButton": "down", "durationMs": 300, "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "tvos.interactions-swipe.single", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "swipe", "direction": "up", "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "tvos.interactor-back.remote-press", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "remotePress", "remoteButton": "menu", "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "tvos.interactor-home.remote-press", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "remotePress", "remoteButton": "home", "appBundleId": "com.example.app", "commandId": "<commandId>"}},
+  {"name": "tvos.interactor-tv-remote.hold", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "remotePress", "remoteButton": "select", "durationMs": 500, "appBundleId": "com.example.app", "commandId": "<commandId>"}}
+]
diff --git a/packages/platform-apple/package.json b/packages/platform-apple/package.json
index b1a9cc3868..acc2bd7c19 100644
--- a/packages/platform-apple/package.json
+++ b/packages/platform-apple/package.json
@@ -64,6 +64,10 @@
       "types": "./src/runner-operations-facade.ts",
       "default": "./src/runner-operations-facade.ts"
     },
+    "./runner/requests-fixtures": {
+      "types": "./src/runner/runner-requests.fixtures.ts",
+      "default": "./src/runner/runner-requests.fixtures.ts"
+    },
     "./runner/test-host": {
       "types": "./src/runner/test-host.ts",
       "default": "./src/runner/test-host.ts"
diff --git a/packages/platform-apple/src/__tests__/interactor-runner-provider.test.ts b/packages/platform-apple/src/__tests__/interactor-runner-provider.test.ts
index d0106f3392..80589e957c 100644
--- a/packages/platform-apple/src/__tests__/interactor-runner-provider.test.ts
+++ b/packages/platform-apple/src/__tests__/interactor-runner-provider.test.ts
@@ -1,4 +1,3 @@
-import type { GesturePlan } from '@agent-device/contracts/gesture-plan-types';
 import type {
   Interactor,
   RunnerContext,
@@ -9,14 +8,14 @@ import { AppError } from '@agent-device/kernel/errors';
 import assert from 'node:assert/strict';
 import { test } from 'vitest';
 import { IOS_SIMULATOR, MACOS_DEVICE } from './device-fixtures.ts';
-import type {
-  AppleRunnerCommandOptions,
-  AppleRunnerProvider,
-  RunnerCommand,
-} from '../runner/index.ts';
+import type { AppleRunnerProvider } from '../runner/index.ts';
 import { createAppleInteractor } from '../interactor.ts';
-
-type RecordedRunnerCall = { command: RunnerCommand; options: AppleRunnerCommandOptions };
+import {
+  recordingRunnerProvider,
+  runnerResultFor,
+  singlePointerPanPlan,
+  type RecordedRunnerCall,
+} from './recording-runner-provider.ts';
 
 function presentedSnapshot(result: SnapshotRuntimeResult): SnapshotResult {
   if ('stage' in result) throw new Error('Apple runner snapshot must be presented');
@@ -446,57 +445,3 @@ test('snapshot forwards either forceable preferredBackend into the emitted runne
   assert.equal(snapshots[0]?.command.preferredBackend, 'tree');
   assert.equal(snapshots[1]?.command.preferredBackend, undefined);
 });
-
-function recordingRunnerProvider(calls: RecordedRunnerCall[]): AppleRunnerProvider {
-  return {
-    hasLiveSession: () => true,
-    runCommand: async (_device, command, options) => {
-      calls.push({ command, options });
-      return runnerResultFor(command);
-    },
-  };
-}
-
-function runnerResultFor(command: RunnerCommand): Record<string, unknown> {
-  switch (command.command) {
-    case 'snapshot':
-      return {
-        nodes: [
-          { index: 0, type: 'Application', rect: { x: 0, y: 0, width: 390, height: 844 } },
-          {
-            index: 1,
-            parentIndex: 0,
-            type: 'Button',
-            label: 'Go',
-            hittable: true,
-            rect: { x: 10, y: 10, width: 80, height: 40 },
-          },
-        ],
-      };
-    case 'gestureViewport':
-      return { x: 0, y: 0, x2: 390, y2: 844 };
-    case 'rotate':
-      return { orientation: command.orientation };
-    default:
-      return {};
-  }
-}
-
-function singlePointerPanPlan(): GesturePlan {
-  return {
-    topology: 'single',
-    intent: 'pan',
-    executionProfile: 'timed-pan',
-    durationMs: 120,
-    viewport: { x: 0, y: 0, width: 390, height: 844 },
-    pointers: [
-      {
-        pointerId: 0,
-        samples: [
-          { offsetMs: 0, point: { x: 100, y: 400 } },
-          { offsetMs: 120, point: { x: 100, y: 200 } },
-        ],
-      },
-    ],
-  };
-}
diff --git a/packages/platform-apple/src/__tests__/recording-runner-provider.ts b/packages/platform-apple/src/__tests__/recording-runner-provider.ts
new file mode 100644
index 0000000000..5c97b0745b
--- /dev/null
+++ b/packages/platform-apple/src/__tests__/recording-runner-provider.ts
@@ -0,0 +1,72 @@
+import type { GesturePlan } from '@agent-device/contracts/gesture-plan-types';
+import type {
+  AppleRunnerCommandOptions,
+  AppleRunnerProvider,
+  RunnerCommand,
+} from '../runner/index.ts';
+
+export type RecordedRunnerCall = Readonly<{
+  command: RunnerCommand;
+  options: AppleRunnerCommandOptions;
+}>;
+
+/** A runner transport that answers every command with a minimal valid result and records it. */
+export function recordingRunnerProvider(
+  calls: RecordedRunnerCall[],
+  results: Partial<Record<RunnerCommand['command'], Record<string, unknown>>> = {},
+): AppleRunnerProvider {
+  return {
+    hasLiveSession: () => true,
+    runCommand: async (_device, command, options) => {
+      calls.push({ command, options });
+      return results[command.command] ?? runnerResultFor(command);
+    },
+  };
+}
+
+export function runnerResultFor(sent: Pick<RunnerCommand, 'command' | 'orientation'>) {
+  switch (sent.command) {
+    case 'snapshot':
+      return {
+        nodes: [
+          { index: 0, type: 'Application', rect: { x: 0, y: 0, width: 390, height: 844 } },
+          {
+            index: 1,
+            parentIndex: 0,
+            type: 'Button',
+            label: 'Go',
+            hittable: true,
+            rect: { x: 10, y: 10, width: 80, height: 40 },
+          },
+        ],
+      };
+    case 'gestureViewport':
+      return { x: 0, y: 0, x2: 390, y2: 844 };
+    case 'rotate':
+      return { orientation: sent.orientation };
+    case 'scroll':
+    case 'desktopScroll':
+      return { referenceWidth: 390, referenceHeight: 844 };
+    default:
+      return {};
+  }
+}
+
+export function singlePointerPanPlan(): GesturePlan {
+  return {
+    topology: 'single',
+    intent: 'pan',
+    executionProfile: 'timed-pan',
+    durationMs: 120,
+    viewport: { x: 0, y: 0, width: 390, height: 844 },
+    pointers: [
+      {
+        pointerId: 0,
+        samples: [
+          { offsetMs: 0, point: { x: 100, y: 400 } },
+          { offsetMs: 120, point: { x: 100, y: 200 } },
+        ],
+      },
+    ],
+  };
+}
diff --git a/packages/platform-apple/src/__tests__/runner-requests.test.ts b/packages/platform-apple/src/__tests__/runner-requests.test.ts
new file mode 100644
index 0000000000..f471daa08d
--- /dev/null
+++ b/packages/platform-apple/src/__tests__/runner-requests.test.ts
@@ -0,0 +1,266 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { test } from 'vitest';
+import type { GesturePlan } from '@agent-device/contracts/gesture-plan-types';
+import type { Interactor, PressPointOptions } from '@agent-device/contracts/interactor-types';
+import type { DeviceInfo } from '@agent-device/kernel/device';
+import { createAppleInteractor } from '../interactor.ts';
+import { resolveIosPhysicalDeviceControl } from '../core/physical-device-control.ts';
+import { runAppleRunnerCommand } from '../core/runner-client.ts';
+import { queryAppleRunnerSelector } from '../core/runner-selector-query.ts';
+import { captureScreenshotViaRunner } from '../core/screenshot.ts';
+import { withAppleRunnerProvider, type RunnerCommand } from '../runner/index.ts';
+import {
+  IOS_DEVICE,
+  IOS_SIMULATOR,
+  MACOS_DEVICE,
+  TVOS_SIMULATOR,
+} from '../runner/__tests__/device-fixtures.ts';
+import { assertProducedRunnerRequests } from '../runner/runner-requests.fixtures.ts';
+import {
+  recordingRunnerProvider,
+  singlePointerPanPlan,
+  type RecordedRunnerCall,
+} from './recording-runner-provider.ts';
+import { mkdtempForTest } from './tmp-dir.ts';
+
+// Every Apple runner request site outside `runner/`, driven through its production entry point and
+// pinned to contracts/fixtures/runner-requests.json. The drives never write a request themselves;
+// runner/__tests__/runner-requests.test.ts reads this source to keep it that way.
+
+const APP = 'com.example.app';
+const XCTEST_DEVICE: DeviceInfo = { ...IOS_DEVICE, iosPhysicalDeviceBackend: 'xctest' };
+
+type InteractorDrive = readonly [DeviceInfo, (interactor: Interactor) => Promise<unknown>];
+
+function press(overrides: Partial<PressPointOptions> = {}) {
+  return (interactor: Interactor) =>
+    interactor.pressPoint!(
+      { x: 10, y: 20 },
+      {
+        button: 'primary',
+        count: 1,
+        intervalMs: 0,
+        holdMs: 0,
+        jitterPx: 0,
+        doubleTap: false,
+        ...overrides,
+      },
+    );
+}
+
+const INTERACTOR_SITES: Record<string, InteractorDrive> = {
+  'ios-simulator.interactions-tap.synthesized': [IOS_SIMULATOR, (i) => i.tap(10, 20)],
+  'macos.interactions-tap.coordinate': [MACOS_DEVICE, (i) => i.tap(10, 20)],
+  'ios-simulator.interactions-focus.synthesized': [IOS_SIMULATOR, (i) => i.focus(10, 20)],
+  'macos.interactions-focus.coordinate': [MACOS_DEVICE, (i) => i.focus(10, 20)],
+  'ios-simulator.interactions-single-press-tap.synthesized': [IOS_SIMULATOR, press()],
+  'macos.interactions-single-press-tap.coordinate': [MACOS_DEVICE, press()],
+  'ios-simulator.interactions-tap-element-selector.expected-point': [
+    IOS_SIMULATOR,
+    (i) =>
+      i.tapElementSelector!({
+        key: 'label',
+        value: 'Go',
+        allowNonHittableCoordinateFallback: true,
+        expectedPoint: { x: 10, y: 20 },
+      }),
+  ],
+  'ios-simulator.interactions-double-tap.single': [IOS_SIMULATOR, (i) => i.doubleTap!(10, 20)],
+  'ios-simulator.interactions-long-press.duration': [
+    IOS_SIMULATOR,
+    (i) => i.longPress(10, 20, 600),
+  ],
+  'ios-simulator.interactions-type.append': [IOS_SIMULATOR, (i) => i.type('hello', 10)],
+  'ios-simulator.interactions-type.newline': [IOS_SIMULATOR, (i) => i.type('\n')],
+  'ios-simulator.interactions-fill.replace': [IOS_SIMULATOR, (i) => i.fill(10, 20, 'hello', 10)],
+  'ios-simulator.interactions-fill.non-hittable-fallback': [
+    IOS_SIMULATOR,
+    (i) => i.fill(10, 20, 'hello', undefined, { allowNonHittableCoordinateFallback: true }),
+  ],
+  'ios-simulator.interactions-gesture-viewport.read': [IOS_SIMULATOR, (i) => i.gestureViewport!()],
+  'ios-simulator.interactions-press-series.tap': [
+    IOS_SIMULATOR,
+    press({ count: 2, intervalMs: 50 }),
+  ],
+  'ios-simulator.interactions-press-series.double-tap': [
+    IOS_SIMULATOR,
+    press({ count: 2, intervalMs: 50, doubleTap: true }),
+  ],
+  'ios-simulator.interactions-press-series.long-press': [
+    IOS_SIMULATOR,
+    press({ count: 2, intervalMs: 50, holdMs: 600 }),
+  ],
+  'macos.interactions-mouse-click.secondary': [MACOS_DEVICE, press({ button: 'secondary' })],
+  'macos.interactions-mouse-click.middle': [MACOS_DEVICE, press({ button: 'middle' })],
+  'ios-simulator.interactions-single-press-double-tap.single': [
+    IOS_SIMULATOR,
+    press({ doubleTap: true }),
+  ],
+  'ios-simulator.interactions-single-press-long-press.hold': [
+    IOS_SIMULATOR,
+    press({ holdMs: 600 }),
+  ],
+  'macos.interactions-drag.single': [
+    MACOS_DEVICE,
+    (i) => i.performGesture!(singlePointerPanPlan()),
+  ],
+  'tvos.interactions-swipe.single': [
+    TVOS_SIMULATOR,
+    (i) => i.performGesture!(singlePointerPanPlan()),
+  ],
+  'ios-simulator.interactions-gesture.single': [
+    IOS_SIMULATOR,
+    (i) => i.performGesture!(singlePointerPanPlan()),
+  ],
+  'ios-simulator.interactions-gesture.two': [IOS_SIMULATOR, (i) => i.performGesture!(pinchPlan())],
+  'tvos.interactions-scroll.remote-press': [
+    TVOS_SIMULATOR,
+    (i) => i.scroll('down', { durationMs: 300 }),
+  ],
+  'ios-simulator.interactions-scroll.amount': [IOS_SIMULATOR, (i) => i.scroll('down')],
+  'ios-simulator.interactions-scroll.pixels': [
+    IOS_SIMULATOR,
+    (i) => i.scroll('up', { pixels: 200, durationMs: 300 }),
+  ],
+  'ios-simulator.interactions-scroll.inertial': [
+    IOS_SIMULATOR,
+    (i) => i.scroll('left', { amount: 0.5, releaseBehavior: 'inertial' }),
+  ],
+  'macos.desktop-scroll.amount': [
+    MACOS_DEVICE,
+    (i) => i.scroll('down', { amount: 0.5, durationMs: 300 }),
+  ],
+  'macos.desktop-scroll.pixels': [
+    MACOS_DEVICE,
+    (i) => i.scroll('up', { pixels: 200, durationMs: 300 }),
+  ],
+  'ios-simulator.interactor-find-text.text': [
+    IOS_SIMULATOR,
+    (i) => i.findText!('Ready', { appBundleId: APP }),
+  ],
+  'tvos.interactor-back.remote-press': [TVOS_SIMULATOR, (i) => i.back()],
+  'ios-simulator.interactor-back.in-app': [IOS_SIMULATOR, (i) => i.back()],
+  'ios-simulator.interactor-back.system': [IOS_SIMULATOR, (i) => i.back('system')],
+  'tvos.interactor-home.remote-press': [TVOS_SIMULATOR, (i) => i.home!()],
+  'ios-simulator.interactor-home.press': [IOS_SIMULATOR, (i) => i.home!()],
+  'ios-simulator.interactor-set-orientation.rotate': [
+    IOS_SIMULATOR,
+    (i) => i.setOrientation('landscape-left'),
+  ],
+  'ios-simulator.interactor-app-switcher.open': [IOS_SIMULATOR, (i) => i.appSwitcher!()],
+  'ios-simulator.interactor-action-button.press': [IOS_SIMULATOR, (i) => i.actionButton!()],
+  'tvos.interactor-tv-remote.hold': [TVOS_SIMULATOR, (i) => i.tvRemote!('select', 500)],
+  'ios-simulator.interactor-keyboard-dismiss.dismiss': [IOS_SIMULATOR, (i) => i.keyboardDismiss!()],
+  'ios-simulator.interactor-keyboard-enter.return': [IOS_SIMULATOR, (i) => i.keyboardEnter!()],
+  'ios-simulator.interactor-snapshot.every-option': [
+    IOS_SIMULATOR,
+    (i) =>
+      i.snapshot({
+        appBundleId: APP,
+        interactiveOnly: true,
+        preferredBackend: 'tree',
+        customActions: true,
+        depth: 3,
+        scope: 'Go',
+        raw: true,
+      }),
+  ],
+  'ios-simulator.interactor-read-text.point': [
+    IOS_SIMULATOR,
+    (i) => i.readTextAtPoint!({ x: 10, y: 20 }, { appBundleId: APP }),
+  ],
+  'ios-simulator.alert.get': [IOS_SIMULATOR, (i) => i.readAlert!({ appBundleId: APP })],
+  'ios-simulator.alert.accept': [IOS_SIMULATOR, (i) => i.acceptAlert!({ appBundleId: APP })],
+  'ios-simulator.alert.dismiss': [IOS_SIMULATOR, (i) => i.dismissAlert!({ appBundleId: APP })],
+};
+
+type ScopedDrive = readonly [DeviceInfo, (outPath: string) => Promise<unknown>];
+
+const SCOPED_SITES: Record<string, ScopedDrive> = {
+  'ios-simulator.runner-selector-query.label': [
+    IOS_SIMULATOR,
+    () => queryAppleRunnerSelector(IOS_SIMULATOR, { key: 'label', value: 'Go' }, APP, {}),
+  ],
+  'macos.screenshot-runner.fullscreen': [
+    MACOS_DEVICE,
+    (outPath) => captureScreenshotViaRunner(MACOS_DEVICE, outPath, APP, true),
+  ],
+  'ios-device.physical-device-screenshot.coredevice-file': [
+    IOS_DEVICE,
+    (outPath) => captureScreenshotViaRunner(IOS_DEVICE, outPath, APP, true),
+  ],
+  'ios-device.physical-device-screenshot.xctest-inline': [
+    XCTEST_DEVICE,
+    (outPath) => captureScreenshotViaRunner(XCTEST_DEVICE, outPath, APP),
+  ],
+  'ios-device.physical-device-control.activate': [
+    XCTEST_DEVICE,
+    () =>
+      resolveIosPhysicalDeviceControl(XCTEST_DEVICE).launchApp(XCTEST_DEVICE, APP, {
+        runRunnerCommand: runAppleRunnerCommand,
+      }),
+  ],
+  'ios-device.physical-device-control.terminate': [
+    XCTEST_DEVICE,
+    () =>
+      resolveIosPhysicalDeviceControl(XCTEST_DEVICE).terminateApp(XCTEST_DEVICE, APP, {
+        runRunnerCommand: runAppleRunnerCommand,
+      }),
+  ],
+};
+
+test('every Apple request site builds exactly its golden runner request', async () => {
+  const captured: Array<readonly [string, RunnerCommand]> = [];
+  for (const [name, [device, drive]] of Object.entries(INTERACTOR_SITES)) {
+    const calls: RecordedRunnerCall[] = [];
+    await drive(
+      createAppleInteractor(device, { appBundleId: APP }, recordingRunnerProvider(calls)),
+    );
+    captured.push([name, onlyRequest(name, calls)]);
+  }
+  const dir = await mkdtempForTest('agent-device-runner-requests-');
+  const runnerScreenshot = path.join(dir, 'runner.png');
+  fs.writeFileSync(runnerScreenshot, '');
+  for (const [name, [device, drive]] of Object.entries(SCOPED_SITES)) {
+    const calls: RecordedRunnerCall[] = [];
+    const provider = recordingRunnerProvider(calls, {
+      screenshot: { message: runnerScreenshot, imageBase64: 'AA==' },
+    });
+    await withAppleRunnerProvider(provider, { deviceId: device.id }, () =>
+      drive(path.join(dir, `${name}.png`)),
+    );
+    captured.push([name, onlyRequest(name, calls)]);
+  }
+  assertProducedRunnerRequests(import.meta.filename, captured);
+});
+
+function onlyRequest(name: string, calls: RecordedRunnerCall[]): RunnerCommand {
+  if (calls.length !== 1) throw new Error(`${name} sent ${calls.length} runner requests`);
+  return calls[0]!.command;
+}
+
+function pinchPlan(): GesturePlan {
+  return {
+    topology: 'two',
+    intent: 'pinch',
+    durationMs: 250,
+    viewport: { x: 0, y: 0, width: 390, height: 844 },
+    pointers: [
+      {
+        pointerId: 0,
+        samples: [
+          { offsetMs: 0, point: { x: 150, y: 422 } },
+          { offsetMs: 250, point: { x: 100, y: 422 } },
+        ],
+      },
+      {
+        pointerId: 1,
+        samples: [
+          { offsetMs: 0, point: { x: 240, y: 422 } },
+          { offsetMs: 250, point: { x: 290, y: 422 } },
+        ],
+      },
+    ],
+  };
+}
diff --git a/packages/platform-apple/src/runner/__tests__/runner-requests.test.ts b/packages/platform-apple/src/runner/__tests__/runner-requests.test.ts
new file mode 100644
index 0000000000..bb6a13fda8
--- /dev/null
+++ b/packages/platform-apple/src/runner/__tests__/runner-requests.test.ts
@@ -0,0 +1,176 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { afterEach, beforeEach, test, vi } from 'vitest';
+import { tryAdoptRunnerSessionFromLease } from '../runner-adoption.ts';
+import { notifyIosRunnerAppRelaunched, prepareIosRunner } from '../runner-client.ts';
+import { RUNNER_COMMAND_TRAITS } from '../runner-command-traits.ts';
+import type { RunnerCommand } from '../runner-contract.ts';
+import { disposeRunnerSession } from '../runner-disposal.ts';
+import { buildRunnerLease, writeRunnerLease } from '../runner-lease.ts';
+import { executeRunnerCommand, prepareLocalIosRunner } from '../runner-lifecycle.ts';
+import { withAppleRunnerProvider } from '../runner-provider.ts';
+import {
+  assertProducedRunnerRequests,
+  readRunnerRequestFixture,
+  REPO_ROOT,
+} from '../runner-requests.fixtures.ts';
+import { runApplePressSeries } from '../runner-sequence.ts';
+import { appleRunnerTestHost } from '../test-host.ts';
+import { IOS_SIMULATOR } from './device-fixtures.ts';
+import { startFakeRunnerServer, type FakeRunnerServer } from './fake-runner-server.ts';
+import { makeRunnerSession } from './runner-session-fixtures.ts';
+import { mkdtempForTestSync } from './tmp-dir.ts';
+
+const runnerState = vi.hoisted(() => ({ ensureRunnerSession: vi.fn(), derivedPath: '' }));
+
+vi.mock('../runner-session.ts', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('../runner-session.ts')>()),
+  ensureRunnerSession: runnerState.ensureRunnerSession,
+}));
+
+vi.mock('../runner-xctestrun.ts', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('../runner-xctestrun.ts')>()),
+  resolveExpectedRunnerCacheMetadata: () => ({}),
+  resolveRunnerDerivedPath: () => runnerState.derivedPath,
+}));
+
+const APP = 'com.example.app';
+
+let server: FakeRunnerServer | undefined;
+let scratch: string;
+
+beforeEach(() => {
+  scratch = mkdtempForTestSync('agent-device-runner-contract-');
+  runnerState.derivedPath = path.join(scratch, 'derived');
+  process.env.AGENT_DEVICE_IOS_RUNNER_LEASE_DIR = path.join(scratch, 'leases');
+});
+
+afterEach(async () => {
+  delete process.env.AGENT_DEVICE_IOS_RUNNER_LEASE_DIR;
+  await server?.close();
+  server = undefined;
+});
+
+test('runner-internal request sites build exactly their runner-requests.json entries', async () => {
+  const sent: RunnerCommand[] = [];
+  await withAppleRunnerProvider(
+    async (_device, request) => {
+      sent.push(request);
+      return {};
+    },
+    { deviceId: IOS_SIMULATOR.id },
+    async () => await prepareIosRunner(IOS_SIMULATOR, { healthTimeoutMs: 1_000 }),
+  );
+
+  server = await startFakeRunnerServer({
+    targetReset: [{ kind: 'hangUp' }],
+    status: [
+      {
+        kind: 'ok',
+        data: { lifecycleState: 'completed', lifecycleResponseJson: '{"ok":true,"data":{}}' },
+      },
+    ],
+  });
+  const session = makeRunnerSession({
+    port: server.port,
+    xctestrunPath: path.join(scratch, 'runner.xctestrun'),
+    jsonPath: path.join(scratch, 'runner.json'),
+  });
+  runnerState.ensureRunnerSession.mockResolvedValue(session);
+  appleRunnerTestHost.update({
+    isProcessAlive: () => false,
+    isProcessGroupAlive: () => false,
+    runXcrun: async () => ({ exitCode: 0, stdout: '', stderr: '' }),
+  });
+  await prepareLocalIosRunner(IOS_SIMULATOR, { healthTimeoutMs: 5_000 });
+  await runApplePressSeries(
+    IOS_SIMULATOR,
+    { x: 10, y: 20 },
+    { button: 'primary', count: 2, intervalMs: 0, holdMs: 0, jitterPx: 0, doubleTap: false },
+    APP,
+    async (request) => await executeRunnerCommand(IOS_SIMULATOR, request, {}),
+  );
+  await notifyIosRunnerAppRelaunched(IOS_SIMULATOR);
+  await disposeRunnerSession(session);
+
+  appleRunnerTestHost.update({
+    isProcessAlive: () => true,
+    readProcessCommand: () => null,
+    readProcessStartTime: () => 'test-process-start',
+  });
+  writeRunnerLease({
+    ...buildRunnerLease({
+      deviceId: IOS_SIMULATOR.id,
+      sessionId: `${IOS_SIMULATOR.id}:${server.port}:1`,
+      runnerPid: 424242,
+      port: server.port,
+      xctestrunPath: path.join(runnerState.derivedPath, 'Build', 'Products', 'r.xctestrun'),
+      jsonPath: path.join(runnerState.derivedPath, 'Build', 'Products', 'r.json'),
+    }),
+    ownerToken: 'owner-99999-deadbeef',
+    ownerPid: 99999,
+    ownerStartTime: 'not-a-real-start-time',
+  });
+  assert.ok(await tryAdoptRunnerSessionFromLease(IOS_SIMULATOR, {}), 'the lease was not adopted');
+
+  const received = server.requests.map((request) => request.body);
+  assert.deepEqual(
+    received.map((request) => request.command),
+    ['uptime', 'uptime', 'sequence', 'targetReset', 'status', 'shutdown', 'uptime'],
+  );
+  assertProducedRunnerRequests(import.meta.filename, [
+    ['ios-simulator.runner-client-prepare.uptime', sent[0]],
+    ['ios-simulator.runner-lifecycle-prepare.uptime', received[0]],
+    ['ios-simulator.runner-session-readiness.uptime', received[1]],
+    ['ios-simulator.runner-client-target-reset.relaunch', received[3]],
+    ['ios-simulator.runner-command-recovery.status', received[4]],
+    ['ios-simulator.runner-disposal.shutdown', received[5]],
+    ['ios-simulator.runner-adoption.uptime', received[6]],
+  ]);
+});
+
+test('runner-requests.json has a production request for every runner command', () => {
+  const entries = readRunnerRequestFixture();
+  const names = entries.map((entry) => entry.name);
+  assert.deepEqual(names, [...new Set(names)].sort());
+  const produced = new Set(entries.map((entry) => entry.request.command));
+  assert.deepEqual(
+    Object.keys(RUNNER_COMMAND_TRAITS).filter((name) => !produced.has(name)),
+    [],
+    'runner commands with no production request',
+  );
+  for (const producer of new Set(entries.map((entry) => entry.producer))) {
+    const source = fs.readFileSync(path.join(REPO_ROOT, producer), 'utf8');
+    assert.ok(
+      producer.endsWith('runner-requests.test.ts') &&
+        source.includes('assertProducedRunnerRequests(import.meta.filename'),
+      `${producer} must be a dedicated *runner-requests.test.ts drive that checks its own entries`,
+    );
+  }
+});
+
+const REQUEST_LITERAL = /\bcommand\s*:(?!\s*RunnerCommand\b)/;
+const DIRECT_SEND = new RegExp(
+  `\\b(?:${['runAppleRunnerCommand', 'executeRunnerCommandWithSession', 'waitForRunner', 'sendRunnerCommandOnce'].join('|')})\\s*\\(`,
+);
+
+test('runner request drives send only requests production builds', () => {
+  const producers = readRunnerRequestFixture().map((entry) => path.join(REPO_ROOT, entry.producer));
+  const sources = [
+    ...new Set(producers),
+    path.join(import.meta.dirname, '../runner-requests.fixtures.ts'),
+    path.join(import.meta.dirname, '../../__tests__/recording-runner-provider.ts'),
+  ];
+  const offending = sources.flatMap((file) =>
+    fs
+      .readFileSync(file, 'utf8')
+      .split('\n')
+      .flatMap((line, index) =>
+        REQUEST_LITERAL.test(line) || DIRECT_SEND.test(line)
+          ? [`${path.relative(REPO_ROOT, file)}:${index + 1}: ${line.trim()}`]
+          : [],
+      ),
+  );
+  assert.deepEqual(offending, []);
+});
diff --git a/packages/platform-apple/src/runner/runner-requests.fixtures.ts b/packages/platform-apple/src/runner/runner-requests.fixtures.ts
new file mode 100644
index 0000000000..379f468048
--- /dev/null
+++ b/packages/platform-apple/src/runner/runner-requests.fixtures.ts
@@ -0,0 +1,47 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export type RunnerRequestEntry = {
+  name: string;
+  producer: string;
+  request: Record<string, unknown>;
+};
+
+export const REPO_ROOT = fileURLToPath(new URL('../../../../', import.meta.url));
+
+const COMMAND_ID_KEYS = ['commandId', 'statusCommandId'];
+
+export function readRunnerRequestFixture(): RunnerRequestEntry[] {
+  return JSON.parse(
+    fs.readFileSync(path.join(REPO_ROOT, 'contracts/fixtures/runner-requests.json'), 'utf8'),
+  ) as RunnerRequestEntry[];
+}
+
+/** The request as the wire carries it, with the random command ids pinned. */
+function wireRunnerRequest(sent: unknown): Record<string, unknown> {
+  const request = JSON.parse(JSON.stringify(sent)) as Record<string, unknown>;
+  for (const key of COMMAND_ID_KEYS) {
+    if (key in request) request[key] = '<commandId>';
+  }
+  return request;
+}
+
+/**
+ * Pins the requests one producer test captured, by site name, to that producer's fixture entries.
+ * On a mismatch the diff shows the entries to paste into the fixture.
+ */
+export function assertProducedRunnerRequests(
+  producerFile: string,
+  captured: ReadonlyArray<readonly [name: string, sent: unknown]>,
+): void {
+  const producer = path.relative(REPO_ROOT, producerFile);
+  const produced = captured
+    .map(([name, sent]) => ({ name, producer, request: wireRunnerRequest(sent) }))
+    .sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0));
+  assert.deepEqual(
+    produced,
+    readRunnerRequestFixture().filter((entry) => entry.producer === producer),
+  );
+}
diff --git a/scripts/layering/package-boundaries.test.ts b/scripts/layering/package-boundaries.test.ts
index d852129882..222b622719 100644
--- a/scripts/layering/package-boundaries.test.ts
+++ b/scripts/layering/package-boundaries.test.ts
@@ -541,6 +541,8 @@ test('the real tree parses, declares, and passes R11', () => {
     '@agent-device/platform-apple/runner',
     '@agent-device/platform-apple/runner-owner',
     '@agent-device/platform-apple/runner/operations',
+    // Test-only entry: the runner-requests.json check package and root tests share.
+    '@agent-device/platform-apple/runner/requests-fixtures',
     '@agent-device/platform-apple/runner/test-host',
     '@agent-device/platform-apple/session-observation',
     '@agent-device/platform-apple/simctl',
diff --git a/scripts/layering/platform-package-policy.test.ts b/scripts/layering/platform-package-policy.test.ts
index 0ca48d2802..4daad31e92 100644
--- a/scripts/layering/platform-package-policy.test.ts
+++ b/scripts/layering/platform-package-policy.test.ts
@@ -38,6 +38,7 @@ function declarations(): PlatformPackageDeclaration[] {
             '@agent-device/platform-apple/runner',
             '@agent-device/platform-apple/runner/test-host',
             '@agent-device/platform-apple/runner/operations',
+            '@agent-device/platform-apple/runner/requests-fixtures',
             '@agent-device/platform-apple/runner-owner',
             '@agent-device/platform-apple/session-observation',
             '@agent-device/platform-apple/simctl',
diff --git a/scripts/layering/platform-package-policy.ts b/scripts/layering/platform-package-policy.ts
index 6b50f48f70..6d6b1a055d 100644
--- a/scripts/layering/platform-package-policy.ts
+++ b/scripts/layering/platform-package-policy.ts
@@ -86,6 +86,7 @@ const MECHANICS_FACET_SUBPATHS: Readonly<Partial<Record<PlatformFamily, readonly
     '@agent-device/platform-apple/physical-device',
     '@agent-device/platform-apple/runner-owner',
     '@agent-device/platform-apple/runner/operations',
+    '@agent-device/platform-apple/runner/requests-fixtures',
     '@agent-device/platform-apple/session-observation',
     '@agent-device/platform-apple/snapshot-source',
     '@agent-device/platform-apple/simctl',
diff --git a/src/__tests__/screen-recording-runner-requests.test.ts b/src/__tests__/screen-recording-runner-requests.test.ts
new file mode 100644
index 0000000000..c33871fbbc
--- /dev/null
+++ b/src/__tests__/screen-recording-runner-requests.test.ts
@@ -0,0 +1,72 @@
+import { expect, test, vi } from 'vitest';
+import { assertProducedRunnerRequests } from '@agent-device/platform-apple/runner/requests-fixtures';
+import { captureAppleClockAnchor } from '../platform-runtime-screen-recording-apple-runner-host.ts';
+import { resolveAppleRunnerScreenRecordingTransport } from '../platform-runtime-screen-recording-apple-runner-transport.ts';
+
+const runner = vi.hoisted(() => ({ run: vi.fn(), snapshot: vi.fn() }));
+
+vi.mock('@agent-device/platform-apple/runner/operations', () => ({
+  runAppleRunnerCommand: runner.run,
+  readRunnerSessionLiveness: runner.snapshot,
+}));
+
+const device = {
+  platform: 'apple' as const,
+  appleOs: 'ios' as const,
+  id: 'device',
+  name: 'iPhone',
+  kind: 'device' as const,
+  target: 'mobile' as const,
+  booted: true,
+};
+const simulator = { ...device, kind: 'simulator' as const, id: 'sim' };
+const macosDevice = {
+  ...device,
+  appleOs: 'macos' as const,
+  id: 'host-macos-local',
+  name: 'Mac',
+  target: 'desktop' as const,
+};
+
+test('screen recording runner requests match their runner-requests.json entries', async () => {
+  runner.snapshot.mockReturnValue({ sessionId: 'runner-session-1', liveness: 'ready' });
+  runner.run.mockResolvedValue({});
+  const transport = resolveAppleRunnerScreenRecordingTransport();
+  const request = { appBundleId: 'com.example.app', outputPath: '/tmp/capture.mp4' };
+
+  vi.setSystemTime(1_700_000_000_000);
+  try {
+    await transport.start({ ...request, device, fps: 30 });
+  } finally {
+    vi.useRealTimers();
+  }
+  await transport.start({ ...request, device: simulator });
+  await transport.start({ ...request, device: macosDevice });
+  await transport.stop({
+    device,
+    runnerSessionId: 'runner-session-1',
+    appBundleId: 'com.example.app',
+  });
+  await transport.stop({ device, runnerSessionId: 'runner-session-1' });
+  const controller = new AbortController();
+  const reason = new Error('cancel after runner acquisition');
+  runner.snapshot.mockImplementationOnce(() => {
+    controller.abort(reason);
+    return { sessionId: 'runner-session-2', liveness: 'ready' };
+  });
+  await expect(transport.start({ ...request, device, signal: controller.signal })).rejects.toBe(
+    reason,
+  );
+  await captureAppleClockAnchor(simulator, 'com.example.app');
+
+  const sent = runner.run.mock.calls.map((call) => call[1]);
+  assertProducedRunnerRequests(import.meta.filename, [
+    ['ios-device.recording-start.fps', sent[0]],
+    ['ios-simulator.recording-start.default', sent[1]],
+    ['macos.recording-start.output-path', sent[2]],
+    ['ios-device.recording-stop.session', sent[3]],
+    ['ios-device.recording-stop.no-app', sent[4]],
+    ['ios-device.recording-start-abort.stop', sent[6]],
+    ['ios-simulator.recording-clock-anchor.snapshot', sent[7]],
+  ]);
+});

From c35b7cf118c1b2bf59b5ce63aaaf9946a5bddcd3 Mon Sep 17 00:00:00 2001
From: Rohit <40559587+Rohit3523@users.noreply.github.com>
Date: Fri, 25 Sep 2026 08:54:39 +0530
Subject: [PATCH 121/132] fix(maestro): address killApp review feedback

Distinct survived-kill reason, direct Android kill without shared Interactor change, foreground-refusal docs, exhaustive lifecycle dispatch.
---
 .../application-lifecycle-interaction.test.ts |  47 --------
 .../src/application-lifecycle-interaction.ts  |   8 +-
 .../src/application-lifecycle-runtime.ts      |   7 +-
 packages/contracts/src/interactor-types.ts    |   6 -
 .../src/internal/runtime-port-commands.ts     |  11 +-
 .../maestro/src/internal/support-matrix.ts    |   2 +-
 .../src/__tests__/app-lifecycle-open.test.ts  |  11 +-
 .../platform-android/src/app-lifecycle.ts     |   4 +-
 .../platform-android/src/lifecycle.test.ts    | 110 +++++++++++++++++-
 packages/platform-android/src/lifecycle.ts    |   7 +-
 src/core/interactors/android.ts               |   2 -
 website/docs/docs/replay-e2e.md               |   2 +-
 12 files changed, 144 insertions(+), 73 deletions(-)

diff --git a/packages/contracts/src/application-lifecycle-interaction.test.ts b/packages/contracts/src/application-lifecycle-interaction.test.ts
index 662aca9474..2e42310f7c 100644
--- a/packages/contracts/src/application-lifecycle-interaction.test.ts
+++ b/packages/contracts/src/application-lifecycle-interaction.test.ts
@@ -5,7 +5,6 @@ import type { OpenApplicationInput } from './application-lifecycle-runtime.ts';
 import {
   bindDirectApplicationLifecycle,
   bindLocalApplicationLifecycleInteractor,
-  invokeApplicationClose,
   invokeApplicationOpen,
 } from './application-lifecycle-interaction.ts';
 
@@ -92,52 +91,6 @@ test('direct lifecycle owners preserve the daemon runtime launch URL follow-up',
   expect(calls[1]?.options).toHaveProperty('launchArgs', undefined);
 });
 
-test('kill mode dispatches Interactor.kill when the owner implements it', async () => {
-  const calls: string[] = [];
-  const interactor: Interactor = {
-    ...interactorWithOpen(),
-    close: async (app) => {
-      calls.push(`close:${app}`);
-    },
-    kill: async (app) => {
-      calls.push(`kill:${app}`);
-    },
-  };
-
-  await invokeApplicationClose({
-    device: LINUX_DEVICE,
-    interactor,
-    positionals: ['com.example.app'],
-    mode: 'kill',
-  });
-
-  expect(calls).toEqual(['kill:com.example.app']);
-});
-
-test('kill mode falls back to close when the owner has no kill', async () => {
-  const calls: string[] = [];
-  const interactor: Interactor = {
-    ...interactorWithOpen(),
-    close: async (app) => {
-      calls.push(`close:${app}`);
-    },
-  };
-
-  await invokeApplicationClose({
-    device: LINUX_DEVICE,
-    interactor,
-    positionals: ['com.example.app'],
-    mode: 'kill',
-  });
-  await invokeApplicationClose({
-    device: LINUX_DEVICE,
-    interactor,
-    positionals: ['com.example.app'],
-  });
-
-  expect(calls).toEqual(['close:com.example.app', 'close:com.example.app']);
-});
-
 test.each([
   {
     name: 'more than two positionals',
diff --git a/packages/contracts/src/application-lifecycle-interaction.ts b/packages/contracts/src/application-lifecycle-interaction.ts
index c82d7ce814..0db4ce162f 100644
--- a/packages/contracts/src/application-lifecycle-interaction.ts
+++ b/packages/contracts/src/application-lifecycle-interaction.ts
@@ -370,19 +370,13 @@ export async function invokeApplicationClose(
     device: DeviceInfo;
     interactor: Interactor;
     positionals: readonly string[];
-    /** `kill` dispatches `Interactor.kill` with fallback to `close`; absent means `stop`. */
-    mode?: 'stop' | 'kill';
   }>,
 ): Promise<void> {
-  const { device, interactor, positionals, mode } = params;
+  const { device, interactor, positionals } = params;
   const app = positionals[0];
   if (!app) {
     if (device.platform === 'web') await interactor.close('');
     return;
   }
-  if (mode === 'kill' && interactor.kill) {
-    await interactor.kill(app);
-    return;
-  }
   await interactor.close(app);
 }
diff --git a/packages/contracts/src/application-lifecycle-runtime.ts b/packages/contracts/src/application-lifecycle-runtime.ts
index 73d1b5c78e..8ee329cc77 100644
--- a/packages/contracts/src/application-lifecycle-runtime.ts
+++ b/packages/contracts/src/application-lifecycle-runtime.ts
@@ -150,10 +150,11 @@ export type CloseApplicationInput = Readonly<{
   ensureReady?: boolean;
   /**
    * `kill` is Maestro `killApp` (system-initiated process death: `am kill` on
-   * Android); absent means `stop`. Owners without an `Interactor.kill` alias
-   * it to `close` in the shared dispatcher.
+   * Android); absent means `stop`. Only the Android owner reads it and calls
+   * its own kill; owners that ignore it keep `force-stop`, which is the
+   * `stopApp` alias Maestro uses elsewhere (iOS included).
    */
-  mode?: 'stop' | 'kill';
+  mode?: 'kill';
   execution: ApplicationLifecycleExecution;
 }>;
 
diff --git a/packages/contracts/src/interactor-types.ts b/packages/contracts/src/interactor-types.ts
index d63cee6025..77f3982c58 100644
--- a/packages/contracts/src/interactor-types.ts
+++ b/packages/contracts/src/interactor-types.ts
@@ -298,12 +298,6 @@ export type Interactor = {
   ): Promise<void>;
   openDevice(): Promise<void>;
   close(app: string): Promise<void>;
-  /**
-   * System-initiated process death (Maestro `killApp`): on Android `am kill`
-   * rather than `am force-stop`. Owners without a lighter-weight kill leave
-   * it undefined and the shared close dispatcher falls back to `close(app)`.
-   */
-  kill?(app: string): Promise<void>;
   tap(x: number, y: number): Promise<Record<string, unknown> | void>;
   /** Complete point-press semantics for owners with fused series, alternate buttons, or surfaces. */
   pressPoint?(point: Point, options: PressPointOptions): Promise<Record<string, unknown> | void>;
diff --git a/packages/maestro/src/internal/runtime-port-commands.ts b/packages/maestro/src/internal/runtime-port-commands.ts
index 7c71f57124..628ee6397d 100644
--- a/packages/maestro/src/internal/runtime-port-commands.ts
+++ b/packages/maestro/src/internal/runtime-port-commands.ts
@@ -175,13 +175,22 @@ async function executeLifecycleCommand(
         context,
         'invalidate',
       );
-    default:
+    case 'stopApp':
+    case 'killApp':
+    case 'clearState':
       return await invokeOperation(
         MAESTRO_APP_TARGET_OPERATIONS[command.kind](operations),
         { appId: command.appId ?? request.appId },
         context,
         'invalidate',
       );
+    default: {
+      const exhaustive: never = command;
+      throw new AppError(
+        'COMMAND_FAILED',
+        `Unsupported Maestro lifecycle command ${(exhaustive as { kind: string }).kind}.`,
+      );
+    }
   }
 }
 
diff --git a/packages/maestro/src/internal/support-matrix.ts b/packages/maestro/src/internal/support-matrix.ts
index dd265a7eaf..54eaa300d4 100644
--- a/packages/maestro/src/internal/support-matrix.ts
+++ b/packages/maestro/src/internal/support-matrix.ts
@@ -1,7 +1,7 @@
 export const MAESTRO_COMPAT_SUPPORTED_CAPABILITIES = [
   'Flows: launchApp (with clearState, permissions, and Apple-only launch arguments; permissions apply after state clearing but before launch, and a launchApp without permissions touches nothing — there is no silent all: allow default); setPermissions (mid-flow permission grants, denials, and resets; all resolves in the backend — one simctl call on iOS, the declared permissions on Android — with specific entries overriding after it); runFlow file/inline with platform, visibility, and limited boolean conditions; onFlowStart/onFlowComplete; repeat.times and retry.',
   'Interactions: tapOn, doubleTapOn, longPressOn, inputText on the focused element, eraseText, openLink, hideKeyboard, basic pressKey, and back; selector targets poll until available and support recursive index, childOf, above, below, leftOf, rightOf, containsChild, containsDescendants, points, and optional; outer command labels are metadata, not target selectors.',
-  'Assertions and navigation: assertVisible, assertNotVisible, assertTrue (literal values and ${VAR} lookups only; "", "false", "0", "null", and "undefined" are falsy, everything else is truthy), extendedWaitUntil, scroll, scrollUntilVisible, absolute/percentage/target swipe, takeScreenshot, waitForAnimationToEnd, clearState, stopApp, and killApp (system-initiated process death: am kill on Android, stopApp alias elsewhere).',
+  'Assertions and navigation: assertVisible, assertNotVisible, assertTrue (literal values and ${VAR} lookups only; "", "false", "0", "null", and "undefined" are falsy, everything else is truthy), extendedWaitUntil, scroll, scrollUntilVisible, absolute/percentage/target swipe, takeScreenshot, waitForAnimationToEnd, clearState, stopApp, and killApp (system-initiated process death: am kill on Android, stopApp alias elsewhere; Android refuses a foreground target with android-kill-requires-background-app — background the app first, for example pressKey: Home — and fails a backgrounded target whose process survives with android-kill-process-survived).',
   'Scripts: ordered runScript file/env scripts with http.post, json, and output variables; evalScript inline expressions run flow-scoped JavaScript and write output.* leaves for later steps.',
 ] as const;
 
diff --git a/packages/platform-android/src/__tests__/app-lifecycle-open.test.ts b/packages/platform-android/src/__tests__/app-lifecycle-open.test.ts
index ac270f8fe5..f8b0dd9886 100644
--- a/packages/platform-android/src/__tests__/app-lifecycle-open.test.ts
+++ b/packages/platform-android/src/__tests__/app-lifecycle-open.test.ts
@@ -292,8 +292,17 @@ test('killAndroidApp fails when the process survives the kill', async () => {
     async () => {
       await assertRejectsAppError(() => killAndroidApp(device, 'com.example.app'), {
         code: 'COMMAND_FAILED',
-        hint: /Background the app before killApp/,
+        hint: /foreground service|force-stop/,
       });
+      try {
+        await killAndroidApp(device, 'com.example.app');
+        assert.fail('expected killAndroidApp to reject when the process survives');
+      } catch (error) {
+        assert.equal(
+          (error as InstanceType<typeof AppError>).details?.reason,
+          'android-kill-process-survived',
+        );
+      }
     },
   );
 });
diff --git a/packages/platform-android/src/app-lifecycle.ts b/packages/platform-android/src/app-lifecycle.ts
index 6b3072fb05..ebe92fc393 100644
--- a/packages/platform-android/src/app-lifecycle.ts
+++ b/packages/platform-android/src/app-lifecycle.ts
@@ -520,8 +520,8 @@ async function killAndroidPackage(device: DeviceInfo, packageName: string): Prom
   await waitForAndroidPackageStopped(device, packageName);
   if (await isAndroidPackageProcessRunning(device, packageName)) {
     throw new AppError('COMMAND_FAILED', `am kill did not stop ${packageName}`, {
-      reason: 'android-kill-requires-background-app',
-      hint: 'Background the app before killApp (for example pressKey: Home): am kill only reaps background processes.',
+      reason: 'android-kill-process-survived',
+      hint: 'The app was backgrounded but its process survived am kill (for example a foreground service is still running): use stopApp (am force-stop) to terminate it.',
     });
   }
 }
diff --git a/packages/platform-android/src/lifecycle.test.ts b/packages/platform-android/src/lifecycle.test.ts
index 0245284910..0549a46a15 100644
--- a/packages/platform-android/src/lifecycle.test.ts
+++ b/packages/platform-android/src/lifecycle.test.ts
@@ -1,9 +1,19 @@
 import { afterEach, expect, test, vi } from 'vitest';
-import type { LocalApplicationInteractorHost } from '@agent-device/contracts/application-lifecycle-runtime';
+import type {
+  CloseApplicationInput,
+  LocalApplicationInteractorHost,
+} from '@agent-device/contracts/application-lifecycle-runtime';
 import type { PlatformRuntimeHost } from '@agent-device/contracts/platform-runtime-operations';
 import type { Interactor } from '@agent-device/contracts/interactor-types';
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import { bindAndroidApplicationLifecycle } from './lifecycle.ts';
+import { killAndroidApp } from './app-lifecycle.ts';
+
+vi.mock('./app-lifecycle.ts', () => ({
+  killAndroidApp: vi.fn(async () => {}),
+}));
+
+const mockKillAndroidApp = vi.mocked(killAndroidApp);
 
 const device: DeviceInfo = {
   platform: 'android',
@@ -16,6 +26,7 @@ const device: DeviceInfo = {
 
 afterEach(() => {
   vi.restoreAllMocks();
+  mockKillAndroidApp.mockClear();
 });
 
 test('preserves a runtime launch URL duration after the admitted Android follow-up open', async () => {
@@ -89,3 +100,100 @@ test('preserves a runtime launch URL duration after the admitted Android follow-
   expect(opens).toEqual(['com.example.app', 'example://after-open']);
   expect(outcome.timing.launchUrlDurationMs).toBe(20);
 });
+
+function closeLifecycleHost(resolve: LocalApplicationInteractorHost['resolve']) {
+  return {
+    localInteractors: { resolve },
+    deviceReadiness: {
+      android: { ensureReady: async () => ({ ...device, booted: true }) },
+    },
+    deviceShutdown: {
+      android: { shutdownTarget: async () => undefined },
+    },
+    androidApplications: {
+      resolveOpenTarget: async () => ({}),
+      inferOpenedAppBundleId: async () => 'com.example.app',
+      resetFramePerfStats: async () => {},
+      applyRuntimeHints: async () => {},
+      clearRuntimeHints: async () => {},
+      activateTestIme: async () => {},
+      restoreTestIme: async () => {},
+      recoverTestImeStartup: async () => {},
+      hasTestImeRecoveryEvidence: async () => false,
+    },
+  } as unknown as Pick<
+    PlatformRuntimeHost,
+    | 'androidApplications'
+    | 'clock'
+    | 'commands'
+    | 'deviceReadiness'
+    | 'deviceShutdown'
+    | 'localInteractors'
+    | 'toolchains'
+  >;
+}
+
+function closeInput(overrides: Partial<CloseApplicationInput> = {}): CloseApplicationInput {
+  return {
+    positionals: ['com.example.app'],
+    appBundleId: 'com.example.app',
+    surface: 'app',
+    execution: {},
+    ...overrides,
+  };
+}
+
+test('kill mode calls am kill without resolving an interactor', async () => {
+  let resolved = 0;
+  const closed: string[] = [];
+  const host = closeLifecycleHost(async () => {
+    resolved += 1;
+    return {
+      open: async () => {},
+      openDevice: async () => {},
+      close: async (app: string) => {
+        closed.push(app);
+      },
+      setSetting: async () => {},
+    } as unknown as Interactor;
+  });
+  const lifecycle = bindAndroidApplicationLifecycle({
+    host,
+    device,
+    signal: new AbortController().signal,
+  });
+
+  await lifecycle.closeApplication(closeInput({ mode: 'kill' }));
+
+  expect(resolved).toBe(0);
+  expect(closed).toEqual([]);
+  expect(mockKillAndroidApp).toHaveBeenCalledOnce();
+  expect(mockKillAndroidApp).toHaveBeenCalledWith(device, 'com.example.app');
+});
+
+test('stop close resolves an interactor and force-stops', async () => {
+  let resolved = 0;
+  const closed: string[] = [];
+  const host = closeLifecycleHost(async () => {
+    resolved += 1;
+    return {
+      open: async () => {},
+      openDevice: async () => {},
+      close: async (app: string) => {
+        closed.push(app);
+      },
+      setSetting: async () => {},
+    } as unknown as Interactor;
+  });
+  const lifecycle = bindAndroidApplicationLifecycle({
+    host,
+    device,
+    signal: new AbortController().signal,
+  });
+
+  await lifecycle.closeApplication(closeInput());
+
+  expect(resolved).toBe(1);
+  expect(closed).toEqual(['com.example.app']);
+  expect(mockKillAndroidApp).not.toHaveBeenCalled();
+});
diff --git a/packages/platform-android/src/lifecycle.ts b/packages/platform-android/src/lifecycle.ts
index 912c0dc606..5cb86da0ca 100644
--- a/packages/platform-android/src/lifecycle.ts
+++ b/packages/platform-android/src/lifecycle.ts
@@ -12,6 +12,7 @@ import {
   invokeApplicationOpen,
 } from '@agent-device/contracts/application-lifecycle-interaction';
 import { ensureAndroidReady } from './readiness/runtime.ts';
+import { killAndroidApp } from './app-lifecycle.ts';
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import { AppError } from '@agent-device/kernel/errors';
 
@@ -63,11 +64,15 @@ export function bindAndroidApplicationLifecycle(
       if (input.ensureReady) {
         await ensureAndroidReady(host, device, { headless: false }, signal);
       }
+      if (input.mode === 'kill') {
+        const target = input.positionals[0];
+        if (target) await killAndroidApp(device, target);
+        return;
+      }
       await invokeApplicationClose({
         device,
         interactor: await binding.resolveInteractor(input.execution, input.appBundleId),
         positionals: input.positionals,
-        mode: input.mode,
       });
     },
     finalizeApplicationClose: async (input) => {
diff --git a/src/core/interactors/android.ts b/src/core/interactors/android.ts
index b52c1917d5..fff5d3f126 100644
--- a/src/core/interactors/android.ts
+++ b/src/core/interactors/android.ts
@@ -11,7 +11,6 @@ import {
   getAndroidKeyboardState,
   handleAndroidAlert,
   homeAndroid,
-  killAndroidApp,
   longPressAndroid,
   openAndroidApp,
   openAndroidDevice,
@@ -70,7 +69,6 @@ export function createAndroidInteractor(
       }),
     openDevice: () => openAndroidDevice(device),
     close: (app) => closeAndroidApp(device, app),
-    kill: (app) => killAndroidApp(device, app),
     tap: (x, y) => pressAndroid(device, x, y),
     doubleTap: async (x, y) => {
       await pressAndroid(device, x, y);
diff --git a/website/docs/docs/replay-e2e.md b/website/docs/docs/replay-e2e.md
index e86b3f66db..c58aea3a87 100644
--- a/website/docs/docs/replay-e2e.md
+++ b/website/docs/docs/replay-e2e.md
@@ -72,7 +72,7 @@ Supported subset:
 
 - Flows: `launchApp` (with `clearState`, `permissions`, and Apple-only launch arguments; `permissions` apply after state clearing but before launch, and a `launchApp` without `permissions` touches nothing — there is no silent `all: allow` default); `setPermissions` (mid-flow permission grants, denials, and resets; `all` resolves in the backend — one simctl call on iOS, the declared permissions on Android — with specific entries overriding after it); `runFlow` file/inline with platform, visibility, and limited boolean conditions; `onFlowStart`/`onFlowComplete`; `repeat.times` and retry.
 - Interactions: `tapOn`, `doubleTapOn`, `longPressOn`, `inputText` on the focused element, `eraseText`, `openLink`, `hideKeyboard`, basic `pressKey`, and `back`; selector targets poll until available and support recursive `index`, `childOf`, `above`, `below`, `leftOf`, `rightOf`, `containsChild`, `containsDescendants`, points, and `optional`; outer command labels are metadata, not target selectors.
-- Assertions and navigation: `assertVisible`, `assertNotVisible`, `assertTrue` (literal values and `${VAR}` lookups only; `""`, `"false"`, `"0"`, `"null"`, and `"undefined"` are falsy, everything else is truthy), `extendedWaitUntil`, `scroll`, `scrollUntilVisible`, absolute/percentage/target `swipe`, `takeScreenshot`, `waitForAnimationToEnd`, `clearState`, `stopApp`, and `killApp` (system-initiated process death: `am kill` on Android, `stopApp` alias elsewhere).
+- Assertions and navigation: `assertVisible`, `assertNotVisible`, `assertTrue` (literal values and `${VAR}` lookups only; `""`, `"false"`, `"0"`, `"null"`, and `"undefined"` are falsy, everything else is truthy), `extendedWaitUntil`, `scroll`, `scrollUntilVisible`, absolute/percentage/target `swipe`, `takeScreenshot`, `waitForAnimationToEnd`, `clearState`, `stopApp`, and `killApp` (system-initiated process death: `am kill` on Android, `stopApp` alias elsewhere; Android refuses a foreground target with `android-kill-requires-background-app` — background the app first, for example `pressKey: Home` — and fails a backgrounded target whose process survives with `android-kill-process-survived`).
 - Scripts: ordered `runScript` file/env scripts with `http.post`, `json`, and `output` variables; `evalScript` inline expressions run flow-scoped JavaScript and write `output.*` leaves for later steps.
 
 Boundaries:

From b2af2a988c7928e9b56a5dfcdd3c73dcd897800b Mon Sep 17 00:00:00 2001
From: Rohit <40559587+Rohit3523@users.noreply.github.com>
Date: Tue, 22 Sep 2026 03:17:20 +0530
Subject: [PATCH 122/132] feat(maestro): support killApp via close mode

Maestro killApp triggers system-initiated process death (adb shell am
kill on Android) instead of stopApp's force-stop. On other platforms it
aliases stopApp through the shared close dispatcher.

- contracts: optional Interactor.kill, CloseApplicationInput.mode, with
  fallback to close in invokeApplicationClose
- android: killAndroidApp (am kill) wired onto the interactor
- maestro: killApp IR kind, parser, runtime port, daemon projection to
  an app-only close carrying killApp dispatch, conformance canonical
- daemon: replay dispatch folds killApp; session close passes
  mode kill into closeApplication
- upstream/116_kill_app now classifies identical; divergence removed
---
 .../application-lifecycle-interaction.test.ts | 47 +++++++++++++++++
 .../src/application-lifecycle-interaction.ts  |  8 ++-
 .../src/application-lifecycle-runtime.ts      |  6 +++
 packages/contracts/src/interactor-types.ts    |  6 +++
 packages/contracts/src/replay.ts              |  5 ++
 .../__tests__/daemon-runtime-port.test.ts     | 41 +++++++++++++++
 .../daemon-runtime-public-operation.test.ts   | 16 ++++++
 .../src/daemon-port/daemon-runtime-port.ts    |  4 ++
 .../daemon-runtime-public-operation.ts        | 22 +++++++-
 .../__tests__/program-ir-parser.test.ts       | 21 ++++++++
 .../__tests__/runtime-port-fixtures.ts        |  1 +
 .../internal/__tests__/runtime-port.test.ts   | 19 +++++++
 .../src/internal/conformance-normalize.ts     |  7 ++-
 .../src/internal/program-ir-command-parser.ts | 12 +++++
 packages/maestro/src/internal/program-ir.ts   |  7 +++
 .../src/internal/runtime-port-commands.ts     | 11 +++-
 .../src/internal/runtime-port-types.ts        |  1 +
 .../maestro/src/internal/support-matrix.ts    |  2 +-
 .../test/conformance/expected-divergence.ts   |  5 --
 .../src/__tests__/app-lifecycle-open.test.ts  | 43 +++++++++++++++-
 .../platform-android/src/app-lifecycle.ts     | 20 ++++++++
 packages/platform-android/src/lifecycle.ts    |  1 +
 packages/platform-android/src/mechanics.ts    |  1 +
 .../fuzz/validation-arbitraries-maestro.ts    |  2 +
 src/core/interactors/android.ts               |  2 +
 .../session-replay-maestro-request.test.ts    | 13 +++++
 .../session-replay-maestro-request.ts         |  1 +
 .../session-close-lifecycle-runtime.test.ts   | 50 +++++++++++++++++++
 .../internal/session-close.ts                 |  1 +
 website/docs/docs/replay-e2e.md               |  2 +-
 30 files changed, 364 insertions(+), 13 deletions(-)

diff --git a/packages/contracts/src/application-lifecycle-interaction.test.ts b/packages/contracts/src/application-lifecycle-interaction.test.ts
index 2e42310f7c..662aca9474 100644
--- a/packages/contracts/src/application-lifecycle-interaction.test.ts
+++ b/packages/contracts/src/application-lifecycle-interaction.test.ts
@@ -5,6 +5,7 @@ import type { OpenApplicationInput } from './application-lifecycle-runtime.ts';
 import {
   bindDirectApplicationLifecycle,
   bindLocalApplicationLifecycleInteractor,
+  invokeApplicationClose,
   invokeApplicationOpen,
 } from './application-lifecycle-interaction.ts';
 
@@ -91,6 +92,52 @@ test('direct lifecycle owners preserve the daemon runtime launch URL follow-up',
   expect(calls[1]?.options).toHaveProperty('launchArgs', undefined);
 });
 
+test('kill mode dispatches Interactor.kill when the owner implements it', async () => {
+  const calls: string[] = [];
+  const interactor: Interactor = {
+    ...interactorWithOpen(),
+    close: async (app) => {
+      calls.push(`close:${app}`);
+    },
+    kill: async (app) => {
+      calls.push(`kill:${app}`);
+    },
+  };
+
+  await invokeApplicationClose({
+    device: LINUX_DEVICE,
+    interactor,
+    positionals: ['com.example.app'],
+    mode: 'kill',
+  });
+
+  expect(calls).toEqual(['kill:com.example.app']);
+});
+
+test('kill mode falls back to close when the owner has no kill', async () => {
+  const calls: string[] = [];
+  const interactor: Interactor = {
+    ...interactorWithOpen(),
+    close: async (app) => {
+      calls.push(`close:${app}`);
+    },
+  };
+
+  await invokeApplicationClose({
+    device: LINUX_DEVICE,
+    interactor,
+    positionals: ['com.example.app'],
+    mode: 'kill',
+  });
+  await invokeApplicationClose({
+    device: LINUX_DEVICE,
+    interactor,
+    positionals: ['com.example.app'],
+  });
+
+  expect(calls).toEqual(['close:com.example.app', 'close:com.example.app']);
+});
+
 test.each([
   {
     name: 'more than two positionals',
diff --git a/packages/contracts/src/application-lifecycle-interaction.ts b/packages/contracts/src/application-lifecycle-interaction.ts
index 0db4ce162f..c82d7ce814 100644
--- a/packages/contracts/src/application-lifecycle-interaction.ts
+++ b/packages/contracts/src/application-lifecycle-interaction.ts
@@ -370,13 +370,19 @@ export async function invokeApplicationClose(
     device: DeviceInfo;
     interactor: Interactor;
     positionals: readonly string[];
+    /** `kill` dispatches `Interactor.kill` with fallback to `close`; absent means `stop`. */
+    mode?: 'stop' | 'kill';
   }>,
 ): Promise<void> {
-  const { device, interactor, positionals } = params;
+  const { device, interactor, positionals, mode } = params;
   const app = positionals[0];
   if (!app) {
     if (device.platform === 'web') await interactor.close('');
     return;
   }
+  if (mode === 'kill' && interactor.kill) {
+    await interactor.kill(app);
+    return;
+  }
   await interactor.close(app);
 }
diff --git a/packages/contracts/src/application-lifecycle-runtime.ts b/packages/contracts/src/application-lifecycle-runtime.ts
index 98504a649b..31f237122c 100644
--- a/packages/contracts/src/application-lifecycle-runtime.ts
+++ b/packages/contracts/src/application-lifecycle-runtime.ts
@@ -178,6 +178,12 @@ export type CloseApplicationInput = Readonly<{
   surface: SessionSurface;
   /** A selector-only close establishes readiness inside its admitted lifecycle binding. */
   ensureReady?: boolean;
+  /**
+   * `kill` is Maestro `killApp` (system-initiated process death: `am kill` on
+   * Android); absent means `stop`. Owners without an `Interactor.kill` alias
+   * it to `close` in the shared dispatcher.
+   */
+  mode?: 'stop' | 'kill';
   execution: ApplicationLifecycleExecution;
 }>;
 
diff --git a/packages/contracts/src/interactor-types.ts b/packages/contracts/src/interactor-types.ts
index 15670d675b..b714ea7a09 100644
--- a/packages/contracts/src/interactor-types.ts
+++ b/packages/contracts/src/interactor-types.ts
@@ -290,6 +290,12 @@ export type Interactor = {
   ): Promise<void>;
   openDevice(): Promise<void>;
   close(app: string): Promise<void>;
+  /**
+   * System-initiated process death (Maestro `killApp`): on Android `am kill`
+   * rather than `am force-stop`. Owners without a lighter-weight kill leave
+   * it undefined and the shared close dispatcher falls back to `close(app)`.
+   */
+  kill?(app: string): Promise<void>;
   tap(x: number, y: number): Promise<Record<string, unknown> | void>;
   /** Complete point-press semantics for owners with fused series, alternate buttons, or surfaces. */
   pressPoint?(point: Point, options: PressPointOptions): Promise<Record<string, unknown> | void>;
diff --git a/packages/contracts/src/replay.ts b/packages/contracts/src/replay.ts
index fab9e8d8c8..8ddd81e9c2 100644
--- a/packages/contracts/src/replay.ts
+++ b/packages/contracts/src/replay.ts
@@ -277,6 +277,11 @@ export type ReplayDispatchOptions = Readonly<{
   openLifecycle?: ReplayOpenLifecycle;
   /** Terminate the targeted app without ending the owning daemon session. */
   closeAppOnly?: boolean;
+  /**
+   * With `closeAppOnly`: Maestro `killApp` system-initiated process death
+   * (`am kill` on Android, `stopApp` alias elsewhere) instead of `stop`.
+   */
+  killApp?: boolean;
   /**
    * Daemon-composed hierarchy capture used as operational evidence only. It must not issue or
    * replace client ref authority.
diff --git a/packages/maestro/src/daemon-port/__tests__/daemon-runtime-port.test.ts b/packages/maestro/src/daemon-port/__tests__/daemon-runtime-port.test.ts
index dccc465176..c505138a71 100644
--- a/packages/maestro/src/daemon-port/__tests__/daemon-runtime-port.test.ts
+++ b/packages/maestro/src/daemon-port/__tests__/daemon-runtime-port.test.ts
@@ -173,6 +173,47 @@ test('projects standalone clearState to settings without opening the app', async
   ]);
 });
 
+test('projects standalone killApp to an app-only close carrying the kill mode', async () => {
+  const requests: MaestroDaemonOperationRequest[] = [];
+  const invoke: MaestroDaemonOperationInvoke = async (request) => {
+    requests.push(request);
+    return { ok: true, data: {} };
+  };
+  const port = createDaemonMaestroRuntimePort({
+    ...makeRuntimeEnvelope({ flags: { platform: 'android', replayBackend: 'maestro' } }),
+    invoke,
+    dependencies: makeDependencies(),
+    platform: 'android',
+  });
+
+  await port.execute({
+    command: { kind: 'killApp', source: { line: 2 }, appId: 'com.example.app' },
+    generation: 0,
+    env: {},
+    invalidateObservation() {},
+  });
+  await port.execute({
+    command: { kind: 'killApp', source: { line: 3 } },
+    generation: 1,
+    env: {},
+    appId: 'com.example.session',
+    invalidateObservation() {},
+  });
+
+  expect(requests).toEqual([
+    expect.objectContaining({
+      command: 'close',
+      positionals: ['com.example.app'],
+      dispatch: { closeAppOnly: true, killApp: true },
+    }),
+    expect.objectContaining({
+      command: 'close',
+      positionals: ['com.example.session'],
+      dispatch: { closeAppOnly: true, killApp: true },
+    }),
+  ]);
+});
+
 test('uses the direct viewport without snapshot and pairs it with the nested gesture request', async () => {
   const requests: MaestroDaemonOperationRequest[] = [];
   const viewport = { x: 10, y: 20, width: 400, height: 800 };
diff --git a/packages/maestro/src/daemon-port/__tests__/daemon-runtime-public-operation.test.ts b/packages/maestro/src/daemon-port/__tests__/daemon-runtime-public-operation.test.ts
index ad9409bf02..1f45660a6a 100644
--- a/packages/maestro/src/daemon-port/__tests__/daemon-runtime-public-operation.test.ts
+++ b/packages/maestro/src/daemon-port/__tests__/daemon-runtime-public-operation.test.ts
@@ -49,6 +49,22 @@ describe('Maestro public operation projection', () => {
       operation: { kind: 'stopApp' },
       expected: { command: 'close', positionals: [], dispatch: { closeAppOnly: true } },
     },
+    {
+      operation: { kind: 'killApp', appId: 'com.example' },
+      expected: {
+        command: 'close',
+        positionals: ['com.example'],
+        dispatch: { closeAppOnly: true, killApp: true },
+      },
+    },
+    {
+      operation: { kind: 'killApp' },
+      expected: {
+        command: 'close',
+        positionals: [],
+        dispatch: { closeAppOnly: true, killApp: true },
+      },
+    },
     {
       operation: { kind: 'clearState', appId: 'com.example' },
       expected: { command: 'settings', positionals: ['clear-app-state', 'com.example'] },
diff --git a/packages/maestro/src/daemon-port/daemon-runtime-port.ts b/packages/maestro/src/daemon-port/daemon-runtime-port.ts
index d2f8917c6a..65788203ff 100644
--- a/packages/maestro/src/daemon-port/daemon-runtime-port.ts
+++ b/packages/maestro/src/daemon-port/daemon-runtime-port.ts
@@ -189,6 +189,10 @@ function createDaemonMaestroRuntimeParts(options: CreateDaemonMaestroRuntimeOper
       const appId = input.appId ?? context.appId;
       await invokeMutation({ kind: 'stopApp', ...(appId ? { appId } : {}) }, context);
     },
+    killApp: async (input, context) => {
+      const appId = input.appId ?? context.appId;
+      await invokeMutation({ kind: 'killApp', ...(appId ? { appId } : {}) }, context);
+    },
     setPermissions: async (input, context) => {
       await applyPermissionMutations(
         input.appId ?? context.appId,
diff --git a/packages/maestro/src/daemon-port/daemon-runtime-public-operation.ts b/packages/maestro/src/daemon-port/daemon-runtime-public-operation.ts
index 9016723661..d30915bf52 100644
--- a/packages/maestro/src/daemon-port/daemon-runtime-public-operation.ts
+++ b/packages/maestro/src/daemon-port/daemon-runtime-public-operation.ts
@@ -21,6 +21,7 @@ export type MaestroPublicOperation =
       launchArgs: string[];
     }
   | { kind: 'stopApp'; appId?: string }
+  | { kind: 'killApp'; appId?: string }
   | { kind: 'clearState'; appId?: string }
   | {
       kind: 'settingsPermission';
@@ -53,6 +54,8 @@ export type MaestroPublicOperation =
 export type MaestroDaemonDispatchOptions = Readonly<{
   /** Terminate the targeted app without ending the owning daemon session. */
   closeAppOnly?: true;
+  /** With `closeAppOnly`: Maestro `killApp` process death (`am kill` on Android) instead of `stop`. */
+  killApp?: true;
   /** A hierarchy capture used as operational evidence only; it issues no client ref authority. */
   observationOnly?: true;
   /** Provider-owned viewport already resolved for a nested gesture command. */
@@ -88,12 +91,15 @@ export function projectMaestroPublicOperation(
 
 type MaestroAppOperation = Extract<
   MaestroPublicOperation,
-  { kind: 'launchApp' | 'stopApp' | 'openLink' }
+  { kind: 'launchApp' | 'stopApp' | 'killApp' | 'openLink' }
 >;
 
 function isAppOperation(operation: MaestroPublicOperation): operation is MaestroAppOperation {
   return (
-    operation.kind === 'launchApp' || operation.kind === 'stopApp' || operation.kind === 'openLink'
+    operation.kind === 'launchApp' ||
+    operation.kind === 'stopApp' ||
+    operation.kind === 'killApp' ||
+    operation.kind === 'openLink'
   );
 }
 
@@ -103,6 +109,8 @@ function projectAppOperation(operation: MaestroAppOperation): MaestroDaemonOpera
       return projectLaunchApp(operation);
     case 'stopApp':
       return projectStopApp(operation);
+    case 'killApp':
+      return projectKillApp(operation);
     case 'openLink':
       return projectOpenLink(operation);
   }
@@ -132,6 +140,16 @@ function projectStopApp(
   };
 }
 
+function projectKillApp(
+  operation: Extract<MaestroAppOperation, { kind: 'killApp' }>,
+): MaestroDaemonOperationRequest {
+  return {
+    command: 'close',
+    positionals: operation.appId ? [operation.appId] : [],
+    dispatch: { closeAppOnly: true, killApp: true },
+  };
+}
+
 function projectClearState(
   operation: Extract<MaestroPublicOperation, { kind: 'clearState' }>,
 ): MaestroDaemonOperationRequest {
diff --git a/packages/maestro/src/internal/__tests__/program-ir-parser.test.ts b/packages/maestro/src/internal/__tests__/program-ir-parser.test.ts
index 52dd72b9bb..090c3815c2 100644
--- a/packages/maestro/src/internal/__tests__/program-ir-parser.test.ts
+++ b/packages/maestro/src/internal/__tests__/program-ir-parser.test.ts
@@ -613,6 +613,27 @@ describe('parseMaestroProgram', () => {
     });
   });
 
+  test('parses standalone killApp with an explicit or config app id', () => {
+    const program = parseMaestroProgram(
+      `appId: example.app
+---
+- killApp: example.app
+- killApp
+`,
+      { sourcePath: '/flows/kill.yaml' },
+    );
+
+    assert.deepEqual(program.commands[0], {
+      kind: 'killApp',
+      source: { path: '/flows/kill.yaml', line: 3 },
+      appId: 'example.app',
+    });
+    assert.deepEqual(program.commands[1], {
+      kind: 'killApp',
+      source: { path: '/flows/kill.yaml', line: 4 },
+    });
+  });
+
   test('preserves source paths for unsupported and malformed flows', () => {
     const sourcePath = '/flows/includes/child.yaml';
     assert.throws(
diff --git a/packages/maestro/src/internal/__tests__/runtime-port-fixtures.ts b/packages/maestro/src/internal/__tests__/runtime-port-fixtures.ts
index 765892c9b2..b69da541af 100644
--- a/packages/maestro/src/internal/__tests__/runtime-port-fixtures.ts
+++ b/packages/maestro/src/internal/__tests__/runtime-port-fixtures.ts
@@ -59,6 +59,7 @@ export function makeOperations(
     resolveGestureViewport: async () => ({ x: 0, y: 0, width: 402, height: 874 }),
     launchApp: noOp,
     stopApp: noOp,
+    killApp: noOp,
     setPermissions: noOp,
     clearState: noOp,
     openLink: noOp,
diff --git a/packages/maestro/src/internal/__tests__/runtime-port.test.ts b/packages/maestro/src/internal/__tests__/runtime-port.test.ts
index 9da89973c2..24a684acdd 100644
--- a/packages/maestro/src/internal/__tests__/runtime-port.test.ts
+++ b/packages/maestro/src/internal/__tests__/runtime-port.test.ts
@@ -178,6 +178,25 @@ describe('MaestroRuntimePort', () => {
     expect(calls[1]).toMatchObject({ input: { appId: 'com.example.checkout' } });
   });
 
+  test('dispatches standalone killApp with an explicit or config app id', async () => {
+    const calls: RecordedCall[] = [];
+    const operations = makeOperations({
+      killApp: vi.fn(async (input, context) => record(calls, 'killApp', input, context)),
+    });
+    const program = parseMaestroProgram(
+      ['appId: com.example.checkout', '---', '- killApp: com.example.checkout', '- killApp'].join(
+        '\n',
+      ),
+    );
+
+    const result = await executeMaestroProgram(program, createMaestroRuntimePort(operations));
+
+    expect(result).toMatchObject({ executed: 2, skipped: 0 });
+    expect(calls.map(({ kind }) => kind)).toEqual(['killApp', 'killApp']);
+    expect(calls[0]).toMatchObject({ input: { appId: 'com.example.checkout' } });
+    expect(calls[1]).toMatchObject({ input: { appId: 'com.example.checkout' } });
+  });
+
   test('preserves observation validity after visual waits and scripts', async () => {
     const waitInvalidation = vi.fn();
     const scriptInvalidation = vi.fn();
diff --git a/packages/maestro/src/internal/conformance-normalize.ts b/packages/maestro/src/internal/conformance-normalize.ts
index 6d61c13be4..1d4993eacf 100644
--- a/packages/maestro/src/internal/conformance-normalize.ts
+++ b/packages/maestro/src/internal/conformance-normalize.ts
@@ -83,6 +83,7 @@ export type CanonicalCommand =
   | { kind: 'takeScreenshot' }
   | { kind: 'waitForAnimationToEnd'; timeout?: number | string }
   | { kind: 'stopApp' }
+  | { kind: 'killApp' }
   | { kind: 'setPermissions'; appId?: string; permissions?: Record<string, string> }
   | { kind: 'clearState'; appId?: string }
   | { kind: 'repeat'; times: string | number }
@@ -116,6 +117,8 @@ function canonicalizeUpstreamLifecycleCommand(
       });
     case 'StopAppCommand':
       return { kind: 'stopApp' };
+    case 'KillAppCommand':
+      return { kind: 'killApp' };
     case 'ClearStateCommand':
       return dropUndefined({ kind: 'clearState' as const, appId: str(f.appId) });
     default:
@@ -367,7 +370,7 @@ type AgentLifecycleCommand = Extract<
   { kind: (typeof AGENT_LIFECYCLE_KINDS)[number] }
 >;
 
-const AGENT_LIFECYCLE_KINDS = ['launchApp', 'stopApp', 'clearState'] as const;
+const AGENT_LIFECYCLE_KINDS = ['launchApp', 'stopApp', 'killApp', 'clearState'] as const;
 
 function isAgentLifecycleCommand(command: MaestroCommand): command is AgentLifecycleCommand {
   return (AGENT_LIFECYCLE_KINDS as readonly string[]).includes(command.kind);
@@ -388,6 +391,8 @@ function canonicalizeAgentLifecycleCommand(
       });
     case 'stopApp':
       return { kind: 'stopApp' };
+    case 'killApp':
+      return { kind: 'killApp' };
     case 'clearState':
       return dropUndefined({ kind: 'clearState', appId: command.appId ?? config.appId });
   }
diff --git a/packages/maestro/src/internal/program-ir-command-parser.ts b/packages/maestro/src/internal/program-ir-command-parser.ts
index f1d797c950..a2b6a3dc4d 100644
--- a/packages/maestro/src/internal/program-ir-command-parser.ts
+++ b/packages/maestro/src/internal/program-ir-command-parser.ts
@@ -10,6 +10,7 @@ import type {
   MaestroExtendedWaitUntilCommand,
   MaestroHideKeyboardCommand,
   MaestroInputTextCommand,
+  MaestroKillAppCommand,
   MaestroLaunchAppCommand,
   MaestroLaunchArguments,
   MaestroOpenLinkCommand,
@@ -127,6 +128,7 @@ const COMMAND_VALUE_PARSERS: Readonly<Record<string, CommandValueParser>> = {
   back: parseBack,
   waitForAnimationToEnd: parseWaitForAnimationToEnd,
   stopApp: parseStopApp,
+  killApp: parseKillApp,
   setPermissions: parseSetPermissions,
   clearState: parseClearState,
   runScript: parseMaestroRunScriptCommand,
@@ -459,6 +461,16 @@ function parseStopApp(
   return { kind: 'stopApp', source, appId: readRequiredString(value, 'stopApp', context) };
 }
 
+function parseKillApp(
+  value: Node | null,
+  commandNode: Node,
+  context: MaestroProgramParseContext,
+): MaestroKillAppCommand {
+  const source = sourceAt(commandNode, context);
+  if (isNullNode(value)) return { kind: 'killApp', source };
+  return { kind: 'killApp', source, appId: readRequiredString(value, 'killApp', context) };
+}
+
 function parseSetPermissions(
   value: Node | null,
   commandNode: Node,
diff --git a/packages/maestro/src/internal/program-ir.ts b/packages/maestro/src/internal/program-ir.ts
index d8020097ee..0798618c5d 100644
--- a/packages/maestro/src/internal/program-ir.ts
+++ b/packages/maestro/src/internal/program-ir.ts
@@ -208,6 +208,12 @@ export type MaestroStopAppCommand = {
   appId?: string;
 };
 
+export type MaestroKillAppCommand = {
+  kind: 'killApp';
+  source: MaestroSourceLocation;
+  appId?: string;
+};
+
 export type MaestroSetPermissionsCommand = MaestroOptionalCommand & {
   kind: 'setPermissions';
   source: MaestroSourceLocation;
@@ -286,6 +292,7 @@ export type MaestroCommand =
   | MaestroBackCommand
   | MaestroWaitForAnimationToEndCommand
   | MaestroStopAppCommand
+  | MaestroKillAppCommand
   | MaestroSetPermissionsCommand
   | MaestroClearStateCommand
   | MaestroRunScriptCommand
diff --git a/packages/maestro/src/internal/runtime-port-commands.ts b/packages/maestro/src/internal/runtime-port-commands.ts
index cb4fafb422..e398600ee1 100644
--- a/packages/maestro/src/internal/runtime-port-commands.ts
+++ b/packages/maestro/src/internal/runtime-port-commands.ts
@@ -30,7 +30,7 @@ type MaestroCommandOf<K extends MaestroRuntimeCommand['kind']> = Extract<
 >;
 
 type MaestroLifecycleCommand = MaestroCommandOf<
-  'launchApp' | 'stopApp' | 'setPermissions' | 'clearState' | 'openLink'
+  'launchApp' | 'stopApp' | 'killApp' | 'setPermissions' | 'clearState' | 'openLink'
 >;
 type MaestroTargetCommand = MaestroCommandOf<'tapOn' | 'doubleTapOn' | 'longPressOn'>;
 type MaestroTextCommand = MaestroCommandOf<'inputText' | 'eraseText'>;
@@ -55,6 +55,7 @@ type MaestroRuntimeCommandHandlers = {
 const MAESTRO_RUNTIME_COMMAND_HANDLERS = {
   launchApp: executeLifecycleCommand,
   stopApp: executeLifecycleCommand,
+  killApp: executeLifecycleCommand,
   setPermissions: executeLifecycleCommand,
   clearState: executeLifecycleCommand,
   openLink: executeLifecycleCommand,
@@ -82,6 +83,7 @@ const MAESTRO_RUNTIME_COMMAND_HANDLERS = {
 const MAESTRO_COMMAND_REQUIRES_SETTLED_PREDECESSOR = {
   launchApp: true,
   stopApp: true,
+  killApp: true,
   setPermissions: true,
   clearState: true,
   openLink: true,
@@ -150,6 +152,13 @@ async function executeLifecycleCommand(
         context,
         'invalidate',
       );
+    case 'killApp':
+      return await invokeOperation(
+        operations.killApp,
+        { appId: command.appId ?? request.appId },
+        context,
+        'invalidate',
+      );
     case 'setPermissions':
       return await invokeOperation(
         operations.setPermissions,
diff --git a/packages/maestro/src/internal/runtime-port-types.ts b/packages/maestro/src/internal/runtime-port-types.ts
index 4c82492049..924468a460 100644
--- a/packages/maestro/src/internal/runtime-port-types.ts
+++ b/packages/maestro/src/internal/runtime-port-types.ts
@@ -124,6 +124,7 @@ export type MaestroRuntimeOperations = {
     readonly launchArguments?: MaestroLaunchArguments;
   }>;
   readonly stopApp: MaestroRuntimeOperation<{ readonly appId?: string }>;
+  readonly killApp: MaestroRuntimeOperation<{ readonly appId?: string }>;
   readonly setPermissions: MaestroRuntimeOperation<{
     readonly appId?: string;
     readonly permissions: Readonly<Record<string, string>>;
diff --git a/packages/maestro/src/internal/support-matrix.ts b/packages/maestro/src/internal/support-matrix.ts
index a58f2bcff7..dd265a7eaf 100644
--- a/packages/maestro/src/internal/support-matrix.ts
+++ b/packages/maestro/src/internal/support-matrix.ts
@@ -1,7 +1,7 @@
 export const MAESTRO_COMPAT_SUPPORTED_CAPABILITIES = [
   'Flows: launchApp (with clearState, permissions, and Apple-only launch arguments; permissions apply after state clearing but before launch, and a launchApp without permissions touches nothing — there is no silent all: allow default); setPermissions (mid-flow permission grants, denials, and resets; all resolves in the backend — one simctl call on iOS, the declared permissions on Android — with specific entries overriding after it); runFlow file/inline with platform, visibility, and limited boolean conditions; onFlowStart/onFlowComplete; repeat.times and retry.',
   'Interactions: tapOn, doubleTapOn, longPressOn, inputText on the focused element, eraseText, openLink, hideKeyboard, basic pressKey, and back; selector targets poll until available and support recursive index, childOf, above, below, leftOf, rightOf, containsChild, containsDescendants, points, and optional; outer command labels are metadata, not target selectors.',
-  'Assertions and navigation: assertVisible, assertNotVisible, assertTrue (literal values and ${VAR} lookups only; "", "false", "0", "null", and "undefined" are falsy, everything else is truthy), extendedWaitUntil, scroll, scrollUntilVisible, absolute/percentage/target swipe, takeScreenshot, waitForAnimationToEnd, clearState, and stopApp.',
+  'Assertions and navigation: assertVisible, assertNotVisible, assertTrue (literal values and ${VAR} lookups only; "", "false", "0", "null", and "undefined" are falsy, everything else is truthy), extendedWaitUntil, scroll, scrollUntilVisible, absolute/percentage/target swipe, takeScreenshot, waitForAnimationToEnd, clearState, stopApp, and killApp (system-initiated process death: am kill on Android, stopApp alias elsewhere).',
   'Scripts: ordered runScript file/env scripts with http.post, json, and output variables; evalScript inline expressions run flow-scoped JavaScript and write output.* leaves for later steps.',
 ] as const;
 
diff --git a/packages/maestro/test/conformance/expected-divergence.ts b/packages/maestro/test/conformance/expected-divergence.ts
index 52f96e4fc1..6d7a2e3997 100644
--- a/packages/maestro/test/conformance/expected-divergence.ts
+++ b/packages/maestro/test/conformance/expected-divergence.ts
@@ -48,11 +48,6 @@ export const FLOW_DIVERGENCES: Record<string, FlowDivergence> = {
     reason: 'travel is outside the supported subset.',
     unsupported: ['travel'],
   },
-  'upstream/116_kill_app': {
-    classification: 'we-reject',
-    reason: 'Standalone killApp is outside the supported subset.',
-    unsupported: ['killApp'],
-  },
   // --- Deliberately stricter than upstream ---
   'invalid/duplicate-keys': {
     classification: 'we-reject',
diff --git a/packages/platform-android/src/__tests__/app-lifecycle-open.test.ts b/packages/platform-android/src/__tests__/app-lifecycle-open.test.ts
index 1abced327e..78b92e563a 100644
--- a/packages/platform-android/src/__tests__/app-lifecycle-open.test.ts
+++ b/packages/platform-android/src/__tests__/app-lifecycle-open.test.ts
@@ -1,6 +1,6 @@
 import { test } from 'vitest';
 import assert from 'node:assert/strict';
-import { closeAndroidApp, openAndroidApp } from '../app-lifecycle.ts';
+import { closeAndroidApp, killAndroidApp, openAndroidApp } from '../app-lifecycle.ts';
 import { withAndroidAdbProvider } from '../adb-executor.ts';
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import { AppError } from '@agent-device/kernel/errors';
@@ -162,6 +162,47 @@ test('closeAndroidApp waits until package process exits after force-stop', async
   ]);
 });
 
+test('killAndroidApp dispatches am kill rather than am force-stop', async () => {
+  const device: DeviceInfo = {
+    platform: 'android',
+    id: 'emulator-5554',
+    name: 'Pixel',
+    kind: 'emulator',
+    booted: true,
+  };
+  const calls: (readonly string[])[] = [];
+
+  await withAndroidAdbProvider(
+    {
+      exec: async (args) => {
+        calls.push(args);
+        if (args.join(' ') === 'shell dumpsys window windows') {
+          return {
+            stdout: 'mCurrentFocus=Window{43 u0 com.android.launcher/.Launcher}\n',
+            stderr: '',
+            exitCode: 0,
+          };
+        }
+        return { stdout: '', stderr: '', exitCode: 0 };
+      },
+      reverse: {
+        ensure: async () => {},
+        remove: async () => {},
+        removeAllOwned: async () => {},
+      },
+    },
+    { serial: 'emulator-5554' },
+    async () => await killAndroidApp(device, 'com.example.app'),
+  );
+
+  assert.deepEqual(calls, [
+    ['shell', 'am', 'kill', 'com.example.app'],
+    ['shell', 'dumpsys', 'window', 'windows'],
+    ['shell', 'pidof', 'com.example.app'],
+    ['shell', 'pidof', 'com.example.app'],
+  ]);
+});
+
 test('openAndroidApp ensures Android reverse before localhost deep link launch', async () => {
   const device: DeviceInfo = {
     platform: 'android',
diff --git a/packages/platform-android/src/app-lifecycle.ts b/packages/platform-android/src/app-lifecycle.ts
index c5880ce5fb..c02cb89c0d 100644
--- a/packages/platform-android/src/app-lifecycle.ts
+++ b/packages/platform-android/src/app-lifecycle.ts
@@ -488,6 +488,26 @@ export async function closeAndroidApp(device: DeviceInfo, app: string): Promise<
   await waitForAndroidPackageStopped(device, resolved.value);
 }
 
+/**
+ * Maestro `killApp` on Android: system-initiated process death (`am kill`),
+ * which only reaps a backgrounded/cached process — unlike `closeAndroidApp`'s
+ * `am force-stop`. Callers background the app first (e.g. `pressKey: Home`).
+ */
+export async function killAndroidApp(device: DeviceInfo, app: string): Promise<void> {
+  const trimmed = app.trim();
+  if (trimmed.toLowerCase() === 'settings') {
+    await runAndroidShell(device, ['am', 'kill', 'com.android.settings']);
+    await waitForAndroidPackageStopped(device, 'com.android.settings');
+    return;
+  }
+  const resolved = await resolveAndroidApp(device, app);
+  if (resolved.type === 'intent') {
+    throw new AppError('INVALID_ARGS', 'Kill requires a package name, not an intent');
+  }
+  await runAndroidShell(device, ['am', 'kill', resolved.value]);
+  await waitForAndroidPackageStopped(device, resolved.value);
+}
+
 async function waitForAndroidPackageStopped(
   device: DeviceInfo,
   packageName: string,
diff --git a/packages/platform-android/src/lifecycle.ts b/packages/platform-android/src/lifecycle.ts
index d6db533324..8ccc907590 100644
--- a/packages/platform-android/src/lifecycle.ts
+++ b/packages/platform-android/src/lifecycle.ts
@@ -70,6 +70,7 @@ export function bindAndroidApplicationLifecycle(
         device,
         interactor: await binding.resolveInteractor(input.execution, input.appBundleId),
         positionals: input.positionals,
+        mode: input.mode,
       });
     },
     finalizeApplicationClose: async (input) => {
diff --git a/packages/platform-android/src/mechanics.ts b/packages/platform-android/src/mechanics.ts
index 96efabf755..43b5dfa3f9 100644
--- a/packages/platform-android/src/mechanics.ts
+++ b/packages/platform-android/src/mechanics.ts
@@ -83,6 +83,7 @@ export async function listAndroidAppsWithAdb(
 export {
   closeAndroidApp,
   isAmStartError,
+  killAndroidApp,
   openAndroidApp,
   openAndroidDevice,
   parseAndroidLaunchComponent,
diff --git a/scripts/fuzz/validation-arbitraries-maestro.ts b/scripts/fuzz/validation-arbitraries-maestro.ts
index 1507debbcc..6b47745bb7 100644
--- a/scripts/fuzz/validation-arbitraries-maestro.ts
+++ b/scripts/fuzz/validation-arbitraries-maestro.ts
@@ -22,6 +22,8 @@ function validMaestroCommand(pick: number, salt: number): string[] {
     () => ['- back'],
     () => ['- hideKeyboard'],
     () => ['- stopApp'],
+    () => ['- killApp'],
+    () => [`- killApp: ${text}`],
     () => ['- clearState'],
     () => [`- clearState: ${text}`],
     () => ['- scroll'],
diff --git a/src/core/interactors/android.ts b/src/core/interactors/android.ts
index 84e1684ac5..c864e241c8 100644
--- a/src/core/interactors/android.ts
+++ b/src/core/interactors/android.ts
@@ -11,6 +11,7 @@ import {
   getAndroidKeyboardState,
   handleAndroidAlert,
   homeAndroid,
+  killAndroidApp,
   longPressAndroid,
   openAndroidApp,
   openAndroidDevice,
@@ -69,6 +70,7 @@ export function createAndroidInteractor(
       }),
     openDevice: () => openAndroidDevice(device),
     close: (app) => closeAndroidApp(device, app),
+    kill: (app) => killAndroidApp(device, app),
     tap: (x, y) => pressAndroid(device, x, y),
     doubleTap: async (x, y) => {
       await pressAndroid(device, x, y);
diff --git a/src/daemon/replay/internal/__tests__/session-replay-maestro-request.test.ts b/src/daemon/replay/internal/__tests__/session-replay-maestro-request.test.ts
index 8102fab292..df2948d92a 100644
--- a/src/daemon/replay/internal/__tests__/session-replay-maestro-request.test.ts
+++ b/src/daemon/replay/internal/__tests__/session-replay-maestro-request.test.ts
@@ -102,6 +102,19 @@ test('folds Maestro settings app targeting into dispatch', () => {
   expect(request.dispatch).toEqual({ settingsAppBundleId: 'com.example.app' });
 });
 
+test('folds Maestro killApp targeting into dispatch', () => {
+  const request = maestroOperationDispatchRequest(
+    { token: 'token', session: 'session', command: 'replay', positionals: [] },
+    {
+      command: 'close',
+      positionals: ['com.example.app'],
+      dispatch: { closeAppOnly: true, killApp: true },
+    },
+  );
+
+  expect(request.dispatch).toEqual({ closeAppOnly: true, killApp: true });
+});
+
 test('leaves dispatch options the operation does not set untouched', () => {
   const viewport = { x: 0, y: 0, width: 402, height: 874 };
   const request = maestroOperationDispatchRequest(
diff --git a/src/daemon/replay/internal/session-replay-maestro-request.ts b/src/daemon/replay/internal/session-replay-maestro-request.ts
index a95e077f2d..5aefbf320a 100644
--- a/src/daemon/replay/internal/session-replay-maestro-request.ts
+++ b/src/daemon/replay/internal/session-replay-maestro-request.ts
@@ -39,6 +39,7 @@ function maestroDispatchOptions(
 ): Pick<ReplayDispatchOptions, keyof MaestroDaemonDispatchOptions> {
   return stripUndefined({
     closeAppOnly: dispatch?.closeAppOnly,
+    killApp: dispatch?.killApp,
     observationOnly: dispatch?.observationOnly,
     gestureViewport: dispatch?.gestureViewport,
     gestureExecutionProfile: dispatch?.gestureExecutionProfile,
diff --git a/src/daemon/session-lifecycle/internal/__tests__/session-close-lifecycle-runtime.test.ts b/src/daemon/session-lifecycle/internal/__tests__/session-close-lifecycle-runtime.test.ts
index 7ca47b926c..dcfc5631a6 100644
--- a/src/daemon/session-lifecycle/internal/__tests__/session-close-lifecycle-runtime.test.ts
+++ b/src/daemon/session-lifecycle/internal/__tests__/session-close-lifecycle-runtime.test.ts
@@ -319,6 +319,56 @@ test('a supported Android close clears admitted runtime hints exactly once', asy
   );
 });
 
+test('an app-only kill close carries mode kill while a stop close carries none', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'android-app-only-kill-carries-mode';
+  const device = {
+    platform: 'android' as const,
+    id: 'emulator-5554',
+    name: 'Pixel',
+    kind: 'emulator' as const,
+    target: 'mobile' as const,
+    booted: true,
+  };
+  const session = makeSession(sessionName, device);
+  session.appBundleId = 'com.example.app';
+  sessionStore.set(sessionName, session);
+  const seenModes: Array<unknown> = [];
+  const baseBind = mockBindDeviceRuntime.getMockImplementation();
+  mockBindDeviceRuntime.mockImplementation(async (boundDevice, use) => {
+    const binding = await baseBind!(boundDevice, use);
+    const innerClose = binding.operations.closeApplication;
+    if (!innerClose) return binding;
+    return {
+      ...binding,
+      operations: {
+        ...binding.operations,
+        closeApplication: async (input: Parameters<typeof innerClose>[0]) => {
+          seenModes.push(input.mode);
+          return await innerClose(input);
+        },
+      },
+    };
+  });
+
+  const killed = await close({
+    sessionName,
+    sessionStore,
+    positionals: ['com.example.app'],
+    internal: { closeAppOnly: true, killApp: true },
+  });
+  const stopped = await close({
+    sessionName,
+    sessionStore,
+    positionals: ['com.example.app'],
+    internal: { closeAppOnly: true },
+  });
+
+  expect(killed?.ok).toBe(true);
+  expect(stopped?.ok).toBe(true);
+  expect(seenModes).toEqual(['kill', undefined]);
+});
+
 test('close expires the ref frame immediately before its admitted platform mutation', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'close-ref-frame-seam';
diff --git a/src/daemon/session-lifecycle/internal/session-close.ts b/src/daemon/session-lifecycle/internal/session-close.ts
index 889cc5016b..1e603d89fd 100644
--- a/src/daemon/session-lifecycle/internal/session-close.ts
+++ b/src/daemon/session-lifecycle/internal/session-close.ts
@@ -149,6 +149,7 @@ async function dispatchTargetedPlatformClose(params: {
       outPath: req.flags?.out,
       appBundleId: session.appBundleId,
       surface: session.surface ?? 'app',
+      ...(req.internal?.killApp === true ? { mode: 'kill' as const } : {}),
       execution: applicationLifecycleExecutionFromRequest(req, logPath, session.trace?.outPath),
     });
     return undefined;
diff --git a/website/docs/docs/replay-e2e.md b/website/docs/docs/replay-e2e.md
index 304ec141da..e86b3f66db 100644
--- a/website/docs/docs/replay-e2e.md
+++ b/website/docs/docs/replay-e2e.md
@@ -72,7 +72,7 @@ Supported subset:
 
 - Flows: `launchApp` (with `clearState`, `permissions`, and Apple-only launch arguments; `permissions` apply after state clearing but before launch, and a `launchApp` without `permissions` touches nothing — there is no silent `all: allow` default); `setPermissions` (mid-flow permission grants, denials, and resets; `all` resolves in the backend — one simctl call on iOS, the declared permissions on Android — with specific entries overriding after it); `runFlow` file/inline with platform, visibility, and limited boolean conditions; `onFlowStart`/`onFlowComplete`; `repeat.times` and retry.
 - Interactions: `tapOn`, `doubleTapOn`, `longPressOn`, `inputText` on the focused element, `eraseText`, `openLink`, `hideKeyboard`, basic `pressKey`, and `back`; selector targets poll until available and support recursive `index`, `childOf`, `above`, `below`, `leftOf`, `rightOf`, `containsChild`, `containsDescendants`, points, and `optional`; outer command labels are metadata, not target selectors.
-- Assertions and navigation: `assertVisible`, `assertNotVisible`, `assertTrue` (literal values and `${VAR}` lookups only; `""`, `"false"`, `"0"`, `"null"`, and `"undefined"` are falsy, everything else is truthy), `extendedWaitUntil`, `scroll`, `scrollUntilVisible`, absolute/percentage/target `swipe`, `takeScreenshot`, `waitForAnimationToEnd`, `clearState`, and `stopApp`.
+- Assertions and navigation: `assertVisible`, `assertNotVisible`, `assertTrue` (literal values and `${VAR}` lookups only; `""`, `"false"`, `"0"`, `"null"`, and `"undefined"` are falsy, everything else is truthy), `extendedWaitUntil`, `scroll`, `scrollUntilVisible`, absolute/percentage/target `swipe`, `takeScreenshot`, `waitForAnimationToEnd`, `clearState`, `stopApp`, and `killApp` (system-initiated process death: `am kill` on Android, `stopApp` alias elsewhere).
 - Scripts: ordered `runScript` file/env scripts with `http.post`, `json`, and `output` variables; `evalScript` inline expressions run flow-scoped JavaScript and write `output.*` leaves for later steps.
 
 Boundaries:

From 0fe63737448e1889f9bba263c0a75752768aa6e8 Mon Sep 17 00:00:00 2001
From: Rohit <40559587+Rohit3523@users.noreply.github.com>
Date: Tue, 22 Sep 2026 03:34:43 +0530
Subject: [PATCH 123/132] refactor(maestro): table-drive app-target lifecycle
 dispatch

executeLifecycleCommand grew a sixth case for killApp and tripped the
complexity gate. The stopApp/killApp/clearState legs share one shape,
so dispatch them through a lookup instead of three switch cases.
---
 .../src/internal/runtime-port-commands.ts     | 39 +++++++++----------
 1 file changed, 19 insertions(+), 20 deletions(-)

diff --git a/packages/maestro/src/internal/runtime-port-commands.ts b/packages/maestro/src/internal/runtime-port-commands.ts
index e398600ee1..7c71f57124 100644
--- a/packages/maestro/src/internal/runtime-port-commands.ts
+++ b/packages/maestro/src/internal/runtime-port-commands.ts
@@ -131,6 +131,19 @@ function dispatchMaestroRuntimeCommand<K extends MaestroCommandKind>(
   return handler(command, request, operations, context);
 }
 
+type MaestroAppTargetLifecycleCommand = MaestroCommandOf<'stopApp' | 'killApp' | 'clearState'>;
+
+/** Lifecycle commands carrying only an app target share one dispatch shape. */
+const MAESTRO_APP_TARGET_OPERATIONS: {
+  [K in MaestroAppTargetLifecycleCommand['kind']]: (
+    operations: MaestroRuntimeOperations,
+  ) => MaestroRuntimeOperations[K];
+} = {
+  stopApp: (operations) => operations.stopApp,
+  killApp: (operations) => operations.killApp,
+  clearState: (operations) => operations.clearState,
+};
+
 async function executeLifecycleCommand(
   command: MaestroLifecycleCommand,
   request: MaestroRuntimeRequest,
@@ -145,20 +158,6 @@ async function executeLifecycleCommand(
         context,
         'invalidate',
       );
-    case 'stopApp':
-      return await invokeOperation(
-        operations.stopApp,
-        { appId: command.appId ?? request.appId },
-        context,
-        'invalidate',
-      );
-    case 'killApp':
-      return await invokeOperation(
-        operations.killApp,
-        { appId: command.appId ?? request.appId },
-        context,
-        'invalidate',
-      );
     case 'setPermissions':
       return await invokeOperation(
         operations.setPermissions,
@@ -169,17 +168,17 @@ async function executeLifecycleCommand(
         context,
         'invalidate',
       );
-    case 'clearState':
+    case 'openLink':
       return await invokeOperation(
-        operations.clearState,
-        { appId: command.appId ?? request.appId },
+        operations.openLink,
+        { link: command.link },
         context,
         'invalidate',
       );
-    case 'openLink':
+    default:
       return await invokeOperation(
-        operations.openLink,
-        { link: command.link },
+        MAESTRO_APP_TARGET_OPERATIONS[command.kind](operations),
+        { appId: command.appId ?? request.appId },
         context,
         'invalidate',
       );

From c63b1c83a0cddd957339e9b98ed70a0cf9dbceb9 Mon Sep 17 00:00:00 2001
From: Rohit <40559587+Rohit3523@users.noreply.github.com>
Date: Tue, 22 Sep 2026 03:43:30 +0530
Subject: [PATCH 124/132] fix(maestro): fail killApp loud when the target
 survives

am kill only reaps background processes, so a foreground killApp used
to succeed without killing anything. Refuse a foreground target naming
the background-first precondition, and verify the process is gone after
the kill instead of reporting an unproven success.
---
 .../src/__tests__/app-lifecycle-open.test.ts  | 95 +++++++++++++++++++
 .../platform-android/src/app-lifecycle.ts     | 26 ++++-
 2 files changed, 117 insertions(+), 4 deletions(-)

diff --git a/packages/platform-android/src/__tests__/app-lifecycle-open.test.ts b/packages/platform-android/src/__tests__/app-lifecycle-open.test.ts
index 78b92e563a..ac270f8fe5 100644
--- a/packages/platform-android/src/__tests__/app-lifecycle-open.test.ts
+++ b/packages/platform-android/src/__tests__/app-lifecycle-open.test.ts
@@ -196,13 +196,108 @@ test('killAndroidApp dispatches am kill rather than am force-stop', async () =>
   );
 
   assert.deepEqual(calls, [
+    ['shell', 'dumpsys', 'window', 'windows'],
     ['shell', 'am', 'kill', 'com.example.app'],
     ['shell', 'dumpsys', 'window', 'windows'],
     ['shell', 'pidof', 'com.example.app'],
     ['shell', 'pidof', 'com.example.app'],
+    ['shell', 'pidof', 'com.example.app'],
   ]);
 });
 
+test('killAndroidApp refuses a foreground target before killing', async () => {
+  const device: DeviceInfo = {
+    platform: 'android',
+    id: 'emulator-5554',
+    name: 'Pixel',
+    kind: 'emulator',
+    booted: true,
+  };
+  const calls: (readonly string[])[] = [];
+
+  await withAndroidAdbProvider(
+    {
+      exec: async (args) => {
+        calls.push(args);
+        if (args.join(' ') === 'shell dumpsys window windows') {
+          return {
+            stdout: 'mCurrentFocus=Window{42 u0 com.example.app/.MainActivity}\n',
+            stderr: '',
+            exitCode: 0,
+          };
+        }
+        return { stdout: '', stderr: '', exitCode: 0 };
+      },
+      reverse: {
+        ensure: async () => {},
+        remove: async () => {},
+        removeAllOwned: async () => {},
+      },
+    },
+    { serial: 'emulator-5554' },
+    async () => {
+      await assertRejectsAppError(() => killAndroidApp(device, 'com.example.app'), {
+        code: 'COMMAND_FAILED',
+        hint: /Background the app before killApp/,
+      });
+      try {
+        await killAndroidApp(device, 'com.example.app');
+        assert.fail('expected killAndroidApp to reject for a foreground app');
+      } catch (error) {
+        assert.equal(
+          (error as InstanceType<typeof AppError>).details?.reason,
+          'android-kill-requires-background-app',
+        );
+      }
+    },
+  );
+
+  assert.deepEqual(calls, [
+    ['shell', 'dumpsys', 'window', 'windows'],
+    ['shell', 'dumpsys', 'window', 'windows'],
+  ]);
+});
+
+test('killAndroidApp fails when the process survives the kill', async () => {
+  const device: DeviceInfo = {
+    platform: 'android',
+    id: 'emulator-5554',
+    name: 'Pixel',
+    kind: 'emulator',
+    booted: true,
+  };
+
+  await withAndroidAdbProvider(
+    {
+      exec: async (args) => {
+        if (args.join(' ') === 'shell dumpsys window windows') {
+          return {
+            stdout: 'mCurrentFocus=Window{43 u0 com.android.launcher/.Launcher}\n',
+            stderr: '',
+            exitCode: 0,
+          };
+        }
+        if (args.join(' ') === 'shell pidof com.example.app') {
+          return { stdout: '12345\n', stderr: '', exitCode: 0 };
+        }
+        return { stdout: '', stderr: '', exitCode: 0 };
+      },
+      reverse: {
+        ensure: async () => {},
+        remove: async () => {},
+        removeAllOwned: async () => {},
+      },
+    },
+    { serial: 'emulator-5554' },
+    async () => {
+      await assertRejectsAppError(() => killAndroidApp(device, 'com.example.app'), {
+        code: 'COMMAND_FAILED',
+        hint: /Background the app before killApp/,
+      });
+    },
+  );
+});
+
 test('openAndroidApp ensures Android reverse before localhost deep link launch', async () => {
   const device: DeviceInfo = {
     platform: 'android',
diff --git a/packages/platform-android/src/app-lifecycle.ts b/packages/platform-android/src/app-lifecycle.ts
index c02cb89c0d..6b3072fb05 100644
--- a/packages/platform-android/src/app-lifecycle.ts
+++ b/packages/platform-android/src/app-lifecycle.ts
@@ -492,20 +492,38 @@ export async function closeAndroidApp(device: DeviceInfo, app: string): Promise<
  * Maestro `killApp` on Android: system-initiated process death (`am kill`),
  * which only reaps a backgrounded/cached process — unlike `closeAndroidApp`'s
  * `am force-stop`. Callers background the app first (e.g. `pressKey: Home`).
+ * A foreground target fails loud naming the precondition, and a process that
+ * survives the kill fails rather than reading as success.
  */
 export async function killAndroidApp(device: DeviceInfo, app: string): Promise<void> {
   const trimmed = app.trim();
   if (trimmed.toLowerCase() === 'settings') {
-    await runAndroidShell(device, ['am', 'kill', 'com.android.settings']);
-    await waitForAndroidPackageStopped(device, 'com.android.settings');
+    await killAndroidPackage(device, 'com.android.settings');
     return;
   }
   const resolved = await resolveAndroidApp(device, app);
   if (resolved.type === 'intent') {
     throw new AppError('INVALID_ARGS', 'Kill requires a package name, not an intent');
   }
-  await runAndroidShell(device, ['am', 'kill', resolved.value]);
-  await waitForAndroidPackageStopped(device, resolved.value);
+  await killAndroidPackage(device, resolved.value);
+}
+
+async function killAndroidPackage(device: DeviceInfo, packageName: string): Promise<void> {
+  const foreground = await readAndroidForegroundApp(device);
+  if (foreground?.package === packageName) {
+    throw new AppError('COMMAND_FAILED', `Cannot kill foreground app ${packageName}`, {
+      reason: 'android-kill-requires-background-app',
+      hint: 'Background the app before killApp (for example pressKey: Home): am kill only reaps background processes.',
+    });
+  }
+  await runAndroidShell(device, ['am', 'kill', packageName]);
+  await waitForAndroidPackageStopped(device, packageName);
+  if (await isAndroidPackageProcessRunning(device, packageName)) {
+    throw new AppError('COMMAND_FAILED', `am kill did not stop ${packageName}`, {
+      reason: 'android-kill-requires-background-app',
+      hint: 'Background the app before killApp (for example pressKey: Home): am kill only reaps background processes.',
+    });
+  }
 }
 
 async function waitForAndroidPackageStopped(

From 05128d859560f963afeede8370007c1b0c79c4b5 Mon Sep 17 00:00:00 2001
From: Rohit <40559587+Rohit3523@users.noreply.github.com>
Date: Fri, 25 Sep 2026 08:54:39 +0530
Subject: [PATCH 125/132] fix(maestro): address killApp review feedback

Distinct survived-kill reason, direct Android kill without shared Interactor change, foreground-refusal docs, exhaustive lifecycle dispatch.
---
 .../application-lifecycle-interaction.test.ts |  47 --------
 .../src/application-lifecycle-interaction.ts  |   8 +-
 .../src/application-lifecycle-runtime.ts      |   7 +-
 packages/contracts/src/interactor-types.ts    |   6 -
 .../src/internal/runtime-port-commands.ts     |  11 +-
 .../maestro/src/internal/support-matrix.ts    |   2 +-
 .../src/__tests__/app-lifecycle-open.test.ts  |  11 +-
 .../platform-android/src/app-lifecycle.ts     |   4 +-
 .../platform-android/src/lifecycle.test.ts    | 106 ++++++++++++++++++
 packages/platform-android/src/lifecycle.ts    |   7 +-
 src/core/interactors/android.ts               |   2 -
 website/docs/docs/replay-e2e.md               |   2 +-
 12 files changed, 141 insertions(+), 72 deletions(-)

diff --git a/packages/contracts/src/application-lifecycle-interaction.test.ts b/packages/contracts/src/application-lifecycle-interaction.test.ts
index 662aca9474..2e42310f7c 100644
--- a/packages/contracts/src/application-lifecycle-interaction.test.ts
+++ b/packages/contracts/src/application-lifecycle-interaction.test.ts
@@ -5,7 +5,6 @@ import type { OpenApplicationInput } from './application-lifecycle-runtime.ts';
 import {
   bindDirectApplicationLifecycle,
   bindLocalApplicationLifecycleInteractor,
-  invokeApplicationClose,
   invokeApplicationOpen,
 } from './application-lifecycle-interaction.ts';
 
@@ -92,52 +91,6 @@ test('direct lifecycle owners preserve the daemon runtime launch URL follow-up',
   expect(calls[1]?.options).toHaveProperty('launchArgs', undefined);
 });
 
-test('kill mode dispatches Interactor.kill when the owner implements it', async () => {
-  const calls: string[] = [];
-  const interactor: Interactor = {
-    ...interactorWithOpen(),
-    close: async (app) => {
-      calls.push(`close:${app}`);
-    },
-    kill: async (app) => {
-      calls.push(`kill:${app}`);
-    },
-  };
-
-  await invokeApplicationClose({
-    device: LINUX_DEVICE,
-    interactor,
-    positionals: ['com.example.app'],
-    mode: 'kill',
-  });
-
-  expect(calls).toEqual(['kill:com.example.app']);
-});
-
-test('kill mode falls back to close when the owner has no kill', async () => {
-  const calls: string[] = [];
-  const interactor: Interactor = {
-    ...interactorWithOpen(),
-    close: async (app) => {
-      calls.push(`close:${app}`);
-    },
-  };
-
-  await invokeApplicationClose({
-    device: LINUX_DEVICE,
-    interactor,
-    positionals: ['com.example.app'],
-    mode: 'kill',
-  });
-  await invokeApplicationClose({
-    device: LINUX_DEVICE,
-    interactor,
-    positionals: ['com.example.app'],
-  });
-
-  expect(calls).toEqual(['close:com.example.app', 'close:com.example.app']);
-});
-
 test.each([
   {
     name: 'more than two positionals',
diff --git a/packages/contracts/src/application-lifecycle-interaction.ts b/packages/contracts/src/application-lifecycle-interaction.ts
index c82d7ce814..0db4ce162f 100644
--- a/packages/contracts/src/application-lifecycle-interaction.ts
+++ b/packages/contracts/src/application-lifecycle-interaction.ts
@@ -370,19 +370,13 @@ export async function invokeApplicationClose(
     device: DeviceInfo;
     interactor: Interactor;
     positionals: readonly string[];
-    /** `kill` dispatches `Interactor.kill` with fallback to `close`; absent means `stop`. */
-    mode?: 'stop' | 'kill';
   }>,
 ): Promise<void> {
-  const { device, interactor, positionals, mode } = params;
+  const { device, interactor, positionals } = params;
   const app = positionals[0];
   if (!app) {
     if (device.platform === 'web') await interactor.close('');
     return;
   }
-  if (mode === 'kill' && interactor.kill) {
-    await interactor.kill(app);
-    return;
-  }
   await interactor.close(app);
 }
diff --git a/packages/contracts/src/application-lifecycle-runtime.ts b/packages/contracts/src/application-lifecycle-runtime.ts
index 31f237122c..bb3ea6387b 100644
--- a/packages/contracts/src/application-lifecycle-runtime.ts
+++ b/packages/contracts/src/application-lifecycle-runtime.ts
@@ -180,10 +180,11 @@ export type CloseApplicationInput = Readonly<{
   ensureReady?: boolean;
   /**
    * `kill` is Maestro `killApp` (system-initiated process death: `am kill` on
-   * Android); absent means `stop`. Owners without an `Interactor.kill` alias
-   * it to `close` in the shared dispatcher.
+   * Android); absent means `stop`. Only the Android owner reads it and calls
+   * its own kill; owners that ignore it keep `force-stop`, which is the
+   * `stopApp` alias Maestro uses elsewhere (iOS included).
    */
-  mode?: 'stop' | 'kill';
+  mode?: 'kill';
   execution: ApplicationLifecycleExecution;
 }>;
 
diff --git a/packages/contracts/src/interactor-types.ts b/packages/contracts/src/interactor-types.ts
index b714ea7a09..15670d675b 100644
--- a/packages/contracts/src/interactor-types.ts
+++ b/packages/contracts/src/interactor-types.ts
@@ -290,12 +290,6 @@ export type Interactor = {
   ): Promise<void>;
   openDevice(): Promise<void>;
   close(app: string): Promise<void>;
-  /**
-   * System-initiated process death (Maestro `killApp`): on Android `am kill`
-   * rather than `am force-stop`. Owners without a lighter-weight kill leave
-   * it undefined and the shared close dispatcher falls back to `close(app)`.
-   */
-  kill?(app: string): Promise<void>;
   tap(x: number, y: number): Promise<Record<string, unknown> | void>;
   /** Complete point-press semantics for owners with fused series, alternate buttons, or surfaces. */
   pressPoint?(point: Point, options: PressPointOptions): Promise<Record<string, unknown> | void>;
diff --git a/packages/maestro/src/internal/runtime-port-commands.ts b/packages/maestro/src/internal/runtime-port-commands.ts
index 7c71f57124..628ee6397d 100644
--- a/packages/maestro/src/internal/runtime-port-commands.ts
+++ b/packages/maestro/src/internal/runtime-port-commands.ts
@@ -175,13 +175,22 @@ async function executeLifecycleCommand(
         context,
         'invalidate',
       );
-    default:
+    case 'stopApp':
+    case 'killApp':
+    case 'clearState':
       return await invokeOperation(
         MAESTRO_APP_TARGET_OPERATIONS[command.kind](operations),
         { appId: command.appId ?? request.appId },
         context,
         'invalidate',
       );
+    default: {
+      const exhaustive: never = command;
+      throw new AppError(
+        'COMMAND_FAILED',
+        `Unsupported Maestro lifecycle command ${(exhaustive as { kind: string }).kind}.`,
+      );
+    }
   }
 }
 
diff --git a/packages/maestro/src/internal/support-matrix.ts b/packages/maestro/src/internal/support-matrix.ts
index dd265a7eaf..54eaa300d4 100644
--- a/packages/maestro/src/internal/support-matrix.ts
+++ b/packages/maestro/src/internal/support-matrix.ts
@@ -1,7 +1,7 @@
 export const MAESTRO_COMPAT_SUPPORTED_CAPABILITIES = [
   'Flows: launchApp (with clearState, permissions, and Apple-only launch arguments; permissions apply after state clearing but before launch, and a launchApp without permissions touches nothing — there is no silent all: allow default); setPermissions (mid-flow permission grants, denials, and resets; all resolves in the backend — one simctl call on iOS, the declared permissions on Android — with specific entries overriding after it); runFlow file/inline with platform, visibility, and limited boolean conditions; onFlowStart/onFlowComplete; repeat.times and retry.',
   'Interactions: tapOn, doubleTapOn, longPressOn, inputText on the focused element, eraseText, openLink, hideKeyboard, basic pressKey, and back; selector targets poll until available and support recursive index, childOf, above, below, leftOf, rightOf, containsChild, containsDescendants, points, and optional; outer command labels are metadata, not target selectors.',
-  'Assertions and navigation: assertVisible, assertNotVisible, assertTrue (literal values and ${VAR} lookups only; "", "false", "0", "null", and "undefined" are falsy, everything else is truthy), extendedWaitUntil, scroll, scrollUntilVisible, absolute/percentage/target swipe, takeScreenshot, waitForAnimationToEnd, clearState, stopApp, and killApp (system-initiated process death: am kill on Android, stopApp alias elsewhere).',
+  'Assertions and navigation: assertVisible, assertNotVisible, assertTrue (literal values and ${VAR} lookups only; "", "false", "0", "null", and "undefined" are falsy, everything else is truthy), extendedWaitUntil, scroll, scrollUntilVisible, absolute/percentage/target swipe, takeScreenshot, waitForAnimationToEnd, clearState, stopApp, and killApp (system-initiated process death: am kill on Android, stopApp alias elsewhere; Android refuses a foreground target with android-kill-requires-background-app — background the app first, for example pressKey: Home — and fails a backgrounded target whose process survives with android-kill-process-survived).',
   'Scripts: ordered runScript file/env scripts with http.post, json, and output variables; evalScript inline expressions run flow-scoped JavaScript and write output.* leaves for later steps.',
 ] as const;
 
diff --git a/packages/platform-android/src/__tests__/app-lifecycle-open.test.ts b/packages/platform-android/src/__tests__/app-lifecycle-open.test.ts
index ac270f8fe5..f8b0dd9886 100644
--- a/packages/platform-android/src/__tests__/app-lifecycle-open.test.ts
+++ b/packages/platform-android/src/__tests__/app-lifecycle-open.test.ts
@@ -292,8 +292,17 @@ test('killAndroidApp fails when the process survives the kill', async () => {
     async () => {
       await assertRejectsAppError(() => killAndroidApp(device, 'com.example.app'), {
         code: 'COMMAND_FAILED',
-        hint: /Background the app before killApp/,
+        hint: /foreground service|force-stop/,
       });
+      try {
+        await killAndroidApp(device, 'com.example.app');
+        assert.fail('expected killAndroidApp to reject when the process survives');
+      } catch (error) {
+        assert.equal(
+          (error as InstanceType<typeof AppError>).details?.reason,
+          'android-kill-process-survived',
+        );
+      }
     },
   );
 });
diff --git a/packages/platform-android/src/app-lifecycle.ts b/packages/platform-android/src/app-lifecycle.ts
index 6b3072fb05..ebe92fc393 100644
--- a/packages/platform-android/src/app-lifecycle.ts
+++ b/packages/platform-android/src/app-lifecycle.ts
@@ -520,8 +520,8 @@ async function killAndroidPackage(device: DeviceInfo, packageName: string): Prom
   await waitForAndroidPackageStopped(device, packageName);
   if (await isAndroidPackageProcessRunning(device, packageName)) {
     throw new AppError('COMMAND_FAILED', `am kill did not stop ${packageName}`, {
-      reason: 'android-kill-requires-background-app',
-      hint: 'Background the app before killApp (for example pressKey: Home): am kill only reaps background processes.',
+      reason: 'android-kill-process-survived',
+      hint: 'The app was backgrounded but its process survived am kill (for example a foreground service is still running): use stopApp (am force-stop) to terminate it.',
     });
   }
 }
diff --git a/packages/platform-android/src/lifecycle.test.ts b/packages/platform-android/src/lifecycle.test.ts
index d8c6aca244..1b9c4efcf0 100644
--- a/packages/platform-android/src/lifecycle.test.ts
+++ b/packages/platform-android/src/lifecycle.test.ts
@@ -1,5 +1,6 @@
 import { afterEach, expect, test, vi } from 'vitest';
 import type {
+  CloseApplicationInput,
   LocalApplicationInteractorHost,
   OpenApplicationInput,
 } from '@agent-device/contracts/application-lifecycle-runtime';
@@ -8,6 +9,13 @@ import type { Interactor, SnapshotOptions } from '@agent-device/contracts/intera
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import { AppError, createRequestCanceledError } from '@agent-device/kernel/errors';
 import { bindAndroidApplicationLifecycle } from './lifecycle.ts';
+import { killAndroidApp } from './app-lifecycle.ts';
+
+vi.mock('./app-lifecycle.ts', () => ({
+  killAndroidApp: vi.fn(async () => {}),
+}));
+
+const mockKillAndroidApp = vi.mocked(killAndroidApp);
 
 const device: DeviceInfo = {
   platform: 'android',
@@ -20,6 +28,7 @@ const device: DeviceInfo = {
 
 afterEach(() => {
   vi.restoreAllMocks();
+  mockKillAndroidApp.mockClear();
 });
 
 type LifecycleFixture = Readonly<{
@@ -212,3 +221,100 @@ test('an app open whose launched package cannot be identified reports it unident
   expect(calls).toEqual(['open:Example']);
   expect(outcome.timing.postOpenObservation).toBe('app-unidentified');
 });
+
+function closeLifecycleHost(resolve: LocalApplicationInteractorHost['resolve']) {
+  return {
+    localInteractors: { resolve },
+    deviceReadiness: {
+      android: { ensureReady: async () => ({ ...device, booted: true }) },
+    },
+    deviceShutdown: {
+      android: { shutdownTarget: async () => undefined },
+    },
+    androidApplications: {
+      resolveOpenTarget: async () => ({}),
+      inferOpenedAppBundleId: async () => 'com.example.app',
+      resetFramePerfStats: async () => {},
+      applyRuntimeHints: async () => {},
+      clearRuntimeHints: async () => {},
+      activateTestIme: async () => {},
+      restoreTestIme: async () => {},
+      recoverTestImeStartup: async () => {},
+      hasTestImeRecoveryEvidence: async () => false,
+    },
+  } as unknown as Pick<
+    PlatformRuntimeHost,
+    | 'androidApplications'
+    | 'clock'
+    | 'commands'
+    | 'deviceReadiness'
+    | 'deviceShutdown'
+    | 'localInteractors'
+    | 'toolchains'
+  >;
+}
+
+function closeInput(overrides: Partial<CloseApplicationInput> = {}): CloseApplicationInput {
+  return {
+    positionals: ['com.example.app'],
+    appBundleId: 'com.example.app',
+    surface: 'app',
+    execution: {},
+    ...overrides,
+  };
+}
+
+test('kill mode calls killAndroidApp without resolving an interactor', async () => {
+  let resolved = 0;
+  const closed: string[] = [];
+  const host = closeLifecycleHost(async () => {
+    resolved += 1;
+    return {
+      open: async () => {},
+      openDevice: async () => {},
+      close: async (app: string) => {
+        closed.push(app);
+      },
+      setSetting: async () => {},
+    } as unknown as Interactor;
+  });
+  const lifecycle = bindAndroidApplicationLifecycle({
+    host,
+    device,
+    signal: new AbortController().signal,
+  });
+
+  await lifecycle.closeApplication(closeInput({ mode: 'kill' }));
+
+  expect(resolved).toBe(0);
+  expect(closed).toEqual([]);
+  expect(mockKillAndroidApp).toHaveBeenCalledOnce();
+  expect(mockKillAndroidApp).toHaveBeenCalledWith(device, 'com.example.app');
+});
+
+test('stop close resolves an interactor and closes', async () => {
+  let resolved = 0;
+  const closed: string[] = [];
+  const host = closeLifecycleHost(async () => {
+    resolved += 1;
+    return {
+      open: async () => {},
+      openDevice: async () => {},
+      close: async (app: string) => {
+        closed.push(app);
+      },
+      setSetting: async () => {},
+    } as unknown as Interactor;
+  });
+  const lifecycle = bindAndroidApplicationLifecycle({
+    host,
+    device,
+    signal: new AbortController().signal,
+  });
+
+  await lifecycle.closeApplication(closeInput());
+
+  expect(resolved).toBe(1);
+  expect(closed).toEqual(['com.example.app']);
+  expect(mockKillAndroidApp).not.toHaveBeenCalled();
+});
diff --git a/packages/platform-android/src/lifecycle.ts b/packages/platform-android/src/lifecycle.ts
index 8ccc907590..365e62a40a 100644
--- a/packages/platform-android/src/lifecycle.ts
+++ b/packages/platform-android/src/lifecycle.ts
@@ -15,6 +15,7 @@ import {
 import { isDeepLinkTarget } from '@agent-device/contracts/command';
 import { observeAndroidLaunch } from './launch-observation.ts';
 import { ensureAndroidReady } from './readiness/runtime.ts';
+import { killAndroidApp } from './app-lifecycle.ts';
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import { AppError } from '@agent-device/kernel/errors';
 
@@ -66,11 +67,15 @@ export function bindAndroidApplicationLifecycle(
       if (input.ensureReady) {
         await ensureAndroidReady(host, device, { headless: false }, signal);
       }
+      if (input.mode === 'kill') {
+        const target = input.positionals[0];
+        if (target) await killAndroidApp(device, target);
+        return;
+      }
       await invokeApplicationClose({
         device,
         interactor: await binding.resolveInteractor(input.execution, input.appBundleId),
         positionals: input.positionals,
-        mode: input.mode,
       });
     },
     finalizeApplicationClose: async (input) => {
diff --git a/src/core/interactors/android.ts b/src/core/interactors/android.ts
index c864e241c8..84e1684ac5 100644
--- a/src/core/interactors/android.ts
+++ b/src/core/interactors/android.ts
@@ -11,7 +11,6 @@ import {
   getAndroidKeyboardState,
   handleAndroidAlert,
   homeAndroid,
-  killAndroidApp,
   longPressAndroid,
   openAndroidApp,
   openAndroidDevice,
@@ -70,7 +69,6 @@ export function createAndroidInteractor(
       }),
     openDevice: () => openAndroidDevice(device),
     close: (app) => closeAndroidApp(device, app),
-    kill: (app) => killAndroidApp(device, app),
     tap: (x, y) => pressAndroid(device, x, y),
     doubleTap: async (x, y) => {
       await pressAndroid(device, x, y);
diff --git a/website/docs/docs/replay-e2e.md b/website/docs/docs/replay-e2e.md
index e86b3f66db..c58aea3a87 100644
--- a/website/docs/docs/replay-e2e.md
+++ b/website/docs/docs/replay-e2e.md
@@ -72,7 +72,7 @@ Supported subset:
 
 - Flows: `launchApp` (with `clearState`, `permissions`, and Apple-only launch arguments; `permissions` apply after state clearing but before launch, and a `launchApp` without `permissions` touches nothing — there is no silent `all: allow` default); `setPermissions` (mid-flow permission grants, denials, and resets; `all` resolves in the backend — one simctl call on iOS, the declared permissions on Android — with specific entries overriding after it); `runFlow` file/inline with platform, visibility, and limited boolean conditions; `onFlowStart`/`onFlowComplete`; `repeat.times` and retry.
 - Interactions: `tapOn`, `doubleTapOn`, `longPressOn`, `inputText` on the focused element, `eraseText`, `openLink`, `hideKeyboard`, basic `pressKey`, and `back`; selector targets poll until available and support recursive `index`, `childOf`, `above`, `below`, `leftOf`, `rightOf`, `containsChild`, `containsDescendants`, points, and `optional`; outer command labels are metadata, not target selectors.
-- Assertions and navigation: `assertVisible`, `assertNotVisible`, `assertTrue` (literal values and `${VAR}` lookups only; `""`, `"false"`, `"0"`, `"null"`, and `"undefined"` are falsy, everything else is truthy), `extendedWaitUntil`, `scroll`, `scrollUntilVisible`, absolute/percentage/target `swipe`, `takeScreenshot`, `waitForAnimationToEnd`, `clearState`, `stopApp`, and `killApp` (system-initiated process death: `am kill` on Android, `stopApp` alias elsewhere).
+- Assertions and navigation: `assertVisible`, `assertNotVisible`, `assertTrue` (literal values and `${VAR}` lookups only; `""`, `"false"`, `"0"`, `"null"`, and `"undefined"` are falsy, everything else is truthy), `extendedWaitUntil`, `scroll`, `scrollUntilVisible`, absolute/percentage/target `swipe`, `takeScreenshot`, `waitForAnimationToEnd`, `clearState`, `stopApp`, and `killApp` (system-initiated process death: `am kill` on Android, `stopApp` alias elsewhere; Android refuses a foreground target with `android-kill-requires-background-app` — background the app first, for example `pressKey: Home` — and fails a backgrounded target whose process survives with `android-kill-process-survived`).
 - Scripts: ordered `runScript` file/env scripts with `http.post`, `json`, and `output` variables; `evalScript` inline expressions run flow-scoped JavaScript and write `output.*` leaves for later steps.
 
 Boundaries:

From 5058165f13b7f8c97f0c159340908313a3512697 Mon Sep 17 00:00:00 2001
From: Rohit <40559587+Rohit3523@users.noreply.github.com>
Date: Fri, 25 Sep 2026 09:39:02 +0530
Subject: [PATCH 126/132] fix(maestro): address cubic killApp review comments

- session-close: propagate kill mode through closeWithoutSession
- android: fail kill closed when foreground probe cannot answer;
  distinguish pidof probe failure from reaped process
- android lifecycle: fall back to session app identity for kill target,
  INVALID_ARGS when no target exists
- tests: single-call reason assertions via details matcher,
  mockImplementationOnce for mode capture, distinct killApp app ids
---
 .../src/application-lifecycle-runtime.ts      |   5 +-
 .../internal/__tests__/runtime-port.test.ts   |   4 +-
 .../src/__tests__/app-lifecycle-open.test.ts  | 142 +++++++++++++++---
 .../src/__tests__/test-utils/app-error.ts     |  12 +-
 .../platform-android/src/app-lifecycle.ts     |  22 ++-
 packages/platform-android/src/lifecycle.ts    |   7 +-
 .../session-close-lifecycle-runtime.test.ts   |   9 +-
 .../internal/session-close.ts                 |   1 +
 8 files changed, 170 insertions(+), 32 deletions(-)

diff --git a/packages/contracts/src/application-lifecycle-runtime.ts b/packages/contracts/src/application-lifecycle-runtime.ts
index bb3ea6387b..b0deb4e05e 100644
--- a/packages/contracts/src/application-lifecycle-runtime.ts
+++ b/packages/contracts/src/application-lifecycle-runtime.ts
@@ -181,8 +181,9 @@ export type CloseApplicationInput = Readonly<{
   /**
    * `kill` is Maestro `killApp` (system-initiated process death: `am kill` on
    * Android); absent means `stop`. Only the Android owner reads it and calls
-   * its own kill; owners that ignore it keep `force-stop`, which is the
-   * `stopApp` alias Maestro uses elsewhere (iOS included).
+   * its own kill, which prefers the positional target and falls back to the
+   * session app identity; owners that ignore it keep `force-stop`, which is
+   * the `stopApp` alias Maestro uses elsewhere (iOS included).
    */
   mode?: 'kill';
   execution: ApplicationLifecycleExecution;
diff --git a/packages/maestro/src/internal/__tests__/runtime-port.test.ts b/packages/maestro/src/internal/__tests__/runtime-port.test.ts
index 24a684acdd..a47f965977 100644
--- a/packages/maestro/src/internal/__tests__/runtime-port.test.ts
+++ b/packages/maestro/src/internal/__tests__/runtime-port.test.ts
@@ -184,7 +184,7 @@ describe('MaestroRuntimePort', () => {
       killApp: vi.fn(async (input, context) => record(calls, 'killApp', input, context)),
     });
     const program = parseMaestroProgram(
-      ['appId: com.example.checkout', '---', '- killApp: com.example.checkout', '- killApp'].join(
+      ['appId: com.example.checkout', '---', '- killApp: com.example.other', '- killApp'].join(
         '\n',
       ),
     );
@@ -193,7 +193,7 @@ describe('MaestroRuntimePort', () => {
 
     expect(result).toMatchObject({ executed: 2, skipped: 0 });
     expect(calls.map(({ kind }) => kind)).toEqual(['killApp', 'killApp']);
-    expect(calls[0]).toMatchObject({ input: { appId: 'com.example.checkout' } });
+    expect(calls[0]).toMatchObject({ input: { appId: 'com.example.other' } });
     expect(calls[1]).toMatchObject({ input: { appId: 'com.example.checkout' } });
   });
 
diff --git a/packages/platform-android/src/__tests__/app-lifecycle-open.test.ts b/packages/platform-android/src/__tests__/app-lifecycle-open.test.ts
index f8b0dd9886..13037afeef 100644
--- a/packages/platform-android/src/__tests__/app-lifecycle-open.test.ts
+++ b/packages/platform-android/src/__tests__/app-lifecycle-open.test.ts
@@ -239,23 +239,12 @@ test('killAndroidApp refuses a foreground target before killing', async () => {
       await assertRejectsAppError(() => killAndroidApp(device, 'com.example.app'), {
         code: 'COMMAND_FAILED',
         hint: /Background the app before killApp/,
+        details: { reason: 'android-kill-requires-background-app' },
       });
-      try {
-        await killAndroidApp(device, 'com.example.app');
-        assert.fail('expected killAndroidApp to reject for a foreground app');
-      } catch (error) {
-        assert.equal(
-          (error as InstanceType<typeof AppError>).details?.reason,
-          'android-kill-requires-background-app',
-        );
-      }
     },
   );
 
-  assert.deepEqual(calls, [
-    ['shell', 'dumpsys', 'window', 'windows'],
-    ['shell', 'dumpsys', 'window', 'windows'],
-  ]);
+  assert.deepEqual(calls, [['shell', 'dumpsys', 'window', 'windows']]);
 });
 
 test('killAndroidApp fails when the process survives the kill', async () => {
@@ -293,16 +282,125 @@ test('killAndroidApp fails when the process survives the kill', async () => {
       await assertRejectsAppError(() => killAndroidApp(device, 'com.example.app'), {
         code: 'COMMAND_FAILED',
         hint: /foreground service|force-stop/,
+        details: { reason: 'android-kill-process-survived' },
+      });
+    },
+  );
+});
+
+test('killAndroidApp fails when the liveness probe itself cannot answer', async () => {
+  const device: DeviceInfo = {
+    platform: 'android',
+    id: 'emulator-5554',
+    name: 'Pixel',
+    kind: 'emulator',
+    booted: true,
+  };
+
+  await withAndroidAdbProvider(
+    {
+      exec: async (args) => {
+        if (args.join(' ') === 'shell dumpsys window windows') {
+          return {
+            stdout: 'mCurrentFocus=Window{43 u0 com.android.launcher/.Launcher}\n',
+            stderr: '',
+            exitCode: 0,
+          };
+        }
+        if (args.join(' ') === 'shell pidof com.example.app') {
+          return { stdout: '', stderr: 'error: device offline\n', exitCode: 1 };
+        }
+        return { stdout: '', stderr: '', exitCode: 0 };
+      },
+      reverse: {
+        ensure: async () => {},
+        remove: async () => {},
+        removeAllOwned: async () => {},
+      },
+    },
+    { serial: 'emulator-5554' },
+    async () => {
+      await assertRejectsAppError(() => killAndroidApp(device, 'com.example.app'), {
+        code: 'COMMAND_FAILED',
+        hint: /pidof did not answer/,
+        details: { reason: 'android-process-probe-unavailable' },
+      });
+    },
+  );
+});
+
+test('killAndroidApp fails closed when the foreground probe cannot answer', async () => {
+  const device: DeviceInfo = {
+    platform: 'android',
+    id: 'emulator-5554',
+    name: 'Pixel',
+    kind: 'emulator',
+    booted: true,
+  };
+  const calls: (readonly string[])[] = [];
+
+  await withAndroidAdbProvider(
+    {
+      exec: async (args) => {
+        calls.push(args);
+        return { stdout: '', stderr: '', exitCode: 0 };
+      },
+      reverse: {
+        ensure: async () => {},
+        remove: async () => {},
+        removeAllOwned: async () => {},
+      },
+    },
+    { serial: 'emulator-5554' },
+    async () => {
+      await assertRejectsAppError(() => killAndroidApp(device, 'com.example.app'), {
+        code: 'COMMAND_FAILED',
+        hint: /dumpsys did not answer/,
+        details: { reason: 'android-process-probe-unavailable' },
+      });
+    },
+  );
+
+  assert.ok(!calls.some((args) => args.join(' ').includes('am kill')));
+});
+
+test('closeAndroidApp fails when the liveness probe itself cannot answer', async () => {
+  const device: DeviceInfo = {
+    platform: 'android',
+    id: 'emulator-5554',
+    name: 'Pixel',
+    kind: 'emulator',
+    booted: true,
+  };
+
+  await withAndroidAdbProvider(
+    {
+      exec: async (args) => {
+        if (args.join(' ') === 'shell dumpsys window windows') {
+          return {
+            stdout: 'mCurrentFocus=Window{43 u0 com.android.launcher/.Launcher}\n',
+            stderr: '',
+            exitCode: 0,
+          };
+        }
+        if (args.join(' ') === 'shell pidof com.example.app') {
+          return { stdout: '', stderr: 'error: device offline\n', exitCode: 1 };
+        }
+        return { stdout: '', stderr: '', exitCode: 0 };
+      },
+      reverse: {
+        ensure: async () => {},
+        remove: async () => {},
+        removeAllOwned: async () => {},
+      },
+    },
+    { serial: 'emulator-5554' },
+    async () => {
+      await assertRejectsAppError(() => closeAndroidApp(device, 'com.example.app'), {
+        code: 'COMMAND_FAILED',
+        hint: /pidof did not answer/,
+        details: { reason: 'android-process-probe-unavailable' },
       });
-      try {
-        await killAndroidApp(device, 'com.example.app');
-        assert.fail('expected killAndroidApp to reject when the process survives');
-      } catch (error) {
-        assert.equal(
-          (error as InstanceType<typeof AppError>).details?.reason,
-          'android-kill-process-survived',
-        );
-      }
     },
   );
 });
diff --git a/packages/platform-android/src/__tests__/test-utils/app-error.ts b/packages/platform-android/src/__tests__/test-utils/app-error.ts
index 1a35896125..920148765b 100644
--- a/packages/platform-android/src/__tests__/test-utils/app-error.ts
+++ b/packages/platform-android/src/__tests__/test-utils/app-error.ts
@@ -1,7 +1,12 @@
 import assert from 'node:assert/strict';
 import { AppError, normalizeError } from '@agent-device/kernel/errors';
 
-type ExpectedAppError = { code: string; message?: RegExp; hint?: string | RegExp };
+type ExpectedAppError = {
+  code: string;
+  message?: RegExp;
+  hint?: string | RegExp;
+  details?: Readonly<Record<string, unknown>>;
+};
 
 function assertAppError(error: unknown, expected: ExpectedAppError): true {
   assert.ok(
@@ -16,6 +21,11 @@ function assertAppError(error: unknown, expected: ExpectedAppError): true {
     if (typeof expected.hint === 'string') assert.equal(hint, expected.hint);
     else assert.match(hint, expected.hint);
   }
+  if (expected.details !== undefined) {
+    for (const [key, value] of Object.entries(expected.details)) {
+      assert.deepEqual(error.details?.[key], value);
+    }
+  }
   return true;
 }
 
diff --git a/packages/platform-android/src/app-lifecycle.ts b/packages/platform-android/src/app-lifecycle.ts
index ebe92fc393..20d020d36e 100644
--- a/packages/platform-android/src/app-lifecycle.ts
+++ b/packages/platform-android/src/app-lifecycle.ts
@@ -516,6 +516,16 @@ async function killAndroidPackage(device: DeviceInfo, packageName: string): Prom
       hint: 'Background the app before killApp (for example pressKey: Home): am kill only reaps background processes.',
     });
   }
+  if (!foreground) {
+    throw new AppError(
+      'COMMAND_FAILED',
+      `Could not read foreground state before killing ${packageName}`,
+      {
+        reason: 'android-process-probe-unavailable',
+        hint: 'adb dumpsys did not answer; retry once the device is reachable.',
+      },
+    );
+  }
   await runAndroidShell(device, ['am', 'kill', packageName]);
   await waitForAndroidPackageStopped(device, packageName);
   if (await isAndroidPackageProcessRunning(device, packageName)) {
@@ -572,5 +582,15 @@ async function isAndroidPackageProcessRunning(
   const result = await runAndroidShell(device, ['pidof', packageName], {
     allowFailure: true,
   });
-  return (result.stdout ?? '').trim().length > 0;
+  if ((result.stdout ?? '').trim().length > 0) return true;
+  // `pidof` exits 1 with empty streams when no process matches; anything else
+  // with empty stdout is the probe itself failing (device unreachable, missing
+  // binary), which must not read as a reaped process.
+  if ((result.exitCode === 0 || result.exitCode === 1) && (result.stderr ?? '').trim() === '') {
+    return false;
+  }
+  throw new AppError('COMMAND_FAILED', `Could not read process state for ${packageName}`, {
+    reason: 'android-process-probe-unavailable',
+    hint: 'adb pidof did not answer; retry once the device is reachable.',
+  });
 }
diff --git a/packages/platform-android/src/lifecycle.ts b/packages/platform-android/src/lifecycle.ts
index 365e62a40a..c2e541c126 100644
--- a/packages/platform-android/src/lifecycle.ts
+++ b/packages/platform-android/src/lifecycle.ts
@@ -68,8 +68,11 @@ export function bindAndroidApplicationLifecycle(
         await ensureAndroidReady(host, device, { headless: false }, signal);
       }
       if (input.mode === 'kill') {
-        const target = input.positionals[0];
-        if (target) await killAndroidApp(device, target);
+        const target = input.positionals[0]?.trim() || input.appBundleId?.trim();
+        if (!target) {
+          throw new AppError('INVALID_ARGS', 'Kill requires an app target');
+        }
+        await killAndroidApp(device, target);
         return;
       }
       await invokeApplicationClose({
diff --git a/src/daemon/session-lifecycle/internal/__tests__/session-close-lifecycle-runtime.test.ts b/src/daemon/session-lifecycle/internal/__tests__/session-close-lifecycle-runtime.test.ts
index dcfc5631a6..b6fa90b7cb 100644
--- a/src/daemon/session-lifecycle/internal/__tests__/session-close-lifecycle-runtime.test.ts
+++ b/src/daemon/session-lifecycle/internal/__tests__/session-close-lifecycle-runtime.test.ts
@@ -335,7 +335,10 @@ test('an app-only kill close carries mode kill while a stop close carries none',
   sessionStore.set(sessionName, session);
   const seenModes: Array<unknown> = [];
   const baseBind = mockBindDeviceRuntime.getMockImplementation();
-  mockBindDeviceRuntime.mockImplementation(async (boundDevice, use) => {
+  const recordModes = async (
+    boundDevice: Parameters<NonNullable<typeof baseBind>>[0],
+    use: Parameters<NonNullable<typeof baseBind>>[1],
+  ) => {
     const binding = await baseBind!(boundDevice, use);
     const innerClose = binding.operations.closeApplication;
     if (!innerClose) return binding;
@@ -349,7 +352,9 @@ test('an app-only kill close carries mode kill while a stop close carries none',
         },
       },
     };
-  });
+  };
+  mockBindDeviceRuntime.mockImplementationOnce(recordModes);
+  mockBindDeviceRuntime.mockImplementationOnce(recordModes);
 
   const killed = await close({
     sessionName,
diff --git a/src/daemon/session-lifecycle/internal/session-close.ts b/src/daemon/session-lifecycle/internal/session-close.ts
index 1e603d89fd..aa5fdc8bb4 100644
--- a/src/daemon/session-lifecycle/internal/session-close.ts
+++ b/src/daemon/session-lifecycle/internal/session-close.ts
@@ -436,6 +436,7 @@ async function closeWithoutSession(params: {
     outPath: req.flags?.out,
     surface: 'app',
     ensureReady: true,
+    ...(req.internal?.killApp === true ? { mode: 'kill' as const } : {}),
     execution: applicationLifecycleExecutionFromRequest(req, logPath),
   });
   return {

From f8943953185e60110278bc512a2d9f6b26c20c20 Mon Sep 17 00:00:00 2001
From: Rohit <40559587+Rohit3523@users.noreply.github.com>
Date: Fri, 25 Sep 2026 09:58:07 +0530
Subject: [PATCH 127/132] fix(maestro): keep killApp tests hermetic and under
 the size ratchet

- Move killAndroidApp tests to app-lifecycle-kill.test.ts so
  app-lifecycle-open.test.ts stays under the 1,000-line tripwire
- Stub the platform close in the session-close mode-plumbing test
  instead of executing the real Android kill against live adb
---
 .../src/__tests__/app-lifecycle-kill.test.ts  | 209 ++++++++++++++++++
 .../src/__tests__/app-lifecycle-open.test.ts  | 204 +----------------
 .../session-close-lifecycle-runtime.test.ts   |   4 +-
 3 files changed, 213 insertions(+), 204 deletions(-)
 create mode 100644 packages/platform-android/src/__tests__/app-lifecycle-kill.test.ts

diff --git a/packages/platform-android/src/__tests__/app-lifecycle-kill.test.ts b/packages/platform-android/src/__tests__/app-lifecycle-kill.test.ts
new file mode 100644
index 0000000000..dd33c7a055
--- /dev/null
+++ b/packages/platform-android/src/__tests__/app-lifecycle-kill.test.ts
@@ -0,0 +1,209 @@
+import { test } from 'vitest';
+import assert from 'node:assert/strict';
+import { killAndroidApp } from '../app-lifecycle.ts';
+import { withAndroidAdbProvider } from '../adb-executor.ts';
+import type { DeviceInfo } from '@agent-device/kernel/device';
+import { assertRejectsAppError } from './test-utils/app-error.ts';
+import './test-utils/android-host-test-setup.ts';
+
+test('killAndroidApp dispatches am kill rather than am force-stop', async () => {
+  const device: DeviceInfo = {
+    platform: 'android',
+    id: 'emulator-5554',
+    name: 'Pixel',
+    kind: 'emulator',
+    booted: true,
+  };
+  const calls: (readonly string[])[] = [];
+
+  await withAndroidAdbProvider(
+    {
+      exec: async (args) => {
+        calls.push(args);
+        if (args.join(' ') === 'shell dumpsys window windows') {
+          return {
+            stdout: 'mCurrentFocus=Window{43 u0 com.android.launcher/.Launcher}\n',
+            stderr: '',
+            exitCode: 0,
+          };
+        }
+        return { stdout: '', stderr: '', exitCode: 0 };
+      },
+      reverse: {
+        ensure: async () => {},
+        remove: async () => {},
+        removeAllOwned: async () => {},
+      },
+    },
+    { serial: 'emulator-5554' },
+    async () => await killAndroidApp(device, 'com.example.app'),
+  );
+
+  assert.deepEqual(calls, [
+    ['shell', 'dumpsys', 'window', 'windows'],
+    ['shell', 'am', 'kill', 'com.example.app'],
+    ['shell', 'dumpsys', 'window', 'windows'],
+    ['shell', 'pidof', 'com.example.app'],
+    ['shell', 'pidof', 'com.example.app'],
+    ['shell', 'pidof', 'com.example.app'],
+  ]);
+});
+
+test('killAndroidApp refuses a foreground target before killing', async () => {
+  const device: DeviceInfo = {
+    platform: 'android',
+    id: 'emulator-5554',
+    name: 'Pixel',
+    kind: 'emulator',
+    booted: true,
+  };
+  const calls: (readonly string[])[] = [];
+
+  await withAndroidAdbProvider(
+    {
+      exec: async (args) => {
+        calls.push(args);
+        if (args.join(' ') === 'shell dumpsys window windows') {
+          return {
+            stdout: 'mCurrentFocus=Window{42 u0 com.example.app/.MainActivity}\n',
+            stderr: '',
+            exitCode: 0,
+          };
+        }
+        return { stdout: '', stderr: '', exitCode: 0 };
+      },
+      reverse: {
+        ensure: async () => {},
+        remove: async () => {},
+        removeAllOwned: async () => {},
+      },
+    },
+    { serial: 'emulator-5554' },
+    async () => {
+      await assertRejectsAppError(() => killAndroidApp(device, 'com.example.app'), {
+        code: 'COMMAND_FAILED',
+        hint: /Background the app before killApp/,
+        details: { reason: 'android-kill-requires-background-app' },
+      });
+    },
+  );
+
+  assert.deepEqual(calls, [['shell', 'dumpsys', 'window', 'windows']]);
+});
+
+test('killAndroidApp fails when the process survives the kill', async () => {
+  const device: DeviceInfo = {
+    platform: 'android',
+    id: 'emulator-5554',
+    name: 'Pixel',
+    kind: 'emulator',
+    booted: true,
+  };
+
+  await withAndroidAdbProvider(
+    {
+      exec: async (args) => {
+        if (args.join(' ') === 'shell dumpsys window windows') {
+          return {
+            stdout: 'mCurrentFocus=Window{43 u0 com.android.launcher/.Launcher}\n',
+            stderr: '',
+            exitCode: 0,
+          };
+        }
+        if (args.join(' ') === 'shell pidof com.example.app') {
+          return { stdout: '12345\n', stderr: '', exitCode: 0 };
+        }
+        return { stdout: '', stderr: '', exitCode: 0 };
+      },
+      reverse: {
+        ensure: async () => {},
+        remove: async () => {},
+        removeAllOwned: async () => {},
+      },
+    },
+    { serial: 'emulator-5554' },
+    async () => {
+      await assertRejectsAppError(() => killAndroidApp(device, 'com.example.app'), {
+        code: 'COMMAND_FAILED',
+        hint: /foreground service|force-stop/,
+        details: { reason: 'android-kill-process-survived' },
+      });
+    },
+  );
+});
+
+test('killAndroidApp fails when the liveness probe itself cannot answer', async () => {
+  const device: DeviceInfo = {
+    platform: 'android',
+    id: 'emulator-5554',
+    name: 'Pixel',
+    kind: 'emulator',
+    booted: true,
+  };
+
+  await withAndroidAdbProvider(
+    {
+      exec: async (args) => {
+        if (args.join(' ') === 'shell dumpsys window windows') {
+          return {
+            stdout: 'mCurrentFocus=Window{43 u0 com.android.launcher/.Launcher}\n',
+            stderr: '',
+            exitCode: 0,
+          };
+        }
+        if (args.join(' ') === 'shell pidof com.example.app') {
+          return { stdout: '', stderr: 'error: device offline\n', exitCode: 1 };
+        }
+        return { stdout: '', stderr: '', exitCode: 0 };
+      },
+      reverse: {
+        ensure: async () => {},
+        remove: async () => {},
+        removeAllOwned: async () => {},
+      },
+    },
+    { serial: 'emulator-5554' },
+    async () => {
+      await assertRejectsAppError(() => killAndroidApp(device, 'com.example.app'), {
+        code: 'COMMAND_FAILED',
+        hint: /pidof did not answer/,
+        details: { reason: 'android-process-probe-unavailable' },
+      });
+    },
+  );
+});
+
+test('killAndroidApp fails closed when the foreground probe cannot answer', async () => {
+  const device: DeviceInfo = {
+    platform: 'android',
+    id: 'emulator-5554',
+    name: 'Pixel',
+    kind: 'emulator',
+    booted: true,
+  };
+  const calls: (readonly string[])[] = [];
+
+  await withAndroidAdbProvider(
+    {
+      exec: async (args) => {
+        calls.push(args);
+        return { stdout: '', stderr: '', exitCode: 0 };
+      },
+      reverse: {
+        ensure: async () => {},
+        remove: async () => {},
+        removeAllOwned: async () => {},
+      },
+    },
+    { serial: 'emulator-5554' },
+    async () => {
+      await assertRejectsAppError(() => killAndroidApp(device, 'com.example.app'), {
+        code: 'COMMAND_FAILED',
+        hint: /dumpsys did not answer/,
+        details: { reason: 'android-process-probe-unavailable' },
+      });
+    },
+  );
+
+  assert.ok(!calls.some((args) => args.join(' ').includes('am kill')));
+});
diff --git a/packages/platform-android/src/__tests__/app-lifecycle-open.test.ts b/packages/platform-android/src/__tests__/app-lifecycle-open.test.ts
index 13037afeef..d763634586 100644
--- a/packages/platform-android/src/__tests__/app-lifecycle-open.test.ts
+++ b/packages/platform-android/src/__tests__/app-lifecycle-open.test.ts
@@ -1,6 +1,6 @@
 import { test } from 'vitest';
 import assert from 'node:assert/strict';
-import { closeAndroidApp, killAndroidApp, openAndroidApp } from '../app-lifecycle.ts';
+import { closeAndroidApp, openAndroidApp } from '../app-lifecycle.ts';
 import { withAndroidAdbProvider } from '../adb-executor.ts';
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import { AppError } from '@agent-device/kernel/errors';
@@ -162,208 +162,6 @@ test('closeAndroidApp waits until package process exits after force-stop', async
   ]);
 });
 
-test('killAndroidApp dispatches am kill rather than am force-stop', async () => {
-  const device: DeviceInfo = {
-    platform: 'android',
-    id: 'emulator-5554',
-    name: 'Pixel',
-    kind: 'emulator',
-    booted: true,
-  };
-  const calls: (readonly string[])[] = [];
-
-  await withAndroidAdbProvider(
-    {
-      exec: async (args) => {
-        calls.push(args);
-        if (args.join(' ') === 'shell dumpsys window windows') {
-          return {
-            stdout: 'mCurrentFocus=Window{43 u0 com.android.launcher/.Launcher}\n',
-            stderr: '',
-            exitCode: 0,
-          };
-        }
-        return { stdout: '', stderr: '', exitCode: 0 };
-      },
-      reverse: {
-        ensure: async () => {},
-        remove: async () => {},
-        removeAllOwned: async () => {},
-      },
-    },
-    { serial: 'emulator-5554' },
-    async () => await killAndroidApp(device, 'com.example.app'),
-  );
-
-  assert.deepEqual(calls, [
-    ['shell', 'dumpsys', 'window', 'windows'],
-    ['shell', 'am', 'kill', 'com.example.app'],
-    ['shell', 'dumpsys', 'window', 'windows'],
-    ['shell', 'pidof', 'com.example.app'],
-    ['shell', 'pidof', 'com.example.app'],
-    ['shell', 'pidof', 'com.example.app'],
-  ]);
-});
-
-test('killAndroidApp refuses a foreground target before killing', async () => {
-  const device: DeviceInfo = {
-    platform: 'android',
-    id: 'emulator-5554',
-    name: 'Pixel',
-    kind: 'emulator',
-    booted: true,
-  };
-  const calls: (readonly string[])[] = [];
-
-  await withAndroidAdbProvider(
-    {
-      exec: async (args) => {
-        calls.push(args);
-        if (args.join(' ') === 'shell dumpsys window windows') {
-          return {
-            stdout: 'mCurrentFocus=Window{42 u0 com.example.app/.MainActivity}\n',
-            stderr: '',
-            exitCode: 0,
-          };
-        }
-        return { stdout: '', stderr: '', exitCode: 0 };
-      },
-      reverse: {
-        ensure: async () => {},
-        remove: async () => {},
-        removeAllOwned: async () => {},
-      },
-    },
-    { serial: 'emulator-5554' },
-    async () => {
-      await assertRejectsAppError(() => killAndroidApp(device, 'com.example.app'), {
-        code: 'COMMAND_FAILED',
-        hint: /Background the app before killApp/,
-        details: { reason: 'android-kill-requires-background-app' },
-      });
-    },
-  );
-
-  assert.deepEqual(calls, [['shell', 'dumpsys', 'window', 'windows']]);
-});
-
-test('killAndroidApp fails when the process survives the kill', async () => {
-  const device: DeviceInfo = {
-    platform: 'android',
-    id: 'emulator-5554',
-    name: 'Pixel',
-    kind: 'emulator',
-    booted: true,
-  };
-
-  await withAndroidAdbProvider(
-    {
-      exec: async (args) => {
-        if (args.join(' ') === 'shell dumpsys window windows') {
-          return {
-            stdout: 'mCurrentFocus=Window{43 u0 com.android.launcher/.Launcher}\n',
-            stderr: '',
-            exitCode: 0,
-          };
-        }
-        if (args.join(' ') === 'shell pidof com.example.app') {
-          return { stdout: '12345\n', stderr: '', exitCode: 0 };
-        }
-        return { stdout: '', stderr: '', exitCode: 0 };
-      },
-      reverse: {
-        ensure: async () => {},
-        remove: async () => {},
-        removeAllOwned: async () => {},
-      },
-    },
-    { serial: 'emulator-5554' },
-    async () => {
-      await assertRejectsAppError(() => killAndroidApp(device, 'com.example.app'), {
-        code: 'COMMAND_FAILED',
-        hint: /foreground service|force-stop/,
-        details: { reason: 'android-kill-process-survived' },
-      });
-    },
-  );
-});
-
-test('killAndroidApp fails when the liveness probe itself cannot answer', async () => {
-  const device: DeviceInfo = {
-    platform: 'android',
-    id: 'emulator-5554',
-    name: 'Pixel',
-    kind: 'emulator',
-    booted: true,
-  };
-
-  await withAndroidAdbProvider(
-    {
-      exec: async (args) => {
-        if (args.join(' ') === 'shell dumpsys window windows') {
-          return {
-            stdout: 'mCurrentFocus=Window{43 u0 com.android.launcher/.Launcher}\n',
-            stderr: '',
-            exitCode: 0,
-          };
-        }
-        if (args.join(' ') === 'shell pidof com.example.app') {
-          return { stdout: '', stderr: 'error: device offline\n', exitCode: 1 };
-        }
-        return { stdout: '', stderr: '', exitCode: 0 };
-      },
-      reverse: {
-        ensure: async () => {},
-        remove: async () => {},
-        removeAllOwned: async () => {},
-      },
-    },
-    { serial: 'emulator-5554' },
-    async () => {
-      await assertRejectsAppError(() => killAndroidApp(device, 'com.example.app'), {
-        code: 'COMMAND_FAILED',
-        hint: /pidof did not answer/,
-        details: { reason: 'android-process-probe-unavailable' },
-      });
-    },
-  );
-});
-
-test('killAndroidApp fails closed when the foreground probe cannot answer', async () => {
-  const device: DeviceInfo = {
-    platform: 'android',
-    id: 'emulator-5554',
-    name: 'Pixel',
-    kind: 'emulator',
-    booted: true,
-  };
-  const calls: (readonly string[])[] = [];
-
-  await withAndroidAdbProvider(
-    {
-      exec: async (args) => {
-        calls.push(args);
-        return { stdout: '', stderr: '', exitCode: 0 };
-      },
-      reverse: {
-        ensure: async () => {},
-        remove: async () => {},
-        removeAllOwned: async () => {},
-      },
-    },
-    { serial: 'emulator-5554' },
-    async () => {
-      await assertRejectsAppError(() => killAndroidApp(device, 'com.example.app'), {
-        code: 'COMMAND_FAILED',
-        hint: /dumpsys did not answer/,
-        details: { reason: 'android-process-probe-unavailable' },
-      });
-    },
-  );
-
-  assert.ok(!calls.some((args) => args.join(' ').includes('am kill')));
-});
-
 test('closeAndroidApp fails when the liveness probe itself cannot answer', async () => {
   const device: DeviceInfo = {
     platform: 'android',
diff --git a/src/daemon/session-lifecycle/internal/__tests__/session-close-lifecycle-runtime.test.ts b/src/daemon/session-lifecycle/internal/__tests__/session-close-lifecycle-runtime.test.ts
index b6fa90b7cb..ff515f6185 100644
--- a/src/daemon/session-lifecycle/internal/__tests__/session-close-lifecycle-runtime.test.ts
+++ b/src/daemon/session-lifecycle/internal/__tests__/session-close-lifecycle-runtime.test.ts
@@ -346,9 +346,11 @@ test('an app-only kill close carries mode kill while a stop close carries none',
       ...binding,
       operations: {
         ...binding.operations,
+        // This test proves mode propagation through session-close dispatch. The
+        // platform effect itself stays stubbed: delegating would execute the
+        // real Android kill against a live adb device instead of a fake.
         closeApplication: async (input: Parameters<typeof innerClose>[0]) => {
           seenModes.push(input.mode);
-          return await innerClose(input);
         },
       },
     };

From e676aded6b481152d908480ab9ce7b1f2e4150e0 Mon Sep 17 00:00:00 2001
From: Rohit <40559587+Rohit3523@users.noreply.github.com>
Date: Fri, 25 Sep 2026 21:04:35 +0530
Subject: [PATCH 128/132] fix(maestro): corroborate a stale foreground read
 before killApp proceeds

Live emulator replay (agent-device replay --maestro) reproduced a real gap
from the PR review: immediately after launchApp, dumpsys window's
mCurrentFocus can still name the previous foreground app for one read while
dumpsys activity activities already shows the launched app resumed.
getAndroidAppState takes whichever dump answers first, so killAndroidPackage's
single-sample foreground check could read "backgrounded" for an app that was
still genuinely in the foreground, skipping the android-kill-requires-
background-app refusal. killAndroidPackage now corroborates a "not the
target" read once after a short settle before trusting it, mirroring the
existing gone-twice-in-a-row pattern used elsewhere in this file.

Also: drop the killAndroidApp re-export from mechanics.ts (no consumer
imports it there; the real caller imports directly from app-lifecycle.ts),
and add a direct test proving mode: 'kill' reaches the platform close when
closeWithoutSession handles close with no stored session.

Claude-Session: https://claude.ai/code/session_01NVfRR5Pmmkg8ZstHQUZ2qR
---
 .../src/__tests__/app-lifecycle-kill.test.ts  | 48 +++++++++++
 .../platform-android/src/app-lifecycle.ts     | 25 +++++-
 packages/platform-android/src/mechanics.ts    |  1 -
 ...session-close-without-session-mode.test.ts | 85 +++++++++++++++++++
 4 files changed, 157 insertions(+), 2 deletions(-)
 create mode 100644 src/daemon/session-lifecycle/internal/__tests__/session-close-without-session-mode.test.ts

diff --git a/packages/platform-android/src/__tests__/app-lifecycle-kill.test.ts b/packages/platform-android/src/__tests__/app-lifecycle-kill.test.ts
index dd33c7a055..7bf9dcf586 100644
--- a/packages/platform-android/src/__tests__/app-lifecycle-kill.test.ts
+++ b/packages/platform-android/src/__tests__/app-lifecycle-kill.test.ts
@@ -40,6 +40,7 @@ test('killAndroidApp dispatches am kill rather than am force-stop', async () =>
   );
 
   assert.deepEqual(calls, [
+    ['shell', 'dumpsys', 'window', 'windows'],
     ['shell', 'dumpsys', 'window', 'windows'],
     ['shell', 'am', 'kill', 'com.example.app'],
     ['shell', 'dumpsys', 'window', 'windows'],
@@ -49,6 +50,53 @@ test('killAndroidApp dispatches am kill rather than am force-stop', async () =>
   ]);
 });
 
+// Live evidence (2026-09-25, Android 16 emulator): immediately after `launchApp`,
+// `dumpsys window`'s `mCurrentFocus` still named the previous foreground app for one read while
+// `dumpsys activity activities` already showed the launched app resumed. A single "not the target"
+// foreground read is not proof the target left the foreground, so `killAndroidApp` corroborates it
+// once before trusting it enough to skip the `android-kill-requires-background-app` refusal.
+test('killAndroidApp refuses when a corroborating read shows the target back in the foreground', async () => {
+  const device: DeviceInfo = {
+    platform: 'android',
+    id: 'emulator-5554',
+    name: 'Pixel',
+    kind: 'emulator',
+    booted: true,
+  };
+  let foregroundReads = 0;
+
+  await withAndroidAdbProvider(
+    {
+      exec: async (args) => {
+        if (args.join(' ') === 'shell dumpsys window windows') {
+          foregroundReads += 1;
+          const stdout =
+            foregroundReads === 1
+              ? 'mCurrentFocus=Window{43 u0 com.android.launcher/.Launcher}\n'
+              : 'mCurrentFocus=Window{44 u0 com.example.app/.MainActivity}\n';
+          return { stdout, stderr: '', exitCode: 0 };
+        }
+        return { stdout: '', stderr: '', exitCode: 0 };
+      },
+      reverse: {
+        ensure: async () => {},
+        remove: async () => {},
+        removeAllOwned: async () => {},
+      },
+    },
+    { serial: 'emulator-5554' },
+    async () => {
+      await assertRejectsAppError(() => killAndroidApp(device, 'com.example.app'), {
+        code: 'COMMAND_FAILED',
+        hint: /Background the app before killApp/,
+        details: { reason: 'android-kill-requires-background-app' },
+      });
+    },
+  );
+
+  assert.equal(foregroundReads, 2);
+});
+
 test('killAndroidApp refuses a foreground target before killing', async () => {
   const device: DeviceInfo = {
     platform: 'android',
diff --git a/packages/platform-android/src/app-lifecycle.ts b/packages/platform-android/src/app-lifecycle.ts
index 20d020d36e..ec04525266 100644
--- a/packages/platform-android/src/app-lifecycle.ts
+++ b/packages/platform-android/src/app-lifecycle.ts
@@ -33,6 +33,7 @@ const ANDROID_CLOSE_FOCUS_POLL_MS = 50;
 const ANDROID_CLOSE_PROCESS_TIMEOUT_MS = 2_000;
 const ANDROID_CLOSE_PROCESS_POLL_MS = 50;
 const ANDROID_CLOSE_PROCESS_GONE_STABLE_MS = 150;
+const ANDROID_KILL_FOREGROUND_STABLE_MS = 150;
 
 export async function listAndroidApps(
   device: DeviceInfo,
@@ -509,7 +510,7 @@ export async function killAndroidApp(device: DeviceInfo, app: string): Promise<v
 }
 
 async function killAndroidPackage(device: DeviceInfo, packageName: string): Promise<void> {
-  const foreground = await readAndroidForegroundApp(device);
+  const foreground = await readAndroidForegroundAppSettled(device, packageName);
   if (foreground?.package === packageName) {
     throw new AppError('COMMAND_FAILED', `Cannot kill foreground app ${packageName}`, {
       reason: 'android-kill-requires-background-app',
@@ -561,6 +562,28 @@ async function readAndroidForegroundApp(device: DeviceInfo): Promise<AppStateRun
   return foreground.package ? foreground : null;
 }
 
+/**
+ * `killAndroidPackage`'s precondition needs the opposite corroboration from
+ * `waitForAndroidPackageProcessGone`'s "gone twice in a row counts": here a read naming a
+ * different app is not enough on its own to trust "safe to kill". Live evidence (2026-09-25,
+ * Android 16 emulator): immediately after `launchApp`, `dumpsys window`'s `mCurrentFocus` still
+ * named the previous foreground app for one read while `dumpsys activity activities` already
+ * showed the launched app resumed — `getAndroidAppState` takes whichever dump answers first, so
+ * that stale window-focus read alone would have skipped the `android-kill-requires-background-app`
+ * refusal against a target still genuinely in the foreground. A same-app read is trusted
+ * immediately (refusing early is always safe); a different-app or unreadable read is corroborated
+ * once after a short settle before this lets `killAndroidPackage` proceed.
+ */
+async function readAndroidForegroundAppSettled(
+  device: DeviceInfo,
+  packageName: string,
+): Promise<AppStateRuntimeResult | null> {
+  const first = await readAndroidForegroundApp(device);
+  if (first?.package === packageName) return first;
+  await sleep(ANDROID_KILL_FOREGROUND_STABLE_MS);
+  return await readAndroidForegroundApp(device);
+}
+
 async function waitForAndroidPackageProcessGone(
   device: DeviceInfo,
   packageName: string,
diff --git a/packages/platform-android/src/mechanics.ts b/packages/platform-android/src/mechanics.ts
index 43b5dfa3f9..96efabf755 100644
--- a/packages/platform-android/src/mechanics.ts
+++ b/packages/platform-android/src/mechanics.ts
@@ -83,7 +83,6 @@ export async function listAndroidAppsWithAdb(
 export {
   closeAndroidApp,
   isAmStartError,
-  killAndroidApp,
   openAndroidApp,
   openAndroidDevice,
   parseAndroidLaunchComponent,
diff --git a/src/daemon/session-lifecycle/internal/__tests__/session-close-without-session-mode.test.ts b/src/daemon/session-lifecycle/internal/__tests__/session-close-without-session-mode.test.ts
new file mode 100644
index 0000000000..bc7dbc26cc
--- /dev/null
+++ b/src/daemon/session-lifecycle/internal/__tests__/session-close-without-session-mode.test.ts
@@ -0,0 +1,85 @@
+import { test, expect, vi } from 'vitest';
+
+import path from 'node:path';
+import type { DeviceInfo } from '@agent-device/kernel/device';
+import type { DaemonRequest, DaemonResponse } from '../../../daemon-request.ts';
+import { SessionStore } from '../../../session-store.ts';
+import { mkdtempForTestSync } from '../../../../__tests__/test-utils/tmp-dir.ts';
+
+const mockResolveTargetDevice = vi.hoisted(() => vi.fn());
+
+vi.mock('@agent-device/device-selection/dispatch-resolve', async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import('@agent-device/device-selection/dispatch-resolve')>();
+  const { selectionFromResolveTargetDevice } =
+    await import('../../../__tests__/device-selection-stub.ts');
+  return {
+    ...actual,
+    resolveTargetDevice: mockResolveTargetDevice,
+    resolveTargetDeviceSelection: vi.fn(selectionFromResolveTargetDevice(mockResolveTargetDevice)),
+  };
+});
+
+import {
+  handleSessionCommands,
+  mockBindDeviceRuntime,
+} from '../../../handlers/__tests__/session-command-harness.ts';
+
+const noopInvoke = async (_req: DaemonRequest): Promise<DaemonResponse> => ({ ok: true, data: {} });
+
+const ANDROID_DEVICE: DeviceInfo = {
+  platform: 'android',
+  id: 'emulator-5554',
+  name: 'Pixel',
+  kind: 'emulator',
+  target: 'mobile',
+  booted: true,
+};
+
+function makeSessionStore(): SessionStore {
+  const root = mkdtempForTestSync('agent-device-session-close-without-session-');
+  return new SessionStore(path.join(root, 'sessions'));
+}
+
+// #2749 review: `closeWithoutSession` (session-close.ts) is a second `mode: 'kill'` dispatch site
+// alongside `dispatchTargetedPlatformClose`, exercised only when no session is stored for the
+// requested name (`close <app>` straight from flags). Nothing previously proved it threads
+// `killApp` into the platform `closeApplication` call the way the stored-session path is proven.
+test('an app-only kill close with no stored session still carries mode kill to the platform close', async () => {
+  const sessionStore = makeSessionStore();
+  mockResolveTargetDevice.mockResolvedValue(ANDROID_DEVICE);
+  const seenModes: Array<unknown> = [];
+  const baseBind = mockBindDeviceRuntime.getMockImplementation();
+  mockBindDeviceRuntime.mockImplementationOnce(async (device, use) => {
+    const binding = await baseBind!(device, use);
+    const innerClose = binding.operations.closeApplication;
+    if (!innerClose) return binding;
+    return {
+      ...binding,
+      operations: {
+        ...binding.operations,
+        closeApplication: async (input: Parameters<typeof innerClose>[0]) => {
+          seenModes.push(input.mode);
+        },
+      },
+    };
+  });
+
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: 'no-such-session',
+      command: 'close',
+      positionals: ['com.example.app'],
+      flags: { serial: 'emulator-5554' },
+      internal: { closeAppOnly: true, killApp: true },
+    },
+    sessionName: 'no-such-session',
+    logPath: path.join(mkdtempForTestSync('daemon'), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+  });
+
+  expect(response?.ok).toBe(true);
+  expect(seenModes).toEqual(['kill']);
+});

From e3387eff0fd8ca45e6e751ca03ac80e26f2da51d Mon Sep 17 00:00:00 2001
From: Rohit <40559587+Rohit3523@users.noreply.github.com>
Date: Fri, 25 Sep 2026 23:52:42 +0530
Subject: [PATCH 129/132] fix(maestro): corroborate same-app foreground read
 and pin no-session close input

- app-lifecycle: settle and re-read a same-app foreground sample before refusing killApp, so a stale mCurrentFocus right after Home does not spuriously refuse a legal kill; unreadable confirm keeps the refusal
- session-close test: record the full closeApplication input and assert positionals, surface, outPath, and ensureReady alongside mode kill
- kill tests: expect two reads on refusal; cover stale same-app settling to background and unreadable confirm failing closed
---
 .../src/__tests__/app-lifecycle-kill.test.ts  | 91 ++++++++++++++++++-
 .../platform-android/src/app-lifecycle.ts     | 23 ++---
 ...session-close-without-session-mode.test.ts | 17 +++-
 3 files changed, 116 insertions(+), 15 deletions(-)

diff --git a/packages/platform-android/src/__tests__/app-lifecycle-kill.test.ts b/packages/platform-android/src/__tests__/app-lifecycle-kill.test.ts
index 7bf9dcf586..1f14704c7c 100644
--- a/packages/platform-android/src/__tests__/app-lifecycle-kill.test.ts
+++ b/packages/platform-android/src/__tests__/app-lifecycle-kill.test.ts
@@ -136,7 +136,96 @@ test('killAndroidApp refuses a foreground target before killing', async () => {
     },
   );
 
-  assert.deepEqual(calls, [['shell', 'dumpsys', 'window', 'windows']]);
+  assert.deepEqual(calls, [
+    ['shell', 'dumpsys', 'window', 'windows'],
+    ['shell', 'dumpsys', 'window', 'windows'],
+  ]);
+});
+
+test('killAndroidApp proceeds when a stale same-app read settles to background', async () => {
+  const device: DeviceInfo = {
+    platform: 'android',
+    id: 'emulator-5554',
+    name: 'Pixel',
+    kind: 'emulator',
+    booted: true,
+  };
+  let foregroundReads = 0;
+  const calls: (readonly string[])[] = [];
+
+  await withAndroidAdbProvider(
+    {
+      exec: async (args) => {
+        calls.push(args);
+        if (args.join(' ') === 'shell dumpsys window windows') {
+          foregroundReads += 1;
+          // First read still names the target (stale `mCurrentFocus` right after
+          // `pressKey: Home`); later reads see the launcher so the kill completes.
+          const stdout =
+            foregroundReads === 1
+              ? 'mCurrentFocus=Window{42 u0 com.example.app/.MainActivity}\n'
+              : 'mCurrentFocus=Window{43 u0 com.android.launcher/.Launcher}\n';
+          return { stdout, stderr: '', exitCode: 0 };
+        }
+        return { stdout: '', stderr: '', exitCode: 0 };
+      },
+      reverse: {
+        ensure: async () => {},
+        remove: async () => {},
+        removeAllOwned: async () => {},
+      },
+    },
+    { serial: 'emulator-5554' },
+    async () => await killAndroidApp(device, 'com.example.app'),
+  );
+
+  assert.equal(foregroundReads >= 2, true);
+  assert.ok(calls.some((args) => args.join(' ') === 'shell am kill com.example.app'));
+});
+
+test('killAndroidApp fails closed when the confirmatory read cannot answer', async () => {
+  const device: DeviceInfo = {
+    platform: 'android',
+    id: 'emulator-5554',
+    name: 'Pixel',
+    kind: 'emulator',
+    booted: true,
+  };
+  let foregroundReads = 0;
+
+  await withAndroidAdbProvider(
+    {
+      exec: async (args) => {
+        if (args.join(' ') === 'shell dumpsys window windows') {
+          foregroundReads += 1;
+          if (foregroundReads === 1) {
+            return {
+              stdout: 'mCurrentFocus=Window{42 u0 com.example.app/.MainActivity}\n',
+              stderr: '',
+              exitCode: 0,
+            };
+          }
+          return { stdout: '', stderr: '', exitCode: 0 };
+        }
+        return { stdout: '', stderr: '', exitCode: 0 };
+      },
+      reverse: {
+        ensure: async () => {},
+        remove: async () => {},
+        removeAllOwned: async () => {},
+      },
+    },
+    { serial: 'emulator-5554' },
+    async () => {
+      await assertRejectsAppError(() => killAndroidApp(device, 'com.example.app'), {
+        code: 'COMMAND_FAILED',
+        hint: /Background the app before killApp/,
+        details: { reason: 'android-kill-requires-background-app' },
+      });
+    },
+  );
+
+  assert.equal(foregroundReads, 2);
 });
 
 test('killAndroidApp fails when the process survives the kill', async () => {
diff --git a/packages/platform-android/src/app-lifecycle.ts b/packages/platform-android/src/app-lifecycle.ts
index ec04525266..eb6247d70f 100644
--- a/packages/platform-android/src/app-lifecycle.ts
+++ b/packages/platform-android/src/app-lifecycle.ts
@@ -563,23 +563,24 @@ async function readAndroidForegroundApp(device: DeviceInfo): Promise<AppStateRun
 }
 
 /**
- * `killAndroidPackage`'s precondition needs the opposite corroboration from
- * `waitForAndroidPackageProcessGone`'s "gone twice in a row counts": here a read naming a
- * different app is not enough on its own to trust "safe to kill". Live evidence (2026-09-25,
- * Android 16 emulator): immediately after `launchApp`, `dumpsys window`'s `mCurrentFocus` still
- * named the previous foreground app for one read while `dumpsys activity activities` already
- * showed the launched app resumed — `getAndroidAppState` takes whichever dump answers first, so
- * that stale window-focus read alone would have skipped the `android-kill-requires-background-app`
- * refusal against a target still genuinely in the foreground. A same-app read is trusted
- * immediately (refusing early is always safe); a different-app or unreadable read is corroborated
- * once after a short settle before this lets `killAndroidPackage` proceed.
+ * `killAndroidPackage`'s precondition corroborates either foreground read once:
+ * `mCurrentFocus` can lag one sample behind the resumed activity both after
+ * `launchApp` (stale different-app read would skip a required refusal) and
+ * after `pressKey: Home` (stale same-app read would spuriously refuse a legal
+ * kill). A confirmatory read after a short settle decides; an unreadable
+ * confirm keeps the first same-app refusal.
  */
 async function readAndroidForegroundAppSettled(
   device: DeviceInfo,
   packageName: string,
 ): Promise<AppStateRuntimeResult | null> {
   const first = await readAndroidForegroundApp(device);
-  if (first?.package === packageName) return first;
+  if (first?.package === packageName) {
+    await sleep(ANDROID_KILL_FOREGROUND_STABLE_MS);
+    const confirmed = await readAndroidForegroundApp(device);
+    if (confirmed && confirmed.package !== packageName) return confirmed;
+    return first;
+  }
   await sleep(ANDROID_KILL_FOREGROUND_STABLE_MS);
   return await readAndroidForegroundApp(device);
 }
diff --git a/src/daemon/session-lifecycle/internal/__tests__/session-close-without-session-mode.test.ts b/src/daemon/session-lifecycle/internal/__tests__/session-close-without-session-mode.test.ts
index bc7dbc26cc..322610dc19 100644
--- a/src/daemon/session-lifecycle/internal/__tests__/session-close-without-session-mode.test.ts
+++ b/src/daemon/session-lifecycle/internal/__tests__/session-close-without-session-mode.test.ts
@@ -48,7 +48,13 @@ function makeSessionStore(): SessionStore {
 test('an app-only kill close with no stored session still carries mode kill to the platform close', async () => {
   const sessionStore = makeSessionStore();
   mockResolveTargetDevice.mockResolvedValue(ANDROID_DEVICE);
-  const seenModes: Array<unknown> = [];
+  const seenInputs: Array<{
+    mode?: unknown;
+    positionals?: unknown;
+    surface?: unknown;
+    outPath?: unknown;
+    ensureReady?: unknown;
+  }> = [];
   const baseBind = mockBindDeviceRuntime.getMockImplementation();
   mockBindDeviceRuntime.mockImplementationOnce(async (device, use) => {
     const binding = await baseBind!(device, use);
@@ -59,7 +65,7 @@ test('an app-only kill close with no stored session still carries mode kill to t
       operations: {
         ...binding.operations,
         closeApplication: async (input: Parameters<typeof innerClose>[0]) => {
-          seenModes.push(input.mode);
+          seenInputs.push(input);
         },
       },
     };
@@ -81,5 +87,10 @@ test('an app-only kill close with no stored session still carries mode kill to t
   });
 
   expect(response?.ok).toBe(true);
-  expect(seenModes).toEqual(['kill']);
+  expect(seenInputs).toHaveLength(1);
+  expect(seenInputs[0]?.mode).toBe('kill');
+  expect(seenInputs[0]?.positionals).toEqual(['com.example.app']);
+  expect(seenInputs[0]?.surface).toBe('app');
+  expect(seenInputs[0]?.outPath).toBeUndefined();
+  expect(seenInputs[0]?.ensureReady).toBe(true);
 });

From 77d2eab7366d7df607cad5c0e89b3919cce12406 Mon Sep 17 00:00:00 2001
From: Rohit <40559587+Rohit3523@users.noreply.github.com>
Date: Sat, 26 Sep 2026 01:47:00 +0530
Subject: [PATCH 130/132] fix(maestro): read the kill precondition from the AMS
 resumed activity

WMS mCurrentFocus can lag activity resume after launchApp, name a system
window holding focus instead of the resumed app (#592), or name a
transient window (IME, dialog), so a focus-based precondition gives the
wrong typed reason in either direction and a settle-and-reread cannot
repair the source.

- window-state: new resumedActivity question backed only by the activity
  dumps, with getAndroidResumedActivity; app-parsers owns the resumed
  markers and a resumed-only line parser
- app-lifecycle: killAndroidPackage reads the resumed activity in one
  shot; the sleep-and-reread helper and its constant are gone
- kill tests: AMS fixtures with disagreeing WMS focus (stale launcher
  focus plus resumed target refuses; target focus plus resumed launcher
  proceeds), kept hermetic with a memo reset
---
 .../src/__tests__/app-lifecycle-kill.test.ts  | 323 ++++++------------
 .../platform-android/src/app-lifecycle.ts     |  33 +-
 packages/platform-android/src/app-parsers.ts  |  32 +-
 packages/platform-android/src/window-state.ts |  32 +-
 4 files changed, 171 insertions(+), 249 deletions(-)

diff --git a/packages/platform-android/src/__tests__/app-lifecycle-kill.test.ts b/packages/platform-android/src/__tests__/app-lifecycle-kill.test.ts
index 1f14704c7c..52301db542 100644
--- a/packages/platform-android/src/__tests__/app-lifecycle-kill.test.ts
+++ b/packages/platform-android/src/__tests__/app-lifecycle-kill.test.ts
@@ -1,47 +1,71 @@
-import { test } from 'vitest';
+import { beforeEach, test } from 'vitest';
 import assert from 'node:assert/strict';
 import { killAndroidApp } from '../app-lifecycle.ts';
 import { withAndroidAdbProvider } from '../adb-executor.ts';
+import { resetAndroidWindowDumpFocusMemoForTests } from '../window-state.ts';
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import { assertRejectsAppError } from './test-utils/app-error.ts';
 import './test-utils/android-host-test-setup.ts';
 
+// The kill precondition reads the AMS resumed activity, never WMS focus: input-focus transfer
+// can lag activity resume after `launchApp`, a system window can own the focus while the target
+// stays resumed (#592), and a transient window (IME, dialog) can own it for one sample. These
+// tests pin that authority against AMS fixtures paired with a disagreeing WMS focus dump.
+
+const RESUMED_TARGET_DUMP =
+  '  mResumedActivity: ActivityRecord{99 u0 com.example.app/.MainActivity t7}\n';
+const RESUMED_LAUNCHER_DUMP =
+  '  mResumedActivity: ActivityRecord{98 u0 com.android.launcher/.Launcher t1}\n';
+const STALE_LAUNCHER_FOCUS_DUMP = 'mCurrentFocus=Window{43 u0 com.android.launcher/.Launcher}\n';
+const TARGET_FOCUS_DUMP = 'mCurrentFocus=Window{42 u0 com.example.app/.MainActivity}\n';
+
+const dumpsysActivityActivities = ['shell', 'dumpsys', 'activity', 'activities'].join(' ');
+const dumpsysWindowWindows = ['shell', 'dumpsys', 'window', 'windows'].join(' ');
+const amKillTarget = ['shell', 'am', 'kill', 'com.example.app'].join(' ');
+const pidofTarget = ['shell', 'pidof', 'com.example.app'].join(' ');
+
+const DEVICE: DeviceInfo = {
+  platform: 'android',
+  id: 'emulator-5554',
+  name: 'Pixel',
+  kind: 'emulator',
+  booted: true,
+};
+
+const noReverse = {
+  ensure: async () => {},
+  remove: async () => {},
+  removeAllOwned: async () => {},
+};
+
+beforeEach(() => {
+  resetAndroidWindowDumpFocusMemoForTests();
+});
+
 test('killAndroidApp dispatches am kill rather than am force-stop', async () => {
-  const device: DeviceInfo = {
-    platform: 'android',
-    id: 'emulator-5554',
-    name: 'Pixel',
-    kind: 'emulator',
-    booted: true,
-  };
   const calls: (readonly string[])[] = [];
 
   await withAndroidAdbProvider(
     {
       exec: async (args) => {
         calls.push(args);
-        if (args.join(' ') === 'shell dumpsys window windows') {
-          return {
-            stdout: 'mCurrentFocus=Window{43 u0 com.android.launcher/.Launcher}\n',
-            stderr: '',
-            exitCode: 0,
-          };
+        const command = args.join(' ');
+        if (command === dumpsysActivityActivities) {
+          return { stdout: RESUMED_LAUNCHER_DUMP, stderr: '', exitCode: 0 };
+        }
+        if (command === dumpsysWindowWindows) {
+          return { stdout: STALE_LAUNCHER_FOCUS_DUMP, stderr: '', exitCode: 0 };
         }
         return { stdout: '', stderr: '', exitCode: 0 };
       },
-      reverse: {
-        ensure: async () => {},
-        remove: async () => {},
-        removeAllOwned: async () => {},
-      },
+      reverse: noReverse,
     },
     { serial: 'emulator-5554' },
-    async () => await killAndroidApp(device, 'com.example.app'),
+    async () => await killAndroidApp(DEVICE, 'com.example.app'),
   );
 
   assert.deepEqual(calls, [
-    ['shell', 'dumpsys', 'window', 'windows'],
-    ['shell', 'dumpsys', 'window', 'windows'],
+    ['shell', 'dumpsys', 'activity', 'activities'],
     ['shell', 'am', 'kill', 'com.example.app'],
     ['shell', 'dumpsys', 'window', 'windows'],
     ['shell', 'pidof', 'com.example.app'],
@@ -50,43 +74,30 @@ test('killAndroidApp dispatches am kill rather than am force-stop', async () =>
   ]);
 });
 
-// Live evidence (2026-09-25, Android 16 emulator): immediately after `launchApp`,
-// `dumpsys window`'s `mCurrentFocus` still named the previous foreground app for one read while
-// `dumpsys activity activities` already showed the launched app resumed. A single "not the target"
-// foreground read is not proof the target left the foreground, so `killAndroidApp` corroborates it
-// once before trusting it enough to skip the `android-kill-requires-background-app` refusal.
-test('killAndroidApp refuses when a corroborating read shows the target back in the foreground', async () => {
-  const device: DeviceInfo = {
-    platform: 'android',
-    id: 'emulator-5554',
-    name: 'Pixel',
-    kind: 'emulator',
-    booted: true,
-  };
-  let foregroundReads = 0;
+test('killAndroidApp refuses when the resumed activity names the target behind stale launcher focus', async () => {
+  const calls: (readonly string[])[] = [];
 
   await withAndroidAdbProvider(
     {
       exec: async (args) => {
-        if (args.join(' ') === 'shell dumpsys window windows') {
-          foregroundReads += 1;
-          const stdout =
-            foregroundReads === 1
-              ? 'mCurrentFocus=Window{43 u0 com.android.launcher/.Launcher}\n'
-              : 'mCurrentFocus=Window{44 u0 com.example.app/.MainActivity}\n';
-          return { stdout, stderr: '', exitCode: 0 };
+        calls.push(args);
+        const command = args.join(' ');
+        // Stale WMS focus right after `launchApp`: the previous app still owns the focused
+        // window while AMS already shows the target resumed. The old foreground-first read
+        // trusted this dump and skipped the refusal.
+        if (command === dumpsysWindowWindows) {
+          return { stdout: STALE_LAUNCHER_FOCUS_DUMP, stderr: '', exitCode: 0 };
+        }
+        if (command === dumpsysActivityActivities) {
+          return { stdout: RESUMED_TARGET_DUMP, stderr: '', exitCode: 0 };
         }
         return { stdout: '', stderr: '', exitCode: 0 };
       },
-      reverse: {
-        ensure: async () => {},
-        remove: async () => {},
-        removeAllOwned: async () => {},
-      },
+      reverse: noReverse,
     },
     { serial: 'emulator-5554' },
     async () => {
-      await assertRejectsAppError(() => killAndroidApp(device, 'com.example.app'), {
+      await assertRejectsAppError(() => killAndroidApp(DEVICE, 'com.example.app'), {
         code: 'COMMAND_FAILED',
         hint: /Background the app before killApp/,
         details: { reason: 'android-kill-requires-background-app' },
@@ -94,173 +105,66 @@ test('killAndroidApp refuses when a corroborating read shows the target back in
     },
   );
 
-  assert.equal(foregroundReads, 2);
+  // The precondition never consults WMS focus: one AMS read decides, and no kill is dispatched.
+  assert.deepEqual(calls, [['shell', 'dumpsys', 'activity', 'activities']]);
 });
 
-test('killAndroidApp refuses a foreground target before killing', async () => {
-  const device: DeviceInfo = {
-    platform: 'android',
-    id: 'emulator-5554',
-    name: 'Pixel',
-    kind: 'emulator',
-    booted: true,
-  };
+test('killAndroidApp proceeds when focus still names the target but the resumed activity moved on', async () => {
   const calls: (readonly string[])[] = [];
+  let windowReads = 0;
 
   await withAndroidAdbProvider(
     {
       exec: async (args) => {
         calls.push(args);
-        if (args.join(' ') === 'shell dumpsys window windows') {
+        const command = args.join(' ');
+        if (command === dumpsysActivityActivities) {
+          return { stdout: RESUMED_LAUNCHER_DUMP, stderr: '', exitCode: 0 };
+        }
+        if (command === dumpsysWindowWindows) {
+          windowReads += 1;
+          // WMS focus still names the target (lag after `pressKey: Home`, or a transient
+          // window); the first window read happens after the kill, in the stop wait.
           return {
-            stdout: 'mCurrentFocus=Window{42 u0 com.example.app/.MainActivity}\n',
+            stdout: windowReads === 1 ? TARGET_FOCUS_DUMP : STALE_LAUNCHER_FOCUS_DUMP,
             stderr: '',
             exitCode: 0,
           };
         }
         return { stdout: '', stderr: '', exitCode: 0 };
       },
-      reverse: {
-        ensure: async () => {},
-        remove: async () => {},
-        removeAllOwned: async () => {},
-      },
+      reverse: noReverse,
     },
     { serial: 'emulator-5554' },
-    async () => {
-      await assertRejectsAppError(() => killAndroidApp(device, 'com.example.app'), {
-        code: 'COMMAND_FAILED',
-        hint: /Background the app before killApp/,
-        details: { reason: 'android-kill-requires-background-app' },
-      });
-    },
+    async () => await killAndroidApp(DEVICE, 'com.example.app'),
   );
 
-  assert.deepEqual(calls, [
-    ['shell', 'dumpsys', 'window', 'windows'],
-    ['shell', 'dumpsys', 'window', 'windows'],
-  ]);
-});
-
-test('killAndroidApp proceeds when a stale same-app read settles to background', async () => {
-  const device: DeviceInfo = {
-    platform: 'android',
-    id: 'emulator-5554',
-    name: 'Pixel',
-    kind: 'emulator',
-    booted: true,
-  };
-  let foregroundReads = 0;
-  const calls: (readonly string[])[] = [];
-
-  await withAndroidAdbProvider(
-    {
-      exec: async (args) => {
-        calls.push(args);
-        if (args.join(' ') === 'shell dumpsys window windows') {
-          foregroundReads += 1;
-          // First read still names the target (stale `mCurrentFocus` right after
-          // `pressKey: Home`); later reads see the launcher so the kill completes.
-          const stdout =
-            foregroundReads === 1
-              ? 'mCurrentFocus=Window{42 u0 com.example.app/.MainActivity}\n'
-              : 'mCurrentFocus=Window{43 u0 com.android.launcher/.Launcher}\n';
-          return { stdout, stderr: '', exitCode: 0 };
-        }
-        return { stdout: '', stderr: '', exitCode: 0 };
-      },
-      reverse: {
-        ensure: async () => {},
-        remove: async () => {},
-        removeAllOwned: async () => {},
-      },
-    },
-    { serial: 'emulator-5554' },
-    async () => await killAndroidApp(device, 'com.example.app'),
-  );
-
-  assert.equal(foregroundReads >= 2, true);
-  assert.ok(calls.some((args) => args.join(' ') === 'shell am kill com.example.app'));
-});
-
-test('killAndroidApp fails closed when the confirmatory read cannot answer', async () => {
-  const device: DeviceInfo = {
-    platform: 'android',
-    id: 'emulator-5554',
-    name: 'Pixel',
-    kind: 'emulator',
-    booted: true,
-  };
-  let foregroundReads = 0;
-
-  await withAndroidAdbProvider(
-    {
-      exec: async (args) => {
-        if (args.join(' ') === 'shell dumpsys window windows') {
-          foregroundReads += 1;
-          if (foregroundReads === 1) {
-            return {
-              stdout: 'mCurrentFocus=Window{42 u0 com.example.app/.MainActivity}\n',
-              stderr: '',
-              exitCode: 0,
-            };
-          }
-          return { stdout: '', stderr: '', exitCode: 0 };
-        }
-        return { stdout: '', stderr: '', exitCode: 0 };
-      },
-      reverse: {
-        ensure: async () => {},
-        remove: async () => {},
-        removeAllOwned: async () => {},
-      },
-    },
-    { serial: 'emulator-5554' },
-    async () => {
-      await assertRejectsAppError(() => killAndroidApp(device, 'com.example.app'), {
-        code: 'COMMAND_FAILED',
-        hint: /Background the app before killApp/,
-        details: { reason: 'android-kill-requires-background-app' },
-      });
-    },
-  );
-
-  assert.equal(foregroundReads, 2);
+  // The AMS read comes first and the kill is dispatched even though WMS named the target.
+  assert.deepEqual(calls[0], ['shell', 'dumpsys', 'activity', 'activities']);
+  assert.ok(calls.some((args) => args.join(' ') === amKillTarget));
 });
 
 test('killAndroidApp fails when the process survives the kill', async () => {
-  const device: DeviceInfo = {
-    platform: 'android',
-    id: 'emulator-5554',
-    name: 'Pixel',
-    kind: 'emulator',
-    booted: true,
-  };
-
   await withAndroidAdbProvider(
     {
       exec: async (args) => {
-        if (args.join(' ') === 'shell dumpsys window windows') {
-          return {
-            stdout: 'mCurrentFocus=Window{43 u0 com.android.launcher/.Launcher}\n',
-            stderr: '',
-            exitCode: 0,
-          };
+        const command = args.join(' ');
+        if (command === dumpsysActivityActivities) {
+          return { stdout: RESUMED_LAUNCHER_DUMP, stderr: '', exitCode: 0 };
+        }
+        if (command === dumpsysWindowWindows) {
+          return { stdout: STALE_LAUNCHER_FOCUS_DUMP, stderr: '', exitCode: 0 };
         }
-        if (args.join(' ') === 'shell pidof com.example.app') {
+        if (command === pidofTarget) {
           return { stdout: '12345\n', stderr: '', exitCode: 0 };
         }
         return { stdout: '', stderr: '', exitCode: 0 };
       },
-      reverse: {
-        ensure: async () => {},
-        remove: async () => {},
-        removeAllOwned: async () => {},
-      },
+      reverse: noReverse,
     },
     { serial: 'emulator-5554' },
     async () => {
-      await assertRejectsAppError(() => killAndroidApp(device, 'com.example.app'), {
+      await assertRejectsAppError(() => killAndroidApp(DEVICE, 'com.example.app'), {
         code: 'COMMAND_FAILED',
         hint: /foreground service|force-stop/,
         details: { reason: 'android-kill-process-survived' },
@@ -270,38 +174,26 @@ test('killAndroidApp fails when the process survives the kill', async () => {
 });
 
 test('killAndroidApp fails when the liveness probe itself cannot answer', async () => {
-  const device: DeviceInfo = {
-    platform: 'android',
-    id: 'emulator-5554',
-    name: 'Pixel',
-    kind: 'emulator',
-    booted: true,
-  };
-
   await withAndroidAdbProvider(
     {
       exec: async (args) => {
-        if (args.join(' ') === 'shell dumpsys window windows') {
-          return {
-            stdout: 'mCurrentFocus=Window{43 u0 com.android.launcher/.Launcher}\n',
-            stderr: '',
-            exitCode: 0,
-          };
+        const command = args.join(' ');
+        if (command === dumpsysActivityActivities) {
+          return { stdout: RESUMED_LAUNCHER_DUMP, stderr: '', exitCode: 0 };
+        }
+        if (command === dumpsysWindowWindows) {
+          return { stdout: STALE_LAUNCHER_FOCUS_DUMP, stderr: '', exitCode: 0 };
         }
-        if (args.join(' ') === 'shell pidof com.example.app') {
+        if (command === pidofTarget) {
           return { stdout: '', stderr: 'error: device offline\n', exitCode: 1 };
         }
         return { stdout: '', stderr: '', exitCode: 0 };
       },
-      reverse: {
-        ensure: async () => {},
-        remove: async () => {},
-        removeAllOwned: async () => {},
-      },
+      reverse: noReverse,
     },
     { serial: 'emulator-5554' },
     async () => {
-      await assertRejectsAppError(() => killAndroidApp(device, 'com.example.app'), {
+      await assertRejectsAppError(() => killAndroidApp(DEVICE, 'com.example.app'), {
         code: 'COMMAND_FAILED',
         hint: /pidof did not answer/,
         details: { reason: 'android-process-probe-unavailable' },
@@ -310,14 +202,7 @@ test('killAndroidApp fails when the liveness probe itself cannot answer', async
   );
 });
 
-test('killAndroidApp fails closed when the foreground probe cannot answer', async () => {
-  const device: DeviceInfo = {
-    platform: 'android',
-    id: 'emulator-5554',
-    name: 'Pixel',
-    kind: 'emulator',
-    booted: true,
-  };
+test('killAndroidApp fails closed when the resumed-activity probe cannot answer', async () => {
   const calls: (readonly string[])[] = [];
 
   await withAndroidAdbProvider(
@@ -326,15 +211,11 @@ test('killAndroidApp fails closed when the foreground probe cannot answer', asyn
         calls.push(args);
         return { stdout: '', stderr: '', exitCode: 0 };
       },
-      reverse: {
-        ensure: async () => {},
-        remove: async () => {},
-        removeAllOwned: async () => {},
-      },
+      reverse: noReverse,
     },
     { serial: 'emulator-5554' },
     async () => {
-      await assertRejectsAppError(() => killAndroidApp(device, 'com.example.app'), {
+      await assertRejectsAppError(() => killAndroidApp(DEVICE, 'com.example.app'), {
         code: 'COMMAND_FAILED',
         hint: /dumpsys did not answer/,
         details: { reason: 'android-process-probe-unavailable' },
@@ -342,5 +223,9 @@ test('killAndroidApp fails closed when the foreground probe cannot answer', asyn
     },
   );
 
-  assert.ok(!calls.some((args) => args.join(' ').includes('am kill')));
+  // Both AMS variants are asked before failing closed, and no kill is dispatched.
+  assert.deepEqual(calls, [
+    ['shell', 'dumpsys', 'activity', 'activities'],
+    ['shell', 'dumpsys', 'activity'],
+  ]);
 });
diff --git a/packages/platform-android/src/app-lifecycle.ts b/packages/platform-android/src/app-lifecycle.ts
index eb6247d70f..b76240b642 100644
--- a/packages/platform-android/src/app-lifecycle.ts
+++ b/packages/platform-android/src/app-lifecycle.ts
@@ -22,7 +22,7 @@ import {
   parseAndroidLaunchablePackages,
   parseAndroidUserInstalledPackages,
 } from './app-parsers.ts';
-import { getAndroidAppState } from './window-state.ts';
+import { getAndroidAppState, getAndroidResumedActivity } from './window-state.ts';
 
 const ANDROID_LAUNCHER_CATEGORY = 'android.intent.category.LAUNCHER';
 const ANDROID_LEANBACK_CATEGORY = 'android.intent.category.LEANBACK_LAUNCHER';
@@ -33,7 +33,6 @@ const ANDROID_CLOSE_FOCUS_POLL_MS = 50;
 const ANDROID_CLOSE_PROCESS_TIMEOUT_MS = 2_000;
 const ANDROID_CLOSE_PROCESS_POLL_MS = 50;
 const ANDROID_CLOSE_PROCESS_GONE_STABLE_MS = 150;
-const ANDROID_KILL_FOREGROUND_STABLE_MS = 150;
 
 export async function listAndroidApps(
   device: DeviceInfo,
@@ -510,17 +509,17 @@ export async function killAndroidApp(device: DeviceInfo, app: string): Promise<v
 }
 
 async function killAndroidPackage(device: DeviceInfo, packageName: string): Promise<void> {
-  const foreground = await readAndroidForegroundAppSettled(device, packageName);
-  if (foreground?.package === packageName) {
+  const resumed = await readAndroidResumedActivity(device);
+  if (resumed?.package === packageName) {
     throw new AppError('COMMAND_FAILED', `Cannot kill foreground app ${packageName}`, {
       reason: 'android-kill-requires-background-app',
       hint: 'Background the app before killApp (for example pressKey: Home): am kill only reaps background processes.',
     });
   }
-  if (!foreground) {
+  if (!resumed) {
     throw new AppError(
       'COMMAND_FAILED',
-      `Could not read foreground state before killing ${packageName}`,
+      `Could not read resumed activity state before killing ${packageName}`,
       {
         reason: 'android-process-probe-unavailable',
         hint: 'adb dumpsys did not answer; retry once the device is reachable.',
@@ -562,27 +561,11 @@ async function readAndroidForegroundApp(device: DeviceInfo): Promise<AppStateRun
   return foreground.package ? foreground : null;
 }
 
-/**
- * `killAndroidPackage`'s precondition corroborates either foreground read once:
- * `mCurrentFocus` can lag one sample behind the resumed activity both after
- * `launchApp` (stale different-app read would skip a required refusal) and
- * after `pressKey: Home` (stale same-app read would spuriously refuse a legal
- * kill). A confirmatory read after a short settle decides; an unreadable
- * confirm keeps the first same-app refusal.
- */
-async function readAndroidForegroundAppSettled(
+async function readAndroidResumedActivity(
   device: DeviceInfo,
-  packageName: string,
 ): Promise<AppStateRuntimeResult | null> {
-  const first = await readAndroidForegroundApp(device);
-  if (first?.package === packageName) {
-    await sleep(ANDROID_KILL_FOREGROUND_STABLE_MS);
-    const confirmed = await readAndroidForegroundApp(device);
-    if (confirmed && confirmed.package !== packageName) return confirmed;
-    return first;
-  }
-  await sleep(ANDROID_KILL_FOREGROUND_STABLE_MS);
-  return await readAndroidForegroundApp(device);
+  const resumed = await getAndroidResumedActivity(device);
+  return resumed.package ? resumed : null;
 }
 
 async function waitForAndroidPackageProcessGone(
diff --git a/packages/platform-android/src/app-parsers.ts b/packages/platform-android/src/app-parsers.ts
index 6dcfdd09bc..27228f8e07 100644
--- a/packages/platform-android/src/app-parsers.ts
+++ b/packages/platform-android/src/app-parsers.ts
@@ -12,12 +12,17 @@ export type AndroidBlockingDialogFocus = {
  */
 export const ANDROID_FOCUSED_WINDOW_MARKER = 'mCurrentFocus=Window{';
 
+/** Markers that name the ActivityManager resumed activity in a `dumpsys activity` dump. */
+export const ANDROID_RESUMED_ACTIVITY_MARKERS = [
+  'mResumedActivity:',
+  'ResumedActivity:',
+] as const;
+
 /** The line prefixes a `dumpsys` dump uses to name the focused window or resumed activity. */
 export const ANDROID_FOCUS_MARKERS = [
   ANDROID_FOCUSED_WINDOW_MARKER,
   'mFocusedApp=AppWindowToken{',
-  'mResumedActivity:',
-  'ResumedActivity:',
+  ...ANDROID_RESUMED_ACTIVITY_MARKERS,
 ] as const;
 const ANDROID_ANR_TITLE_PATTERN = /\bApplication Not Responding:\s*([A-Za-z0-9_.]+)/i;
 const ANDROID_PACKAGE_PATTERN = /\b([A-Za-z][A-Za-z0-9_]*(?:\.[A-Za-z0-9_]+)+)\b/;
@@ -90,6 +95,29 @@ export function parseAndroidFocusSegment<T>(
   return null;
 }
 
+/**
+ * Reads the resumed activity out of an AMS dump (`dumpsys activity …`). Only a
+ * resumed-marker line counts: an activity dump lists the whole back stack, so any
+ * other `package/Activity` token is not evidence about what is resumed.
+ */
+export function parseAndroidResumedActivity(
+  text: string,
+): { package: string; activity: string } | null {
+  for (const line of text.split('\n')) {
+    for (const marker of ANDROID_RESUMED_ACTIVITY_MARKERS) {
+      const markerIndex = line.indexOf(marker);
+      if (markerIndex === -1) continue;
+      const component = line
+        .slice(markerIndex + marker.length)
+        .match(/\b([A-Za-z][A-Za-z0-9_]*(?:\.[A-Za-z0-9_]+)+)\/([A-Za-z0-9_.$]+)/);
+      if (component?.[1] && component[2]) {
+        return { package: component[1], activity: component[2] };
+      }
+    }
+  }
+  return null;
+}
+
 function parseAndroidBlockingDialogFromSegment(
   segment: string,
   raw: string,
diff --git a/packages/platform-android/src/window-state.ts b/packages/platform-android/src/window-state.ts
index f41d290221..57bb37aedd 100644
--- a/packages/platform-android/src/window-state.ts
+++ b/packages/platform-android/src/window-state.ts
@@ -4,14 +4,17 @@ import { runAndroidShell } from './adb.ts';
 import {
   ANDROID_FOCUSED_WINDOW_MARKER,
   ANDROID_FOCUS_MARKERS,
+  ANDROID_RESUMED_ACTIVITY_MARKERS,
+  parseAndroidResumedActivity,
   readAndroidBlockingDialogFocus,
   type AndroidBlockingDialogFocus,
 } from './app-parsers.ts';
 
 /**
- * What is on the Android screen right now: which app owns the foreground, and whether a blocking
- * system dialog owns the focus. Both answers come out of the same `dumpsys` text, so the dump
- * sequence is owned here once instead of being repeated per question.
+ * What is on the Android screen right now: which app owns the foreground, which activity AMS
+ * reports resumed, and whether a blocking system dialog owns the focus. Every answer comes out
+ * of the same `dumpsys` text, so the dump sequence is owned here once instead of being repeated
+ * per question.
  */
 
 // What WMS says owns the focus. Ranked ahead of the activity dumps because that is what the user
@@ -49,6 +52,14 @@ const ANDROID_WINDOW_QUESTIONS = {
     tiers: [ANDROID_WINDOW_FOCUS_DUMPS, ANDROID_RESUMED_ACTIVITY_DUMPS],
     section: markerSectionPattern(ANDROID_FOCUS_MARKERS),
   },
+  // Which activity AMS reports resumed: the authority for `am kill`, which reaps on process
+  // state rather than input focus. WMS focus can lag activity resume after `launchApp`, name a
+  // system window holding focus instead of the resumed app (#592), or name a transient window
+  // (IME, dialog), so the kill precondition asks this rather than `foreground`.
+  resumedActivity: {
+    tiers: [ANDROID_RESUMED_ACTIVITY_DUMPS],
+    section: markerSectionPattern(ANDROID_RESUMED_ACTIVITY_MARKERS),
+  },
   // Whether a blocking dialog owns the focus: only the focused-window line can carry that title,
   // and only the window dumps print it.
   blockingDialog: {
@@ -135,6 +146,21 @@ export async function getAndroidAppState(
   return {};
 }
 
+/**
+ * Which app AMS reports resumed, without consulting WMS focus. Backed only by the activity
+ * dumps: the kill precondition's source of truth for whether `am kill` can reap the target.
+ */
+export async function getAndroidResumedActivity(
+  device: DeviceInfo,
+  read: AndroidWindowDumpReader = createAndroidWindowDumpReader(device),
+): Promise<AppStateRuntimeResult> {
+  for (const args of orderAndroidWindowDumps(device, 'resumedActivity')) {
+    const state = parseAndroidResumedActivity(await read(args));
+    if (state) return state;
+  }
+  return {};
+}
+
 /**
  * A dump that shows the focused window has answered the blocking-dialog question, whether or not
  * the answer is a dialog. The remaining variants exist for devices whose earlier one says nothing

From c76f103c39eaf896d7e9d611cb02cc42e6fcb3de Mon Sep 17 00:00:00 2001
From: Rohit <40559587+Rohit3523@users.noreply.github.com>
Date: Sat, 26 Sep 2026 02:16:32 +0530
Subject: [PATCH 131/132] fix(maestro): anchor the resumed-activity parse and
 cover all AMS marker shapes

- app-parsers: recognize topResumedActivity= (newer dumps expose only that
  field), and require a resumed marker at field start so mLastResumedActivity
  can never refuse a kill as a stale record
- kill tests: pin the full AMS-first adb sequence for the moved-on focus case
- parser tests: every marker shape parses; a lone last-resumed record reads
  as no resumed activity
---
 .../src/__tests__/app-lifecycle-kill.test.ts  | 14 ++++++--
 .../src/__tests__/app-parsers.test.ts         | 32 ++++++++++++++++++-
 packages/platform-android/src/app-parsers.ts  |  6 +++-
 3 files changed, 47 insertions(+), 5 deletions(-)

diff --git a/packages/platform-android/src/__tests__/app-lifecycle-kill.test.ts b/packages/platform-android/src/__tests__/app-lifecycle-kill.test.ts
index 52301db542..832a778b2a 100644
--- a/packages/platform-android/src/__tests__/app-lifecycle-kill.test.ts
+++ b/packages/platform-android/src/__tests__/app-lifecycle-kill.test.ts
@@ -21,7 +21,6 @@ const TARGET_FOCUS_DUMP = 'mCurrentFocus=Window{42 u0 com.example.app/.MainActiv
 
 const dumpsysActivityActivities = ['shell', 'dumpsys', 'activity', 'activities'].join(' ');
 const dumpsysWindowWindows = ['shell', 'dumpsys', 'window', 'windows'].join(' ');
-const amKillTarget = ['shell', 'am', 'kill', 'com.example.app'].join(' ');
 const pidofTarget = ['shell', 'pidof', 'com.example.app'].join(' ');
 
 const DEVICE: DeviceInfo = {
@@ -140,8 +139,17 @@ test('killAndroidApp proceeds when focus still names the target but the resumed
   );
 
   // The AMS read comes first and the kill is dispatched even though WMS named the target.
-  assert.deepEqual(calls[0], ['shell', 'dumpsys', 'activity', 'activities']);
-  assert.ok(calls.some((args) => args.join(' ') === amKillTarget));
+  // The full sequence pins that no WMS read happens before the kill: the two window reads are
+  // the post-kill stop wait (TARGET focus once, then STALE).
+  assert.deepEqual(calls, [
+    ['shell', 'dumpsys', 'activity', 'activities'],
+    ['shell', 'am', 'kill', 'com.example.app'],
+    ['shell', 'dumpsys', 'window', 'windows'],
+    ['shell', 'dumpsys', 'window', 'windows'],
+    ['shell', 'pidof', 'com.example.app'],
+    ['shell', 'pidof', 'com.example.app'],
+    ['shell', 'pidof', 'com.example.app'],
+  ]);
 });
 
 test('killAndroidApp fails when the process survives the kill', async () => {
diff --git a/packages/platform-android/src/__tests__/app-parsers.test.ts b/packages/platform-android/src/__tests__/app-parsers.test.ts
index fe5c1d7277..d92636a7e3 100644
--- a/packages/platform-android/src/__tests__/app-parsers.test.ts
+++ b/packages/platform-android/src/__tests__/app-parsers.test.ts
@@ -1,6 +1,10 @@
 import { test } from 'vitest';
 import assert from 'node:assert/strict';
-import { parseAndroidLaunchablePackages, readAndroidBlockingDialogFocus } from '../app-parsers.ts';
+import {
+  parseAndroidLaunchablePackages,
+  parseAndroidResumedActivity,
+  readAndroidBlockingDialogFocus,
+} from '../app-parsers.ts';
 
 test('parseAndroidLaunchablePackages ignores cmd package query metadata lines', () => {
   assert.deepEqual(
@@ -32,3 +36,29 @@ test('readAndroidBlockingDialogFocus preserves responding window text without re
     },
   );
 });
+
+test('parseAndroidResumedActivity reads every resumed-marker shape', () => {
+  assert.deepEqual(
+    parseAndroidResumedActivity(
+      '  mResumedActivity: ActivityRecord{99 u0 com.example.app/.MainActivity t7}\n',
+    ),
+    { package: 'com.example.app', activity: '.MainActivity' },
+  );
+  assert.deepEqual(
+    parseAndroidResumedActivity(
+      '  topResumedActivity=ActivityRecord{99 u0 com.example.app/.MainActivity t7}\n',
+    ),
+    { package: 'com.example.app', activity: '.MainActivity' },
+  );
+});
+
+test('parseAndroidResumedActivity ignores a stale last-resumed record', () => {
+  // `mLastResumedActivity:` contains `ResumedActivity:` as a substring. Matching it would let a
+  // stale record refuse a kill whose current resumed field is null or names another app.
+  assert.equal(
+    parseAndroidResumedActivity(
+      '  mLastResumedActivity: ActivityRecord{98 u0 com.example.app/.MainActivity t7}\n',
+    ),
+    null,
+  );
+});
diff --git a/packages/platform-android/src/app-parsers.ts b/packages/platform-android/src/app-parsers.ts
index 27228f8e07..d95404a4b4 100644
--- a/packages/platform-android/src/app-parsers.ts
+++ b/packages/platform-android/src/app-parsers.ts
@@ -16,6 +16,7 @@ export const ANDROID_FOCUSED_WINDOW_MARKER = 'mCurrentFocus=Window{';
 export const ANDROID_RESUMED_ACTIVITY_MARKERS = [
   'mResumedActivity:',
   'ResumedActivity:',
+  'topResumedActivity=',
 ] as const;
 
 /** The line prefixes a `dumpsys` dump uses to name the focused window or resumed activity. */
@@ -106,7 +107,10 @@ export function parseAndroidResumedActivity(
   for (const line of text.split('\n')) {
     for (const marker of ANDROID_RESUMED_ACTIVITY_MARKERS) {
       const markerIndex = line.indexOf(marker);
-      if (markerIndex === -1) continue;
+      // Unanchored match would also hit stale fields such as `mLastResumedActivity:`: a
+      // marker only counts at the start of a field, i.e. at line start or after whitespace.
+      if (markerIndex === -1 || (markerIndex > 0 && /\S/.test(line[markerIndex - 1] ?? '')))
+        continue;
       const component = line
         .slice(markerIndex + marker.length)
         .match(/\b([A-Za-z][A-Za-z0-9_]*(?:\.[A-Za-z0-9_]+)+)\/([A-Za-z0-9_.$]+)/);

From 23ea708810a7eb5d4d14ab9eb7585b66330fec2c Mon Sep 17 00:00:00 2001
From: Rohit <40559587+Rohit3523@users.noreply.github.com>
Date: Sat, 26 Sep 2026 02:22:39 +0530
Subject: [PATCH 132/132] test(maestro): cover the bare ResumedActivity marker
 shape

---
 packages/platform-android/src/__tests__/app-parsers.test.ts | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/packages/platform-android/src/__tests__/app-parsers.test.ts b/packages/platform-android/src/__tests__/app-parsers.test.ts
index d92636a7e3..c643203cc2 100644
--- a/packages/platform-android/src/__tests__/app-parsers.test.ts
+++ b/packages/platform-android/src/__tests__/app-parsers.test.ts
@@ -44,6 +44,12 @@ test('parseAndroidResumedActivity reads every resumed-marker shape', () => {
     ),
     { package: 'com.example.app', activity: '.MainActivity' },
   );
+  assert.deepEqual(
+    parseAndroidResumedActivity(
+      '  ResumedActivity: ActivityRecord{99 u0 com.example.app/.MainActivity t7}\n',
+    ),
+    { package: 'com.example.app', activity: '.MainActivity' },
+  );
   assert.deepEqual(
     parseAndroidResumedActivity(
       '  topResumedActivity=ActivityRecord{99 u0 com.example.app/.MainActivity t7}\n',