Complete issue #39 phase diagnostics telemetry and boot command

Author: thymikee

README.md

@@ -75,7 +75,7 @@ Coordinates:
 - X increases to the right, Y increases downward.
 
 ## Command Index
-- `open`, `close`, `home`, `back`, `app-switcher`
+- `boot`, `open`, `close`, `home`, `back`, `app-switcher`
 - `snapshot`, `find`, `get`
 - `click`, `focus`, `type`, `fill`, `press`, `long-press`, `scroll`, `scrollintoview`, `is`
 - `alert`, `wait`, `screenshot`
@@ -186,8 +186,10 @@ App state:
 
 Boot diagnostics:
 - Boot failures include normalized reason codes in `error.details.reason` (JSON mode) and verbose logs.
-- Reason codes: `BOOT_TIMEOUT`, `DEVICE_UNAVAILABLE`, `DEVICE_OFFLINE`, `PERMISSION_DENIED`, `TOOL_MISSING`, `BOOT_COMMAND_FAILED`, `UNKNOWN`.
+- Reason codes: `IOS_BOOT_TIMEOUT`, `IOS_RUNNER_CONNECT_TIMEOUT`, `ANDROID_BOOT_TIMEOUT`, `ADB_TRANSPORT_UNAVAILABLE`, `CI_RESOURCE_STARVATION_SUSPECTED`, `BOOT_COMMAND_FAILED`, `UNKNOWN`.
 - Android boot waits fail fast for permission/tooling issues and do not always collapse into timeout errors.
+- Use `agent-device boot --platform ios|android` for explicit CI preflight readiness checks.
+- Set `AGENT_DEVICE_RETRY_LOGS=1` to print structured retry telemetry (attempt, phase, delay, elapsed/remaining deadline, reason).
 
 ## App resolution
 - Bundle/package identifiers are accepted directly (e.g., `com.apple.Preferences`).

src/cli.ts

@@ -105,6 +105,13 @@ export async function runCli(argv: string[]): Promise<void> {
         if (logTailStopper) logTailStopper();
         return;
       }
