From 31e247d2f1cba2f6f55d500eb890f0575c912eda Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Fri, 13 Nov 2026 14:36:18 +0100 Subject: [PATCH 01/10] fix(apple): read the screenshot timeout where simctl states it, and boot on observed state The screenshot retry, the runner fallback and the skipped-boot-check recovery each decided from the tool's prose. `screenshot.ts` matched "timeout waiting for screen surfaces", a POSIX-domain string pair, and six spellings of a shutdown state, so any CoreSimulator wording change could silently retire all three decisions at once. `tool-provider.ts` is the one adapter that runs `xcrun simctl` itself, so it is the one place allowed to read simctl's error protocol. It takes the top-level header's `domain= NSPOSIXErrorDomain, code=60` and stamps `details.reason`; a nested `Underlying error` line, another domain or code, stdout, and a caller-supplied command or simctl callback stay unattributed. The reason is stamped, never host-kit's `timeoutMs`, which is that layer's own evidence that it killed a child at its deadline. Recovery now asks the tool what state the simulator is in. `simulator.ts` owns the one boot-state read and takes the caller's ceiling, so the probe runs under a 5s screenshot-owned budget instead of the 60s inventory budget. Only the literal `Shutdown` authorizes a boot: `Booted`, `Booting`, `Creating` and `Shutting Down` describe a simulator that is already on its way, and a listing that failed, omits the simulator, or names no state proves nothing. A canceled request is terminal and never reaches the probe; a probe that is itself canceled travels on; every other probe failure answers `false` and leaves the capture's own error, details and hint, as the reported failure. The boot memo policy is unchanged, so a simulator turned off outside this process is still not seen until the memo expires. Refs #4442 --- .../screenshot-boot-state-recovery.test.ts | 341 +++++++++++++++++ .../screenshot-simctl-protocol.test.ts | 345 ++++++++++++++++++ .../__tests__/screenshot-simctl-retry.test.ts | 210 +++++++++++ .../screenshot-simulator-capture.test.ts | 12 +- .../screenshot-status-bar-concurrency.test.ts | 15 +- .../src/core/__tests__/screenshot.test.ts | 53 ++- .../__tests__/scripted-command-executor.ts | 71 ++++ packages/platform-apple/src/core/config.ts | 8 + .../platform-apple/src/core/screenshot.ts | 89 +++-- packages/platform-apple/src/core/simctl.ts | 3 + packages/platform-apple/src/core/simulator.ts | 22 +- .../platform-apple/src/core/tool-provider.ts | 69 +++- 12 files changed, 1193 insertions(+), 45 deletions(-) create mode 100644 packages/platform-apple/src/core/__tests__/screenshot-boot-state-recovery.test.ts create mode 100644 packages/platform-apple/src/core/__tests__/screenshot-simctl-protocol.test.ts create mode 100644 packages/platform-apple/src/core/__tests__/screenshot-simctl-retry.test.ts create mode 100644 packages/platform-apple/src/core/__tests__/scripted-command-executor.ts diff --git a/packages/platform-apple/src/core/__tests__/screenshot-boot-state-recovery.test.ts b/packages/platform-apple/src/core/__tests__/screenshot-boot-state-recovery.test.ts new file mode 100644 index 0000000000..2ba67cf387 --- /dev/null +++ b/packages/platform-apple/src/core/__tests__/screenshot-boot-state-recovery.test.ts @@ -0,0 +1,341 @@ +import { beforeEach, test, vi } from 'vitest'; +import assert from 'node:assert/strict'; +import { bindTestCommandHost } from '@agent-device/test-kit'; +import type { DeviceInfo } from '@agent-device/kernel/device'; +import { AppError, createRequestCanceledError } from '@agent-device/kernel/errors'; +import type { ExecResult } from '@agent-device/host-kit/command'; + +bindTestCommandHost(); + +// Only the boot owner's own work stands in for the boot: the recovery decision, the state probe, +// and the `simctl list devices -j` reader behind it all run for real, over scripted host commands. +vi.mock('../simulator.ts', async (importOriginal) => { + const actual = await importOriginal(); + return { ...actual, ensureBootedSimulator: vi.fn(actual.ensureBootedSimulator) }; +}); +vi.mock('../screenshot-status-bar.ts', async (importOriginal) => { + const actual = await importOriginal(); + return { + ...actual, + withSimulatorStatusBarHeld: vi.fn(async (_device, capture: () => unknown) => await capture()), + withNormalizedSimulatorStatusBar: vi.fn( + async (_device, capture: () => unknown) => await capture(), + ), + }; +}); + +import { ensureBootedSimulator } from '../simulator.ts'; +import { captureSimulatorScreenshotWithFallback } from '../screenshot.ts'; +import { SIMCTL_SCREENSHOT_TIMEOUT_REASON } from '../tool-provider.ts'; +import { + IOS_SIMCTL_LIST_TIMEOUT_MS, + IOS_SIMULATOR_SCREENSHOT_STATE_PROBE_TIMEOUT_MS, +} from '../config.ts'; +import { + commandFailed, + commandStdout, + isSimctlListDevices, + withScriptedCommands, + type ScriptedCommandCall, +} from './scripted-command-executor.ts'; + +/** + * The skipped-boot-check recovery: a failed simulator capture may boot its simulator only when the + * tool answers that the simulator is turned off right now. + * + * The trigger is the `state` field of `simctl list devices -j` — the same field the shutdown owner + * compares against the same literal — so the capture's own wording selects nothing. + */ + +/** The failure the capture step reports, exactly as the local simctl adapter reports a protocol + * timeout: its typed reason beside the tool's own header. The wording is never a boot authorization; + * the observed state is. */ +const CAPTURE_FAILURE = new AppError('COMMAND_FAILED', 'xcrun exited with code 60', { + stderr: + 'An error was encountered processing the command (domain=NSPOSIXErrorDomain, code=60):\n' + + 'Timeout waiting for screen surfaces', + exitCode: 60, + processExitError: true, + hint: 'Capture stderr excerpt preserved for the operator.', + reason: SIMCTL_SCREENSHOT_TIMEOUT_REASON, +}); + +function listingFor(udid: string, state: string): ExecResult { + return commandStdout( + JSON.stringify({ + devices: { 'com.apple.CoreSimulator.SimRuntime.iOS-18-6': [{ udid, state }] }, + }), + ); +} + +type RecoveryProbe = { + error: unknown; + stateReads: ScriptedCommandCall[]; + captureAttempts: number; + runnerCaptures: number; + boots: number; +}; + +/** + * Runs the capture route over the real flow with a failing capture step. The host commands, the + * probe and its JSON reader are the production ones; only the capture step and the boot owner's own + * booting work are held still. + */ +async function probeRecovery( + device: DeviceInfo, + options: { + state?: (call: ScriptedCommandCall) => ExecResult; + captureError?: unknown | ((attempt: number) => unknown); + signal?: AbortSignal; + skipIosSimulatorBootCheck?: boolean; + /** The fallback decision the flow makes after recovery; the production one is the timeout reason. */ + shouldFallbackToRunner?: (error: unknown) => boolean; + } = {}, +): Promise { + const boot = vi.mocked(ensureBootedSimulator); + boot.mockReset(); + boot.mockResolvedValue(undefined); + let captureAttempts = 0; + let runnerCaptures = 0; + const fallbackToRunner = options.shouldFallbackToRunner ?? (() => false); + + return await withScriptedCommands( + (call) => options.state?.(call) ?? commandStdout(''), + async (executor) => { + const error = await captureSimulatorScreenshotWithFallback(device, '/tmp/out.png', { + env: process.env, + skipIosSimulatorBootCheck: options.skipIosSimulatorBootCheck ?? true, + runnerOptions: options.signal ? { signal: options.signal } : undefined, + deps: { + captureWithRetry: async () => { + captureAttempts += 1; + const failure = options.captureError; + throw typeof failure === 'function' + ? (failure as (attempt: number) => unknown)(captureAttempts) + : (failure ?? CAPTURE_FAILURE); + }, + captureWithRunner: async () => { + runnerCaptures += 1; + return undefined; + }, + normalizeDensity: async () => {}, + resolveCaptureTarget: async () => ({}), + shouldFallbackToRunner: fallbackToRunner, + }, + }).then( + () => undefined, + (caught: unknown) => caught, + ); + return { + error, + stateReads: executor.calls().filter(isSimctlListDevices), + captureAttempts, + runnerCaptures, + boots: boot.mock.calls.length, + }; + }, + ); +} + +function simulator(id: string): DeviceInfo { + return { platform: 'apple', id, name: 'iPhone 17 Pro', kind: 'simulator' }; +} + +beforeEach(() => { + vi.mocked(ensureBootedSimulator).mockReset(); + vi.mocked(ensureBootedSimulator).mockResolvedValue(undefined); +}); + +test('a fresh Shutdown answer boots the skipped-check simulator once and re-captures once', async () => { + const device = simulator('sim-recover-shutdown'); + const probe = await probeRecovery(device, { state: () => listingFor(device.id, 'Shutdown') }); + + assert.equal(probe.boots, 1, 'one boot attempt authorized by the observed state'); + assert.equal(probe.captureAttempts, 2, 'one capture, then one re-capture after the boot'); + assert.equal(probe.stateReads.length, 1, 'one state observation per failed capture'); + assert.equal( + probe.runnerCaptures, + 0, + 'the recovery re-captures through the same simctl route, not the runner', + ); +}); + +test('the re-capture that fails again reports its own failure and adds no second recovery', async () => { + const device = simulator('sim-recover-recapture-fails'); + const recaptureFailure = new AppError('COMMAND_FAILED', 'xcrun exited with code 71', { + exitCode: 71, + }); + const probe = await probeRecovery(device, { + state: () => listingFor(device.id, 'Shutdown'), + captureError: (attempt) => (attempt === 1 ? CAPTURE_FAILURE : recaptureFailure), + }); + + assert.equal(probe.captureAttempts, 2); + assert.equal(probe.boots, 1, 'a failed re-capture does not boot again'); + assert.equal(probe.stateReads.length, 1, 'the recovery observes the state once'); + assert.equal(probe.error, recaptureFailure, 'the re-capture failure is what the caller sees'); +}); + +test.each(['Booted', 'Booting', 'Creating', 'Shutting Down', 'Living'] as const)( + 'a simulator listed as %s is not turned off, so nothing boots or re-captures', + async (state) => { + const device = simulator(`sim-recover-${state.toLowerCase().replace(/[^a-z]+/g, '-')}`); + const probe = await probeRecovery(device, { state: () => listingFor(device.id, state) }); + + assert.equal(probe.stateReads.length, 1, 'exactly one state observation'); + assert.equal(probe.boots, 0, 'no boot is authorized'); + assert.equal(probe.captureAttempts, 1, 'no re-capture starts'); + assert.equal(probe.error, CAPTURE_FAILURE, 'the capture keeps its failure, unchanged'); + }, +); + +test('an unreadable, unlisted or stateless listing cannot authorize a boot', async () => { + const unreadableAnswers: Array<[string, () => ExecResult]> = [ + [ + 'a listing that failed', + () => commandFailed('xcrun: error: unable to find utility "simctl"', 72), + ], + ['output that is not JSON', () => commandStdout('not json')], + ['a listing that omits the simulator', () => commandStdout('{"devices":{}}')], + [ + 'an entry that names no state', + () => + commandStdout( + '{"devices":{"com.apple.CoreSimulator.SimRuntime.iOS-18-6":[{"udid":"sim-unreadable"}]}}', + ), + ], + ]; + + for (const [label, answer] of unreadableAnswers) { + const device = simulator(`sim-unreadable-${label.length}`); + const probe = await probeRecovery(device, { state: answer }); + + assert.equal(probe.boots, 0, `${label}: no boot from an answer that names no shutdown`); + assert.equal(probe.captureAttempts, 1, `${label}: no re-capture may start`); + assert.equal(probe.error, CAPTURE_FAILURE, `${label}: the original failure stands`); + assert.equal(probe.runnerCaptures, 0, `${label}: no fallback is added`); + } +}); + +test('a state read that itself fails keeps the capture failure and its diagnostics', async () => { + const device = simulator('sim-recover-probe-throws'); + const probe = await probeRecovery(device, { + state: () => { + throw new Error('simctl list devices -j could not be spawned'); + }, + }); + + assert.equal(probe.error, CAPTURE_FAILURE, 'a failed probe never replaces the capture failure'); + assert.equal(probe.boots, 0); + assert.equal(probe.captureAttempts, 1); + const details = (CAPTURE_FAILURE.details ?? {}) as Record; + assert.equal(details.exitCode, 60); + assert.equal(details.processExitError, true); + assert.equal(typeof details.hint, 'string', 'the hint the producer attached is preserved'); +}); + +test('the recovery probe is bounded by the screenshot ceiling, not the inventory budget', async () => { + const device = simulator('sim-recover-budget'); + const probe = await probeRecovery(device, { state: () => listingFor(device.id, 'Shutdown') }); + + const [onlyProbe] = probe.stateReads; + assert.ok(onlyProbe, 'the recovery reads the boot state once'); + assert.equal( + onlyProbe.options.timeoutMs, + IOS_SIMULATOR_SCREENSHOT_STATE_PROBE_TIMEOUT_MS, + 'the probe runs under the screenshot-owned ceiling', + ); + assert.ok( + IOS_SIMULATOR_SCREENSHOT_STATE_PROBE_TIMEOUT_MS < IOS_SIMCTL_LIST_TIMEOUT_MS, + 'the probe must not inherit the 60s inventory budget behind a 20s capture', + ); +}); + +test('an already canceled request never reaches the probe', async () => { + const device = simulator('sim-recover-canceled'); + // The cancellation a request carries is the typed one the capture route raises it with. + const cancellation = createRequestCanceledError({ cmd: 'xcrun' }); + const abortController = new AbortController(); + abortController.abort(cancellation); + + const probe = await probeRecovery(device, { + signal: abortController.signal, + state: () => listingFor(device.id, 'Shutdown'), + }); + + assert.equal(probe.stateReads.length, 0, 'a canceled request must not query the device'); + assert.equal(probe.boots, 0); + assert.equal(probe.captureAttempts, 1); + assert.equal(probe.runnerCaptures, 0); + assert.equal(probe.error, cancellation, 'the cancellation stays the reported failure'); +}); + +test('a cancellation that arrives with the capture failure is not treated as an unknown state', async () => { + const device = simulator('sim-recover-canceled-error'); + const cancellation = createRequestCanceledError({ cmd: 'xcrun' }); + const probe = await probeRecovery(device, { + captureError: cancellation, + // Even a Shutdown answer may not turn a canceled request into a boot. + state: () => listingFor(device.id, 'Shutdown'), + }); + + assert.equal(probe.error, cancellation, 'the typed cancellation is what the caller sees'); + assert.equal(probe.stateReads.length, 0, 'a cancellation never reaches the probe'); + assert.equal(probe.boots, 0); + assert.equal(probe.captureAttempts, 1); +}); + +test('a cancellation raised by the probe travels on instead of answering no', async () => { + const device = simulator('sim-recover-probe-canceled'); + const cancellation = createRequestCanceledError({ cmd: 'xcrun' }); + const probe = await probeRecovery(device, { + captureError: CAPTURE_FAILURE, + state: () => { + throw cancellation; + }, + }); + + assert.equal(probe.error, cancellation, 'the probe must not swallow a cancellation'); + assert.equal(probe.boots, 0); + assert.equal(probe.captureAttempts, 1); +}); + +test('a capture that did not skip the boot check never probes the state', async () => { + const device = simulator('sim-recover-no-skip'); + const probe = await probeRecovery(device, { + skipIosSimulatorBootCheck: false, + state: () => listingFor(device.id, 'Shutdown'), + }); + + assert.equal(probe.stateReads.length, 0); + assert.equal(probe.captureAttempts, 1); +}); + +test('a mask-bearing capture that observed a shutdown still refuses the runner fallback', async () => { + const device = simulator('sim-recover-mask'); + const probe = await withScriptedCommands( + () => listingFor(device.id, 'Shutdown'), + async (executor) => { + const error = await captureSimulatorScreenshotWithFallback(device, '/tmp/out.png', { + env: process.env, + screenMask: 'black', + skipIosSimulatorBootCheck: true, + deps: { + captureWithRetry: async () => { + throw CAPTURE_FAILURE; + }, + normalizeDensity: async () => {}, + resolveCaptureTarget: async () => ({}), + captureWithRunner: async () => undefined, + }, + }).then( + () => undefined, + (caught: unknown) => caught, + ); + return { error, stateReads: executor.calls().filter(isSimctlListDevices) }; + }, + ); + + assert.equal(probe.stateReads.length, 1, 'the observed shutdown is still asked about'); + assert.equal(probe.error, CAPTURE_FAILURE, 'a masked capture is never handed to the runner'); +}); diff --git a/packages/platform-apple/src/core/__tests__/screenshot-simctl-protocol.test.ts b/packages/platform-apple/src/core/__tests__/screenshot-simctl-protocol.test.ts new file mode 100644 index 0000000000..11223b2693 --- /dev/null +++ b/packages/platform-apple/src/core/__tests__/screenshot-simctl-protocol.test.ts @@ -0,0 +1,345 @@ +import { test } from 'vitest'; +import assert from 'node:assert/strict'; +import { bindTestCommandHost } from '@agent-device/test-kit'; +import { AppError } from '@agent-device/kernel/errors'; +import type { DeviceInfo } from '@agent-device/kernel/device'; +import type { ExecResult } from '@agent-device/host-kit/command'; + +bindTestCommandHost(); + +import { + createLocalAppleToolProvider, + runXcrun, + withAppleToolProvider, + SIMCTL_SCREENSHOT_TIMEOUT_REASON, +} from '../tool-provider.ts'; +import { buildSimctlArgsForDevice } from '../simctl.ts'; +import { shouldRetryIosSimulatorScreenshot } from '../screenshot.ts'; +import { + commandFailed, + commandStdout, + withScriptedCommands, + type ScriptedCommandCall, +} from './scripted-command-executor.ts'; + +/** + * The simctl screenshot protocol, read where it is produced. + * + * These run the production local Apple tool provider over the seam `runCmd` consults before it + * spawns, so the adapter, its parse, and exec's own failure construction are the code under test. + * The fake Apple tool provider supplies its own `simctl.run` and `runCommand`, which routes around + * this adapter, so it cannot prove any of it. + */ + +const SIMULATOR: DeviceInfo = { + platform: 'apple', + id: 'sim-1', + name: 'iPhone 17 Pro', + kind: 'simulator', +}; + +/** The screenshot command this flow builds, as `xcrun simctl` receives it after the tool name. */ +const SCREENSHOT_ARGS = ['io', 'sim-1', 'screenshot', '/tmp/out.png']; + +/** simctl's own top-level header, plus the CoreSimulator sentence it renders under it. */ +function protocolTimeout(stderr = ''): string { + return [ + 'An error was encountered processing the command (domain=NSPOSIXErrorDomain, code=60):', + "The operation couldn't be completed.", + stderr || 'Timeout waiting for screen surfaces', + ].join('\n'); +} + +function runScreenshot(options: { allowFailure?: boolean } = {}): Promise { + return runXcrun(buildSimctlArgsForDevice(SIMULATOR, SCREENSHOT_ARGS), { + timeoutMs: 20_000, + ...(options.allowFailure === undefined ? {} : { allowFailure: options.allowFailure }), + }); +} + +/** Runs the screenshot call through the production local provider over scripted host commands. */ +async function captureScreenshot( + answer: (call: ScriptedCommandCall) => ExecResult, +): Promise<{ result?: ExecResult; error?: unknown; calls: ScriptedCommandCall[] }> { + return await withAppleToolProvider( + createLocalAppleToolProvider(), + async () => + await withScriptedCommands(answer, async (executor) => { + try { + return { result: await runScreenshot(), calls: executor.calls() }; + } catch (error) { + return { error, calls: executor.calls() }; + } + }), + ); +} + +function failedCommandError(error: unknown): AppError { + assert.ok(error instanceof AppError, `expected an AppError, received: ${String(error)}`); + return error; +} + +function details(error: unknown): Record { + return (failedCommandError(error).details ?? {}) as Record; +} + +test('the local adapter stamps the screenshot protocol timeout as a typed reason', async () => { + const { result, error, calls } = await captureScreenshot(() => + commandFailed(protocolTimeout(), 60, 'Detected file type from extension: PNG\n'), + ); + + assert.equal(result, undefined); + const appError = failedCommandError(error); + assert.equal(appError.code, 'COMMAND_FAILED'); + assert.equal(details(error).reason, SIMCTL_SCREENSHOT_TIMEOUT_REASON); + assert.equal(shouldRetryIosSimulatorScreenshot(error), true); + + assert.equal(calls.length, 1); + assert.equal(calls[0]?.cmd, 'xcrun'); + assert.deepEqual(calls[0]?.args, ['simctl', ...SCREENSHOT_ARGS]); +}); + +test('the typed reason survives a changed human message and an unrelated exit code', async () => { + // The header is the protocol; everything after it is prose the tool rewords between builds. + const { error } = await captureScreenshot(() => + commandFailed( + [ + 'An error was encountered processing the command (domain=NSPOSIXErrorDomain, code=60):', + 'Rendering the display did not finish in time.', + ].join('\n'), + 149, + ), + ); + + assert.equal(details(error).reason, SIMCTL_SCREENSHOT_TIMEOUT_REASON); + assert.equal(shouldRetryIosSimulatorScreenshot(error), true); +}); + +test('the adapter keeps every exec failure detail beside the reason it stamped', async () => { + const { error } = await captureScreenshot(() => + commandFailed(protocolTimeout(), 60, 'Detected file type from extension: PNG\n'), + ); + + const commandDetails = details(error); + assert.equal(commandDetails.exitCode, 60); + assert.equal(commandDetails.processExitError, true); + assert.equal(commandDetails.cmd, 'xcrun'); + assert.deepEqual(commandDetails.args, ['simctl', ...SCREENSHOT_ARGS]); + assert.equal( + commandDetails.stderr, + 'An error was encountered processing the command (domain=NSPOSIXErrorDomain, code=60):\n' + + "The operation couldn't be completed.\nTimeout waiting for screen surfaces", + ); + assert.equal(commandDetails.stdout, 'Detected file type from extension: PNG\n'); +}); + +test('the adapter reads the protocol header for a set-scoped screenshot call', async () => { + const scopedDevice: DeviceInfo = { ...SIMULATOR, simulatorSetPath: '/tmp/tenant/set' }; + const { error } = await withAppleToolProvider( + createLocalAppleToolProvider(), + async () => + await withScriptedCommands( + () => commandFailed(protocolTimeout(), 60), + async () => { + try { + return await runXcrun(buildSimctlArgsForDevice(scopedDevice, SCREENSHOT_ARGS), { + timeoutMs: 20_000, + }); + } catch (caught) { + return { error: caught }; + } + }, + ), + ); + + assert.equal(details(error).reason, SIMCTL_SCREENSHOT_TIMEOUT_REASON); +}); + +test('the same screenshot text without the protocol header stays unattributed', async () => { + // Identical message, stdout, stderr and argv as the positive above, minus the header line: this + // is the case the text classifier used to accept, and the one that must stay terminal. + const { error } = await captureScreenshot(() => + commandFailed( + 'Detected file type from extension: PNG\nTimeout waiting for screen surfaces\n', + 60, + ), + ); + + const appError = failedCommandError(error); + assert.equal(appError.code, 'COMMAND_FAILED'); + assert.equal(appError.message, 'xcrun exited with code 60'); + assert.equal(details(error).reason, undefined); + assert.equal(shouldRetryIosSimulatorScreenshot(error), false); +}); + +test('the adapter ignores a header whose domain or code is not the screenshot timeout', async () => { + const unrelatedHeaders = [ + // EINVAL, the refusal a screenshot request gets from a display argument it cannot honour. + 'An error was encountered processing the command (domain=NSPOSIXErrorDomain, code=22):', + // ESRCH, printed by the same protocol on another path. + 'An error was encountered processing the command (domain=NSPOSIXErrorDomain, code=3):', + // A CoreSimulator state answer: a different domain, and no screenshot contract at all. + 'An error was encountered processing the command (domain=com.apple.CoreSimulator.SimError, code=405):', + // The POSIX domain with a code that is not 60, and a code that merely starts with 60. + 'An error was encountered processing the command (domain=NSPOSIXErrorDomain, code=600):', + 'An error was encountered processing the command (domain=NSPOSIXErrorDomain, code=-60):', + // Malformed protocol: the header states no number. + 'An error was encountered processing the command (domain=NSPOSIXErrorDomain, code=):', + 'An error was encountered processing the command (domain=NSPOSIXErrorDomain, code=ETIMEDOUT):', + ]; + + for (const stderr of unrelatedHeaders) { + const { error } = await captureScreenshot(() => + commandFailed(`${stderr}\nThe operation couldn't be completed.`, 149), + ); + + assert.equal( + details(error).reason, + undefined, + `must not attribute a screenshot timeout: ${stderr}`, + ); + assert.equal(shouldRetryIosSimulatorScreenshot(error), false, `must stay terminal: ${stderr}`); + } +}); + +test('the adapter ignores a header that simctl did not print at the top level', async () => { + const nestedOnly = [ + 'An error was encountered processing the command (domain=com.apple.CoreSimulator.SimError, code=405):', + 'Unable to lookup in current state: Shutdown', + ' Underlying error (domain=NSPOSIXErrorDomain, code=60):', + 'Timeout waiting for screen surfaces', + ].join('\n'); + + const stdoutOnly = `${protocolTimeout()}\n`; + const cases: Array<[string, () => ExecResult]> = [ + ['nested underlying-error header only', () => commandFailed(nestedOnly, 149)], + ['header printed on stdout instead of stderr', () => commandFailed('', 60, stdoutOnly)], + ]; + + for (const [label, answer] of cases) { + const { error } = await captureScreenshot(answer); + + assert.equal(details(error).reason, undefined, label); + assert.equal(shouldRetryIosSimulatorScreenshot(error), false, label); + } +}); + +test('the adapter attributes nothing for a screenshot call that succeeded', async () => { + const { result, error } = await captureScreenshot(() => commandStdout('')); + + assert.equal(error, undefined); + assert.equal(result?.exitCode, 0); +}); + +test('the adapter leaves a caller-supplied command executor unclassified', async () => { + // A host that supplies its own `runCommand` owns its errors: the local parse does not run over a + // callback it does not control, so its protocol-looking failure stays unknown. + const supplied = async (): Promise => { + throw new AppError('COMMAND_FAILED', 'remote screenshot failed', { + stderr: protocolTimeout(), + exitCode: 60, + args: ['xcrun', 'simctl', ...SCREENSHOT_ARGS], + }); + }; + + const error = await withAppleToolProvider( + createLocalAppleToolProvider({ runCommand: supplied }), + async () => + await withScriptedCommands( + () => commandStdout(''), + async () => + await runScreenshot().then( + () => null, + (caught: unknown) => caught, + ), + ), + ); + + assert.ok(error instanceof AppError); + assert.equal(error.message, 'remote screenshot failed'); + assert.equal(details(error).reason, undefined); + assert.equal(shouldRetryIosSimulatorScreenshot(error), false); +}); + +test('the adapter leaves a caller-supplied simctl runner unclassified', async () => { + // A host that supplies `simctl.run` owns its own failure reporting: the local parse never sees what + // that callback answers, so a protocol-shaped failure crosses over untouched and names no reason. + const suppliedFailure = new AppError('COMMAND_FAILED', 'simctl screenshot failed', { + exitCode: 60, + stderr: protocolTimeout(), + }); + const error = await withAppleToolProvider( + createLocalAppleToolProvider({ + simctl: { + run: async () => { + throw suppliedFailure; + }, + }, + }), + async () => + await withScriptedCommands( + () => commandStdout(''), + async () => + await runScreenshot().then( + () => null, + (caught: unknown) => caught, + ), + ), + ); + + assert.equal(error, suppliedFailure, "the supplied callback's own error is what surfaces"); + assert.equal(details(error).reason, undefined); + assert.equal(shouldRetryIosSimulatorScreenshot(error), false); +}); + +test('the adapter does not parse a simctl subcommand it did not scope as a screenshot', async () => { + const otherSubcommands = [ + ['status_bar', ['status_bar', 'sim-1', 'list']], + ['getenv', ['getenv', 'sim-1', 'SIMULATOR_MAINSCREEN_SCALE']], + ['boot', ['boot', 'sim-1']], + ] as const; + + for (const [label, args] of otherSubcommands) { + const { error } = await withAppleToolProvider( + createLocalAppleToolProvider(), + async () => + await withScriptedCommands( + () => commandFailed(protocolTimeout(), 60), + async () => + await runXcrun(buildSimctlArgsForDevice(SIMULATOR, [...args]), { + timeoutMs: 20_000, + }).then( + (result) => ({ result }), + (caught: unknown) => ({ error: caught }), + ), + ), + ); + + assert.equal( + details(error).reason, + undefined, + `a ${label} failure is not a screenshot timeout`, + ); + } +}); + +test('the adapter leaves an allowFailure screenshot call untouched', async () => { + // A caller that asked to read the failure itself gets the tool's raw result, not an error. + const { result, error } = await withAppleToolProvider( + createLocalAppleToolProvider(), + async () => + await withScriptedCommands( + () => commandFailed(protocolTimeout(), 60), + async (executor) => { + try { + return { result: await runScreenshot({ allowFailure: true }), calls: executor.calls() }; + } catch (caught) { + return { error: caught }; + } + }, + ), + ); + + assert.equal(error, undefined); + assert.equal(result?.exitCode, 60); +}); diff --git a/packages/platform-apple/src/core/__tests__/screenshot-simctl-retry.test.ts b/packages/platform-apple/src/core/__tests__/screenshot-simctl-retry.test.ts new file mode 100644 index 0000000000..265aea2f5e --- /dev/null +++ b/packages/platform-apple/src/core/__tests__/screenshot-simctl-retry.test.ts @@ -0,0 +1,210 @@ +import { test, vi } from 'vitest'; +import assert from 'node:assert/strict'; +import { writeFileSync } from 'node:fs'; +import path from 'node:path'; +import { bindTestCommandHost } from '@agent-device/test-kit'; +import type { DeviceInfo } from '@agent-device/kernel/device'; +import type { ExecResult } from '@agent-device/host-kit/command'; + +bindTestCommandHost(); + +// The retry loop runs for real; only its wait is removed, so no test sleeps through the +// production backoff. The policy, its predicate, and every command it issues stay the real ones. +vi.mock('@agent-device/host-kit/retry', async (importOriginal) => { + const actual = await importOriginal(); + return { ...actual, retryWithPolicy: vi.fn(actual.retryWithPolicy) }; +}); + +import { retryWithPolicy } from '@agent-device/host-kit/retry'; +import { + createLocalAppleToolProvider, + withAppleToolProvider, + SIMCTL_SCREENSHOT_TIMEOUT_REASON, +} from '../tool-provider.ts'; +import { captureSimulatorScreenshotWithRetry } from '../screenshot.ts'; +import { IOS_SIMULATOR_SCREENSHOT_STATE_PROBE_TIMEOUT_MS } from '../config.ts'; +import { mkdtempForTest } from '../../__tests__/tmp-dir.ts'; +import { + commandFailed, + commandStdout, + isSimctlListDevices, + isSimctlScreenshot, + withScriptedCommands, + type ScriptedCommandCall, +} from './scripted-command-executor.ts'; + +/** + * The simulator screenshot retry loop, driven through the production local Apple tool provider. + * + * No `simctl` callback is supplied anywhere here, so every capture reaches the real local adapter + * and the protocol parse that decides a retry is the one that ships. + */ + +const SIMULATOR: DeviceInfo = { + platform: 'apple', + id: 'sim-retry', + name: 'iPhone 17 Pro', + kind: 'simulator', +}; + +/** simctl's top-level error protocol, rendered for a screenshot call whose surfaces never answered. */ +const PROTOCOL_TIMEOUT = + 'An error was encountered processing the command (domain=NSPOSIXErrorDomain, code=60):\n' + + "The operation couldn't be completed.\n" + + 'Timeout waiting for screen surfaces'; + +/** The wording a render-server stall printed, with no protocol header in front of it. */ +const HEADERLESS_TIMEOUT = + 'Detected file type from extension: PNG\nTimeout waiting for screen surfaces\n'; + +const TINY_PNG = Buffer.from( + 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==', + 'base64', +); + +/** Runs one attempt per round without waiting, keeping the real policy and predicate. */ +function withoutBackoff(): void { + vi.mocked(retryWithPolicy).mockImplementation( + async (fn: Parameters[0], policy, options) => { + const maxAttempts = policy?.maxAttempts; + assert.ok( + typeof maxAttempts === 'number', + 'the capture retry must declare the budget this loop is bounded by', + ); + let lastError: unknown; + for (let attempt = 1; attempt <= maxAttempts; attempt += 1) { + try { + return await fn({ attempt, maxAttempts, deadline: options?.deadline }); + } catch (error) { + lastError = error; + if (!policy?.shouldRetry?.(error, attempt)) throw error; + } + } + throw lastError; + }, + ); +} + +/** Answers the scripted commands, failing this simulator's screenshot calls as `refuse` dictates. */ +function screenshotRefusals(refuse: (attempt: number) => ExecResult | undefined, outPath: string) { + let attempts = 0; + return (call: ScriptedCommandCall): ExecResult => { + if (!isSimctlScreenshot(call)) return commandStdout(''); + attempts += 1; + const refusal = refuse(attempts); + if (refusal) return refusal; + // A capture that gets through writes the image file, the way the tool does. + writeFileSync(outPath, TINY_PNG); + return commandStdout(''); + }; +} + +async function captureThroughLocalAdapter( + script: (call: ScriptedCommandCall) => ExecResult, + outPath: string, +): Promise<{ error: unknown; calls: ScriptedCommandCall[]; attempts: number }> { + return await withAppleToolProvider( + createLocalAppleToolProvider(), + async () => + await withScriptedCommands(script, async (executor) => { + const error = await captureSimulatorScreenshotWithRetry(SIMULATOR, outPath, undefined).then( + () => undefined, + (caught: unknown) => caught, + ); + const calls = executor.calls(); + return { + error, + calls, + attempts: calls.filter(isSimctlScreenshot).length, + }; + }), + ); +} + +test.beforeEach(() => { + vi.mocked(retryWithPolicy).mockRestore(); + withoutBackoff(); +}); + +test('a protocol timeout the local adapter stamped is retried until the capture succeeds', async () => { + const tmpDir = await mkdtempForTest('agent-device-screenshot-protocol-retry-'); + const outPath = path.join(tmpDir, 'screen.png'); + + const { error, calls, attempts } = await captureThroughLocalAdapter( + screenshotRefusals( + (attempt) => + attempt === 1 ? commandFailed(PROTOCOL_TIMEOUT, 60, HEADERLESS_TIMEOUT) : undefined, + outPath, + ), + outPath, + ); + + assert.equal(error, undefined); + assert.equal(attempts, 2, 'the typed timeout is retried, and the second attempt wins'); + assert.equal( + calls.filter(isSimctlScreenshot).every((call) => call.options.timeoutMs !== undefined), + true, + 'every attempt carries its own exec budget', + ); + // A capture budget is decided by the capture: the retry loop never reads the boot state. + assert.equal(calls.filter(isSimctlListDevices).length, 0); +}); + +test('the retry loop stops at its declared attempt ceiling and reports the typed timeout', async () => { + const tmpDir = await mkdtempForTest('agent-device-screenshot-protocol-exhaust-'); + const outPath = path.join(tmpDir, 'screen.png'); + + const { error, attempts } = await captureThroughLocalAdapter( + screenshotRefusals(() => commandFailed(PROTOCOL_TIMEOUT, 60), outPath), + outPath, + ); + + assert.ok(error && error instanceof Error); + const details = (error as { details?: Record }).details; + assert.equal(details?.reason, SIMCTL_SCREENSHOT_TIMEOUT_REASON); + assert.equal(attempts, 5, 'the retry budget is the declared five attempts, no more'); +}); + +test('identical timeout wording without the protocol header is terminal on the first attempt', async () => { + const tmpDir = await mkdtempForTest('agent-device-screenshot-unattributed-'); + const outPath = path.join(tmpDir, 'screen.png'); + + const { error, attempts } = await captureThroughLocalAdapter( + screenshotRefusals(() => commandFailed(HEADERLESS_TIMEOUT, 60), outPath), + outPath, + ); + + assert.ok(error instanceof Error); + assert.match(error.message, /exited with code 60/); + assert.equal(attempts, 1, 'wording the adapter did not attribute must not retry'); + assert.equal((error as { details?: Record }).details?.reason, undefined); +}); + +test('an unrelated protocol code stays terminal and keeps the tool failure as reported', async () => { + const tmpDir = await mkdtempForTest('agent-device-screenshot-einval-'); + const outPath = path.join(tmpDir, 'screen.png'); + + const { error, attempts } = await captureThroughLocalAdapter( + screenshotRefusals( + () => + commandFailed( + 'An error was encountered processing the command (domain=NSPOSIXErrorDomain, code=22):\n' + + 'The operation couldn’t be completed. Invalid argument', + 149, + ), + outPath, + ), + outPath, + ); + + assert.ok(error instanceof Error); + assert.equal(attempts, 1); + assert.equal((error as { details?: Record }).details?.reason, undefined); +}); + +test('the boot-state probe ceiling stays below the capture budget it explains', () => { + // The probe is a best-effort read on the failure path, so it must be bounded under the operation + // it follows; the inventory read's own 60s budget would invert that. + assert.equal(IOS_SIMULATOR_SCREENSHOT_STATE_PROBE_TIMEOUT_MS, 5_000); + assert.ok(IOS_SIMULATOR_SCREENSHOT_STATE_PROBE_TIMEOUT_MS < 20_000); +}); diff --git a/packages/platform-apple/src/core/__tests__/screenshot-simulator-capture.test.ts b/packages/platform-apple/src/core/__tests__/screenshot-simulator-capture.test.ts index f6cafa44e3..9085ba7cd9 100644 --- a/packages/platform-apple/src/core/__tests__/screenshot-simulator-capture.test.ts +++ b/packages/platform-apple/src/core/__tests__/screenshot-simulator-capture.test.ts @@ -18,6 +18,8 @@ import { retryWithPolicy } from '@agent-device/host-kit/retry'; import { PNG } from '@agent-device/capture-kit/png'; import { withFakeAppleTool, type FakeAppleToolResponse } from '../../__tests__/fake-apple-tool.ts'; import { IOS_TEST_SIMULATOR } from './apple-core-stub-helpers.ts'; +import { SIMCTL_SCREENSHOT_TIMEOUT_REASON } from '../tool-provider.ts'; +import { AppError } from '@agent-device/kernel/errors'; const mockRetryWithPolicy = vi.mocked(retryWithPolicy); @@ -95,10 +97,14 @@ test('screenshotIos retries simulator capture timeouts and eventually succeeds', if (isSimctlScreenshot(args)) { screenshotAttempts += 1; if (screenshotAttempts < 3) { - return { - stderr: 'Detected file type from extension: PNG\nTimeout waiting for screen surfaces\n', + // The shape the local simctl adapter hands back for a protocol timeout: the reason it read + // off the tool's own error line, and the tool's wording beside it. The wording is not what + // makes this retryable, and the pair is what a real attempt looks like at this seam. + return new AppError('COMMAND_FAILED', 'xcrun simctl exited with code 60', { exitCode: 60, - }; + stderr: 'Detected file type from extension: PNG\nTimeout waiting for screen surfaces\n', + reason: SIMCTL_SCREENSHOT_TIMEOUT_REASON, + }); } writeFileSync(args.at(-1) ?? '', sourcePng); return ''; diff --git a/packages/platform-apple/src/core/__tests__/screenshot-status-bar-concurrency.test.ts b/packages/platform-apple/src/core/__tests__/screenshot-status-bar-concurrency.test.ts index f165873c1e..dea3c09050 100644 --- a/packages/platform-apple/src/core/__tests__/screenshot-status-bar-concurrency.test.ts +++ b/packages/platform-apple/src/core/__tests__/screenshot-status-bar-concurrency.test.ts @@ -3,7 +3,11 @@ import assert from 'node:assert/strict'; import type { DeviceInfo } from '@agent-device/kernel/device'; import { AppError } from '@agent-device/kernel/errors'; import { withFakeAppleTool } from '../../__tests__/fake-apple-tool.ts'; -import { createLocalAppleToolProvider, withAppleToolProvider } from '../tool-provider.ts'; +import { + createLocalAppleToolProvider, + withAppleToolProvider, + SIMCTL_SCREENSHOT_TIMEOUT_REASON, +} from '../tool-provider.ts'; // `setIosSetting` boots through this owner; the capture route under test skips it, so the settings // case below needs it quiet without touching the status bar owner. @@ -84,13 +88,20 @@ function captureDeps(captureWithRetry: (device: DeviceInfo) => Promise) { normalizeDensity: async () => {}, captureWithRunner: async () => undefined, shouldFallbackToRunner: () => false, + // The capture under these cases either succeeds or fails as a transport failure; none of them is + // about the recovery, and a probe would query the fake status bar tool about a boot state it + // does not model. + observesSimulatorShutdown: async () => false, }; } +/** A capture failure carrying the reason the local simctl adapter stamps for its protocol timeout: + * what the real capture would have thrown here. These cases only assert the status bar it leaves + * behind, so the failure stays a transport failure and never a shape a text rule could select. */ function screenshotFailure(): AppError { return new AppError('COMMAND_FAILED', 'simctl screenshot failed', { - stderr: 'Unable to capture screenshot', exitCode: 60, + reason: SIMCTL_SCREENSHOT_TIMEOUT_REASON, }); } diff --git a/packages/platform-apple/src/core/__tests__/screenshot.test.ts b/packages/platform-apple/src/core/__tests__/screenshot.test.ts index 9f33fd2698..fece4becaf 100644 --- a/packages/platform-apple/src/core/__tests__/screenshot.test.ts +++ b/packages/platform-apple/src/core/__tests__/screenshot.test.ts @@ -64,7 +64,11 @@ import { runCmd } from '@agent-device/host-kit/command'; import { withDiagnosticsScope } from '@agent-device/host-kit/diagnostics'; import { retryWithPolicy } from '@agent-device/host-kit/retry'; import { AppError } from '@agent-device/kernel/errors'; -import { resolveAppleToolProvider, withAppleToolProvider } from '../tool-provider.ts'; +import { + resolveAppleToolProvider, + withAppleToolProvider, + SIMCTL_SCREENSHOT_TIMEOUT_REASON, +} from '../tool-provider.ts'; import { IOS_TEST_SIMULATOR, MACOS_TEST_DEVICE } from './apple-core-stub-helpers.ts'; @@ -109,15 +113,18 @@ async function waitForFileText(filePath: string, attempts = 20): Promise throw lastError; } -test('shouldRetryIosSimulatorScreenshot detects simulator screen-surface timeout', () => { - const error = new AppError('COMMAND_FAILED', 'Detected file type from extension: PNG', { +test('shouldRetryIosSimulatorScreenshot retries the timeout reason the adapter stamps', () => { + // The reason the local simctl adapter stamps from the tool's protocol header; see + // screenshot-simctl-protocol.test.ts for the producer that mints it. + const error = new AppError('COMMAND_FAILED', 'xcrun exited with code 60', { stderr: 'Timeout waiting for screen surfaces', exitCode: 60, + reason: SIMCTL_SCREENSHOT_TIMEOUT_REASON, }); assert.equal(shouldRetryIosSimulatorScreenshot(error), true); }); -test('shouldRetryIosSimulatorScreenshot detects timed out simctl screenshot command', () => { +test('shouldRetryIosSimulatorScreenshot retries a command host-kit killed at its deadline', () => { const error = new AppError('COMMAND_FAILED', 'xcrun timed out after 20000ms', { args: ['simctl', 'io', 'sim-1', 'screenshot', '/tmp/out.png'], timeoutMs: 20_000, @@ -133,6 +140,22 @@ test('shouldRetryIosSimulatorScreenshot ignores unrelated screenshot failures', assert.equal(shouldRetryIosSimulatorScreenshot(error), false); }); +test('the same screenshot timeout wording without the typed reason is not retryable', () => { + // Identical wording and argv to the two positives above, minus the typed evidence: the retry + // decision must not be reachable from the tool's prose or from this module's own argv. + const worded = new AppError('COMMAND_FAILED', 'Detected file type from extension: PNG', { + stderr: 'Timeout waiting for screen surfaces', + exitCode: 60, + }); + const wordedAndSpelled = new AppError('COMMAND_FAILED', 'xcrun timed out after 20000ms', { + args: ['simctl', 'io', 'sim-1', 'screenshot', '/tmp/out.png'], + stderr: 'Timeout waiting for screen surfaces', + exitCode: 60, + }); + assert.equal(shouldRetryIosSimulatorScreenshot(worded), false); + assert.equal(shouldRetryIosSimulatorScreenshot(wordedAndSpelled), false); +}); + test('captureSimulatorScreenshotWithFallback falls back to runner after retry exhaustion', async () => { const tmpDir = await mkdtempForTest('agent-device-ios-runner-fallback-'); let ensureBootedCalls = 0; @@ -145,9 +168,10 @@ test('captureSimulatorScreenshotWithFallback falls back to runner after retry ex }); mockOpenIosSimulatorApp.mockResolvedValue(undefined); mockRetryWithPolicy.mockRejectedValue( - new AppError('COMMAND_FAILED', 'Detected file type from extension: PNG', { + new AppError('COMMAND_FAILED', 'xcrun exited with code 60', { stderr: 'Timeout waiting for screen surfaces', exitCode: 60, + reason: SIMCTL_SCREENSHOT_TIMEOUT_REASON, }), ); mockRunAppleRunnerCommand.mockResolvedValue({ message: 'tmp/fallback.png' }); @@ -269,14 +293,17 @@ test('captureSimulatorScreenshotWithFallback can skip session-backed simulator b assert.equal(mockRunAppleRunnerCommand.mock.calls.length, 0); }); -test('captureSimulatorScreenshotWithFallback boots skipped-check simulator after shutdown screenshot failure', async () => { +test('captureSimulatorScreenshotWithFallback boots skipped-check simulator after an observed shutdown', async () => { + // The boot authorization is the observed state, not the capture's wording; see + // screenshot-boot-state-recovery.test.ts for the state seam itself. This case pins the flow: + // one boot, one re-capture, no runner leg. const ensureBooted = vi.fn(async () => {}); let captureAttempts = 0; const captureWithRetry = vi.fn(async () => { captureAttempts += 1; if (captureAttempts === 1) { throw new AppError('COMMAND_FAILED', 'simctl screenshot failed', { - stderr: 'Unable to boot device in current state: Shutdown', + stderr: 'Unable to capture screenshot', args: ['simctl', 'io', 'sim-1', 'screenshot', '/tmp/out.png'], }); } @@ -291,6 +318,7 @@ test('captureSimulatorScreenshotWithFallback boots skipped-check simulator after deps: { ensureBooted, captureWithRetry, + observesSimulatorShutdown: async () => true, normalizeDensity: async () => {}, captureWithRunner, shouldFallbackToRunner: shouldRetryIosSimulatorScreenshot, @@ -310,7 +338,7 @@ test('captureSimulatorScreenshotWithFallback keeps runner fallback after skipped captureAttempts += 1; if (captureAttempts === 1) { throw new AppError('COMMAND_FAILED', 'simctl screenshot failed', { - stderr: 'Unable to boot device in current state: Shutdown', + stderr: 'Unable to capture screenshot', args: ['simctl', 'io', 'sim-1', 'screenshot', '/tmp/out.png'], }); } @@ -329,6 +357,7 @@ test('captureSimulatorScreenshotWithFallback keeps runner fallback after skipped deps: { ensureBooted, captureWithRetry, + observesSimulatorShutdown: async () => true, normalizeDensity: async () => {}, captureWithRunner, shouldFallbackToRunner: shouldRetryIosSimulatorScreenshot, @@ -635,6 +664,7 @@ test('captureSimulatorScreenshotWithFallback keeps the real runner fallback insi new AppError('COMMAND_FAILED', 'Detected file type from extension: PNG', { stderr: 'Timeout waiting for screen surfaces', exitCode: 60, + reason: SIMCTL_SCREENSHOT_TIMEOUT_REASON, }), ); mockRunAppleRunnerCommand.mockImplementation(async () => { @@ -670,6 +700,9 @@ test('captureSimulatorScreenshotWithFallback keeps the real runner fallback insi captureWithRunner: captureScreenshotViaRunner, shouldFallbackToRunner: shouldRetryIosSimulatorScreenshot, resolveCaptureTarget: async () => ({}), + // The state question belongs to screenshot-boot-state-recovery.test.ts; here it must answer + // "not turned off" so the runner fallback this case observes is the ordinary one. + observesSimulatorShutdown: async () => false, }, }); @@ -845,6 +878,8 @@ test('captureSimulatorScreenshotWithFallback keeps the panel rotation for a runn captureWithRetry: async () => { throw new Error('simctl screenshot failed'); }, + // This case is about the rotation facts; the state question is the recovery suite's. + observesSimulatorShutdown: async () => false, }, }); assert.deepEqual(facts, { displayRotation: 'landscape-right' }); @@ -865,6 +900,8 @@ test('an explicit screen mask refuses an unmasked runner fallback after simctl e captureWithRetry: captureSimulatorScreenshotWithRetry, captureWithRunner: captureScreenshotViaRunner, normalizeDensity: async () => {}, + // The mask, not a turned-off simulator, is what must refuse the runner here. + observesSimulatorShutdown: async () => false, }, }), (error) => error === failure, diff --git a/packages/platform-apple/src/core/__tests__/scripted-command-executor.ts b/packages/platform-apple/src/core/__tests__/scripted-command-executor.ts new file mode 100644 index 0000000000..5d4422de43 --- /dev/null +++ b/packages/platform-apple/src/core/__tests__/scripted-command-executor.ts @@ -0,0 +1,71 @@ +import type { ExecOptions, ExecResult } from '@agent-device/host-kit/command'; +import { requireExecSuccess, withCommandExecutorOverride } from '@agent-device/host-kit/command'; + +/** + * The host commands the production adapters would spawn, answered from a script instead. + * + * This is the seam `runCmd` consults before it spawns anything, so the Apple tool provider runs its + * real local adapter over it — including the screenshot protocol parse and its own failure + * construction — and nothing is launched. + * + * The script answers with the tool's result, exactly as a spawned process reports it. A non-zero + * exit that the caller did not ask to tolerate fails here, through the same host-kit + * `requireExecSuccess` the exec layer uses, so a scripted failure carries the shape a real one does. + */ +export type ScriptedCommandCall = { + cmd: string; + args: readonly string[]; + options: ExecOptions; +}; + +export type ScriptedCommandScript = (call: ScriptedCommandCall) => ExecResult; + +export type ScriptedCommandExecutor = { + /** The commands the code under test asked the host to run, in order. */ + calls(): ScriptedCommandCall[]; +}; + +/** Every command the script answers, whether or not the caller tolerated its failure. */ +export async function withScriptedCommands( + script: ScriptedCommandScript, + run: (executor: ScriptedCommandExecutor) => Promise, +): Promise { + const recorded: ScriptedCommandCall[] = []; + const executor: ScriptedCommandExecutor = { + calls: () => recorded.map((call) => ({ ...call })), + }; + return await withCommandExecutorOverride( + async (cmd, args, options) => { + const call = { cmd, args, options }; + recorded.push(call); + const result = script(call); + if (options.allowFailure) return result; + return requireExecSuccess(result, `${cmd} exited with code ${result.exitCode}`, { + cmd, + args, + }); + }, + async () => await run(executor), + ); +} + +/** A command that succeeded and printed `stdout`, the shape a working `simctl` answers with. */ +export function commandStdout(stdout: string): ExecResult { + return { exitCode: 0, stdout, stderr: '' }; +} + +/** The command failed: `stderr` is what the tool printed, `exitCode` what it exited with. */ +export function commandFailed(stderr: string, exitCode: number, stdout = ''): ExecResult { + return { exitCode, stdout, stderr }; +} + +/** Whether one recorded command is the `simctl list devices -j` boot-state read. */ +export function isSimctlListDevices(call: ScriptedCommandCall): boolean { + return call.args[0] === 'simctl' && call.args.includes('list') && call.args.includes('-j'); +} + +/** Whether one recorded command is this simulator's screenshot capture: `simctl [--set …] io screenshot …`. */ +export function isSimctlScreenshot(call: ScriptedCommandCall): boolean { + const ioIndex = call.args.indexOf('io'); + return call.args[0] === 'simctl' && ioIndex >= 0 && call.args[ioIndex + 2] === 'screenshot'; +} diff --git a/packages/platform-apple/src/core/config.ts b/packages/platform-apple/src/core/config.ts index b81ecc0233..728388eb24 100644 --- a/packages/platform-apple/src/core/config.ts +++ b/packages/platform-apple/src/core/config.ts @@ -65,6 +65,14 @@ export const IOS_FOLDABLE_ORIENTATION_SETTLE_MS = 600; // after a keyboard transition. Keep this bounded below the full capture budget. export const IOS_SIMULATOR_SCREENSHOT_SCALE_TIMEOUT_MS = 15_000; +/** + * The boot-state read a skipped-boot-check capture makes after its own failure. It answers only + * whether a re-boot is authorized, so it stays well under the 20s capture it follows: a wedged + * CoreSimulator must not spend the recovery budget and turn one bounded capture into a stalled + * request. A canceled request wins over this ceiling — the read carries the request's signal. + */ +export const IOS_SIMULATOR_SCREENSHOT_STATE_PROBE_TIMEOUT_MS = 5_000; + export const IOS_RUNNER_SCREENSHOT_COPY_TIMEOUT_MS = 20_000; export const IOS_SIMULATOR_SCREENSHOT_RETRY_MAX_ATTEMPTS = 5; diff --git a/packages/platform-apple/src/core/screenshot.ts b/packages/platform-apple/src/core/screenshot.ts index e63a543cc7..845346a93f 100644 --- a/packages/platform-apple/src/core/screenshot.ts +++ b/packages/platform-apple/src/core/screenshot.ts @@ -7,9 +7,8 @@ import type { EnvMap } from '@agent-device/kernel/source-value'; import { emitDiagnostic } from '@agent-device/host-kit/diagnostics'; import { copyHostFile } from '@agent-device/host-kit/host-file'; import { copySimulatorFileToHost } from './simulator-files.ts'; -import { resolveAppleToolProvider } from './tool-provider.ts'; import { Deadline, retryWithPolicy } from '@agent-device/host-kit/retry'; -import { AppError } from '@agent-device/kernel/errors'; +import { AppError, isRequestCanceledError } from '@agent-device/kernel/errors'; import { readRunnerScreenCaptureMetadata, type RunnerScreenCaptureMetadata, @@ -25,6 +24,7 @@ import { IOS_SIMULATOR_SCREENSHOT_RETRY_MAX_ATTEMPTS, IOS_SIMULATOR_SCREENSHOT_RETRY_MAX_DELAY_MS, IOS_SIMULATOR_SCREENSHOT_SCALE_TIMEOUT_MS, + IOS_SIMULATOR_SCREENSHOT_STATE_PROBE_TIMEOUT_MS, IOS_SIMULATOR_SCREENSHOT_TIMEOUT_MS, } from './config.ts'; import { runAppleRunnerCommand } from './runner-client.ts'; @@ -42,9 +42,12 @@ import { type AppleCaptureTarget, type AppleDeviceDisplay, } from './display-inventory.ts'; -import { ensureBootedSimulator } from './simulator.ts'; +import { ensureBootedSimulator, readSimulatorBootState } from './simulator.ts'; import { runSimctlForDevice } from './simctl-execution.ts'; -import { appleToolFailureText, extractAppleToolErrorMeta } from './tool-diagnostics.ts'; +import { SIMCTL_SHUTDOWN_STATE } from './simctl.ts'; +import { extractAppleToolErrorMeta } from './tool-diagnostics.ts'; +import { resolveAppleToolProvider, SIMCTL_SCREENSHOT_TIMEOUT_REASON } from './tool-provider.ts'; +import { isCommandTimeoutError } from '@agent-device/host-kit/command'; import { resolveIosPhysicalDeviceControl } from './physical-device-control.ts'; type SimulatorScreenshotFlowDeps = { @@ -68,6 +71,12 @@ type SimulatorScreenshotFlowDeps = { signal?: AbortSignal, ) => Promise; resolveCaptureTarget: (device: DeviceInfo) => Promise; + /** + * Whether this failed capture left its simulator turned off, observed from the tool's own state + * listing rather than from the capture's wording. Answers `false` when the listing failed or does + * not name the simulator: nobody may boot a simulator nobody observed. + */ + observesSimulatorShutdown: (device: DeviceInfo, signal?: AbortSignal) => Promise; captureWithRetry: ( device: DeviceInfo, outPath: string, @@ -116,6 +125,7 @@ const defaultSimulatorScreenshotFlowDeps: SimulatorScreenshotFlowDeps = { withNormalizedStatusBar: withNormalizedSimulatorStatusBar, withStatusBarHeld: withSimulatorStatusBarHeld, resolveCaptureTarget: resolveAppleCaptureTarget, + observesSimulatorShutdown: observesSimulatorShutdown, captureWithRetry: captureSimulatorScreenshotWithRetry, normalizeDensity: normalizeIosSimulatorScreenshotDensity, captureWithRunner: captureScreenshotViaRunner, @@ -181,6 +191,16 @@ export async function captureSimulatorScreenshotWithFallback( await deps.captureWithRetry(device, outPath, options.screenMask, display); await deps.normalizeDensity(device, outPath, options.pixelDensity, display?.pointScale); }; + const mayRecoverSkippedBootCheck = async (error: unknown): Promise => { + if (!options.skipIosSimulatorBootCheck) return false; + // A canceled request is terminal: it must not boot a simulator or start another capture. + if (isRequestCanceledError(error)) return false; + // The probe answers from the tool's state listing, so a probe that itself got canceled stays + // terminal rather than becoming an unknown state; anything else it cannot read keeps the + // capture's own failure, unchanged, as the answer the caller sees. + return await deps.observesSimulatorShutdown(device, options.runnerOptions?.signal); + }; + const captureWithFallback = async (): Promise => { if (resolveAppleToolProvider().simulatorScreenshotBackend !== 'runner') { try { @@ -188,10 +208,7 @@ export async function captureSimulatorScreenshotWithFallback( return captureFacts; } catch (error) { let screenshotError = error; - if ( - options.skipIosSimulatorBootCheck && - shouldEnsureBootedAfterSimulatorScreenshotFailure(error) - ) { + if (await mayRecoverSkippedBootCheck(error)) { await deps.ensureBooted(device); try { await captureAndNormalize(); @@ -451,31 +468,47 @@ function emitScreenshotFallbackDiagnostic( }); } +/** + * Whether a failed simulator capture may be retried, and, once its retries are spent, whether the + * runner may take it over. Both answers come from typed evidence only: host-kit's own record that it + * killed the command at its deadline, or the reason this module's simctl adapter stamped from the + * tool's error protocol. The capture's wording and its argv spellings select nothing. + */ export function shouldRetryIosSimulatorScreenshot(error: unknown): boolean { - if (!(error instanceof AppError)) return false; - if (error.code !== 'COMMAND_FAILED') return false; - const combined = appleToolFailureText(error); return ( - combined.includes('timeout waiting for screen surfaces') || - (combined.includes('nsposixerrordomain') && - combined.includes('code=60') && - combined.includes('screenshot')) || - (combined.includes('timed out') && combined.includes('screenshot')) + isCommandTimeoutError(error) || + (error instanceof AppError && + error.code === 'COMMAND_FAILED' && + error.details?.reason === SIMCTL_SCREENSHOT_TIMEOUT_REASON) ); } -function shouldEnsureBootedAfterSimulatorScreenshotFailure(error: unknown): boolean { - if (!(error instanceof AppError)) return false; - if (error.code !== 'COMMAND_FAILED') return false; - const combined = appleToolFailureText(error); - return ( - combined.includes('not booted') || - combined.includes('current state: shutdown') || - combined.includes('current state is shutdown') || - combined.includes('current state=shutdown') || - combined.includes('state: shutdown') || - combined.includes('state=shutdown') - ); +/** + * Whether this simulator is turned off right now, read from the tool's own state listing under the + * screenshot's own probe ceiling. Only the literal {@link SIMCTL_SHUTDOWN_STATE} authorizes a boot: + * `Booted`, `Booting`, `Creating` and `Shutting Down` describe a simulator that is on its way, and a + * listing that failed, omits the device, or reports no state proves nothing about it. + * + * A probe canceled with the request travels on: a request the caller gave up on stays terminal. + * Every other probe failure answers `false`, so the capture's own error stays the reported failure. + */ +async function observesSimulatorShutdown( + device: DeviceInfo, + signal?: AbortSignal, +): Promise { + signal?.throwIfAborted(); + let state: string | null; + try { + state = await readSimulatorBootState(device, { + signal, + timeoutMs: IOS_SIMULATOR_SCREENSHOT_STATE_PROBE_TIMEOUT_MS, + }); + } catch (error) { + if (isRequestCanceledError(error)) throw error; + return false; + } + signal?.throwIfAborted(); + return state === SIMCTL_SHUTDOWN_STATE; } async function normalizeIosSimulatorScreenshotDensity( diff --git a/packages/platform-apple/src/core/simctl.ts b/packages/platform-apple/src/core/simctl.ts index eedef950c4..8b7c6bdbe6 100644 --- a/packages/platform-apple/src/core/simctl.ts +++ b/packages/platform-apple/src/core/simctl.ts @@ -71,6 +71,9 @@ export function buildSimctlArgsForDevice( type SimctlListedDevice = { udid?: string; state?: string }; +/** The `state` value `simctl list devices -j` reports for a simulator that is turned off. */ +export const SIMCTL_SHUTDOWN_STATE = 'Shutdown'; + /** Parses runtime-keyed device lists from `simctl list devices -j` output. */ export function readSimctlDevicesByRuntime(stdout: string): Record { const payload = JSON.parse(stdout) as { devices?: Record }; diff --git a/packages/platform-apple/src/core/simulator.ts b/packages/platform-apple/src/core/simulator.ts index e4be2d63be..cc7e0b2b3d 100644 --- a/packages/platform-apple/src/core/simulator.ts +++ b/packages/platform-apple/src/core/simulator.ts @@ -180,13 +180,29 @@ export async function ensureBootedSimulator( await openIosSimulatorApp({ signal: options.signal }); } -async function getSimulatorState(device: DeviceInfo, signal?: AbortSignal): Promise { +/** + * The one boot-state read: `simctl list devices -j` answered through the listing's typed `state` + * field. `null` means the listing failed or omits this simulator, which is never a state. + * + * The caller names the ceiling. The boot path can afford the inventory budget; a caller that only + * wants to know whether it may boot after its own failed command bounds the same read to itself. + * This read does not consult the boot memo: it is the fresh observation, and the memo is written by + * the owners that make one. + */ +export async function readSimulatorBootState( + device: DeviceInfo, + options: { signal?: AbortSignal; timeoutMs: number }, +): Promise { const simctlArgs = buildSimctlArgsForDevice(device, ['list', 'devices', '-j']); const result = await runXcrun(simctlArgs, { allowFailure: true, - signal, - timeoutMs: IOS_SIMCTL_LIST_TIMEOUT_MS, + signal: options.signal, + timeoutMs: options.timeoutMs, }); if (result.exitCode !== 0) return null; return readSimctlDeviceState(result.stdout, device.id); } + +async function getSimulatorState(device: DeviceInfo, signal?: AbortSignal): Promise { + return await readSimulatorBootState(device, { signal, timeoutMs: IOS_SIMCTL_LIST_TIMEOUT_MS }); +} diff --git a/packages/platform-apple/src/core/tool-provider.ts b/packages/platform-apple/src/core/tool-provider.ts index ca2471863b..9136323c3c 100644 --- a/packages/platform-apple/src/core/tool-provider.ts +++ b/packages/platform-apple/src/core/tool-provider.ts @@ -1,6 +1,7 @@ import type { DeviceInfo } from '@agent-device/kernel/device'; import { coerceExecResult, + requireExecSuccess, runCmd, whichCmd, type ExecOptions, @@ -55,6 +56,70 @@ async function runSimctlCommand( return await runCommand('xcrun', [...simctlCommand(args)], options); } +/** + * simctl's own error-protocol header, printed once at the top of stderr ahead of the human + * sentence it renders: `An error was encountered processing the command (domain=…, code=…):`. + * The header line is the protocol; the text after it is CoreSimulator's prose. A nested + * `Underlying error (…)` line is indented and is never this line. + */ +const SIMCTL_ERROR_HEADER = + /^An error was encountered processing the command \(domain=([^,]+), code=(-?\d+)\):\s*$/m; + +/** + * `NSPOSIXErrorDomain` code 60 is macOS `ETIMEDOUT`: the tool's own answer that the screenshot + * call timed out. This is the only place that reads it, so the verdict becomes a typed reason here + * and nothing downstream re-parses the tool's text. A nested `Underlying error (…)` line is + * indented and is never the header, and a code the header does not state is not this reason. + */ +const SIMCTL_SCREENSHOT_TIMEOUT_DOMAIN = 'NSPOSIXErrorDomain'; +const SIMCTL_SCREENSHOT_TIMEOUT_CODE = 60; + +/** + * `details.reason` this adapter stamps when simctl's screenshot call reports its own protocol + * timeout. Owned beside the parse that mints it; the screenshot retry and runner-fallback decisions + * read the reason and never the tool's wording. + */ +export const SIMCTL_SCREENSHOT_TIMEOUT_REASON = 'simulator-screenshot-timeout'; + +/** + * The screenshot subcommand of an otherwise-unscoped simctl argv: `io screenshot …`. The + * `--set ` prefix is stripped first, and the flag fragments simctl's screenshot options add + * (`--mask=`, `--display=`) come after the subcommand, so positions 0 and 2 are the verb pair. + */ +function isSimctlScreenshotArgs(args: ScopedSimctlArgs): boolean { + const unscoped = args[0] === '--set' ? args.slice(2) : args; + return unscoped[0] === 'io' && unscoped[2] === 'screenshot'; +} + +/** + * The local simctl adapter: the one producer that runs `xcrun simctl` itself, so the one place + * allowed to read the tool's error protocol. A failed screenshot call answers with the typed + * {@link SIMCTL_SCREENSHOT_TIMEOUT_CODE} reason and keeps every exit-failure detail the exec layer + * would have produced; other failures, and other subcommands, keep exec's own behaviour. + * + * `reason` is stamped, never host-kit's `timeoutMs`: that field is exec's evidence that *it* killed + * a child at its deadline, and `isCommandTimeoutError` reads it as such. + */ +async function runLocalSimctlCommand( + args: ScopedSimctlArgs, + options?: AppleToolExecOptions, +): Promise { + const commandArgs = [...simctlCommand(args)]; + if (options?.allowFailure || !isSimctlScreenshotArgs(args)) { + return await runCmd('xcrun', commandArgs, options); + } + const result = await runCmd('xcrun', commandArgs, { ...options, allowFailure: true }); + const header = SIMCTL_ERROR_HEADER.exec(result.stderr); + const isScreenshotTimeout = + header?.[1] === SIMCTL_SCREENSHOT_TIMEOUT_DOMAIN && + Number(header?.[2]) === SIMCTL_SCREENSHOT_TIMEOUT_CODE; + return requireExecSuccess(result, `xcrun exited with code ${result.exitCode}`, { + cmd: 'xcrun', + args: commandArgs, + ...(isScreenshotTimeout ? { reason: SIMCTL_SCREENSHOT_TIMEOUT_REASON } : {}), + }); +} + function simctlCommandArgs(command: ScopedSimctlCommand): ScopedSimctlArgs { return Object.freeze(command.slice(1)) as ScopedSimctlArgs; } @@ -96,7 +161,9 @@ export function createLocalAppleToolProvider( const simctl: AppleSimctlToolProvider = { run: provider.simctl ? coerceRun(provider.simctl.run) - : async (args, options) => await runSimctlCommand(runCommand, args, options), + : provider.runCommand + ? async (args, options) => await runSimctlCommand(runCommand, args, options) + : runLocalSimctlCommand, }; const plist = provider.plist ?? { readJson: async (plistPath: string, signal?: AbortSignal) => From faac886f445498dcd434255cfb1a10a43f20fb89 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Fri, 13 Nov 2026 14:41:03 +0100 Subject: [PATCH 02/10] fix(apple): require the leading simctl error header --- .../screenshot-simctl-protocol.test.ts | 17 +++++++++++++++++ .../platform-apple/src/core/tool-provider.ts | 2 +- 2 files changed, 18 insertions(+), 1 deletion(-) diff --git a/packages/platform-apple/src/core/__tests__/screenshot-simctl-protocol.test.ts b/packages/platform-apple/src/core/__tests__/screenshot-simctl-protocol.test.ts index 11223b2693..130ffd0402 100644 --- a/packages/platform-apple/src/core/__tests__/screenshot-simctl-protocol.test.ts +++ b/packages/platform-apple/src/core/__tests__/screenshot-simctl-protocol.test.ts @@ -115,6 +115,15 @@ test('the typed reason survives a changed human message and an unrelated exit co assert.equal(shouldRetryIosSimulatorScreenshot(error), true); }); +test('the adapter accepts a leading protocol header with CRLF line endings', async () => { + const { error } = await captureScreenshot(() => + commandFailed(protocolTimeout().replaceAll('\n', '\r\n'), 60), + ); + + assert.equal(details(error).reason, SIMCTL_SCREENSHOT_TIMEOUT_REASON); + assert.equal(shouldRetryIosSimulatorScreenshot(error), true); +}); + test('the adapter keeps every exec failure detail beside the reason it stamped', async () => { const { error } = await captureScreenshot(() => commandFailed(protocolTimeout(), 60, 'Detected file type from extension: PNG\n'), @@ -214,6 +223,14 @@ test('the adapter ignores a header that simctl did not print at the top level', const cases: Array<[string, () => ExecResult]> = [ ['nested underlying-error header only', () => commandFailed(nestedOnly, 149)], ['header printed on stdout instead of stderr', () => commandFailed('', 60, stdoutOnly)], + [ + 'matching header after a diagnostic preamble', + () => commandFailed(`Diagnostic preamble\n${protocolTimeout()}`, 60), + ], + [ + 'matching header after an unrelated top-level error', + () => commandFailed(`${nestedOnly}\n${protocolTimeout()}`, 149), + ], ]; for (const [label, answer] of cases) { diff --git a/packages/platform-apple/src/core/tool-provider.ts b/packages/platform-apple/src/core/tool-provider.ts index 9136323c3c..2c1f59aa95 100644 --- a/packages/platform-apple/src/core/tool-provider.ts +++ b/packages/platform-apple/src/core/tool-provider.ts @@ -63,7 +63,7 @@ async function runSimctlCommand( * `Underlying error (…)` line is indented and is never this line. */ const SIMCTL_ERROR_HEADER = - /^An error was encountered processing the command \(domain=([^,]+), code=(-?\d+)\):\s*$/m; + /^An error was encountered processing the command \(domain=([^,]+), code=(-?\d+)\):[\t ]*(?:\r?\n|$)/; /** * `NSPOSIXErrorDomain` code 60 is macOS `ETIMEDOUT`: the tool's own answer that the screenshot From 54812974b38957886e072eb471c9006aee6c6a49 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Fri, 13 Nov 2026 21:52:54 +0100 Subject: [PATCH 03/10] test(apple): narrow scripted recovery errors and type retry attempts --- .../__tests__/screenshot-boot-state-recovery.test.ts | 2 +- .../core/__tests__/screenshot-simctl-protocol.test.ts | 10 ++++++---- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/packages/platform-apple/src/core/__tests__/screenshot-boot-state-recovery.test.ts b/packages/platform-apple/src/core/__tests__/screenshot-boot-state-recovery.test.ts index 2ba67cf387..72eb23523c 100644 --- a/packages/platform-apple/src/core/__tests__/screenshot-boot-state-recovery.test.ts +++ b/packages/platform-apple/src/core/__tests__/screenshot-boot-state-recovery.test.ts @@ -167,7 +167,7 @@ test('the re-capture that fails again reports its own failure and adds no second }); const probe = await probeRecovery(device, { state: () => listingFor(device.id, 'Shutdown'), - captureError: (attempt) => (attempt === 1 ? CAPTURE_FAILURE : recaptureFailure), + captureError: (attempt: number) => (attempt === 1 ? CAPTURE_FAILURE : recaptureFailure), }); assert.equal(probe.captureAttempts, 2); diff --git a/packages/platform-apple/src/core/__tests__/screenshot-simctl-protocol.test.ts b/packages/platform-apple/src/core/__tests__/screenshot-simctl-protocol.test.ts index 130ffd0402..ee9e281318 100644 --- a/packages/platform-apple/src/core/__tests__/screenshot-simctl-protocol.test.ts +++ b/packages/platform-apple/src/core/__tests__/screenshot-simctl-protocol.test.ts @@ -144,7 +144,7 @@ test('the adapter keeps every exec failure detail beside the reason it stamped', test('the adapter reads the protocol header for a set-scoped screenshot call', async () => { const scopedDevice: DeviceInfo = { ...SIMULATOR, simulatorSetPath: '/tmp/tenant/set' }; - const { error } = await withAppleToolProvider( + const outcome = await withAppleToolProvider( createLocalAppleToolProvider(), async () => await withScriptedCommands( @@ -161,7 +161,8 @@ test('the adapter reads the protocol header for a set-scoped screenshot call', a ), ); - assert.equal(details(error).reason, SIMCTL_SCREENSHOT_TIMEOUT_REASON); + assert.ok('error' in outcome, 'the scoped screenshot command must fail'); + assert.equal(details(outcome.error).reason, SIMCTL_SCREENSHOT_TIMEOUT_REASON); }); test('the same screenshot text without the protocol header stays unattributed', async () => { @@ -317,7 +318,7 @@ test('the adapter does not parse a simctl subcommand it did not scope as a scree ] as const; for (const [label, args] of otherSubcommands) { - const { error } = await withAppleToolProvider( + const outcome = await withAppleToolProvider( createLocalAppleToolProvider(), async () => await withScriptedCommands( @@ -332,8 +333,9 @@ test('the adapter does not parse a simctl subcommand it did not scope as a scree ), ); + assert.ok('error' in outcome, `${label} must report the scripted command failure`); assert.equal( - details(error).reason, + details(outcome.error).reason, undefined, `a ${label} failure is not a screenshot timeout`, ); From b80056b6fd92857e2a4e4df5a5f0ffc8fa0ec8ae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 14 Nov 2026 11:57:39 +0100 Subject: [PATCH 04/10] test(apple): keep screenshot recovery proofs within lint limits --- .../screenshot-boot-state-recovery.test.ts | 6 +-- .../__tests__/screenshot-retry-policy.test.ts | 48 +++++++++++++++++++ .../screenshot-simctl-protocol.test.ts | 14 +++--- .../__tests__/screenshot-simctl-retry.test.ts | 2 +- .../src/core/__tests__/screenshot.test.ts | 43 ----------------- 5 files changed, 59 insertions(+), 54 deletions(-) create mode 100644 packages/platform-apple/src/core/__tests__/screenshot-retry-policy.test.ts diff --git a/packages/platform-apple/src/core/__tests__/screenshot-boot-state-recovery.test.ts b/packages/platform-apple/src/core/__tests__/screenshot-boot-state-recovery.test.ts index 72eb23523c..a025174813 100644 --- a/packages/platform-apple/src/core/__tests__/screenshot-boot-state-recovery.test.ts +++ b/packages/platform-apple/src/core/__tests__/screenshot-boot-state-recovery.test.ts @@ -124,7 +124,7 @@ async function probeRecovery( }, }).then( () => undefined, - (caught: unknown) => caught, + (error: unknown) => error, ); return { error, @@ -179,7 +179,7 @@ test('the re-capture that fails again reports its own failure and adds no second test.each(['Booted', 'Booting', 'Creating', 'Shutting Down', 'Living'] as const)( 'a simulator listed as %s is not turned off, so nothing boots or re-captures', async (state) => { - const device = simulator(`sim-recover-${state.toLowerCase().replace(/[^a-z]+/g, '-')}`); + const device = simulator(`sim-recover-${state.toLowerCase().replaceAll(/[^a-z]+/g, '-')}`); const probe = await probeRecovery(device, { state: () => listingFor(device.id, state) }); assert.equal(probe.stateReads.length, 1, 'exactly one state observation'); @@ -330,7 +330,7 @@ test('a mask-bearing capture that observed a shutdown still refuses the runner f }, }).then( () => undefined, - (caught: unknown) => caught, + (error: unknown) => error, ); return { error, stateReads: executor.calls().filter(isSimctlListDevices) }; }, diff --git a/packages/platform-apple/src/core/__tests__/screenshot-retry-policy.test.ts b/packages/platform-apple/src/core/__tests__/screenshot-retry-policy.test.ts new file mode 100644 index 0000000000..3d6f9ff224 --- /dev/null +++ b/packages/platform-apple/src/core/__tests__/screenshot-retry-policy.test.ts @@ -0,0 +1,48 @@ +import { test } from 'vitest'; +import assert from 'node:assert/strict'; +import { AppError } from '@agent-device/kernel/errors'; +import { shouldRetryIosSimulatorScreenshot } from '../screenshot.ts'; +import { SIMCTL_SCREENSHOT_TIMEOUT_REASON } from '../tool-provider.ts'; + +test('shouldRetryIosSimulatorScreenshot retries the timeout reason the adapter stamps', () => { + // The reason the local simctl adapter stamps from the tool's protocol header; see + // screenshot-simctl-protocol.test.ts for the producer that mints it. + const error = new AppError('COMMAND_FAILED', 'xcrun exited with code 60', { + stderr: 'Timeout waiting for screen surfaces', + exitCode: 60, + reason: SIMCTL_SCREENSHOT_TIMEOUT_REASON, + }); + assert.equal(shouldRetryIosSimulatorScreenshot(error), true); +}); + +test('shouldRetryIosSimulatorScreenshot retries a command host-kit killed at its deadline', () => { + const error = new AppError('COMMAND_FAILED', 'xcrun timed out after 20000ms', { + args: ['simctl', 'io', 'sim-1', 'screenshot', '/tmp/out.png'], + timeoutMs: 20_000, + }); + assert.equal(shouldRetryIosSimulatorScreenshot(error), true); +}); + +test('shouldRetryIosSimulatorScreenshot ignores unrelated screenshot failures', () => { + const error = new AppError('COMMAND_FAILED', 'Failed to capture iOS screenshot', { + stderr: 'No such file or directory', + exitCode: 2, + }); + assert.equal(shouldRetryIosSimulatorScreenshot(error), false); +}); + +test('the same screenshot timeout wording without the typed reason is not retryable', () => { + // Identical wording and argv to the two positives above, minus the typed evidence: the retry + // decision must not be reachable from the tool's prose or from this module's own argv. + const worded = new AppError('COMMAND_FAILED', 'Detected file type from extension: PNG', { + stderr: 'Timeout waiting for screen surfaces', + exitCode: 60, + }); + const wordedAndSpelled = new AppError('COMMAND_FAILED', 'xcrun timed out after 20000ms', { + args: ['simctl', 'io', 'sim-1', 'screenshot', '/tmp/out.png'], + stderr: 'Timeout waiting for screen surfaces', + exitCode: 60, + }); + assert.equal(shouldRetryIosSimulatorScreenshot(worded), false); + assert.equal(shouldRetryIosSimulatorScreenshot(wordedAndSpelled), false); +}); diff --git a/packages/platform-apple/src/core/__tests__/screenshot-simctl-protocol.test.ts b/packages/platform-apple/src/core/__tests__/screenshot-simctl-protocol.test.ts index ee9e281318..f620b61386 100644 --- a/packages/platform-apple/src/core/__tests__/screenshot-simctl-protocol.test.ts +++ b/packages/platform-apple/src/core/__tests__/screenshot-simctl-protocol.test.ts @@ -154,8 +154,8 @@ test('the adapter reads the protocol header for a set-scoped screenshot call', a return await runXcrun(buildSimctlArgsForDevice(scopedDevice, SCREENSHOT_ARGS), { timeoutMs: 20_000, }); - } catch (caught) { - return { error: caught }; + } catch (error) { + return { error }; } }, ), @@ -268,7 +268,7 @@ test('the adapter leaves a caller-supplied command executor unclassified', async async () => await runScreenshot().then( () => null, - (caught: unknown) => caught, + (error: unknown) => error, ), ), ); @@ -300,7 +300,7 @@ test('the adapter leaves a caller-supplied simctl runner unclassified', async () async () => await runScreenshot().then( () => null, - (caught: unknown) => caught, + (error: unknown) => error, ), ), ); @@ -328,7 +328,7 @@ test('the adapter does not parse a simctl subcommand it did not scope as a scree timeoutMs: 20_000, }).then( (result) => ({ result }), - (caught: unknown) => ({ error: caught }), + (error: unknown) => ({ error }), ), ), ); @@ -352,8 +352,8 @@ test('the adapter leaves an allowFailure screenshot call untouched', async () => async (executor) => { try { return { result: await runScreenshot({ allowFailure: true }), calls: executor.calls() }; - } catch (caught) { - return { error: caught }; + } catch (error) { + return { error }; } }, ), diff --git a/packages/platform-apple/src/core/__tests__/screenshot-simctl-retry.test.ts b/packages/platform-apple/src/core/__tests__/screenshot-simctl-retry.test.ts index 265aea2f5e..ccdf1ad1fe 100644 --- a/packages/platform-apple/src/core/__tests__/screenshot-simctl-retry.test.ts +++ b/packages/platform-apple/src/core/__tests__/screenshot-simctl-retry.test.ts @@ -109,7 +109,7 @@ async function captureThroughLocalAdapter( await withScriptedCommands(script, async (executor) => { const error = await captureSimulatorScreenshotWithRetry(SIMULATOR, outPath, undefined).then( () => undefined, - (caught: unknown) => caught, + (error: unknown) => error, ); const calls = executor.calls(); return { diff --git a/packages/platform-apple/src/core/__tests__/screenshot.test.ts b/packages/platform-apple/src/core/__tests__/screenshot.test.ts index fece4becaf..5ec4c601af 100644 --- a/packages/platform-apple/src/core/__tests__/screenshot.test.ts +++ b/packages/platform-apple/src/core/__tests__/screenshot.test.ts @@ -113,49 +113,6 @@ async function waitForFileText(filePath: string, attempts = 20): Promise throw lastError; } -test('shouldRetryIosSimulatorScreenshot retries the timeout reason the adapter stamps', () => { - // The reason the local simctl adapter stamps from the tool's protocol header; see - // screenshot-simctl-protocol.test.ts for the producer that mints it. - const error = new AppError('COMMAND_FAILED', 'xcrun exited with code 60', { - stderr: 'Timeout waiting for screen surfaces', - exitCode: 60, - reason: SIMCTL_SCREENSHOT_TIMEOUT_REASON, - }); - assert.equal(shouldRetryIosSimulatorScreenshot(error), true); -}); - -test('shouldRetryIosSimulatorScreenshot retries a command host-kit killed at its deadline', () => { - const error = new AppError('COMMAND_FAILED', 'xcrun timed out after 20000ms', { - args: ['simctl', 'io', 'sim-1', 'screenshot', '/tmp/out.png'], - timeoutMs: 20_000, - }); - assert.equal(shouldRetryIosSimulatorScreenshot(error), true); -}); - -test('shouldRetryIosSimulatorScreenshot ignores unrelated screenshot failures', () => { - const error = new AppError('COMMAND_FAILED', 'Failed to capture iOS screenshot', { - stderr: 'No such file or directory', - exitCode: 2, - }); - assert.equal(shouldRetryIosSimulatorScreenshot(error), false); -}); - -test('the same screenshot timeout wording without the typed reason is not retryable', () => { - // Identical wording and argv to the two positives above, minus the typed evidence: the retry - // decision must not be reachable from the tool's prose or from this module's own argv. - const worded = new AppError('COMMAND_FAILED', 'Detected file type from extension: PNG', { - stderr: 'Timeout waiting for screen surfaces', - exitCode: 60, - }); - const wordedAndSpelled = new AppError('COMMAND_FAILED', 'xcrun timed out after 20000ms', { - args: ['simctl', 'io', 'sim-1', 'screenshot', '/tmp/out.png'], - stderr: 'Timeout waiting for screen surfaces', - exitCode: 60, - }); - assert.equal(shouldRetryIosSimulatorScreenshot(worded), false); - assert.equal(shouldRetryIosSimulatorScreenshot(wordedAndSpelled), false); -}); - test('captureSimulatorScreenshotWithFallback falls back to runner after retry exhaustion', async () => { const tmpDir = await mkdtempForTest('agent-device-ios-runner-fallback-'); let ensureBootedCalls = 0; From 600d51dc49c06b44c3e66e098cff3629fee72b71 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 14 Nov 2026 12:20:09 +0100 Subject: [PATCH 05/10] refactor(apple): use the real screenshot recovery state reader --- .../core/__tests__/fake-status-bar-simctl.ts | 3 ++ .../screenshot-boot-state-recovery.test.ts | 12 +++++--- .../__tests__/screenshot-simctl-retry.test.ts | 8 ----- .../screenshot-status-bar-concurrency.test.ts | 4 --- .../src/core/__tests__/screenshot.test.ts | 29 ++++++++++++------- .../platform-apple/src/core/screenshot.ts | 9 +----- 6 files changed, 31 insertions(+), 34 deletions(-) diff --git a/packages/platform-apple/src/core/__tests__/fake-status-bar-simctl.ts b/packages/platform-apple/src/core/__tests__/fake-status-bar-simctl.ts index a9df742b08..2d11609889 100644 --- a/packages/platform-apple/src/core/__tests__/fake-status-bar-simctl.ts +++ b/packages/platform-apple/src/core/__tests__/fake-status-bar-simctl.ts @@ -142,6 +142,9 @@ export function createFakeStatusBarSimctl( return { script: (args): FakeAppleToolResponse => { + if (args[0] === 'simctl' && args[1] === 'list' && args[2] === 'devices' && args[3] === '-j') { + return JSON.stringify({ devices: { runtime: [{ udid, state: 'Booted' }] } }); + } const unexpected = (detail: string): FakeAppleToolResponse => ({ stderr: `unexpected status bar call: ${detail}`, exitCode: 1, diff --git a/packages/platform-apple/src/core/__tests__/screenshot-boot-state-recovery.test.ts b/packages/platform-apple/src/core/__tests__/screenshot-boot-state-recovery.test.ts index a025174813..ba185deaed 100644 --- a/packages/platform-apple/src/core/__tests__/screenshot-boot-state-recovery.test.ts +++ b/packages/platform-apple/src/core/__tests__/screenshot-boot-state-recovery.test.ts @@ -228,10 +228,14 @@ test('a state read that itself fails keeps the capture failure and its diagnosti assert.equal(probe.error, CAPTURE_FAILURE, 'a failed probe never replaces the capture failure'); assert.equal(probe.boots, 0); assert.equal(probe.captureAttempts, 1); - const details = (CAPTURE_FAILURE.details ?? {}) as Record; - assert.equal(details.exitCode, 60); - assert.equal(details.processExitError, true); - assert.equal(typeof details.hint, 'string', 'the hint the producer attached is preserved'); + assert.ok(probe.error instanceof AppError); + assert.equal(probe.error.details?.exitCode, 60); + assert.equal(probe.error.details?.processExitError, true); + assert.equal( + typeof probe.error.details?.hint, + 'string', + 'the hint the producer attached is preserved', + ); }); test('the recovery probe is bounded by the screenshot ceiling, not the inventory budget', async () => { diff --git a/packages/platform-apple/src/core/__tests__/screenshot-simctl-retry.test.ts b/packages/platform-apple/src/core/__tests__/screenshot-simctl-retry.test.ts index ccdf1ad1fe..eab7cb80ab 100644 --- a/packages/platform-apple/src/core/__tests__/screenshot-simctl-retry.test.ts +++ b/packages/platform-apple/src/core/__tests__/screenshot-simctl-retry.test.ts @@ -22,7 +22,6 @@ import { SIMCTL_SCREENSHOT_TIMEOUT_REASON, } from '../tool-provider.ts'; import { captureSimulatorScreenshotWithRetry } from '../screenshot.ts'; -import { IOS_SIMULATOR_SCREENSHOT_STATE_PROBE_TIMEOUT_MS } from '../config.ts'; import { mkdtempForTest } from '../../__tests__/tmp-dir.ts'; import { commandFailed, @@ -201,10 +200,3 @@ test('an unrelated protocol code stays terminal and keeps the tool failure as re assert.equal(attempts, 1); assert.equal((error as { details?: Record }).details?.reason, undefined); }); - -test('the boot-state probe ceiling stays below the capture budget it explains', () => { - // The probe is a best-effort read on the failure path, so it must be bounded under the operation - // it follows; the inventory read's own 60s budget would invert that. - assert.equal(IOS_SIMULATOR_SCREENSHOT_STATE_PROBE_TIMEOUT_MS, 5_000); - assert.ok(IOS_SIMULATOR_SCREENSHOT_STATE_PROBE_TIMEOUT_MS < 20_000); -}); diff --git a/packages/platform-apple/src/core/__tests__/screenshot-status-bar-concurrency.test.ts b/packages/platform-apple/src/core/__tests__/screenshot-status-bar-concurrency.test.ts index dea3c09050..43521bd349 100644 --- a/packages/platform-apple/src/core/__tests__/screenshot-status-bar-concurrency.test.ts +++ b/packages/platform-apple/src/core/__tests__/screenshot-status-bar-concurrency.test.ts @@ -88,10 +88,6 @@ function captureDeps(captureWithRetry: (device: DeviceInfo) => Promise) { normalizeDensity: async () => {}, captureWithRunner: async () => undefined, shouldFallbackToRunner: () => false, - // The capture under these cases either succeeds or fails as a transport failure; none of them is - // about the recovery, and a probe would query the fake status bar tool about a boot state it - // does not model. - observesSimulatorShutdown: async () => false, }; } diff --git a/packages/platform-apple/src/core/__tests__/screenshot.test.ts b/packages/platform-apple/src/core/__tests__/screenshot.test.ts index 5ec4c601af..cc7ce6c1e2 100644 --- a/packages/platform-apple/src/core/__tests__/screenshot.test.ts +++ b/packages/platform-apple/src/core/__tests__/screenshot.test.ts @@ -92,7 +92,12 @@ assert(MEASURED_CAPTURE, 'the golden table must record at least one measured cap beforeEach(() => { vi.resetAllMocks(); - mockRunCmd.mockImplementation(execActual.runCmd); + mockRunCmd.mockImplementation(async (cmd, args, options) => { + if (args.includes('list') && args.includes('devices') && args.includes('-j')) { + return simulatorListing('Booted'); + } + return await execActual.runCmd(cmd, args, options); + }); mockRetryWithPolicy.mockImplementation(retryActual.retryWithPolicy); mockRunAppleRunnerCommand.mockImplementation(runnerActual.runAppleRunnerCommand); mockEnsureBootedSimulator.mockImplementation(simulatorActual.ensureBootedSimulator); @@ -100,6 +105,14 @@ beforeEach(() => { mockWithNormalizedStatusBar.mockImplementation(async (_device, capture) => await capture()); }); +function simulatorListing(state: 'Booted' | 'Shutdown') { + return { + exitCode: 0, + stderr: '', + stdout: JSON.stringify({ devices: { runtime: [{ udid: IOS_TEST_SIMULATOR.id, state }] } }), + }; +} + async function waitForFileText(filePath: string, attempts = 20): Promise { let lastError: unknown; for (let attempt = 0; attempt < attempts; attempt += 1) { @@ -251,6 +264,7 @@ test('captureSimulatorScreenshotWithFallback can skip session-backed simulator b }); test('captureSimulatorScreenshotWithFallback boots skipped-check simulator after an observed shutdown', async () => { + mockRunCmd.mockResolvedValue(simulatorListing('Shutdown')); // The boot authorization is the observed state, not the capture's wording; see // screenshot-boot-state-recovery.test.ts for the state seam itself. This case pins the flow: // one boot, one re-capture, no runner leg. @@ -275,7 +289,6 @@ test('captureSimulatorScreenshotWithFallback boots skipped-check simulator after deps: { ensureBooted, captureWithRetry, - observesSimulatorShutdown: async () => true, normalizeDensity: async () => {}, captureWithRunner, shouldFallbackToRunner: shouldRetryIosSimulatorScreenshot, @@ -289,6 +302,7 @@ test('captureSimulatorScreenshotWithFallback boots skipped-check simulator after }); test('captureSimulatorScreenshotWithFallback keeps runner fallback after skipped-check boot recovery', async () => { + mockRunCmd.mockResolvedValue(simulatorListing('Shutdown')); const ensureBooted = vi.fn(async () => {}); let captureAttempts = 0; const captureWithRetry = vi.fn(async () => { @@ -314,7 +328,6 @@ test('captureSimulatorScreenshotWithFallback keeps runner fallback after skipped deps: { ensureBooted, captureWithRetry, - observesSimulatorShutdown: async () => true, normalizeDensity: async () => {}, captureWithRunner, shouldFallbackToRunner: shouldRetryIosSimulatorScreenshot, @@ -631,6 +644,9 @@ test('captureSimulatorScreenshotWithFallback keeps the real runner fallback insi }); mockRunCmd.mockImplementation(async (cmd, args) => { const argv = [cmd, ...(args ?? [])].join(' '); + if (args.includes('list') && args.includes('devices') && args.includes('-j')) { + return simulatorListing('Booted'); + } if (argv.includes('status_bar')) { timeline.push(`status_bar:${/status_bar\s+\S+\s+(\S+)/.exec(argv)?.[1]}`); return { @@ -657,9 +673,6 @@ test('captureSimulatorScreenshotWithFallback keeps the real runner fallback insi captureWithRunner: captureScreenshotViaRunner, shouldFallbackToRunner: shouldRetryIosSimulatorScreenshot, resolveCaptureTarget: async () => ({}), - // The state question belongs to screenshot-boot-state-recovery.test.ts; here it must answer - // "not turned off" so the runner fallback this case observes is the ordinary one. - observesSimulatorShutdown: async () => false, }, }); @@ -835,8 +848,6 @@ test('captureSimulatorScreenshotWithFallback keeps the panel rotation for a runn captureWithRetry: async () => { throw new Error('simctl screenshot failed'); }, - // This case is about the rotation facts; the state question is the recovery suite's. - observesSimulatorShutdown: async () => false, }, }); assert.deepEqual(facts, { displayRotation: 'landscape-right' }); @@ -857,8 +868,6 @@ test('an explicit screen mask refuses an unmasked runner fallback after simctl e captureWithRetry: captureSimulatorScreenshotWithRetry, captureWithRunner: captureScreenshotViaRunner, normalizeDensity: async () => {}, - // The mask, not a turned-off simulator, is what must refuse the runner here. - observesSimulatorShutdown: async () => false, }, }), (error) => error === failure, diff --git a/packages/platform-apple/src/core/screenshot.ts b/packages/platform-apple/src/core/screenshot.ts index 845346a93f..49a562dce1 100644 --- a/packages/platform-apple/src/core/screenshot.ts +++ b/packages/platform-apple/src/core/screenshot.ts @@ -71,12 +71,6 @@ type SimulatorScreenshotFlowDeps = { signal?: AbortSignal, ) => Promise; resolveCaptureTarget: (device: DeviceInfo) => Promise; - /** - * Whether this failed capture left its simulator turned off, observed from the tool's own state - * listing rather than from the capture's wording. Answers `false` when the listing failed or does - * not name the simulator: nobody may boot a simulator nobody observed. - */ - observesSimulatorShutdown: (device: DeviceInfo, signal?: AbortSignal) => Promise; captureWithRetry: ( device: DeviceInfo, outPath: string, @@ -125,7 +119,6 @@ const defaultSimulatorScreenshotFlowDeps: SimulatorScreenshotFlowDeps = { withNormalizedStatusBar: withNormalizedSimulatorStatusBar, withStatusBarHeld: withSimulatorStatusBarHeld, resolveCaptureTarget: resolveAppleCaptureTarget, - observesSimulatorShutdown: observesSimulatorShutdown, captureWithRetry: captureSimulatorScreenshotWithRetry, normalizeDensity: normalizeIosSimulatorScreenshotDensity, captureWithRunner: captureScreenshotViaRunner, @@ -198,7 +191,7 @@ export async function captureSimulatorScreenshotWithFallback( // The probe answers from the tool's state listing, so a probe that itself got canceled stays // terminal rather than becoming an unknown state; anything else it cannot read keeps the // capture's own failure, unchanged, as the answer the caller sees. - return await deps.observesSimulatorShutdown(device, options.runnerOptions?.signal); + return await observesSimulatorShutdown(device, options.runnerOptions?.signal); }; const captureWithFallback = async (): Promise => { From 855aa4acc510cda6eba9891d12ec89d5c5ef1301 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 14 Nov 2026 13:04:24 +0100 Subject: [PATCH 06/10] test(apple): pin the observed screenshot recovery probe budget --- .../screenshot-boot-state-recovery.test.ts | 18 ++++++------------ 1 file changed, 6 insertions(+), 12 deletions(-) diff --git a/packages/platform-apple/src/core/__tests__/screenshot-boot-state-recovery.test.ts b/packages/platform-apple/src/core/__tests__/screenshot-boot-state-recovery.test.ts index ba185deaed..34c69ec8c1 100644 --- a/packages/platform-apple/src/core/__tests__/screenshot-boot-state-recovery.test.ts +++ b/packages/platform-apple/src/core/__tests__/screenshot-boot-state-recovery.test.ts @@ -27,10 +27,7 @@ vi.mock('../screenshot-status-bar.ts', async (importOriginal) => { import { ensureBootedSimulator } from '../simulator.ts'; import { captureSimulatorScreenshotWithFallback } from '../screenshot.ts'; import { SIMCTL_SCREENSHOT_TIMEOUT_REASON } from '../tool-provider.ts'; -import { - IOS_SIMCTL_LIST_TIMEOUT_MS, - IOS_SIMULATOR_SCREENSHOT_STATE_PROBE_TIMEOUT_MS, -} from '../config.ts'; +import { IOS_SIMULATOR_SCREENSHOT_TIMEOUT_MS } from '../config.ts'; import { commandFailed, commandStdout, @@ -238,20 +235,17 @@ test('a state read that itself fails keeps the capture failure and its diagnosti ); }); -test('the recovery probe is bounded by the screenshot ceiling, not the inventory budget', async () => { +test('the five-second recovery probe stays below the capture budget', async () => { const device = simulator('sim-recover-budget'); const probe = await probeRecovery(device, { state: () => listingFor(device.id, 'Shutdown') }); const [onlyProbe] = probe.stateReads; assert.ok(onlyProbe, 'the recovery reads the boot state once'); - assert.equal( - onlyProbe.options.timeoutMs, - IOS_SIMULATOR_SCREENSHOT_STATE_PROBE_TIMEOUT_MS, - 'the probe runs under the screenshot-owned ceiling', - ); + const timeoutMs = onlyProbe.options.timeoutMs; + assert.equal(timeoutMs, 5_000, 'the probe uses the adopted five-second ceiling'); assert.ok( - IOS_SIMULATOR_SCREENSHOT_STATE_PROBE_TIMEOUT_MS < IOS_SIMCTL_LIST_TIMEOUT_MS, - 'the probe must not inherit the 60s inventory budget behind a 20s capture', + timeoutMs !== undefined && timeoutMs < IOS_SIMULATOR_SCREENSHOT_TIMEOUT_MS, + 'the recovery probe stays below the capture budget', ); }); From 50034fe3afeaba5893090fdc4f060586dda5fb9f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 14 Nov 2026 13:40:16 +0100 Subject: [PATCH 07/10] test(host-kit): isolate process fixtures from live procfs --- .../host-kit/src/internal/host-process-liveness.test.ts | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/packages/host-kit/src/internal/host-process-liveness.test.ts b/packages/host-kit/src/internal/host-process-liveness.test.ts index a2e6b212f8..034658fd49 100644 --- a/packages/host-kit/src/internal/host-process-liveness.test.ts +++ b/packages/host-kit/src/internal/host-process-liveness.test.ts @@ -42,6 +42,13 @@ function psInstalledAt(installed: readonly string[]): void { } beforeEach(() => { + const readFileSync = fs.readFileSync; + vi.spyOn(fs, 'readFileSync').mockImplementation((path, options) => { + if (String(path).startsWith('/proc/')) { + throw Object.assign(new Error('proc is unavailable in the ps fixture'), { code: 'ENOENT' }); + } + return readFileSync(path, options); + }); mockRunCmdSync.mockReset(); mockRunCmd.mockReset(); }); From cec1726bb03383a3c678d8ea7313713280a5412e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 14 Nov 2026 14:02:24 +0100 Subject: [PATCH 08/10] fix(apple): accept simctl timeout headers after diagnostics --- .../screenshot-simctl-protocol.test.ts | 19 +++++++++- .../platform-apple/src/core/tool-provider.ts | 38 +++---------------- 2 files changed, 23 insertions(+), 34 deletions(-) diff --git a/packages/platform-apple/src/core/__tests__/screenshot-simctl-protocol.test.ts b/packages/platform-apple/src/core/__tests__/screenshot-simctl-protocol.test.ts index f620b61386..9cd3a481d0 100644 --- a/packages/platform-apple/src/core/__tests__/screenshot-simctl-protocol.test.ts +++ b/packages/platform-apple/src/core/__tests__/screenshot-simctl-protocol.test.ts @@ -115,6 +115,21 @@ test('the typed reason survives a changed human message and an unrelated exit co assert.equal(shouldRetryIosSimulatorScreenshot(error), true); }); +test.each(['\n', '\r\n'])( + 'a PNG diagnostic before the stderr header preserves typed retry with line ending %j', + async (lineEnding) => { + const stderr = [ + 'Detected file type from extension: PNG', + ...protocolTimeout().split('\n'), + ].join(lineEnding); + const { error } = await captureScreenshot(() => commandFailed(stderr, 60)); + + assert.equal(details(error).stderr, stderr); + assert.equal(details(error).reason, SIMCTL_SCREENSHOT_TIMEOUT_REASON); + assert.equal(shouldRetryIosSimulatorScreenshot(error), true); + }, +); + test('the adapter accepts a leading protocol header with CRLF line endings', async () => { const { error } = await captureScreenshot(() => commandFailed(protocolTimeout().replaceAll('\n', '\r\n'), 60), @@ -225,8 +240,8 @@ test('the adapter ignores a header that simctl did not print at the top level', ['nested underlying-error header only', () => commandFailed(nestedOnly, 149)], ['header printed on stdout instead of stderr', () => commandFailed('', 60, stdoutOnly)], [ - 'matching header after a diagnostic preamble', - () => commandFailed(`Diagnostic preamble\n${protocolTimeout()}`, 60), + 'indented matching header after a diagnostic preamble', + () => commandFailed(`Detected file type from extension: PNG\n ${protocolTimeout()}`, 60), ], [ 'matching header after an unrelated top-level error', diff --git a/packages/platform-apple/src/core/tool-provider.ts b/packages/platform-apple/src/core/tool-provider.ts index 2c1f59aa95..ad8490b239 100644 --- a/packages/platform-apple/src/core/tool-provider.ts +++ b/packages/platform-apple/src/core/tool-provider.ts @@ -56,50 +56,24 @@ async function runSimctlCommand( return await runCommand('xcrun', [...simctlCommand(args)], options); } -/** - * simctl's own error-protocol header, printed once at the top of stderr ahead of the human - * sentence it renders: `An error was encountered processing the command (domain=…, code=…):`. - * The header line is the protocol; the text after it is CoreSimulator's prose. A nested - * `Underlying error (…)` line is indented and is never this line. - */ +/** The first unindented simctl error header; diagnostic lines can precede it on stderr. */ const SIMCTL_ERROR_HEADER = - /^An error was encountered processing the command \(domain=([^,]+), code=(-?\d+)\):[\t ]*(?:\r?\n|$)/; + /^An error was encountered processing the command \(domain=([^,]+), code=(-?\d+)\):[\t ]*(?:\r?\n|$)/m; -/** - * `NSPOSIXErrorDomain` code 60 is macOS `ETIMEDOUT`: the tool's own answer that the screenshot - * call timed out. This is the only place that reads it, so the verdict becomes a typed reason here - * and nothing downstream re-parses the tool's text. A nested `Underlying error (…)` line is - * indented and is never the header, and a code the header does not state is not this reason. - */ +/** macOS ETIMEDOUT in simctl's protocol, classified only by this local adapter. */ const SIMCTL_SCREENSHOT_TIMEOUT_DOMAIN = 'NSPOSIXErrorDomain'; const SIMCTL_SCREENSHOT_TIMEOUT_CODE = 60; -/** - * `details.reason` this adapter stamps when simctl's screenshot call reports its own protocol - * timeout. Owned beside the parse that mints it; the screenshot retry and runner-fallback decisions - * read the reason and never the tool's wording. - */ +/** The local screenshot timeout reason consumed by retry and runner fallback. */ export const SIMCTL_SCREENSHOT_TIMEOUT_REASON = 'simulator-screenshot-timeout'; -/** - * The screenshot subcommand of an otherwise-unscoped simctl argv: `io screenshot …`. The - * `--set ` prefix is stripped first, and the flag fragments simctl's screenshot options add - * (`--mask=`, `--display=`) come after the subcommand, so positions 0 and 2 are the verb pair. - */ +/** Screenshot options follow `io screenshot`; a simulator-set prefix precedes it. */ function isSimctlScreenshotArgs(args: ScopedSimctlArgs): boolean { const unscoped = args[0] === '--set' ? args.slice(2) : args; return unscoped[0] === 'io' && unscoped[2] === 'screenshot'; } -/** - * The local simctl adapter: the one producer that runs `xcrun simctl` itself, so the one place - * allowed to read the tool's error protocol. A failed screenshot call answers with the typed - * {@link SIMCTL_SCREENSHOT_TIMEOUT_CODE} reason and keeps every exit-failure detail the exec layer - * would have produced; other failures, and other subcommands, keep exec's own behaviour. - * - * `reason` is stamped, never host-kit's `timeoutMs`: that field is exec's evidence that *it* killed - * a child at its deadline, and `isCommandTimeoutError` reads it as such. - */ +/** Stamp {@link SIMCTL_SCREENSHOT_TIMEOUT_REASON}, preserving exec's own timeout evidence. */ async function runLocalSimctlCommand( args: ScopedSimctlArgs, options?: AppleToolExecOptions, From b0cc3743bf705de1a3489c736f5051913ae20181 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 14 Nov 2026 14:21:27 +0100 Subject: [PATCH 09/10] fix(apple): retain screenshot recovery diagnostics --- .../screenshot-boot-state-recovery.test.ts | 57 +++++++++++++++++-- .../screenshot-simctl-protocol.test.ts | 49 +++++++++++++++- .../platform-apple/src/core/screenshot.ts | 28 ++++++++- 3 files changed, 126 insertions(+), 8 deletions(-) diff --git a/packages/platform-apple/src/core/__tests__/screenshot-boot-state-recovery.test.ts b/packages/platform-apple/src/core/__tests__/screenshot-boot-state-recovery.test.ts index 34c69ec8c1..62dc427741 100644 --- a/packages/platform-apple/src/core/__tests__/screenshot-boot-state-recovery.test.ts +++ b/packages/platform-apple/src/core/__tests__/screenshot-boot-state-recovery.test.ts @@ -1,6 +1,9 @@ import { beforeEach, test, vi } from 'vitest'; import assert from 'node:assert/strict'; +import { existsSync, readFileSync } from 'node:fs'; +import path from 'node:path'; import { bindTestCommandHost } from '@agent-device/test-kit'; +import { withDiagnosticsScope } from '@agent-device/host-kit/diagnostics'; import type { DeviceInfo } from '@agent-device/kernel/device'; import { AppError, createRequestCanceledError } from '@agent-device/kernel/errors'; import type { ExecResult } from '@agent-device/host-kit/command'; @@ -28,6 +31,7 @@ import { ensureBootedSimulator } from '../simulator.ts'; import { captureSimulatorScreenshotWithFallback } from '../screenshot.ts'; import { SIMCTL_SCREENSHOT_TIMEOUT_REASON } from '../tool-provider.ts'; import { IOS_SIMULATOR_SCREENSHOT_TIMEOUT_MS } from '../config.ts'; +import { mkdtempForTest } from '../../__tests__/tmp-dir.ts'; import { commandFailed, commandStdout, @@ -71,6 +75,7 @@ type RecoveryProbe = { captureAttempts: number; runnerCaptures: number; boots: number; + normalizations: number; }; /** @@ -94,6 +99,7 @@ async function probeRecovery( boot.mockResolvedValue(undefined); let captureAttempts = 0; let runnerCaptures = 0; + let normalizations = 0; const fallbackToRunner = options.shouldFallbackToRunner ?? (() => false); return await withScriptedCommands( @@ -107,15 +113,20 @@ async function probeRecovery( captureWithRetry: async () => { captureAttempts += 1; const failure = options.captureError; - throw typeof failure === 'function' - ? (failure as (attempt: number) => unknown)(captureAttempts) - : (failure ?? CAPTURE_FAILURE); + if (typeof failure === 'function') { + const error = (failure as (attempt: number) => unknown)(captureAttempts); + if (error !== undefined) throw error; + return; + } + throw failure ?? CAPTURE_FAILURE; }, captureWithRunner: async () => { runnerCaptures += 1; return undefined; }, - normalizeDensity: async () => {}, + normalizeDensity: async () => { + normalizations += 1; + }, resolveCaptureTarget: async () => ({}), shouldFallbackToRunner: fallbackToRunner, }, @@ -129,6 +140,7 @@ async function probeRecovery( captureAttempts, runnerCaptures, boots: boot.mock.calls.length, + normalizations, }; }, ); @@ -157,6 +169,43 @@ test('a fresh Shutdown answer boots the skipped-check simulator once and re-capt ); }); +test.each([ + { label: 'typed timeout', typedReason: SIMCTL_SCREENSHOT_TIMEOUT_REASON, code: 60 }, + { label: 'unattributed state failure', typedReason: undefined, code: 405 }, +])('successful recovery retains the original $label diagnostic', async ({ typedReason, code }) => { + const device = simulator(`sim-recovery-diagnostic-${code}`); + const stderr = `Detected file type from extension: PNG\nOriginal failure ${code}\n`; + const captureError = new AppError('COMMAND_FAILED', 'original capture message', { + stderr, + exitCode: code, + ...(typedReason ? { reason: typedReason } : {}), + }); + const logPath = path.join(await mkdtempForTest('ios-screenshot-recovery-diag-'), 'events.ndjson'); + const probe = await withDiagnosticsScope({ command: 'screenshot', debug: true, logPath }, () => + probeRecovery(device, { + state: () => listingFor(device.id, 'Shutdown'), + captureError: (attempt: number) => (attempt === 1 ? captureError : undefined), + }), + ); + assert.ok(existsSync(logPath), 'recovery must retain the discarded failure in diagnostics'); + const events = readFileSync(logPath, 'utf8') + .trim() + .split('\n') + .map((line) => JSON.parse(line) as { phase: string; data: Record }) + .filter((event) => event.phase === 'ios_screenshot_skipped_boot_recovery'); + + assert.equal(probe.error, undefined); + assert.equal(probe.boots, 1); + assert.equal(probe.captureAttempts, 2); + assert.equal(probe.normalizations, 1, 'the re-capture reaches successful normalization'); + assert.equal(events.length, 1); + assert.equal(events[0]?.data.observedState, 'Shutdown'); + assert.equal(events[0]?.data.recoveryAuthorized, true); + assert.equal(events[0]?.data.stderr, stderr.trim(), 'diagnostics normalize outer whitespace'); + assert.equal(events[0]?.data.reason, 'original capture message'); + assert.equal(events[0]?.data.captureFailureReason, typedReason); +}); + test('the re-capture that fails again reports its own failure and adds no second recovery', async () => { const device = simulator('sim-recover-recapture-fails'); const recaptureFailure = new AppError('COMMAND_FAILED', 'xcrun exited with code 71', { diff --git a/packages/platform-apple/src/core/__tests__/screenshot-simctl-protocol.test.ts b/packages/platform-apple/src/core/__tests__/screenshot-simctl-protocol.test.ts index 9cd3a481d0..200cd3d96e 100644 --- a/packages/platform-apple/src/core/__tests__/screenshot-simctl-protocol.test.ts +++ b/packages/platform-apple/src/core/__tests__/screenshot-simctl-protocol.test.ts @@ -1,6 +1,9 @@ import { test } from 'vitest'; import assert from 'node:assert/strict'; +import { readFileSync } from 'node:fs'; +import path from 'node:path'; import { bindTestCommandHost } from '@agent-device/test-kit'; +import { withDiagnosticsScope } from '@agent-device/host-kit/diagnostics'; import { AppError } from '@agent-device/kernel/errors'; import type { DeviceInfo } from '@agent-device/kernel/device'; import type { ExecResult } from '@agent-device/host-kit/command'; @@ -14,7 +17,11 @@ import { SIMCTL_SCREENSHOT_TIMEOUT_REASON, } from '../tool-provider.ts'; import { buildSimctlArgsForDevice } from '../simctl.ts'; -import { shouldRetryIosSimulatorScreenshot } from '../screenshot.ts'; +import { + captureSimulatorScreenshotWithRetry, + shouldRetryIosSimulatorScreenshot, +} from '../screenshot.ts'; +import { mkdtempForTest } from '../../__tests__/tmp-dir.ts'; import { commandFailed, commandStdout, @@ -130,6 +137,46 @@ test.each(['\n', '\r\n'])( }, ); +test.each([ + { message: 'changed provider wording', typedReason: 'capture-provider-refused' }, + { message: 'capture-provider-refused', typedReason: undefined }, +])('retry telemetry preserves typed evidence for $message', async ({ message, typedReason }) => { + const failure = new AppError( + 'COMMAND_FAILED', + message, + typedReason ? { reason: typedReason } : {}, + ); + const logPath = path.join(await mkdtempForTest('ios-screenshot-retry-diag-'), 'events.ndjson'); + await withDiagnosticsScope({ command: 'screenshot', debug: true, logPath }, () => + withAppleToolProvider(createLocalAppleToolProvider(), () => + withScriptedCommands( + () => { + throw failure; + }, + () => + assert.rejects( + captureSimulatorScreenshotWithRetry(SIMULATOR, '/tmp/out.png', undefined), + (error: unknown) => error === failure, + ), + ), + ), + ); + const events = readFileSync(logPath, 'utf8') + .trim() + .split('\n') + .map((line) => JSON.parse(line) as { phase: string; data: Record }) + .filter((event) => event.phase === 'retry' && event.data.phase === 'ios_simulator_screenshot'); + const failed = events.filter((event) => event.data.event === 'attempt_failed'); + + assert.equal(failed.length, 1); + assert.equal(failed[0]?.data.attempt, 1); + assert.equal(failed[0]?.data.reason, typedReason); + assert.equal( + events.some((event) => event.data.event === 'retry_scheduled'), + false, + ); +}); + test('the adapter accepts a leading protocol header with CRLF line endings', async () => { const { error } = await captureScreenshot(() => commandFailed(protocolTimeout().replaceAll('\n', '\r\n'), 60), diff --git a/packages/platform-apple/src/core/screenshot.ts b/packages/platform-apple/src/core/screenshot.ts index 49a562dce1..bc2649a94d 100644 --- a/packages/platform-apple/src/core/screenshot.ts +++ b/packages/platform-apple/src/core/screenshot.ts @@ -191,7 +191,7 @@ export async function captureSimulatorScreenshotWithFallback( // The probe answers from the tool's state listing, so a probe that itself got canceled stays // terminal rather than becoming an unknown state; anything else it cannot read keeps the // capture's own failure, unchanged, as the answer the caller sees. - return await observesSimulatorShutdown(device, options.runnerOptions?.signal); + return await observesSimulatorShutdown(device, error, options.runnerOptions?.signal); }; const captureWithFallback = async (): Promise => { @@ -268,7 +268,11 @@ export async function captureSimulatorScreenshotWithRetry( jitter: 0.2, shouldRetry: (error) => shouldRetryIosSimulatorScreenshot(error), }, - { deadline, phase: 'ios_simulator_screenshot' }, + { + deadline, + phase: 'ios_simulator_screenshot', + classifyReason: readSimulatorScreenshotFailureReason, + }, ); } @@ -476,6 +480,11 @@ export function shouldRetryIosSimulatorScreenshot(error: unknown): boolean { ); } +function readSimulatorScreenshotFailureReason(error: unknown): string | undefined { + const reason = error instanceof AppError ? error.details?.reason : undefined; + return typeof reason === 'string' ? reason : undefined; +} + /** * Whether this simulator is turned off right now, read from the tool's own state listing under the * screenshot's own probe ceiling. Only the literal {@link SIMCTL_SHUTDOWN_STATE} authorizes a boot: @@ -487,6 +496,7 @@ export function shouldRetryIosSimulatorScreenshot(error: unknown): boolean { */ async function observesSimulatorShutdown( device: DeviceInfo, + captureError: unknown, signal?: AbortSignal, ): Promise { signal?.throwIfAborted(); @@ -501,7 +511,19 @@ async function observesSimulatorShutdown( return false; } signal?.throwIfAborted(); - return state === SIMCTL_SHUTDOWN_STATE; + const recoveryAuthorized = state === SIMCTL_SHUTDOWN_STATE; + emitDiagnostic({ + level: 'info', + phase: 'ios_screenshot_skipped_boot_recovery', + data: { + udid: device.id, + observedState: state, + recoveryAuthorized, + ...extractAppleToolErrorMeta(captureError), + captureFailureReason: readSimulatorScreenshotFailureReason(captureError), + }, + }); + return recoveryAuthorized; } async function normalizeIosSimulatorScreenshotDensity( From d4bc0556139fa4078b4a79a28b81fdb493655dbb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 14 Nov 2026 16:11:37 +0100 Subject: [PATCH 10/10] fix(apple): make screenshot probe failures observable --- .../screenshot-boot-state-recovery.test.ts | 119 ++++++++++++++---- .../__tests__/scripted-command-executor.ts | 7 +- .../platform-apple/src/core/screenshot.ts | 12 +- packages/platform-apple/src/core/simulator.ts | 9 +- 4 files changed, 112 insertions(+), 35 deletions(-) diff --git a/packages/platform-apple/src/core/__tests__/screenshot-boot-state-recovery.test.ts b/packages/platform-apple/src/core/__tests__/screenshot-boot-state-recovery.test.ts index 62dc427741..ba975902f7 100644 --- a/packages/platform-apple/src/core/__tests__/screenshot-boot-state-recovery.test.ts +++ b/packages/platform-apple/src/core/__tests__/screenshot-boot-state-recovery.test.ts @@ -155,6 +155,15 @@ beforeEach(() => { vi.mocked(ensureBootedSimulator).mockResolvedValue(undefined); }); +test.each([ + { args: ['simctl', 'list', 'devices', '-j'], isStateRead: true }, + { args: ['simctl', '--set', '/tmp/simulator-set', 'list', 'devices', '-j'], isStateRead: true }, + { args: ['simctl', 'list', '-j'], isStateRead: false }, + { args: ['simctl', 'list', 'runtimes', '-j'], isStateRead: false }, +])('classifies the state read separately from inventory: $args', ({ args, isStateRead }) => { + assert.equal(isSimctlListDevices({ cmd: 'xcrun', args, options: {} }), isStateRead); +}); + test('a fresh Shutdown answer boots the skipped-check simulator once and re-captures once', async () => { const device = simulator('sim-recover-shutdown'); const probe = await probeRecovery(device, { state: () => listingFor(device.id, 'Shutdown') }); @@ -199,6 +208,8 @@ test.each([ assert.equal(probe.captureAttempts, 2); assert.equal(probe.normalizations, 1, 'the re-capture reaches successful normalization'); assert.equal(events.length, 1); + assert.equal(events[0]?.data.deviceId, device.id); + assert.equal(events[0]?.data.udid, undefined); assert.equal(events[0]?.data.observedState, 'Shutdown'); assert.equal(events[0]?.data.recoveryAuthorized, true); assert.equal(events[0]?.data.stderr, stderr.trim(), 'diagnostics normalize outer whitespace'); @@ -263,26 +274,68 @@ test('an unreadable, unlisted or stateless listing cannot authorize a boot', asy } }); -test('a state read that itself fails keeps the capture failure and its diagnostics', async () => { - const device = simulator('sim-recover-probe-throws'); - const probe = await probeRecovery(device, { - state: () => { - throw new Error('simctl list devices -j could not be spawned'); - }, - }); - - assert.equal(probe.error, CAPTURE_FAILURE, 'a failed probe never replaces the capture failure'); - assert.equal(probe.boots, 0); - assert.equal(probe.captureAttempts, 1); - assert.ok(probe.error instanceof AppError); - assert.equal(probe.error.details?.exitCode, 60); - assert.equal(probe.error.details?.processExitError, true); - assert.equal( - typeof probe.error.details?.hint, - 'string', - 'the hint the producer attached is preserved', - ); -}); +test.each([ + { + label: 'spawn failure', + failure: new Error('simctl list devices -j could not be spawned'), + reason: undefined, + }, + { + label: 'typed deadline', + failure: new AppError('COMMAND_FAILED', 'probe deadline reached', { + reason: 'probe-deadline', + timeoutMs: 5_000, + stderr: 'probe stderr', + }), + reason: 'probe-deadline', + }, +])( + 'a state read $label keeps the capture failure and records the probe error', + async ({ failure, reason }) => { + const device = simulator('sim-recover-probe-throws'); + const logPath = path.join( + await mkdtempForTest('ios-screenshot-probe-failure-'), + 'events.ndjson', + ); + const probe = await withDiagnosticsScope({ command: 'screenshot', debug: true, logPath }, () => + probeRecovery(device, { + state: () => { + throw failure; + }, + }), + ); + + assert.equal(probe.error, CAPTURE_FAILURE, 'a failed probe never replaces the capture failure'); + assert.equal(probe.boots, 0); + assert.equal(probe.captureAttempts, 1); + assert.ok(probe.error instanceof AppError); + assert.equal(probe.error.details?.exitCode, 60); + assert.equal(probe.error.details?.processExitError, true); + assert.equal( + typeof probe.error.details?.hint, + 'string', + 'the hint the producer attached is preserved', + ); + assert.ok(existsSync(logPath), 'a failed probe records its diagnostic'); + const events = readFileSync(logPath, 'utf8') + .trim() + .split('\n') + .filter(Boolean) + .map((line) => JSON.parse(line) as { phase: string; data: Record }); + const failures = events.filter( + (event) => event.phase === 'ios_screenshot_boot_state_probe_failed', + ); + assert.equal(failures.length, 1); + assert.equal(failures[0]?.data.deviceId, device.id); + assert.equal(failures[0]?.data.recoveryAuthorized, false); + assert.equal(failures[0]?.data.reason, failure.message); + assert.equal(failures[0]?.data.probeFailureReason, reason); + assert.equal( + events.some((event) => event.phase === 'ios_screenshot_skipped_boot_recovery'), + false, + ); + }, +); test('the five-second recovery probe stays below the capture budget', async () => { const device = simulator('sim-recover-budget'); @@ -335,16 +388,30 @@ test('a cancellation that arrives with the capture failure is not treated as an test('a cancellation raised by the probe travels on instead of answering no', async () => { const device = simulator('sim-recover-probe-canceled'); const cancellation = createRequestCanceledError({ cmd: 'xcrun' }); - const probe = await probeRecovery(device, { - captureError: CAPTURE_FAILURE, - state: () => { - throw cancellation; - }, - }); + const logPath = path.join(await mkdtempForTest('ios-screenshot-probe-cancel-'), 'events.ndjson'); + const probe = await withDiagnosticsScope({ command: 'screenshot', debug: true, logPath }, () => + probeRecovery(device, { + captureError: CAPTURE_FAILURE, + state: () => { + throw cancellation; + }, + }), + ); assert.equal(probe.error, cancellation, 'the probe must not swallow a cancellation'); assert.equal(probe.boots, 0); assert.equal(probe.captureAttempts, 1); + const events = existsSync(logPath) + ? readFileSync(logPath, 'utf8') + .trim() + .split('\n') + .filter(Boolean) + .map((line) => JSON.parse(line) as { phase: string }) + : []; + assert.equal( + events.some((event) => event.phase === 'ios_screenshot_boot_state_probe_failed'), + false, + ); }); test('a capture that did not skip the boot check never probes the state', async () => { diff --git a/packages/platform-apple/src/core/__tests__/scripted-command-executor.ts b/packages/platform-apple/src/core/__tests__/scripted-command-executor.ts index 5d4422de43..31290b2bf3 100644 --- a/packages/platform-apple/src/core/__tests__/scripted-command-executor.ts +++ b/packages/platform-apple/src/core/__tests__/scripted-command-executor.ts @@ -61,7 +61,12 @@ export function commandFailed(stderr: string, exitCode: number, stdout = ''): Ex /** Whether one recorded command is the `simctl list devices -j` boot-state read. */ export function isSimctlListDevices(call: ScriptedCommandCall): boolean { - return call.args[0] === 'simctl' && call.args.includes('list') && call.args.includes('-j'); + return ( + call.args[0] === 'simctl' && + call.args.includes('list') && + call.args.includes('devices') && + call.args.includes('-j') + ); } /** Whether one recorded command is this simulator's screenshot capture: `simctl [--set …] io screenshot …`. */ diff --git a/packages/platform-apple/src/core/screenshot.ts b/packages/platform-apple/src/core/screenshot.ts index bc2649a94d..bfb3809faf 100644 --- a/packages/platform-apple/src/core/screenshot.ts +++ b/packages/platform-apple/src/core/screenshot.ts @@ -508,6 +508,16 @@ async function observesSimulatorShutdown( }); } catch (error) { if (isRequestCanceledError(error)) throw error; + emitDiagnostic({ + level: 'warn', + phase: 'ios_screenshot_boot_state_probe_failed', + data: { + deviceId: device.id, + recoveryAuthorized: false, + ...extractAppleToolErrorMeta(error), + probeFailureReason: readSimulatorScreenshotFailureReason(error), + }, + }); return false; } signal?.throwIfAborted(); @@ -516,7 +526,7 @@ async function observesSimulatorShutdown( level: 'info', phase: 'ios_screenshot_skipped_boot_recovery', data: { - udid: device.id, + deviceId: device.id, observedState: state, recoveryAuthorized, ...extractAppleToolErrorMeta(captureError), diff --git a/packages/platform-apple/src/core/simulator.ts b/packages/platform-apple/src/core/simulator.ts index cc7e0b2b3d..c4cc6fec97 100644 --- a/packages/platform-apple/src/core/simulator.ts +++ b/packages/platform-apple/src/core/simulator.ts @@ -181,13 +181,8 @@ export async function ensureBootedSimulator( } /** - * The one boot-state read: `simctl list devices -j` answered through the listing's typed `state` - * field. `null` means the listing failed or omits this simulator, which is never a state. - * - * The caller names the ceiling. The boot path can afford the inventory budget; a caller that only - * wants to know whether it may boot after its own failed command bounds the same read to itself. - * This read does not consult the boot memo: it is the fresh observation, and the memo is written by - * the owners that make one. + * Reads fresh simctl state within the caller's budget. + * Unknown state returns null; process timeouts and cancellation throw. */ export async function readSimulatorBootState( device: DeviceInfo,