refactor(ios): drop the observe-only capability probe and runner pinning

An observe-only snapshot now sends the `observeOnly` field on the snapshot
request alone. The runner enforces the no-activation contract and returns
`observation`; the host asserts that shape on the response. The separate
`uptime` capability probe, `supportsObserveOnlySnapshot`, the ready-runner-only
rule, runner session pinning and the readiness-preflight exemption existed to
survive a CLI and runner that disagree about the field, which the repo ships
together and already guards through the protocol fixture.

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

Author: thymikee

apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandDispatch.swift

@@ -42,14 +42,9 @@ extension RunnerTests {
   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.
-#if os(iOS)
-    let supportsObserveOnlySnapshot = true
-#else
-    let supportsObserveOnlySnapshot = false
-#endif
-    return Response(
+    Response(
       ok: true,
-      data: DataPayload(currentUptimeMs: currentUptimeMs(), supportsObserveOnlySnapshot: supportsObserveOnlySnapshot)
+      data: DataPayload(currentUptimeMs: currentUptimeMs())
     )
   }
 

apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift

@@ -448,7 +448,6 @@ struct DataPayload: Codable {
   var referenceWidth: Double?
   var referenceHeight: Double?
   var currentUptimeMs: Double?
-  var supportsObserveOnlySnapshot: Bool?
   var applicationState: String?
   var commandId: String?
   var lifecycleState: String?

apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+CommandDispatchTests.swift

@@ -3,14 +3,6 @@ import AgentDeviceSnapshotPresentation
 
 #if AGENT_DEVICE_RUNNER_UNIT_TESTS
 extension RunnerTests {
-  func testUptimeAdvertisesObserveOnlyOnIosOnly() {
-#if os(iOS)
-    XCTAssertEqual(executeUptime().data?.supportsObserveOnlySnapshot, true)
-#else
-    XCTAssertEqual(executeUptime().data?.supportsObserveOnlySnapshot, false)
-#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

contracts/fixtures/runner-requests.json

@@ -44,7 +44,6 @@
   {"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.interactor-snapshot.observe-only", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "snapshot", "appBundleId": "com.example.app", "observeOnly": true, "commandId": "<commandId>"}},
-  {"name": "ios-simulator.interactor-snapshot.observe-only.capability", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "uptime", "observeOnly": true, "commandId": "<commandId>"}},
   {"name": "ios-simulator.interactor-write-clipboard.text", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "pasteboardWrite", "text": "one-time code 246810", "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"}},

packages/platform-apple/src/__tests__/interactor-target-activation.test.ts

@@ -29,11 +29,7 @@ const HEALTHY_TREE = {
 function interactorServing(payload: Record<string, unknown>) {
   const runnerProvider: AppleRunnerProvider = {
     hasLiveSession: () => true,
-    runCommand: async () => ({
-      ...payload,
-      supportsObserveOnlySnapshot: true,
-      runnerSessionId: 'observation-runner',
-    }),
+    runCommand: async () => payload,
   };
   return createAppleInteractor(IOS_SIMULATOR, { appBundleId: 'com.example.app' }, runnerProvider);
 }
@@ -70,77 +66,24 @@ test.each([
     const commands: RunnerCommand[] = [];
     const runnerProvider: AppleRunnerProvider = {
       hasLiveSession: () => true,
-      runCommand: async (_device, command, options) => {
+      runCommand: async (_device, command) => {
         commands.push(command);
-        if (command.command === 'snapshot') {
-          assert.equal(options?.expectedRunnerSessionId, 'observation-runner');
-        }
-        return {
-          ...HEALTHY_TREE,
-          observation,
-          supportsObserveOnlySnapshot: true,
-          runnerSessionId: 'observation-runner',
-        };
+        return { ...HEALTHY_TREE, observation };
       },
     };
     const snapshot = (await createAppleInteractor(device, {}, runnerProvider).snapshot({
       appBundleId: 'com.example.app',
       observeOnly: true,
     })) as SnapshotResult;
-    const runnerCommand = (name: string) => commands.find((command) => command.command === name);
-    assert.equal(runnerCommand('uptime')?.observeOnly, true);
-    assert.equal(runnerCommand('snapshot')?.observeOnly, true);
+    assert.deepEqual(
+      commands.map((command) => [command.command, command.observeOnly]),
+      [['snapshot', true]],
+    );
     assert.deepEqual(snapshot.observation, observation);
     assert.equal('targetActivation' in snapshot, false);
   },
 );
 
-test('observe-only refuses a tvOS session before any runner command', async () => {
-  const commands: string[] = [];
-  const runnerProvider: AppleRunnerProvider = {
-    hasLiveSession: () => true,
-    runCommand: async (_device, command) => {
-      commands.push(command.command);
-      return {};
-    },
-  };
-  await assert.rejects(
-    createAppleInteractor(
-      { ...IOS_SIMULATOR, appleOs: 'tvos', target: 'tv' },
-      {},
-      runnerProvider,
-    ).snapshot({ appBundleId: 'com.example.app', observeOnly: true }),
-    (error: unknown) => error instanceof AppError && error.code === 'UNSUPPORTED_OPERATION',
-  );
-  assert.deepEqual(commands, []);
-});
-
-test.each([
-  { supportsObserveOnlySnapshot: false, runnerSessionId: 'observation-runner' },
-  { supportsObserveOnlySnapshot: true },
-])(
-  'observe-only rejects an unbound capability response before snapshot dispatch: %j',
-  async (capabilities) => {
-    const commands: string[] = [];
-    const runnerProvider: AppleRunnerProvider = {
-      hasLiveSession: () => true,
-      runCommand: async (_device, command) => {
-        commands.push(command.command);
-        return capabilities;
-      },
-    };
-    await assert.rejects(
-      createAppleInteractor(IOS_SIMULATOR, {}, runnerProvider).snapshot({
-        appBundleId: 'com.example.app',
-        observeOnly: true,
-      }),
-      (error: unknown) =>
-        error instanceof AppError && error.details?.reason === 'observation-unavailable',
-    );
-    assert.deepEqual(commands, ['uptime']);
-  },
-);
-
 test('observe-only refuses absent provenance rather than crediting a legacy activating runner', async () => {
   await assert.rejects(
     interactorServing(HEALTHY_TREE).snapshot({ appBundleId: 'com.example.app', observeOnly: true }),

packages/platform-apple/src/__tests__/runner-requests.test.ts

@@ -1,4 +1,3 @@
-import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import path from 'node:path';
 import { test } from 'vitest';
@@ -230,7 +229,6 @@ test('every Apple request site builds exactly its golden runner request', async
     IOS_SIMULATOR,
     { appBundleId: APP },
     recordingRunnerProvider(observationCalls, {
-      uptime: { supportsObserveOnlySnapshot: true, runnerSessionId: 'observe-only-runner' },
       snapshot: {
         nodes: [{ index: 0, type: 'Application', rect: { x: 0, y: 0, width: 390, height: 844 } }],
         observation: {
@@ -242,15 +240,10 @@ test('every Apple request site builds exactly its golden runner request', async
       },
     }),
   ).snapshot({ appBundleId: APP, observeOnly: true });
-  assert.deepEqual(
-    observationCalls.map((call) => call.command.command),
-    ['uptime', 'snapshot'],
-  );
-  assert.equal(observationCalls[1]!.options.expectedRunnerSessionId, 'observe-only-runner');
-  captured.push(
-    ['ios-simulator.interactor-snapshot.observe-only.capability', observationCalls[0]!.command],
-    ['ios-simulator.interactor-snapshot.observe-only', observationCalls[1]!.command],
-  );
+  captured.push([
+    'ios-simulator.interactor-snapshot.observe-only',
+    onlyRequest('ios-simulator.interactor-snapshot.observe-only', observationCalls),
+  ]);
   const dir = await mkdtempForTest('agent-device-runner-requests-');
   const runnerScreenshot = path.join(dir, 'runner.png');
   fs.writeFileSync(runnerScreenshot, '');

packages/platform-apple/src/interactor.ts

@@ -7,11 +7,11 @@ import { appleRemotePressCommand } from './os/tvos/remote.ts';
 import { runMacOsScreenshotAction } from './os/macos/helper.ts';
 import { actOnAppleAlert, awaitAppleAlert, readAppleAlert } from './alert.ts';
 import { runAppleRunnerCommand } from './core/runner-client.ts';
-import type { AppleRunnerCommandOptions } from './runner/runner-provider.ts';
 import {
   withAppleRunnerProvider,
   type AppleRunnerCommandExecutor,
   type AppleRunnerProvider,
+  type RunnerCommand,
 } from './runner/index.ts';
 import { toAppleTvRemoteButton } from '@agent-device/contracts/tv-remote';
 import { SCREENSHOT_FULLSCREEN_REASONS } from '@agent-device/contracts/capture';
@@ -23,12 +23,7 @@ import {
 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';
-import {
-  isHandheldAppleDevice,
-  isMacOs,
-  isTvOsDevice,
-  type DeviceInfo,
-} from '@agent-device/kernel/device';
+import { isMacOs, isTvOsDevice, type DeviceInfo } from '@agent-device/kernel/device';
 import { AppError } from '@agent-device/kernel/errors';
 import { withMethodScope } from '@agent-device/kernel/scoped-provider';
 import type { Point, SnapshotQualityVerdict } from '@agent-device/kernel/snapshot';
@@ -233,12 +228,6 @@ async function captureAppleSnapshot(
   runnerOpts: RunnerCallOptions,
   helper: MacOsHelperSurface | undefined,
 ) {
-  if (options?.observeOnly === true && !isHandheldAppleDevice(device)) {
-    throw new AppError(
-      'UNSUPPORTED_OPERATION',
-      'observe-only snapshot is supported on iOS and iPadOS only.',
-    );
-  }
   if (helper) {
     return await captureMacOsSurfaceSnapshot({ ...options, surface: helper }, options?.signal);
   }
@@ -250,25 +239,14 @@ async function captureAppleRunnerSnapshot(
   options: SnapshotOptions | undefined,
   runnerOpts: RunnerCallOptions,
 ) {
-  const observationPolicy = await snapshotObservationPolicy(device, options, runnerOpts);
   const result = readAppleSnapshotResult(
     await withDiagnosticTimer(
       'snapshot_capture',
       async () =>
         await runAppleRunnerCommand(
           device,
-          {
-            command: 'snapshot',
-            appBundleId: options?.appBundleId,
-            interactiveOnly: options?.interactiveOnly,
-            preferredBackend: options?.preferredBackend,
-            customActions: options?.customActions,
-            ...observationPolicy.request,
-            depth: options?.depth,
-            scope: options?.scope,
-            raw: options?.raw,
-          },
-          mergeRunnerCallSignal(observationPolicy.runnerOpts, options?.signal),
+          runnerSnapshotCommand(options),
+          mergeRunnerCallSignal(runnerOpts, options?.signal),
         ),
       { backend: 'xctest' },
     ),
@@ -292,33 +270,19 @@ async function captureAppleRunnerSnapshot(
   };
 }
 
-async function snapshotObservationPolicy(
-  device: DeviceInfo,
-  options: SnapshotOptions | undefined,
-  runnerOpts: RunnerCallOptions,
-): Promise<{
-  request: { observeOnly?: true };
-  runnerOpts: RunnerCallOptions & Pick<AppleRunnerCommandOptions, 'expectedRunnerSessionId'>;
-}> {
-  if (options?.observeOnly !== true) return { request: {}, runnerOpts };
-  const capabilities = await runAppleRunnerCommand(
-    device,
-    { command: 'uptime', observeOnly: true },
-    mergeRunnerCallSignal(runnerOpts, options.signal),
-  );
-  if (
-    capabilities.supportsObserveOnlySnapshot !== true ||
-    typeof capabilities.runnerSessionId !== 'string' ||
-    capabilities.runnerSessionId.length === 0
-  ) {
-    throw new AppError('COMMAND_FAILED', 'Runner does not support observe-only snapshots.', {
-      reason: 'observation-unavailable',
-      dispatched: 'no',
-    });
-  }
+function runnerSnapshotCommand(options: SnapshotOptions | undefined): RunnerCommand {
+  const { appBundleId, interactiveOnly, preferredBackend, customActions, depth, scope, raw } =
+    options ?? {};
   return {
-    request: { observeOnly: true },
-    runnerOpts: { ...runnerOpts, expectedRunnerSessionId: capabilities.runnerSessionId },
+    command: 'snapshot',
+    appBundleId,
+    interactiveOnly,
+    preferredBackend,
+    customActions,
+    ...(options?.observeOnly === true ? { observeOnly: true } : {}),
+    depth,
+    scope,
+    raw,
   };
 }
 

packages/platform-apple/src/runner/__tests__/runner-command-traits.test.ts

@@ -39,8 +39,9 @@ test('runner command trait table pins lifecycle-sensitive command groups', () =>
       'querySelector',
       'readText',
       'screenshot',
+      'snapshot',
     ],
-    payloadDependent: ['alert', 'snapshot'],
+    payloadDependent: ['alert'],
     readOnlyReadinessProbe: ['status', 'uptime'],
     readinessPreflightExemptMutation: ['activate', 'targetReset', 'terminate'],
     default: [
@@ -64,18 +65,6 @@ test('runner command trait table pins lifecycle-sensitive command groups', () =>
   assert.deepEqual(Object.values(groups).flat().sort(), [...RUNNER_COMMANDS].sort());
 });
 
-test('only an observe-only snapshot is exempt from the readiness preflight', () => {
-  assert.deepEqual(readRunnerCommandTraits({ command: 'snapshot' }), readOnly());
-  assert.deepEqual(
-    readRunnerCommandTraits({ command: 'snapshot', observeOnly: false }),
-    readOnly(),
-  );
-  assert.deepEqual(readRunnerCommandTraits({ command: 'snapshot', observeOnly: true }), {
-    ...readOnly(),
-    readinessPreflightExempt: true,
-  });
-});
-
 test('alert actions match the native read-only golden table', () => {
   // The fixture's `query` column records whether the alert request changes anything — `get` is the
   // one action that is side-effect-free — and each side consumes it under its own name: `readOnly`

packages/platform-apple/src/runner/__tests__/runner-exchange.test.ts

@@ -57,27 +57,6 @@ test('the exchange preflights a mutation and settles only its answer', async ()
   assert.deepEqual(invalidations, []);
 });
 
-test('the exchange sends an observe-only snapshot without a readiness preflight', async () => {
-  server = await startFakeRunnerServer({
-    snapshot: [{ kind: 'ok', data: { nodes: [] } }],
-  });
-  const session = sessionFor(server.port);
-
-  await executeRunnerExchange(
-    IOS_SIMULATOR,
-    session,
-    { command: 'snapshot', observeOnly: true, appBundleId: 'com.example.app' },
-    undefined,
-    10_000,
-    async () => {},
-  );
-
-  assert.deepEqual(
-    server.requests.map(({ command }) => command),
-    ['snapshot'],
-  );
-});
-
 test('the readiness probe preserves its main-thread busy report when the command omits it', async () => {
   server = await startFakeRunnerServer({
     uptime: [{ kind: 'ok', data: { runnerMainThreadBusy: true } }],

packages/platform-apple/src/runner/__tests__/runner-recovery-wiring.test.ts

@@ -597,40 +597,6 @@ test('an exact-session command never dispatches to a replacement runner', async
   assert.deepEqual(server.requests, []);
 });
 
-test('observe-only refuses an unavailable runner without creating a session', async () => {
-  await expect(
-    runAppleRunnerCommand(IOS_SIMULATOR, { command: 'snapshot', observeOnly: true }),
-  ).rejects.toMatchObject({
-    code: 'COMMAND_FAILED',
-    details: { reason: 'observation-unavailable', dispatched: 'no' },
-  });
-  expect(ensureRunnerSessionMock).not.toHaveBeenCalled();
-  expect(invalidateRunnerSessionMock).not.toHaveBeenCalled();
-});
-
-test('observe-only keeps the capability-probed identity when a replacement runner is ready', async () => {
-  server = await startFakeRunnerServer({ snapshot: [{ kind: 'ok', data: {} }] });
-  const replacement = seedSession(server.port);
-  const sessionModule = await import('../runner-session.ts');
-  const liveness = vi.spyOn(sessionModule, 'readRunnerSessionLiveness').mockReturnValue({
-    sessionId: replacement.sessionId,
-    liveness: 'ready',
-  });
-  try {
-    await expect(
-      runAppleRunnerCommand(
-        IOS_SIMULATOR,
-        { command: 'snapshot', observeOnly: true },
-        { expectedRunnerSessionId: `${replacement.sessionId}:capability-probed` },
-      ),
-    ).rejects.toThrow('runner session ownership changed');
-    assert.deepEqual(server.requests, []);
-    expect(invalidateRunnerSessionMock).not.toHaveBeenCalled();
-  } finally {
-    liveness.mockRestore();
-  }
-});
-
 test.each(
   (['accept', 'dismiss'] as const).flatMap((action) =>
     (['accepted', 'started', 'completed'] as const).map((lifecycleState) => ({