agent-device 0.4.1 → 0.4.2

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

@@ -3,7 +3,7 @@ import assert from 'node:assert/strict';
 import { promises as fs } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { openAndroidApp, parseAndroidLaunchComponent, swipeAndroid } from '../index.ts';
+import { inferAndroidAppName, listAndroidApps, openAndroidApp, parseAndroidLaunchComponent, swipeAndroid } from '../index.ts';
 import type { DeviceInfo } from '../../../utils/device.ts';
 import { AppError } from '../../../utils/errors.ts';
 import { findBounds, parseUiHierarchy } from '../ui-hierarchy.ts';
@@ -95,6 +95,123 @@ test('parseAndroidLaunchComponent returns null when no component is present', ()
   assert.equal(parseAndroidLaunchComponent(stdout), null);
 });
 
+test('inferAndroidAppName derives readable names from package ids', () => {
+  assert.equal(inferAndroidAppName('com.android.settings'), 'Settings');
+  assert.equal(inferAndroidAppName('com.google.android.apps.maps'), 'Maps');
+  assert.equal(inferAndroidAppName('org.mozilla.firefox'), 'Firefox');
+  assert.equal(inferAndroidAppName('com.facebook.katana'), 'Katana');
+  assert.equal(inferAndroidAppName('single'), 'Single');
+  assert.equal(inferAndroidAppName('com.android.app.services'), 'Services');
+});
+
+test('listAndroidApps returns launchable apps with inferred names', async () => {
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'agent-device-android-apps-all-'));
+  const adbPath = path.join(tmpDir, 'adb');
+  await fs.writeFile(
+    adbPath,
+    [
+      '#!/bin/sh',
+      'if [ "$1" = "-s" ]; then',
+      '  shift',
+      '  shift',
+      'fi',
+      'if [ "$1" = "shell" ] && [ "$2" = "cmd" ] && [ "$3" = "package" ] && [ "$4" = "query-activities" ]; then',
+      '  echo "com.google.android.apps.maps/.MainActivity"',
+      '  echo "org.mozilla.firefox/.App"',
+      '  echo "com.android.settings/.Settings"',
+      '  exit 0',
+      'fi',
+      'if [ "$1" = "shell" ] && [ "$2" = "pm" ] && [ "$3" = "list" ] && [ "$4" = "packages" ] && [ "$5" = "-3" ]; then',
+      '  echo "package:com.google.android.apps.maps"',
+      '  echo "package:com.example.serviceonly"',
+      '  echo "package:org.mozilla.firefox"',
+      '  exit 0',
+      'fi',
+      'echo "unexpected args: $@" >&2',
+      'exit 1',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  await fs.chmod(adbPath, 0o755);
+
+  const previousPath = process.env.PATH;
+  process.env.PATH = `${tmpDir}${path.delimiter}${previousPath ?? ''}`;
+
+  const device: DeviceInfo = {
+    platform: 'android',
+    id: 'emulator-5554',
+    name: 'Pixel',
+    kind: 'emulator',
+    booted: true,
+  };
+
+  try {
+    const apps = await listAndroidApps(device, 'all');
+    assert.deepEqual(apps, [
+      { package: 'com.android.settings', name: 'Settings' },
+      { package: 'com.google.android.apps.maps', name: 'Maps' },
+      { package: 'org.mozilla.firefox', name: 'Firefox' },
+    ]);
+  } finally {
+    process.env.PATH = previousPath;
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  }
+});
+
+test('listAndroidApps user-installed excludes non-launchable packages', async () => {
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'agent-device-android-apps-user-'));
+  const adbPath = path.join(tmpDir, 'adb');
+  await fs.writeFile(
+    adbPath,
+    [
+      '#!/bin/sh',
+      'if [ "$1" = "-s" ]; then',
+      '  shift',
+      '  shift',
+      'fi',
+      'if [ "$1" = "shell" ] && [ "$2" = "cmd" ] && [ "$3" = "package" ] && [ "$4" = "query-activities" ]; then',
+      '  echo "com.google.android.apps.maps/.MainActivity"',
+      '  echo "org.mozilla.firefox/.App"',
+      '  exit 0',
+      'fi',
+      'if [ "$1" = "shell" ] && [ "$2" = "pm" ] && [ "$3" = "list" ] && [ "$4" = "packages" ] && [ "$5" = "-3" ]; then',
+      '  echo "package:com.google.android.apps.maps"',
+      '  echo "package:com.example.serviceonly"',
+      '  echo "package:org.mozilla.firefox"',
+      '  exit 0',
+      'fi',
+      'echo "unexpected args: $@" >&2',
+      'exit 1',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  await fs.chmod(adbPath, 0o755);
+
+  const previousPath = process.env.PATH;
+  process.env.PATH = `${tmpDir}${path.delimiter}${previousPath ?? ''}`;
+
+  const device: DeviceInfo = {
+    platform: 'android',
+    id: 'emulator-5554',
+    name: 'Pixel',
+    kind: 'emulator',
+    booted: true,
+  };
+
+  try {
+    const apps = await listAndroidApps(device, 'user-installed');
+    assert.deepEqual(apps, [
+      { package: 'com.google.android.apps.maps', name: 'Maps' },
+      { package: 'org.mozilla.firefox', name: 'Firefox' },
+    ]);
+  } finally {
+    process.env.PATH = previousPath;
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  }
+});
+
 test('openAndroidApp rejects activity override for deep link URLs', async () => {
   const device: DeviceInfo = {
     platform: 'android',

package/src/platforms/android/index.ts

@@ -48,60 +48,87 @@ export async function resolveAndroidApp(
 
 export async function listAndroidApps(
   device: DeviceInfo,
-  filter: 'launchable' | 'user-installed' | 'all' = 'launchable',
-): Promise<string[]> {
-  if (filter === 'launchable') {
-    const result = await runCmd(
-      'adb',
-      adbArgs(device, [
-        'shell',
-        'cmd',
-        'package',
-        'query-activities',
-        '--brief',
-        '-a',
-        'android.intent.action.MAIN',
-        '-c',
-        'android.intent.category.LAUNCHER',
-      ]),
-      { allowFailure: true },
-    );
-    if (result.exitCode === 0 && result.stdout.trim().length > 0) {
-      const packages = new Set<string>();
-      for (const line of result.stdout.split('\n')) {
-        const trimmed = line.trim();
-        if (!trimmed) continue;
-        const firstToken = trimmed.split(/\s+/)[0];
-        const pkg = firstToken.includes('/') ? firstToken.split('/')[0] : firstToken;
-        if (pkg) packages.add(pkg);
-      }
-      if (packages.size > 0) {
-        return Array.from(packages);
-      }
-    }
-    // fallback: list all if query-activities not available
+  filter: 'user-installed' | 'all' = 'all',
+): Promise<Array<{ package: string; name: string }>> {
+  const launchable = await listAndroidLaunchablePackages(device);
+  const packageIds =
+    filter === 'user-installed'
+      ? (await listAndroidUserInstalledPackages(device)).filter((pkg) => launchable.has(pkg))
+      : Array.from(launchable);
+  return packageIds
+    .sort((a, b) => a.localeCompare(b))
+    .map((pkg) => ({ package: pkg, name: inferAndroidAppName(pkg) }));
+}
+
+async function listAndroidLaunchablePackages(device: DeviceInfo): Promise<Set<string>> {
+  const result = await runCmd(
+    'adb',
+    adbArgs(device, [
+      'shell',
+      'cmd',
+      'package',
+      'query-activities',
+      '--brief',
+      '-a',
+      'android.intent.action.MAIN',
+      '-c',
+      'android.intent.category.LAUNCHER',
+    ]),
+    { allowFailure: true },
+  );
+  if (result.exitCode !== 0 || result.stdout.trim().length === 0) {
+    return new Set<string>();
+  }
+  const packages = new Set<string>();
+  for (const line of result.stdout.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const firstToken = trimmed.split(/\s+/)[0];
+    const pkg = firstToken.includes('/') ? firstToken.split('/')[0] : firstToken;
+    if (pkg) packages.add(pkg);
   }
+  return packages;
+}
 
-  const args =
-    filter === 'user-installed'
-      ? ['shell', 'pm', 'list', 'packages', '-3']
-      : ['shell', 'pm', 'list', 'packages'];
-  const result = await runCmd('adb', adbArgs(device, args));
+async function listAndroidUserInstalledPackages(device: DeviceInfo): Promise<string[]> {
+  const result = await runCmd('adb', adbArgs(device, ['shell', 'pm', 'list', 'packages', '-3']));
   return result.stdout
     .split('\n')
     .map((line: string) => line.replace('package:', '').trim())
     .filter(Boolean);
 }
 
-export async function listAndroidAppsMetadata(
-  device: DeviceInfo,
-  filter: 'launchable' | 'user-installed' | 'all' = 'launchable',
-): Promise<Array<{ package: string; launchable: boolean }>> {
-  const apps = await listAndroidApps(device, filter);
-  const launchable = filter === 'launchable'
-    ? new Set(apps)
-    : new Set(await listAndroidApps(device, 'launchable'));
-  return apps.map((pkg) => ({ package: pkg, launchable: launchable.has(pkg) }));
+export function inferAndroidAppName(packageName: string): string {
+  const ignoredTokens = new Set([
+    'com',
+    'android',
+    'google',
+    'app',
+    'apps',
+    'service',
+    'services',
+    'mobile',
+    'client',
+  ]);
+  const tokens = packageName
+    .split('.')
+    .flatMap((segment) => segment.split(/[_-]+/))
+    .map((token) => token.trim().toLowerCase())
+    .filter((token) => token.length > 0);
+  // Fallback to last token if every token is ignored (e.g. "com.android.app.services" → "Services").
+  let chosen = tokens[tokens.length - 1] ?? packageName;
+  for (let index = tokens.length - 1; index >= 0; index -= 1) {
+    const token = tokens[index];
+    if (!ignoredTokens.has(token)) {
+      chosen = token;
+      break;
+    }
+  }
+  return chosen
+    .split(/[^a-z0-9]+/i)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ');
 }
 
 export async function getAndroidAppState(
@@ -180,7 +207,7 @@ export async function openAndroidApp(
     if (activity) {
       throw new AppError('INVALID_ARGS', 'Activity override requires a package name, not an intent');
     }
-    await runCmd('adb', adbArgs(device, ['shell', 'am', 'start', '-a', resolved.value]));
+    await runCmd('adb', adbArgs(device, ['shell', 'am', 'start', '-W', '-a', resolved.value]));
     return;
   }
   if (activity) {
@@ -193,6 +220,7 @@ export async function openAndroidApp(
         'shell',
         'am',
         'start',
+        '-W',
         '-a',
         'android.intent.action.MAIN',
         '-c',
@@ -212,6 +240,7 @@ export async function openAndroidApp(
         'shell',
         'am',
         'start',
+        '-W',
         '-a',
         'android.intent.action.MAIN',
         '-c',
@@ -232,6 +261,7 @@ export async function openAndroidApp(
         'shell',
         'am',
         'start',
+        '-W',
         '-a',
         'android.intent.action.MAIN',
         '-c',

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

@@ -1,10 +1,13 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { openIosApp } from '../index.ts';
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { listIosApps, openIosApp, parseIosDeviceAppsPayload, resolveIosApp } from '../index.ts';
 import type { DeviceInfo } from '../../../utils/device.ts';
 import { AppError } from '../../../utils/errors.ts';
 
-test('openIosApp rejects deep links on iOS physical devices', async () => {
+test('openIosApp custom scheme deep links on iOS devices require app bundle context', async () => {
   const device: DeviceInfo = {
     platform: 'ios',
     id: 'ios-device-1',
@@ -14,11 +17,296 @@ test('openIosApp rejects deep links on iOS physical devices', async () => {
   };
 
   await assert.rejects(
-    () => openIosApp(device, 'https://example.com/path'),
+    () => openIosApp(device, 'myapp://home'),
     (error: unknown) => {
       assert.equal(error instanceof AppError, true);
-      assert.equal((error as AppError).code, 'UNSUPPORTED_OPERATION');
+      assert.equal((error as AppError).code, 'INVALID_ARGS');
       return true;
     },
   );
 });
+
+test('openIosApp web URL on iOS device without app falls back to Safari', async () => {
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'agent-device-ios-safari-test-'));
+  const xcrunPath = path.join(tmpDir, 'xcrun');
+  const argsLogPath = path.join(tmpDir, 'args.log');
+  await fs.writeFile(
+    xcrunPath,
+    '#!/bin/sh\nprintf "%s\\n" "$@" > "$AGENT_DEVICE_TEST_ARGS_FILE"\nexit 0\n',
+    'utf8',
+  );
+  await fs.chmod(xcrunPath, 0o755);
+
+  const previousPath = process.env.PATH;
+  const previousArgsFile = process.env.AGENT_DEVICE_TEST_ARGS_FILE;
+  process.env.PATH = `${tmpDir}${path.delimiter}${previousPath ?? ''}`;
+  process.env.AGENT_DEVICE_TEST_ARGS_FILE = argsLogPath;
+
+  const device: DeviceInfo = {
+    platform: 'ios',
+    id: 'ios-device-1',
+    name: 'iPhone Device',
+    kind: 'device',
+    booted: true,
+  };
+
+  try {
+    await openIosApp(device, 'https://example.com/path');
+    const args = (await fs.readFile(argsLogPath, 'utf8'))
+      .trim()
+      .split('\n')
+      .filter(Boolean);
+    assert.deepEqual(args, [
+      'devicectl',
+      'device',
+      'process',
+      'launch',
+      '--device',
+      'ios-device-1',
+      'com.apple.mobilesafari',
+      '--payload-url',
+      'https://example.com/path',
+    ]);
+  } finally {
+    process.env.PATH = previousPath;
+    if (previousArgsFile === undefined) {
+      delete process.env.AGENT_DEVICE_TEST_ARGS_FILE;
+    } else {
+      process.env.AGENT_DEVICE_TEST_ARGS_FILE = previousArgsFile;
+    }
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  }
+});
+
+test('openIosApp custom scheme on iOS device uses active app context', async () => {
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'agent-device-ios-openurl-test-'));
+  const xcrunPath = path.join(tmpDir, 'xcrun');
+  const argsLogPath = path.join(tmpDir, 'args.log');
+  await fs.writeFile(
+    xcrunPath,
+    '#!/bin/sh\nprintf "%s\\n" "$@" > "$AGENT_DEVICE_TEST_ARGS_FILE"\nexit 0\n',
+    'utf8',
+  );
+  await fs.chmod(xcrunPath, 0o755);
+
+  const previousPath = process.env.PATH;
+  const previousArgsFile = process.env.AGENT_DEVICE_TEST_ARGS_FILE;
+  process.env.PATH = `${tmpDir}${path.delimiter}${previousPath ?? ''}`;
+  process.env.AGENT_DEVICE_TEST_ARGS_FILE = argsLogPath;
+
+  const device: DeviceInfo = {
+    platform: 'ios',
+    id: 'ios-device-1',
+    name: 'iPhone Device',
+    kind: 'device',
+    booted: true,
+  };
+
+  try {
+    await openIosApp(device, 'myapp://item/42', { appBundleId: 'com.example.app' });
+    const args = (await fs.readFile(argsLogPath, 'utf8'))
+      .trim()
+      .split('\n')
+      .filter(Boolean);
+    assert.deepEqual(args, [
+      'devicectl',
+      'device',
+      'process',
+      'launch',
+      '--device',
+      'ios-device-1',
+      'com.example.app',
+      '--payload-url',
+      'myapp://item/42',
+    ]);
+  } finally {
+    process.env.PATH = previousPath;
+    if (previousArgsFile === undefined) {
+      delete process.env.AGENT_DEVICE_TEST_ARGS_FILE;
+    } else {
+      process.env.AGENT_DEVICE_TEST_ARGS_FILE = previousArgsFile;
+    }
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  }
+});
+
+test('openIosApp with app and URL on iOS device launches app bundle with payload URL', async () => {
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'agent-device-ios-open-app-url-test-'));
+  const xcrunPath = path.join(tmpDir, 'xcrun');
+  const argsLogPath = path.join(tmpDir, 'args.log');
+  await fs.writeFile(
+    xcrunPath,
+    '#!/bin/sh\nprintf "%s\\n" "$@" > "$AGENT_DEVICE_TEST_ARGS_FILE"\nexit 0\n',
+    'utf8',
+  );
+  await fs.chmod(xcrunPath, 0o755);
+
+  const previousPath = process.env.PATH;
+  const previousArgsFile = process.env.AGENT_DEVICE_TEST_ARGS_FILE;
+  process.env.PATH = `${tmpDir}${path.delimiter}${previousPath ?? ''}`;
+  process.env.AGENT_DEVICE_TEST_ARGS_FILE = argsLogPath;
+
+  const device: DeviceInfo = {
+    platform: 'ios',
+    id: 'ios-device-1',
+    name: 'iPhone Device',
+    kind: 'device',
+    booted: true,
+  };
+
+  try {
+    await openIosApp(device, 'MyApp', { appBundleId: 'com.example.app', url: 'myapp://screen/to' });
+    const args = (await fs.readFile(argsLogPath, 'utf8'))
+      .trim()
+      .split('\n')
+      .filter(Boolean);
+    assert.deepEqual(args, [
+      'devicectl',
+      'device',
+      'process',
+      'launch',
+      '--device',
+      'ios-device-1',
+      'com.example.app',
+      '--payload-url',
+      'myapp://screen/to',
+    ]);
+  } finally {
+    process.env.PATH = previousPath;
+    if (previousArgsFile === undefined) {
+      delete process.env.AGENT_DEVICE_TEST_ARGS_FILE;
+    } else {
+      process.env.AGENT_DEVICE_TEST_ARGS_FILE = previousArgsFile;
+    }
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  }
+});
+
+test('parseIosDeviceAppsPayload maps devicectl app entries', () => {
+  const apps = parseIosDeviceAppsPayload({
+    result: {
+      apps: [
+        {
+          bundleIdentifier: 'com.apple.Maps',
+          name: 'Maps',
+        },
+        {
+          bundleIdentifier: 'com.example.NoName',
+        },
+      ],
+    },
+  });
+
+  assert.equal(apps.length, 2);
+  assert.deepEqual(apps[0], {
+    bundleId: 'com.apple.Maps',
+    name: 'Maps',
+  });
+  assert.equal(apps[1].bundleId, 'com.example.NoName');
+  assert.equal(apps[1].name, 'com.example.NoName');
+});
+
+test('parseIosDeviceAppsPayload ignores malformed entries', () => {
+  const apps = parseIosDeviceAppsPayload({
+    result: {
+      apps: [
+        null,
+        {},
+        { name: 'Missing bundle id' },
+        { bundleIdentifier: '' },
+      ],
+    },
+  });
+  assert.deepEqual(apps, []);
+});
+
+test('resolveIosApp resolves app display name on iOS physical devices', async () => {
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'agent-device-ios-app-resolve-'));
+  const xcrunPath = path.join(tmpDir, 'xcrun');
+  await fs.writeFile(
+    xcrunPath,
+    [
+      '#!/bin/sh',
+      'if [ "$1" = "devicectl" ] && [ "$2" = "device" ] && [ "$3" = "info" ] && [ "$4" = "apps" ]; then',
+      '  out=""',
+      '  while [ "$#" -gt 0 ]; do',
+      '    if [ "$1" = "--json-output" ]; then',
+      '      out="$2"',
+      '      shift 2',
+      '      continue',
+      '    fi',
+      '    shift',
+      '  done',
+      "  cat > \"$out\" <<'JSON'",
+      '{"result":{"apps":[{"bundleIdentifier":"com.apple.Maps","name":"Maps"},{"bundleIdentifier":"com.example.demo","name":"Demo"}]}}',
+      'JSON',
+      '  exit 0',
+      'fi',
+      'echo "unexpected xcrun args: $@" >&2',
+      'exit 1',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  await fs.chmod(xcrunPath, 0o755);
+
+  const previousPath = process.env.PATH;
+  process.env.PATH = `${tmpDir}${path.delimiter}${previousPath ?? ''}`;
+
+  const device: DeviceInfo = {
+    platform: 'ios',
+    id: 'ios-device-1',
+    name: 'iPhone Device',
+    kind: 'device',
+    booted: true,
+  };
+
+  try {
+    const bundleId = await resolveIosApp(device, 'Maps');
+    assert.equal(bundleId, 'com.apple.Maps');
+  } finally {
+    process.env.PATH = previousPath;
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  }
+});
+
+test('listIosApps applies user-installed filter on simulator', async () => {
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'agent-device-ios-list-sim-'));
+  const xcrunPath = path.join(tmpDir, 'xcrun');
+  await fs.writeFile(
+    xcrunPath,
+    [
+      '#!/bin/sh',
+      'if [ "$1" = "simctl" ] && [ "$2" = "listapps" ]; then',
+      "  cat <<'JSON'",
+      '{"com.apple.Maps":{"CFBundleDisplayName":"Maps"},"com.example.demo":{"CFBundleDisplayName":"Demo"}}',
+      'JSON',
+      '  exit 0',
+      'fi',
+      'echo "unexpected xcrun args: $@" >&2',
+      'exit 1',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  await fs.chmod(xcrunPath, 0o755);
+
+  const previousPath = process.env.PATH;
+  process.env.PATH = `${tmpDir}${path.delimiter}${previousPath ?? ''}`;
+
+  const device: DeviceInfo = {
+    platform: 'ios',
+    id: 'sim-1',
+    name: 'iPhone Sim',
+    kind: 'simulator',
+    booted: true,
+  };
+
+  try {
+    const apps = await listIosApps(device, 'user-installed');
+    assert.deepEqual(apps, [{ bundleId: 'com.example.demo', name: 'Demo' }]);
+  } finally {
+    process.env.PATH = previousPath;
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  }
+});

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

@@ -1,12 +1,16 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
 import type { DeviceInfo } from '../../../utils/device.ts';
+import { AppError } from '../../../utils/errors.ts';
 import {
   assertSafeDerivedCleanup,
+  isRetryableRunnerError,
+  resolveRunnerEarlyExitHint,
   resolveRunnerBuildDestination,
   resolveRunnerDestination,
   resolveRunnerMaxConcurrentDestinationsFlag,
   resolveRunnerSigningBuildSettings,
+  shouldRetryRunnerConnectError,
 } from '../runner-client.ts';
 
 const iosSimulator: DeviceInfo = {
@@ -111,3 +115,41 @@ test('assertSafeDerivedCleanup allows cleaning override path with explicit opt-i
     });
   });
 });
+
+test('resolveRunnerEarlyExitHint surfaces busy-connecting guidance', () => {
+  const hint = resolveRunnerEarlyExitHint(
+    'Runner did not accept connection (xcodebuild exited early)',
+    'Ineligible destinations for the "AgentDeviceRunner" scheme:\n{ error:Device is busy (Connecting to iPhone) }',
+    '',
+  );
+  assert.match(hint, /still connecting/i);
+});
+
+test('resolveRunnerEarlyExitHint falls back to runner connect timeout hint', () => {
+  const hint = resolveRunnerEarlyExitHint(
+    'Runner did not accept connection (xcodebuild exited early)',
+    '',
+    'xcodebuild failed unexpectedly',
+  );
+  assert.match(hint, /retry runner startup/i);
+});
+
+test('shouldRetryRunnerConnectError does not retry xcodebuild early-exit errors', () => {
+  const err = new AppError('COMMAND_FAILED', 'Runner did not accept connection (xcodebuild exited early)');
+  assert.equal(shouldRetryRunnerConnectError(err), false);
+});
+
+test('shouldRetryRunnerConnectError retries transient connect errors', () => {
+  const err = new AppError('COMMAND_FAILED', 'Runner endpoint probe failed');
+  assert.equal(shouldRetryRunnerConnectError(err), true);
+});
+
+test('isRetryableRunnerError does not retry xcodebuild early-exit errors', () => {
+  const err = new AppError('COMMAND_FAILED', 'Runner did not accept connection (xcodebuild exited early)');
+  assert.equal(isRetryableRunnerError(err), false);
+});
+
+test('isRetryableRunnerError does not retry busy-connecting errors', () => {
+  const err = new AppError('COMMAND_FAILED', 'Device is busy (Connecting to iPhone)');
+  assert.equal(isRetryableRunnerError(err), false);
+});