agent-device 0.3.1 → 0.3.3

package/src/platforms/android/devices.ts

@@ -2,11 +2,12 @@ import { runCmd, whichCmd } from '../../utils/exec.ts';
 import type { ExecResult } from '../../utils/exec.ts';
 import { AppError, asAppError } 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 EMULATOR_SERIAL_PREFIX = 'emulator-';
 const ANDROID_BOOT_POLL_MS = 1000;
+const RETRY_LOGS_ENABLED = isEnvTruthy(process.env.AGENT_DEVICE_RETRY_LOGS);
 
 function adbArgs(serial: string, args: string[]): string[] {
   return ['-s', serial, ...args];
@@ -16,9 +17,13 @@ function isEmulatorSerial(serial: string): boolean {
   return serial.startsWith(EMULATOR_SERIAL_PREFIX);
 }
 
-async function readAndroidBootProp(serial: string): Promise<ExecResult> {
+async function readAndroidBootProp(
+  serial: string,
+  timeoutMs = TIMEOUT_PROFILES.android_boot.operationMs,
+): Promise<ExecResult> {
   return runCmd('adb', adbArgs(serial, ['shell', 'getprop', 'sys.boot_completed']), {
     allowFailure: true,
+    timeoutMs,
   });
 }
 
@@ -27,6 +32,7 @@ async function resolveAndroidDeviceName(serial: string, rawModel: string): Promi
   if (!isEmulatorSerial(serial)) return modelName || serial;
   const avd = await runCmd('adb', adbArgs(serial, ['emu', 'avd', 'name']), {
     allowFailure: true,
+    timeoutMs: TIMEOUT_PROFILES.android_boot.operationMs,
   });
   const avdName = avd.stdout.trim();
   if (avd.exitCode === 0 && avdName) {
@@ -41,7 +47,9 @@ export async function listAndroidDevices(): Promise<DeviceInfo[]> {
     throw new AppError('TOOL_MISSING', 'adb not found in PATH');
   }
 
-  const result = await runCmd('adb', ['devices', '-l']);
+  const result = await runCmd('adb', ['devices', '-l'], {
+    timeoutMs: TIMEOUT_PROFILES.android_boot.operationMs,
+  });
   const lines = result.stdout.split('\n').map((l: string) => l.trim());
   const entries = lines
     .filter((line) => line.length > 0 && !line.startsWith('List of devices'))
@@ -79,8 +87,9 @@ export async function isAndroidBooted(serial: string): Promise<boolean> {
 }
 
 export async function waitForAndroidBoot(serial: string, timeoutMs = 60000): Promise<void> {
-  const deadline = Deadline.fromTimeoutMs(timeoutMs);
-  const maxAttempts = Math.max(1, Math.ceil(timeoutMs / ANDROID_BOOT_POLL_MS));
+  const timeoutBudget = timeoutMs;
+  const deadline = Deadline.fromTimeoutMs(timeoutBudget);
+  const maxAttempts = Math.max(1, Math.ceil(timeoutBudget / ANDROID_BOOT_POLL_MS));
   let lastBootResult: ExecResult | undefined;
   let timedOut = false;
   try {
@@ -95,7 +104,11 @@ export async function waitForAndroidBoot(serial: string, timeoutMs = 60000): Pro
             message: 'timeout',
           });
         }
-        const result = await readAndroidBootProp(serial);
+        const remainingMs = Math.max(1_000, attemptDeadline?.remainingMs() ?? timeoutBudget);
+        const result = await readAndroidBootProp(
+          serial,
+          Math.min(remainingMs, TIMEOUT_PROFILES.android_boot.operationMs),
+        );
         lastBootResult = result;
         if (result.stdout.trim() === '1') return;
         throw new AppError('COMMAND_FAILED', 'Android device is still booting', {
@@ -115,41 +128,61 @@ export async function waitForAndroidBoot(serial: string, timeoutMs = 60000): Pro
             error,
             stdout: lastBootResult?.stdout,
             stderr: lastBootResult?.stderr,
+            context: { platform: 'android', phase: 'boot' },
           });
-          return reason !== 'PERMISSION_DENIED' && reason !== 'TOOL_MISSING' && reason !== 'BOOT_TIMEOUT';
+          return reason !== 'ADB_TRANSPORT_UNAVAILABLE' && reason !== 'ANDROID_BOOT_TIMEOUT';
+        },
+      },
+      {
+        deadline,
+        phase: 'boot',
+        classifyReason: (error) =>
+          classifyBootFailure({
+            error,
+            stdout: lastBootResult?.stdout,
+            stderr: lastBootResult?.stderr,
+            context: { platform: 'android', phase: 'boot' },
+          }),
+        onEvent: (event: RetryTelemetryEvent) => {
+          if (!RETRY_LOGS_ENABLED) return;
+          process.stderr.write(`[agent-device][retry] ${JSON.stringify(event)}\n`);
         },
       },
