agent-device 0.3.1 → 0.3.2

package/src/platforms/boot-diagnostics.ts

@@ -1,22 +1,33 @@
 import { asAppError } from '../utils/errors.ts';
 
 export type BootFailureReason =
-  | 'BOOT_TIMEOUT'
-  | 'DEVICE_UNAVAILABLE'
-  | 'DEVICE_OFFLINE'
-  | 'PERMISSION_DENIED'
-  | 'TOOL_MISSING'
+  | 'IOS_BOOT_TIMEOUT'
+  | 'IOS_RUNNER_CONNECT_TIMEOUT'
+  | 'IOS_TOOL_MISSING'
+  | 'ANDROID_BOOT_TIMEOUT'
+  | 'ADB_TRANSPORT_UNAVAILABLE'
+  | 'CI_RESOURCE_STARVATION_SUSPECTED'
   | 'BOOT_COMMAND_FAILED'
   | 'UNKNOWN';
 
+type BootDiagnosticContext = {
+  platform?: 'ios' | 'android';
+  phase?: 'boot' | 'connect' | 'transport';
+};
+
 export function classifyBootFailure(input: {
   error?: unknown;
   message?: string;
   stdout?: string;
   stderr?: string;
+  context?: BootDiagnosticContext;
 }): BootFailureReason {
   const appErr = input.error ? asAppError(input.error) : null;
-  if (appErr?.code === 'TOOL_MISSING') return 'TOOL_MISSING';
+  const platform = input.context?.platform;
+  const phase = input.context?.phase;
+  if (appErr?.code === 'TOOL_MISSING') {
+    return platform === 'android' ? 'ADB_TRANSPORT_UNAVAILABLE' : 'IOS_TOOL_MISSING';
+  }
   const details = (appErr?.details ?? {}) as Record<string, unknown>;
   const detailMessage = typeof details.message === 'string' ? details.message : undefined;
   const detailStdout = typeof details.stdout === 'string' ? details.stdout : undefined;
@@ -45,23 +56,73 @@ export function classifyBootFailure(input: {
     .join('\n')
     .toLowerCase();
 
-  if (haystack.includes('timed out') || haystack.includes('timeout')) return 'BOOT_TIMEOUT';
   if (
-    haystack.includes('device not found') ||
-    haystack.includes('no devices') ||
-    haystack.includes('unable to locate device') ||
-    haystack.includes('invalid device')
+    platform === 'ios' &&
+    (
+      haystack.includes('runner did not accept connection') ||
+      (phase === 'connect' &&
+        (
+          haystack.includes('timed out') ||
+          haystack.includes('timeout') ||
+          haystack.includes('econnrefused') ||
+          haystack.includes('connection refused') ||
+          haystack.includes('fetch failed') ||
+          haystack.includes('socket hang up')
+        ))
+    )
+  ) {
+    return 'IOS_RUNNER_CONNECT_TIMEOUT';
+  }
+  if (platform === 'ios' && phase === 'boot' && (haystack.includes('timed out') || haystack.includes('timeout'))) {
+    return 'IOS_BOOT_TIMEOUT';
+  }
+  if (platform === 'android' && phase === 'boot' && (haystack.includes('timed out') || haystack.includes('timeout'))) {
+    return 'ANDROID_BOOT_TIMEOUT';
+  }
+  if (
+    haystack.includes('resource temporarily unavailable') ||
+    haystack.includes('killed: 9') ||
+    haystack.includes('cannot allocate memory') ||
+    haystack.includes('system is low on memory')
   ) {
-    return 'DEVICE_UNAVAILABLE';
+    return 'CI_RESOURCE_STARVATION_SUSPECTED';
   }
-  if (haystack.includes('offline')) return 'DEVICE_OFFLINE';
   if (
-    haystack.includes('permission denied') ||
-    haystack.includes('not authorized') ||
-    haystack.includes('unauthorized')
+    platform === 'android' &&
+    (
+      haystack.includes('device not found') ||
+      haystack.includes('no devices') ||
+      haystack.includes('device offline') ||
+      haystack.includes('offline') ||
+      haystack.includes('unauthorized') ||
+      haystack.includes('not authorized') ||
+      haystack.includes('unable to locate device') ||
+      haystack.includes('invalid device')
+    )
   ) {
-    return 'PERMISSION_DENIED';
+    return 'ADB_TRANSPORT_UNAVAILABLE';
   }
   if (appErr?.code === 'COMMAND_FAILED' || haystack.length > 0) return 'BOOT_COMMAND_FAILED';
   return 'UNKNOWN';
 }
+
+export function bootFailureHint(reason: BootFailureReason): string {
+  switch (reason) {
+    case 'IOS_BOOT_TIMEOUT':
+      return 'Retry simulator boot and inspect simctl bootstatus logs; in CI consider increasing AGENT_DEVICE_IOS_BOOT_TIMEOUT_MS.';
+    case 'IOS_RUNNER_CONNECT_TIMEOUT':
+      return 'Retry runner startup, inspect xcodebuild logs, and verify simulator responsiveness before command execution.';
+    case 'ANDROID_BOOT_TIMEOUT':
+      return 'Retry emulator startup and verify sys.boot_completed reaches 1; consider increasing startup budget in CI.';
+    case 'ADB_TRANSPORT_UNAVAILABLE':
+      return 'Check adb server/device transport (adb devices -l), restart adb, and ensure the target device is online and authorized.';
+    case 'CI_RESOURCE_STARVATION_SUSPECTED':
+      return 'CI machine may be resource constrained; reduce parallel jobs or use a larger runner.';
+    case 'IOS_TOOL_MISSING':
+      return 'Xcode command-line tools are missing or not in PATH; run xcode-select --install and verify xcrun works.';
+    case 'BOOT_COMMAND_FAILED':
+      return 'Inspect command stderr/stdout for the failing boot phase and retry after environment validation.';
+    default:
+      return 'Retry once and inspect verbose logs for the failing phase.';
+  }
+}

package/src/platforms/ios/index.ts

@@ -2,14 +2,19 @@ import { runCmd } from '../../utils/exec.ts';
 import type { ExecResult } from '../../utils/exec.ts';
 import { AppError } from '../../utils/errors.ts';
 import type { DeviceInfo } from '../../utils/device.ts';
-import { Deadline, retryWithPolicy } from '../../utils/retry.ts';
-import { classifyBootFailure } from '../boot-diagnostics.ts';
+import { Deadline, isEnvTruthy, retryWithPolicy, TIMEOUT_PROFILES, type RetryTelemetryEvent } from '../../utils/retry.ts';
+import { bootFailureHint, classifyBootFailure } from '../boot-diagnostics.ts';
 
 const ALIASES: Record<string, string> = {
   settings: 'com.apple.Preferences',
 };
 
-const IOS_BOOT_TIMEOUT_MS = resolveTimeoutMs(process.env.AGENT_DEVICE_IOS_BOOT_TIMEOUT_MS, 120_000, 5_000);
+const IOS_BOOT_TIMEOUT_MS = resolveTimeoutMs(
+  process.env.AGENT_DEVICE_IOS_BOOT_TIMEOUT_MS,
+  TIMEOUT_PROFILES.ios_boot.totalMs,
+  5_000,
+);
+const RETRY_LOGS_ENABLED = isEnvTruthy(process.env.AGENT_DEVICE_RETRY_LOGS);
 
 export async function resolveIosApp(device: DeviceInfo, app: string): Promise<string> {
   const trimmed = app.trim();
@@ -88,6 +93,42 @@ export async function closeIosApp(device: DeviceInfo, app: string): Promise<void
   ]);
 }
 
