From 4dcbf9b45f343bb4dc82bcaf14fb121b5619c97d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Mon, 16 Feb 2026 17:36:34 +0100
Subject: [PATCH 1/4] refactor: stabilize iOS app/session and daemon startup
 flows

---
 README.md                                     |  17 +-
 .../RunnerTests.swift                         |  10 +-
 skills/agent-device/SKILL.md                  |  17 +-
 skills/agent-device/references/permissions.md |   9 +-
 .../references/session-management.md          |   1 +
 src/__tests__/cli-close.test.ts               | 139 +++++
 src/cli.ts                                    |  47 +-
 src/core/__tests__/capabilities.test.ts       |   3 +-
 src/core/capabilities.ts                      |   2 +-
 src/daemon-client.ts                          | 131 ++++-
 src/daemon/__tests__/app-state.test.ts        | 138 -----
 src/daemon/__tests__/device-ready.test.ts     |  52 ++
 src/daemon/app-state.ts                       |  65 ---
 src/daemon/device-ready.ts                    | 152 +++++-
 src/daemon/handlers/__tests__/session.test.ts | 294 +++++++++++
 src/daemon/handlers/session.ts                | 267 ++++++----
 src/daemon/session-store.ts                   |   2 -
 src/platforms/android/__tests__/index.test.ts | 116 ++++-
 src/platforms/android/index.ts                | 118 +++--
 src/platforms/ios/__tests__/index.test.ts     |  40 +-
 .../ios/__tests__/runner-client.test.ts       |  42 ++
 src/platforms/ios/apps.ts                     | 309 ++++++++++++
 src/platforms/ios/config.ts                   |  34 ++
 src/platforms/ios/devicectl.ts                | 131 +++++
 src/platforms/ios/devices.ts                  |  21 +-
 src/platforms/ios/index.ts                    | 475 +-----------------
 src/platforms/ios/runner-client.ts            |  87 +++-
 src/platforms/ios/simulator.ts                | 164 ++++++
 src/utils/__tests__/args.test.ts              |  22 +-
 src/utils/__tests__/daemon-client.test.ts     |  25 +-
 src/utils/args.ts                             |   7 +-
 src/utils/command-schema.ts                   |  19 +-
 test/integration/ios.test.ts                  |  10 +
 website/docs/docs/commands.md                 |  19 +-
 website/docs/docs/installation.md             |   7 +-
 website/docs/docs/introduction.md             |   5 +-
 website/docs/docs/sessions.md                 |   1 +
 37 files changed, 2112 insertions(+), 886 deletions(-)
 create mode 100644 src/__tests__/cli-close.test.ts
 delete mode 100644 src/daemon/__tests__/app-state.test.ts
 create mode 100644 src/daemon/__tests__/device-ready.test.ts
 delete mode 100644 src/daemon/app-state.ts
 create mode 100644 src/platforms/ios/apps.ts
 create mode 100644 src/platforms/ios/config.ts
 create mode 100644 src/platforms/ios/devicectl.ts
 create mode 100644 src/platforms/ios/simulator.ts

diff --git a/README.md b/README.md
index 93474e687..0c4b0b027 100644
--- a/README.md
+++ b/README.md
@@ -15,7 +15,7 @@ The project is in early development and considered experimental. Pull requests a
 ## Features
 - Platforms: iOS (simulator + physical device core automation) and Android (emulator + device).
 - Core commands: `open`, `back`, `home`, `app-switcher`, `press`, `long-press`, `focus`, `type`, `fill`, `scroll`, `scrollintoview`, `wait`, `alert`, `screenshot`, `close`, `reinstall`.
-- Inspection commands: `snapshot` (accessibility tree).
+- Inspection commands: `snapshot` (accessibility tree), `appstate`, `apps`, `devices`.
 - Device tooling: `adb` (Android), `simctl`/`devicectl` (iOS via Xcode).
 - Minimal dependencies; TypeScript executed directly on Node 22+ (no build step).
 
@@ -148,6 +148,7 @@ Sessions:
 - `--save-script` accepts an optional path: `--save-script ./workflows/my-flow.ad`.
 - For ambiguous bare values, use an explicit form: `--save-script=workflow.ad` or a path-like value such as `./workflow.ad`.
 - Deterministic replay is `.ad`-based; use `replay --update` (`-u`) to update selector drift and rewrite the replay file in place.
+- On iOS, `appstate` is session-scoped and requires an active session on the target device.
 
 Navigation helpers:
 - `boot --platform ios|android` ensures the target is ready without launching an app.
@@ -217,8 +218,10 @@ Settings helpers:
 Note: iOS supports these only on simulators. iOS wifi/airplane toggles status bar indicators, not actual network state. Airplane off clears status bar overrides.
 
 App state:
-- `appstate` shows the foreground app/activity (Android). On iOS it uses the current session app when available, otherwise it resolves via XCTest snapshot.
-- `apps --metadata` returns app list with minimal metadata.
+- `appstate` shows the foreground app/activity (Android).
+- On iOS, `appstate` returns the currently tracked session app (`source: session`) and requires an active session on the selected device.
+- `apps` supports Android, iOS simulators, and iOS devices.
+- `apps` includes default/system apps by default (use `--user-installed` to filter).
 
 ## Debug
 
@@ -227,6 +230,7 @@ App state:
 - The trace log includes snapshot logs and XCTest runner logs for the session.
 - Built-in retries cover transient runner connection failures and Android UI dumps.
 - For snapshot issues (missing elements), compare with `--raw` flag for unaltered output and scope with `-s "<label>"`.
+- If startup fails with stale metadata hints, remove stale `~/.agent-device/daemon.json` / `~/.agent-device/daemon.lock` and retry.
 
 Boot diagnostics:
 - Boot failures include normalized reason codes in `error.details.reason` (JSON mode) and verbose logs.
@@ -242,7 +246,8 @@ Boot diagnostics:
 
 ## iOS notes
 - Core runner commands (`snapshot`, `wait`, `click`, `fill`, `get`, `is`, `find`, `press`, `long-press`, `focus`, `type`, `scroll`, `scrollintoview`, `back`, `home`, `app-switcher`) support iOS simulators and iOS devices.
-- Simulator-only commands: `alert`, `pinch`, `record`, `reinstall`, `apps`, `settings`.
+- `apps` is supported on both iOS simulators and iOS devices.
+- Simulator-only commands: `alert`, `pinch`, `record`, `reinstall`, `settings`.
 - iOS deep link open (`open <url>`) is simulator-only.
 - iOS device runs require valid signing/provisioning (Automatic Signing recommended). Optional overrides: `AGENT_DEVICE_IOS_TEAM_ID`, `AGENT_DEVICE_IOS_SIGNING_IDENTITY`, `AGENT_DEVICE_IOS_PROVISIONING_PROFILE`.
 
@@ -270,11 +275,11 @@ Environment selectors:
 - `ANDROID_DEVICE=Pixel_9_Pro_XL` or `ANDROID_SERIAL=emulator-5554`
 - `IOS_DEVICE="iPhone 17 Pro"` or `IOS_UDID=<udid>`
 - `AGENT_DEVICE_IOS_BOOT_TIMEOUT_MS=<ms>` to adjust iOS simulator boot timeout (default: `120000`, minimum: `5000`).
-- `AGENT_DEVICE_DAEMON_TIMEOUT_MS=<ms>` to increase daemon request timeout for slow first-run iOS device setup (for example `180000`).
+- `AGENT_DEVICE_DAEMON_TIMEOUT_MS=<ms>` to override daemon request timeout (default `45000`). Increase for slow physical-device setup (for example `120000`).
 - `AGENT_DEVICE_IOS_TEAM_ID=<team-id>` optional Team ID override for iOS device runner signing.
 - `AGENT_DEVICE_IOS_SIGNING_IDENTITY=<identity>` optional signing identity override.
 - `AGENT_DEVICE_IOS_PROVISIONING_PROFILE=<profile>` optional provisioning profile specifier for iOS device runner signing.
-- `AGENT_DEVICE_IOS_RUNNER_DERIVED_PATH=<path>` optional override for iOS runner derived data root. By default, agent-device separates caches by target kind (`.../derived/simulator` and `.../derived/device`). If you set this override, use separate paths per kind to avoid simulator/device artifact collisions.
+- `AGENT_DEVICE_IOS_RUNNER_DERIVED_PATH=<path>` optional override for iOS runner derived data root. By default, simulator uses `~/.agent-device/ios-runner/derived` and physical device uses `~/.agent-device/ios-runner/derived/device`. If you set this override, use separate paths per kind to avoid simulator/device artifact collisions.
 - `AGENT_DEVICE_IOS_CLEAN_DERIVED=1` rebuild iOS runner artifacts from scratch. When `AGENT_DEVICE_IOS_RUNNER_DERIVED_PATH` is set, cleanup is blocked by default; set `AGENT_DEVICE_IOS_ALLOW_OVERRIDE_DERIVED_CLEAN=1` only for trusted custom paths.
 
 Test screenshots are written to:
