agent-device 0.3.1 → 0.3.3

package/src/daemon/handlers/interaction.ts

@@ -12,6 +12,7 @@ import {
   formatSelectorFailure,
   parseSelectorChain,
   resolveSelectorChain,
+  splitIsSelectorArgs,
   splitSelectorFromArgs,
 } from '../selectors.ts';
 
@@ -90,6 +91,7 @@ export async function handleInteractionCommands(params: {
       platform: session.device.platform,
       requireRect: true,
       requireUnique: true,
+      disambiguateAmbiguous: true,
     });
     if (!resolved || !resolved.node.rect) {
       return {
@@ -180,7 +182,7 @@ export async function handleInteractionCommands(params: {
         error: { code: 'SESSION_NOT_FOUND', message: 'No active session. Run open first.' },
       };
     }
-    const selectorArgs = splitSelectorFromArgs(req.positionals ?? []);
+    const selectorArgs = splitSelectorFromArgs(req.positionals ?? [], { preferTrailingValue: true });
     if (selectorArgs) {
       if (selectorArgs.rest.length === 0) {
         return { ok: false, error: { code: 'INVALID_ARGS', message: 'fill requires text after selector' } };
@@ -197,6 +199,7 @@ export async function handleInteractionCommands(params: {
         platform: session.device.platform,
         requireRect: true,
         requireUnique: true,
+        disambiguateAmbiguous: true,
       });
       if (!resolved || !resolved.node.rect) {
         return {
@@ -367,8 +370,7 @@ export async function handleInteractionCommands(params: {
         error: { code: 'UNSUPPORTED_OPERATION', message: 'is is not supported on this device' },
       };
     }
-    const selectorArgs = req.positionals.slice(1);
-    const split = splitSelectorFromArgs(selectorArgs);
+    const { split } = splitIsSelectorArgs(req.positionals);
     if (!split) {
       return {
         ok: false,

package/src/daemon/handlers/session.ts

@@ -11,9 +11,48 @@ import { resolveIosAppStateFromSnapshots } from '../app-state.ts';
 import { stopIosRunnerSession } from '../../platforms/ios/runner-client.ts';
 import { attachRefs, type RawSnapshotNode, type SnapshotState } from '../../utils/snapshot.ts';
 import { pruneGroupNodes } from '../snapshot-processing.ts';
-import { buildSelectorChainForNode, parseSelectorChain, resolveSelectorChain, splitSelectorFromArgs } from '../selectors.ts';
+import {
+  buildSelectorChainForNode,
+  resolveSelectorChain,
+  splitIsSelectorArgs,
+  splitSelectorFromArgs,
+  tryParseSelectorChain,
+} from '../selectors.ts';
 import { inferFillText, uniqueStrings } from '../action-utils.ts';
 
+type ReinstallOps = {
+  ios: (device: DeviceInfo, app: string, appPath: string) => Promise<{ bundleId: string }>;
+  android: (device: DeviceInfo, app: string, appPath: string) => Promise<{ package: string }>;
+};
+
+function hasExplicitDeviceSelector(flags: DaemonRequest['flags'] | undefined): boolean {
+  return Boolean(flags?.platform || flags?.device || flags?.udid || flags?.serial);
+}
+
+async function resolveCommandDevice(params: {
+  session: SessionState | undefined;
+  flags: DaemonRequest['flags'] | undefined;
+  ensureReadyFn: typeof ensureDeviceReady;
+  ensureReady?: boolean;
+}): Promise<DeviceInfo> {
+  const device = params.session?.device ?? (await resolveTargetDevice(params.flags ?? {}));
+  if (params.ensureReady !== false) {
+    await params.ensureReadyFn(device);
+  }
+  return device;
+}
+
+const defaultReinstallOps: ReinstallOps = {
+  ios: async (device, app, appPath) => {
+    const { reinstallIosApp } = await import('../../platforms/ios/index.ts');
+    return await reinstallIosApp(device, app, appPath);
+  },
+  android: async (device, app, appPath) => {
+    const { reinstallAndroidApp } = await import('../../platforms/android/index.ts');
+    return await reinstallAndroidApp(device, app, appPath);
+  },
+};
+
 export async function handleSessionCommands(params: {
   req: DaemonRequest;
   sessionName: string;
@@ -21,9 +60,21 @@ export async function handleSessionCommands(params: {
   sessionStore: SessionStore;
   invoke: (req: DaemonRequest) => Promise<DaemonResponse>;
   dispatch?: typeof dispatchCommand;
+  ensureReady?: typeof ensureDeviceReady;
+  reinstallOps?: ReinstallOps;
 }): Promise<DaemonResponse | null> {
-  const { req, sessionName, logPath, sessionStore, invoke, dispatch: dispatchOverride } = params;
+  const {
+    req,
+    sessionName,
+    logPath,
+    sessionStore,
+    invoke,
+    dispatch: dispatchOverride,
+    ensureReady: ensureReadyOverride,
+    reinstallOps = defaultReinstallOps,
+  } = params;
   const dispatch = dispatchOverride ?? dispatchCommand;
+  const ensureReady = ensureReadyOverride ?? ensureDeviceReady;
   const command = req.command;
 
   if (command === 'session_list') {
@@ -72,7 +123,7 @@ export async function handleSessionCommands(params: {
   if (command === 'apps') {
     const session = sessionStore.get(sessionName);
     const flags = req.flags ?? {};
-    if (!session && !flags.platform && !flags.device && !flags.udid && !flags.serial) {
+    if (!session && !hasExplicitDeviceSelector(flags)) {
       return {
         ok: false,
         error: {
@@ -81,8 +132,7 @@ export async function handleSessionCommands(params: {
         },
       };
     }
-    const device = session?.device ?? (await resolveTargetDevice(flags));
-    await ensureDeviceReady(device);
+    const device = await resolveCommandDevice({ session, flags, ensureReadyFn: ensureReady, ensureReady: true });
     if (!isCommandSupportedOnDevice('apps', device)) {
       return { ok: false, error: { code: 'UNSUPPORTED_OPERATION', message: 'apps is not supported on this device' } };
     }
@@ -106,11 +156,39 @@ export async function handleSessionCommands(params: {
     return { ok: true, data: { apps } };
   }
 
-  if (command === 'appstate') {
+  if (command === 'boot') {
     const session = sessionStore.get(sessionName);
     const flags = req.flags ?? {};
+    if (!session && !hasExplicitDeviceSelector(flags)) {
+      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);
+    if (!isCommandSupportedOnDevice('boot', device)) {
+      return { ok: false, error: { code: 'UNSUPPORTED_OPERATION', message: 'boot is not supported on this device' } };
+    }
+    await ensureReady(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 ?? {};
+    const device = await resolveCommandDevice({ session, flags, ensureReadyFn: ensureReady, ensureReady: true });
     if (device.platform === 'ios') {
       if (session?.appBundleId) {
         return {
@@ -151,6 +229,62 @@ export async function handleSessionCommands(params: {
     };
   }
 
+  if (command === 'reinstall') {
+    const session = sessionStore.get(sessionName);
+    const flags = req.flags ?? {};
+    if (!session && !hasExplicitDeviceSelector(flags)) {
+      return {
+        ok: false,
+        error: {
+          code: 'INVALID_ARGS',
+          message: 'reinstall requires an active session or an explicit device selector (e.g. --platform ios).',
+        },
+      };
+    }
+    const app = req.positionals?.[0]?.trim();
+    const appPathInput = req.positionals?.[1]?.trim();
+    if (!app || !appPathInput) {
+      return {
+        ok: false,
+        error: { code: 'INVALID_ARGS', message: 'reinstall requires: reinstall <app> <path-to-app-binary>' },
+      };
+    }
+    const appPath = SessionStore.expandHome(appPathInput);
+    if (!fs.existsSync(appPath)) {
+      return {
+        ok: false,
+        error: { code: 'INVALID_ARGS', message: `App binary not found: ${appPath}` },
+      };
+    }
+    const device = await resolveCommandDevice({ session, flags, ensureReadyFn: ensureReady, ensureReady: false });
+    if (!isCommandSupportedOnDevice('reinstall', device)) {
+      return {
+        ok: false,
+        error: { code: 'UNSUPPORTED_OPERATION', message: 'reinstall is not supported on this device' },
+      };
+    }
+    let reinstallData:
+      | { platform: 'ios'; appId: string; bundleId: string }
+      | { platform: 'android'; appId: string; package: string };
+    if (device.platform === 'ios') {
+      const iosResult = await reinstallOps.ios(device, app, appPath);
+      reinstallData = { platform: 'ios', appId: iosResult.bundleId, bundleId: iosResult.bundleId };
+    } else {
+      const androidResult = await reinstallOps.android(device, app, appPath);
+      reinstallData = { platform: 'android', appId: androidResult.package, package: androidResult.package };
+    }
+    const result = { app, appPath, ...reinstallData };
+    if (session) {
+      sessionStore.recordAction(session, {
+        command,
+        positionals: req.positionals ?? [],
+        flags: req.flags ?? {},
+        result,
+      });
+    }
+    return { ok: true, data: result };
+  }
+
   if (command === 'open') {
     if (sessionStore.has(sessionName)) {
       const session = sessionStore.get(sessionName);
@@ -193,7 +327,6 @@ export async function handleSessionCommands(params: {
       return { ok: true, data: { session: sessionName, appName, appBundleId } };
     }
     const device = await resolveTargetDevice(req.flags ?? {});
-    await ensureDeviceReady(device);
     const inUse = sessionStore.toArray().find((s) => s.device.id === device.id);
     if (inUse) {
       return {
@@ -269,7 +402,9 @@ export async function handleSessionCommands(params: {
           flags: action.flags ?? {},
         });
         if (response.ok) continue;
-        if (!shouldUpdate) return response;
+        if (!shouldUpdate) {
+          return withReplayFailureContext(response, action, index, resolved);
+        }
         const nextAction = await healReplayAction({
           action,
           sessionName,
@@ -278,7 +413,7 @@ export async function handleSessionCommands(params: {
           dispatch,
         });
         if (!nextAction) {
-          return response;
+          return withReplayFailureContext(response, action, index, resolved);
         }
         actions[index] = nextAction;
         response = await invoke({
@@ -289,7 +424,7 @@ export async function handleSessionCommands(params: {
           flags: nextAction.flags ?? {},
         });
         if (!response.ok) {
-          return response;
+          return withReplayFailureContext(response, nextAction, index, resolved);
         }
         healed += 1;
       }
@@ -334,6 +469,42 @@ export async function handleSessionCommands(params: {
   return null;
 }
 
+function withReplayFailureContext(
+  response: DaemonResponse,
+  action: SessionAction,
+  index: number,
+  replayPath: string,
+): DaemonResponse {
+  if (response.ok) return response;
+  const step = index + 1;
+  const summary = formatReplayActionSummary(action);
+  const details = {
+    ...(response.error.details ?? {}),
+    replayPath,
+    step,
+    action: action.command,
+    positionals: action.positionals ?? [],
+  };
+  return {
+    ok: false,
+    error: {
+      code: response.error.code,
+      message: `Replay failed at step ${step} (${summary}): ${response.error.message}`,
+      details,
+    },
+  };
+}
+
+function formatReplayActionSummary(action: SessionAction): string {
+  const values = (action.positionals ?? []).map((value) => {
+    const trimmed = value.trim();
+    if (/^-?\d+(\.\d+)?$/.test(trimmed)) return trimmed;
+    if (trimmed.startsWith('@')) return trimmed;
+    return JSON.stringify(trimmed);
+  });
+  return [action.command, ...values].join(' ');
+}
+
 async function healReplayAction(params: {
   action: SessionAction;
   sessionName: string;
@@ -349,11 +520,13 @@ async function healReplayAction(params: {
   const snapshot = await captureSnapshotForReplay(session, action, logPath, requiresRect, dispatch, sessionStore);
   const selectorCandidates = collectReplaySelectorCandidates(action);
   for (const candidate of selectorCandidates) {
-    const chain = parseSelectorChain(candidate);
+    const chain = tryParseSelectorChain(candidate);
+    if (!chain) continue;
     const resolved = resolveSelectorChain(snapshot.nodes, chain, {
       platform: session.device.platform,
       requireRect: requiresRect,
       requireUnique: true,
+      disambiguateAmbiguous: requiresRect,
     });
     if (!resolved) continue;
     const selectorChain = buildSelectorChainForNode(resolved.node, session.device.platform, {
@@ -383,9 +556,8 @@ async function healReplayAction(params: {
       };
     }
     if (action.command === 'is') {
-      const predicate = action.positionals?.[0];
+      const { predicate, split } = splitIsSelectorArgs(action.positionals);
       if (!predicate) continue;
-      const split = splitSelectorFromArgs(action.positionals.slice(1));
       const expectedText = split?.rest.join(' ').trim() ?? '';
       const nextPositionals = [predicate, selectorExpression];
       if (predicate === 'text' && expectedText.length > 0) {
@@ -476,7 +648,7 @@ function collectReplaySelectorCandidates(action: SessionAction): string[] {
     }
   }
   if (action.command === 'is') {
-    const split = splitSelectorFromArgs(action.positionals.slice(1));
+    const { split } = splitIsSelectorArgs(action.positionals);
     if (split) {
       result.push(split.selectorExpression);
     }

package/src/daemon/selectors.ts

@@ -85,25 +85,38 @@ export function resolveSelectorChain(
     platform: 'ios' | 'android';
     requireRect?: boolean;
     requireUnique?: boolean;
+    disambiguateAmbiguous?: boolean;
   },
 ): SelectorResolution | null {
   const requireRect = options.requireRect ?? false;
   const requireUnique = options.requireUnique ?? true;
+  const disambiguateAmbiguous = options.disambiguateAmbiguous ?? false;
   const diagnostics: SelectorDiagnostics[] = [];
   for (let i = 0; i < chain.selectors.length; i += 1) {
     const selector = chain.selectors[i];
-    const matches = nodes.filter((node) => {
-      if (requireRect && !node.rect) return false;
-      return matchesSelector(node, selector, options.platform);
+    const summary = analyzeSelectorMatches(nodes, selector, {
+      platform: options.platform,
+      requireRect,
     });
-    diagnostics.push({ selector: selector.raw, matches: matches.length });
-    if (matches.length === 0) continue;
-    if (requireUnique && matches.length !== 1) continue;
+    diagnostics.push({ selector: selector.raw, matches: summary.count });
+    if (summary.count === 0 || !summary.firstNode) continue;
+    if (requireUnique && summary.count !== 1) {
+      if (!disambiguateAmbiguous) continue;
+      const disambiguatedNode = summary.disambiguated;
+      if (!disambiguatedNode) continue;
+      return {
+        node: disambiguatedNode,
+        selector,
+        selectorIndex: i,
+        matches: summary.count,
+        diagnostics,
+      };
+    }
     return {
-      node: matches[0],
+      node: summary.firstNode,
       selector,
       selectorIndex: i,
-      matches: matches.length,
+      matches: summary.count,
       diagnostics,
     };
   }
@@ -122,13 +135,13 @@ export function findSelectorChainMatch(
   const diagnostics: SelectorDiagnostics[] = [];
   for (let i = 0; i < chain.selectors.length; i += 1) {
     const selector = chain.selectors[i];
-    const matches = nodes.filter((node) => {
-      if (requireRect && !node.rect) return false;
-      return matchesSelector(node, selector, options.platform);
+    const matches = countSelectorMatchesOnly(nodes, selector, {
+      platform: options.platform,
+      requireRect,
     });
-    diagnostics.push({ selector: selector.raw, matches: matches.length });
-    if (matches.length > 0) {
-      return { selectorIndex: i, selector, matches: matches.length, diagnostics };
+    diagnostics.push({ selector: selector.raw, matches });
+    if (matches > 0) {
+      return { selectorIndex: i, selector, matches, diagnostics };
     }
   }
   return null;
@@ -162,21 +175,51 @@ export function isSelectorToken(token: string): boolean {
   return ALL_KEYS.has(trimmed.toLowerCase() as SelectorKey);
 }
 
-export function splitSelectorFromArgs(args: string[]): { selectorExpression: string; rest: string[] } | null {
+export function splitSelectorFromArgs(
+  args: string[],
+  options: { preferTrailingValue?: boolean } = {},
+): { selectorExpression: string; rest: string[] } | null {
   if (args.length === 0) return null;
+  const preferTrailingValue = options.preferTrailingValue ?? false;
   let i = 0;
+  const boundaries: number[] = [];
   while (i < args.length && isSelectorToken(args[i])) {
     i += 1;
+    const candidate = args.slice(0, i).join(' ').trim();
+    if (!candidate) continue;
+    if (tryParseSelectorChain(candidate)) {
+      boundaries.push(i);
+    }
+  }
+  if (boundaries.length === 0) return null;
+  let boundary = boundaries[boundaries.length - 1];
+  if (preferTrailingValue) {
+    for (let j = boundaries.length - 1; j >= 0; j -= 1) {
+      if (boundaries[j] < args.length) {
+        boundary = boundaries[j];
+        break;
+      }
+    }
   }
-  if (i === 0) return null;
-  const selectorExpression = args.slice(0, i).join(' ').trim();
+  const selectorExpression = args.slice(0, boundary).join(' ').trim();
   if (!selectorExpression) return null;
   return {
     selectorExpression,
-    rest: args.slice(i),
+    rest: args.slice(boundary),
   };
 }
 
+export function splitIsSelectorArgs(positionals: string[]): {
+  predicate: string;
+  split: { selectorExpression: string; rest: string[] } | null;
+} {
+  const predicate = positionals[0] ?? '';
+  const split = splitSelectorFromArgs(positionals.slice(1), {
+    preferTrailingValue: predicate === 'text',
+  });
+  return { predicate, split };
+}
+
 export function isNodeVisible(node: SnapshotNode): boolean {
   if (node.hittable === true) return true;
   if (!node.rect) return false;
@@ -318,7 +361,7 @@ function splitByFallback(expression: string): string[] {
   let quote: '"' | "'" | null = null;
   for (let i = 0; i < expression.length; i += 1) {
     const ch = expression[i];
-    if ((ch === '"' || ch === "'") && expression[i - 1] !== '\\') {
+    if ((ch === '"' || ch === "'") && !isEscapedQuote(expression, i)) {
       if (!quote) {
         quote = ch;
       } else if (quote === ch) {
@@ -353,7 +396,7 @@ function tokenize(segment: string): string[] {
   let quote: '"' | "'" | null = null;
   for (let i = 0; i < segment.length; i += 1) {
     const ch = segment[i];
-    if ((ch === '"' || ch === "'") && segment[i - 1] !== '\\') {
+    if ((ch === '"' || ch === "'") && !isEscapedQuote(segment, i)) {
       if (!quote) {
         quote = ch;
       } else if (quote === ch) {
@@ -421,3 +464,78 @@ function normalizeSelectorText(value: string | undefined): string | null {
   if (!trimmed) return null;
   return trimmed;
 }
+
+function analyzeSelectorMatches(
+  nodes: SnapshotState['nodes'],
+  selector: Selector,
+  options: { platform: 'ios' | 'android'; requireRect: boolean },
+): { count: number; firstNode: SnapshotNode | null; disambiguated: SnapshotNode | null } {
+  let count = 0;
+  let firstNode: SnapshotNode | null = null;
+  let best: SnapshotNode | null = null;
+  let tie = false;
+  for (const node of nodes) {
+    if (options.requireRect && !node.rect) continue;
+    if (!matchesSelector(node, selector, options.platform)) continue;
+    count += 1;
+    if (!firstNode) {
+      firstNode = node;
+    }
+    if (!best) {
+      best = node;
+      tie = false;
+      continue;
+    }
+    const comparison = compareDisambiguationCandidates(node, best);
+    if (comparison > 0) {
+      best = node;
+      tie = false;
+      continue;
+    }
+    if (comparison === 0) {
+      tie = true;
+    }
+  }
+  return {
+    count,
+    firstNode,
+    disambiguated: tie ? null : best,
+  };
+}
+
+function countSelectorMatchesOnly(
+  nodes: SnapshotState['nodes'],
+  selector: Selector,
+  options: { platform: 'ios' | 'android'; requireRect: boolean },
+): number {
+  let count = 0;
+  for (const node of nodes) {
+    if (options.requireRect && !node.rect) continue;
+    if (!matchesSelector(node, selector, options.platform)) continue;
+    count += 1;
+  }
+  return count;
+}
+
+function compareDisambiguationCandidates(a: SnapshotNode, b: SnapshotNode): number {
+  const depthA = a.depth ?? 0;
+  const depthB = b.depth ?? 0;
+  if (depthA !== depthB) return depthA > depthB ? 1 : -1;
+  const areaA = areaOfNode(a);
+  const areaB = areaOfNode(b);
+  if (areaA !== areaB) return areaA < areaB ? 1 : -1;
+  return 0;
+}
+
+function areaOfNode(node: SnapshotNode): number {
+  if (!node.rect) return Number.POSITIVE_INFINITY;
+  return node.rect.width * node.rect.height;
+}
+
+function isEscapedQuote(source: string, index: number): boolean {
+  let backslashCount = 0;
+  for (let i = index - 1; i >= 0 && source[i] === '\\'; i -= 1) {
+    backslashCount += 1;
+  }
+  return backslashCount % 2 === 1;
+}

package/src/daemon/snapshot-processing.ts

@@ -78,10 +78,14 @@ export function pruneGroupNodes(nodes: RawSnapshotNode[]): RawSnapshotNode[] {
 }
 
 export function normalizeType(type: string): string {
-  let value = type.replace(/XCUIElementType/gi, '').toLowerCase();
+  let value = type.trim().replace(/XCUIElementType/gi, '').toLowerCase();
   if (value.startsWith('ax')) {
     value = value.replace(/^ax/, '');
   }
+  const lastSeparator = Math.max(value.lastIndexOf('.'), value.lastIndexOf('/'));
+  if (lastSeparator !== -1) {
+    value = value.slice(lastSeparator + 1);
+  }
   return value;
 }
 

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

@@ -1,23 +1,38 @@
 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', () => {
+test('classifyBootFailure maps tool missing from AppError code (android)', () => {
   const reason = classifyBootFailure({
     error: new AppError('TOOL_MISSING', 'adb not found in PATH'),
+    context: { platform: 'android', phase: 'transport' },
+  });
+  assert.equal(reason, 'ADB_TRANSPORT_UNAVAILABLE');
+});
+
+test('classifyBootFailure maps tool missing from AppError code (ios)', () => {
+  const reason = classifyBootFailure({
+    error: new AppError('TOOL_MISSING', 'xcrun not found in PATH'),
+    context: { platform: 'ios', phase: 'boot' },
   });
-  assert.equal(reason, 'TOOL_MISSING');
+  assert.equal(reason, 'IOS_TOOL_MISSING');
 });
 
 test('classifyBootFailure reads stderr from AppError details', () => {
@@ -25,6 +40,20 @@ test('classifyBootFailure reads stderr from AppError details', () => {
     error: new AppError('COMMAND_FAILED', 'adb failed', {
       stderr: 'error: device unauthorized',
     }),
+    context: { platform: 'android', phase: 'transport' },
+  });
+  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);
+});
+
+test('connect phase does not classify non-timeout errors as connect timeout', () => {
+  const reason = classifyBootFailure({
+    message: 'Runner returned malformed JSON payload',
+    context: { platform: 'ios', phase: 'connect' },
   });
-  assert.equal(reason, 'PERMISSION_DENIED');
+  assert.equal(reason, 'BOOT_COMMAND_FAILED');
 });

package/src/platforms/android/__tests__/index.test.ts

@@ -1,5 +1,6 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
+import { parseAndroidLaunchComponent } from '../index.ts';
 import { findBounds, parseUiHierarchy } from '../ui-hierarchy.ts';
 
 test('parseUiHierarchy reads double-quoted Android node attributes', () => {
@@ -72,3 +73,19 @@ test('findBounds ignores bounds-like fragments inside other attribute values', (
 
   assert.deepEqual(findBounds(xml, 'target'), { x: 200, y: 350 });
 });
+
+test('parseAndroidLaunchComponent extracts final resolved component', () => {
+  const stdout = [
+    'priority=0 preferredOrder=0 match=0x108000 specificIndex=-1 isDefault=true',
+    'com.boatsgroup.boattrader/com.boatsgroup.boattrader.MainActivity',
+  ].join('\n');
+  assert.equal(
+    parseAndroidLaunchComponent(stdout),
+    'com.boatsgroup.boattrader/com.boatsgroup.boattrader.MainActivity',
+  );
+});
+
+test('parseAndroidLaunchComponent returns null when no component is present', () => {
+  const stdout = 'No activity found';
+  assert.equal(parseAndroidLaunchComponent(stdout), null);
+});