fix(android): honor boot --timeout as the emulator boot deadline

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

@@ -85,7 +85,7 @@ export const WORKFLOW_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
     min: 1,
     usageLabel: '--timeout <ms>',
     usageDescription:
-      '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)',
+      'Boot/Open/Prepare: startup budget covering the device 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)',
     projectConfig: true,
     recorded: false,
   },

packages/command-registry/src/registry.ts

@@ -714,7 +714,7 @@ export const RAW_COMMAND_DESCRIPTORS = [
       sessionKind: 'state',
     },
     platformExecution: { kind: 'device-runtime', uses: deviceBootRuntimeUses },
-    // --timeout is a startup budget: it reaches the Simulator boot wait, same as open/prepare
+    // --timeout is a startup budget: it reaches the device boot wait, same as open/prepare
     // (#2325). A first boot can outlast the fixed 90s envelope (#3004).
     timeoutPolicy: { ...DEFAULT_TIMEOUT_POLICY, budget: { source: 'flag', envelope: 'margin' } },
     batchable: true,

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

@@ -101,7 +101,7 @@ export type StartupPerfSample = {
 
 export type DeviceBootOptions = DeviceCommandBaseOptions & {
   headless?: boolean;
-  /** Startup budget in milliseconds: bounds the Simulator boot wait on a cold device. */
+  /** Startup budget in milliseconds: bounds the boot wait on a cold Simulator or emulator. */
   timeoutMs?: number;
 };
 

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

@@ -1,12 +1,16 @@
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import type { DeviceInventoryRequest } from './device-inventory.ts';
 
+/** Typed `details.reason` every platform reports when the boot deadline expires. */
+export const BOOT_TIMEOUT_REASON = 'boot_timeout';
+
 export type EnsureReadyInput = Readonly<{
   serial?: string;
   androidSerialAllowlist?: readonly string[];
   /**
    * Absolute deadline (epoch ms), from `boot --timeout`, already validated finite and positive.
-   * Bounds a cold Simulator boot wait; the Apple runtime is the only current consumer.
+   * Bounds a cold boot wait; the Apple and Android runtimes honor it. HarmonyOS, Vega, and Linux
+   * have no boot wait to bound.
    */
   deadlineAtMs?: number;
 }>;

packages/platform-android/src/lifecycle.ts

@@ -54,8 +54,12 @@ export function bindAndroidApplicationLifecycle(
     resolveOpenTarget: async (input) =>
       await host.androidApplications.resolveOpenTarget(device, input),
     prepareApplicationOpen: async (input) => {
-      await ensureAndroidReady(host, device, { headless: false }, signal);
-      void input;
+      await ensureAndroidReady(
+        host,
+        device,
+        { headless: false, deadlineAtMs: input.execution.startupDeadlineAtMs },
+        signal,
+      );
     },
     openApplication: async (input) => await openAndroidApplication(host, binding, input),
     applyRuntimeHints: async (input) =>

packages/platform-android/src/readiness/runtime.test.ts

@@ -48,6 +48,95 @@ test('cancellation interrupts Android boot polling and terminates the emulator l
   expect(terminate).toHaveBeenCalledWith(4242);
 });
 
+function timedHost(overrides: { bootCompleted: string; discover: () => DeviceInfo[] }) {
+  let now = 1_000;
+  const run = vi.fn(async () => ({ stdout: overrides.bootCompleted, stderr: '', exitCode: 0 }));
+  const terminate = vi.fn(async () => {});
+  const host = {
+    commands: { which: async () => 'tool', run },
+    toolchains: { prepare: async () => {} },
+    clock: {
+      now: () => now,
+      sleep: async (ms: number) => {
+        now += ms;
+      },
+    },
+    deviceReadiness: {
+      androidEmulator: {
+        discover: async () => overrides.discover(),
+        launch: () => 4242,
+        terminate,
+      },
+    },
+  } as unknown as PlatformRuntimeHost;
+  return { host, run, terminate, elapsed: () => now - 1_000 };
+}
+
+test('a startup deadline bounds the emulator boot wait and expiry reports boot_timeout without killing the emulator', async () => {
+  const { host, run, terminate, elapsed } = timedHost({
+    bootCompleted: '0',
+    discover: () => [runningEmulator()],
+  });
+
+  await expect(
+    ensureAndroidReady(
+      host,
+      runningEmulator(),
+      { headless: false, deadlineAtMs: 3_000 },
+      new AbortController().signal,
+    ),
+  ).rejects.toMatchObject({ details: { reason: 'boot_timeout', serial: 'emulator-5554' } });
+
+  expect(elapsed()).toBeLessThan(5_000);
+  expect(run).toHaveBeenCalled();
+  expect(terminate).not.toHaveBeenCalled();
+});
+
+test('a startup deadline also bounds waiting for a launched emulator to appear', async () => {
+  const { host, elapsed, terminate } = timedHost({
+    bootCompleted: '1',
+    discover: () => [stoppedAvd()],
+  });
+
+  await expect(
+    ensureAndroidReady(
+      host,
+      stoppedAvd(),
+      { headless: true, deadlineAtMs: 3_000 },
+      new AbortController().signal,
+    ),
+  ).rejects.toMatchObject({ details: { reason: 'boot_timeout' } });
+  expect(elapsed()).toBeLessThan(5_000);
+  expect(terminate).not.toHaveBeenCalled();
+});
+
+test('expiry of a launched emulator that never reports boot_completed leaves it running', async () => {
+  let discoveries = 0;
+  const { host, terminate } = timedHost({
+    bootCompleted: '0',
+    discover: () => (++discoveries === 1 ? [stoppedAvd()] : [runningEmulator()]),
+  });
+
+  await expect(
+    ensureAndroidReady(
+      host,
+      stoppedAvd(),
+      { headless: true, deadlineAtMs: 3_000 },
+      new AbortController().signal,
+    ),
+  ).rejects.toMatchObject({ details: { reason: 'boot_timeout', serial: 'emulator-5554' } });
+  expect(terminate).not.toHaveBeenCalled();
+});
+
+test('without a deadline the default 120s boot wait applies', async () => {
+  const { host, elapsed } = timedHost({ bootCompleted: '0', discover: () => [runningEmulator()] });
+
+  await expect(
+    ensureAndroidReady(host, runningEmulator(), { headless: false }, new AbortController().signal),
+  ).rejects.toMatchObject({ details: { reason: 'boot_timeout' } });
+  expect(elapsed()).toBeGreaterThanOrEqual(120_000);
+});
+
 function stoppedAvd(): DeviceInfo {
   return {
     platform: 'android',

packages/platform-android/src/readiness/runtime.ts

@@ -1,4 +1,7 @@
-import type { EnsureReadyInput } from '@agent-device/contracts/device-readiness-runtime';
+import {
+  BOOT_TIMEOUT_REASON,
+  type EnsureReadyInput,
+} from '@agent-device/contracts/device-readiness-runtime';
 import type { PlatformRuntimeHost } from '@agent-device/contracts/platform-runtime-operations';
 
 /** Readiness reads exactly these host ports; the lifecycle binding composes the same subset. */
@@ -25,7 +28,9 @@ export async function ensureAndroidReady(
   if (device.kind === 'emulator' && (device.booted !== true || !isRunningEmulator(device))) {
     return await ensureEmulatorReady(host, device, input, signal);
   }
-  if (device.booted !== true) await waitForBoot(host, device.id, BOOT_TIMEOUT_MS, signal);
+  if (device.booted !== true) {
+    await waitForBoot(host, device.id, bootDeadlineAtMs(host, input), signal);
+  }
   return { ...device, booted: true };
 }
 
@@ -37,6 +42,7 @@ async function ensureEmulatorReady(
 ): Promise<DeviceInfo> {
   await prepareAndroidEmulatorToolchain(host);
   const request = inventoryRequest(input);
+  const deadlineAtMs = bootDeadlineAtMs(host, input);
   const available = await host.deviceReadiness.androidEmulator.discover(request, signal);
   const selected = requireAvailableAvd(available, device.name, input.serial);
 
@@ -46,8 +52,9 @@ async function ensureEmulatorReady(
     : host.deviceReadiness.androidEmulator.launch(selected.name, input.headless);
   try {
     const discovered =
-      existing ?? (await waitForDiscovery(host, selected.name, request, input.serial, signal));
-    await waitForBoot(host, discovered.id, BOOT_TIMEOUT_MS, signal);
+      existing ??
+      (await waitForDiscovery(host, selected.name, request, input.serial, deadlineAtMs, signal));
+    await waitForBoot(host, discovered.id, deadlineAtMs, signal);
     const refreshed = (await host.deviceReadiness.androidEmulator.discover(request, signal)).find(
       (candidate) => candidate.id === discovered.id,
     );
@@ -90,29 +97,24 @@ async function waitForDiscovery(
   avdName: string,
   request: ReturnType<typeof inventoryRequest>,
   serial: string | undefined,
+  deadline: number,
   signal: AbortSignal,
 ): Promise<DeviceInfo> {
-  const deadline = host.clock.now() + BOOT_TIMEOUT_MS;
   while (host.clock.now() < deadline) {
     const devices = await host.deviceReadiness.androidEmulator.discover(request, signal);
     const device = findByAvdName(devices, avdName, serial);
     if (device && isRunningEmulator(device)) return device;
     await host.clock.sleep(POLL_MS, signal);
   }
-  throw new AppError('COMMAND_FAILED', 'Android emulator did not appear in time', {
-    avdName,
-    serial,
-    timeoutMs: BOOT_TIMEOUT_MS,
-  });
+  throw bootTimeoutError('Android emulator did not appear in time', { avdName, serial });
 }
 
 async function waitForBoot(
   host: AndroidReadinessHost,
   serial: string,
-  timeoutMs: number,
+  deadline: number,
   signal: AbortSignal,
 ): Promise<void> {
-  const deadline = host.clock.now() + timeoutMs;
   while (host.clock.now() < deadline) {
     const result = await host.commands.run(
       {
@@ -126,13 +128,22 @@ async function waitForBoot(
     if (result.stdout.trim() === '1') return;
     await host.clock.sleep(POLL_MS, signal);
   }
-  throw new AppError('COMMAND_FAILED', 'Android device failed to finish booting', {
-    serial,
-    timeoutMs,
-    reason: 'ANDROID_BOOT_TIMEOUT',
+  throw bootTimeoutError('Android device failed to finish booting', { serial });
+}
+
+function bootTimeoutError(message: string, details: Record<string, unknown>): AppError {
+  return new AppError('COMMAND_FAILED', message, {
+    ...details,
+    reason: BOOT_TIMEOUT_REASON,
+    hint: 'The emulator keeps booting in the background. Retry once it is up, or pass a larger --timeout.',
   });
 }
 
+/** The caller's `--timeout` deadline when stated, else the default boot wait from now. */
+function bootDeadlineAtMs(host: AndroidReadinessHost, input: EnsureReadyInput): number {
+  return input.deadlineAtMs ?? host.clock.now() + BOOT_TIMEOUT_MS;
+}
+
 function inventoryRequest(input: EnsureReadyInput) {
   return {
     platform: 'android' as const,

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

@@ -1,3 +1,4 @@
+import { BOOT_TIMEOUT_REASON } from '@agent-device/contracts/device-readiness-runtime';
 import type { PlatformRuntimeHost } from '@agent-device/contracts/platform-runtime-operations';
 import { isMacOs, type DeviceInfo } from '@agent-device/kernel/device';
 import { AppError } from '@agent-device/kernel/errors';
@@ -170,7 +171,7 @@ function bootDeadlineError(device: DeviceInfo, cause?: unknown): AppError {
     'COMMAND_FAILED',
     'Simulator did not finish booting within the startup budget',
     {
-      reason: 'boot_timeout',
+      reason: BOOT_TIMEOUT_REASON,
       deviceId: device.id,
       hint: 'The Simulator keeps booting in the background; a first boot can take several minutes. Retry once it is up, or pass a larger --timeout.',
     },

src/commands/management/device.ts

@@ -79,7 +79,7 @@ const bootCommandMetadata = defineFieldCommandMetadata(
   {
     headless: booleanField('Boot without showing simulator UI when supported.'),
     timeoutMs: integerField(
-      '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.',
+      'Startup budget in milliseconds. Bounds the boot wait, so a never-booted Simulator can finish its first-boot migration or a cold emulator its boot; omit for the default startup behavior.',
       { min: 1 },
     ),
   },

website/docs/docs/commands.md

@@ -69,12 +69,12 @@ agent-device fold open
 - `--platform apple` is an alias for the Apple automation backend (`ios`, `tvOS`, `macOS` selection).
 - Use `--target mobile|tv|desktop` with `--platform` (required) to select phone/tablet vs TV-class vs desktop-class targets.
 - `boot` is mainly needed when starting a new session and `open` fails because no booted simulator/emulator is available.
-- `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 command's 90-second request envelope ends the boot first, before the wait's own 120-second cap ever applies. 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.
+- `boot --timeout <ms>` is a startup budget for the Simulator or Android emulator 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 command's 90-second request envelope ends the boot first, before the wait's own 120-second cap ever applies. When the budget runs out the command fails with `error.details.reason: boot_timeout` and the Simulator or emulator keeps booting, so a retry finds it further along.
 - Android: `boot --platform android --device <avd-name>` launches that emulator in GUI mode when needed.
 - Android: add `--headless` to launch without opening a GUI window.
 - Android: `shutdown --platform android --device <avd-name>` stops a running emulator.
 - `open [app|url] [url]` already boots/activates the selected target when needed.
-- `open <app> --timeout <ms>` is a startup budget for that boot. A never-booted iOS Simulator runs Apple's first-boot migration, which can take several minutes; without the flag the 90-second request envelope ends the boot first, before the wait's own 120-second cap ever applies. 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.
+- `open <app> --timeout <ms>` is a startup budget for that boot, on iOS Simulators and Android emulators. A never-booted iOS Simulator runs Apple's first-boot migration, which can take several minutes; without the flag the 90-second request envelope ends the boot first, before the wait's own 120-second cap ever applies. 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.
 - `open <app> --wait <ms>` waits up to that budget for a device another session is holding instead of failing at once. The open reports each poll, then either opens the device or fails with `DEVICE_IN_USE` naming the owning session and saying the budget was spent. A wait that finds the device taken again keeps waiting for the rest of its budget, so several opens can queue on one device and none of them is refused before its budget is spent. Only session contention is waited for: a device claim held by another workspace's daemon is never retriable and returns its recovery command immediately. The wait extends the command's timeout envelope, so a long budget does not need a longer `--timeout`.
 - `open <url>` deep links are supported on Android and iOS.
 - `open <app> <url>` opens a deep link on iOS.