+      if (command === 'boot') {
+        const platform = (response.data as any)?.platform ?? 'unknown';
+        const device = (response.data as any)?.device ?? (response.data as any)?.id ?? 'unknown';
+        process.stdout.write(`Boot ready: ${device} (${platform})\n`);
+        if (logTailStopper) logTailStopper();
+        return;
+      }
       if (command === 'click') {
         const ref = (response.data as any)?.ref ?? '';
         const x = (response.data as any)?.x;

src/core/__tests__/capabilities.test.ts

@@ -37,6 +37,7 @@ test('iOS simulator + Android commands reject iOS devices', () => {
     'app-switcher',
     'apps',
     'back',
+    'boot',
     'click',
     'close',
     'fill',

src/core/capabilities.ts

@@ -19,6 +19,7 @@ const COMMAND_CAPABILITY_MATRIX: Record<string, CommandCapability> = {
   'app-switcher': { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
   apps: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
   back: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
+  boot: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
   click: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
   close: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
   fill: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },

src/daemon/handlers/session.ts

@@ -106,6 +106,32 @@ export async function handleSessionCommands(params: {
     return { ok: true, data: { apps } };
   }
 
+  if (command === 'boot') {
+    const session = sessionStore.get(sessionName);
+    const flags = req.flags ?? {};
+    if (!session && !flags.platform && !flags.device && !flags.udid && !flags.serial) {
+      return {
+        ok: false,
+        error: {
+          code: 'INVALID_ARGS',
+          message: 'boot requires an active session or an explicit device selector (e.g. --platform ios).',
+        },
+      };
+    }
+    const device = session?.device ?? (await resolveTargetDevice(flags));
+    await ensureDeviceReady(device);
+    return {
+      ok: true,
+      data: {
+        platform: device.platform,
+        device: device.name,
+        id: device.id,
+        kind: device.kind,
+        booted: true,
+      },
+    };
+  }
+
   if (command === 'appstate') {
     const session = sessionStore.get(sessionName);
     const flags = req.flags ?? {};

src/platforms/__tests__/boot-diagnostics.test.ts

@@ -1,30 +1,43 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { classifyBootFailure } from '../boot-diagnostics.ts';
+import { bootFailureHint, classifyBootFailure } from '../boot-diagnostics.ts';
 import { AppError } from '../../utils/errors.ts';
 
 test('classifyBootFailure maps timeout errors', () => {
-  const reason = classifyBootFailure({ message: 'bootstatus timed out after 120s' });
-  assert.equal(reason, 'BOOT_TIMEOUT');
+  const reason = classifyBootFailure({
+    message: 'bootstatus timed out after 120s',
+    context: { platform: 'ios', phase: 'boot' },
+  });
+  assert.equal(reason, 'IOS_BOOT_TIMEOUT');
 });
 
 test('classifyBootFailure maps adb offline errors', () => {
-  const reason = classifyBootFailure({ stderr: 'error: device offline' });
-  assert.equal(reason, 'DEVICE_OFFLINE');
+  const reason = classifyBootFailure({
+    stderr: 'error: device offline',
+    context: { platform: 'android', phase: 'transport' },
+  });
+  assert.equal(reason, 'ADB_TRANSPORT_UNAVAILABLE');
 });
 
 test('classifyBootFailure maps tool missing from AppError code', () => {
   const reason = classifyBootFailure({
     error: new AppError('TOOL_MISSING', 'adb not found in PATH'),
+    context: { platform: 'android', phase: 'transport' },
   });
-  assert.equal(reason, 'TOOL_MISSING');
+  assert.equal(reason, 'ADB_TRANSPORT_UNAVAILABLE');
 });
 
 test('classifyBootFailure reads stderr from AppError details', () => {
   const reason = classifyBootFailure({
     error: new AppError('COMMAND_FAILED', 'adb failed', {
       stderr: 'error: device unauthorized',
     }),
+    context: { platform: 'android', phase: 'transport' },
   });
-  assert.equal(reason, 'PERMISSION_DENIED');
+  assert.equal(reason, 'ADB_TRANSPORT_UNAVAILABLE');
+});
+
+test('bootFailureHint returns actionable guidance', () => {
+  const hint = bootFailureHint('IOS_RUNNER_CONNECT_TIMEOUT');
+  assert.equal(hint.includes('xcodebuild logs'), true);
 });

src/platforms/android/devices.ts

@@ -2,11 +2,14 @@ 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, retryWithPolicy, 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 = ['1', 'true', 'yes', 'on'].includes(
+  (process.env.AGENT_DEVICE_RETRY_LOGS ?? '').toLowerCase(),
+);
 
 function adbArgs(serial: string, args: string[]): string[] {
   return ['-s', serial, ...args];
@@ -79,8 +82,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 {
@@ -115,11 +119,26 @@ 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);
@@ -130,26 +149,28 @@ export async function waitForAndroidBoot(serial: string, timeoutMs = 60000): Pro
       error,
       stdout,
       stderr,
+      context: { platform: 'android', phase: 'boot' },
     });
     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 ?? {}),

src/platforms/boot-diagnostics.ts

@@ -1,22 +1,32 @@
 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'
+  | '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' : 'BOOT_COMMAND_FAILED';
+  }
   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 +55,56 @@ export function classifyBootFailure(input: {
     .join('\n')
     .toLowerCase();
 
-  if (haystack.includes('timed out') || haystack.includes('timeout')) return 'BOOT_TIMEOUT';
+  if (platform === 'ios' && (phase === 'connect' || haystack.includes('runner did not accept connection'))) {
+    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('device not found') ||
-    haystack.includes('no devices') ||
-    haystack.includes('unable to locate device') ||
-    haystack.includes('invalid device')
+    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') ||
+    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('unauthorized')
+    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 '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.';
+  }
+}