Skip to content

Commit 3e5af3a

Browse files
authored
fix(wait): report readiness work that consumed the wait budget (#2893)
* fix(wait): report readiness work that consumed the wait budget A wait whose deadline cancels a poll while the iOS XCTest runner is still starting, or while the Simulator app is still being discovered, now fails with wait_readiness_exhausted and details.readinessPhase instead of wait_capture_stalled. The platform names the phase on the cancellation it throws; the wait classifies the cancelled poll as readiness. Refs #2343 * fix(wait): tag only running discovery as readiness and keep platform imports type-only * fix(wait): keep an earlier retriable refusal ahead of the readiness verdict * test(ios): type the route test tool mocks against readonly simctl args * refactor(ios): name the route's cancelled target-resolution rethrow * test(ios): pin the resolver's discovery and re-check cancellations
1 parent 4260aa7 commit 3e5af3a

11 files changed

Lines changed: 519 additions & 50 deletions

File tree

‎packages/contracts/src/wait.ts‎

Lines changed: 20 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,22 @@ 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. Only the code doing that work
33+
* at the moment of cancellation names it, as `details.readinessPhase` on the error it throws.
34+
*/
35+
const READINESS_PHASES = ['runner-start', 'target-discovery'] as const;
36+
37+
export type ReadinessPhase = (typeof READINESS_PHASES)[number];
38+
39+
export function readinessPhaseOf(
40+
details: Readonly<Record<string, unknown>> | undefined,
41+
): ReadinessPhase | undefined {
42+
const phase = details?.readinessPhase;
43+
return READINESS_PHASES.find((candidate) => candidate === phase);
44+
}
45+
2646
/**
2747
* Public daemon result for `wait`. The runtime-local result carries a `kind`
2848
* 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: 20 additions & 6 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 type { ReadinessPhase } 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,15 +271,15 @@ export async function executeRunnerCommand(
265271
const recycleKey = runnerRecycleLedgerKey(options, command);
266272
let session: RunnerSession | undefined;
267273
let recycleBootBegun = false;
274+
const livenessAtEntry = 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 (
276-
(liveness === 'gone' || liveness === 'stopped') &&
282+
(livenessAtEntry === 'gone' || livenessAtEntry === 'stopped') &&
277283
hasRunnerRequestTouchedSession(recycleKey)
278284
) {
279285
if (!tryBeginRunnerRecycle(recycleKey)) {
@@ -301,9 +307,17 @@ 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 runnerNeverAnswered = session
311+
? session.state === 'starting'
312+
: livenessAtEntry !== 'ready';
313+
if (runnerNeverAnswered && isRequestCanceledError(appErr)) {
314+
if (session) {
315+
await invalidateRunnerSessionBestEffort(session, 'runner_startup_request_canceled');
316+
}
317+
throw createRequestCanceledError(
318+
{ ...appErr.details, readinessPhase: 'runner-start' satisfies ReadinessPhase },
319+
appErr,
320+
);
307321
}
308322
if (shouldRestartRunnerBeforeCommandSend(appErr) && session) {
309323
assertRunnerRequestActive(options.requestId);

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

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
import { expect, test, vi } from 'vitest';
22
import type { DeviceInfo } from '@agent-device/kernel/device';
3+
import { createRequestCanceledError } from '@agent-device/kernel/errors';
34

45
// Keep the route tests hermetic: the default system-surface presence probe shells out to `ps`, which
56
// never resolves under the fake timers these tests drive. Tests that exercise the bypass inject
@@ -783,3 +784,130 @@ test('a slow app discovery keeps observation on the bridge while no runner can a
783784
vi.useRealTimers();
784785
}
785786
});
787+
788+
test.for(['rejects', 'exits'] as const)(
789+
'a deadline during the cached target re-check is not readiness work (ps %s)',
790+
async (psOnAbort) => {
791+
// A known target is re-checked with one `ps` per capture; no discovery runs. A deadline that
792+
// lands there must stay a plain cancellation, or a wait would report readiness exhaustion over
793+
// evidence its earlier polls already gathered (#2343 review).
794+
const run = vi.fn(async (args: readonly string[]) => ({
795+
stdout:
796+
args[0] === 'spawn'
797+
? `42\t0\tUIKitApplication:${input.options.appBundleId}[launch-a][rb-legacy]`
798+
: JSON.stringify({
799+
devices: { 'com.apple.CoreSimulator.SimRuntime.iOS-26-0': [{ udid: ios.id }] },
800+
}),
801+
stderr: '',
802+
exitCode: 0,
803+
}));
804+
let recheckStarted!: () => void;
805+
const recheck = new Promise<void>((resolve) => {
806+
recheckStarted = resolve;
807+
});
808+
let psCalls = 0;
809+
const runCommand = vi.fn(
810+
async (cmd: string, args: readonly string[], options?: { signal?: AbortSignal }) => {
811+
if (cmd !== 'ps' || ++psCalls === 1) return { stdout: 'start-a', stderr: '', exitCode: 0 };
812+
recheckStarted();
813+
return await new Promise<{ stdout: string; stderr: string; exitCode: number }>(
814+
(resolve, reject) => {
815+
options?.signal?.addEventListener(
816+
'abort',
817+
() =>
818+
psOnAbort === 'rejects'
819+
? reject(createRequestCanceledError({ cmd, args }))
820+
: resolve({ stdout: '', stderr: '', exitCode: 1 }),
821+
{ once: true },
822+
);
823+
},
824+
);
825+
},
826+
);
827+
const fallback = vi.fn(async () => runnerResult());
828+
const baseHost = platformRuntimeHostFixture();
829+
const route = createAppleSnapshotRoute(
830+
{
831+
...baseHost,
832+
appleApplications: {
833+
...baseHost.appleApplications,
834+
hasLiveRunnerSession: async () => false,
835+
},
836+
snapshot: {
837+
captureSurface: vi.fn(),
838+
presentIosAcquisition: vi.fn(async () => ({
839+
backend: 'xctest' as const,
840+
producer: 'simulator-ax-bridge' as const,
841+
nodes: [{ index: 0, type: 'Application' }],
842+
})),
843+
},
844+
},
845+
{
846+
source: sourceReturning(bridgeAcquisition()),
847+
resolveTarget: createSimulatorSnapshotTargetResolver(),
848+
},
849+
);
850+
await withAppleToolProvider(
851+
createLocalAppleToolProvider({ simctl: { run }, runCommand }),
852+
async () => {
853+
await route.capture(ios, input, signal(), fallback);
854+
const deadline = new AbortController();
855+
const capture = route.capture(ios, input, deadline.signal, fallback);
856+
await recheck;
857+
deadline.abort(new DOMException('Wait deadline exceeded', 'TimeoutError'));
858+
859+
await expect(capture).rejects.not.toHaveProperty('details.readinessPhase');
860+
expect(run.mock.calls.filter(([args]) => args[0] === 'spawn')).toHaveLength(1);
861+
expect(fallback).not.toHaveBeenCalled();
862+
},
863+
);
864+
},
865+
);
866+
867+
test('a deadline during a slow app discovery names the discovery as the readiness phase', async () => {
868+
// The capture never reached the bridge or the runner: its whole cost was finding the target, so
869+
// the cancellation says so instead of reading as a capture that produced nothing (#2343).
870+
const run = vi.fn(async (args: readonly string[]) => {
871+
if (args[0] === 'spawn') await new Promise<never>(() => {});
872+
return {
873+
stdout: JSON.stringify({
874+
devices: { 'com.apple.CoreSimulator.SimRuntime.iOS-26-0': [{ udid: ios.id }] },
875+
}),
876+
stderr: '',
877+
exitCode: 0,
878+
};
879+
});
880+
const runCommand = vi.fn(async () => ({ stdout: 'start-a', stderr: '', exitCode: 0 }));
881+
const fallback = vi.fn(async () => runnerResult());
882+
const baseHost = platformRuntimeHostFixture();
883+
const route = createAppleSnapshotRoute(
884+
{
885+
...baseHost,
886+
appleApplications: { ...baseHost.appleApplications, hasLiveRunnerSession: async () => false },
887+
},
888+
{
889+
source: sourceReturning(bridgeAcquisition()),
890+
resolveTarget: createSimulatorSnapshotTargetResolver(),
891+
},
892+
);
893+
const deadline = new AbortController();
894+
vi.useFakeTimers();
895+
try {
896+
await withAppleToolProvider(
897+
createLocalAppleToolProvider({ simctl: { run }, runCommand }),
898+
async () => {
899+
const capture = route.capture(ios, input, deadline.signal, fallback);
900+
const settled = expect(capture).rejects.toMatchObject({
901+
code: 'COMMAND_FAILED',
902+
details: { reason: 'request_canceled', readinessPhase: 'target-discovery' },
903+
});
904+
await vi.advanceTimersByTimeAsync(3_000);
905+
deadline.abort(new DOMException('Wait deadline exceeded', 'TimeoutError'));
906+
await settled;
907+
expect(fallback).not.toHaveBeenCalled();
908+
},
909+
);
910+
} finally {
911+
vi.useRealTimers();
912+
}
913+
});

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

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ 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, isRequestCanceledError } from '@agent-device/kernel/errors';
2020
import type { DeviceInfo } from '@agent-device/kernel/device';
2121
import {
2222
createSimulatorSnapshotSource,
@@ -140,7 +140,7 @@ export function createAppleSnapshotRoute(
140140
try {
141141
target = await resolveTargetForObservation(host, resolveTarget, device, input, signal);
142142
} catch (error) {
143-
signal.throwIfAborted();
143+
rethrowIfResolutionCancelled(signal, error);
144144
emitRouteDiagnostic('target-resolution-failed', device, undefined, error);
145145
return await runFallback(
146146
device.id,
@@ -247,6 +247,14 @@ async function resolveTargetForObservation(
247247
}
248248
}
249249

250+
/**
251+
* A cancelled target resolution rethrows the resolver's own cancellation, which names the readiness
252+
* phase only when the resolver was waiting on a running discovery.
253+
*/
254+
function rethrowIfResolutionCancelled(signal: AbortSignal, error: unknown): void {
255+
if (signal.aborted) throw isRequestCanceledError(error) ? error : signal.reason;
256+
}
257+
250258
function isEligible(device: DeviceInfo, input: CaptureSnapshotInput): boolean {
251259
return (
252260
device.platform === 'apple' &&

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

Lines changed: 26 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -217,15 +217,39 @@ test('a cancelled caller leaves discovery running for the next capture', async (
217217
await withAppleToolProvider(fixture.provider, async () => {
218218
const controller = new AbortController();
219219
const cancelled = fixture.resolve(ios, app, controller.signal);
220-
controller.abort(new Error('request-ended'));
221-
await expect(cancelled).rejects.toThrow('request-ended');
220+
const reason = new Error('request-ended');
221+
controller.abort(reason);
222+
// The caller spent its time waiting on discovery, so its cancellation names that readiness
223+
// work (#2343) and keeps the caller's own reason as the cause.
224+
await expect(cancelled).rejects.toMatchObject({
225+
details: { reason: 'request_canceled', readinessPhase: 'target-discovery' },
226+
cause: reason,
227+
});
222228

223229
release();
224230
expect(await fixture.resolve(ios, app, signal())).toMatchObject({ pid: 42 });
225231
expect(fixture.discoveryCount()).toBe(1);
226232
});
227233
});
228234

235+
test('a cancelled re-check of a known target keeps it and names no readiness work', async () => {
236+
const fixture = targetFixture();
237+
await withAppleToolProvider(fixture.provider, async () => {
238+
await fixture.resolve(ios, app, signal());
239+
const controller = new AbortController();
240+
const reason = new Error('wait-deadline');
241+
fixture.runCommand.mockImplementationOnce(async () => {
242+
controller.abort(reason);
243+
return { stdout: '', stderr: '', exitCode: 1 };
244+
});
245+
246+
await expect(fixture.resolve(ios, app, controller.signal)).rejects.toBe(reason);
247+
248+
expect(await fixture.resolve(ios, app, signal())).toMatchObject({ pid: 42 });
249+
expect(fixture.discoveryCount()).toBe(1);
250+
});
251+
});
252+
229253
test('one discovery shares a single deadline across its simctl probes and the identity read', async () => {
230254
const fixture = targetFixture();
231255
const release = deferredSpawn(fixture);

0 commit comments

Comments
 (0)