diff --git a/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift b/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift
index 1228cd2f9..b5e361184 100644
--- a/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift
+++ b/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift
@@ -216,14 +216,20 @@ final class RunnerTests: XCTestCase {
   }
 
   private func executeOnMain(command: Command) throws -> Response {
-    let bundleId = command.appBundleId ?? currentBundleId ?? "com.apple.Preferences"
-    if currentBundleId != bundleId {
+    let normalizedBundleId = command.appBundleId?
+      .trimmingCharacters(in: .whitespacesAndNewlines)
+    let requestedBundleId = (normalizedBundleId?.isEmpty == true) ? nil : normalizedBundleId
+    if let bundleId = requestedBundleId, currentBundleId != bundleId {
       let target = XCUIApplication(bundleIdentifier: bundleId)
       NSLog("AGENT_DEVICE_RUNNER_ACTIVATE bundle=%@ state=%d", bundleId, target.state.rawValue)
       // activate avoids terminating and relaunching the target app
       target.activate()
       currentApp = target
       currentBundleId = bundleId
+    } else if requestedBundleId == nil {
+      // Do not reuse stale bundle targets when the caller does not explicitly request one.
+      currentApp = nil
+      currentBundleId = nil
     }
     let activeApp = currentApp ?? app
     _ = activeApp.waitForExistence(timeout: 5)
diff --git a/skills/agent-device/SKILL.md b/skills/agent-device/SKILL.md
index 335451b13..914dde566 100644
--- a/skills/agent-device/SKILL.md
+++ b/skills/agent-device/SKILL.md
@@ -101,10 +101,12 @@ iOS settings helpers are simulator-only.
 
 ```bash
 agent-device appstate
-agent-device apps --metadata --platform ios
-agent-device apps --metadata --platform android
 ```
 
+- Android: `appstate` reports live foreground package/activity.
+- iOS: `appstate` is session-scoped and reports the app tracked by the active session on the target device.
+- For iOS `appstate`, ensure a matching session exists (for example `open --session <name> --platform ios --device "<name>" <app>`).
+
 ### Interactions (use @refs from snapshot)
 
 ```bash
@@ -167,9 +169,11 @@ agent-device trace stop ./trace.log    # Stop and move trace log
 
 ```bash
 agent-device devices
-agent-device apps --platform ios
-agent-device apps --platform android          # default: launchable only
-agent-device apps --platform android --all
+agent-device apps --platform ios              # iOS simulator + iOS device, includes default/system apps
+agent-device apps --platform ios --all        # explicit include-all (same as default)
+agent-device apps --platform ios --user-installed
+agent-device apps --platform android          # includes default/system apps
+agent-device apps --platform android --all    # explicit include-all (same as default)
 agent-device apps --platform android --user-installed
 ```
 
@@ -192,7 +196,8 @@ agent-device apps --platform android --user-installed
 - Use `--activity <component>` on Android to launch a specific activity (e.g. TV apps with LEANBACK); do not combine with URL opens.
 - iOS deep-link opens are simulator-only.
 - iOS physical-device runner requires Xcode signing/provisioning; optional overrides: `AGENT_DEVICE_IOS_TEAM_ID`, `AGENT_DEVICE_IOS_SIGNING_IDENTITY`, `AGENT_DEVICE_IOS_PROVISIONING_PROFILE`.
-- For long first-run physical-device setup/build, increase daemon timeout: `AGENT_DEVICE_DAEMON_TIMEOUT_MS=180000` (or higher).
+- Default daemon request timeout is `45000`ms. For slow physical-device setup/build, increase `AGENT_DEVICE_DAEMON_TIMEOUT_MS` (for example `120000`).
+- For daemon startup troubleshooting, follow stale metadata hints for `~/.agent-device/daemon.json` / `~/.agent-device/daemon.lock`.
 - Use `fill` when you want clear-then-type semantics.
 - Use `type` when you want to append/enter text without clearing.
 - On Android, prefer `fill` for important fields; it verifies entered text and retries once when IME reorders characters.
diff --git a/skills/agent-device/references/permissions.md b/skills/agent-device/references/permissions.md
index 4fbb7ea42..4238cd905 100644
--- a/skills/agent-device/references/permissions.md
+++ b/skills/agent-device/references/permissions.md
@@ -24,9 +24,14 @@ Use Automatic Signing in Xcode, or provide optional overrides:
 - `AGENT_DEVICE_IOS_SIGNING_IDENTITY`
 - `AGENT_DEVICE_IOS_PROVISIONING_PROFILE`
 
-If first-run setup/build takes long, increase:
+If setup/build takes long, increase:
 
-- `AGENT_DEVICE_DAEMON_TIMEOUT_MS` (for example `180000`)
+- `AGENT_DEVICE_DAEMON_TIMEOUT_MS` (default `45000`, for example `120000`)
+
+If daemon startup fails with stale metadata hints, clean stale files and retry:
+
+- `~/.agent-device/daemon.json`
+- `~/.agent-device/daemon.lock`
 
 ## Simulator troubleshooting
 
diff --git a/skills/agent-device/references/session-management.md b/skills/agent-device/references/session-management.md
index 09a0dfb05..3e757f6e8 100644
--- a/skills/agent-device/references/session-management.md
+++ b/skills/agent-device/references/session-management.md
@@ -15,6 +15,7 @@ Sessions isolate device context. A device can only be held by one session at a t
 - Close sessions when done.
 - Use separate sessions for parallel work.
 - In iOS sessions, use `open <app>` for simulator/device. `open <url>` is simulator-only.
+- On iOS, `appstate` is session-scoped and requires a matching active session on the target device.
 - For dev loops where runtime state can persist (for example React Native Fast Refresh), use `open <app> --relaunch` to restart the app process in the same session.
 - Use `--save-script [path]` to record replay scripts on `close`; path is a file path and parent directories are created automatically.
 - For ambiguous bare `--save-script` values, prefer `--save-script=workflow.ad` or `./workflow.ad`.
diff --git a/src/__tests__/cli-close.test.ts b/src/__tests__/cli-close.test.ts
new file mode 100644
index 000000000..1d9117e53
--- /dev/null
+++ b/src/__tests__/cli-close.test.ts
@@ -0,0 +1,139 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { runCli } from '../cli.ts';
+import { AppError } from '../utils/errors.ts';
+import type { DaemonResponse } from '../daemon-client.ts';
+
+class ExitSignal extends Error {
+  public readonly code: number;
+
+  constructor(code: number) {
+    super(`EXIT_${code}`);
+    this.code = code;
+  }
+}
+
+type RunResult = {
+  code: number | null;
+  stdout: string;
+  stderr: string;
+  daemonCalls: number;
+};
+
+async function runCliCapture(argv: string[]): Promise<RunResult> {
+  let daemonCalls = 0;
+  let stdout = '';
+  let stderr = '';
+  let code: number | null = null;
+
+  const originalExit = process.exit;
+  const originalStdoutWrite = process.stdout.write.bind(process.stdout);
+  const originalStderrWrite = process.stderr.write.bind(process.stderr);
+
+  (process as any).exit = ((nextCode?: number) => {
+    throw new ExitSignal(nextCode ?? 0);
+  }) as typeof process.exit;
+  (process.stdout as any).write = ((chunk: unknown) => {
+    stdout += String(chunk);
+    return true;
+  }) as typeof process.stdout.write;
+  (process.stderr as any).write = ((chunk: unknown) => {
+    stderr += String(chunk);
+    return true;
+  }) as typeof process.stderr.write;
+
+  const sendToDaemon = async (): Promise<DaemonResponse> => {
+    daemonCalls += 1;
+    throw new AppError('COMMAND_FAILED', 'Failed to start daemon', {
+      infoPath: '/tmp/daemon.json',
+      hint: 'stale daemon info',
+    });
+  };
+
+  try {
+    await runCli(argv, { sendToDaemon });
+  } catch (error) {
+    if (error instanceof ExitSignal) code = error.code;
+    else throw error;
+  } finally {
+    process.exit = originalExit;
+    process.stdout.write = originalStdoutWrite;
+    process.stderr.write = originalStderrWrite;
+  }
+
+  return { code, stdout, stderr, daemonCalls };
+}
+
+async function runCliCaptureWithErrorDetails(
+  argv: string[],
+  details: Record<string, unknown>,
+): Promise<RunResult> {
+  let daemonCalls = 0;
+  let stdout = '';
+  let stderr = '';
+  let code: number | null = null;
+
+  const originalExit = process.exit;
+  const originalStdoutWrite = process.stdout.write.bind(process.stdout);
+  const originalStderrWrite = process.stderr.write.bind(process.stderr);
+
+  (process as any).exit = ((nextCode?: number) => {
+    throw new ExitSignal(nextCode ?? 0);
+  }) as typeof process.exit;
+  (process.stdout as any).write = ((chunk: unknown) => {
+    stdout += String(chunk);
+    return true;
+  }) as typeof process.stdout.write;
+  (process.stderr as any).write = ((chunk: unknown) => {
+    stderr += String(chunk);
+    return true;
+  }) as typeof process.stderr.write;
+
+  const sendToDaemon = async (): Promise<DaemonResponse> => {
+    daemonCalls += 1;
+    throw new AppError('COMMAND_FAILED', 'Failed to start daemon', details);
+  };
+
+  try {
+    await runCli(argv, { sendToDaemon });
+  } catch (error) {
+    if (error instanceof ExitSignal) code = error.code;
+    else throw error;
+  } finally {
+    process.exit = originalExit;
+    process.stdout.write = originalStdoutWrite;
+    process.stderr.write = originalStderrWrite;
+  }
+
+  return { code, stdout, stderr, daemonCalls };
+}
+
+test('close treats daemon startup failure as no-op', async () => {
+  const result = await runCliCapture(['close']);
+  assert.equal(result.code, null);
+  assert.equal(result.daemonCalls, 1);
+  assert.equal(result.stdout, '');
+  assert.equal(result.stderr, '');
+});
+
+test('close --json treats daemon startup failure as no-op success', async () => {
+  const result = await runCliCapture(['close', '--json']);
+  assert.equal(result.code, null);
+  assert.equal(result.daemonCalls, 1);
+  const payload = JSON.parse(result.stdout);
+  assert.equal(payload.success, true);
+  assert.equal(payload.data.closed, 'session');
+  assert.equal(payload.data.source, 'no-daemon');
+  assert.equal(result.stderr, '');
+});
+
+test('close treats lock-only daemon startup failure as no-op', async () => {
+  const result = await runCliCaptureWithErrorDetails(['close'], {
+    lockPath: '/tmp/daemon.lock',
+    hint: 'stale daemon lock',
+  });
+  assert.equal(result.code, null);
+  assert.equal(result.daemonCalls, 1);
+  assert.equal(result.stdout, '');
+  assert.equal(result.stderr, '');
+});
diff --git a/src/cli.ts b/src/cli.ts
index 428689e7e..acd6bbdaf 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -179,9 +179,6 @@ export async function runCli(argv: string[], deps: CliDeps = DEFAULT_CLI_DEPS):
               const bundleId = app.bundleId ?? app.package;
               const name = app.name ?? app.label;
               if (name && bundleId) return `${name} (${bundleId})`;
-              if (bundleId && typeof app.launchable === 'boolean') {
-                return `${bundleId} (launchable=${app.launchable})`;
-              }
               if (bundleId) return String(bundleId);
               return JSON.stringify(app);
             }
@@ -199,7 +196,7 @@ export async function runCli(argv: string[], deps: CliDeps = DEFAULT_CLI_DEPS):
           const pkg = (data as any)?.package;
           const activity = (data as any)?.activity;
           if (platform === 'ios') {
-            process.stdout.write(`Foreground app: ${appName ?? appBundleId}\n`);
+            process.stdout.write(`Foreground app: ${appName ?? appBundleId ?? 'unknown'}\n`);
             if (appBundleId) process.stdout.write(`Bundle: ${appBundleId}\n`);
             if (source) process.stdout.write(`Source: ${source}\n`);
             if (logTailStopper) logTailStopper();
@@ -220,6 +217,13 @@ export async function runCli(argv: string[], deps: CliDeps = DEFAULT_CLI_DEPS):
     throw new AppError(response.error.code as any, response.error.message, response.error.details);
   } catch (err) {
     const appErr = asAppError(err);
+    if (command === 'close' && isDaemonStartupFailure(appErr)) {
+      if (flags.json) {
+        printJson({ success: true, data: { closed: 'session', source: 'no-daemon' } });
+      }
+      if (logTailStopper) logTailStopper();
+      return;
+    }
     if (flags.json) {
       printJson({
         success: false,
@@ -229,9 +233,6 @@ export async function runCli(argv: string[], deps: CliDeps = DEFAULT_CLI_DEPS):
       printHumanError(appErr);
       if (flags.verbose) {
         try {
-          const fs = await import('node:fs');
-          const os = await import('node:os');
-          const path = await import('node:path');
           const logPath = path.join(os.homedir(), '.agent-device', 'daemon.log');
           if (fs.existsSync(logPath)) {
             const content = fs.readFileSync(logPath, 'utf8');
@@ -251,6 +252,12 @@ export async function runCli(argv: string[], deps: CliDeps = DEFAULT_CLI_DEPS):
   }
 }
 
+function isDaemonStartupFailure(error: AppError): boolean {
+  if (error.code !== 'COMMAND_FAILED') return false;
+  if (!error.message.toLowerCase().includes('failed to start daemon')) return false;
+  return typeof error.details?.infoPath === 'string' || typeof error.details?.lockPath === 'string';
+}
+
 const isDirectRun = pathToFileURL(process.argv[1] ?? '').href === import.meta.url;
 if (isDirectRun) {
   runCli(process.argv.slice(2)).catch((err) => {
@@ -268,15 +275,23 @@ function startDaemonLogTail(): (() => void) | null {
     const interval = setInterval(() => {
       if (stopped) return;
       if (!fs.existsSync(logPath)) return;
-      const stats = fs.statSync(logPath);
-      if (stats.size <= offset) return;
-      const fd = fs.openSync(logPath, 'r');
-      const buffer = Buffer.alloc(stats.size - offset);
-      fs.readSync(fd, buffer, 0, buffer.length, offset);
-      fs.closeSync(fd);
-      offset = stats.size;
-      if (buffer.length > 0) {
-        process.stdout.write(buffer.toString('utf8'));
+      try {
+        const stats = fs.statSync(logPath);
+        if (stats.size < offset) offset = 0;
+        if (stats.size <= offset) return;
+        const fd = fs.openSync(logPath, 'r');
+        try {
+          const buffer = Buffer.alloc(stats.size - offset);
+          fs.readSync(fd, buffer, 0, buffer.length, offset);
+          offset = stats.size;
+          if (buffer.length > 0) {
+            process.stdout.write(buffer.toString('utf8'));
+          }
+        } finally {
+          fs.closeSync(fd);
+        }
+      } catch {
+        // Best-effort tailing should not crash CLI flow.
       }
     }, 200);
     return () => {
diff --git a/src/core/__tests__/capabilities.test.ts b/src/core/__tests__/capabilities.test.ts
index 1d160a367..b4cfbea91 100644
--- a/src/core/__tests__/capabilities.test.ts
+++ b/src/core/__tests__/capabilities.test.ts
@@ -33,7 +33,7 @@ test('iOS simulator-only commands reject iOS devices and Android', () => {
 });
 
 test('simulator-only iOS commands with Android support reject iOS devices', () => {
-  for (const cmd of ['apps', 'reinstall', 'record', 'settings', 'swipe']) {
+  for (const cmd of ['reinstall', 'record', 'settings', 'swipe']) {
     assert.equal(isCommandSupportedOnDevice(cmd, iosSimulator), true, `${cmd} on iOS sim`);
     assert.equal(isCommandSupportedOnDevice(cmd, iosDevice), false, `${cmd} on iOS device`);
     assert.equal(isCommandSupportedOnDevice(cmd, androidDevice), true, `${cmd} on Android`);
@@ -43,6 +43,7 @@ test('simulator-only iOS commands with Android support reject iOS devices', () =
 test('core commands support iOS simulator, iOS device, and Android', () => {
   for (const cmd of [
     'app-switcher',
+    'apps',
     'back',
     'boot',
     'click',
diff --git a/src/core/capabilities.ts b/src/core/capabilities.ts
index a5f6fef6e..643d7fe76 100644
--- a/src/core/capabilities.ts
+++ b/src/core/capabilities.ts
@@ -17,7 +17,7 @@ const COMMAND_CAPABILITY_MATRIX: Record<string, CommandCapability> = {
   alert: { ios: { simulator: true }, android: {} },
   pinch: { ios: { simulator: true }, android: {} },
   'app-switcher': { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
-  apps: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
+  apps: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
   back: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
   boot: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
   click: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
diff --git a/src/daemon-client.ts b/src/daemon-client.ts
index e15c9e01b..8f236b5fe 100644
--- a/src/daemon-client.ts
+++ b/src/daemon-client.ts
@@ -6,7 +6,10 @@ import { AppError } from './utils/errors.ts';
 import type { CommandFlags } from './core/dispatch.ts';
 import { runCmdDetached } from './utils/exec.ts';
 import { findProjectRoot, readVersion } from './utils/version.ts';
-import { stopProcessForTakeover } from './utils/process-identity.ts';
+import {
+  isAgentDeviceDaemonProcess,
+  stopProcessForTakeover,
+} from './utils/process-identity.ts';
 
 export type DaemonRequest = {
   token: string;
@@ -28,8 +31,20 @@ type DaemonInfo = {
   processStartTime?: string;
 };
 
+type DaemonLockInfo = {
+  pid: number;
+  processStartTime?: string;
+  startedAt?: number;
+};
+
+type DaemonMetadataState = {
+  hasInfo: boolean;
+  hasLock: boolean;
+};
+
 const baseDir = path.join(os.homedir(), '.agent-device');
 const infoPath = path.join(baseDir, 'daemon.json');
+const lockPath = path.join(baseDir, 'daemon.lock');
 const REQUEST_TIMEOUT_MS = resolveDaemonRequestTimeoutMs();
 const DAEMON_STARTUP_TIMEOUT_MS = 5000;
 const DAEMON_TAKEOVER_TERM_TIMEOUT_MS = 3000;
@@ -51,19 +66,49 @@ async function ensureDaemon(): Promise<DaemonInfo> {
     removeDaemonInfo();
   }
 
+  cleanupStaleDaemonLockIfSafe();
   await startDaemon();
+  const started = await waitForDaemonInfo(DAEMON_STARTUP_TIMEOUT_MS);
+  if (started) return started;
 
+  if (await recoverDaemonLockHolder()) {
+    await startDaemon();
+    const recovered = await waitForDaemonInfo(DAEMON_STARTUP_TIMEOUT_MS);
+    if (recovered) return recovered;
+  }
+
+  throw new AppError('COMMAND_FAILED', 'Failed to start daemon', {
+    infoPath,
+    lockPath,
+    hint: resolveDaemonStartupHint(getDaemonMetadataState()),
+  });
+}
+
+async function waitForDaemonInfo(timeoutMs: number): Promise<DaemonInfo | null> {
   const start = Date.now();
-  while (Date.now() - start < DAEMON_STARTUP_TIMEOUT_MS) {
+  while (Date.now() - start < timeoutMs) {
     const info = readDaemonInfo();
     if (info && (await canConnect(info))) return info;
     await new Promise((resolve) => setTimeout(resolve, 100));
   }
+  return null;
+}
 
-  throw new AppError('COMMAND_FAILED', 'Failed to start daemon', {
-    infoPath,
-    hint: 'Run pnpm build, or delete ~/.agent-device/daemon.json if stale.',
+async function recoverDaemonLockHolder(): Promise<boolean> {
+  const state = getDaemonMetadataState();
+  if (!state.hasLock || state.hasInfo) return false;
+  const lockInfo = readDaemonLockInfo();
+  if (!lockInfo) {
+    removeDaemonLock();
+    return true;
+  }
+  await stopProcessForTakeover(lockInfo.pid, {
+    termTimeoutMs: DAEMON_TAKEOVER_TERM_TIMEOUT_MS,
+    killTimeoutMs: DAEMON_TAKEOVER_KILL_TIMEOUT_MS,
+    expectedStartTime: lockInfo.processStartTime,
   });
+  removeDaemonLock();
+  return true;
 }
 
 async function stopDaemonProcessForTakeover(info: DaemonInfo): Promise<void> {
@@ -75,24 +120,65 @@ async function stopDaemonProcessForTakeover(info: DaemonInfo): Promise<void> {
 }
 
 function readDaemonInfo(): DaemonInfo | null {
-  if (!fs.existsSync(infoPath)) return null;
+  const data = readJsonFile(infoPath) as DaemonInfo | null;
+  if (!data || !data.port || !data.token) return null;
+  return {
+    ...data,
+    pid: Number.isInteger(data.pid) && data.pid > 0 ? data.pid : 0,
+  };
+}
+
+function readDaemonLockInfo(): DaemonLockInfo | null {
+  const data = readJsonFile(lockPath) as DaemonLockInfo | null;
+  if (!data || !Number.isInteger(data.pid) || data.pid <= 0) {
+    return null;
+  }
+  return data;
+}
+
+function removeDaemonInfo(): void {
+  removeFileIfExists(infoPath);
+}
+
+function removeDaemonLock(): void {
+  removeFileIfExists(lockPath);
+}
+
+function cleanupStaleDaemonLockIfSafe(): void {
+  const state = getDaemonMetadataState();
+  if (!state.hasLock || state.hasInfo) return;
+  const lockInfo = readDaemonLockInfo();
+  if (!lockInfo) {
+    removeDaemonLock();
+    return;
+  }
+  if (isAgentDeviceDaemonProcess(lockInfo.pid, lockInfo.processStartTime)) {
+    return;
+  }
+  removeDaemonLock();
+}
+
+function getDaemonMetadataState(): DaemonMetadataState {
+  return {
+    hasInfo: fs.existsSync(infoPath),
+    hasLock: fs.existsSync(lockPath),
+  };
+}
+
+function readJsonFile(filePath: string): unknown | null {
+  if (!fs.existsSync(filePath)) return null;
   try {
-    const data = JSON.parse(fs.readFileSync(infoPath, 'utf8')) as DaemonInfo;
-    if (!data.port || !data.token) return null;
-    return {
-      ...data,
-      pid: Number.isInteger(data.pid) && data.pid > 0 ? data.pid : 0,
-    };
+    return JSON.parse(fs.readFileSync(filePath, 'utf8')) as unknown;
   } catch {
     return null;
   }
 }
 
-function removeDaemonInfo(): void {
+function removeFileIfExists(filePath: string): void {
   try {
-    if (fs.existsSync(infoPath)) fs.unlinkSync(infoPath);
+    if (fs.existsSync(filePath)) fs.unlinkSync(filePath);
   } catch {
-    // Best-effort cleanup only; daemon can still overwrite this file on startup.
+    // Best-effort cleanup only.
   }
 }
 
@@ -164,9 +250,18 @@ async function sendRequest(info: DaemonInfo, req: DaemonRequest): Promise<Daemon
 }
 
 export function resolveDaemonRequestTimeoutMs(raw: string | undefined = process.env.AGENT_DEVICE_DAEMON_TIMEOUT_MS): number {
-  // iOS physical-device runner startup/build can exceed 60s, so use a safer default for daemon RPCs.
-  if (!raw) return 180000;
+  if (!raw) return 45000;
   const parsed = Number(raw);
-  if (!Number.isFinite(parsed)) return 180000;
+  if (!Number.isFinite(parsed)) return 45000;
   return Math.max(1000, Math.floor(parsed));
 }
+
+export function resolveDaemonStartupHint(state: { hasInfo: boolean; hasLock: boolean }): string {
+  if (state.hasLock && !state.hasInfo) {
+    return 'Detected ~/.agent-device/daemon.lock without daemon.json. If no agent-device daemon process is running, delete ~/.agent-device/daemon.lock and retry.';
+  }
+  if (state.hasLock && state.hasInfo) {
+    return 'Daemon metadata may be stale. If no agent-device daemon process is running, delete ~/.agent-device/daemon.json and ~/.agent-device/daemon.lock, then retry.';
+  }
+  return 'Daemon metadata is missing or stale. Delete ~/.agent-device/daemon.json if present and retry.';
+}
diff --git a/src/daemon/__tests__/app-state.test.ts b/src/daemon/__tests__/app-state.test.ts
deleted file mode 100644
index 85d89ac97..000000000
--- a/src/daemon/__tests__/app-state.test.ts
+++ /dev/null
@@ -1,138 +0,0 @@
-import test from 'node:test';
-import assert from 'node:assert/strict';
-import type { DeviceInfo } from '../../utils/device.ts';
-import { resolveIosAppStateFromSnapshots } from '../app-state.ts';
-import type { CommandFlags, dispatchCommand } from '../../core/dispatch.ts';
-
-const iosSimulator: DeviceInfo = {
-  platform: 'ios',
-  id: 'sim-1',
-  name: 'iPhone Simulator',
-  kind: 'simulator',
-  booted: true,
-};
-
-const iosDevice: DeviceInfo = {
-  platform: 'ios',
-  id: '00008110-000E12341234002E',
-  name: 'iPhone',
-  kind: 'device',
-  booted: true,
-};
-
-test('appstate uses xctest first on iOS simulator', async () => {
-  const backends: string[] = [];
-  const fakeDispatch: typeof dispatchCommand = async (_device, _command, _positionals, _outPath, context) => {
-    backends.push(context?.snapshotBackend ?? 'unknown');
-    return {
-      nodes: [
-        {
-          type: 'XCUIElementTypeApplication',
-          label: 'Settings',
-          identifier: 'com.apple.Preferences',
-        },
-      ],
-    };
-  };
-
-  const result = await resolveIosAppStateFromSnapshots(
-    iosSimulator,
-    '/tmp/daemon.log',
-    undefined,
-    {} as CommandFlags,
-    fakeDispatch,
-  );
-
-  assert.deepEqual(backends, ['xctest']);
-  assert.equal(result.source, 'snapshot-xctest');
-  assert.equal(result.appBundleId, 'com.apple.Preferences');
-});
-
-test('appstate does not try ax on iOS device when xctest succeeds', async () => {
-  const backends: string[] = [];
-  const fakeDispatch: typeof dispatchCommand = async (_device, _command, _positionals, _outPath, context) => {
-    backends.push(context?.snapshotBackend ?? 'unknown');
-    return {
-      nodes: [
-        {
-          type: 'XCUIElementTypeApplication',
-          label: 'Settings',
-          identifier: 'com.apple.Preferences',
-        },
-      ],
-    };
-  };
-
-  const result = await resolveIosAppStateFromSnapshots(
-    iosDevice,
-    '/tmp/daemon.log',
-    undefined,
-    {} as CommandFlags,
-    fakeDispatch,
-  );
-
-  assert.deepEqual(backends, ['xctest']);
-  assert.equal(result.source, 'snapshot-xctest');
-  assert.equal(result.appName, 'Settings');
-});
-
-test('appstate fails on simulator when xctest is empty', async () => {
-  const backends: string[] = [];
-  const fakeDispatch: typeof dispatchCommand = async (_device, _command, _positionals, _outPath, context) => {
-    backends.push(context?.snapshotBackend ?? 'unknown');
-    return { nodes: [] };
-  };
-
-  await assert.rejects(
-    resolveIosAppStateFromSnapshots(
-      iosSimulator,
-      '/tmp/daemon.log',
-      undefined,
-      {} as CommandFlags,
-      fakeDispatch,
-    ),
-    /not recommended/,
-  );
-  assert.deepEqual(backends, ['xctest']);
-});
-
-test('appstate fails on simulator when xctest throws', async () => {
-  const backends: string[] = [];
-  const fakeDispatch: typeof dispatchCommand = async (_device, _command, _positionals, _outPath, context) => {
-    const backend = context?.snapshotBackend ?? 'unknown';
-    backends.push(backend);
-    throw new Error('xctest failed');
-  };
-
-  await assert.rejects(
-    resolveIosAppStateFromSnapshots(
-      iosSimulator,
-      '/tmp/daemon.log',
-      undefined,
-      {} as CommandFlags,
-      fakeDispatch,
-    ),
-    /not recommended/,
-  );
-  assert.deepEqual(backends, ['xctest']);
-});
-
-test('appstate fails on device when xctest throws', async () => {
-  const backends: string[] = [];
-  const fakeDispatch: typeof dispatchCommand = async (_device, _command, _positionals, _outPath, context) => {
-    backends.push(context?.snapshotBackend ?? 'unknown');
-    throw new Error('xctest failed');
-  };
-
-  await assert.rejects(
-    resolveIosAppStateFromSnapshots(
-      iosDevice,
-      '/tmp/daemon.log',
-      undefined,
-      {} as CommandFlags,
-      fakeDispatch,
-    ),
-    /not recommended/,
-  );
-  assert.deepEqual(backends, ['xctest']);
-});
diff --git a/src/daemon/__tests__/device-ready.test.ts b/src/daemon/__tests__/device-ready.test.ts
new file mode 100644
index 000000000..99250af17
--- /dev/null
+++ b/src/daemon/__tests__/device-ready.test.ts
@@ -0,0 +1,52 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { parseIosReadyPayload, resolveIosReadyHint } from '../device-ready.ts';
+
+test('parseIosReadyPayload reads tunnelState from direct connectionProperties', () => {
+  const parsed = parseIosReadyPayload({
+    result: {
+      connectionProperties: {
+        tunnelState: 'connected',
+      },
+    },
+  });
+  assert.equal(parsed.tunnelState, 'connected');
+});
+
+test('parseIosReadyPayload reads tunnelState from nested device connectionProperties', () => {
+  const parsed = parseIosReadyPayload({
+    result: {
+      device: {
+        connectionProperties: {
+          tunnelState: 'connecting',
+        },
+      },
+    },
+  });
+  assert.equal(parsed.tunnelState, 'connecting');
+});
+
+test('parseIosReadyPayload returns empty payload for malformed input', () => {
+  assert.deepEqual(parseIosReadyPayload(null), {});
+  assert.deepEqual(parseIosReadyPayload({}), {});
+  assert.deepEqual(
+    parseIosReadyPayload({
+      result: { connectionProperties: { tunnelState: 123 } },
+    }),
+    {},
+  );
+});
+
+test('resolveIosReadyHint maps known connection errors', () => {
+  const connecting = resolveIosReadyHint('', 'Device is busy (Connecting to iPhone)');
+  assert.match(connecting, /still connecting/i);
+
+  const coreDeviceTimeout = resolveIosReadyHint('CoreDeviceService timed out', '');
+  assert.match(coreDeviceTimeout, /coredevice service/i);
+});
+
+test('resolveIosReadyHint falls back to generic guidance', () => {
+  const hint = resolveIosReadyHint('unexpected failure', '');
+  assert.match(hint, /unlocked/i);
+  assert.match(hint, /xcode/i);
+});
diff --git a/src/daemon/app-state.ts b/src/daemon/app-state.ts
deleted file mode 100644
index 098674701..000000000
--- a/src/daemon/app-state.ts
+++ /dev/null
@@ -1,65 +0,0 @@
-import { dispatchCommand, type CommandFlags } from '../core/dispatch.ts';
-import type { DeviceInfo } from '../utils/device.ts';
-import { attachRefs, type RawSnapshotNode } from '../utils/snapshot.ts';
-import { AppError } from '../utils/errors.ts';
-import { contextFromFlags } from './context.ts';
-import { normalizeType } from './snapshot-processing.ts';
-
-export async function resolveIosAppStateFromSnapshots(
-  device: DeviceInfo,
-  logPath: string,
-  traceLogPath: string | undefined,
-  flags: CommandFlags | undefined,
-  dispatch: typeof dispatchCommand = dispatchCommand,
-): Promise<{ appName: string; appBundleId?: string; source: 'snapshot-xctest' }> {
-  let xctestResult: { nodes?: RawSnapshotNode[] } | undefined;
-  try {
-    xctestResult = (await dispatch(device, 'snapshot', [], flags?.out, {
-      ...contextFromFlags(
-        logPath,
-        {
-          ...flags,
-          snapshotDepth: 1,
-          snapshotCompact: true,
-          snapshotBackend: 'xctest',
-        },
-        undefined,
-        traceLogPath,
-      ),
-    })) as { nodes?: RawSnapshotNode[] };
-  } catch (error) {
-    const cause = error instanceof Error ? error.message : String(error);
-    throw new AppError(
-      'COMMAND_FAILED',
-      'Unable to resolve iOS app state from XCTest snapshot. You can try snapshot --backend ax for diagnostics, but AX snapshots are not recommended.',
-      { cause },
-    );
-  }
-
-  const xcNode = extractAppNodeFromSnapshot(xctestResult);
-  if (xcNode?.appName || xcNode?.appBundleId) {
-    return {
-      appName: xcNode.appName ?? xcNode.appBundleId ?? 'unknown',
-      appBundleId: xcNode.appBundleId,
-      source: 'snapshot-xctest',
-    };
-  }
-
-  throw new AppError(
-    'COMMAND_FAILED',
-    'Unable to resolve iOS app state from XCTest snapshot (0 nodes or missing application node). You can try snapshot --backend ax for diagnostics, but AX snapshots are not recommended.',
-  );
-}
-
-function extractAppNodeFromSnapshot(
-  data: { nodes?: RawSnapshotNode[] } | undefined,
-): { appName?: string; appBundleId?: string } | null {
-  const rawNodes = data?.nodes ?? [];
-  const nodes = attachRefs(rawNodes);
-  const appNode = nodes.find((node) => normalizeType(node.type ?? '') === 'application') ?? nodes[0];
-  if (!appNode) return null;
-  const appName = appNode.label?.trim();
-  const appBundleId = appNode.identifier?.trim();
-  if (!appName && !appBundleId) return null;
-  return { appName: appName || undefined, appBundleId: appBundleId || undefined };
-}
diff --git a/src/daemon/device-ready.ts b/src/daemon/device-ready.ts
index 224980c2e..1b218dad5 100644
--- a/src/daemon/device-ready.ts
+++ b/src/daemon/device-ready.ts
@@ -1,13 +1,157 @@
 import type { DeviceInfo } from '../utils/device.ts';
+import os from 'node:os';
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import { runCmd } from '../utils/exec.ts';
+import { AppError } from '../utils/errors.ts';
+
+const IOS_DEVICE_READY_TIMEOUT_MS = resolveTimeoutMs(
+  process.env.AGENT_DEVICE_IOS_DEVICE_READY_TIMEOUT_MS,
+  15_000,
+  1_000,
+);
 
 export async function ensureDeviceReady(device: DeviceInfo): Promise<void> {
-  if (device.platform === 'ios' && device.kind === 'simulator') {
-    const { ensureBootedSimulator } = await import('../platforms/ios/index.ts');
-    await ensureBootedSimulator(device);
-    return;
+  if (device.platform === 'ios') {
+    if (device.kind === 'simulator') {
+      const { ensureBootedSimulator } = await import('../platforms/ios/index.ts');
+      await ensureBootedSimulator(device);
+      return;
+    }
+    if (device.kind === 'device') {
+      await ensureIosDeviceReady(device.id);
+      return;
+    }
   }
   if (device.platform === 'android') {
     const { waitForAndroidBoot } = await import('../platforms/android/devices.ts');
     await waitForAndroidBoot(device.id);
   }
 }
+
+function resolveTimeoutMs(raw: string | undefined, fallback: number, min: number): number {
+  if (!raw) return fallback;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.max(min, Math.floor(parsed));
+}
+
+async function ensureIosDeviceReady(deviceId: string): Promise<void> {
+  const jsonPath = path.join(os.tmpdir(), `agent-device-ready-${process.pid}-${Date.now()}.json`);
+  const timeoutSeconds = Math.max(1, Math.ceil(IOS_DEVICE_READY_TIMEOUT_MS / 1000));
+  try {
+    const result = await runCmd(
+      'xcrun',
+      [
+        'devicectl',
+        'device',
+        'info',
+        'details',
+        '--device',
+        deviceId,
+        '--json-output',
+        jsonPath,
+        '--timeout',
+        String(timeoutSeconds),
+      ],
+      { allowFailure: true, timeoutMs: IOS_DEVICE_READY_TIMEOUT_MS },
+    );
+    const stdout = String(result.stdout ?? '');
+    const stderr = String(result.stderr ?? '');
+    const parsed = await readIosReadyPayload(jsonPath);
+    if (result.exitCode === 0) {
+      if (!parsed.parsed) {
+        throw new AppError('COMMAND_FAILED', 'iOS device readiness probe failed', {
+          kind: 'probe_inconclusive',
+          deviceId,
+          stdout,
+          stderr,
+          hint: 'CoreDevice returned success but readiness JSON output was missing or invalid. Retry; if it persists restart Xcode and the iOS device.',
+        });
+      }
+      const tunnelState = parsed?.tunnelState?.toLowerCase();
+      if (tunnelState === 'connecting') {
+        throw new AppError('COMMAND_FAILED', 'iOS device is not ready for automation', {
+          kind: 'not_ready',
+          deviceId,
+          tunnelState,
+          hint: 'Device tunnel is still connecting. Keep the device unlocked and connected by cable until it is fully available in Xcode Devices, then retry.',
+        });
+      }
+      return;
+    }
+    throw new AppError('COMMAND_FAILED', 'iOS device is not ready for automation', {
+      kind: 'not_ready',
+      deviceId,
+      stdout,
+      stderr,
+      exitCode: result.exitCode,
+      tunnelState: parsed?.tunnelState,
+      hint: resolveIosReadyHint(stdout, stderr),
+    });
+  } catch (error) {
+    if (error instanceof AppError && error.code === 'COMMAND_FAILED') {
+      const kind = typeof error.details?.kind === 'string' ? error.details.kind : '';
+      if (kind === 'not_ready') {
+        throw error;
+      }
+      const details = (error.details ?? {}) as {
+        stdout?: string;
+        stderr?: string;
+        timeoutMs?: number;
+      };
+      const stdout = String(details.stdout ?? '');
+      const stderr = String(details.stderr ?? '');
+      const timeoutMs = Number(details.timeoutMs ?? IOS_DEVICE_READY_TIMEOUT_MS);
+      const timeoutHint = `CoreDevice did not respond within ${timeoutMs}ms. Keep the device unlocked and trusted, then retry; if it persists restart Xcode and the iOS device.`;
+      throw new AppError('COMMAND_FAILED', 'iOS device readiness probe failed', {
+        deviceId,
+        cause: error.message,
+        timeoutMs,
+        stdout,
+        stderr,
+        hint: stdout || stderr ? resolveIosReadyHint(stdout, stderr) : timeoutHint,
+      }, error);
+    }
+    throw new AppError('COMMAND_FAILED', 'iOS device readiness probe failed', {
+      deviceId,
+      hint: 'Reconnect the device, keep it unlocked, and retry.',
+    }, error instanceof Error ? error : undefined);
+  } finally {
+    await fs.rm(jsonPath, { force: true }).catch(() => {});
+  }
+}
+
+export function parseIosReadyPayload(payload: unknown): { tunnelState?: string } {
+  const result = (payload as { result?: unknown } | null | undefined)?.result;
+  if (!result || typeof result !== 'object') return {};
+  const direct = (result as { connectionProperties?: { tunnelState?: unknown } }).connectionProperties?.tunnelState;
+  const nested = (result as { device?: { connectionProperties?: { tunnelState?: unknown } } }).device?.connectionProperties?.tunnelState;
+  const tunnelState = typeof direct === 'string' ? direct : typeof nested === 'string' ? nested : undefined;
+  return tunnelState ? { tunnelState } : {};
+}
+
+async function readIosReadyPayload(jsonPath: string): Promise<{ parsed: boolean; tunnelState?: string }> {
+  try {
+    const payloadText = await fs.readFile(jsonPath, 'utf8');
+    const payload = JSON.parse(payloadText) as unknown;
+    const parsed = parseIosReadyPayload(payload);
+    return { parsed: true, tunnelState: parsed.tunnelState };
+  } catch {
+    return { parsed: false };
+  }
+}
+
+export function resolveIosReadyHint(stdout: string, stderr: string): string {
+  const text = `${stdout}\n${stderr}`.toLowerCase();
+  if (text.includes('device is busy') && text.includes('connecting')) {
+    return 'Device is still connecting. Keep it unlocked and connected by cable until connection settles, then retry.';
+  }
+  if (text.includes('coredeviceservice') && text.includes('timed out')) {
+    return 'CoreDevice service did not initialize in time. Reconnect device and retry; if it persists restart Xcode and the iOS device.';
+  }
+  if (text.includes('timed out waiting for all destinations')) {
+    return 'Xcode destination did not become available in time. Keep device unlocked and retry.';
+  }
+  return 'Ensure the iOS device is unlocked, trusted, and visible in Xcode > Devices, then retry.';
+}
diff --git a/src/daemon/handlers/__tests__/session.test.ts b/src/daemon/handlers/__tests__/session.test.ts
index 5d5b5b2ec..c67fa9944 100644
--- a/src/daemon/handlers/__tests__/session.test.ts
+++ b/src/daemon/handlers/__tests__/session.test.ts
@@ -124,6 +124,299 @@ test('boot succeeds for supported device in session', async () => {
   }
 });
 
+test('boot prefers explicit device selector over active session device', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'default';
+  sessionStore.set(
+    sessionName,
+    makeSession(sessionName, {
+      platform: 'android',
+      id: 'emulator-5554',
+      name: 'Pixel Emulator',
+      kind: 'emulator',
+      booted: true,
+    }),
+  );
+  const selectedDevice: SessionState['device'] = {
+    platform: 'ios',
+    id: 'sim-2',
+    name: 'iPhone 17 Pro',
+    kind: 'simulator',
+    booted: true,
+  };
+
+  const ensured: string[] = [];
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'boot',
+      positionals: [],
+      flags: { platform: 'ios', device: 'iPhone 17 Pro' },
+    },
+    sessionName,
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+    ensureReady: async (device) => {
+      ensured.push(device.id);
+    },
+    resolveTargetDevice: async () => selectedDevice,
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, true);
+  assert.deepEqual(ensured, ['sim-2']);
+  if (response && response.ok) {
+    assert.equal(response.data?.platform, 'ios');
+    assert.equal(response.data?.id, 'sim-2');
+  }
+});
+
+test('appstate on iOS requires active session on selected device', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'default';
+  sessionStore.set(
+    sessionName,
+    {
+      ...makeSession(sessionName, {
+        platform: 'ios',
+        id: 'sim-1',
+        name: 'iPhone 15',
+        kind: 'simulator',
+        booted: true,
+      }),
+      appBundleId: 'com.apple.Preferences',
+      appName: 'Settings',
+    },
+  );
+  const selectedDevice: SessionState['device'] = {
+    platform: 'ios',
+    id: 'sim-2',
+    name: 'iPhone 17 Pro',
+    kind: 'simulator',
+    booted: true,
+  };
+
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'appstate',
+      positionals: [],
+      flags: { platform: 'ios', device: 'iPhone 17 Pro' },
+    },
+    sessionName,
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+    ensureReady: async () => {},
+    resolveTargetDevice: async () => selectedDevice,
+    dispatch: async () => {
+      throw new Error('snapshot dispatch should not run');
+    },
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, false);
+  if (response && !response.ok) {
+    assert.equal(response.error.code, 'SESSION_NOT_FOUND');
+    assert.match(response.error.message, /requires an active session/i);
+  }
+});
+
+test('appstate with explicit selector matching session returns session state', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'sim';
+  sessionStore.set(
+    sessionName,
+    {
+      ...makeSession(sessionName, {
+        platform: 'ios',
+        id: 'sim-1',
+        name: 'iPhone 17 Pro',
+        kind: 'simulator',
+        booted: true,
+      }),
+      appBundleId: 'com.apple.Maps',
+      appName: 'Maps',
+    },
+  );
+
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'appstate',
+      positionals: [],
+      flags: { platform: 'ios', device: 'iPhone 17 Pro' },
+    },
+    sessionName,
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+    ensureReady: async () => {},
+    dispatch: async () => {
+      throw new Error('snapshot dispatch should not run');
+    },
+    resolveTargetDevice: async () => {
+      throw new Error('resolveTargetDevice should not run');
+    },
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, true);
+  if (response && response.ok) {
+    assert.equal(response.data?.platform, 'ios');
+    assert.equal(response.data?.appName, 'Maps');
+    assert.equal(response.data?.appBundleId, 'com.apple.Maps');
+    assert.equal(response.data?.source, 'session');
+  }
+});
+
+test('appstate returns session appName when bundle id is unavailable', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'sim';
+  sessionStore.set(
+    sessionName,
+    {
+      ...makeSession(sessionName, {
+        platform: 'ios',
+        id: 'sim-1',
+        name: 'iPhone 17 Pro',
+        kind: 'simulator',
+        booted: true,
+      }),
+      appName: 'Maps',
+    },
+  );
+
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'appstate',
+      positionals: [],
+      flags: { platform: 'ios', device: 'iPhone 17 Pro' },
+    },
+    sessionName,
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+    ensureReady: async () => {},
+    dispatch: async () => {
+      throw new Error('snapshot dispatch should not run');
+    },
+    resolveTargetDevice: async () => {
+      throw new Error('resolveTargetDevice should not run');
+    },
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, true);
+  if (response && response.ok) {
+    assert.equal(response.data?.platform, 'ios');
+    assert.equal(response.data?.appName, 'Maps');
+    assert.equal(response.data?.appBundleId, undefined);
+    assert.equal(response.data?.source, 'session');
+  }
+});
+
+test('appstate fails when iOS session has no tracked app', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'sim';
+  sessionStore.set(
+    sessionName,
+    makeSession(sessionName, {
+      platform: 'ios',
+      id: 'sim-1',
+      name: 'iPhone 17 Pro',
+      kind: 'simulator',
+      booted: true,
+    }),
+  );
+
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'appstate',
+      positionals: [],
+      flags: { platform: 'ios', device: 'iPhone 17 Pro' },
+    },
+    sessionName,
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+    ensureReady: async () => {},
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, false);
+  if (response && !response.ok) {
+    assert.equal(response.error.code, 'COMMAND_FAILED');
+    assert.match(response.error.message, /no foreground app is tracked/i);
+  }
+});
+
+test('appstate without session on iOS selector returns SESSION_NOT_FOUND', async () => {
+  const sessionStore = makeSessionStore();
+  const selectedDevice: SessionState['device'] = {
+    platform: 'ios',
+    id: 'sim-2',
+    name: 'iPhone 17 Pro',
+    kind: 'simulator',
+    booted: true,
+  };
+
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: 'default',
+      command: 'appstate',
+      positionals: [],
+      flags: { platform: 'ios', device: 'iPhone 17 Pro' },
+    },
+    sessionName: 'default',
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+    ensureReady: async () => {},
+    resolveTargetDevice: async () => selectedDevice,
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, false);
+  if (response && !response.ok) {
+    assert.equal(response.error.code, 'SESSION_NOT_FOUND');
+  }
+});
+
+test('appstate with explicit missing session returns SESSION_NOT_FOUND', async () => {
+  const sessionStore = makeSessionStore();
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: 'sim',
+      command: 'appstate',
+      positionals: [],
+      flags: { session: 'sim', platform: 'ios', device: 'iPhone 17 Pro' },
+    },
+    sessionName: 'sim',
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, false);
+  if (response && !response.ok) {
+    assert.equal(response.error.code, 'SESSION_NOT_FOUND');
+    assert.match(response.error.message, /no active session "sim"/i);
+    assert.doesNotMatch(response.error.message, /omit --session/i);
+  }
+});
+
 test('open URL on existing iOS session clears stale app bundle id', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'ios-session';
@@ -250,6 +543,7 @@ test('open --relaunch closes and reopens active session app', async () => {
       calls.push({ command, positionals });
       return {};
     },
+    ensureReady: async () => {},
   });
 
   assert.ok(response);
diff --git a/src/daemon/handlers/session.ts b/src/daemon/handlers/session.ts
index be778cf00..44a1cabd0 100644
--- a/src/daemon/handlers/session.ts
+++ b/src/daemon/handlers/session.ts
@@ -8,7 +8,6 @@ import type { DaemonRequest, DaemonResponse, SessionAction, SessionState } from
 import { SessionStore } from '../session-store.ts';
 import { contextFromFlags } from '../context.ts';
 import { ensureDeviceReady } from '../device-ready.ts';
-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 { extractNodeText, normalizeType, pruneGroupNodes } from '../snapshot-processing.ts';
@@ -26,17 +25,61 @@ type ReinstallOps = {
   android: (device: DeviceInfo, app: string, appPath: string) => Promise<{ package: string }>;
 };
 
+const IOS_APPSTATE_SESSION_REQUIRED_MESSAGE =
+  'iOS appstate requires an active session on the target device. Run open first (for example: open --session sim --platform ios --device "<name>" <app>).';
+
+function requireSessionOrExplicitSelector(
+  command: string,
+  session: SessionState | undefined,
+  flags: DaemonRequest['flags'] | undefined,
+): DaemonResponse | null {
+  if (session || hasExplicitDeviceSelector(flags)) {
+    return null;
+  }
+  return {
+    ok: false,
+    error: {
+      code: 'INVALID_ARGS',
+      message: `${command} requires an active session or an explicit device selector (e.g. --platform ios).`,
+    },
+  };
+}
+
 function hasExplicitDeviceSelector(flags: DaemonRequest['flags'] | undefined): boolean {
   return Boolean(flags?.platform || flags?.device || flags?.udid || flags?.serial);
 }
 
+function hasExplicitSessionFlag(flags: DaemonRequest['flags'] | undefined): boolean {
+  return typeof flags?.session === 'string' && flags.session.trim().length > 0;
+}
+
+function selectorTargetsSessionDevice(
+  flags: DaemonRequest['flags'] | undefined,
+  session: SessionState | undefined,
+): boolean {
+  if (!session) return false;
+  if (!hasExplicitDeviceSelector(flags)) return true;
+  if (flags?.platform && flags.platform !== session.device.platform) return false;
+  if (flags?.udid && flags.udid !== session.device.id) return false;
+  if (flags?.serial && flags.serial !== session.device.id) return false;
+  if (flags?.device) {
+    return flags.device.trim().toLowerCase() === session.device.name.trim().toLowerCase();
+  }
+  return true;
+}
+
 async function resolveCommandDevice(params: {
   session: SessionState | undefined;
   flags: DaemonRequest['flags'] | undefined;
   ensureReadyFn: typeof ensureDeviceReady;
+  resolveTargetDeviceFn: typeof resolveTargetDevice;
   ensureReady?: boolean;
 }): Promise<DeviceInfo> {
-  const device = params.session?.device ?? (await resolveTargetDevice(params.flags ?? {}));
+  const shouldUseExplicitSelector = hasExplicitDeviceSelector(params.flags);
+  const device =
+    shouldUseExplicitSelector || !params.session
+      ? await params.resolveTargetDeviceFn(params.flags ?? {})
+      : params.session.device;
   if (params.ensureReady !== false) {
     await params.ensureReadyFn(device);
   }
@@ -66,6 +109,92 @@ async function resolveIosBundleIdForOpen(device: DeviceInfo, openTarget: string
   }
 }
 
+async function handleAppStateCommand(params: {
+  req: DaemonRequest;
+  sessionName: string;
+  sessionStore: SessionStore;
+  ensureReady: typeof ensureDeviceReady;
+  resolveDevice: typeof resolveTargetDevice;
+}): Promise<DaemonResponse> {
+  const { req, sessionName, sessionStore, ensureReady, resolveDevice } = params;
+  const session = sessionStore.get(sessionName);
+  const flags = req.flags ?? {};
+  if (!session && hasExplicitSessionFlag(flags)) {
+    const iOSSessionHint =
+      flags.platform === 'ios'
+        ? `No active session "${sessionName}". Run open with --session ${sessionName} first.`
+        : `No active session "${sessionName}". Run open with --session ${sessionName} first, or omit --session to query by device selector.`;
+    return {
+      ok: false,
+      error: {
+        code: 'SESSION_NOT_FOUND',
+        message: iOSSessionHint,
+      },
+    };
+  }
+  const guard = requireSessionOrExplicitSelector('appstate', session, flags);
+  if (guard) return guard;
+
+  const shouldUseSessionStateForIos = session?.device.platform === 'ios' && selectorTargetsSessionDevice(flags, session);
+  const targetsIos = flags.platform === 'ios';
+  if (targetsIos && !shouldUseSessionStateForIos) {
+    return {
+      ok: false,
+      error: {
+        code: 'SESSION_NOT_FOUND',
+        message: IOS_APPSTATE_SESSION_REQUIRED_MESSAGE,
+      },
+    };
+  }
+  if (shouldUseSessionStateForIos) {
+    const appName = session.appName ?? session.appBundleId;
+    if (!appName && !session.appBundleId) {
+      return {
+        ok: false,
+        error: {
+          code: 'COMMAND_FAILED',
+          message: 'No foreground app is tracked for this iOS session. Open an app in the session, then retry appstate.',
+        },
+      };
+    }
+    return {
+      ok: true,
+      data: {
+        platform: 'ios',
+        appName: appName ?? 'unknown',
+        appBundleId: session.appBundleId,
+        source: 'session',
+      },
+    };
+  }
+  const device = await resolveCommandDevice({
+    session,
+    flags,
+    ensureReadyFn: ensureReady,
+    resolveTargetDeviceFn: resolveDevice,
+    ensureReady: true,
+  });
+  if (device.platform === 'ios') {
+    return {
+      ok: false,
+      error: {
+        code: 'SESSION_NOT_FOUND',
+        message: IOS_APPSTATE_SESSION_REQUIRED_MESSAGE,
+      },
+    };
+  }
+  const { getAndroidAppState } = await import('../../platforms/android/index.ts');
+  const state = await getAndroidAppState(device);
+  return {
+    ok: true,
+    data: {
+      platform: 'android',
+      package: state.package,
+      activity: state.activity,
+    },
+  };
+}
+
 export async function handleSessionCommands(params: {
   req: DaemonRequest;
   sessionName: string;
@@ -74,6 +203,7 @@ export async function handleSessionCommands(params: {
   invoke: (req: DaemonRequest) => Promise<DaemonResponse>;
   dispatch?: typeof dispatchCommand;
   ensureReady?: typeof ensureDeviceReady;
+  resolveTargetDevice?: typeof resolveTargetDevice;
   reinstallOps?: ReinstallOps;
 }): Promise<DaemonResponse | null> {
   const {
@@ -84,10 +214,12 @@ export async function handleSessionCommands(params: {
     invoke,
     dispatch: dispatchOverride,
     ensureReady: ensureReadyOverride,
+    resolveTargetDevice: resolveTargetDeviceOverride,
     reinstallOps = defaultReinstallOps,
   } = params;
   const dispatch = dispatchOverride ?? dispatchCommand;
   const ensureReady = ensureReadyOverride ?? ensureDeviceReady;
+  const resolveDevice = resolveTargetDeviceOverride ?? resolveTargetDevice;
   const command = req.command;
 
   if (command === 'session_list') {
@@ -136,56 +268,50 @@ export async function handleSessionCommands(params: {
   if (command === 'apps') {
     const session = sessionStore.get(sessionName);
     const flags = req.flags ?? {};
-    if (!session && !hasExplicitDeviceSelector(flags)) {
-      return {
-        ok: false,
-        error: {
-          code: 'INVALID_ARGS',
-          message: 'apps requires an active session or an explicit device selector (e.g. --platform ios).',
-        },
-      };
-    }
-    const device = await resolveCommandDevice({ session, flags, ensureReadyFn: ensureReady, ensureReady: true });
+    const guard = requireSessionOrExplicitSelector(command, session, flags);
+    if (guard) return guard;
+    const device = await resolveCommandDevice({
+      session,
+      flags,
+      ensureReadyFn: ensureReady,
+      resolveTargetDeviceFn: resolveDevice,
+      ensureReady: true,
+    });
     if (!isCommandSupportedOnDevice('apps', device)) {
       return { ok: false, error: { code: 'UNSUPPORTED_OPERATION', message: 'apps is not supported on this device' } };
     }
+    const appsFilter = req.flags?.appsFilter ?? 'all';
     if (device.platform === 'ios') {
-      const { listSimulatorApps } = await import('../../platforms/ios/index.ts');
-      const apps = await listSimulatorApps(device);
-      if (req.flags?.appsMetadata) {
-        return { ok: true, data: { apps } };
-      }
+      const { listIosApps } = await import('../../platforms/ios/index.ts');
+      const apps = await listIosApps(device, appsFilter);
       const formatted = apps.map((app) =>
         app.name && app.name !== app.bundleId ? `${app.name} (${app.bundleId})` : app.bundleId,
       );
       return { ok: true, data: { apps: formatted } };
     }
-    const { listAndroidApps, listAndroidAppsMetadata } = await import('../../platforms/android/index.ts');
-    if (req.flags?.appsMetadata) {
-      const apps = await listAndroidAppsMetadata(device, req.flags?.appsFilter);
-      return { ok: true, data: { apps } };
-    }
-    const apps = await listAndroidApps(device, req.flags?.appsFilter);
-    return { ok: true, data: { apps } };
+    const { listAndroidApps } = await import('../../platforms/android/index.ts');
+    const apps = await listAndroidApps(device, appsFilter);
+    const formatted = apps.map((app) =>
+      app.name && app.name !== app.package ? `${app.name} (${app.package})` : app.package,
+    );
+    return { ok: true, data: { apps: formatted } };
   }
 
   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));
+    const guard = requireSessionOrExplicitSelector(command, session, flags);
+    if (guard) return guard;
+    const device = await resolveCommandDevice({
+      session,
+      flags,
+      ensureReadyFn: ensureReady,
+      resolveTargetDeviceFn: resolveDevice,
+      ensureReady: true,
+    });
     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: {
@@ -199,61 +325,20 @@ export async function handleSessionCommands(params: {
   }
 
   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 {
-          ok: true,
-          data: {
-            platform: 'ios',
-            appBundleId: session.appBundleId,
-            appName: session.appName ?? session.appBundleId,
-            source: 'session',
-          },
-        };
-      }
-      const snapshotResult = await resolveIosAppStateFromSnapshots(
-        device,
-        logPath,
-        session?.trace?.outPath,
-        req.flags,
-      );
-      return {
-        ok: true,
-        data: {
-          platform: 'ios',
-          appName: snapshotResult.appName,
-          appBundleId: snapshotResult.appBundleId,
-          source: snapshotResult.source,
-        },
-      };
-    }
-    const { getAndroidAppState } = await import('../../platforms/android/index.ts');
-    const state = await getAndroidAppState(device);
-    return {
-      ok: true,
-      data: {
-        platform: 'android',
-        package: state.package,
-        activity: state.activity,
-      },
-    };
+    return await handleAppStateCommand({
+      req,
+      sessionName,
+      sessionStore,
+      ensureReady,
+      resolveDevice,
+    });
   }
 
   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 guard = requireSessionOrExplicitSelector(command, session, flags);
+    if (guard) return guard;
     const app = req.positionals?.[0]?.trim();
     const appPathInput = req.positionals?.[1]?.trim();
     if (!app || !appPathInput) {
@@ -269,7 +354,13 @@ export async function handleSessionCommands(params: {
         error: { code: 'INVALID_ARGS', message: `App binary not found: ${appPath}` },
       };
     }
-    const device = await resolveCommandDevice({ session, flags, ensureReadyFn: ensureReady, ensureReady: false });
+    const device = await resolveCommandDevice({
+      session,
+      flags,
+      ensureReadyFn: ensureReady,
+      resolveTargetDeviceFn: resolveDevice,
+      ensureReady: false,
+    });
     if (!isCommandSupportedOnDevice('reinstall', device)) {
       return {
         ok: false,
@@ -331,6 +422,7 @@ export async function handleSessionCommands(params: {
           },
         };
       }
+      await ensureReady(session.device);
       const appBundleId = await resolveIosBundleIdForOpen(session.device, openTarget);
       const openPositionals = requestedOpenTarget ? (req.positionals ?? []) : [openTarget];
       if (shouldRelaunch) {
@@ -377,7 +469,8 @@ export async function handleSessionCommands(params: {
         },
       };
     }
-    const device = await resolveTargetDevice(req.flags ?? {});
+    const device = await resolveDevice(req.flags ?? {});
+    await ensureReady(device);
     const inUse = sessionStore.toArray().find((s) => s.device.id === device.id);
     if (inUse) {
       return {
diff --git a/src/daemon/session-store.ts b/src/daemon/session-store.ts
index 76fc8c262..fec6e69e1 100644
--- a/src/daemon/session-store.ts
+++ b/src/daemon/session-store.ts
@@ -177,7 +177,6 @@ function sanitizeFlags(flags: CommandFlags | undefined): SessionAction['flags']
     snapshotScope,
     snapshotRaw,
     snapshotBackend,
-    appsMetadata,
     relaunch,
     saveScript,
     noRecord,
@@ -195,7 +194,6 @@ function sanitizeFlags(flags: CommandFlags | undefined): SessionAction['flags']
     snapshotScope,
     snapshotRaw,
     snapshotBackend,
-    appsMetadata,
     relaunch,
     saveScript,
     noRecord,
diff --git a/src/platforms/android/__tests__/index.test.ts b/src/platforms/android/__tests__/index.test.ts
index 6877bc629..1de17c866 100644
--- a/src/platforms/android/__tests__/index.test.ts
+++ b/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,120 @@ 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');
+});
+
+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',
diff --git a/src/platforms/android/index.ts b/src/platforms/android/index.ts
index 828554cff..4e660518b 100644
--- a/src/platforms/android/index.ts
+++ b/src/platforms/android/index.ts
@@ -48,60 +48,86 @@ 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);
+  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(
diff --git a/src/platforms/ios/__tests__/index.test.ts b/src/platforms/ios/__tests__/index.test.ts
index d96927468..970699e3c 100644
--- a/src/platforms/ios/__tests__/index.test.ts
+++ b/src/platforms/ios/__tests__/index.test.ts
@@ -1,6 +1,6 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { openIosApp } from '../index.ts';
+import { openIosApp, parseIosDeviceAppsPayload } from '../index.ts';
 import type { DeviceInfo } from '../../../utils/device.ts';
 import { AppError } from '../../../utils/errors.ts';
 
@@ -22,3 +22,41 @@ test('openIosApp rejects deep links on iOS physical devices', async () => {
     },
   );
 });
+
+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, []);
+});
diff --git a/src/platforms/ios/__tests__/runner-client.test.ts b/src/platforms/ios/__tests__/runner-client.test.ts
index b4d72d6ee..136ce196d 100644
--- a/src/platforms/ios/__tests__/runner-client.test.ts
+++ b/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);
+});
diff --git a/src/platforms/ios/apps.ts b/src/platforms/ios/apps.ts
new file mode 100644
index 000000000..4a7a2b6fe
--- /dev/null
+++ b/src/platforms/ios/apps.ts
@@ -0,0 +1,309 @@
+import type { DeviceInfo } from '../../utils/device.ts';
+import { AppError } from '../../utils/errors.ts';
+import { runCmd } from '../../utils/exec.ts';
+import { Deadline, retryWithPolicy } from '../../utils/retry.ts';
+import { isDeepLinkTarget } from '../../core/open-target.ts';
+
+import { IOS_APP_LAUNCH_TIMEOUT_MS } from './config.ts';
+import { listIosDeviceApps, runIosDevicectl, type IosAppInfo } from './devicectl.ts';
+import { ensureBootedSimulator, ensureSimulator, getSimulatorState } from './simulator.ts';
+
+const ALIASES: Record<string, string> = {
+  settings: 'com.apple.Preferences',
+};
+
+export async function resolveIosApp(device: DeviceInfo, app: string): Promise<string> {
+  const trimmed = app.trim();
+  if (trimmed.includes('.')) return trimmed;
+
+  const alias = ALIASES[trimmed.toLowerCase()];
+  if (alias) return alias;
+
+  if (device.kind === 'simulator') {
+    const list = await listSimulatorApps(device);
+    const matches = list.filter((entry) => entry.name.toLowerCase() === trimmed.toLowerCase());
+    if (matches.length === 1) return matches[0].bundleId;
+    if (matches.length > 1) {
+      throw new AppError('INVALID_ARGS', `Multiple apps matched "${app}"`, { matches });
+    }
+  }
+
+  throw new AppError('APP_NOT_INSTALLED', `No app found matching "${app}"`);
+}
+
+export async function openIosApp(
+  device: DeviceInfo,
+  app: string,
+  options?: { appBundleId?: string },
+): Promise<void> {
+  const deepLinkTarget = app.trim();
+  if (isDeepLinkTarget(deepLinkTarget)) {
+    if (device.kind !== 'simulator') {
+      throw new AppError('UNSUPPORTED_OPERATION', 'Deep link open is only supported on iOS simulators');
+    }
+    await ensureBootedSimulator(device);
+    await runCmd('open', ['-a', 'Simulator'], { allowFailure: true });
+    await runCmd('xcrun', ['simctl', 'openurl', device.id, deepLinkTarget]);
+    return;
+  }
+
+  const bundleId = options?.appBundleId ?? (await resolveIosApp(device, app));
+  if (device.kind === 'simulator') {
+    await launchIosSimulatorApp(device, bundleId);
+    return;
+  }
+
+  await runIosDevicectl(['device', 'process', 'launch', '--device', device.id, bundleId], {
+    action: 'launch iOS app',
+    deviceId: device.id,
+  });
+}
+
+export async function openIosDevice(device: DeviceInfo): Promise<void> {
+  if (device.kind !== 'simulator') return;
+  const state = await getSimulatorState(device.id);
+  if (state === 'Booted') return;
+
+  await ensureBootedSimulator(device);
+  await runCmd('open', ['-a', 'Simulator'], { allowFailure: true });
+}
+
+export async function closeIosApp(device: DeviceInfo, app: string): Promise<void> {
+  const bundleId = await resolveIosApp(device, app);
+  if (device.kind === 'simulator') {
+    await ensureBootedSimulator(device);
+    const result = await runCmd('xcrun', ['simctl', 'terminate', device.id, bundleId], {
+      allowFailure: true,
+    });
+    if (result.exitCode !== 0) {
+      const stderr = result.stderr.toLowerCase();
+      if (stderr.includes('found nothing to terminate')) return;
+      throw new AppError('COMMAND_FAILED', `xcrun exited with code ${result.exitCode}`, {
+        cmd: 'xcrun',
+        args: ['simctl', 'terminate', device.id, bundleId],
+        stdout: result.stdout,
+        stderr: result.stderr,
+        exitCode: result.exitCode,
+      });
+    }
+    return;
+  }
+
+  await runIosDevicectl(['device', 'process', 'terminate', '--device', device.id, bundleId], {
+    action: 'terminate iOS app',
+    deviceId: device.id,
+  });
+}
+
+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);
+    await runCmd('xcrun', ['simctl', 'io', device.id, 'screenshot', outPath]);
+    return;
+  }
+
+  await runIosDevicectl(['device', 'screenshot', '--device', device.id, outPath], {
+    action: 'capture iOS screenshot',
+    deviceId: device.id,
+  });
+}
+
+export async function setIosSetting(
+  device: DeviceInfo,
+  setting: string,
+  state: string,
+  appBundleId?: string,
+): Promise<void> {
+  ensureSimulator(device, 'settings');
+  await ensureBootedSimulator(device);
+  const normalized = setting.toLowerCase();
+  const enabled = parseSettingState(state);
+
+  switch (normalized) {
+    case 'wifi': {
+      const mode = enabled ? 'active' : 'failed';
+      await runCmd('xcrun', ['simctl', 'status_bar', device.id, 'override', '--wifiMode', mode]);
+      return;
+    }
+    case 'airplane': {
+      if (enabled) {
+        await runCmd('xcrun', [
+          'simctl',
+          'status_bar',
+          device.id,
+          'override',
+          '--dataNetwork',
+          'hide',
+          '--wifiMode',
+          'failed',
+          '--wifiBars',
+          '0',
+          '--cellularMode',
+          'failed',
+          '--cellularBars',
+          '0',
+          '--operatorName',
+          '',
+        ]);
+      } else {
+        await runCmd('xcrun', ['simctl', 'status_bar', device.id, 'clear']);
+      }
+      return;
+    }
+    case 'location': {
+      if (!appBundleId) {
+        throw new AppError('INVALID_ARGS', 'location setting requires an active app in session');
+      }
+      const action = enabled ? 'grant' : 'revoke';
+      await runCmd('xcrun', ['simctl', 'privacy', device.id, action, 'location', appBundleId]);
+      return;
+    }
+    default:
+      throw new AppError('INVALID_ARGS', `Unsupported setting: ${setting}`);
+  }
+}
+
+export async function listIosApps(
+  device: DeviceInfo,
+  filter: 'user-installed' | 'all' = 'all',
+): Promise<IosAppInfo[]> {
+  if (device.kind === 'simulator') {
+    return await listSimulatorApps(device);
+  }
+  return await listIosDeviceApps(device, filter);
+}
+
+export async function listSimulatorApps(device: DeviceInfo): Promise<IosAppInfo[]> {
+  const result = await runCmd('xcrun', ['simctl', 'listapps', device.id], { allowFailure: true });
+  const stdout = result.stdout as string;
+  const trimmed = stdout.trim();
+  if (!trimmed) return [];
+
+  let parsed: Record<string, { CFBundleDisplayName?: string; CFBundleName?: string }> | null = null;
+  if (trimmed.startsWith('{')) {
+    try {
+      parsed = JSON.parse(trimmed) as Record<string, { CFBundleDisplayName?: string; CFBundleName?: string }>;
+    } catch {
+      parsed = null;
+    }
+  }
+
+  if (!parsed && trimmed.startsWith('{')) {
+    try {
+      const converted = await runCmd('plutil', ['-convert', 'json', '-o', '-', '-'], {
+        allowFailure: true,
+        stdin: trimmed,
+      });
+      if (converted.exitCode === 0 && converted.stdout.trim().startsWith('{')) {
+        parsed = JSON.parse(converted.stdout) as Record<
+          string,
+          { CFBundleDisplayName?: string; CFBundleName?: string }
+        >;
+      }
+    } catch {
+      parsed = null;
+    }
+  }
+
+  if (!parsed) return [];
+  return Object.entries(parsed).map(([bundleId, info]) => ({
+    bundleId,
+    name: info.CFBundleDisplayName ?? info.CFBundleName ?? bundleId,
+  }));
+}
+
+function parseSettingState(state: string): boolean {
+  const normalized = state.toLowerCase();
+  if (normalized === 'on' || normalized === 'true' || normalized === '1') return true;
+  if (normalized === 'off' || normalized === 'false' || normalized === '0') return false;
+  throw new AppError('INVALID_ARGS', `Invalid setting state: ${state}`);
+}
+
+function isTransientSimulatorLaunchFailure(error: unknown): boolean {
+  if (!(error instanceof AppError)) return false;
+  if (error.code !== 'COMMAND_FAILED') return false;
+
+  const details = (error.details ?? {}) as { exitCode?: number; stderr?: unknown };
+  if (details.exitCode !== 4) return false;
+  const stderr = String(details.stderr ?? '').toLowerCase();
+
+  return (
+    stderr.includes('fbsopenapplicationserviceerrordomain') &&
+    stderr.includes('the request to open')
+  );
+}
+
+async function launchIosSimulatorApp(device: DeviceInfo, bundleId: string): Promise<void> {
+  await ensureBootedSimulator(device);
+  await runCmd('open', ['-a', 'Simulator'], { allowFailure: true });
+
+  const launchDeadline = Deadline.fromTimeoutMs(IOS_APP_LAUNCH_TIMEOUT_MS);
+  await retryWithPolicy(
+    async ({ deadline: attemptDeadline }) => {
+      if (attemptDeadline?.isExpired()) {
+        throw new AppError('COMMAND_FAILED', 'App launch deadline exceeded', {
+          timeoutMs: IOS_APP_LAUNCH_TIMEOUT_MS,
+        });
+      }
+
+      const result = await runCmd('xcrun', ['simctl', 'launch', device.id, bundleId], {
+        allowFailure: true,
+      });
+      if (result.exitCode === 0) return;
+
+      throw new AppError('COMMAND_FAILED', `xcrun exited with code ${result.exitCode}`, {
+        cmd: 'xcrun',
+        args: ['simctl', 'launch', device.id, bundleId],
+        stdout: result.stdout,
+        stderr: result.stderr,
+        exitCode: result.exitCode,
+      });
+    },
+    {
+      maxAttempts: 30,
+      baseDelayMs: 1_000,
+      maxDelayMs: 5_000,
+      jitter: 0.2,
+      shouldRetry: isTransientSimulatorLaunchFailure,
+    },
+    { deadline: launchDeadline },
+  );
+}
diff --git a/src/platforms/ios/config.ts b/src/platforms/ios/config.ts
new file mode 100644
index 000000000..2b29cd80b
--- /dev/null
+++ b/src/platforms/ios/config.ts
@@ -0,0 +1,34 @@
+import { isEnvTruthy, TIMEOUT_PROFILES } from '../../utils/retry.ts';
+
+export const IOS_BOOT_TIMEOUT_MS = resolveTimeoutMs(
+  process.env.AGENT_DEVICE_IOS_BOOT_TIMEOUT_MS,
+  TIMEOUT_PROFILES.ios_boot.totalMs,
+  5_000,
+);
+
+export const IOS_SIMCTL_LIST_TIMEOUT_MS = resolveTimeoutMs(
+  process.env.AGENT_DEVICE_IOS_SIMCTL_LIST_TIMEOUT_MS,
+  TIMEOUT_PROFILES.ios_boot.operationMs,
+  1_000,
+);
+
+export const IOS_APP_LAUNCH_TIMEOUT_MS = resolveTimeoutMs(
+  process.env.AGENT_DEVICE_IOS_APP_LAUNCH_TIMEOUT_MS,
+  30_000,
+  5_000,
+);
+
+export const IOS_DEVICECTL_TIMEOUT_MS = resolveTimeoutMs(
+  process.env.AGENT_DEVICE_IOS_DEVICECTL_TIMEOUT_MS,
+  20_000,
+  1_000,
+);
+
+export const RETRY_LOGS_ENABLED = isEnvTruthy(process.env.AGENT_DEVICE_RETRY_LOGS);
+
+function resolveTimeoutMs(raw: string | undefined, fallback: number, min: number): number {
+  if (!raw) return fallback;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.max(min, Math.floor(parsed));
+}
diff --git a/src/platforms/ios/devicectl.ts b/src/platforms/ios/devicectl.ts
new file mode 100644
index 000000000..b9864899b
--- /dev/null
+++ b/src/platforms/ios/devicectl.ts
@@ -0,0 +1,131 @@
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import type { DeviceInfo } from '../../utils/device.ts';
+import { AppError } from '../../utils/errors.ts';
+import { runCmd } from '../../utils/exec.ts';
+
+import { IOS_DEVICECTL_TIMEOUT_MS } from './config.ts';
+
+export type IosAppInfo = {
+  bundleId: string;
+  name: string;
+};
+
+type IosDeviceAppsPayload = {
+  result?: {
+    apps?: Array<{
+      bundleIdentifier?: unknown;
+      name?: unknown;
+    }>;
+  };
+};
+
+export async function runIosDevicectl(
+  args: string[],
+  context: { action: string; deviceId: string },
+): Promise<void> {
+  const fullArgs = ['devicectl', ...args];
+  const result = await runCmd('xcrun', fullArgs, {
+    allowFailure: true,
+    timeoutMs: IOS_DEVICECTL_TIMEOUT_MS,
+  });
+  if (result.exitCode === 0) return;
+  const stdout = String(result.stdout ?? '');
+  const stderr = String(result.stderr ?? '');
+  throw new AppError('COMMAND_FAILED', `Failed to ${context.action}`, {
+    cmd: 'xcrun',
+    args: fullArgs,
+    exitCode: result.exitCode,
+    stdout,
+    stderr,
+    deviceId: context.deviceId,
+    hint: resolveIosDevicectlHint(stdout, stderr),
+  });
+}
+
+export async function listIosDeviceApps(
+  device: DeviceInfo,
+  filter: 'user-installed' | 'all',
+): Promise<IosAppInfo[]> {
+  const jsonPath = path.join(
+    os.tmpdir(),
+    `agent-device-ios-apps-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}.json`,
+  );
+  const args = [
+    'devicectl',
+    'device',
+    'info',
+    'apps',
+    '--device',
+    device.id,
+    '--include-all-apps',
+    '--json-output',
+    jsonPath,
+  ];
+  const result = await runCmd('xcrun', args, {
+    allowFailure: true,
+    timeoutMs: IOS_DEVICECTL_TIMEOUT_MS,
+  });
+
+  try {
+    if (result.exitCode !== 0) {
+      const stdout = String(result.stdout ?? '');
+      const stderr = String(result.stderr ?? '');
+      throw new AppError('COMMAND_FAILED', 'Failed to list iOS apps', {
+        cmd: 'xcrun',
+        args,
+        exitCode: result.exitCode,
+        stdout,
+        stderr,
+        deviceId: device.id,
+        hint: resolveIosDevicectlHint(stdout, stderr),
+      });
+    }
+    const jsonText = await fs.readFile(jsonPath, 'utf8');
+    const apps = parseIosDeviceAppsPayload(JSON.parse(jsonText));
+    return filterIosDeviceApps(apps, filter);
+  } catch (error) {
+    if (error instanceof AppError) throw error;
+    throw new AppError('COMMAND_FAILED', 'Failed to parse iOS apps list', {
+      deviceId: device.id,
+      cause: String(error),
+    });
+  } finally {
+    await fs.unlink(jsonPath).catch(() => {});
+  }
+}
+
+export function parseIosDeviceAppsPayload(payload: unknown): IosAppInfo[] {
+  const apps = (payload as IosDeviceAppsPayload | null | undefined)?.result?.apps;
+  if (!Array.isArray(apps)) return [];
+
+  const parsed: IosAppInfo[] = [];
+  for (const entry of apps) {
+    if (!entry || typeof entry !== 'object') continue;
+    const bundleId = typeof entry.bundleIdentifier === 'string' ? entry.bundleIdentifier.trim() : '';
+    if (!bundleId) continue;
+    const name = typeof entry.name === 'string' && entry.name.trim().length > 0 ? entry.name.trim() : bundleId;
+    parsed.push({ bundleId, name });
+  }
+  return parsed;
+}
+
+function filterIosDeviceApps(apps: IosAppInfo[], filter: 'user-installed' | 'all'): IosAppInfo[] {
+  if (filter === 'user-installed') {
+    return apps.filter((app) => !app.bundleId.startsWith('com.apple.'));
+  }
+  return apps;
+}
+
+function resolveIosDevicectlHint(stdout: string, stderr: string): string {
+  const text = `${stdout}\n${stderr}`.toLowerCase();
+  if (text.includes('device is busy') && text.includes('connecting')) {
+    return 'iOS device is still connecting. Keep it unlocked and connected by cable until it is fully available in Xcode Devices, then retry.';
+  }
+  if (text.includes('coredeviceservice') && text.includes('timed out')) {
+    return 'CoreDevice service timed out. Reconnect the device and retry; if it persists restart Xcode and the iOS device.';
+  }
+  return 'Ensure the iOS device is unlocked, trusted, and available in Xcode > Devices, then retry.';
+}
diff --git a/src/platforms/ios/devices.ts b/src/platforms/ios/devices.ts
index e465e7a24..0aa1b4f4a 100644
--- a/src/platforms/ios/devices.ts
+++ b/src/platforms/ios/devices.ts
@@ -5,6 +5,12 @@ import { runCmd, whichCmd } from '../../utils/exec.ts';
 import { AppError } from '../../utils/errors.ts';
 import type { DeviceInfo } from '../../utils/device.ts';
 
+const IOS_DEVICECTL_LIST_TIMEOUT_MS = resolveTimeoutMs(
+  process.env.AGENT_DEVICE_IOS_DEVICECTL_LIST_TIMEOUT_MS,
+  8_000,
+  500,
+);
+
 export async function listIosDevices(): Promise<DeviceInfo[]> {
   if (process.platform !== 'darwin') {
     throw new AppError('UNSUPPORTED_PLATFORM', 'iOS tools are only available on macOS');
@@ -47,7 +53,13 @@ export async function listIosDevices(): Promise<DeviceInfo[]> {
       os.tmpdir(),
       `agent-device-devicectl-${process.pid}-${Date.now()}.json`,
     );
-    await runCmd('xcrun', ['devicectl', 'list', 'devices', '--json-output', jsonPath]);
+    const devicectlResult = await runCmd('xcrun', ['devicectl', 'list', 'devices', '--json-output', jsonPath], {
+      allowFailure: true,
+      timeoutMs: IOS_DEVICECTL_LIST_TIMEOUT_MS,
+    });
+    if (devicectlResult.exitCode !== 0) {
+      return devices;
+    }
     const jsonText = await fs.readFile(jsonPath, 'utf8');
     const payload = JSON.parse(jsonText) as {
       result?: {
@@ -85,3 +97,10 @@ export async function listIosDevices(): Promise<DeviceInfo[]> {
 
   return devices;
 }
+
+function resolveTimeoutMs(raw: string | undefined, fallback: number, min: number): number {
+  if (!raw) return fallback;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.max(min, Math.floor(parsed));
+}
diff --git a/src/platforms/ios/index.ts b/src/platforms/ios/index.ts
index 4da75c1d0..6728c437e 100644
--- a/src/platforms/ios/index.ts
+++ b/src/platforms/ios/index.ts
@@ -1,455 +1,20 @@
-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, isEnvTruthy, retryWithPolicy, TIMEOUT_PROFILES, type RetryTelemetryEvent } from '../../utils/retry.ts';
-import { isDeepLinkTarget } from '../../core/open-target.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,
-  TIMEOUT_PROFILES.ios_boot.totalMs,
-  5_000,
-);
-const IOS_SIMCTL_LIST_TIMEOUT_MS = resolveTimeoutMs(
-  process.env.AGENT_DEVICE_IOS_SIMCTL_LIST_TIMEOUT_MS,
-  TIMEOUT_PROFILES.ios_boot.operationMs,
-  1_000,
-);
-const IOS_APP_LAUNCH_TIMEOUT_MS = resolveTimeoutMs(
-  process.env.AGENT_DEVICE_IOS_APP_LAUNCH_TIMEOUT_MS,
-  30_000,
-  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();
-  if (trimmed.includes('.')) return trimmed;
-
-  const alias = ALIASES[trimmed.toLowerCase()];
-  if (alias) return alias;
-
-  if (device.kind === 'simulator') {
-    const list = await listSimulatorApps(device);
-    const matches = list.filter((entry) => entry.name.toLowerCase() === trimmed.toLowerCase());
-    if (matches.length === 1) return matches[0].bundleId;
-    if (matches.length > 1) {
-      throw new AppError('INVALID_ARGS', `Multiple apps matched "${app}"`, { matches });
-    }
-  }
-
-  throw new AppError('APP_NOT_INSTALLED', `No app found matching "${app}"`);
-}
-
-export async function openIosApp(
-  device: DeviceInfo,
-  app: string,
-  options?: { appBundleId?: string },
-): Promise<void> {
-  const deepLinkTarget = app.trim();
-  if (isDeepLinkTarget(deepLinkTarget)) {
-    if (device.kind !== 'simulator') {
-      throw new AppError('UNSUPPORTED_OPERATION', 'Deep link open is only supported on iOS simulators');
-    }
-    await ensureBootedSimulator(device);
-    await runCmd('open', ['-a', 'Simulator'], { allowFailure: true });
-    await runCmd('xcrun', ['simctl', 'openurl', device.id, deepLinkTarget]);
-    return;
-  }
-  const bundleId = options?.appBundleId ?? (await resolveIosApp(device, app));
-  if (device.kind === 'simulator') {
-    await ensureBootedSimulator(device);
-    await runCmd('open', ['-a', 'Simulator'], { allowFailure: true });
-    const launchDeadline = Deadline.fromTimeoutMs(IOS_APP_LAUNCH_TIMEOUT_MS);
-    await retryWithPolicy(
-      async ({ deadline: attemptDeadline }) => {
-        if (attemptDeadline?.isExpired()) {
-          throw new AppError('COMMAND_FAILED', 'App launch deadline exceeded', {
-            timeoutMs: IOS_APP_LAUNCH_TIMEOUT_MS,
-          });
-        }
-        const result = await runCmd('xcrun', ['simctl', 'launch', device.id, bundleId], {
-          allowFailure: true,
-        });
-        if (result.exitCode === 0) return;
-        throw new AppError('COMMAND_FAILED', `xcrun exited with code ${result.exitCode}`, {
-          cmd: 'xcrun',
-          args: ['simctl', 'launch', device.id, bundleId],
-          stdout: result.stdout,
-          stderr: result.stderr,
-          exitCode: result.exitCode,
-        });
-      },
-      {
-        maxAttempts: 30,
-        baseDelayMs: 1_000,
-        maxDelayMs: 5_000,
-        jitter: 0.2,
-        shouldRetry: isTransientSimulatorLaunchFailure,
-      },
-      { deadline: launchDeadline },
-    );
-    return;
-  }
-  await runCmd('xcrun', [
-    'devicectl',
-    'device',
-    'process',
-    'launch',
-    '--device',
-    device.id,
-    bundleId,
-  ]);
-}
-
-export async function openIosDevice(device: DeviceInfo): Promise<void> {
-  if (device.kind !== 'simulator') return;
-  const state = await getSimulatorState(device.id);
-  if (state === 'Booted') return;
-  await ensureBootedSimulator(device);
-  await runCmd('open', ['-a', 'Simulator'], { allowFailure: true });
-}
-
-export async function closeIosApp(device: DeviceInfo, app: string): Promise<void> {
-  const bundleId = await resolveIosApp(device, app);
-  if (device.kind === 'simulator') {
-    await ensureBootedSimulator(device);
-    const result = await runCmd('xcrun', ['simctl', 'terminate', device.id, bundleId], {
-      allowFailure: true,
-    });
-    if (result.exitCode !== 0) {
-      const stderr = result.stderr.toLowerCase();
-      if (stderr.includes('found nothing to terminate')) return;
-      throw new AppError('COMMAND_FAILED', `xcrun exited with code ${result.exitCode}`, {
-        cmd: 'xcrun',
-        args: ['simctl', 'terminate', device.id, bundleId],
-        stdout: result.stdout,
-        stderr: result.stderr,
-        exitCode: result.exitCode,
-      });
-    }
-    return;
-  }
-  await runCmd('xcrun', [
-    'devicectl',
-    'device',
-    'process',
-    'terminate',
-    '--device',
-    device.id,
-    bundleId,
-  ]);
-}
-
-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);
-    await runCmd('xcrun', ['simctl', 'io', device.id, 'screenshot', outPath]);
-    return;
-  }
-  await runCmd('xcrun', ['devicectl', 'device', 'screenshot', '--device', device.id, outPath]);
-}
-
-export async function setIosSetting(
-  device: DeviceInfo,
-  setting: string,
-  state: string,
-  appBundleId?: string,
-): Promise<void> {
-  ensureSimulator(device, 'settings');
-  await ensureBootedSimulator(device);
-  const normalized = setting.toLowerCase();
-  const enabled = parseSettingState(state);
-  switch (normalized) {
-    case 'wifi': {
-      const mode = enabled ? 'active' : 'failed';
-      await runCmd('xcrun', ['simctl', 'status_bar', device.id, 'override', '--wifiMode', mode]);
-      return;
-    }
-    case 'airplane': {
-      if (enabled) {
-        await runCmd('xcrun', [
-          'simctl',
-          'status_bar',
-          device.id,
-          'override',
-          '--dataNetwork',
-          'hide',
-          '--wifiMode',
-          'failed',
-          '--wifiBars',
-          '0',
-          '--cellularMode',
-          'failed',
-          '--cellularBars',
-          '0',
-          '--operatorName',
-          '',
-        ]);
-      } else {
-        await runCmd('xcrun', ['simctl', 'status_bar', device.id, 'clear']);
-      }
-      return;
-    }
-    case 'location': {
-      if (!appBundleId) {
-        throw new AppError('INVALID_ARGS', 'location setting requires an active app in session');
-      }
-      const action = enabled ? 'grant' : 'revoke';
-      await runCmd('xcrun', ['simctl', 'privacy', device.id, action, 'location', appBundleId]);
-      return;
-    }
-    default:
-      throw new AppError('INVALID_ARGS', `Unsupported setting: ${setting}`);
-  }
-}
-
-function ensureSimulator(device: DeviceInfo, command: string): void {
-  if (device.kind !== 'simulator') {
-    throw new AppError(
-      'UNSUPPORTED_OPERATION',
-      `${command} is only supported on iOS simulators`,
-    );
-  }
-}
-
-function parseSettingState(state: string): boolean {
-  const normalized = state.toLowerCase();
-  if (normalized === 'on' || normalized === 'true' || normalized === '1') return true;
-  if (normalized === 'off' || normalized === 'false' || normalized === '0') return false;
-  throw new AppError('INVALID_ARGS', `Invalid setting state: ${state}`);
-}
-
-function isTransientSimulatorLaunchFailure(error: unknown): boolean {
-  if (!(error instanceof AppError)) return false;
-  if (error.code !== 'COMMAND_FAILED') return false;
-  const details = (error.details ?? {}) as { exitCode?: number; stderr?: unknown };
-  if (details.exitCode !== 4) return false;
-  const stderr = String(details.stderr ?? '').toLowerCase();
-  return (
-    stderr.includes('fbsopenapplicationserviceerrordomain') &&
-    stderr.includes('the request to open')
-  );
-}
-
-export async function listSimulatorApps(
-  device: DeviceInfo,
-): Promise<{ bundleId: string; name: string }[]> {
-  const result = await runCmd('xcrun', ['simctl', 'listapps', device.id], { allowFailure: true });
-  const stdout = result.stdout as string;
-  const trimmed = stdout.trim();
-  if (!trimmed) return [];
-  let parsed: Record<string, { CFBundleDisplayName?: string; CFBundleName?: string }> | null = null;
-  if (trimmed.startsWith('{')) {
-    try {
-      parsed = JSON.parse(trimmed) as Record<
-        string,
-        { CFBundleDisplayName?: string; CFBundleName?: string }
-      >;
-    } catch {
-      parsed = null;
-    }
-  }
-  if (!parsed && trimmed.startsWith('{')) {
-    try {
-      const converted = await runCmd('plutil', ['-convert', 'json', '-o', '-', '-'], {
-        allowFailure: true,
-        stdin: trimmed,
-      });
-      if (converted.exitCode === 0 && converted.stdout.trim().startsWith('{')) {
-        parsed = JSON.parse(converted.stdout) as Record<
-          string,
-          { CFBundleDisplayName?: string; CFBundleName?: string }
-        >;
-      }
-    } catch {
-      parsed = null;
-    }
-  }
-  if (!parsed) return [];
-  return Object.entries(parsed).map(([bundleId, info]) => ({
-    bundleId,
-    name: info.CFBundleDisplayName ?? info.CFBundleName ?? bundleId,
-  }));
-}
-
-export async function ensureBootedSimulator(device: DeviceInfo): Promise<void> {
-  if (device.kind !== 'simulator') return;
-  const state = await getSimulatorState(device.id);
-  if (state === 'Booted') return;
-  const deadline = Deadline.fromTimeoutMs(IOS_BOOT_TIMEOUT_MS);
-  let bootResult: ExecResult | undefined;
-  let bootStatusResult: ExecResult | undefined;
-  try {
-    await retryWithPolicy(
-      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');
-        if (bootResult.exitCode !== 0 && !bootAlreadyDone) {
-          throw new AppError('COMMAND_FAILED', 'simctl boot failed', {
-            stdout: bootResult.stdout,
-            stderr: bootResult.stderr,
-            exitCode: bootResult.exitCode,
-          });
-        }
-        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', {
-            stdout: bootStatusResult.stdout,
-            stderr: bootStatusResult.stderr,
-            exitCode: bootStatusResult.exitCode,
-          });
-        }
-        const nextState = await getSimulatorState(device.id);
-        if (nextState !== 'Booted') {
-          throw new AppError('COMMAND_FAILED', 'Simulator is still booting', {
-            state: nextState,
-          });
-        }
-      },
-      {
-        maxAttempts: 3,
-        baseDelayMs: 500,
-        maxDelayMs: 2000,
-        jitter: 0.2,
-        shouldRetry: (error) => {
-          const reason = classifyBootFailure({
-            error,
-            stdout: bootStatusResult?.stdout ?? bootResult?.stdout,
-            stderr: bootStatusResult?.stderr ?? bootResult?.stderr,
-            context: { platform: 'ios', phase: 'boot' },
-          });
-          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`);
-        },
-      },
-    );
-  } catch (error) {
-    const bootStdout = bootResult?.stdout;
-    const bootStderr = bootResult?.stderr;
-    const bootExitCode = bootResult?.exitCode;
-    const bootstatusStdout = bootStatusResult?.stdout;
-    const bootstatusStderr = bootStatusResult?.stderr;
-    const bootstatusExitCode = bootStatusResult?.exitCode;
-    const reason = classifyBootFailure({
-      error,
-      stdout: bootstatusStdout ?? bootStdout,
-      stderr: bootstatusStderr ?? bootStderr,
-      context: { platform: 'ios', phase: 'boot' },
-    });
-    throw new AppError('COMMAND_FAILED', 'iOS simulator failed to boot', {
-      platform: 'ios',
-      deviceId: device.id,
-      timeoutMs: IOS_BOOT_TIMEOUT_MS,
-      elapsedMs: deadline.elapsedMs(),
-      reason,
-      hint: bootFailureHint(reason),
-      boot: bootResult
-        ? { exitCode: bootExitCode, stdout: bootStdout, stderr: bootStderr }
-        : undefined,
-      bootstatus: bootStatusResult
-        ? {
-          exitCode: bootstatusExitCode,
-          stdout: bootstatusStdout,
-          stderr: bootstatusStderr,
-        }
-        : undefined,
-    });
-  }
-}
-
-async function getSimulatorState(udid: string): Promise<string | null> {
-  const result = await runCmd('xcrun', ['simctl', 'list', 'devices', '-j'], {
-    allowFailure: true,
-    timeoutMs: IOS_SIMCTL_LIST_TIMEOUT_MS,
-  });
-  if (result.exitCode !== 0) return null;
-  try {
-    const payload = JSON.parse(result.stdout as string) as {
-      devices: Record<string, { udid: string; state: string }[]>;
-    };
-    for (const runtime of Object.values(payload.devices ?? {})) {
-      const match = runtime.find((d) => d.udid === udid);
-      if (match) return match.state;
-    }
-  } catch {
-    return null;
-  }
-  return null;
-}
-
-function resolveTimeoutMs(raw: string | undefined, fallback: number, min: number): number {
-  if (!raw) return fallback;
-  const parsed = Number(raw);
-  if (!Number.isFinite(parsed)) return fallback;
-  return Math.max(min, Math.floor(parsed));
-}
+export {
+  closeIosApp,
+  installIosApp,
+  listIosApps,
+  listSimulatorApps,
+  openIosApp,
+  openIosDevice,
+  reinstallIosApp,
+  resolveIosApp,
+  screenshotIos,
+  setIosSetting,
+  uninstallIosApp,
+} from './apps.ts';
+
+export { ensureBootedSimulator } from './simulator.ts';
+
+export {
+  parseIosDeviceAppsPayload,
+  type IosAppInfo,
+} from './devicectl.ts';
diff --git a/src/platforms/ios/runner-client.ts b/src/platforms/ios/runner-client.ts
index 90b850075..fe68248df 100644
--- a/src/platforms/ios/runner-client.ts
+++ b/src/platforms/ios/runner-client.ts
@@ -60,7 +60,7 @@ const runnerSessions = new Map<string, RunnerSession>();
 const runnerSessionLocks = new Map<string, Promise<unknown>>();
 const RUNNER_STARTUP_TIMEOUT_MS = resolveTimeoutMs(
   process.env.AGENT_DEVICE_RUNNER_STARTUP_TIMEOUT_MS,
-  120_000,
+  45_000,
   5_000,
 );
 const RUNNER_COMMAND_TIMEOUT_MS = resolveTimeoutMs(
@@ -75,24 +75,29 @@ const RUNNER_CONNECT_ATTEMPT_INTERVAL_MS = resolveTimeoutMs(
 );
 const RUNNER_CONNECT_RETRY_BASE_DELAY_MS = resolveTimeoutMs(
   process.env.AGENT_DEVICE_RUNNER_CONNECT_RETRY_BASE_DELAY_MS,
-  100,
+  300,
   10,
 );
 const RUNNER_CONNECT_RETRY_MAX_DELAY_MS = resolveTimeoutMs(
   process.env.AGENT_DEVICE_RUNNER_CONNECT_RETRY_MAX_DELAY_MS,
-  500,
+  2_000,
   10,
 );
 const RUNNER_CONNECT_REQUEST_TIMEOUT_MS = resolveTimeoutMs(
   process.env.AGENT_DEVICE_RUNNER_CONNECT_REQUEST_TIMEOUT_MS,
-  1_000,
-  50,
+  5_000,
+  250,
 );
 const RUNNER_DEVICE_INFO_TIMEOUT_MS = resolveTimeoutMs(
   process.env.AGENT_DEVICE_IOS_DEVICE_INFO_TIMEOUT_MS,
   10_000,
   500,
 );
+const RUNNER_DESTINATION_TIMEOUT_SECONDS = resolveTimeoutSeconds(
+  process.env.AGENT_DEVICE_RUNNER_DESTINATION_TIMEOUT_SECONDS,
+  20,
+  5,
+);
 const RUNNER_STOP_WAIT_TIMEOUT_MS = 10_000;
 const RUNNER_SHUTDOWN_TIMEOUT_MS = 15_000;
 const RUNNER_DERIVED_ROOT = path.join(os.homedir(), '.agent-device', 'ios-runner');
@@ -104,6 +109,13 @@ function resolveTimeoutMs(raw: string | undefined, fallback: number, min: number
   return Math.max(min, Math.floor(parsed));
 }
 
+function resolveTimeoutSeconds(raw: string | undefined, fallback: number, min: number): number {
+  if (!raw) return fallback;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.max(min, Math.floor(parsed));
+}
+
 export type RunnerSnapshotNode = {
   index: number;
   type?: string;
@@ -156,7 +168,9 @@ async function executeRunnerCommand(
     if (
       appErr.code === 'COMMAND_FAILED' &&
       typeof appErr.message === 'string' &&
-      appErr.message.includes('Runner did not accept connection')
+      appErr.message.includes('Runner did not accept connection') &&
+      shouldRetryRunnerConnectError(appErr) &&
+      session?.ready
     ) {
       if (session) {
         await stopRunnerSession(session);
@@ -184,7 +198,7 @@ async function executeRunnerCommandWithSession(
   logPath: string | undefined,
   timeoutMs: number,
 ): Promise<Record<string, unknown>> {
-  const response = await waitForRunner(device, session.port, command, logPath, timeoutMs);
+  const response = await waitForRunner(device, session.port, command, logPath, timeoutMs, session);
   return await parseRunnerResponse(response, session, logPath);
 }
 
@@ -304,6 +318,8 @@ async function ensureRunnerSession(
         'NO',
         resolveRunnerMaxConcurrentDestinationsFlag(device),
         '1',
+        '-destination-timeout',
+        String(RUNNER_DESTINATION_TIMEOUT_SECONDS),
         '-xctestrun',
         xctestrunPath,
         '-destination',
@@ -437,6 +453,10 @@ function resolveRunnerDerivedPath(kind: DeviceInfo['kind']): string {
   if (override) {
     return path.resolve(override);
   }
+  if (kind === 'simulator') {
+    // Keep simulator runtime path aligned with pnpm build:xcuitest/build:all.
+    return path.join(RUNNER_DERIVED_ROOT, 'derived');
+  }
   return path.join(RUNNER_DERIVED_ROOT, 'derived', kind);
 }
 
@@ -565,10 +585,12 @@ function logChunk(chunk: string, logPath?: string, traceLogPath?: string, verbos
   }
 }
 
-function isRetryableRunnerError(err: unknown): boolean {
+export function isRetryableRunnerError(err: unknown): boolean {
   if (!(err instanceof AppError)) return false;
   if (err.code !== 'COMMAND_FAILED') return false;
   const message = `${err.message ?? ''}`.toLowerCase();
+  if (message.includes('xcodebuild exited early')) return false;
+  if (message.includes('device is busy') && message.includes('connecting')) return false;
   if (message.includes('runner did not accept connection')) return true;
   if (message.includes('fetch failed')) return true;
   if (message.includes('econnrefused')) return true;
@@ -631,12 +653,56 @@ function buildRunnerConnectError(params: {
   });
 }
 
+export function resolveRunnerEarlyExitHint(message: string, stdout: string, stderr: string): string {
+  const haystack = `${message}\n${stdout}\n${stderr}`.toLowerCase();
+  if (haystack.includes('device is busy') && haystack.includes('connecting')) {
+    return 'Target iOS device is still connecting. Keep it unlocked, wait for device trust/connection to settle, then retry.';
+  }
+  return bootFailureHint('IOS_RUNNER_CONNECT_TIMEOUT');
+}
+
+export function shouldRetryRunnerConnectError(error: unknown): boolean {
+  if (!(error instanceof AppError)) return true;
+  if (error.code !== 'COMMAND_FAILED') return true;
+  const message = String(error.message ?? '').toLowerCase();
+  if (message.includes('xcodebuild exited early')) return false;
+  return true;
+}
+
+async function buildRunnerEarlyExitError(params: {
+  session: RunnerSession;
+  port: number;
+  logPath?: string;
+}): Promise<AppError> {
+  const { session, port, logPath } = params;
+  const result = await session.testPromise;
+  const message = 'Runner did not accept connection (xcodebuild exited early)';
+  const reason = classifyBootFailure({
+    message,
+    stdout: result.stdout,
+    stderr: result.stderr,
+    context: { platform: 'ios', phase: 'connect' },
+  });
+  return new AppError('COMMAND_FAILED', message, {
+    port,
+    logPath,
+    xcodebuild: {
+      exitCode: result.exitCode,
+      stdout: result.stdout,
+      stderr: result.stderr,
+    },
+    reason,
+    hint: resolveRunnerEarlyExitHint(message, result.stdout, result.stderr),
+  });
+}
+
 async function waitForRunner(
   device: DeviceInfo,
   port: number,
   command: RunnerCommand,
   logPath?: string,
   timeoutMs: number = RUNNER_STARTUP_TIMEOUT_MS,
+  session?: RunnerSession,
 ): Promise<Response> {
   const deadline = Deadline.fromTimeoutMs(timeoutMs);
   let endpoints = await resolveRunnerCommandEndpoints(device, port, deadline.remainingMs());
@@ -651,6 +717,9 @@ async function waitForRunner(
             timeoutMs,
           });
         }
+        if (session && session.child.exitCode !== null && session.child.exitCode !== undefined) {
+          throw await buildRunnerEarlyExitError({ session, port, logPath });
+        }
         if (device.kind === 'device') {
           endpoints = await resolveRunnerCommandEndpoints(device, port, attemptDeadline?.remainingMs());
         }
@@ -688,7 +757,7 @@ async function waitForRunner(
         baseDelayMs: RUNNER_CONNECT_RETRY_BASE_DELAY_MS,
         maxDelayMs: RUNNER_CONNECT_RETRY_MAX_DELAY_MS,
         jitter: 0.2,
-        shouldRetry: () => true,
+        shouldRetry: shouldRetryRunnerConnectError,
       },
       { deadline, phase: 'ios_runner_connect' },
     );
diff --git a/src/platforms/ios/simulator.ts b/src/platforms/ios/simulator.ts
new file mode 100644
index 000000000..903099bdd
--- /dev/null
+++ b/src/platforms/ios/simulator.ts
@@ -0,0 +1,164 @@
+import type { DeviceInfo } from '../../utils/device.ts';
+import { AppError } from '../../utils/errors.ts';
+import { runCmd } from '../../utils/exec.ts';
+import { Deadline, retryWithPolicy, type RetryTelemetryEvent } from '../../utils/retry.ts';
+import { bootFailureHint, classifyBootFailure } from '../boot-diagnostics.ts';
+
+import { IOS_BOOT_TIMEOUT_MS, IOS_SIMCTL_LIST_TIMEOUT_MS, RETRY_LOGS_ENABLED } from './config.ts';
+
+export function ensureSimulator(device: DeviceInfo, command: string): void {
+  if (device.kind !== 'simulator') {
+    throw new AppError('UNSUPPORTED_OPERATION', `${command} is only supported on iOS simulators`);
+  }
+}
+
+export async function ensureBootedSimulator(device: DeviceInfo): Promise<void> {
+  if (device.kind !== 'simulator') return;
+
+  const state = await getSimulatorState(device.id);
+  if (state === 'Booted') return;
+
+  const deadline = Deadline.fromTimeoutMs(IOS_BOOT_TIMEOUT_MS);
+  let bootResult:
+    | {
+      stdout: string;
+      stderr: string;
+      exitCode: number;
+    }
+    | undefined;
+  let bootStatusResult:
+    | {
+      stdout: string;
+      stderr: string;
+      exitCode: number;
+    }
+    | undefined;
+
+  try {
+    await retryWithPolicy(
+      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);
+        const boot = await runCmd('xcrun', ['simctl', 'boot', device.id], {
+          allowFailure: true,
+          timeoutMs: remainingMs,
+        });
+        bootResult = {
+          stdout: String(boot.stdout ?? ''),
+          stderr: String(boot.stderr ?? ''),
+          exitCode: boot.exitCode,
+        };
+
+        const bootOutput = `${bootResult.stdout}\n${bootResult.stderr}`.toLowerCase();
+        const bootAlreadyDone =
+          bootOutput.includes('already booted') || bootOutput.includes('current state: booted');
+
+        if (bootResult.exitCode !== 0 && !bootAlreadyDone) {
+          throw new AppError('COMMAND_FAILED', 'simctl boot failed', {
+            stdout: bootResult.stdout,
+            stderr: bootResult.stderr,
+            exitCode: bootResult.exitCode,
+          });
+        }
+
+        const bootStatus = await runCmd('xcrun', ['simctl', 'bootstatus', device.id, '-b'], {
+          allowFailure: true,
+          timeoutMs: remainingMs,
+        });
+        bootStatusResult = {
+          stdout: String(bootStatus.stdout ?? ''),
+          stderr: String(bootStatus.stderr ?? ''),
+          exitCode: bootStatus.exitCode,
+        };
+
+        if (bootStatusResult.exitCode !== 0) {
+          throw new AppError('COMMAND_FAILED', 'simctl bootstatus failed', {
+            stdout: bootStatusResult.stdout,
+            stderr: bootStatusResult.stderr,
+            exitCode: bootStatusResult.exitCode,
+          });
+        }
+
+        const nextState = await getSimulatorState(device.id);
+        if (nextState !== 'Booted') {
+          throw new AppError('COMMAND_FAILED', 'Simulator is still booting', { state: nextState });
+        }
+      },
+      {
+        maxAttempts: 3,
+        baseDelayMs: 500,
+        maxDelayMs: 2000,
+        jitter: 0.2,
+        shouldRetry: (error) => {
+          const reason = classifyBootFailure({
+            error,
+            stdout: bootStatusResult?.stdout ?? bootResult?.stdout,
+            stderr: bootStatusResult?.stderr ?? bootResult?.stderr,
+            context: { platform: 'ios', phase: 'boot' },
+          });
+          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`);
+        },
+      },
+    );
+  } catch (error) {
+    const reason = classifyBootFailure({
+      error,
+      stdout: bootStatusResult?.stdout ?? bootResult?.stdout,
+      stderr: bootStatusResult?.stderr ?? bootResult?.stderr,
+      context: { platform: 'ios', phase: 'boot' },
+    });
+
+    throw new AppError('COMMAND_FAILED', 'iOS simulator failed to boot', {
+      platform: 'ios',
+      deviceId: device.id,
+      timeoutMs: IOS_BOOT_TIMEOUT_MS,
+      elapsedMs: deadline.elapsedMs(),
+      reason,
+      hint: bootFailureHint(reason),
+      boot: bootResult,
+      bootstatus: bootStatusResult,
+    });
+  }
+}
+
+export async function getSimulatorState(udid: string): Promise<string | null> {
+  const result = await runCmd('xcrun', ['simctl', 'list', 'devices', '-j'], {
+    allowFailure: true,
+    timeoutMs: IOS_SIMCTL_LIST_TIMEOUT_MS,
+  });
+  if (result.exitCode !== 0) return null;
+
+  try {
+    const payload = JSON.parse(String(result.stdout ?? '')) as {
+      devices: Record<string, { udid: string; state: string }[]>;
+    };
+
+    for (const runtime of Object.values(payload.devices ?? {})) {
+      const match = runtime.find((entry) => entry.udid === udid);
+      if (match) return match.state;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
diff --git a/src/utils/__tests__/args.test.ts b/src/utils/__tests__/args.test.ts
index bfa77abf1..cc48e95c9 100644
--- a/src/utils/__tests__/args.test.ts
+++ b/src/utils/__tests__/args.test.ts
@@ -1,6 +1,6 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { parseArgs, usage, usageForCommand } from '../args.ts';
+import { parseArgs, toDaemonFlags, usage, usageForCommand } from '../args.ts';
 import { AppError } from '../errors.ts';
 import { getCliCommandNames, getSchemaCapabilityKeys } from '../command-schema.ts';
 import { listCapabilityCommands } from '../../core/capabilities.ts';
@@ -12,6 +12,14 @@ test('parseArgs recognizes --relaunch', () => {
   assert.equal(parsed.flags.relaunch, true);
 });
 
+test('toDaemonFlags strips CLI-only flags', () => {
+  const parsed = parseArgs(['open', 'settings', '--json']);
+  const daemonFlags = toDaemonFlags(parsed.flags);
+  assert.equal(Object.hasOwn(daemonFlags, 'json'), false);
+  assert.equal(Object.hasOwn(daemonFlags, 'help'), false);
+  assert.equal(Object.hasOwn(daemonFlags, 'version'), false);
+});
+
 test('parseArgs accepts --save-script with optional path value', () => {
   const withoutPath = parseArgs(['open', 'settings', '--save-script']);
   assert.equal(withoutPath.command, 'open');
@@ -93,7 +101,17 @@ test('usage includes --relaunch flag', () => {
   assert.match(usage(), /--relaunch/);
   assert.match(usage(), /--save-script \[path\]/);
   assert.match(usage(), /pinch <scale> \[x\] \[y\]/);
-  assert.match(usage(), /--metadata/);
+  assert.doesNotMatch(usage(), /--metadata/);
+});
+
+test('apps defaults to --all filter and allows overrides', () => {
+  const defaultFilter = parseArgs(['apps'], { strictFlags: true });
+  assert.equal(defaultFilter.command, 'apps');
+  assert.equal(defaultFilter.flags.appsFilter, 'all');
+
+  const userInstalled = parseArgs(['apps', '--user-installed'], { strictFlags: true });
+  assert.equal(userInstalled.command, 'apps');
+  assert.equal(userInstalled.flags.appsFilter, 'user-installed');
 });
 
 test('every capability command has a parser schema entry', () => {
diff --git a/src/utils/__tests__/daemon-client.test.ts b/src/utils/__tests__/daemon-client.test.ts
index c5d2a6cdd..099a31c59 100644
--- a/src/utils/__tests__/daemon-client.test.ts
+++ b/src/utils/__tests__/daemon-client.test.ts
@@ -4,7 +4,7 @@ import { spawn } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { resolveDaemonRequestTimeoutMs } from '../../daemon-client.ts';
+import { resolveDaemonRequestTimeoutMs, resolveDaemonStartupHint } from '../../daemon-client.ts';
 import {
   isProcessAlive,
   readProcessCommand,
@@ -12,14 +12,31 @@ import {
   waitForProcessExit,
 } from '../process-identity.ts';
 
-test('resolveDaemonRequestTimeoutMs defaults to 180000', () => {
-  assert.equal(resolveDaemonRequestTimeoutMs(undefined), 180000);
+test('resolveDaemonRequestTimeoutMs defaults to 45000', () => {
+  assert.equal(resolveDaemonRequestTimeoutMs(undefined), 45000);
 });
 
 test('resolveDaemonRequestTimeoutMs enforces minimum timeout', () => {
   assert.equal(resolveDaemonRequestTimeoutMs('100'), 1000);
   assert.equal(resolveDaemonRequestTimeoutMs('2500'), 2500);
-  assert.equal(resolveDaemonRequestTimeoutMs('invalid'), 180000);
+  assert.equal(resolveDaemonRequestTimeoutMs('invalid'), 45000);
+});
+
+test('resolveDaemonStartupHint prefers stale lock guidance when lock exists without info', () => {
+  const hint = resolveDaemonStartupHint({ hasInfo: false, hasLock: true });
+  assert.match(hint, /daemon\.lock/i);
+  assert.match(hint, /delete/i);
+});
+
+test('resolveDaemonStartupHint covers stale info+lock pair', () => {
+  const hint = resolveDaemonStartupHint({ hasInfo: true, hasLock: true });
+  assert.match(hint, /daemon\.json/i);
+  assert.match(hint, /daemon\.lock/i);
+});
+
+test('resolveDaemonStartupHint falls back to daemon.json guidance', () => {
+  const hint = resolveDaemonStartupHint({ hasInfo: true, hasLock: false });
+  assert.match(hint, /daemon\.json/i);
 });
 
 test('stopDaemonProcessForTakeover terminates a matching daemon process', async (t) => {
diff --git a/src/utils/args.ts b/src/utils/args.ts
index a26709154..fc03b9e3a 100644
--- a/src/utils/args.ts
+++ b/src/utils/args.ts
@@ -221,7 +221,12 @@ function formatUnsupportedFlagMessage(command: string | null, unsupported: strin
 }
 
 export function toDaemonFlags(flags: CliFlags): Omit<CliFlags, 'json' | 'help' | 'version'> {
-  const { json: _json, help: _help, version: _version, ...daemonFlags } = flags;
+  const {
+    json: _json,
+    help: _help,
+    version: _version,
+    ...daemonFlags
+  } = flags;
   return daemonFlags;
 }
 
diff --git a/src/utils/command-schema.ts b/src/utils/command-schema.ts
index 8885072d3..973f8b3d2 100644
--- a/src/utils/command-schema.ts
+++ b/src/utils/command-schema.ts
@@ -13,8 +13,7 @@ export type CliFlags = {
   snapshotScope?: string;
   snapshotRaw?: boolean;
   snapshotBackend?: 'ax' | 'xctest';
-  appsFilter?: 'launchable' | 'user-installed' | 'all';
-  appsMetadata?: boolean;
+  appsFilter?: 'user-installed' | 'all';
   count?: number;
   intervalMs?: number;
   holdMs?: number;
@@ -232,7 +231,7 @@ export const FLAG_DEFINITIONS: readonly FlagDefinition[] = [
     type: 'enum',
     setValue: 'user-installed',
     usageLabel: '--user-installed',
-    usageDescription: 'Apps: list user-installed packages (Android only)',
+    usageDescription: 'Apps: list user-installed apps',
   },
   {
     key: 'appsFilter',
@@ -240,14 +239,7 @@ export const FLAG_DEFINITIONS: readonly FlagDefinition[] = [
     type: 'enum',
     setValue: 'all',
     usageLabel: '--all',
-    usageDescription: 'Apps: list all packages (Android only)',
-  },
-  {
-    key: 'appsMetadata',
-    names: ['--metadata'],
-    type: 'boolean',
-    usageLabel: '--metadata',
-    usageDescription: 'Apps: return metadata objects',
+    usageDescription: 'Apps: list all apps (include system/default apps)',
   },
   {
     key: 'snapshotInteractiveOnly',
@@ -348,9 +340,10 @@ export const COMMAND_SCHEMAS: Record<string, CommandSchema> = {
     skipCapabilityCheck: true,
   },
   apps: {
-    description: 'List installed apps (Android launchable by default, iOS simulator)',
+    description: 'List installed apps (includes default/system apps by default)',
     positionalArgs: [],
-    allowedFlags: ['appsFilter', 'appsMetadata'],
+    allowedFlags: ['appsFilter'],
+    defaults: { appsFilter: 'all' },
   },
   appstate: {
     description: 'Show foreground app/activity',
diff --git a/test/integration/ios.test.ts b/test/integration/ios.test.ts
index b03e0e1cd..c23dfc051 100644
--- a/test/integration/ios.test.ts
+++ b/test/integration/ios.test.ts
@@ -37,6 +37,16 @@ test('ios settings commands', { skip: shouldSkipIos() }, async () => {
     detail: 'expected snapshot to include a nodes array',
   });
 
+  const appStateArgs = ['appstate', '--json', ...session];
+  const appState = integration.runStep('appstate', appStateArgs);
+  integration.assertResult(
+    appState.json?.data?.source === 'session',
+    'appstate source is session',
+    appStateArgs,
+    appState,
+    { detail: `expected appstate source=session, received ${JSON.stringify(appState.json?.data?.source)}` },
+  );
+
   const openGeneralArgs = ['click', 'role=cell', 'label=General', '--json', ...session];
   const openGeneral = integration.runStep('open general', openGeneralArgs);
   integration.assertResult(
diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md
index 4c5297e63..ca7ba3b55 100644
--- a/website/docs/docs/commands.md
+++ b/website/docs/docs/commands.md
@@ -108,6 +108,21 @@ agent-device settings location off
 - iOS `settings` support is simulator-only.
 - Android `settings` support works on emulators and devices.
 
+## App state and app lists
+
+```bash
+agent-device appstate
+agent-device apps --platform ios
+agent-device apps --platform ios --all
+agent-device apps --platform android
+agent-device apps --platform android --all
+```
+
+- Android `appstate` reports live foreground package/activity.
+- iOS `appstate` is session-scoped and reports the app tracked by the active session on the target device.
+- iOS `apps` supports simulators and physical devices.
+- `apps` includes default/system apps by default (use `--user-installed` to filter).
+
 ## Media and logs
 
 ```bash
@@ -129,4 +144,6 @@ agent-device record stop                # Stop active recording
   - `AGENT_DEVICE_IOS_SIGNING_IDENTITY` (optional)
   - `AGENT_DEVICE_IOS_PROVISIONING_PROFILE`
 - If first-run XCTest setup/build is slow, increase daemon request timeout:
-  - `AGENT_DEVICE_DAEMON_TIMEOUT_MS=180000` (or higher)
+  - `AGENT_DEVICE_DAEMON_TIMEOUT_MS=120000` (default is `45000`)
+- For daemon startup troubleshooting:
+  - follow stale metadata hints for `~/.agent-device/daemon.json` and `~/.agent-device/daemon.lock`
diff --git a/website/docs/docs/installation.md b/website/docs/docs/installation.md
index 94889982d..c6b859c19 100644
--- a/website/docs/docs/installation.md
+++ b/website/docs/docs/installation.md
@@ -30,5 +30,8 @@ npx agent-device open Settings --platform ios
 - `AGENT_DEVICE_IOS_TEAM_ID`
 - `AGENT_DEVICE_IOS_SIGNING_IDENTITY`
 - `AGENT_DEVICE_IOS_PROVISIONING_PROFILE`
-- If first-run device setup is slow, increase daemon timeout:
-  - `AGENT_DEVICE_DAEMON_TIMEOUT_MS=180000` (or higher)
+- If device setup is slow, increase daemon timeout:
+  - `AGENT_DEVICE_DAEMON_TIMEOUT_MS=120000` (default is `45000`)
+- If daemon startup reports stale metadata, remove stale files and retry:
+  - `~/.agent-device/daemon.json`
+  - `~/.agent-device/daemon.lock`
diff --git a/website/docs/docs/introduction.md b/website/docs/docs/introduction.md
index 119e40f1b..215518c3f 100644
--- a/website/docs/docs/introduction.md
+++ b/website/docs/docs/introduction.md
@@ -20,8 +20,9 @@ If you know `agent-browser`, this is the mobile-native counterpart for iOS/Andro
 
 ## Platform support highlights
 
-- iOS simulator + iOS device core runner commands: `snapshot`, `wait`, `click`, `fill`, `get`, `is`, `find`, `press`, `long-press`, `focus`, `type`, `scroll`, `scrollintoview`, `back`, `home`, `app-switcher`, `open` (app), `close`, `screenshot`, `appstate`.
-- iOS simulator-only: `alert`, `pinch`, `record`, `reinstall`, `apps`, `settings`, and deep-link open (`open <url>`).
+- iOS simulator + iOS device core runner commands: `snapshot`, `wait`, `click`, `fill`, `get`, `is`, `find`, `press`, `long-press`, `focus`, `type`, `scroll`, `scrollintoview`, `back`, `home`, `app-switcher`, `open` (app), `close`, `screenshot`, `apps`, `appstate`.
+- iOS `appstate` is session-scoped on the selected target device.
+- iOS simulator-only: `alert`, `pinch`, `record`, `reinstall`, `settings`, and deep-link open (`open <url>`).
 - Android emulator + Android device support remains unchanged.
 
 ## Architecture (high level)
diff --git a/website/docs/docs/sessions.md b/website/docs/docs/sessions.md
index 16898de98..b65c9b8c9 100644
--- a/website/docs/docs/sessions.md
+++ b/website/docs/docs/sessions.md
@@ -25,6 +25,7 @@ Notes:
 
 - `open <app>` within an existing session switches the active app and updates the session bundle id.
 - `open <url>` in iOS sessions is simulator-only.
+- On iOS, `appstate` is session-scoped and requires a matching active session on the target device.
 - Use `--session <name>` to run multiple sessions in parallel.
 
 For replay scripts and deterministic E2E guidance, see [Replay & E2E (Experimental)](/docs/replay-e2e).

From bf19dc0a746a0d24fdf43a6268b30bf18dff86d8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Mon, 16 Feb 2026 17:44:32 +0100
Subject: [PATCH 2/4] fix: wait for android app launch completion

---
 src/platforms/android/index.ts | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/src/platforms/android/index.ts b/src/platforms/android/index.ts
index 4e660518b..b44dc284f 100644
--- a/src/platforms/android/index.ts
+++ b/src/platforms/android/index.ts
@@ -206,7 +206,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) {
@@ -219,6 +219,7 @@ export async function openAndroidApp(
         'shell',
         'am',
         'start',
+        '-W',
         '-a',
         'android.intent.action.MAIN',
         '-c',
@@ -238,6 +239,7 @@ export async function openAndroidApp(
         'shell',
         'am',
         'start',
+        '-W',
         '-a',
         'android.intent.action.MAIN',
         '-c',
@@ -258,6 +260,7 @@ export async function openAndroidApp(
         'shell',
         'am',
         'start',
+        '-W',
         '-a',
         'android.intent.action.MAIN',
         '-c',

From 8caa037027164181d739350a558859793a41f132 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Mon, 16 Feb 2026 17:50:34 +0100
Subject: [PATCH 3/4] fix: address review findings for iOS appstate and daemon
 flows

---
 README.md                                     |  2 +-
 src/__tests__/cli-close.test.ts               | 18 +++-
 src/cli.ts                                    |  1 +
 src/daemon-client.ts                          |  9 +-
 src/daemon/device-ready.ts                    | 32 +++----
 src/daemon/handlers/session.ts                |  2 +-
 src/platforms/android/__tests__/index.test.ts |  3 +
 src/platforms/ios/__tests__/index.test.ts     | 96 ++++++++++++++++++-
 src/platforms/ios/apps.ts                     | 25 +++--
 src/platforms/ios/config.ts                   |  8 +-
 src/platforms/ios/devicectl.ts                |  2 +-
 src/platforms/ios/devices.ts                  | 10 +-
 src/platforms/ios/runner-client.ts            | 15 +--
 src/utils/__tests__/daemon-client.test.ts     |  6 +-
 src/utils/timeouts.ts                         | 13 +++
 website/docs/docs/commands.md                 |  2 +-
 website/docs/docs/installation.md             |  2 +-
 17 files changed, 181 insertions(+), 65 deletions(-)
 create mode 100644 src/utils/timeouts.ts

diff --git a/README.md b/README.md
index 0c4b0b027..84f703fc1 100644
--- a/README.md
+++ b/README.md
@@ -275,7 +275,7 @@ Environment selectors:
 - `ANDROID_DEVICE=Pixel_9_Pro_XL` or `ANDROID_SERIAL=emulator-5554`
 - `IOS_DEVICE="iPhone 17 Pro"` or `IOS_UDID=<udid>`
 - `AGENT_DEVICE_IOS_BOOT_TIMEOUT_MS=<ms>` to adjust iOS simulator boot timeout (default: `120000`, minimum: `5000`).
-- `AGENT_DEVICE_DAEMON_TIMEOUT_MS=<ms>` to override daemon request timeout (default `45000`). Increase for slow physical-device setup (for example `120000`).
+- `AGENT_DEVICE_DAEMON_TIMEOUT_MS=<ms>` to override daemon request timeout (default `90000`). Increase for slow physical-device setup (for example `120000`).
 - `AGENT_DEVICE_IOS_TEAM_ID=<team-id>` optional Team ID override for iOS device runner signing.
 - `AGENT_DEVICE_IOS_SIGNING_IDENTITY=<identity>` optional signing identity override.
 - `AGENT_DEVICE_IOS_PROVISIONING_PROFILE=<profile>` optional provisioning profile specifier for iOS device runner signing.
diff --git a/src/__tests__/cli-close.test.ts b/src/__tests__/cli-close.test.ts
index 1d9117e53..8660e73e9 100644
--- a/src/__tests__/cli-close.test.ts
+++ b/src/__tests__/cli-close.test.ts
@@ -67,6 +67,7 @@ async function runCliCapture(argv: string[]): Promise<RunResult> {
 async function runCliCaptureWithErrorDetails(
   argv: string[],
   details: Record<string, unknown>,
+  message = 'Failed to start daemon',
 ): Promise<RunResult> {
   let daemonCalls = 0;
   let stdout = '';
@@ -91,7 +92,7 @@ async function runCliCaptureWithErrorDetails(
 
   const sendToDaemon = async (): Promise<DaemonResponse> => {
     daemonCalls += 1;
-    throw new AppError('COMMAND_FAILED', 'Failed to start daemon', details);
+    throw new AppError('COMMAND_FAILED', message, details);
   };
 
   try {
@@ -137,3 +138,18 @@ test('close treats lock-only daemon startup failure as no-op', async () => {
   assert.equal(result.stdout, '');
   assert.equal(result.stderr, '');
 });
+
+test('close treats structured daemon startup failure as no-op without relying on message text', async () => {
+  const result = await runCliCaptureWithErrorDetails(
+    ['close'],
+    {
+      kind: 'daemon_startup_failed',
+      lockPath: '/tmp/daemon.lock',
+    },
+    'daemon bootstrap failed',
+  );
+  assert.equal(result.code, null);
+  assert.equal(result.daemonCalls, 1);
+  assert.equal(result.stdout, '');
+  assert.equal(result.stderr, '');
+});
diff --git a/src/cli.ts b/src/cli.ts
index acd6bbdaf..05777a51c 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -254,6 +254,7 @@ export async function runCli(argv: string[], deps: CliDeps = DEFAULT_CLI_DEPS):
 
 function isDaemonStartupFailure(error: AppError): boolean {
   if (error.code !== 'COMMAND_FAILED') return false;
+  if (error.details?.kind === 'daemon_startup_failed') return true;
   if (!error.message.toLowerCase().includes('failed to start daemon')) return false;
   return typeof error.details?.infoPath === 'string' || typeof error.details?.lockPath === 'string';
 }
diff --git a/src/daemon-client.ts b/src/daemon-client.ts
index 8f236b5fe..4341b40d4 100644
--- a/src/daemon-client.ts
+++ b/src/daemon-client.ts
@@ -78,6 +78,7 @@ async function ensureDaemon(): Promise<DaemonInfo> {
   }
 
   throw new AppError('COMMAND_FAILED', 'Failed to start daemon', {
+    kind: 'daemon_startup_failed',
     infoPath,
     lockPath,
     hint: resolveDaemonStartupHint(getDaemonMetadataState()),
@@ -102,6 +103,10 @@ async function recoverDaemonLockHolder(): Promise<boolean> {
     removeDaemonLock();
     return true;
   }
+  if (!isAgentDeviceDaemonProcess(lockInfo.pid, lockInfo.processStartTime)) {
+    removeDaemonLock();
+    return true;
+  }
   await stopProcessForTakeover(lockInfo.pid, {
     termTimeoutMs: DAEMON_TAKEOVER_TERM_TIMEOUT_MS,
     killTimeoutMs: DAEMON_TAKEOVER_KILL_TIMEOUT_MS,
@@ -250,9 +255,9 @@ async function sendRequest(info: DaemonInfo, req: DaemonRequest): Promise<Daemon
 }
 
 export function resolveDaemonRequestTimeoutMs(raw: string | undefined = process.env.AGENT_DEVICE_DAEMON_TIMEOUT_MS): number {
-  if (!raw) return 45000;
+  if (!raw) return 90000;
   const parsed = Number(raw);
-  if (!Number.isFinite(parsed)) return 45000;
+  if (!Number.isFinite(parsed)) return 90000;
   return Math.max(1000, Math.floor(parsed));
 }
 
diff --git a/src/daemon/device-ready.ts b/src/daemon/device-ready.ts
index 1b218dad5..abc393a0f 100644
--- a/src/daemon/device-ready.ts
+++ b/src/daemon/device-ready.ts
@@ -4,12 +4,15 @@ import path from 'node:path';
 import { promises as fs } from 'node:fs';
 import { runCmd } from '../utils/exec.ts';
 import { AppError } from '../utils/errors.ts';
+import { resolveTimeoutMs } from '../utils/timeouts.ts';
+import { resolveIosDevicectlHint } from '../platforms/ios/devicectl.ts';
 
 const IOS_DEVICE_READY_TIMEOUT_MS = resolveTimeoutMs(
   process.env.AGENT_DEVICE_IOS_DEVICE_READY_TIMEOUT_MS,
   15_000,
   1_000,
 );
+const IOS_DEVICE_READY_COMMAND_TIMEOUT_BUFFER_MS = 3_000;
 
 export async function ensureDeviceReady(device: DeviceInfo): Promise<void> {
   if (device.platform === 'ios') {
@@ -29,15 +32,11 @@ export async function ensureDeviceReady(device: DeviceInfo): Promise<void> {
   }
 }
 
-function resolveTimeoutMs(raw: string | undefined, fallback: number, min: number): number {
-  if (!raw) return fallback;
-  const parsed = Number(raw);
-  if (!Number.isFinite(parsed)) return fallback;
-  return Math.max(min, Math.floor(parsed));
-}
-
 async function ensureIosDeviceReady(deviceId: string): Promise<void> {
-  const jsonPath = path.join(os.tmpdir(), `agent-device-ready-${process.pid}-${Date.now()}.json`);
+  const jsonPath = path.join(
+    os.tmpdir(),
+    `agent-device-ready-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}.json`,
+  );
   const timeoutSeconds = Math.max(1, Math.ceil(IOS_DEVICE_READY_TIMEOUT_MS / 1000));
   try {
     const result = await runCmd(
@@ -54,7 +53,10 @@ async function ensureIosDeviceReady(deviceId: string): Promise<void> {
         '--timeout',
         String(timeoutSeconds),
       ],
-      { allowFailure: true, timeoutMs: IOS_DEVICE_READY_TIMEOUT_MS },
+      {
+        allowFailure: true,
+        timeoutMs: IOS_DEVICE_READY_TIMEOUT_MS + IOS_DEVICE_READY_COMMAND_TIMEOUT_BUFFER_MS,
+      },
     );
     const stdout = String(result.stdout ?? '');
     const stderr = String(result.stderr ?? '');
@@ -143,15 +145,13 @@ async function readIosReadyPayload(jsonPath: string): Promise<{ parsed: boolean;
 }
 
 export function resolveIosReadyHint(stdout: string, stderr: string): string {
-  const text = `${stdout}\n${stderr}`.toLowerCase();
-  if (text.includes('device is busy') && text.includes('connecting')) {
-    return 'Device is still connecting. Keep it unlocked and connected by cable until connection settles, then retry.';
-  }
-  if (text.includes('coredeviceservice') && text.includes('timed out')) {
-    return 'CoreDevice service did not initialize in time. Reconnect device and retry; if it persists restart Xcode and the iOS device.';
+  const devicectlHint = resolveIosDevicectlHint(stdout, stderr);
+  if (devicectlHint !== 'Ensure the iOS device is unlocked, trusted, and available in Xcode > Devices, then retry.') {
+    return devicectlHint;
   }
+  const text = `${stdout}\n${stderr}`.toLowerCase();
   if (text.includes('timed out waiting for all destinations')) {
     return 'Xcode destination did not become available in time. Keep device unlocked and retry.';
   }
-  return 'Ensure the iOS device is unlocked, trusted, and visible in Xcode > Devices, then retry.';
+  return devicectlHint;
 }
diff --git a/src/daemon/handlers/session.ts b/src/daemon/handlers/session.ts
index 44a1cabd0..b3b8b6adf 100644
--- a/src/daemon/handlers/session.ts
+++ b/src/daemon/handlers/session.ts
@@ -148,7 +148,7 @@ async function handleAppStateCommand(params: {
   }
   if (shouldUseSessionStateForIos) {
     const appName = session.appName ?? session.appBundleId;
-    if (!appName && !session.appBundleId) {
+    if (!session.appName && !session.appBundleId) {
       return {
         ok: false,
         error: {
diff --git a/src/platforms/android/__tests__/index.test.ts b/src/platforms/android/__tests__/index.test.ts
index 1de17c866..cf8959f79 100644
--- a/src/platforms/android/__tests__/index.test.ts
+++ b/src/platforms/android/__tests__/index.test.ts
@@ -99,6 +99,9 @@ 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 () => {
diff --git a/src/platforms/ios/__tests__/index.test.ts b/src/platforms/ios/__tests__/index.test.ts
index 970699e3c..f21c16ff1 100644
--- a/src/platforms/ios/__tests__/index.test.ts
+++ b/src/platforms/ios/__tests__/index.test.ts
@@ -1,6 +1,9 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { openIosApp, parseIosDeviceAppsPayload } 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';
 
@@ -60,3 +63,94 @@ test('parseIosDeviceAppsPayload ignores malformed entries', () => {
   });
   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 });
+  }
+});
diff --git a/src/platforms/ios/apps.ts b/src/platforms/ios/apps.ts
index 4a7a2b6fe..78c65de4f 100644
--- a/src/platforms/ios/apps.ts
+++ b/src/platforms/ios/apps.ts
@@ -19,13 +19,14 @@ export async function resolveIosApp(device: DeviceInfo, app: string): Promise<st
   const alias = ALIASES[trimmed.toLowerCase()];
   if (alias) return alias;
 
-  if (device.kind === 'simulator') {
-    const list = await listSimulatorApps(device);
-    const matches = list.filter((entry) => entry.name.toLowerCase() === trimmed.toLowerCase());
-    if (matches.length === 1) return matches[0].bundleId;
-    if (matches.length > 1) {
-      throw new AppError('INVALID_ARGS', `Multiple apps matched "${app}"`, { matches });
-    }
+  const list =
+    device.kind === 'simulator'
+      ? await listSimulatorApps(device)
+      : await listIosDeviceApps(device, 'all');
+  const matches = list.filter((entry) => entry.name.toLowerCase() === trimmed.toLowerCase());
+  if (matches.length === 1) return matches[0].bundleId;
+  if (matches.length > 1) {
+    throw new AppError('INVALID_ARGS', `Multiple apps matched "${app}"`, { matches });
   }
 
   throw new AppError('APP_NOT_INSTALLED', `No app found matching "${app}"`);
@@ -206,7 +207,8 @@ export async function listIosApps(
   filter: 'user-installed' | 'all' = 'all',
 ): Promise<IosAppInfo[]> {
   if (device.kind === 'simulator') {
-    return await listSimulatorApps(device);
+    const apps = await listSimulatorApps(device);
+    return filterIosAppsByBundlePrefix(apps, filter);
   }
   return await listIosDeviceApps(device, filter);
 }
@@ -307,3 +309,10 @@ async function launchIosSimulatorApp(device: DeviceInfo, bundleId: string): Prom
     { deadline: launchDeadline },
   );
 }
+
+function filterIosAppsByBundlePrefix(apps: IosAppInfo[], filter: 'user-installed' | 'all'): IosAppInfo[] {
+  if (filter === 'user-installed') {
+    return apps.filter((app) => !app.bundleId.startsWith('com.apple.'));
+  }
+  return apps;
+}
diff --git a/src/platforms/ios/config.ts b/src/platforms/ios/config.ts
index 2b29cd80b..7c888bb46 100644
--- a/src/platforms/ios/config.ts
+++ b/src/platforms/ios/config.ts
@@ -1,4 +1,5 @@
 import { isEnvTruthy, TIMEOUT_PROFILES } from '../../utils/retry.ts';
+import { resolveTimeoutMs } from '../../utils/timeouts.ts';
 
 export const IOS_BOOT_TIMEOUT_MS = resolveTimeoutMs(
   process.env.AGENT_DEVICE_IOS_BOOT_TIMEOUT_MS,
@@ -25,10 +26,3 @@ export const IOS_DEVICECTL_TIMEOUT_MS = resolveTimeoutMs(
 );
 
 export const RETRY_LOGS_ENABLED = isEnvTruthy(process.env.AGENT_DEVICE_RETRY_LOGS);
-
-function resolveTimeoutMs(raw: string | undefined, fallback: number, min: number): number {
-  if (!raw) return fallback;
-  const parsed = Number(raw);
-  if (!Number.isFinite(parsed)) return fallback;
-  return Math.max(min, Math.floor(parsed));
-}
diff --git a/src/platforms/ios/devicectl.ts b/src/platforms/ios/devicectl.ts
index b9864899b..15964e910 100644
--- a/src/platforms/ios/devicectl.ts
+++ b/src/platforms/ios/devicectl.ts
@@ -119,7 +119,7 @@ function filterIosDeviceApps(apps: IosAppInfo[], filter: 'user-installed' | 'all
   return apps;
 }
 
-function resolveIosDevicectlHint(stdout: string, stderr: string): string {
+export function resolveIosDevicectlHint(stdout: string, stderr: string): string {
   const text = `${stdout}\n${stderr}`.toLowerCase();
   if (text.includes('device is busy') && text.includes('connecting')) {
     return 'iOS device is still connecting. Keep it unlocked and connected by cable until it is fully available in Xcode Devices, then retry.';
diff --git a/src/platforms/ios/devices.ts b/src/platforms/ios/devices.ts
index 0aa1b4f4a..6000af819 100644
--- a/src/platforms/ios/devices.ts
+++ b/src/platforms/ios/devices.ts
@@ -4,6 +4,7 @@ import path from 'node:path';
 import { runCmd, whichCmd } from '../../utils/exec.ts';
 import { AppError } from '../../utils/errors.ts';
 import type { DeviceInfo } from '../../utils/device.ts';
+import { resolveTimeoutMs } from '../../utils/timeouts.ts';
 
 const IOS_DEVICECTL_LIST_TIMEOUT_MS = resolveTimeoutMs(
   process.env.AGENT_DEVICE_IOS_DEVICECTL_LIST_TIMEOUT_MS,
@@ -51,7 +52,7 @@ export async function listIosDevices(): Promise<DeviceInfo[]> {
   try {
     jsonPath = path.join(
       os.tmpdir(),
-      `agent-device-devicectl-${process.pid}-${Date.now()}.json`,
+      `agent-device-devicectl-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}.json`,
     );
     const devicectlResult = await runCmd('xcrun', ['devicectl', 'list', 'devices', '--json-output', jsonPath], {
       allowFailure: true,
@@ -97,10 +98,3 @@ export async function listIosDevices(): Promise<DeviceInfo[]> {
 
   return devices;
 }
-
-function resolveTimeoutMs(raw: string | undefined, fallback: number, min: number): number {
-  if (!raw) return fallback;
-  const parsed = Number(raw);
-  if (!Number.isFinite(parsed)) return fallback;
-  return Math.max(min, Math.floor(parsed));
-}
diff --git a/src/platforms/ios/runner-client.ts b/src/platforms/ios/runner-client.ts
index fe68248df..2261f5eae 100644
--- a/src/platforms/ios/runner-client.ts
+++ b/src/platforms/ios/runner-client.ts
@@ -10,6 +10,7 @@ import { withKeyedLock } from '../../utils/keyed-lock.ts';
 import { isProcessAlive } from '../../utils/process-identity.ts';
 import net from 'node:net';
 import { bootFailureHint, classifyBootFailure } from '../boot-diagnostics.ts';
+import { resolveTimeoutMs, resolveTimeoutSeconds } from '../../utils/timeouts.ts';
 
 export type RunnerCommand = {
   command:
@@ -102,20 +103,6 @@ const RUNNER_STOP_WAIT_TIMEOUT_MS = 10_000;
 const RUNNER_SHUTDOWN_TIMEOUT_MS = 15_000;
 const RUNNER_DERIVED_ROOT = path.join(os.homedir(), '.agent-device', 'ios-runner');
 
-function resolveTimeoutMs(raw: string | undefined, fallback: number, min: number): number {
-  if (!raw) return fallback;
-  const parsed = Number(raw);
-  if (!Number.isFinite(parsed)) return fallback;
-  return Math.max(min, Math.floor(parsed));
-}
-
-function resolveTimeoutSeconds(raw: string | undefined, fallback: number, min: number): number {
-  if (!raw) return fallback;
-  const parsed = Number(raw);
-  if (!Number.isFinite(parsed)) return fallback;
-  return Math.max(min, Math.floor(parsed));
-}
-
 export type RunnerSnapshotNode = {
   index: number;
   type?: string;
diff --git a/src/utils/__tests__/daemon-client.test.ts b/src/utils/__tests__/daemon-client.test.ts
index 099a31c59..e820d44f1 100644
--- a/src/utils/__tests__/daemon-client.test.ts
+++ b/src/utils/__tests__/daemon-client.test.ts
@@ -12,14 +12,14 @@ import {
   waitForProcessExit,
 } from '../process-identity.ts';
 
-test('resolveDaemonRequestTimeoutMs defaults to 45000', () => {
-  assert.equal(resolveDaemonRequestTimeoutMs(undefined), 45000);
+test('resolveDaemonRequestTimeoutMs defaults to 90000', () => {
+  assert.equal(resolveDaemonRequestTimeoutMs(undefined), 90000);
 });
 
 test('resolveDaemonRequestTimeoutMs enforces minimum timeout', () => {
   assert.equal(resolveDaemonRequestTimeoutMs('100'), 1000);
   assert.equal(resolveDaemonRequestTimeoutMs('2500'), 2500);
-  assert.equal(resolveDaemonRequestTimeoutMs('invalid'), 45000);
+  assert.equal(resolveDaemonRequestTimeoutMs('invalid'), 90000);
 });
 
 test('resolveDaemonStartupHint prefers stale lock guidance when lock exists without info', () => {
diff --git a/src/utils/timeouts.ts b/src/utils/timeouts.ts
new file mode 100644
index 000000000..877308f71
--- /dev/null
+++ b/src/utils/timeouts.ts
@@ -0,0 +1,13 @@
+export function resolveTimeoutMs(raw: string | undefined, fallback: number, min: number): number {
+  if (!raw) return fallback;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.max(min, Math.floor(parsed));
+}
+
+export function resolveTimeoutSeconds(raw: string | undefined, fallback: number, min: number): number {
+  if (!raw) return fallback;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.max(min, Math.floor(parsed));
+}
diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md
index ca7ba3b55..f26076553 100644
--- a/website/docs/docs/commands.md
+++ b/website/docs/docs/commands.md
@@ -144,6 +144,6 @@ agent-device record stop                # Stop active recording
   - `AGENT_DEVICE_IOS_SIGNING_IDENTITY` (optional)
   - `AGENT_DEVICE_IOS_PROVISIONING_PROFILE`
 - If first-run XCTest setup/build is slow, increase daemon request timeout:
-  - `AGENT_DEVICE_DAEMON_TIMEOUT_MS=120000` (default is `45000`)
+  - `AGENT_DEVICE_DAEMON_TIMEOUT_MS=120000` (default is `90000`)
 - For daemon startup troubleshooting:
   - follow stale metadata hints for `~/.agent-device/daemon.json` and `~/.agent-device/daemon.lock`
diff --git a/website/docs/docs/installation.md b/website/docs/docs/installation.md
index c6b859c19..589907284 100644
--- a/website/docs/docs/installation.md
+++ b/website/docs/docs/installation.md
@@ -31,7 +31,7 @@ npx agent-device open Settings --platform ios
 - `AGENT_DEVICE_IOS_SIGNING_IDENTITY`
 - `AGENT_DEVICE_IOS_PROVISIONING_PROFILE`
 - If device setup is slow, increase daemon timeout:
-  - `AGENT_DEVICE_DAEMON_TIMEOUT_MS=120000` (default is `45000`)
+  - `AGENT_DEVICE_DAEMON_TIMEOUT_MS=120000` (default is `90000`)
 - If daemon startup reports stale metadata, remove stale files and retry:
   - `~/.agent-device/daemon.json`
   - `~/.agent-device/daemon.lock`

From 453cc390c56fcee6cc38f4fb57aac14b11009c1f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Mon, 16 Feb 2026 18:10:50 +0100
Subject: [PATCH 4/4] fixups

---
 src/daemon/device-ready.ts     |  8 +++-----
 src/platforms/android/index.ts |  1 +
 src/platforms/ios/devicectl.ts | 11 +++++++----
 src/utils/timeouts.ts          |  8 ++------
 4 files changed, 13 insertions(+), 15 deletions(-)

diff --git a/src/daemon/device-ready.ts b/src/daemon/device-ready.ts
index abc393a0f..1ef91c105 100644
--- a/src/daemon/device-ready.ts
+++ b/src/daemon/device-ready.ts
@@ -5,7 +5,7 @@ import { promises as fs } from 'node:fs';
 import { runCmd } from '../utils/exec.ts';
 import { AppError } from '../utils/errors.ts';
 import { resolveTimeoutMs } from '../utils/timeouts.ts';
-import { resolveIosDevicectlHint } from '../platforms/ios/devicectl.ts';
+import { resolveIosDevicectlHint, IOS_DEVICECTL_DEFAULT_HINT } from '../platforms/ios/devicectl.ts';
 
 const IOS_DEVICE_READY_TIMEOUT_MS = resolveTimeoutMs(
   process.env.AGENT_DEVICE_IOS_DEVICE_READY_TIMEOUT_MS,
@@ -146,12 +146,10 @@ async function readIosReadyPayload(jsonPath: string): Promise<{ parsed: boolean;
 
 export function resolveIosReadyHint(stdout: string, stderr: string): string {
   const devicectlHint = resolveIosDevicectlHint(stdout, stderr);
-  if (devicectlHint !== 'Ensure the iOS device is unlocked, trusted, and available in Xcode > Devices, then retry.') {
-    return devicectlHint;
-  }
+  if (devicectlHint) return devicectlHint;
   const text = `${stdout}\n${stderr}`.toLowerCase();
   if (text.includes('timed out waiting for all destinations')) {
     return 'Xcode destination did not become available in time. Keep device unlocked and retry.';
   }
-  return devicectlHint;
+  return IOS_DEVICECTL_DEFAULT_HINT;
 }
diff --git a/src/platforms/android/index.ts b/src/platforms/android/index.ts
index b44dc284f..325c309db 100644
--- a/src/platforms/android/index.ts
+++ b/src/platforms/android/index.ts
@@ -115,6 +115,7 @@ export function inferAndroidAppName(packageName: string): string {
     .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];
diff --git a/src/platforms/ios/devicectl.ts b/src/platforms/ios/devicectl.ts
index 15964e910..44f97f937 100644
--- a/src/platforms/ios/devicectl.ts
+++ b/src/platforms/ios/devicectl.ts
@@ -41,7 +41,7 @@ export async function runIosDevicectl(
     stdout,
     stderr,
     deviceId: context.deviceId,
-    hint: resolveIosDevicectlHint(stdout, stderr),
+    hint: resolveIosDevicectlHint(stdout, stderr) ?? IOS_DEVICECTL_DEFAULT_HINT,
   });
 }
 
@@ -80,7 +80,7 @@ export async function listIosDeviceApps(
         stdout,
         stderr,
         deviceId: device.id,
-        hint: resolveIosDevicectlHint(stdout, stderr),
+        hint: resolveIosDevicectlHint(stdout, stderr) ?? IOS_DEVICECTL_DEFAULT_HINT,
       });
     }
     const jsonText = await fs.readFile(jsonPath, 'utf8');
@@ -119,7 +119,10 @@ function filterIosDeviceApps(apps: IosAppInfo[], filter: 'user-installed' | 'all
   return apps;
 }
 
-export function resolveIosDevicectlHint(stdout: string, stderr: string): string {
+export const IOS_DEVICECTL_DEFAULT_HINT =
+  'Ensure the iOS device is unlocked, trusted, and available in Xcode > Devices, then retry.';
+
+export function resolveIosDevicectlHint(stdout: string, stderr: string): string | null {
   const text = `${stdout}\n${stderr}`.toLowerCase();
   if (text.includes('device is busy') && text.includes('connecting')) {
     return 'iOS device is still connecting. Keep it unlocked and connected by cable until it is fully available in Xcode Devices, then retry.';
@@ -127,5 +130,5 @@ export function resolveIosDevicectlHint(stdout: string, stderr: string): string
   if (text.includes('coredeviceservice') && text.includes('timed out')) {
     return 'CoreDevice service timed out. Reconnect the device and retry; if it persists restart Xcode and the iOS device.';
   }
-  return 'Ensure the iOS device is unlocked, trusted, and available in Xcode > Devices, then retry.';
+  return null;
 }
diff --git a/src/utils/timeouts.ts b/src/utils/timeouts.ts
index 877308f71..22bad7d0a 100644
--- a/src/utils/timeouts.ts
+++ b/src/utils/timeouts.ts
@@ -5,9 +5,5 @@ export function resolveTimeoutMs(raw: string | undefined, fallback: number, min:
   return Math.max(min, Math.floor(parsed));
 }
 
-export function resolveTimeoutSeconds(raw: string | undefined, fallback: number, min: number): number {
-  if (!raw) return fallback;
-  const parsed = Number(raw);
-  if (!Number.isFinite(parsed)) return fallback;
-  return Math.max(min, Math.floor(parsed));
-}
+/** Alias for `resolveTimeoutMs` — semantically marks the caller expects seconds. */
+export const resolveTimeoutSeconds = resolveTimeoutMs;