Skip to content

Commit 31eecff

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

4 files changed

Lines changed: 124 additions & 33 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,14 @@
22

33
## Unreleased
44

5+
- Changed (apple): a read-only runner command is resent inside the same request only when the
6+
runner refused it as `RUNNER_BUSY`. Before, any `COMMAND_FAILED` carrying `details.retriable:
7+
true` was sent up to three times. That flag tells a caller's own poll, such as `wait`, to try
8+
again. It does not mean a resend is safe inside one request. A runner startup that ran out of its
9+
budget (`runner_phase_budget_exhausted`) or could not read the Xcode toolchain
10+
(`apple_toolchain_probe_unavailable`) now fails once, not three times with a fresh startup budget
11+
each time. A `retriable` failure from an external Apple runner provider is also no longer resent.
12+
The error keeps `retriable: true`, so the caller's next request still tries again. (#2862)
513
- Fixed (mobile): a read taken right after a `scroll`, `swipe`, or `gesture swipe` no longer reports
614
a definite miss when the surface never settled. When post-gesture stabilization ran out of budget
715
on a surface still moving, `is visible` answered a plain `selector_not_found` and `is absent`

‎packages/platform-apple/src/runner/__tests__/runner-error-classification.test.ts‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -59,11 +59,16 @@ test('boot-shaped failures are not retryable', () => {
5959
);
6060
});
6161

