Skip to content

Commit 68d9ed9

Browse files
committed
fix(wait): report readiness work that consumed the wait budget
A wait whose deadline cancels a poll while the iOS XCTest runner is still starting, or while the Simulator app is still being discovered, now fails with wait_readiness_exhausted and details.readinessPhase instead of wait_capture_stalled. The platform names the phase on the cancellation it throws; the wait classifies the cancelled poll as readiness. Refs #2343
1 parent dc9ab86 commit 68d9ed9

9 files changed

Lines changed: 295 additions & 32 deletions

File tree

‎packages/contracts/src/wait.ts‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,9 @@
66
* `wait_capture_stalled` means no readable capture established an observation
77
* before the deadline and is retriable. `wait_deadline_exceeded` means a later
88
* capture consumed the remaining budget after at least one readable capture.
9+
* `wait_readiness_exhausted` means the deadline cancelled a poll that was still
10+
* making the target observable; `details.readinessPhase` names the work, and
11+
* `wait_runner_restart_exhausted` is the same verdict for a runner restart.
912
* `wait_target_absent` is the ordinary timeout reason for a selector that was
1013
* never found. `wait_target_present` is the strict-absence timeout reason when
1114
* valid captures still contain matches. The remaining reasons describe
@@ -15,6 +18,7 @@ export const WAIT_REASONS = {
1518
captureStalled: 'wait_capture_stalled',
1619
deadlineExceeded: 'wait_deadline_exceeded',
1720
runnerRestartExhausted: 'wait_runner_restart_exhausted',
21+
readinessExhausted: 'wait_readiness_exhausted',
1822
targetAbsent: 'wait_target_absent',
1923
targetPresent: 'wait_target_present',
2024
stableTimeout: 'wait_stable_timeout',
@@ -23,6 +27,26 @@ export const WAIT_REASONS = {
2327

2428
export type WaitReason = (typeof WAIT_REASONS)[keyof typeof WAIT_REASONS];
2529

30+
/**
31+
* Work a platform does before it can observe the target at all: starting the Apple XCTest runner,
32+
* or discovering the Simulator app process the host AX bridge reads. A platform cancelled during
33+
* that work names it on the error it throws, through {@link readinessPhaseDetails}.
34+
*/
35+
const READINESS_PHASES = ['runner-start', 'target-discovery'] as const;
36+
37+
export type ReadinessPhase = (typeof READINESS_PHASES)[number];
38+
39+
export function readinessPhaseDetails(phase: ReadinessPhase): { readinessPhase: ReadinessPhase } {
40+
return { readinessPhase: phase };
41+
}
42+
43+
export function readinessPhaseOf(
44+
details: Readonly<Record<string, unknown>> | undefined,
45+
): ReadinessPhase | undefined {
46+
const phase = details?.readinessPhase;
47+
return READINESS_PHASES.find((candidate) => candidate === phase);
48+
}
49+
2650
/**
2751
* Public daemon result for `wait`. The runtime-local result carries a `kind`
2852
* discriminant, but `toDaemonWaitData` intentionally projects the normal daemon

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

Lines changed: 63 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
import assert from 'node:assert/strict';
22
import { afterEach, beforeEach, expect, test, vi } from 'vitest';
3-
import { AppError } from '@agent-device/kernel/errors';
3+
import http from 'node:http';
4+
import type { AddressInfo } from 'node:net';
5+
import { AppError, createRequestCanceledError } from '@agent-device/kernel/errors';
46
import { resetAllProcessMemosForTests } from '@agent-device/kernel/ttl-memo';
57
import { IOS_SIMULATOR } from './device-fixtures.ts';
68
import type { ExecResult } from '@agent-device/host-kit/command';
@@ -220,6 +222,66 @@ test('a failed restart preserves the invalidated runner evidence', async () => {
220222
}
221223
});
222224

225+
// A runner that has not answered yet is readiness work, not observation: a caller whose deadline
226+
// lands there needs to know the start consumed it, so the cancellation names the phase (#2343).
227+
test('a cancellation during a runner start names the start as the readiness phase', async () => {
228+
const unanswered = await startFakeRunnerServer([]);
229+
await unanswered.close();
230+
const starting = { ...makeRunnerSession(unanswered.port), state: 'starting' as const };
231+
ensureRunnerSessionMock.mockResolvedValue(starting);
232+
const controller = new AbortController();
233+
setTimeout(() => controller.abort(), 50);
234+
235+
await expect(
236+
runAppleRunnerCommand(IOS_SIMULATOR, { command: 'snapshot' }, { signal: controller.signal }),
237+
).rejects.toMatchObject({
238+
details: { reason: 'request_canceled', readinessPhase: 'runner-start' },
239+
});
240+
expect(invalidateRunnerSessionMock).toHaveBeenCalledWith(
241+
starting,
242+
'runner_startup_request_canceled',
243+
);
244+
});
245+
246+
test('a cancellation before any runner session exists names the start as the readiness phase', async () => {
247+
ensureRunnerSessionMock.mockImplementation(
248+
async (_device: unknown, options: { signal?: AbortSignal }) =>
249+
await new Promise((_resolve, reject) => {
250+
options.signal?.addEventListener('abort', () => reject(createRequestCanceledError()), {
251+
once: true,
252+
});
253+
}),
254+
);
255+
const controller = new AbortController();
256+
setTimeout(() => controller.abort(), 20);
257+
258+
await expect(
259+
runAppleRunnerCommand(IOS_SIMULATOR, { command: 'snapshot' }, { signal: controller.signal }),
260+
).rejects.toMatchObject({ details: { readinessPhase: 'runner-start' } });
261+
});
262+
263+
test('a cancellation of a command on a ready runner is not readiness work', async () => {
264+
const silent = http.createServer(() => {});
265+
await new Promise<void>((resolve) => silent.listen(0, '127.0.0.1', resolve));
266+
try {
267+
seedSession((silent.address() as AddressInfo).port);
268+
const controller = new AbortController();
269+
setTimeout(() => controller.abort(), 50);
270+
271+
const command = runAppleRunnerCommand(
272+
IOS_SIMULATOR,
273+
{ command: 'snapshot' },
274+
{ signal: controller.signal },
275+
);
276+
277+
await expect(command).rejects.toMatchObject({ details: { reason: 'request_canceled' } });
278+
await expect(command).rejects.not.toHaveProperty('details.readinessPhase');
279+
} finally {
280+
silent.closeAllConnections();
281+
await new Promise<void>((resolve) => silent.close(() => resolve()));
282+
}
283+
});
284+
223285
test('an exact-session command never dispatches to a replacement runner', async () => {
224286
server = await startFakeRunnerServer({ recordStop: [{ kind: 'ok', data: {} }] });
225287
const replacement = seedSession(server.port);

‎packages/platform-apple/src/runner/runner-lifecycle.ts‎

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,11 @@
1-
import { AppError, asAppError, isRequestCanceledError } from '@agent-device/kernel/errors';
1+
import {
2+
AppError,
3+
asAppError,
4+
createRequestCanceledError,
5+
isRequestCanceledError,
6+
} from '@agent-device/kernel/errors';
27
import type { DeviceInfo } from '@agent-device/kernel/device';
8+
import { readinessPhaseDetails } from '@agent-device/contracts/wait';
39
import { emitDiagnostic } from './host.ts';
410
import { RUNNER_STARTUP_TIMEOUT_MS } from './runner-startup-transport.ts';
511
import { RUNNER_COMMAND_TIMEOUT_MS } from './runner-transport.ts';
@@ -265,13 +271,13 @@ export async function executeRunnerCommand(
265271
const recycleKey = runnerRecycleLedgerKey(options, command);
266272
let session: RunnerSession | undefined;
267273
let recycleBootBegun = false;
274+
const liveness = readRunnerSessionLiveness(device.id)?.liveness ?? 'gone';
268275
try {
269276
// A request that already used a runner session and finds no runner process is about to pay
270277
// for a recycle boot (~25s): bound that to the per-request recycle budget so a hostile screen
271278
// fails fast with a preserved session instead of stacking runner boots (#1105).
272279
// `gone` and `stopped` are the two liveness answers that mean no runner is answering now, so
273280
// this command is the one that would start a process (#2662).
274-
const liveness = readRunnerSessionLiveness(device.id)?.liveness ?? 'gone';
275281
if (
276282
(liveness === 'gone' || liveness === 'stopped') &&
277283
hasRunnerRequestTouchedSession(recycleKey)
@@ -301,9 +307,15 @@ export async function executeRunnerCommand(
301307
} catch (error) {
302308
if (options.expectedRunnerSessionId !== undefined) throw error;
303309
const appErr = asAppError(error, 'COMMAND_FAILED');
304-
if (session && session.state === 'starting' && isRequestCanceledError(appErr)) {
305-
await invalidateRunnerSessionBestEffort(session, 'runner_startup_request_canceled');
306-
throw error;
310+
const runnerStarting = session ? session.state === 'starting' : liveness !== 'ready';
311+
if (runnerStarting && isRequestCanceledError(appErr)) {
312+
if (session) {
313+
await invalidateRunnerSessionBestEffort(session, 'runner_startup_request_canceled');
314+
}
315+
throw createRequestCanceledError(
316+
{ ...appErr.details, ...readinessPhaseDetails('runner-start') },
317+
appErr,
318+
);
307319
}
308320
if (shouldRestartRunnerBeforeCommandSend(appErr) && session) {
309321
assertRunnerRequestActive(options.requestId);

‎packages/platform-apple/src/snapshot-route.test.ts‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -783,3 +783,51 @@ test('a slow app discovery keeps observation on the bridge while no runner can a
783783
vi.useRealTimers();
784784
}
785785
});
786+
787+
test('a deadline during a slow app discovery names the discovery as the readiness phase', async () => {
788+
// The capture never reached the bridge or the runner: its whole cost was finding the target, so
789+
// the cancellation says so instead of reading as a capture that produced nothing (#2343).
790+
const run = vi.fn(async (args: string[]) => {
791+
if (args[0] === 'spawn') await new Promise<never>(() => {});
792+
return {
793+
stdout: JSON.stringify({
794+
devices: { 'com.apple.CoreSimulator.SimRuntime.iOS-26-0': [{ udid: ios.id }] },
795+
}),
796+
stderr: '',
797+
exitCode: 0,
798+
};
799+
});
800+
const runCommand = vi.fn(async () => ({ stdout: 'start-a', stderr: '', exitCode: 0 }));
801+
const fallback = vi.fn(async () => runnerResult());
802+
const baseHost = platformRuntimeHostFixture();
803+
const route = createAppleSnapshotRoute(
804+
{
805+
...baseHost,
806+
appleApplications: { ...baseHost.appleApplications, hasLiveRunnerSession: async () => false },
807+
},
808+
{
809+
source: sourceReturning(bridgeAcquisition()),
810+
resolveTarget: createSimulatorSnapshotTargetResolver(),
811+
},
812+
);
813+
const deadline = new AbortController();
814+
vi.useFakeTimers();
815+
try {
816+
await withAppleToolProvider(
817+
createLocalAppleToolProvider({ simctl: { run }, runCommand }),
818+
async () => {
819+
const capture = route.capture(ios, input, deadline.signal, fallback);
820+
const settled = expect(capture).rejects.toMatchObject({
821+
code: 'COMMAND_FAILED',
822+
details: { reason: 'request_canceled', readinessPhase: 'target-discovery' },
823+
});
824+
await vi.advanceTimersByTimeAsync(3_000);
825+
deadline.abort(new DOMException('Wait deadline exceeded', 'TimeoutError'));
826+
await settled;
827+
expect(fallback).not.toHaveBeenCalled();
828+
},
829+
);
830+
} finally {
831+
vi.useRealTimers();
832+
}
833+
});

‎packages/platform-apple/src/snapshot-route.ts‎

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,8 @@ import {
1616
deriveIosCaptureHint,
1717
} from '@agent-device/capture-kit/ios-snapshot-planning';
1818
import { emitDiagnostic, withDiagnosticTimer } from '@agent-device/host-kit/diagnostics';
19-
import { AppError } from '@agent-device/kernel/errors';
19+
import { AppError, createRequestCanceledError } from '@agent-device/kernel/errors';
20+
import { readinessPhaseDetails } from '@agent-device/contracts/wait';
2021
import type { DeviceInfo } from '@agent-device/kernel/device';
2122
import {
2223
createSimulatorSnapshotSource,
@@ -140,7 +141,7 @@ export function createAppleSnapshotRoute(
140141
try {
141142
target = await resolveTargetForObservation(host, resolveTarget, device, input, signal);
142143
} catch (error) {
143-
signal.throwIfAborted();
144+
throwIfTargetResolutionCancelled(signal);
144145
emitRouteDiagnostic('target-resolution-failed', device, undefined, error);
145146
return await runFallback(
146147
device.id,
@@ -247,6 +248,15 @@ async function resolveTargetForObservation(
247248
}
248249
}
249250

251+
/**
252+
* A capture cancelled before its target was resolved never reached the bridge or the runner, so the
253+
* cancellation names the readiness work that consumed it rather than reading as a failed capture.
254+
*/
255+
function throwIfTargetResolutionCancelled(signal: AbortSignal): void {
256+
if (!signal.aborted) return;
257+
throw createRequestCanceledError(readinessPhaseDetails('target-discovery'), signal.reason);
258+
}
259+
250260
function isEligible(device: DeviceInfo, input: CaptureSnapshotInput): boolean {
251261
return (
252262
device.platform === 'apple' &&

‎src/commands/interaction/runtime/wait-absent.ts‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -88,10 +88,11 @@ export async function waitForAbsent<Runtime extends SelectorWaitRuntime>(
8888
await polling.sleepUntilNextPoll();
8989
}
9090

91-
// A runner restart is the authoritative deadline cause even when an earlier
92-
// readable poll saw the target. Returning stale target-present evidence would
93-
// hide the retriable restart and make callers stop retrying the wrong reason.
94-
if (deadline === 'runner-restart-exhausted') {
91+
// A runner restart or unfinished readiness is the authoritative deadline cause
92+
// even when an earlier readable poll saw the target. Returning stale
93+
// target-present evidence would hide the retriable cause and make callers stop
94+
// retrying for the wrong reason.
95+
if (deadline === 'runner-restart-exhausted' || deadline === 'readiness-exhausted') {
9596
throw waitTimeoutError(
9697
`wait absent timed out for selector: ${selectorExpression}`,
9798
polling,

0 commit comments

Comments
 (0)