+export async function uninstallIosApp(device: DeviceInfo, app: string): Promise<{ bundleId: string }> {
+  ensureSimulator(device, 'reinstall');
+  const bundleId = await resolveIosApp(device, app);
+  await ensureBootedSimulator(device);
+  const result = await runCmd('xcrun', ['simctl', 'uninstall', device.id, bundleId], {
+    allowFailure: true,
+  });
+  if (result.exitCode !== 0) {
+    const output = `${result.stdout}\n${result.stderr}`.toLowerCase();
+    if (!output.includes('not installed') && !output.includes('not found') && !output.includes('no such file')) {
+      throw new AppError('COMMAND_FAILED', `simctl uninstall failed for ${bundleId}`, {
+        stdout: result.stdout,
+        stderr: result.stderr,
+        exitCode: result.exitCode,
+      });
+    }
+  }
+  return { bundleId };
+}
+
+export async function installIosApp(device: DeviceInfo, appPath: string): Promise<void> {
+  ensureSimulator(device, 'reinstall');
+  await ensureBootedSimulator(device);
+  await runCmd('xcrun', ['simctl', 'install', device.id, appPath]);
+}
+
+export async function reinstallIosApp(
+  device: DeviceInfo,
+  app: string,
+  appPath: string,
+): Promise<{ bundleId: string }> {
+  const { bundleId } = await uninstallIosApp(device, app);
+  await installIosApp(device, appPath);
+  return { bundleId };
+}
+
 export async function screenshotIos(device: DeviceInfo, outPath: string): Promise<void> {
   if (device.kind === 'simulator') {
     await ensureBootedSimulator(device);
@@ -217,10 +258,17 @@ export async function ensureBootedSimulator(device: DeviceInfo): Promise<void> {
   let bootStatusResult: ExecResult | undefined;
   try {
     await retryWithPolicy(
-      async () => {
-        const currentState = await getSimulatorState(device.id);
-        if (currentState === 'Booted') return;
-        bootResult = await runCmd('xcrun', ['simctl', 'boot', device.id], { allowFailure: true });
+      async ({ deadline: attemptDeadline }) => {
+        if (attemptDeadline?.isExpired()) {
+          throw new AppError('COMMAND_FAILED', 'iOS simulator boot deadline exceeded', {
+            timeoutMs: IOS_BOOT_TIMEOUT_MS,
+          });
+        }
+        const remainingMs = Math.max(1_000, attemptDeadline?.remainingMs() ?? IOS_BOOT_TIMEOUT_MS);
+        bootResult = await runCmd('xcrun', ['simctl', 'boot', device.id], {
+          allowFailure: true,
+          timeoutMs: remainingMs,
+        });
         const bootOutput = `${bootResult.stdout}\n${bootResult.stderr}`.toLowerCase();
         const bootAlreadyDone =
           bootOutput.includes('already booted') || bootOutput.includes('current state: booted');
@@ -233,6 +281,7 @@ export async function ensureBootedSimulator(device: DeviceInfo): Promise<void> {
         }
         bootStatusResult = await runCmd('xcrun', ['simctl', 'bootstatus', device.id, '-b'], {
           allowFailure: true,
+          timeoutMs: remainingMs,
         });
         if (bootStatusResult.exitCode !== 0) {
           throw new AppError('COMMAND_FAILED', 'simctl bootstatus failed', {
@@ -258,11 +307,26 @@ export async function ensureBootedSimulator(device: DeviceInfo): Promise<void> {
             error,
             stdout: bootStatusResult?.stdout ?? bootResult?.stdout,
             stderr: bootStatusResult?.stderr ?? bootResult?.stderr,
+            context: { platform: 'ios', phase: 'boot' },
           });
-          return reason !== 'PERMISSION_DENIED' && reason !== 'TOOL_MISSING';
+          return reason !== 'IOS_BOOT_TIMEOUT' && reason !== 'CI_RESOURCE_STARVATION_SUSPECTED';
+        },
+      },
+      {
+        deadline,
+        phase: 'boot',
+        classifyReason: (error) =>
+          classifyBootFailure({
+            error,
+            stdout: bootStatusResult?.stdout ?? bootResult?.stdout,
+            stderr: bootStatusResult?.stderr ?? bootResult?.stderr,
+            context: { platform: 'ios', phase: 'boot' },
+          }),
+        onEvent: (event: RetryTelemetryEvent) => {
+          if (!RETRY_LOGS_ENABLED) return;
+          process.stderr.write(`[agent-device][retry] ${JSON.stringify(event)}\n`);
         },
       },
-      { deadline },
     );
   } catch (error) {
     const bootStdout = bootResult?.stdout;
@@ -275,6 +339,7 @@ export async function ensureBootedSimulator(device: DeviceInfo): Promise<void> {
       error,
       stdout: bootstatusStdout ?? bootStdout,
       stderr: bootstatusStderr ?? bootStderr,
+      context: { platform: 'ios', phase: 'boot' },
     });
     throw new AppError('COMMAND_FAILED', 'iOS simulator failed to boot', {
       platform: 'ios',
@@ -282,6 +347,7 @@ export async function ensureBootedSimulator(device: DeviceInfo): Promise<void> {
       timeoutMs: IOS_BOOT_TIMEOUT_MS,
       elapsedMs: deadline.elapsedMs(),
       reason,
+      hint: bootFailureHint(reason),
       boot: bootResult
         ? { exitCode: bootExitCode, stdout: bootStdout, stderr: bootStderr }
         : undefined,
@@ -299,6 +365,7 @@ export async function ensureBootedSimulator(device: DeviceInfo): Promise<void> {
 async function getSimulatorState(udid: string): Promise<string | null> {
   const result = await runCmd('xcrun', ['simctl', 'list', 'devices', '-j'], {
     allowFailure: true,
+    timeoutMs: TIMEOUT_PROFILES.ios_boot.operationMs,
   });
   if (result.exitCode !== 0) return null;
   try {

package/src/platforms/ios/runner-client.ts

@@ -7,6 +7,7 @@ import { runCmd, runCmdStreaming, runCmdBackground, type ExecResult, type ExecBa
 import { withRetry } from '../../utils/retry.ts';
 import type { DeviceInfo } from '../../utils/device.ts';
 import net from 'node:net';
+import { bootFailureHint, classifyBootFailure } from '../boot-diagnostics.ts';
 
 export type RunnerCommand = {
   command:
@@ -204,7 +205,10 @@ export async function stopIosRunnerSession(deviceId: string): Promise<void> {
 }
 
 async function ensureBooted(udid: string): Promise<void> {
-  await runCmd('xcrun', ['simctl', 'bootstatus', udid, '-b'], { allowFailure: true });
+  await runCmd('xcrun', ['simctl', 'bootstatus', udid, '-b'], {
+    allowFailure: true,
+    timeoutMs: RUNNER_STARTUP_TIMEOUT_MS,
+  });
 }
 
 async function ensureRunnerSession(
@@ -449,6 +453,12 @@ async function waitForRunner(
     port,
     logPath,
     lastError: lastError ? String(lastError) : undefined,
+    reason: classifyBootFailure({
+      error: lastError,
+      message: 'Runner did not accept connection',
+      context: { platform: 'ios', phase: 'connect' },
+    }),
+    hint: bootFailureHint('IOS_RUNNER_CONNECT_TIMEOUT'),
   });
 }
 
@@ -478,11 +488,19 @@ async function postCommandViaSimulator(
   );
   const body = result.stdout as string;
   if (result.exitCode !== 0) {
+    const reason = classifyBootFailure({
+      message: 'Runner did not accept connection (simctl spawn)',
+      stdout: result.stdout,
+      stderr: result.stderr,
+      context: { platform: 'ios', phase: 'connect' },
+    });
     throw new AppError('COMMAND_FAILED', 'Runner did not accept connection (simctl spawn)', {
       port,
       stdout: result.stdout,
       stderr: result.stderr,
       exitCode: result.exitCode,
+      reason,
+      hint: bootFailureHint(reason),
     });
   }
   return { status: 200, body };

package/src/utils/__tests__/exec.test.ts

@@ -0,0 +1,16 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { runCmd } from '../exec.ts';
+
+test('runCmd enforces timeoutMs and rejects with COMMAND_FAILED', async () => {
+  await assert.rejects(
+    runCmd(process.execPath, ['-e', 'setTimeout(() => {}, 10_000)'], { timeoutMs: 100 }),
+    (error: unknown) => {
+      const err = error as { code?: string; message?: string; details?: Record<string, unknown> };
+      return err?.code === 'COMMAND_FAILED' &&
+        typeof err?.message === 'string' &&
+        err.message.includes('timed out') &&
+        err.details?.timeoutMs === 100;
+    },
+  );
+});

package/src/utils/__tests__/finders.test.ts

@@ -0,0 +1,34 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { findBestMatchesByLocator, findNodeByLocator } from '../finders.ts';
+import type { SnapshotNode } from '../snapshot.ts';
+
+function makeNode(ref: string, label?: string, identifier?: string): SnapshotNode {
+  return {
+    index: Number(ref.replace('e', '')) || 0,
+    ref,
+    type: 'android.widget.TextView',
+    label,
+    identifier,
+    rect: { x: 0, y: 0, width: 100, height: 20 },
+  };
+}
+
+test('findBestMatchesByLocator returns all best-scored matches', () => {
+  const nodes: SnapshotNode[] = [
+    makeNode('e1', 'Continue'),
+    makeNode('e2', 'Continue'),
+    makeNode('e3', 'Continue later'),
+  ];
+  const result = findBestMatchesByLocator(nodes, 'label', 'Continue', { requireRect: true });
+  assert.equal(result.score, 2);
+  assert.equal(result.matches.length, 2);
+  assert.equal(result.matches[0]?.ref, 'e1');
+  assert.equal(result.matches[1]?.ref, 'e2');
+});
+
+test('findNodeByLocator preserves first best match behavior', () => {
+  const nodes: SnapshotNode[] = [makeNode('e1', 'Continue'), makeNode('e2', 'Continue')];
+  const match = findNodeByLocator(nodes, 'label', 'Continue', { requireRect: true });
+  assert.equal(match?.ref, 'e1');
+});

package/src/utils/__tests__/retry.test.ts

@@ -25,3 +25,20 @@ test('retryWithPolicy retries until success', async () => {
   assert.equal(result, 'ok');
   assert.equal(attempts, 3);
 });
+
+test('retryWithPolicy emits telemetry events', async () => {
+  const events: string[] = [];
+  await retryWithPolicy(
+    async ({ attempt }) => {
+      if (attempt === 1) throw new Error('transient');
+      return 'ok';
+    },
+    { maxAttempts: 2, baseDelayMs: 1, maxDelayMs: 1, jitter: 0 },
+    {
+      phase: 'boot',
+      classifyReason: () => 'ANDROID_BOOT_TIMEOUT',
+      onEvent: (event) => events.push(event.event),
+    },
+  );
+  assert.deepEqual(events, ['attempt_failed', 'retry_scheduled', 'succeeded']);
+});

package/src/utils/args.ts

@@ -173,8 +173,10 @@ export function usage(): string {
 CLI to control iOS and Android devices for AI agents.
 
 Commands:
+  boot                                      Ensure target device/simulator is booted and ready
   open [app]                                 Boot device/simulator; optionally launch app
   close [app]                                Close app or just end session
+  reinstall <app> <path>                     Uninstall + install app from binary path
   snapshot [-i] [-c] [-d <depth>] [-s <scope>] [--raw] [--backend ax|xctest]
                                              Capture accessibility tree
     -i                                       Interactive elements only

package/src/utils/exec.ts

@@ -14,6 +14,7 @@ export type ExecOptions = {
   allowFailure?: boolean;
   binaryStdout?: boolean;
   stdin?: string | Buffer;
+  timeoutMs?: number;
 };
 
 export type ExecStreamOptions = ExecOptions & {
@@ -41,6 +42,14 @@ export async function runCmd(
     let stdout = '';
     let stdoutBuffer: Buffer | undefined = options.binaryStdout ? Buffer.alloc(0) : undefined;
     let stderr = '';
+    let didTimeout = false;
+    const timeoutMs = normalizeTimeoutMs(options.timeoutMs);
+    const timeoutHandle = timeoutMs
+      ? setTimeout(() => {
+        didTimeout = true;
+        child.kill('SIGKILL');
+      }, timeoutMs)
+      : null;
 
     if (!options.binaryStdout) child.stdout.setEncoding('utf8');
     child.stderr.setEncoding('utf8');
@@ -66,6 +75,7 @@ export async function runCmd(
     });
 
     child.on('error', (err) => {
+      if (timeoutHandle) clearTimeout(timeoutHandle);
       const code = (err as NodeJS.ErrnoException).code;
       if (code === 'ENOENT') {
         reject(new AppError('TOOL_MISSING', `${cmd} not found in PATH`, { cmd }, err));
@@ -75,7 +85,21 @@ export async function runCmd(
     });
 
     child.on('close', (code) => {
+      if (timeoutHandle) clearTimeout(timeoutHandle);
       const exitCode = code ?? 1;
+      if (didTimeout && timeoutMs) {
+        reject(
+          new AppError('COMMAND_FAILED', `${cmd} timed out after ${timeoutMs}ms`, {
+            cmd,
+            args,
+            stdout,
+            stderr,
+            exitCode,
+            timeoutMs,
+          }),
+        );
+        return;
+      }
       if (exitCode !== 0 && !options.allowFailure) {
         reject(
           new AppError('COMMAND_FAILED', `${cmd} exited with code ${exitCode}`, {
@@ -110,10 +134,18 @@ export function runCmdSync(cmd: string, args: string[], options: ExecOptions = {
     stdio: ['pipe', 'pipe', 'pipe'],
     encoding: options.binaryStdout ? undefined : 'utf8',
     input: options.stdin,
+    timeout: normalizeTimeoutMs(options.timeoutMs),
   });
 
   if (result.error) {
     const code = (result.error as NodeJS.ErrnoException).code;
+    if (code === 'ETIMEDOUT') {
+      throw new AppError('COMMAND_FAILED', `${cmd} timed out after ${normalizeTimeoutMs(options.timeoutMs)}ms`, {
+        cmd,
+        args,
+        timeoutMs: normalizeTimeoutMs(options.timeoutMs),
+      }, result.error);
+    }
     if (code === 'ENOENT') {
       throw new AppError('TOOL_MISSING', `${cmd} not found in PATH`, { cmd }, result.error);
     }
@@ -298,3 +330,10 @@ function resolveWhichArgs(cmd: string): { shell: string; args: string[] } {
   }
   return { shell: 'bash', args: ['-lc', `command -v ${cmd}`] };
 }
+
+function normalizeTimeoutMs(value: number | undefined): number | undefined {
+  if (!Number.isFinite(value)) return undefined;
+  const timeout = Math.floor(value as number);
+  if (timeout <= 0) return undefined;
+  return timeout;
+}

package/src/utils/finders.ts

@@ -6,28 +6,46 @@ export type FindMatchOptions = {
   requireRect?: boolean;
 };
 
+export type FindBestMatches = {
+  matches: SnapshotNode[];
+  score: number;
+};
+
 export function findNodeByLocator(
   nodes: SnapshotNode[],
   locator: FindLocator,
   query: string,
   options: FindMatchOptions = {},
 ): SnapshotNode | null {
+  const best = findBestMatchesByLocator(nodes, locator, query, options);
+  return best.matches[0] ?? null;
+}
+
+export function findBestMatchesByLocator(
+  nodes: SnapshotNode[],
+  locator: FindLocator,
+  query: string,
+  options: FindMatchOptions = {},
+): FindBestMatches {
   const normalizedQuery = normalizeText(query);
-  if (!normalizedQuery) return null;
-  let best: { node: SnapshotNode; score: number } | null = null;
+  if (!normalizedQuery) return { matches: [], score: 0 };
+  let bestScore = 0;
+  const matches: SnapshotNode[] = [];
   for (const node of nodes) {
     if (options.requireRect && !node.rect) continue;
     const score = matchNode(node, locator, normalizedQuery);
     if (score <= 0) continue;
-    if (!best || score > best.score) {
-      best = { node, score };
-      if (score >= 2) {
-        // exact match, keep first exact match
-        break;
-      }
+    if (score > bestScore) {
+      bestScore = score;
+      matches.length = 0;
+      matches.push(node);
+      continue;
+    }
+    if (score === bestScore) {
+      matches.push(node);
     }
   }
-  return best?.node ?? null;
+  return { matches, score: bestScore };
 }
 
 function matchNode(node: SnapshotNode, locator: FindLocator, query: string): number {

package/src/utils/retry.ts

@@ -22,6 +22,33 @@ export type RetryAttemptContext = {
   deadline?: Deadline;
 };
 
+export type TimeoutProfile = {
+  startupMs: number;
+  operationMs: number;
+  totalMs: number;
+};
+
+export type RetryTelemetryEvent = {
+  phase?: string;
+  event: 'attempt_failed' | 'retry_scheduled' | 'succeeded' | 'exhausted';
+  attempt: number;
+  maxAttempts: number;
+  delayMs?: number;
+  elapsedMs?: number;
+  remainingMs?: number;
+  reason?: string;
+};
+
+export function isEnvTruthy(value: string | undefined): boolean {
+  return ['1', 'true', 'yes', 'on'].includes((value ?? '').toLowerCase());
+}
+
+export const TIMEOUT_PROFILES: Record<string, TimeoutProfile> = {
+  ios_boot: { startupMs: 120_000, operationMs: 20_000, totalMs: 120_000 },
+  ios_runner_connect: { startupMs: 120_000, operationMs: 15_000, totalMs: 120_000 },
+  android_boot: { startupMs: 60_000, operationMs: 10_000, totalMs: 60_000 },
+};
+
 const defaultOptions: Required<Pick<RetryOptions, 'attempts' | 'baseDelayMs' | 'maxDelayMs' | 'jitter'>> = {
   attempts: 3,
   baseDelayMs: 200,
@@ -58,7 +85,12 @@ export class Deadline {
 export async function retryWithPolicy<T>(
   fn: (context: RetryAttemptContext) => Promise<T>,
   policy: Partial<RetryPolicy> = {},
-  options: { deadline?: Deadline } = {},
+  options: {
+    deadline?: Deadline;
+    phase?: string;
+    classifyReason?: (error: unknown) => string | undefined;
+    onEvent?: (event: RetryTelemetryEvent) => void;
+  } = {},
 ): Promise<T> {
   const merged: RetryPolicy = {
     maxAttempts: policy.maxAttempts ?? defaultOptions.attempts,
@@ -71,17 +103,55 @@ export async function retryWithPolicy<T>(
   for (let attempt = 1; attempt <= merged.maxAttempts; attempt += 1) {
     if (options.deadline?.isExpired() && attempt > 1) break;
     try {
-      return await fn({ attempt, maxAttempts: merged.maxAttempts, deadline: options.deadline });
+      const result = await fn({ attempt, maxAttempts: merged.maxAttempts, deadline: options.deadline });
+      options.onEvent?.({
+        phase: options.phase,
+        event: 'succeeded',
+        attempt,
+        maxAttempts: merged.maxAttempts,
+        elapsedMs: options.deadline?.elapsedMs(),
+        remainingMs: options.deadline?.remainingMs(),
+      });
+      return result;
     } catch (err) {
       lastError = err;
+      const reason = options.classifyReason?.(err);
+      options.onEvent?.({
+        phase: options.phase,
+        event: 'attempt_failed',
+        attempt,
+        maxAttempts: merged.maxAttempts,
+        elapsedMs: options.deadline?.elapsedMs(),
+        remainingMs: options.deadline?.remainingMs(),
+        reason,
+      });
       if (attempt >= merged.maxAttempts) break;
       if (merged.shouldRetry && !merged.shouldRetry(err, attempt)) break;
       const delay = computeDelay(merged.baseDelayMs, merged.maxDelayMs, merged.jitter, attempt);
       const boundedDelay = options.deadline ? Math.min(delay, options.deadline.remainingMs()) : delay;
       if (boundedDelay <= 0) break;
+      options.onEvent?.({
+        phase: options.phase,
+        event: 'retry_scheduled',
+        attempt,
+        maxAttempts: merged.maxAttempts,
+        delayMs: boundedDelay,
+        elapsedMs: options.deadline?.elapsedMs(),
+        remainingMs: options.deadline?.remainingMs(),
+        reason,
+      });
       await sleep(boundedDelay);
     }
   }
+  options.onEvent?.({
+    phase: options.phase,
+    event: 'exhausted',
+    attempt: merged.maxAttempts,
+    maxAttempts: merged.maxAttempts,
+    elapsedMs: options.deadline?.elapsedMs(),
+    remainingMs: options.deadline?.remainingMs(),
+    reason: options.classifyReason?.(lastError),
+  });
   if (lastError) throw lastError;
   throw new AppError('COMMAND_FAILED', 'retry failed');
 }