62-
test('an explicitly retriable flag wins over any message denial', () => {
63-
const flagged = runnerConnectFailure('xcodebuild_exited_early', 'xcodebuild exited early', {
64-
retriable: true,
65-
});
66-
assert.equal(isRetryableRunnerError(flagged), true);
62+
test('only the runner busy refusal earns a resend; a retriable flag alone does not', () => {
63+
const busy = classifyRunnerReportedError('RUNNER_BUSY');
64+
assert.equal(isRetryableRunnerError(new AppError(busy.code, 'busy', busy.details)), true);
65+
const notRunning = classifyRunnerReportedError('APP_NOT_RUNNING');
66+
assert.equal(notRunning.details.retriable, true);
67+
assert.equal(
68+
isRetryableRunnerError(new AppError(notRunning.code, 'not running', notRunning.details)),
69+
false,
70+
);
71+
assert.equal(isRetryableRunnerError(commandFailed('boom', { retriable: true })), false);
6772
});
6873

6974
test('retryable requires an AppError with COMMAND_FAILED', () => {

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

Lines changed: 95 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,18 @@
11
import assert from 'node:assert/strict';
22
import { afterEach, beforeEach, expect, test, vi } from 'vitest';
33
import { AppError } from '@agent-device/kernel/errors';
4+
import { resetAllProcessMemosForTests } from '@agent-device/kernel/ttl-memo';
45
import { IOS_SIMULATOR } from './device-fixtures.ts';
56
import type { ExecResult } from '@agent-device/host-kit/command';
67
import type { RunnerSession } from '../runner-session.ts';
78
import { appleRunnerTestHost } from '../test-host.ts';
89
import { withAppleRunnerProvider } from '../runner-provider.ts';
9-
import type { RunnerCommand } from '../runner-contract.ts';
10+
import { classifyRunnerReportedError, type RunnerCommand } from '../runner-contract.ts';
11+
import {
12+
createRunnerPhaseBudget,
13+
requireRunnerPhaseRemainingMs,
14+
resolveExpectedRunnerCacheMetadata,
15+
} from '../runner-cache-metadata.ts';
1016
import { startFakeRunnerServer, type FakeRunnerServer } from './fake-runner-server.ts';
1117

1218
/**
@@ -298,7 +304,8 @@ test.each([undefined, 'get', 'accept', 'dismiss'] as const)(
298304
'alert action %s selects provider retries by mutation semantics',
299305
async (action) => {
300306
const commands: RunnerCommand[] = [];
301-
const failure = new AppError('COMMAND_FAILED', 'response unavailable', { retriable: true });
307+
const busy = classifyRunnerReportedError('RUNNER_BUSY');
308+
const failure = new AppError(busy.code, 'runner busy', busy.details);
302309
const result = withAppleRunnerProvider(
303310
async (_device, command) => {
304311
commands.push(command);
@@ -346,3 +353,89 @@ test('a read refused over a not-running app is one definite answer, not a transp
346353
);
347354
assert.equal(invalidateRunnerSessionMock.mock.calls.length, 0);
348355
});
356+
357+
test('a read the runner refused as busy is resent on the same session', async () => {
358+
server = await startFakeRunnerServer({
359+
snapshot: [
360+
{ kind: 'runnerError', code: 'RUNNER_BUSY', message: 'runner is draining' },
361+
{ kind: 'ok', data: { captured: true } },
362+
],
363+
status: [
364+
{
365+
kind: 'ok',
366+
data: {
367+
lifecycleState: 'failed',
368+
lifecycleErrorCode: 'RUNNER_BUSY',
369+
lifecycleErrorMessage: 'runner is draining',
370+
},
371+
},
372+
],
373+
});
374+
seedSession(server.port);
375+
376+
assert.deepEqual(await runAppleRunnerCommand(IOS_SIMULATOR, { command: 'snapshot' }), {
377+
captured: true,
378+
});
379+
assert.equal(server.requests.filter((request) => request.command === 'snapshot').length, 2);
380+
assert.equal(invalidateRunnerSessionMock.mock.calls.length, 0);
381+
});
382+
383+
// `retriable` on these tells the caller's next request to try again. Resending inside this request
384+
// would open a fresh startup budget per attempt, or second-guess a provider's own transport policy.
385+
const readSnapshot = () => runAppleRunnerCommand(IOS_SIMULATOR, { command: 'snapshot' });
386+
const sessionStarts = () => ensureRunnerSessionMock.mock.calls.length;
387+
388+
test.each([
389+
{
390+
producer: 'a spent startup budget',
391+
reason: 'runner_phase_budget_exhausted',
392+
arrange: () => {
393+
ensureRunnerSessionMock.mockImplementation(async () =>
394+
requireRunnerPhaseRemainingMs(createRunnerPhaseBudget(0, undefined), 'runner_startup'),
395+
);
396+
return { run: readSnapshot, sends: sessionStarts };
397+
},
398+
},
399+
{
400+
producer: 'an unreadable toolchain',
401+
reason: 'apple_toolchain_probe_unavailable',
402+
arrange: () => {
403+
resetAllProcessMemosForTests();
404+
appleRunnerTestHost.update({
405+
runCmdSync: () => ({ exitCode: 1, stdout: '', stderr: 'xcode-select: error' }),
406+
});
407+
ensureRunnerSessionMock.mockImplementation(async () =>
408+
resolveExpectedRunnerCacheMetadata(IOS_SIMULATOR),
409+
);
410+
return { run: readSnapshot, sends: sessionStarts };
411+
},
412+
},
413+
{
414+
producer: 'an external runner provider',
415+
reason: 'provider_transport_unavailable',
416+
arrange: () => {
417+
let calls = 0;
418+
const provider = async () => {
419+
calls += 1;
420+
throw new AppError('COMMAND_FAILED', 'provider transport unavailable', {
421+
reason: 'provider_transport_unavailable',
422+
retriable: true,
423+
});
424+
};
425+
return {
426+
run: () => withAppleRunnerProvider(provider, { deviceId: IOS_SIMULATOR.id }, readSnapshot),
427+
sends: () => calls,
428+
};
429+
},
430+
},
431+
])('a retriable read failure from $producer is not resent', async ({ reason, arrange }) => {
432+
const { run, sends } = arrange();
433+
434+
await assert.rejects(run(), (error: unknown) => {
435+
assert.ok(error instanceof AppError);
436+
assert.equal(error.details?.reason, reason);
437+
assert.equal(error.details?.retriable, true);
438+
return true;
439+
});
440+
assert.equal(sends(), 1);
441+
});

‎packages/platform-apple/src/runner/runner-error-classification.ts‎

Lines changed: 11 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -9,19 +9,15 @@ import {
99
type IosDeveloperDiskImageState,
1010
type IosDeveloperModeState,
1111
} from './host.ts';
12-
import {
13-
APP_NOT_RUNNING_RUNNER_CODE,
14-
MAIN_THREAD_TIMEOUT_RUNNER_CODE,
15-
RUNNER_BUSY_RUNNER_CODE,
16-
} from './runner-contract.ts';
12+
import { MAIN_THREAD_TIMEOUT_RUNNER_CODE, RUNNER_BUSY_RUNNER_CODE } from './runner-contract.ts';
1713

1814
export const RUNNER_CACHE_RECOVERY_HINT =
1915
'If runner build products look stale or corrupted, run `pnpm clean:xcuitest` in a local checkout, or remove ~/.agent-device/apple-runner/derived, then retry.';
2016

2117
/**
2218
* Details evidence a rule requires beyond code and message. A predicate rather than a
2319
* fixed vocabulary because the useful evidence is a shape: a recorded deadline, a
24-
* preflight marker, a retriable flag. Every predicate below names one.
20+
* preflight marker, a runner error code. Every predicate below names one.
2521
*/
2622
type RunnerErrorDetailsMatch = (details: AppErrorDetails) => boolean;
2723

@@ -69,9 +65,12 @@ type RunnerErrorMatch = {
6965
details?: RunnerErrorDetailsMatch;
7066
};
7167

72-
const hasRetriableFlag: RunnerErrorDetailsMatch = (details) => details.retriable === true;
73-
const hasAppNotRunningRunnerCode: RunnerErrorDetailsMatch = (details) =>
74-
details.runnerErrorCode === APP_NOT_RUNNING_RUNNER_CODE;
68+
/**
69+
* The runner refused the command before running it while abandoned main-thread work drains (#1105).
70+
* A resend keys on this code, never on `details.retriable`: that flag tells a caller's poll to try
71+
* again, and its other producers (a not-running app, a spent startup budget, an unavailable
72+
* toolchain probe, an external provider) must not be resent inside one request.
73+
*/
7574
const hasRunnerBusyCode: RunnerErrorDetailsMatch = (details) =>
7675
details.runnerErrorCode === RUNNER_BUSY_RUNNER_CODE;
7776
/**
@@ -210,11 +209,8 @@ const PROFILE_UNUSABLE: RunnerErrorRule['buildFailure'] = {
210209
* and since #2680 so does the one classification of startup failures — a row
211210
* carries recovery verdicts, a `buildFailure` reason and hint, or both.
212211
* Per axis, the FIRST matching rule that defines the axis wins — which is why
213-
* `flagged_retriable` precedes the denials (an explicitly retriable error
214-
* stays retriable whatever its message says), and `usbmux_device_unattached`
215-
* sits first (retrying cannot attach a cable, and its typed verdict carries
216-
* the recovery hint a generic connect failure would replace). `app_not_running`
217-
* precedes it too: its retriable flag is for the caller's poll, not a resend.
212+
* `usbmux_device_unattached` sits first (retrying cannot attach a cable, and its
213+
* typed verdict carries the recovery hint a generic connect failure would replace).
218214
*/
219215
export const RUNNER_ERROR_RULES: readonly RunnerErrorRule[] = [
220216
{
@@ -223,22 +219,11 @@ export const RUNNER_ERROR_RULES: readonly RunnerErrorRule[] = [
223219
verdicts: { connectRetry: false },
224220
},
225221
{
226-
reason: 'app_not_running',
227-
match: { code: 'COMMAND_FAILED', details: hasAppNotRunningRunnerCode },
228-
verdicts: { retryable: false, connectRetry: false },
229-
},
230-
{
231-
// Named before the generic retriable flag so diagnostics say what refused, not that a flag
232-
// was set. Nothing ran: the runner answered before dispatching the command (#1105).
222+
// Nothing ran: the runner answered before dispatching the command (#1105).
233223
reason: 'runner_busy_refusal',
234224
match: { code: 'COMMAND_FAILED', details: hasRunnerBusyCode },
235225
verdicts: { retryable: true, connectRetry: true, drainResend: true },
236226
},
237-
{
238-
reason: 'flagged_retriable',
239-
match: { code: 'COMMAND_FAILED', details: hasRetriableFlag },
240-
verdicts: { retryable: true, connectRetry: true },
241-
},
242227
{
243228
// Says `artifactSuspect: false` on purpose: a boot that cannot compile is not cured by wiping
244229
// derived data.

0 commit comments

Comments
 (0)