-      { deadline },
     );
   } catch (error) {
     const appErr = asAppError(error);
     const stdout = lastBootResult?.stdout;
     const stderr = lastBootResult?.stderr;
     const exitCode = lastBootResult?.exitCode;
-    const reason = classifyBootFailure({
+    let reason = classifyBootFailure({
       error,
       stdout,
       stderr,
+      context: { platform: 'android', phase: 'boot' },
     });
+    if (reason === 'BOOT_COMMAND_FAILED' && appErr.message === 'Android device is still booting') {
+      reason = 'ANDROID_BOOT_TIMEOUT';
+    }
     const baseDetails = {
       serial,
-      timeoutMs,
+      timeoutMs: timeoutBudget,
       elapsedMs: deadline.elapsedMs(),
       reason,
+      hint: bootFailureHint(reason),
       stdout,
       stderr,
       exitCode,
     };
-    if (timedOut || reason === 'BOOT_TIMEOUT') {
+    if (timedOut || reason === 'ANDROID_BOOT_TIMEOUT') {
       throw new AppError('COMMAND_FAILED', 'Android device did not finish booting in time', baseDetails);
     }
-    if (appErr.code === 'TOOL_MISSING' || reason === 'TOOL_MISSING') {
+    if (appErr.code === 'TOOL_MISSING') {
       throw new AppError('TOOL_MISSING', appErr.message, {
         ...baseDetails,
         ...(appErr.details ?? {}),
       });
     }
-    if (reason === 'PERMISSION_DENIED' || reason === 'DEVICE_UNAVAILABLE' || reason === 'DEVICE_OFFLINE') {
+    if (reason === 'ADB_TRANSPORT_UNAVAILABLE') {
       throw new AppError('COMMAND_FAILED', appErr.message, {
         ...baseDetails,
         ...(appErr.details ?? {}),

package/src/platforms/android/index.ts

@@ -187,22 +187,70 @@ export async function openAndroidApp(
     );
     return;
   }
-  await runCmd(
+  try {
+    await runCmd(
+      'adb',
+      adbArgs(device, [
+        'shell',
+        'am',
+        'start',
+        '-a',
+        'android.intent.action.MAIN',
+        '-c',
+        'android.intent.category.DEFAULT',
+        '-c',
+        'android.intent.category.LAUNCHER',
+        '-p',
+        resolved.value,
+      ]),
+    );
+    return;
+  } catch (initialError) {
+    const component = await resolveAndroidLaunchComponent(device, resolved.value);
+    if (!component) throw initialError;
+    await runCmd(
+      'adb',
+      adbArgs(device, [
+        'shell',
+        'am',
+        'start',
+        '-a',
+        'android.intent.action.MAIN',
+        '-c',
+        'android.intent.category.DEFAULT',
+        '-c',
+        'android.intent.category.LAUNCHER',
+        '-n',
+        component,
+      ]),
+    );
+  }
+}
+
+async function resolveAndroidLaunchComponent(
+  device: DeviceInfo,
+  packageName: string,
+): Promise<string | null> {
+  const result = await runCmd(
     'adb',
-    adbArgs(device, [
-      'shell',
-      'am',
-      'start',
-      '-a',
-      'android.intent.action.MAIN',
-      '-c',
-      'android.intent.category.DEFAULT',
-      '-c',
-      'android.intent.category.LAUNCHER',
-      '-p',
-      resolved.value,
-    ]),
+    adbArgs(device, ['shell', 'cmd', 'package', 'resolve-activity', '--brief', packageName]),
+    { allowFailure: true },
   );
+  if (result.exitCode !== 0) return null;
+  return parseAndroidLaunchComponent(result.stdout);
+}
+
+export function parseAndroidLaunchComponent(stdout: string): string | null {
+  const lines = stdout
+    .split('\n')
+    .map((line: string) => line.trim())
+    .filter(Boolean);
+  for (let index = lines.length - 1; index >= 0; index -= 1) {
+    const line = lines[index];
+    if (!line.includes('/')) continue;
+    return line.split(/\s+/)[0];
+  }
+  return null;
 }
 
 export async function openAndroidDevice(device: DeviceInfo): Promise<void> {
@@ -224,6 +272,45 @@ export async function closeAndroidApp(device: DeviceInfo, app: string): Promise<
   await runCmd('adb', adbArgs(device, ['shell', 'am', 'force-stop', resolved.value]));
 }
 
+export async function uninstallAndroidApp(
+  device: DeviceInfo,
+  app: string,
+): Promise<{ package: string }> {
+  const resolved = await resolveAndroidApp(device, app);
+  if (resolved.type === 'intent') {
+    throw new AppError('INVALID_ARGS', 'reinstall requires a package name, not an intent');
+  }
+  const result = await runCmd('adb', adbArgs(device, ['uninstall', resolved.value]), { allowFailure: true });
+  if (result.exitCode !== 0) {
+    const output = `${result.stdout}\n${result.stderr}`.toLowerCase();
+    if (!output.includes('unknown package') && !output.includes('not installed')) {
+      throw new AppError('COMMAND_FAILED', `adb uninstall failed for ${resolved.value}`, {
+        stdout: result.stdout,
+        stderr: result.stderr,
+        exitCode: result.exitCode,
+      });
+    }
+  }
+  return { package: resolved.value };
+}
+
+export async function installAndroidApp(device: DeviceInfo, appPath: string): Promise<void> {
+  await runCmd('adb', adbArgs(device, ['install', appPath]));
+}
+
+export async function reinstallAndroidApp(
+  device: DeviceInfo,
+  app: string,
+  appPath: string,
+): Promise<{ package: string }> {
+  if (!device.booted) {
+    await waitForAndroidBoot(device.id);
+  }
+  const { package: pkg } = await uninstallAndroidApp(device, app);
+  await installAndroidApp(device, appPath);
+  return { package: pkg };
+}
+
 export async function pressAndroid(device: DeviceInfo, x: number, y: number): Promise<void> {
   await runCmd('adb', adbArgs(device, ['shell', 'input', 'tap', String(x), String(y)]));
 }

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']);
+});