Skip to content

Commit 800da9a

Browse files
committed
fix(ios): give boot a --timeout startup budget (#3004)
The first boot of a never-booted Simulator runs Apple's first-boot migration, which can take minutes, but `boot`'s fixed 90s client envelope and 120s daemon-side boot wait had no way to raise it. - `boot --timeout <ms>` is a daemon-side startup budget, mirroring open/prepare (#2325): the client envelope keeps a 30s margin over it so the daemon's own `boot_timeout` result wins the race, and the budget reaches the Simulator boot wait as an absolute deadline. - Expiry fails with `error.details.reason: boot_timeout` and leaves the Simulator booting, so a retry finds it further along. Closes #3004
1 parent 657a6fc commit 800da9a

10 files changed

Lines changed: 67 additions & 8 deletions

File tree

‎packages/command-registry/src/flag-definitions-workflow.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,7 @@ export const WORKFLOW_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
8585
min: 1,
8686
usageLabel: '--timeout <ms>',
8787
usageDescription:
88-
'Open/Prepare: startup budget covering the Simulator boot (and runner preparation for prepare). Replay/Snapshot/Test: maximum wall-clock time for the command or attempt. With --settle: the settle-wait deadline (default 10s)',
88+
'Boot/Open/Prepare: startup budget covering the Simulator boot (and runner preparation for prepare). Replay/Snapshot/Test: maximum wall-clock time for the command or attempt. With --settle: the settle-wait deadline (default 10s)',
8989
projectConfig: true,
9090
recorded: false,
9191
},

‎packages/command-registry/src/registry.ts‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -714,7 +714,9 @@ export const RAW_COMMAND_DESCRIPTORS = [
714714
sessionKind: 'state',
715715
},
716716
platformExecution: { kind: 'device-runtime', uses: deviceBootRuntimeUses },
717-
timeoutPolicy: DEFAULT_TIMEOUT_POLICY,
717+
// --timeout is a startup budget: it reaches the Simulator boot wait, same as open/prepare
718+
// (#2325). A first boot can outlast the fixed 90s envelope (#3004).
719+
timeoutPolicy: { ...DEFAULT_TIMEOUT_POLICY, budget: { source: 'flag', envelope: 'margin' } },
718720
batchable: true,
719721
},
720722
{

‎packages/contracts/src/client-device-view.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -101,6 +101,8 @@ export type StartupPerfSample = {
101101

102102
export type DeviceBootOptions = DeviceCommandBaseOptions & {
103103
headless?: boolean;
104+
/** Startup budget in milliseconds: bounds the Simulator boot wait on a cold device. */
105+
timeoutMs?: number;
104106
};
105107

106108
export type DeviceShutdownOptions = DeviceCommandBaseOptions;

‎packages/contracts/src/device-readiness-runtime.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@ import type { DeviceInventoryRequest } from './device-inventory.ts';
44
export type EnsureReadyInput = Readonly<{
55
serial?: string;
66
androidSerialAllowlist?: readonly string[];
7+
/** Startup budget in milliseconds, from `boot --timeout`. Bounds a cold Simulator boot wait. */
8+
timeoutMs?: number;
79
}>;
810

911
export type DeviceReadinessRuntimeOperations = Readonly<{

‎packages/platform-apple/src/runtime.test.ts‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -522,6 +522,48 @@ test('readiness and boot keep the Apple automation helper warm inside the platfo
522522
expect(keepHot).toHaveBeenNthCalledWith(3, device);
523523
});
524524

525+
test('bootTarget forwards a --timeout budget as the Simulator boot deadline (#3004)', async () => {
526+
const host = platformRuntimeHostFixture();
527+
let state = 'Shutdown';
528+
const calls: Array<{ args: readonly string[]; timeoutMs?: number }> = [];
529+
const runtime = createApplePlatformRuntime({
530+
...host,
531+
appleTools: {
532+
...host.appleTools,
533+
run: vi.fn(async (request) => {
534+
calls.push({ args: request.args, timeoutMs: request.timeoutMs });
535+
if (request.args.includes('list')) {
536+
return {
537+
stdout: JSON.stringify({ devices: { ios: [{ udid: 'apple-fact', state }] } }),
538+
stderr: '',
539+
exitCode: 0,
540+
};
541+
}
542+
if (request.args.includes('boot')) state = 'Booted';
543+
return { stdout: '', stderr: '', exitCode: 0 };
544+
}),
545+
},
546+
});
547+
const device = appleDevice({ booted: false });
548+
const binding = await runtime.bind({
549+
device,
550+
intent: { kind: 'ordinary' },
551+
scope: {
552+
signal: new AbortController().signal,
553+
diagnostics: { emit: () => {} },
554+
progress: { report: () => {} },
555+
},
556+
});
557+
558+
await binding.operations.bootTarget?.({ timeoutMs: 45_000 });
559+
560+
// The startup budget reaches the boot wait, same as open/prepare (#2325): the
561+
// envelope's --timeout is the deadline the simctl calls run under, not a fixed default.
562+
const bootCall = calls.find((call) => call.args.includes('boot'));
563+
expect(bootCall?.timeoutMs).toBeLessThanOrEqual(45_000);
564+
expect(bootCall?.timeoutMs).toBeGreaterThan(0);
565+
});
566+
525567
test('macOS readiness is a no-op while boot remains unavailable', async () => {
526568
const host = platformRuntimeHostFixture();
527569
const ensureConnected = vi.fn(host.deviceReadiness.applePhysical.ensureConnected);

‎packages/platform-apple/src/runtime.ts‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,7 @@ import {
6060
appleScreenRecordingFacts,
6161
createAppleScreenRecordingOperations,
6262
} from './recording/runtime.ts';
63+
import type { EnsureReadyInput } from '@agent-device/contracts/device-readiness-runtime';
6364
import { ensureAppleReady } from './readiness/runtime.ts';
6465
import { bindAppleApplicationLifecycle } from './lifecycle.ts';
6566
import {
@@ -475,8 +476,11 @@ export function createApplePlatformRuntime(host: PlatformRuntimeHost): PlatformR
475476
await ensureAppleReady(host, request.device, request.scope.signal),
476477
})),
477478
...whenAdmitted(facts.operations.bootTarget, () => ({
478-
bootTarget: async () =>
479-
await ensureAppleReady(host, request.device, request.scope.signal),
479+
bootTarget: async (input: EnsureReadyInput) =>
480+
await ensureAppleReady(host, request.device, request.scope.signal, {
481+
deadlineAtMs:
482+
typeof input.timeoutMs === 'number' ? Date.now() + input.timeoutMs : undefined,
483+
}),
480484
})),
481485
...whenAdmitted(facts.operations.listApps, () => ({
482486
listApps: async (input: { device: DeviceInfo; filter: 'all' | 'user-installed' }) => {

‎src/__tests__/command-descriptor-timeout-policy.test.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -113,9 +113,9 @@ test('budget sources deviating from the default are bounded, reviewed sets', ()
113113
}
114114
// --timeout bounds the request envelope for these commands only.
115115
assert.deepEqual(flagBoundBudget.sort(), ['replay', 'snapshot']);
116-
// --timeout is a daemon-side startup budget on these commands (#2324); the
116+
// --timeout is a daemon-side startup budget on these commands (#2324, #3004); the
117117
// envelope keeps a margin over it so the daemon's own timeout wins the race.
118-
assert.deepEqual(flagMarginBudget.sort(), ['open', 'prepare']);
118+
assert.deepEqual(flagMarginBudget.sort(), ['boot', 'open', 'prepare']);
119119
// --timeout bounds the --settle wait on these commands (#1101); like wait's
120120
// positional budget it only ever widens the envelope, never shrinks it.
121121
assert.deepEqual(flagWidenBudget.sort(), settleObservationCommandNames());

‎src/commands/management/device.ts‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ import { DEVICE_KINDS, DEVICE_TARGETS, PUBLIC_PLATFORMS } from '@agent-device/ke
55
import {
66
booleanField,
77
booleanSchema,
8+
integerField,
89
enumSchema,
910
looseObjectSchema,
1011
numberSchema,
@@ -77,6 +78,10 @@ const bootCommandMetadata = defineFieldCommandMetadata(
7778
'Boot or prepare the selected device or simulator so later commands can target it. The device is chosen through the device-selection inputs, not by naming it here.',
7879
{
7980
headless: booleanField('Boot without showing simulator UI when supported.'),
81+
timeoutMs: integerField(
82+
'Startup budget in milliseconds. Bounds the Simulator boot wait, so a never-booted Simulator can finish its first-boot migration; omit for the default startup behavior.',
83+
{ min: 1 },
84+
),
8085
},
8186
);
8287

@@ -87,7 +92,7 @@ const shutdownCommandMetadata = defineFieldCommandMetadata(
8792
);
8893

8994
const bootCliSchema = {
90-
allowedFlags: ['headless'],
95+
allowedFlags: ['headless', 'timeoutMs'],
9196
} as const satisfies CommandSchemaOverride;
9297

9398
const devicesCliSchema = {} as const satisfies CommandSchemaOverride;
@@ -101,6 +106,7 @@ const commonCliReader: CliReader = (_positionals, flags) => commonInputFromFlags
101106
const bootCliReader: CliReader = (_positionals, flags) => ({
102107
...commonInputFromFlags(flags),
103108
headless: flags.headless,
109+
timeoutMs: flags.timeoutMs,
104110
});
105111

106112
const devicesDaemonWriter: DaemonWriter = direct(PUBLIC_COMMANDS.devices);

‎src/daemon/handlers/session-state.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -302,7 +302,7 @@ export async function handleSessionStateCommands(params: {
302302
});
303303
if (admitted.type === 'response') return admitted.response;
304304

305-
const input = { serial: flags.serial, androidSerialAllowlist };
305+
const input = { serial: flags.serial, androidSerialAllowlist, timeoutMs: flags.timeoutMs };
306306
if (plan.kind === 'boot-target-headless') {
307307
device = await (await admitted.bind(device, plan.use)).operations.bootTargetHeadless(input);
308308
} else {

‎website/docs/docs/commands.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,7 @@ agent-device fold open
6969
- `--platform apple` is an alias for the Apple automation backend (`ios`, `tvOS`, `macOS` selection).
7070
- Use `--target mobile|tv|desktop` with `--platform` (required) to select phone/tablet vs TV-class vs desktop-class targets.
7171
- `boot` is mainly needed when starting a new session and `open` fails because no booted simulator/emulator is available.
72+
- `boot --timeout <ms>` is a startup budget for the Simulator boot, same as `open`'s. A never-booted iOS Simulator runs Apple's first-boot migration, which can take several minutes; without the flag the boot wait is capped at 120 seconds. When the budget runs out the command fails with `error.details.reason: boot_timeout` and the Simulator keeps booting, so a retry finds it further along.
7273
- Android: `boot --platform android --device <avd-name>` launches that emulator in GUI mode when needed.
7374
- Android: add `--headless` to launch without opening a GUI window.
7475
- Android: `shutdown --platform android --device <avd-name>` stops a running emulator.

0 commit comments

Comments
 (0)