From 5a5ebcb7186d6535125868e555fc41c787e82ac9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Fri, 13 Feb 2026 21:10:56 +0100
Subject: [PATCH 01/13] Add iOS device runner support and document platform
 matrix

---
 README.md                                     |  26 ++-
 skills/agent-device/SKILL.md                  |  17 +-
 skills/agent-device/references/permissions.md |  14 ++
 .../references/session-management.md          |   1 +
 .../agent-device/references/snapshot-refs.md  |   1 +
 .../references/video-recording.md             |   2 +
 src/core/__tests__/capabilities.test.ts       |  18 +-
 src/core/capabilities.ts                      |  39 ++--
 src/core/dispatch.ts                          |   8 +-
 src/daemon.ts                                 |   2 +-
 src/daemon/app-state.ts                       |  22 +++
 src/daemon/handlers/__tests__/session.test.ts |  13 +-
 .../__tests__/snapshot-handler.test.ts        |  92 ++++++++++
 src/daemon/handlers/session.ts                |   2 +-
 src/daemon/handlers/snapshot.ts               |  22 ++-
 .../ios/__tests__/runner-client.test.ts       |  63 +++++++
 src/platforms/ios/devices.ts                  |  35 +++-
 src/platforms/ios/runner-client.ts            | 171 +++++++++++++++---
 test/integration/ios.test.ts                  |  36 ++++
 website/docs/docs/commands.md                 |  20 ++
 website/docs/docs/installation.md             |  13 +-
 website/docs/docs/introduction.md             |  14 +-
 website/docs/docs/quick-start.md              |   6 +-
 website/docs/docs/sessions.md                 |   1 +
 website/docs/docs/snapshots.md                |   6 +-
 website/docs/index.md                         |   4 +-
 26 files changed, 552 insertions(+), 96 deletions(-)
 create mode 100644 src/daemon/handlers/__tests__/snapshot-handler.test.ts
 create mode 100644 src/platforms/ios/__tests__/runner-client.test.ts

diff --git a/README.md b/README.md
index 4e34732e1..2d9e79935 100644
--- a/README.md
+++ b/README.md
@@ -13,8 +13,8 @@ CLI to control iOS and Android devices for AI agents influenced by Vercel’s [a
 The project is in early development and considered experimental. Pull requests are welcome!
 
 ## Features
-- Platforms: iOS (simulator + limited device support) and Android (emulator + device).
-- Core commands: `open`, `back`, `home`, `app-switcher`, `press`, `long-press`, `swipe`, `focus`, `type`, `fill`, `scroll`, `scrollintoview`, `pinch`, `wait`, `alert`, `screenshot`, `close`, `reinstall`.
+- 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).
 - Device tooling: `adb` (Android), `simctl`/`devicectl` (iOS via Xcode).
 - Minimal dependencies; TypeScript executed directly on Node 22+ (no build step).
@@ -99,9 +99,10 @@ agent-device swipe 540 1500 540 500 120 --count 8 --pause-ms 30 --pattern ping-p
 | `ax` | Fast | Medium | Accessibility permission for the terminal app, not recommended |
 
 Notes:
-- Default backend is `xctest` on iOS.
+- Default backend is `xctest` on iOS simulators and iOS devices.
 - Scope snapshots with `-s "<label>"` or `-s @ref`.
-- If XCTest returns 0 nodes (e.g., foreground app changed), agent-device falls back to AX when available.
+- If XCTest returns 0 nodes (e.g., foreground app changed), agent-device falls back to AX on simulators when available.
+- `ax` backend is simulator-only.
 
 Flags:
 - `--version, -V` print version and exit
@@ -207,14 +208,14 @@ Android fill reliability:
 - If value does not match, agent-device clears the field and retries once with slower typing.
 - This reduces IME-related character swaps on long strings (e.g. emails and IDs).
 
-Settings helpers (simulators):
+Settings helpers:
 - `settings wifi on|off`
 - `settings airplane on|off`
 - `settings location on|off` (iOS uses per-app permission for the current session app)
-Note: iOS wifi/airplane toggles status bar indicators, not actual network state. Airplane off clears status bar overrides.
+Note: iOS supports these only on simulators in v1. 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 falls back to a snapshot-based guess (AX first, XCTest if AX can’t identify).
+- `appstate` shows the foreground app/activity (Android). On iOS it uses the current session app when available, otherwise it falls back to a snapshot-based guess (`xctest` on devices; AX-first on simulators with XCTest fallback).
 - `apps --metadata` returns app list with minimal metadata.
 
 ## Debug
@@ -238,9 +239,10 @@ Boot diagnostics:
 - Built-in aliases include `Settings` for both platforms.
 
 ## iOS notes
-- Input commands (`press`, `type`, `scroll`, etc.) are supported only on simulators in v1 and use the XCTest runner.
-- `alert` and `scrollintoview` use the XCTest runner and are simulator-only in v1.
-- Real device support (including snapshots) is on the roadmap for iOS.
+- 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 in v1: `alert`, `pinch`, `record`, `reinstall`, `apps`, `settings`.
+- iOS deep link open (`open <url>`) is simulator-only in v1.
+- 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`.
 
 ## Testing
 
@@ -266,6 +268,10 @@ 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_IOS_TEAM_ID=<team-id>` optional Team ID override for iOS device runner signing.
+- `AGENT_DEVICE_IOS_SIGNING_IDENTITY=<identity>` optional signing identity override (defaults to `Apple Development` when signing overrides are used).
+- `AGENT_DEVICE_IOS_PROVISIONING_PROFILE=<profile>` optional provisioning profile specifier for iOS device runner signing.
 
 Test screenshots are written to:
 - `test/screenshots/android-settings.png`
diff --git a/skills/agent-device/SKILL.md b/skills/agent-device/SKILL.md
index 1afe5727c..ef105e6bb 100644
--- a/skills/agent-device/SKILL.md
+++ b/skills/agent-device/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: agent-device
-description: Automates mobile and simulator interactions for iOS and Android devices. Use when navigating apps, taking snapshots/screenshots, tapping, typing, scrolling, pinching, or extracting UI info on mobile devices or simulators.
+description: Automates interactions for iOS simulators/devices and Android emulators/devices. Use when navigating apps, taking snapshots/screenshots, tapping, typing, scrolling, or extracting UI info on mobile targets.
 ---
 
 # Mobile Automation with agent-device
@@ -39,13 +39,13 @@ npx -y agent-device
 
 ```bash
 agent-device boot                 # Ensure target is booted/ready without opening app
-agent-device boot --platform ios  # Boot iOS simulator
+agent-device boot --platform ios  # Boot iOS simulator/device target
 agent-device boot --platform android # Boot Android emulator/device target
 agent-device open [app|url]       # Boot device/simulator; optionally launch app or deep link URL
 agent-device open [app] --relaunch # Terminate app process first, then launch (fresh runtime)
 agent-device open [app] --activity com.example/.MainActivity # Android: open specific activity (app targets only)
 agent-device open "myapp://home" --platform android          # Android deep link
-agent-device open "https://example.com" --platform ios       # iOS simulator deep link
+agent-device open "https://example.com" --platform ios       # iOS simulator deep link (device unsupported in v1)
 agent-device close [app]          # Close app or just end session
 agent-device reinstall <app> <path> # Uninstall + install app in one command
 agent-device session list         # List active sessions
@@ -82,7 +82,7 @@ agent-device find "Settings" wait 10000
 agent-device find "Settings" exists
 ```
 
-### Settings helpers (simulators)
+### Settings helpers
 
 ```bash
 agent-device settings wifi on
@@ -95,6 +95,7 @@ agent-device settings location off
 
 Note: iOS wifi/airplane toggles status bar indicators, not actual network state.
 Airplane off clears status bar overrides.
+iOS settings helpers are simulator-only in v1.
 
 ### App state
 
@@ -118,8 +119,8 @@ agent-device swipe 540 1500 540 500 120
 agent-device swipe 540 1500 540 500 120 --count 8 --pause-ms 30 --pattern ping-pong
 agent-device long-press 300 500 800    # Long press (where supported)
 agent-device scroll down 0.5
-agent-device pinch 2.0              # Zoom in 2x (iOS simulator)
-agent-device pinch 0.5 200 400     # Zoom out at coordinates (iOS simulator)
+agent-device pinch 2.0              # Zoom in 2x (iOS simulator only)
+agent-device pinch 0.5 200 400     # Zoom out at coordinates (iOS simulator only)
 agent-device back
 agent-device home
 agent-device app-switcher
@@ -179,7 +180,7 @@ agent-device apps --platform android --user-installed
 - Use selectors for deterministic replay artifacts and assertions (e.g. in e2e test workflows).
 - Prefer `snapshot -i` to reduce output size.
 - On iOS, `xctest` is the default and does not require Accessibility permission.
-- If XCTest returns 0 nodes (foreground app changed), agent-device falls back to AX when available.
+- If XCTest returns 0 nodes (foreground app changed), agent-device falls back to AX on simulators when available.
 - `open <app|url>` can be used within an existing session to switch apps or open deep links.
 - `open <app>` updates session app bundle context; URL opens do not set an app bundle id.
 - Use `open <app> --relaunch` during React Native/Fast Refresh debugging when you need a fresh app process without ending the session.
@@ -187,6 +188,8 @@ agent-device apps --platform android --user-installed
 - Use `--session <name>` for parallel sessions; avoid device contention.
 - 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 in v1.
+- 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).
 - 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 076de4f2f..04fcf3510 100644
--- a/skills/agent-device/references/permissions.md
+++ b/skills/agent-device/references/permissions.md
@@ -13,6 +13,20 @@ agent-device snapshot --backend xctest --platform ios
 ```
 
 Hybrid/AX is fast; XCTest is equally fast but does not require permissions.
+AX backend is simulator-only in v1.
+
+## iOS physical device runner
+
+For iOS physical devices, XCTest runner setup requires valid signing/provisioning.
+Use Automatic Signing in Xcode, or provide optional overrides:
+
+- `AGENT_DEVICE_IOS_TEAM_ID`
+- `AGENT_DEVICE_IOS_SIGNING_IDENTITY`
+- `AGENT_DEVICE_IOS_PROVISIONING_PROFILE`
+
+If first-run setup/build takes long, increase:
+
+- `AGENT_DEVICE_DAEMON_TIMEOUT_MS` (for example `180000`)
 
 ## Simulator troubleshooting
 
diff --git a/skills/agent-device/references/session-management.md b/skills/agent-device/references/session-management.md
index 5da3b713d..63f0dab5a 100644
--- a/skills/agent-device/references/session-management.md
+++ b/skills/agent-device/references/session-management.md
@@ -14,6 +14,7 @@ Sessions isolate device context. A device can only be held by one session at a t
 - Name sessions semantically.
 - Close sessions when done.
 - Use separate sessions for parallel work.
+- In iOS sessions, use `open <app>` for simulator/device. `open <url>` is simulator-only in v1.
 - 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.
 - For deterministic replay scripts, prefer selector-based actions and assertions.
 - Use `replay -u` to update selector drift during maintenance.
diff --git a/skills/agent-device/references/snapshot-refs.md b/skills/agent-device/references/snapshot-refs.md
index 01b351d8e..2d669e4f6 100644
--- a/skills/agent-device/references/snapshot-refs.md
+++ b/skills/agent-device/references/snapshot-refs.md
@@ -55,6 +55,7 @@ agent-device snapshot -i -s @e3
 - Ref not found: re-snapshot.
 - AX returns Simulator window: restart Simulator and re-run.
 - AX empty: verify Accessibility permission or use `--backend xctest` (XCTest is more complete).
+- AX backend is simulator-only in v1; use `--backend xctest` on iOS devices.
 
 ## Replay note
 
diff --git a/skills/agent-device/references/video-recording.md b/skills/agent-device/references/video-recording.md
index 09cec7949..42899241c 100644
--- a/skills/agent-device/references/video-recording.md
+++ b/skills/agent-device/references/video-recording.md
@@ -20,6 +20,8 @@ agent-device close
 agent-device record stop
 ```
 
+`record` is iOS simulator-only in v1.
+
 ## Android Emulator/Device
 
 Use `agent-device record` commands (wrapper around adb):
diff --git a/src/core/__tests__/capabilities.test.ts b/src/core/__tests__/capabilities.test.ts
index 9aaefbefb..1d160a367 100644
--- a/src/core/__tests__/capabilities.test.ts
+++ b/src/core/__tests__/capabilities.test.ts
@@ -32,10 +32,17 @@ test('iOS simulator-only commands reject iOS devices and Android', () => {
   }
 });
 
-test('iOS simulator + Android commands reject iOS devices', () => {
+test('simulator-only iOS commands with Android support reject iOS devices', () => {
+  for (const cmd of ['apps', '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`);
+  }
+});
+
+test('core commands support iOS simulator, iOS device, and Android', () => {
   for (const cmd of [
     'app-switcher',
-    'apps',
     'back',
     'boot',
     'click',
@@ -47,19 +54,16 @@ test('iOS simulator + Android commands reject iOS devices', () => {
     'home',
     'long-press',
     'open',
-    'reinstall',
     'press',
-    'record',
     'screenshot',
     'scroll',
-    'swipe',
-    'settings',
+    'scrollintoview',
     'snapshot',
     'type',
     'wait',
   ]) {
     assert.equal(isCommandSupportedOnDevice(cmd, iosSimulator), true, `${cmd} on iOS sim`);
-    assert.equal(isCommandSupportedOnDevice(cmd, iosDevice), false, `${cmd} on iOS device`);
+    assert.equal(isCommandSupportedOnDevice(cmd, iosDevice), true, `${cmd} on iOS device`);
     assert.equal(isCommandSupportedOnDevice(cmd, androidDevice), true, `${cmd} on Android`);
   }
 });
diff --git a/src/core/capabilities.ts b/src/core/capabilities.ts
index a9c52efd4..d3c733fbb 100644
--- a/src/core/capabilities.ts
+++ b/src/core/capabilities.ts
@@ -16,30 +16,31 @@ const COMMAND_CAPABILITY_MATRIX: Record<string, CommandCapability> = {
   // iOS simulator-only in v1.
   alert: { ios: { simulator: true }, android: {} },
   pinch: { ios: { simulator: true }, android: {} },
-  'app-switcher': { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
+  '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 } },
-  back: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  boot: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  click: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  close: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  fill: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  find: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  focus: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  get: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  is: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  home: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  'long-press': { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  open: { ios: { simulator: 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 } },
+  close: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  fill: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  find: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  focus: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  get: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  is: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  home: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  'long-press': { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  open: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
   reinstall: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  press: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
+  press: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
   record: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  screenshot: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  scroll: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
+  screenshot: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  scroll: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  scrollintoview: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
   swipe: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
   settings: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  snapshot: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  type: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  wait: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
+  snapshot: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  type: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  wait: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
 };
 
 export function isCommandSupportedOnDevice(command: string, device: DeviceInfo): boolean {
diff --git a/src/core/dispatch.ts b/src/core/dispatch.ts
index 02713ee61..88e5564ec 100644
--- a/src/core/dispatch.ts
+++ b/src/core/dispatch.ts
@@ -283,6 +283,12 @@ export async function dispatchCommand(
     case 'snapshot': {
       const backend = context?.snapshotBackend ?? 'xctest';
       if (device.platform === 'ios') {
+        if (backend === 'ax' && device.kind !== 'simulator') {
+          throw new AppError(
+            'UNSUPPORTED_OPERATION',
+            'AX snapshot backend is not supported on iOS physical devices; use --backend xctest',
+          );
+        }
         if (backend === 'ax') {
           const ax = await snapshotAx(device, { traceLogPath: context?.traceLogPath });
           return { nodes: ax.nodes ?? [], truncated: false, backend: 'ax' };
@@ -301,7 +307,7 @@ export async function dispatchCommand(
           { verbose: context?.verbose, logPath: context?.logPath, traceLogPath: context?.traceLogPath },
         )) as { nodes?: RawSnapshotNode[]; truncated?: boolean };
         const nodes = result.nodes ?? [];
-        if (nodes.length === 0) {
+        if (nodes.length === 0 && device.kind === 'simulator') {
           try {
             const ax = await snapshotAx(device, { traceLogPath: context?.traceLogPath });
             return { nodes: ax.nodes ?? [], truncated: false, backend: 'ax' };
diff --git a/src/daemon.ts b/src/daemon.ts
index 503f6e271..39ef12371 100644
--- a/src/daemon.ts
+++ b/src/daemon.ts
@@ -175,7 +175,7 @@ function start(): void {
   const shutdown = async () => {
     const sessionsToStop = sessionStore.toArray();
     for (const session of sessionsToStop) {
-      if (session.device.platform === 'ios' && session.device.kind === 'simulator') {
+      if (session.device.platform === 'ios') {
         await stopIosRunnerSession(session.device.id);
       }
       sessionStore.writeSessionLog(session);
diff --git a/src/daemon/app-state.ts b/src/daemon/app-state.ts
index 82438fd1d..2afa8dcb7 100644
--- a/src/daemon/app-state.ts
+++ b/src/daemon/app-state.ts
@@ -10,6 +10,28 @@ export async function resolveIosAppStateFromSnapshots(
   traceLogPath: string | undefined,
   flags: CommandFlags | undefined,
 ): Promise<{ appName: string; appBundleId?: string; source: 'snapshot-ax' | 'snapshot-xctest' }> {
+  if (device.kind === 'device') {
+    const xctestResult = await dispatchCommand(device, 'snapshot', [], flags?.out, {
+      ...contextFromFlags(
+        logPath,
+        {
+          ...flags,
+          snapshotDepth: 1,
+          snapshotCompact: true,
+          snapshotBackend: 'xctest',
+        },
+        undefined,
+        traceLogPath,
+      ),
+    });
+    const xcNode = extractAppNodeFromSnapshot(xctestResult as { nodes?: RawSnapshotNode[] });
+    return {
+      appName: xcNode?.appName ?? xcNode?.appBundleId ?? 'unknown',
+      appBundleId: xcNode?.appBundleId,
+      source: 'snapshot-xctest',
+    };
+  }
+
   const axResult = await dispatchCommand(device, 'snapshot', [], flags?.out, {
     ...contextFromFlags(
       logPath,
diff --git a/src/daemon/handlers/__tests__/session.test.ts b/src/daemon/handlers/__tests__/session.test.ts
index 25049db88..5d5b5b2ec 100644
--- a/src/daemon/handlers/__tests__/session.test.ts
+++ b/src/daemon/handlers/__tests__/session.test.ts
@@ -46,7 +46,7 @@ test('boot requires session or explicit selector', async () => {
   }
 });
 
-test('boot rejects unsupported iOS device kind', async () => {
+test('boot succeeds for iOS physical devices', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'ios-device-session';
   sessionStore.set(
@@ -59,6 +59,7 @@ test('boot rejects unsupported iOS device kind', async () => {
       booted: true,
     }),
   );
+  let ensureCalls = 0;
   const response = await handleSessionCommands({
     req: {
       token: 't',
@@ -72,13 +73,15 @@ test('boot rejects unsupported iOS device kind', async () => {
     sessionStore,
     invoke: noopInvoke,
     ensureReady: async () => {
-      throw new Error('ensureReady should not be called for unsupported boot');
+      ensureCalls += 1;
     },
   });
   assert.ok(response);
-  assert.equal(response?.ok, false);
-  if (response && !response.ok) {
-    assert.equal(response.error.code, 'UNSUPPORTED_OPERATION');
+  assert.equal(response?.ok, true);
+  assert.equal(ensureCalls, 1);
+  if (response && response.ok) {
+    assert.equal(response.data?.platform, 'ios');
+    assert.equal(response.data?.booted, true);
   }
 });
 
diff --git a/src/daemon/handlers/__tests__/snapshot-handler.test.ts b/src/daemon/handlers/__tests__/snapshot-handler.test.ts
new file mode 100644
index 000000000..a689c6b8c
--- /dev/null
+++ b/src/daemon/handlers/__tests__/snapshot-handler.test.ts
@@ -0,0 +1,92 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { handleSnapshotCommands } from '../snapshot.ts';
+import { SessionStore } from '../../session-store.ts';
+import type { SessionState } from '../../types.ts';
+
+function makeSessionStore(): SessionStore {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-snapshot-handler-'));
+  return new SessionStore(path.join(root, 'sessions'));
+}
+
+function makeSession(name: string, device: SessionState['device']): SessionState {
+  return {
+    name,
+    device,
+    createdAt: Date.now(),
+    actions: [],
+  };
+}
+
+test('snapshot rejects AX backend on iOS physical devices', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'ios-device';
+  sessionStore.set(
+    sessionName,
+    makeSession(sessionName, {
+      platform: 'ios',
+      id: 'ios-device-1',
+      name: 'My iPhone',
+      kind: 'device',
+      booted: true,
+    }),
+  );
+
+  const response = await handleSnapshotCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'snapshot',
+      positionals: [],
+      flags: { snapshotBackend: 'ax' },
+    },
+    sessionName,
+    logPath: '/tmp/daemon.log',
+    sessionStore,
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, false);
+  if (response && !response.ok) {
+    assert.equal(response.error.code, 'UNSUPPORTED_OPERATION');
+    assert.match(response.error.message, /AX snapshot backend is not supported/i);
+  }
+});
+
+test('settings rejects unsupported iOS physical devices', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'ios-device';
+  sessionStore.set(
+    sessionName,
+    makeSession(sessionName, {
+      platform: 'ios',
+      id: 'ios-device-1',
+      name: 'My iPhone',
+      kind: 'device',
+      booted: true,
+    }),
+  );
+
+  const response = await handleSnapshotCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'settings',
+      positionals: ['wifi', 'on'],
+      flags: {},
+    },
+    sessionName,
+    logPath: '/tmp/daemon.log',
+    sessionStore,
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, false);
+  if (response && !response.ok) {
+    assert.equal(response.error.code, 'UNSUPPORTED_OPERATION');
+    assert.match(response.error.message, /settings is not supported/i);
+  }
+});
diff --git a/src/daemon/handlers/session.ts b/src/daemon/handlers/session.ts
index cdf12416a..4f3f08c41 100644
--- a/src/daemon/handlers/session.ts
+++ b/src/daemon/handlers/session.ts
@@ -497,7 +497,7 @@ export async function handleSessionCommands(params: {
         ...contextFromFlags(logPath, req.flags, session.appBundleId, session.trace?.outPath),
       });
     }
-    if (session.device.platform === 'ios' && session.device.kind === 'simulator') {
+    if (session.device.platform === 'ios') {
       await stopIosRunnerSession(session.device.id);
     }
     sessionStore.recordAction(session, {
diff --git a/src/daemon/handlers/snapshot.ts b/src/daemon/handlers/snapshot.ts
index 5c0b57493..771f937c0 100644
--- a/src/daemon/handlers/snapshot.ts
+++ b/src/daemon/handlers/snapshot.ts
@@ -33,7 +33,16 @@ export async function handleSnapshotCommands(params: {
         ok: false,
         error: {
           code: 'UNSUPPORTED_OPERATION',
-          message: 'snapshot is only supported on iOS simulators in v1',
+          message: 'snapshot is not supported on this device',
+        },
+      };
+    }
+    if (device.platform === 'ios' && device.kind === 'device' && req.flags?.snapshotBackend === 'ax') {
+      return {
+        ok: false,
+        error: {
+          code: 'UNSUPPORTED_OPERATION',
+          message: 'AX snapshot backend is not supported on iOS physical devices; use --backend xctest',
         },
       };
     }
@@ -227,7 +236,7 @@ export async function handleSnapshotCommands(params: {
     const timeout = timeoutMs ?? DEFAULT_TIMEOUT_MS;
     const start = Date.now();
     while (Date.now() - start < timeout) {
-      if (device.platform === 'ios' && device.kind === 'simulator') {
+      if (device.platform === 'ios') {
         const result = (await runIosRunnerCommand(
           device,
           { command: 'findText', text, appBundleId: session?.appBundleId },
@@ -310,6 +319,15 @@ export async function handleSnapshotCommands(params: {
       };
     }
     const { session, device } = await resolveSessionDevice(sessionStore, sessionName, req.flags);
+    if (!isCommandSupportedOnDevice('settings', device)) {
+      return {
+        ok: false,
+        error: {
+          code: 'UNSUPPORTED_OPERATION',
+          message: 'settings is not supported on this device',
+        },
+      };
+    }
     const appBundleId = session?.appBundleId;
     const data = await dispatchCommand(
       device,
diff --git a/src/platforms/ios/__tests__/runner-client.test.ts b/src/platforms/ios/__tests__/runner-client.test.ts
new file mode 100644
index 000000000..34c62a81c
--- /dev/null
+++ b/src/platforms/ios/__tests__/runner-client.test.ts
@@ -0,0 +1,63 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import type { DeviceInfo } from '../../../utils/device.ts';
+import {
+  resolveRunnerBuildDestination,
+  resolveRunnerDestination,
+  resolveRunnerSigningBuildSettings,
+} from '../runner-client.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('resolveRunnerDestination uses simulator destination for simulators', () => {
+  assert.equal(resolveRunnerDestination(iosSimulator), 'platform=iOS Simulator,id=sim-1');
+});
+
+test('resolveRunnerDestination uses device destination for physical devices', () => {
+  assert.equal(
+    resolveRunnerDestination(iosDevice),
+    'platform=iOS,id=00008110-000E12341234002E',
+  );
+});
+
+test('resolveRunnerBuildDestination uses generic iOS destination for physical devices', () => {
+  assert.equal(resolveRunnerBuildDestination(iosDevice), 'generic/platform=iOS');
+});
+
+test('resolveRunnerSigningBuildSettings returns empty args without env overrides', () => {
+  assert.deepEqual(resolveRunnerSigningBuildSettings({}), []);
+});
+
+test('resolveRunnerSigningBuildSettings enables automatic signing defaults for device builds', () => {
+  assert.deepEqual(resolveRunnerSigningBuildSettings({}, true), [
+    'CODE_SIGN_STYLE=Automatic',
+    'CODE_SIGN_IDENTITY=Apple Development',
+  ]);
+});
+
+test('resolveRunnerSigningBuildSettings uses Appium-style defaults with optional overrides', () => {
+  const settings = resolveRunnerSigningBuildSettings({
+    AGENT_DEVICE_IOS_TEAM_ID: 'ABCDE12345',
+    AGENT_DEVICE_IOS_PROVISIONING_PROFILE: 'My Profile',
+  }, true);
+  assert.deepEqual(settings, [
+    'CODE_SIGN_STYLE=Automatic',
+    'DEVELOPMENT_TEAM=ABCDE12345',
+    'CODE_SIGN_IDENTITY=Apple Development',
+    'PROVISIONING_PROFILE_SPECIFIER=My Profile',
+  ]);
+});
diff --git a/src/platforms/ios/devices.ts b/src/platforms/ios/devices.ts
index ab70426be..0ecbf7fb2 100644
--- a/src/platforms/ios/devices.ts
+++ b/src/platforms/ios/devices.ts
@@ -1,3 +1,6 @@
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+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';
@@ -41,16 +44,34 @@ export async function listIosDevices(): Promise<DeviceInfo[]> {
   const devicectlAvailable = await whichCmd('xcrun');
   if (devicectlAvailable) {
     try {
-      const result = await runCmd('xcrun', ['devicectl', 'list', 'devices', '--json']);
-      const payload = JSON.parse(result.stdout as string) as {
-        devices: { identifier: string; name: string; platform: string }[];
+      const jsonPath = path.join(
+        os.tmpdir(),
+        `agent-device-devicectl-${process.pid}-${Date.now()}.json`,
+      );
+      await runCmd('xcrun', ['devicectl', 'list', 'devices', '--json-output', jsonPath]);
+      const jsonText = await fs.readFile(jsonPath, 'utf8');
+      await fs.rm(jsonPath, { force: true });
+      const payload = JSON.parse(jsonText) as {
+        result?: {
+          devices?: Array<{
+            identifier?: string;
+            name?: string;
+            hardwareProperties?: { platform?: string; udid?: string };
+            deviceProperties?: { name?: string };
+            connectionProperties?: { tunnelState?: string };
+          }>;
+        };
       };
-      for (const device of payload.devices ?? []) {
-        if (device.platform?.toLowerCase().includes('ios')) {
+      for (const device of payload.result?.devices ?? []) {
+        const platform = device.hardwareProperties?.platform ?? '';
+        if (platform.toLowerCase().includes('ios')) {
+          const id = device.hardwareProperties?.udid ?? device.identifier ?? '';
+          const name = device.name ?? device.deviceProperties?.name ?? id;
+          if (!id) continue;
           devices.push({
             platform: 'ios',
-            id: device.identifier,
-            name: device.name,
+            id,
+            name,
             kind: 'device',
             booted: true,
           });
diff --git a/src/platforms/ios/runner-client.ts b/src/platforms/ios/runner-client.ts
index 2c7a8c0e9..e085ff47c 100644
--- a/src/platforms/ios/runner-client.ts
+++ b/src/platforms/ios/runner-client.ts
@@ -106,10 +106,6 @@ async function executeRunnerCommand(
   command: RunnerCommand,
   options: { verbose?: boolean; logPath?: string; traceLogPath?: string } = {},
 ): Promise<Record<string, unknown>> {
-  if (device.kind !== 'simulator') {
-    throw new AppError('UNSUPPORTED_OPERATION', 'iOS runner only supports simulators in v1');
-  }
-
   try {
     const session = await ensureRunnerSession(device, options);
     const timeoutMs = session.ready ? RUNNER_COMMAND_TIMEOUT_MS : RUNNER_STARTUP_TIMEOUT_MS;
@@ -221,8 +217,8 @@ async function ensureRunnerSession(
   const existing = runnerSessions.get(device.id);
   if (existing) return existing;
 
-  await ensureBooted(device.id);
-  const xctestrun = await ensureXctestrun(device.id, options);
+  await ensureBootedIfNeeded(device);
+  const xctestrun = await ensureXctestrun(device, options);
   const port = await getFreePort();
   const { xctestrunPath, jsonPath } = await prepareXctestrunWithEnv(
     xctestrun,
@@ -239,12 +235,12 @@ async function ensureRunnerSession(
       'NO',
       '-test-timeouts-enabled',
       'NO',
-      '-maximum-concurrent-test-simulator-destinations',
+      '-maximum-concurrent-test-device-destinations',
       '1',
       '-xctestrun',
       xctestrunPath,
       '-destination',
-      `platform=iOS Simulator,id=${device.id}`,
+      resolveRunnerDestination(device),
     ],
     {
       allowFailure: true,
@@ -292,10 +288,10 @@ async function killRunnerProcessTree(
 
 
 async function ensureXctestrun(
-  udid: string,
+  device: DeviceInfo,
   options: { verbose?: boolean; logPath?: string; traceLogPath?: string },
 ): Promise<string> {
-  const derived = resolveRunnerDerivedPath();
+  const derived = resolveRunnerDerivedPath(device.kind);
   if (shouldCleanDerived()) {
     try {
       fs.rmSync(derived, { recursive: true, force: true });
@@ -313,6 +309,8 @@ async function ensureXctestrun(
     throw new AppError('COMMAND_FAILED', 'iOS runner project not found', { projectPath });
   }
 
+  const signingBuildSettings = resolveRunnerSigningBuildSettings(process.env, device.kind === 'device');
+  const provisioningArgs = device.kind === 'device' ? ['-allowProvisioningUpdates'] : [];
   try {
     await runCmdStreaming(
       'xcodebuild',
@@ -324,12 +322,14 @@ async function ensureXctestrun(
         'AgentDeviceRunner',
         '-parallel-testing-enabled',
         'NO',
-        '-maximum-concurrent-test-simulator-destinations',
+        '-maximum-concurrent-test-device-destinations',
         '1',
         '-destination',
-        `platform=iOS Simulator,id=${udid}`,
+        resolveRunnerBuildDestination(device),
         '-derivedDataPath',
         derived,
+        ...provisioningArgs,
+        ...signingBuildSettings,
       ],
       {
         onStdoutChunk: (chunk) => {
@@ -342,10 +342,12 @@ async function ensureXctestrun(
     );
   } catch (err) {
     const appErr = err instanceof AppError ? err : new AppError('COMMAND_FAILED', String(err));
+    const hint = resolveSigningFailureHint(appErr);
     throw new AppError('COMMAND_FAILED', 'xcodebuild build-for-testing failed', {
       error: appErr.message,
       details: appErr.details,
       logPath: options.logPath,
+      hint,
     });
   }
 
@@ -356,13 +358,76 @@ async function ensureXctestrun(
   return built;
 }
 
-function resolveRunnerDerivedPath(): string {
+function resolveRunnerDerivedPath(kind: DeviceInfo['kind']): string {
   const override = process.env.AGENT_DEVICE_IOS_RUNNER_DERIVED_PATH?.trim();
   if (override) {
     return path.resolve(override);
   }
   const base = path.join(os.homedir(), '.agent-device', 'ios-runner');
-  return path.join(base, 'derived');
+  return path.join(base, 'derived', kind);
+}
+
+export function resolveRunnerDestination(device: DeviceInfo): string {
+  if (device.platform !== 'ios') {
+    throw new AppError('UNSUPPORTED_PLATFORM', `Unsupported platform for iOS runner: ${device.platform}`);
+  }
+  if (device.kind === 'simulator') {
+    return `platform=iOS Simulator,id=${device.id}`;
+  }
+  return `platform=iOS,id=${device.id}`;
+}
+
+export function resolveRunnerBuildDestination(device: DeviceInfo): string {
+  if (device.platform !== 'ios') {
+    throw new AppError('UNSUPPORTED_PLATFORM', `Unsupported platform for iOS runner: ${device.platform}`);
+  }
+  if (device.kind === 'simulator') {
+    return `platform=iOS Simulator,id=${device.id}`;
+  }
+  return 'generic/platform=iOS';
+}
+
+function ensureBootedIfNeeded(device: DeviceInfo): Promise<void> {
+  if (device.kind !== 'simulator') {
+    return Promise.resolve();
+  }
+  return ensureBooted(device.id);
+}
+
+export function resolveRunnerSigningBuildSettings(
+  env: NodeJS.ProcessEnv = process.env,
+  forDevice = false,
+): string[] {
+  const teamId = env.AGENT_DEVICE_IOS_TEAM_ID?.trim() || '';
+  const configuredIdentity = env.AGENT_DEVICE_IOS_SIGNING_IDENTITY?.trim() || '';
+  const profile = env.AGENT_DEVICE_IOS_PROVISIONING_PROFILE?.trim() || '';
+  if (!forDevice && !teamId && !configuredIdentity && !profile) {
+    return [];
+  }
+  const args = ['CODE_SIGN_STYLE=Automatic'];
+  if (teamId) {
+    args.push(`DEVELOPMENT_TEAM=${teamId}`);
+  }
+  if (configuredIdentity || forDevice) {
+    args.push(`CODE_SIGN_IDENTITY=${configuredIdentity || 'Apple Development'}`);
+  }
+  if (profile) args.push(`PROVISIONING_PROFILE_SPECIFIER=${profile}`);
+  return args;
+}
+
+function resolveSigningFailureHint(error: AppError): string | undefined {
+  const details = error.details ? JSON.stringify(error.details) : '';
+  const combined = `${error.message}\n${details}`.toLowerCase();
+  if (combined.includes('requires a development team')) {
+    return 'Configure signing in Xcode or set AGENT_DEVICE_IOS_TEAM_ID for physical-device runs.';
+  }
+  if (combined.includes('no profiles for') || combined.includes('provisioning profile')) {
+    return 'Install/select a valid iOS provisioning profile, or set AGENT_DEVICE_IOS_PROVISIONING_PROFILE.';
+  }
+  if (combined.includes('code signing')) {
+    return 'Enable Automatic Signing in Xcode or provide AGENT_DEVICE_IOS_TEAM_ID and optional AGENT_DEVICE_IOS_SIGNING_IDENTITY.';
+  }
+  return undefined;
 }
 
 function findXctestrun(root: string): string | null {
@@ -440,20 +505,23 @@ async function waitForRunner(
   logPath?: string,
   timeoutMs: number = RUNNER_STARTUP_TIMEOUT_MS,
 ): Promise<Response> {
+  const endpoints = await resolveRunnerCommandEndpoints(device, port);
   const start = Date.now();
   let lastError: unknown = null;
   while (Date.now() - start < timeoutMs) {
-    try {
-      const response = await fetch(`http://127.0.0.1:${port}/command`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(command),
-      });
-      return response;
-    } catch (err) {
-      lastError = err;
-      await new Promise((resolve) => setTimeout(resolve, 100));
+    for (const endpoint of endpoints) {
+      try {
+        const response = await fetch(endpoint, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(command),
+        });
+        return response;
+      } catch (err) {
+        lastError = err;
+      }
     }
+    await new Promise((resolve) => setTimeout(resolve, 100));
   }
   if (device.kind === 'simulator') {
     const simResponse = await postCommandViaSimulator(device.id, port, command);
@@ -462,6 +530,7 @@ async function waitForRunner(
 
   throw new AppError('COMMAND_FAILED', 'Runner did not accept connection', {
     port,
+    endpoints,
     logPath,
     lastError: lastError ? String(lastError) : undefined,
     reason: classifyBootFailure({
@@ -473,6 +542,60 @@ async function waitForRunner(
   });
 }
 
+async function resolveRunnerCommandEndpoints(
+  device: DeviceInfo,
+  port: number,
+): Promise<string[]> {
+  const endpoints = [`http://127.0.0.1:${port}/command`];
+  if (device.kind !== 'device') {
+    return endpoints;
+  }
+  const tunnelIp = await resolveDeviceTunnelIp(device.id);
+  if (tunnelIp) {
+    endpoints.unshift(`http://[${tunnelIp}]:${port}/command`);
+  }
+  return endpoints;
+}
+
+async function resolveDeviceTunnelIp(deviceId: string): Promise<string | null> {
+  const jsonPath = path.join(
+    os.tmpdir(),
+    `agent-device-devicectl-info-${process.pid}-${Date.now()}.json`,
+  );
+  try {
+    const result = await runCmd(
+      'xcrun',
+      [
+        'devicectl',
+        'device',
+        'info',
+        'details',
+        '--device',
+        deviceId,
+        '--json-output',
+        jsonPath,
+        '--timeout',
+        '10',
+      ],
+      { allowFailure: true },
+    );
+    if (result.exitCode !== 0 || !fs.existsSync(jsonPath)) {
+      return null;
+    }
+    const payload = JSON.parse(fs.readFileSync(jsonPath, 'utf8')) as {
+      result?: {
+        connectionProperties?: { tunnelIPAddress?: string };
+      };
+    };
+    const ip = payload.result?.connectionProperties?.tunnelIPAddress?.trim();
+    return ip && ip.length > 0 ? ip : null;
+  } catch {
+    return null;
+  } finally {
+    cleanupTempFile(jsonPath);
+  }
+}
+
 async function postCommandViaSimulator(
   udid: string,
   port: number,
diff --git a/test/integration/ios.test.ts b/test/integration/ios.test.ts
index 67feb716a..f34b7ab3e 100644
--- a/test/integration/ios.test.ts
+++ b/test/integration/ios.test.ts
@@ -5,9 +5,13 @@ import { createIntegrationTestContext, runCliJson } from './test-helpers.ts';
 
 const session = ['--session', 'ios-test'];
 const iosTarget = ['--platform', 'ios'];
+const iosPhysicalUdid = process.env.IOS_UDID?.trim();
 
 test.after(() => {
   runCliJson(['close', ...iosTarget, '--json', ...session]);
+  if (iosPhysicalUdid) {
+    runCliJson(['close', '--platform', 'ios', '--udid', iosPhysicalUdid, '--json', '--session', 'ios-device-test']);
+  }
 });
 
 test('ios settings commands', { skip: shouldSkipIos() }, async () => {
@@ -79,6 +83,38 @@ test('ios settings commands', { skip: shouldSkipIos() }, async () => {
   integration.runStep('back', backArgs);
 });
 
+test('ios physical device core lifecycle', { skip: shouldSkipIosPhysicalDevice() }, async () => {
+  const integration = createIntegrationTestContext({
+    platform: 'ios',
+    testName: 'ios physical device core lifecycle',
+  });
+  const deviceSession = ['--session', 'ios-device-test'];
+  const target = ['--platform', 'ios', '--udid', iosPhysicalUdid as string];
+
+  const openArgs = ['open', 'com.apple.Preferences', ...target, '--json', ...deviceSession];
+  integration.runStep('open settings (device)', openArgs);
+
+  const snapshotArgs = ['snapshot', '--backend', 'xctest', '--json', ...deviceSession];
+  const snapshot = integration.runStep('snapshot (device)', snapshotArgs);
+  integration.assertResult(
+    Array.isArray(snapshot.json?.data?.nodes),
+    'snapshot nodes (device)',
+    snapshotArgs,
+    snapshot,
+    { detail: 'expected snapshot to include a nodes array' },
+  );
+
+  const clickArgs = ['click', 'role=cell', 'label=General', '--json', ...deviceSession];
+  integration.runStep('click general (device)', clickArgs);
+
+  const backArgs = ['back', '--json', ...deviceSession];
+  integration.runStep('back (device)', backArgs);
+});
+
 function shouldSkipIos(): boolean {
   return process.platform !== 'darwin';
 }
+
+function shouldSkipIosPhysicalDevice(): boolean {
+  return process.platform !== 'darwin' || !iosPhysicalUdid;
+}
diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md
index 525fb7028..83a50964d 100644
--- a/website/docs/docs/commands.md
+++ b/website/docs/docs/commands.md
@@ -23,6 +23,7 @@ agent-device app-switcher
 - `boot` requires either an active session or an explicit device selector.
 - `boot` is mainly needed when starting a new session and `open` fails because no booted simulator/emulator is available.
 - `open [app]` already boots/activates the selected target when needed.
+- `open <url>` deep links are supported on Android; iOS deep-link open is simulator-only in v1.
 
 ## Snapshot and inspect
 
@@ -32,6 +33,9 @@ agent-device get text @e1
 agent-device get attrs @e1
 ```
 
+- `--backend xctest` works on iOS simulators and iOS devices.
+- `--backend ax` is simulator-only.
+
 ## Interactions
 
 ```bash
@@ -98,6 +102,9 @@ agent-device settings location on
 agent-device settings location off
 ```
 
+- iOS `settings` support is simulator-only in v1.
+- Android `settings` support works on emulators and devices.
+
 ## Media and logs
 
 ```bash
@@ -107,3 +114,16 @@ agent-device record start               # Start screen recording to auto filenam
 agent-device record start session.mp4   # Start recording to explicit path
 agent-device record stop                # Stop active recording
 ```
+
+- iOS `record` is simulator-only in v1.
+
+## iOS device prerequisites
+
+- Xcode + `xcrun devicectl` available.
+- Paired physical device with Developer Mode enabled.
+- Use Automatic Signing in Xcode, or pass optional env overrides:
+  - `AGENT_DEVICE_IOS_TEAM_ID`
+  - `AGENT_DEVICE_IOS_SIGNING_IDENTITY` (defaults to `Apple Development` when overrides are used)
+  - `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)
diff --git a/website/docs/docs/installation.md b/website/docs/docs/installation.md
index c47af7bd5..94889982d 100644
--- a/website/docs/docs/installation.md
+++ b/website/docs/docs/installation.md
@@ -19,5 +19,16 @@ npx agent-device open Settings --platform ios
 ## Requirements
 
 - Node.js 22+
-- Xcode for iOS simulator automation
+- Xcode for iOS simulator/device automation (`simctl` + `devicectl`)
 - Android SDK / ADB for Android
+
+## iOS physical device prerequisites
+
+- Device is paired and visible in `xcrun devicectl list devices`.
+- Developer Mode enabled on device.
+- Signing configured in Xcode (Automatic Signing recommended), or use:
+- `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)
diff --git a/website/docs/docs/introduction.md b/website/docs/docs/introduction.md
index d49df3a0b..dc9ab7bc9 100644
--- a/website/docs/docs/introduction.md
+++ b/website/docs/docs/introduction.md
@@ -4,13 +4,13 @@ title: Introduction
 
 # Introduction
 
-`agent-device` is a CLI for automating iOS simulators and Android emulators (and devices) from agents. It provides:
+`agent-device` is a CLI for automating iOS simulators + physical devices and Android emulators + devices from agents. It provides:
 
 - Accessibility snapshots for UI understanding
 - Deterministic interactions (tap, type, scroll)
 - Session-aware workflows and replay
 
-If you know `agent-browser`, this is the mobile-native counterpart focused on simulators and emulators.
+If you know `agent-browser`, this is the mobile-native counterpart for iOS/Android UI automation.
 
 ## What it’s good at
 
@@ -18,11 +18,17 @@ If you know `agent-browser`, this is the mobile-native counterpart focused on si
 - Driving common UI actions with refs or semantic selectors
 - Replaying flows for regression checks
 
+## 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 in v1: `alert`, `pinch`, `record`, `reinstall`, `apps`, `settings`, and deep-link open (`open <url>`).
+- Android emulator + Android device support remains unchanged.
+
 ## Architecture (high level)
 
 1. CLI sends requests to the daemon.
 2. The daemon manages sessions and dispatches to platform drivers.
-3. iOS uses XCTest runner for snapshots and input; AX is optional fallback.
+3. iOS uses XCTest runner for snapshots and input on simulators and physical devices; AX is optional simulator fallback.
 4. Android uses ADB-based tooling.
 
 ## Example
@@ -49,4 +55,4 @@ agent-device click @e8
 agent-device snapshot -i
 agent-device fill @e5 "Doe 2"
 agent-device close
-```
\ No newline at end of file
+```
diff --git a/website/docs/docs/quick-start.md b/website/docs/docs/quick-start.md
index 9700be9c1..76ef190bf 100644
--- a/website/docs/docs/quick-start.md
+++ b/website/docs/docs/quick-start.md
@@ -23,7 +23,7 @@ agent-device click @e2
 agent-device snapshot -i
 ```
 
-boot simulator if there's none available:
+Boot target if there is no ready device/simulator:
 
 ```bash
 agent-device boot --platform ios # or android
@@ -41,7 +41,7 @@ agent-device screenshot page.png         # Save to specific path
 agent-device close
 ```
 
-If `open` fails because no booted simulator/emulator is available, run `boot --platform ios|android` and retry.
+If `open` fails because no booted simulator/emulator/device is available, run `boot --platform ios|android` and retry.
 
 ## Semantic discovery
 
@@ -76,6 +76,8 @@ agent-device settings airplane on
 agent-device settings location off
 ```
 
+Note: iOS `settings` commands are simulator-only in v1.
+
 ## JSON output
 
 For programmatic parsing in scripts:
diff --git a/website/docs/docs/sessions.md b/website/docs/docs/sessions.md
index 609173403..04ffb0de1 100644
--- a/website/docs/docs/sessions.md
+++ b/website/docs/docs/sessions.md
@@ -24,6 +24,7 @@ agent-device close --session my-session
 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 in v1.
 - Use `--session <name>` to run multiple sessions in parallel.
 
 For replay scripts and deterministic E2E guidance, see [Replay & E2E (Experimental)](/docs/replay-e2e).
diff --git a/website/docs/docs/snapshots.md b/website/docs/docs/snapshots.md
index 848278b62..afd2c7ca8 100644
--- a/website/docs/docs/snapshots.md
+++ b/website/docs/docs/snapshots.md
@@ -22,7 +22,7 @@ agent-device snapshot -i -c -d 5         # Combine options
 | `-d <depth>` | Limit tree depth          |
 | `-s <scope>` | Scope to label/identifier |
 
-Note: If XCTest returns 0 nodes (foreground app changed), agent-device falls back to AX when available.
+Note: If XCTest returns 0 nodes (foreground app changed), agent-device falls back to AX on iOS simulators when available.
 
 ## Example output:
 
@@ -43,5 +43,5 @@ agent-device snapshot -i
 
 ## Backends (iOS):
 
-- `xctest` (default): full fidelity, fast, no Accessibility permission required.
-- `ax`: fast accessibility tree, may miss details, requires Accessibility permission.
+- `xctest` (default): full fidelity, fast, no Accessibility permission required; supported on iOS simulators and iOS devices.
+- `ax`: fast accessibility tree, may miss details, requires Accessibility permission; simulator-only.
diff --git a/website/docs/index.md b/website/docs/index.md
index 7674248c7..807584ab8 100644
--- a/website/docs/index.md
+++ b/website/docs/index.md
@@ -14,13 +14,13 @@ hero:
 
 features:
   - title: One CLI, many devices
-    details: Control iOS simulators and Android emulators with consistent commands for snapshotting, input, and navigation.
+    details: Control iOS simulators + physical devices and Android emulators + devices with consistent snapshot and interaction commands.
   - title: Token-efficient UI snapshots
     details: XCTest accessibility trees give agents a complete view of the UI while keeping output compact.
   - title: Interactions that just work
     details: Tap, swipe, scroll, focus, and type with precise coordinates or semantic finders.
   - title: Session and replay
-    details: Open apps, switch apps in-session, and replay recorded actions to reproduce flows.
+    details: Open apps, switch apps in-session, and replay recorded actions to reproduce flows across platforms.
   - title: Visual verification
     details: Capture full-resolution screenshots for reporting and visual checks.
   - title: Traceable automation

From 1adc0de56eb041f4d784ad06eab32f1a47a2a4a5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Sat, 14 Feb 2026 12:52:25 +0100
Subject: [PATCH 02/13] ios: make signing identity override-only

---
 README.md                                         |  2 +-
 src/platforms/ios/__tests__/runner-client.test.ts |  6 +++---
 src/platforms/ios/runner-client.ts                | 14 +++++++++++---
 website/docs/docs/commands.md                     |  2 +-
 4 files changed, 16 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 2d9e79935..9c41f3d10 100644
--- a/README.md
+++ b/README.md
@@ -270,7 +270,7 @@ Environment selectors:
 - `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_IOS_TEAM_ID=<team-id>` optional Team ID override for iOS device runner signing.
-- `AGENT_DEVICE_IOS_SIGNING_IDENTITY=<identity>` optional signing identity override (defaults to `Apple Development` when signing overrides are used).
+- `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.
 
 Test screenshots are written to:
diff --git a/src/platforms/ios/__tests__/runner-client.test.ts b/src/platforms/ios/__tests__/runner-client.test.ts
index 34c62a81c..75a2de9ac 100644
--- a/src/platforms/ios/__tests__/runner-client.test.ts
+++ b/src/platforms/ios/__tests__/runner-client.test.ts
@@ -42,16 +42,16 @@ test('resolveRunnerSigningBuildSettings returns empty args without env overrides
   assert.deepEqual(resolveRunnerSigningBuildSettings({}), []);
 });
 
-test('resolveRunnerSigningBuildSettings enables automatic signing defaults for device builds', () => {
+test('resolveRunnerSigningBuildSettings enables automatic signing for device builds without forcing identity', () => {
   assert.deepEqual(resolveRunnerSigningBuildSettings({}, true), [
     'CODE_SIGN_STYLE=Automatic',
-    'CODE_SIGN_IDENTITY=Apple Development',
   ]);
 });
 
-test('resolveRunnerSigningBuildSettings uses Appium-style defaults with optional overrides', () => {
+test('resolveRunnerSigningBuildSettings applies optional overrides when provided', () => {
   const settings = resolveRunnerSigningBuildSettings({
     AGENT_DEVICE_IOS_TEAM_ID: 'ABCDE12345',
+    AGENT_DEVICE_IOS_SIGNING_IDENTITY: 'Apple Development',
     AGENT_DEVICE_IOS_PROVISIONING_PROFILE: 'My Profile',
   }, true);
   assert.deepEqual(settings, [
diff --git a/src/platforms/ios/runner-client.ts b/src/platforms/ios/runner-client.ts
index e085ff47c..f2f8f8672 100644
--- a/src/platforms/ios/runner-client.ts
+++ b/src/platforms/ios/runner-client.ts
@@ -408,8 +408,8 @@ export function resolveRunnerSigningBuildSettings(
   if (teamId) {
     args.push(`DEVELOPMENT_TEAM=${teamId}`);
   }
-  if (configuredIdentity || forDevice) {
-    args.push(`CODE_SIGN_IDENTITY=${configuredIdentity || 'Apple Development'}`);
+  if (configuredIdentity) {
+    args.push(`CODE_SIGN_IDENTITY=${configuredIdentity}`);
   }
   if (profile) args.push(`PROVISIONING_PROFILE_SPECIFIER=${profile}`);
   return args;
@@ -583,11 +583,19 @@ async function resolveDeviceTunnelIp(deviceId: string): Promise<string | null> {
       return null;
     }
     const payload = JSON.parse(fs.readFileSync(jsonPath, 'utf8')) as {
+      info?: { outcome?: string };
       result?: {
         connectionProperties?: { tunnelIPAddress?: string };
+        device?: { connectionProperties?: { tunnelIPAddress?: string } };
       };
     };
-    const ip = payload.result?.connectionProperties?.tunnelIPAddress?.trim();
+    if (payload.info?.outcome && payload.info.outcome !== 'success') {
+      return null;
+    }
+    const ip = (
+      payload.result?.connectionProperties?.tunnelIPAddress
+      ?? payload.result?.device?.connectionProperties?.tunnelIPAddress
+    )?.trim();
     return ip && ip.length > 0 ? ip : null;
   } catch {
     return null;
diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md
index 83a50964d..90803dfa6 100644
--- a/website/docs/docs/commands.md
+++ b/website/docs/docs/commands.md
@@ -123,7 +123,7 @@ agent-device record stop                # Stop active recording
 - Paired physical device with Developer Mode enabled.
 - Use Automatic Signing in Xcode, or pass optional env overrides:
   - `AGENT_DEVICE_IOS_TEAM_ID`
-  - `AGENT_DEVICE_IOS_SIGNING_IDENTITY` (defaults to `Apple Development` when overrides are used)
+  - `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)

From 03824c931a4c590c1b4028552923a23d59b60000 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Sat, 14 Feb 2026 13:36:10 +0100
Subject: [PATCH 03/13] ios: address PR55 review follow-ups

---
 src/core/dispatch.ts                          |  1 +
 .../ios/__tests__/runner-client.test.ts       | 23 ++++++
 src/platforms/ios/devices.ts                  | 73 ++++++++++---------
 src/platforms/ios/runner-client.ts            | 26 +++++--
 test/integration/ios.test.ts                  |  4 +-
 5 files changed, 85 insertions(+), 42 deletions(-)

diff --git a/src/core/dispatch.ts b/src/core/dispatch.ts
index 88e5564ec..28e1118b6 100644
--- a/src/core/dispatch.ts
+++ b/src/core/dispatch.ts
@@ -283,6 +283,7 @@ export async function dispatchCommand(
     case 'snapshot': {
       const backend = context?.snapshotBackend ?? 'xctest';
       if (device.platform === 'ios') {
+        // Keep this guard for non-daemon callers that invoke dispatch directly.
         if (backend === 'ax' && device.kind !== 'simulator') {
           throw new AppError(
             'UNSUPPORTED_OPERATION',
diff --git a/src/platforms/ios/__tests__/runner-client.test.ts b/src/platforms/ios/__tests__/runner-client.test.ts
index 75a2de9ac..6d085b57d 100644
--- a/src/platforms/ios/__tests__/runner-client.test.ts
+++ b/src/platforms/ios/__tests__/runner-client.test.ts
@@ -4,6 +4,7 @@ import type { DeviceInfo } from '../../../utils/device.ts';
 import {
   resolveRunnerBuildDestination,
   resolveRunnerDestination,
+  resolveRunnerMaxConcurrentDestinationsFlag,
   resolveRunnerSigningBuildSettings,
 } from '../runner-client.ts';
 
@@ -38,6 +39,20 @@ test('resolveRunnerBuildDestination uses generic iOS destination for physical de
   assert.equal(resolveRunnerBuildDestination(iosDevice), 'generic/platform=iOS');
 });
 
+test('resolveRunnerMaxConcurrentDestinationsFlag uses simulator flag for simulators', () => {
+  assert.equal(
+    resolveRunnerMaxConcurrentDestinationsFlag(iosSimulator),
+    '-maximum-concurrent-test-simulator-destinations',
+  );
+});
+
+test('resolveRunnerMaxConcurrentDestinationsFlag uses device flag for physical devices', () => {
+  assert.equal(
+    resolveRunnerMaxConcurrentDestinationsFlag(iosDevice),
+    '-maximum-concurrent-test-device-destinations',
+  );
+});
+
 test('resolveRunnerSigningBuildSettings returns empty args without env overrides', () => {
   assert.deepEqual(resolveRunnerSigningBuildSettings({}), []);
 });
@@ -48,6 +63,14 @@ test('resolveRunnerSigningBuildSettings enables automatic signing for device bui
   ]);
 });
 
+test('resolveRunnerSigningBuildSettings ignores device signing overrides for simulator builds', () => {
+  assert.deepEqual(resolveRunnerSigningBuildSettings({
+    AGENT_DEVICE_IOS_TEAM_ID: 'ABCDE12345',
+    AGENT_DEVICE_IOS_SIGNING_IDENTITY: 'Apple Development',
+    AGENT_DEVICE_IOS_PROVISIONING_PROFILE: 'My Profile',
+  }, false), []);
+});
+
 test('resolveRunnerSigningBuildSettings applies optional overrides when provided', () => {
   const settings = resolveRunnerSigningBuildSettings({
     AGENT_DEVICE_IOS_TEAM_ID: 'ABCDE12345',
diff --git a/src/platforms/ios/devices.ts b/src/platforms/ios/devices.ts
index 0ecbf7fb2..e465e7a24 100644
--- a/src/platforms/ios/devices.ts
+++ b/src/platforms/ios/devices.ts
@@ -41,44 +41,45 @@ export async function listIosDevices(): Promise<DeviceInfo[]> {
     throw new AppError('COMMAND_FAILED', 'Failed to parse simctl devices JSON', undefined, err);
   }
 
-  const devicectlAvailable = await whichCmd('xcrun');
-  if (devicectlAvailable) {
-    try {
-      const jsonPath = path.join(
-        os.tmpdir(),
-        `agent-device-devicectl-${process.pid}-${Date.now()}.json`,
-      );
-      await runCmd('xcrun', ['devicectl', 'list', 'devices', '--json-output', jsonPath]);
-      const jsonText = await fs.readFile(jsonPath, 'utf8');
-      await fs.rm(jsonPath, { force: true });
-      const payload = JSON.parse(jsonText) as {
-        result?: {
-          devices?: Array<{
-            identifier?: string;
-            name?: string;
-            hardwareProperties?: { platform?: string; udid?: string };
-            deviceProperties?: { name?: string };
-            connectionProperties?: { tunnelState?: string };
-          }>;
-        };
+  let jsonPath: string | null = null;
+  try {
+    jsonPath = path.join(
+      os.tmpdir(),
+      `agent-device-devicectl-${process.pid}-${Date.now()}.json`,
+    );
+    await runCmd('xcrun', ['devicectl', 'list', 'devices', '--json-output', jsonPath]);
+    const jsonText = await fs.readFile(jsonPath, 'utf8');
+    const payload = JSON.parse(jsonText) as {
+      result?: {
+        devices?: Array<{
+          identifier?: string;
+          name?: string;
+          hardwareProperties?: { platform?: string; udid?: string };
+          deviceProperties?: { name?: string };
+          connectionProperties?: { tunnelState?: string };
+        }>;
       };
-      for (const device of payload.result?.devices ?? []) {
-        const platform = device.hardwareProperties?.platform ?? '';
-        if (platform.toLowerCase().includes('ios')) {
-          const id = device.hardwareProperties?.udid ?? device.identifier ?? '';
-          const name = device.name ?? device.deviceProperties?.name ?? id;
-          if (!id) continue;
-          devices.push({
-            platform: 'ios',
-            id,
-            name,
-            kind: 'device',
-            booted: true,
-          });
-        }
+    };
+    for (const device of payload.result?.devices ?? []) {
+      const platform = device.hardwareProperties?.platform ?? '';
+      if (platform.toLowerCase().includes('ios')) {
+        const id = device.hardwareProperties?.udid ?? device.identifier ?? '';
+        const name = device.name ?? device.deviceProperties?.name ?? id;
+        if (!id) continue;
+        devices.push({
+          platform: 'ios',
+          id,
+          name,
+          kind: 'device',
+          booted: true,
+        });
       }
-    } catch {
-      // Ignore devicectl failures; simulators are still supported.
+    }
+  } catch {
+    // Ignore devicectl failures; simulators are still supported.
+  } finally {
+    if (jsonPath) {
+      await fs.rm(jsonPath, { force: true }).catch(() => {});
     }
   }
 
diff --git a/src/platforms/ios/runner-client.ts b/src/platforms/ios/runner-client.ts
index f2f8f8672..6edb59c3c 100644
--- a/src/platforms/ios/runner-client.ts
+++ b/src/platforms/ios/runner-client.ts
@@ -92,6 +92,7 @@ export async function runIosRunnerCommand(
   command: RunnerCommand,
   options: { verbose?: boolean; logPath?: string; traceLogPath?: string } = {},
 ): Promise<Record<string, unknown>> {
+  validateRunnerDevice(device);
   if (isReadOnlyRunnerCommand(command.command)) {
     return withRetry(
       () => executeRunnerCommand(device, command, options),
@@ -235,7 +236,7 @@ async function ensureRunnerSession(
       'NO',
       '-test-timeouts-enabled',
       'NO',
-      '-maximum-concurrent-test-device-destinations',
+      resolveRunnerMaxConcurrentDestinationsFlag(device),
       '1',
       '-xctestrun',
       xctestrunPath,
@@ -322,7 +323,7 @@ async function ensureXctestrun(
         'AgentDeviceRunner',
         '-parallel-testing-enabled',
         'NO',
-        '-maximum-concurrent-test-device-destinations',
+        resolveRunnerMaxConcurrentDestinationsFlag(device),
         '1',
         '-destination',
         resolveRunnerBuildDestination(device),
@@ -394,16 +395,31 @@ function ensureBootedIfNeeded(device: DeviceInfo): Promise<void> {
   return ensureBooted(device.id);
 }
 
+function validateRunnerDevice(device: DeviceInfo): void {
+  if (device.platform !== 'ios') {
+    throw new AppError('UNSUPPORTED_PLATFORM', `Unsupported platform for iOS runner: ${device.platform}`);
+  }
+  if (device.kind !== 'simulator' && device.kind !== 'device') {
+    throw new AppError('UNSUPPORTED_OPERATION', `Unsupported iOS device kind for runner: ${device.kind}`);
+  }
+}
+
+export function resolveRunnerMaxConcurrentDestinationsFlag(device: DeviceInfo): string {
+  return device.kind === 'device'
+    ? '-maximum-concurrent-test-device-destinations'
+    : '-maximum-concurrent-test-simulator-destinations';
+}
+
 export function resolveRunnerSigningBuildSettings(
   env: NodeJS.ProcessEnv = process.env,
   forDevice = false,
 ): string[] {
+  if (!forDevice) {
+    return [];
+  }
   const teamId = env.AGENT_DEVICE_IOS_TEAM_ID?.trim() || '';
   const configuredIdentity = env.AGENT_DEVICE_IOS_SIGNING_IDENTITY?.trim() || '';
   const profile = env.AGENT_DEVICE_IOS_PROVISIONING_PROFILE?.trim() || '';
-  if (!forDevice && !teamId && !configuredIdentity && !profile) {
-    return [];
-  }
   const args = ['CODE_SIGN_STYLE=Automatic'];
   if (teamId) {
     args.push(`DEVELOPMENT_TEAM=${teamId}`);
diff --git a/test/integration/ios.test.ts b/test/integration/ios.test.ts
index f34b7ab3e..64a5d8830 100644
--- a/test/integration/ios.test.ts
+++ b/test/integration/ios.test.ts
@@ -6,10 +6,11 @@ import { createIntegrationTestContext, runCliJson } from './test-helpers.ts';
 const session = ['--session', 'ios-test'];
 const iosTarget = ['--platform', 'ios'];
 const iosPhysicalUdid = process.env.IOS_UDID?.trim();
+let didRunIosPhysicalSession = false;
 
 test.after(() => {
   runCliJson(['close', ...iosTarget, '--json', ...session]);
-  if (iosPhysicalUdid) {
+  if (iosPhysicalUdid && didRunIosPhysicalSession) {
     runCliJson(['close', '--platform', 'ios', '--udid', iosPhysicalUdid, '--json', '--session', 'ios-device-test']);
   }
 });
@@ -90,6 +91,7 @@ test('ios physical device core lifecycle', { skip: shouldSkipIosPhysicalDevice()
   });
   const deviceSession = ['--session', 'ios-device-test'];
   const target = ['--platform', 'ios', '--udid', iosPhysicalUdid as string];
+  didRunIosPhysicalSession = true;
 
   const openArgs = ['open', 'com.apple.Preferences', ...target, '--json', ...deviceSession];
   integration.runStep('open settings (device)', openArgs);

From 6b8b5b2041bd7f33f878a49f6a6ac04c43b853af Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Sat, 14 Feb 2026 13:47:32 +0100
Subject: [PATCH 04/13] docs: remove v1 phrasing from support messages

---
 README.md                                            | 10 +++++-----
 ios-runner/README.md                                 |  2 +-
 skills/agent-device/SKILL.md                         |  8 ++++----
 skills/agent-device/references/permissions.md        |  2 +-
 skills/agent-device/references/session-management.md |  2 +-
 skills/agent-device/references/snapshot-refs.md      |  2 +-
 skills/agent-device/references/video-recording.md    |  2 +-
 src/core/capabilities.ts                             |  2 +-
 src/daemon/handlers/record-trace.ts                  |  2 +-
 src/daemon/handlers/snapshot.ts                      |  2 +-
 src/platforms/ios/index.ts                           |  4 ++--
 website/docs/docs/commands.md                        | 10 +++++-----
 website/docs/docs/introduction.md                    |  2 +-
 website/docs/docs/quick-start.md                     |  2 +-
 website/docs/docs/sessions.md                        |  2 +-
 15 files changed, 27 insertions(+), 27 deletions(-)

diff --git a/README.md b/README.md
index 9c41f3d10..898b478f1 100644
--- a/README.md
+++ b/README.md
@@ -151,13 +151,13 @@ Navigation helpers:
 - `boot --platform ios|android` ensures the target is ready without launching an app.
 - Use `boot` mainly when starting a new session and `open` fails because no booted simulator/emulator is available.
 - `open [app|url]` already boots/activates the selected target when needed.
-- `reinstall <app> <path>` uninstalls and installs the app binary in one command (Android + iOS simulator in v1).
+- `reinstall <app> <path>` uninstalls and installs the app binary in one command (Android + iOS simulator).
 - `reinstall` accepts package/bundle id style app names and supports `~` in paths.
 
 Deep links:
 - `open <url>` supports deep links with `scheme://...`.
 - Android opens deep links via `VIEW` intent.
-- iOS deep link open is simulator-only in v1.
+- iOS deep link open is simulator-only.
 - `--activity` cannot be combined with URL opens.
 
 ```bash
@@ -212,7 +212,7 @@ Settings helpers:
 - `settings wifi on|off`
 - `settings airplane on|off`
 - `settings location on|off` (iOS uses per-app permission for the current session app)
-Note: iOS supports these only on simulators in v1. iOS wifi/airplane toggles status bar indicators, not actual network state. Airplane off clears status bar overrides.
+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 falls back to a snapshot-based guess (`xctest` on devices; AX-first on simulators with XCTest fallback).
@@ -240,8 +240,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 in v1: `alert`, `pinch`, `record`, `reinstall`, `apps`, `settings`.
-- iOS deep link open (`open <url>`) is simulator-only in v1.
+- Simulator-only commands: `alert`, `pinch`, `record`, `reinstall`, `apps`, `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`.
 
 ## Testing
diff --git a/ios-runner/README.md b/ios-runner/README.md
index 81e48e790..fdf88084d 100644
--- a/ios-runner/README.md
+++ b/ios-runner/README.md
@@ -8,4 +8,4 @@ This folder is reserved for the lightweight XCUITest runner used to provide elem
 - Support simulator prebuilds where compatible.
 
 ## Status
-Planned for v1 automation layer. See `docs/ios-automation.md` and `docs/ios-runner-protocol.md`.
+Planned for the automation layer. See `docs/ios-automation.md` and `docs/ios-runner-protocol.md`.
diff --git a/skills/agent-device/SKILL.md b/skills/agent-device/SKILL.md
index ef105e6bb..55fcc3ad4 100644
--- a/skills/agent-device/SKILL.md
+++ b/skills/agent-device/SKILL.md
@@ -45,7 +45,7 @@ agent-device open [app|url]       # Boot device/simulator; optionally launch app
 agent-device open [app] --relaunch # Terminate app process first, then launch (fresh runtime)
 agent-device open [app] --activity com.example/.MainActivity # Android: open specific activity (app targets only)
 agent-device open "myapp://home" --platform android          # Android deep link
-agent-device open "https://example.com" --platform ios       # iOS simulator deep link (device unsupported in v1)
+agent-device open "https://example.com" --platform ios       # iOS simulator deep link (device unsupported)
 agent-device close [app]          # Close app or just end session
 agent-device reinstall <app> <path> # Uninstall + install app in one command
 agent-device session list         # List active sessions
@@ -95,7 +95,7 @@ agent-device settings location off
 
 Note: iOS wifi/airplane toggles status bar indicators, not actual network state.
 Airplane off clears status bar overrides.
-iOS settings helpers are simulator-only in v1.
+iOS settings helpers are simulator-only.
 
 ### App state
 
@@ -175,7 +175,7 @@ agent-device apps --platform android --user-installed
 - `press` supports gesture series controls: `--count`, `--interval-ms`, `--hold-ms`, `--jitter-px`.
 - `swipe` supports coordinate + timing controls and repeat patterns: `swipe x1 y1 x2 y2 [durationMs] --count --pause-ms --pattern`.
 - `swipe` timing is platform-safe: Android uses requested duration; iOS uses normalized safe timing to avoid long-press side effects.
-- Pinch (`pinch <scale> [x y]`) is currently supported on iOS simulators only.
+- Pinch (`pinch <scale> [x y]`) is iOS simulator-only; scale > 1 zooms in, < 1 zooms out.
 - Snapshot refs are the core mechanism for interactive agent flows.
 - Use selectors for deterministic replay artifacts and assertions (e.g. in e2e test workflows).
 - Prefer `snapshot -i` to reduce output size.
@@ -187,7 +187,7 @@ agent-device apps --platform android --user-installed
 - If AX returns the Simulator window or empty tree, restart Simulator or use `--backend xctest`.
 - Use `--session <name>` for parallel sessions; avoid device contention.
 - 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 in v1.
+- 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).
 - Use `fill` when you want clear-then-type semantics.
diff --git a/skills/agent-device/references/permissions.md b/skills/agent-device/references/permissions.md
index 04fcf3510..dea9fd025 100644
--- a/skills/agent-device/references/permissions.md
+++ b/skills/agent-device/references/permissions.md
@@ -13,7 +13,7 @@ agent-device snapshot --backend xctest --platform ios
 ```
 
 Hybrid/AX is fast; XCTest is equally fast but does not require permissions.
-AX backend is simulator-only in v1.
+AX backend is simulator-only.
 
 ## iOS physical device runner
 
diff --git a/skills/agent-device/references/session-management.md b/skills/agent-device/references/session-management.md
index 63f0dab5a..22eaa7b56 100644
--- a/skills/agent-device/references/session-management.md
+++ b/skills/agent-device/references/session-management.md
@@ -14,7 +14,7 @@ Sessions isolate device context. A device can only be held by one session at a t
 - Name sessions semantically.
 - Close sessions when done.
 - Use separate sessions for parallel work.
-- In iOS sessions, use `open <app>` for simulator/device. `open <url>` is simulator-only in v1.
+- In iOS sessions, use `open <app>` for simulator/device. `open <url>` is simulator-only.
 - 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.
 - For deterministic replay scripts, prefer selector-based actions and assertions.
 - Use `replay -u` to update selector drift during maintenance.
diff --git a/skills/agent-device/references/snapshot-refs.md b/skills/agent-device/references/snapshot-refs.md
index 2d669e4f6..2ff33dbca 100644
--- a/skills/agent-device/references/snapshot-refs.md
+++ b/skills/agent-device/references/snapshot-refs.md
@@ -55,7 +55,7 @@ agent-device snapshot -i -s @e3
 - Ref not found: re-snapshot.
 - AX returns Simulator window: restart Simulator and re-run.
 - AX empty: verify Accessibility permission or use `--backend xctest` (XCTest is more complete).
-- AX backend is simulator-only in v1; use `--backend xctest` on iOS devices.
+- AX backend is simulator-only; use `--backend xctest` on iOS devices.
 
 ## Replay note
 
diff --git a/skills/agent-device/references/video-recording.md b/skills/agent-device/references/video-recording.md
index 42899241c..a590ad056 100644
--- a/skills/agent-device/references/video-recording.md
+++ b/skills/agent-device/references/video-recording.md
@@ -20,7 +20,7 @@ agent-device close
 agent-device record stop
 ```
 
-`record` is iOS simulator-only in v1.
+`record` is iOS simulator-only.
 
 ## Android Emulator/Device
 
diff --git a/src/core/capabilities.ts b/src/core/capabilities.ts
index d3c733fbb..a5f6fef6e 100644
--- a/src/core/capabilities.ts
+++ b/src/core/capabilities.ts
@@ -13,7 +13,7 @@ type CommandCapability = {
 };
 
 const COMMAND_CAPABILITY_MATRIX: Record<string, CommandCapability> = {
-  // iOS simulator-only in v1.
+  // iOS simulator-only.
   alert: { ios: { simulator: true }, android: {} },
   pinch: { ios: { simulator: true }, android: {} },
   'app-switcher': { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
diff --git a/src/daemon/handlers/record-trace.ts b/src/daemon/handlers/record-trace.ts
index 34aea8b80..fc7833e9d 100644
--- a/src/daemon/handlers/record-trace.ts
+++ b/src/daemon/handlers/record-trace.ts
@@ -47,7 +47,7 @@ export async function handleRecordTraceCommands(params: {
       if (!isCommandSupportedOnDevice('record', device)) {
         return {
           ok: false,
-          error: { code: 'UNSUPPORTED_OPERATION', message: 'record is only supported on iOS simulators in v1' },
+          error: { code: 'UNSUPPORTED_OPERATION', message: 'record is only supported on iOS simulators' },
         };
       }
       if (device.platform === 'ios') {
diff --git a/src/daemon/handlers/snapshot.ts b/src/daemon/handlers/snapshot.ts
index 771f937c0..887dafccb 100644
--- a/src/daemon/handlers/snapshot.ts
+++ b/src/daemon/handlers/snapshot.ts
@@ -269,7 +269,7 @@ export async function handleSnapshotCommands(params: {
         ok: false,
         error: {
           code: 'UNSUPPORTED_OPERATION',
-          message: 'alert is only supported on iOS simulators in v1',
+          message: 'alert is only supported on iOS simulators',
         },
       };
     }
diff --git a/src/platforms/ios/index.ts b/src/platforms/ios/index.ts
index 4b8f4c80e..4da75c1d0 100644
--- a/src/platforms/ios/index.ts
+++ b/src/platforms/ios/index.ts
@@ -54,7 +54,7 @@ export async function openIosApp(
   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 in v1');
+      throw new AppError('UNSUPPORTED_OPERATION', 'Deep link open is only supported on iOS simulators');
     }
     await ensureBootedSimulator(device);
     await runCmd('open', ['-a', 'Simulator'], { allowFailure: true });
@@ -249,7 +249,7 @@ function ensureSimulator(device: DeviceInfo, command: string): void {
   if (device.kind !== 'simulator') {
     throw new AppError(
       'UNSUPPORTED_OPERATION',
-      `${command} is only supported on iOS simulators in v1`,
+      `${command} is only supported on iOS simulators`,
     );
   }
 }
diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md
index 90803dfa6..000942822 100644
--- a/website/docs/docs/commands.md
+++ b/website/docs/docs/commands.md
@@ -23,7 +23,7 @@ agent-device app-switcher
 - `boot` requires either an active session or an explicit device selector.
 - `boot` is mainly needed when starting a new session and `open` fails because no booted simulator/emulator is available.
 - `open [app]` already boots/activates the selected target when needed.
-- `open <url>` deep links are supported on Android; iOS deep-link open is simulator-only in v1.
+- `open <url>` deep links are supported on Android; iOS deep-link open is simulator-only.
 
 ## Snapshot and inspect
 
@@ -58,7 +58,7 @@ agent-device pinch 0.5 200 400 # zoom out at coordinates (iOS simulator)
 On Android, `fill` also verifies text and performs one clear-and-retry pass on mismatch.
 `swipe` accepts an optional `durationMs` argument (default `250ms`, range `16..10000`).
 On iOS, swipe timing uses a safe normalized duration to avoid long-press side effects.
-`pinch` is iOS-simulator-only in the current adb-backed Android implementation.
+`pinch` is iOS simulator-only.
 
 ## Find (semantic)
 
@@ -88,7 +88,7 @@ agent-device reinstall com.example.app ./build/MyApp.app --platform ios
 ```
 
 - `reinstall <app> <path>` uninstalls and installs in one command.
-- Supports Android devices/emulators and iOS simulators in v1.
+- Supports Android devices/emulators and iOS simulators.
 - Useful for login/logout reset flows and deterministic test setup.
 
 ## Settings helpers
@@ -102,7 +102,7 @@ agent-device settings location on
 agent-device settings location off
 ```
 
-- iOS `settings` support is simulator-only in v1.
+- iOS `settings` support is simulator-only.
 - Android `settings` support works on emulators and devices.
 
 ## Media and logs
@@ -115,7 +115,7 @@ agent-device record start session.mp4   # Start recording to explicit path
 agent-device record stop                # Stop active recording
 ```
 
-- iOS `record` is simulator-only in v1.
+- iOS `record` is simulator-only.
 
 ## iOS device prerequisites
 
diff --git a/website/docs/docs/introduction.md b/website/docs/docs/introduction.md
index dc9ab7bc9..fb2222434 100644
--- a/website/docs/docs/introduction.md
+++ b/website/docs/docs/introduction.md
@@ -21,7 +21,7 @@ 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 in v1: `alert`, `pinch`, `record`, `reinstall`, `apps`, `settings`, and deep-link open (`open <url>`).
+- iOS simulator-only: `alert`, `pinch`, `record`, `reinstall`, `apps`, `settings`, and deep-link open (`open <url>`).
 - Android emulator + Android device support remains unchanged.
 
 ## Architecture (high level)
diff --git a/website/docs/docs/quick-start.md b/website/docs/docs/quick-start.md
index 76ef190bf..d30fb5476 100644
--- a/website/docs/docs/quick-start.md
+++ b/website/docs/docs/quick-start.md
@@ -76,7 +76,7 @@ agent-device settings airplane on
 agent-device settings location off
 ```
 
-Note: iOS `settings` commands are simulator-only in v1.
+Note: iOS `settings` commands are simulator-only.
 
 ## JSON output
 
diff --git a/website/docs/docs/sessions.md b/website/docs/docs/sessions.md
index 04ffb0de1..16898de98 100644
--- a/website/docs/docs/sessions.md
+++ b/website/docs/docs/sessions.md
@@ -24,7 +24,7 @@ agent-device close --session my-session
 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 in v1.
+- `open <url>` in iOS sessions is simulator-only.
 - Use `--session <name>` to run multiple sessions in parallel.
 
 For replay scripts and deterministic E2E guidance, see [Replay & E2E (Experimental)](/docs/replay-e2e).

From ce71512638267a6b9552ae8d4b9977c52faaf1e4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Sat, 14 Feb 2026 13:54:40 +0100
Subject: [PATCH 05/13] ios appstate: prefer xctest before ax fallback

---
 README.md                              |   2 +-
 src/daemon/__tests__/app-state.test.ts | 101 +++++++++++++++++++++++++
 src/daemon/app-state.ts                |  62 +++++++--------
 3 files changed, 131 insertions(+), 34 deletions(-)
 create mode 100644 src/daemon/__tests__/app-state.test.ts

diff --git a/README.md b/README.md
index 898b478f1..a48fec848 100644
--- a/README.md
+++ b/README.md
@@ -215,7 +215,7 @@ 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 falls back to a snapshot-based guess (`xctest` on devices; AX-first on simulators with XCTest fallback).
+- `appstate` shows the foreground app/activity (Android). On iOS it uses the current session app when available, otherwise it uses a snapshot-based guess (XCTest first; AX fallback on simulators).
 - `apps --metadata` returns app list with minimal metadata.
 
 ## Debug
diff --git a/src/daemon/__tests__/app-state.test.ts b/src/daemon/__tests__/app-state.test.ts
new file mode 100644
index 000000000..fdceb3872
--- /dev/null
+++ b/src/daemon/__tests__/app-state.test.ts
@@ -0,0 +1,101 @@
+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 falls back to ax on simulator when xctest is empty', async () => {
+  const backends: string[] = [];
+  const fakeDispatch: typeof dispatchCommand = async (_device, _command, _positionals, _outPath, context) => {
+    const backend = context?.snapshotBackend ?? 'unknown';
+    backends.push(backend);
+    if (backend === 'xctest') {
+      return { nodes: [] };
+    }
+    return {
+      nodes: [
+        {
+          type: 'AXApplication',
+          label: 'Calculator',
+          identifier: 'com.apple.calculator',
+        },
+      ],
+    };
+  };
+
+  const result = await resolveIosAppStateFromSnapshots(
+    iosSimulator,
+    '/tmp/daemon.log',
+    undefined,
+    {} as CommandFlags,
+    fakeDispatch,
+  );
+
+  assert.deepEqual(backends, ['xctest', 'ax']);
+  assert.equal(result.source, 'snapshot-ax');
+  assert.equal(result.appBundleId, 'com.apple.calculator');
+});
+
+test('appstate does not try ax on iOS device', async () => {
+  const backends: string[] = [];
+  const fakeDispatch: typeof dispatchCommand = async (_device, _command, _positionals, _outPath, context) => {
+    backends.push(context?.snapshotBackend ?? 'unknown');
+    return { nodes: [] };
+  };
+
+  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, 'unknown');
+});
diff --git a/src/daemon/app-state.ts b/src/daemon/app-state.ts
index 2afa8dcb7..694526068 100644
--- a/src/daemon/app-state.ts
+++ b/src/daemon/app-state.ts
@@ -9,30 +9,39 @@ export async function resolveIosAppStateFromSnapshots(
   logPath: string,
   traceLogPath: string | undefined,
   flags: CommandFlags | undefined,
+  dispatch: typeof dispatchCommand = dispatchCommand,
 ): Promise<{ appName: string; appBundleId?: string; source: 'snapshot-ax' | 'snapshot-xctest' }> {
+  const xctestResult = await dispatch(device, 'snapshot', [], flags?.out, {
+    ...contextFromFlags(
+      logPath,
+      {
+        ...flags,
+        snapshotDepth: 1,
+        snapshotCompact: true,
+        snapshotBackend: 'xctest',
+      },
+      undefined,
+      traceLogPath,
+    ),
+  });
+  const xcNode = extractAppNodeFromSnapshot(xctestResult as { nodes?: RawSnapshotNode[] });
+  if (xcNode?.appName || xcNode?.appBundleId) {
+    return {
+      appName: xcNode.appName ?? xcNode.appBundleId ?? 'unknown',
+      appBundleId: xcNode.appBundleId,
+      source: 'snapshot-xctest',
+    };
+  }
+
   if (device.kind === 'device') {
-    const xctestResult = await dispatchCommand(device, 'snapshot', [], flags?.out, {
-      ...contextFromFlags(
-        logPath,
-        {
-          ...flags,
-          snapshotDepth: 1,
-          snapshotCompact: true,
-          snapshotBackend: 'xctest',
-        },
-        undefined,
-        traceLogPath,
-      ),
-    });
-    const xcNode = extractAppNodeFromSnapshot(xctestResult as { nodes?: RawSnapshotNode[] });
     return {
-      appName: xcNode?.appName ?? xcNode?.appBundleId ?? 'unknown',
-      appBundleId: xcNode?.appBundleId,
+      appName: 'unknown',
+      appBundleId: undefined,
       source: 'snapshot-xctest',
     };
   }
 
-  const axResult = await dispatchCommand(device, 'snapshot', [], flags?.out, {
+  const axResult = await dispatch(device, 'snapshot', [], flags?.out, {
     ...contextFromFlags(
       logPath,
       {
@@ -53,23 +62,10 @@ export async function resolveIosAppStateFromSnapshots(
       source: 'snapshot-ax',
     };
   }
-  const xctestResult = await dispatchCommand(device, 'snapshot', [], flags?.out, {
-    ...contextFromFlags(
-      logPath,
-      {
-        ...flags,
-        snapshotDepth: 1,
-        snapshotCompact: true,
-        snapshotBackend: 'xctest',
-      },
-      undefined,
-      traceLogPath,
-    ),
-  });
-  const xcNode = extractAppNodeFromSnapshot(xctestResult as { nodes?: RawSnapshotNode[] });
+
   return {
-    appName: xcNode?.appName ?? xcNode?.appBundleId ?? 'unknown',
-    appBundleId: xcNode?.appBundleId,
+    appName: 'unknown',
+    appBundleId: undefined,
     source: 'snapshot-xctest',
   };
 }

From 5478d3934c866ce2a9c6f84f38e9ffec060d4480 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Sat, 14 Feb 2026 13:56:51 +0100
Subject: [PATCH 06/13] docs: clarify ios runner derived path override behavior

---
 README.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/README.md b/README.md
index a48fec848..4ca6ba314 100644
--- a/README.md
+++ b/README.md
@@ -272,6 +272,7 @@ Environment selectors:
 - `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.
 
 Test screenshots are written to:
 - `test/screenshots/android-settings.png`

From fec1c464e005b301218e19163f303d0cfa4ebfe1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Sat, 14 Feb 2026 14:00:10 +0100
Subject: [PATCH 07/13] ios: harden runner polling and appstate fallback

---
 src/daemon/__tests__/app-state.test.ts | 53 ++++++++++++++++++++++++++
 src/daemon/app-state.ts                | 53 ++++++++++++++++----------
 src/platforms/ios/runner-client.ts     | 25 ++++++++++--
 3 files changed, 108 insertions(+), 23 deletions(-)

diff --git a/src/daemon/__tests__/app-state.test.ts b/src/daemon/__tests__/app-state.test.ts
index fdceb3872..fcd991b16 100644
--- a/src/daemon/__tests__/app-state.test.ts
+++ b/src/daemon/__tests__/app-state.test.ts
@@ -99,3 +99,56 @@ test('appstate does not try ax on iOS device', async () => {
   assert.equal(result.source, 'snapshot-xctest');
   assert.equal(result.appName, 'unknown');
 });
+
+test('appstate falls back to ax 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);
+    if (backend === 'xctest') {
+      throw new Error('xctest failed');
+    }
+    return {
+      nodes: [
+        {
+          type: 'AXApplication',
+          label: 'Photos',
+          identifier: 'com.apple.mobileslideshow',
+        },
+      ],
+    };
+  };
+
+  const result = await resolveIosAppStateFromSnapshots(
+    iosSimulator,
+    '/tmp/daemon.log',
+    undefined,
+    {} as CommandFlags,
+    fakeDispatch,
+  );
+
+  assert.deepEqual(backends, ['xctest', 'ax']);
+  assert.equal(result.source, 'snapshot-ax');
+  assert.equal(result.appBundleId, 'com.apple.mobileslideshow');
+});
+
+test('appstate surfaces xctest failure on simulator when ax fallback fails', async () => {
+  const fakeDispatch: typeof dispatchCommand = async (_device, _command, _positionals, _outPath, context) => {
+    const backend = context?.snapshotBackend ?? 'unknown';
+    if (backend === 'xctest') {
+      throw new Error('xctest failed');
+    }
+    return { nodes: [] };
+  };
+
+  await assert.rejects(
+    resolveIosAppStateFromSnapshots(
+      iosSimulator,
+      '/tmp/daemon.log',
+      undefined,
+      {} as CommandFlags,
+      fakeDispatch,
+    ),
+    /xctest failed/,
+  );
+});
diff --git a/src/daemon/app-state.ts b/src/daemon/app-state.ts
index 694526068..298829d66 100644
--- a/src/daemon/app-state.ts
+++ b/src/daemon/app-state.ts
@@ -11,26 +11,35 @@ export async function resolveIosAppStateFromSnapshots(
   flags: CommandFlags | undefined,
   dispatch: typeof dispatchCommand = dispatchCommand,
 ): Promise<{ appName: string; appBundleId?: string; source: 'snapshot-ax' | 'snapshot-xctest' }> {
-  const xctestResult = await dispatch(device, 'snapshot', [], flags?.out, {
-    ...contextFromFlags(
-      logPath,
-      {
-        ...flags,
-        snapshotDepth: 1,
-        snapshotCompact: true,
-        snapshotBackend: 'xctest',
-      },
-      undefined,
-      traceLogPath,
-    ),
-  });
-  const xcNode = extractAppNodeFromSnapshot(xctestResult as { nodes?: RawSnapshotNode[] });
-  if (xcNode?.appName || xcNode?.appBundleId) {
-    return {
-      appName: xcNode.appName ?? xcNode.appBundleId ?? 'unknown',
-      appBundleId: xcNode.appBundleId,
-      source: 'snapshot-xctest',
-    };
+  let xctestError: unknown = undefined;
+  let xcNode: { appName?: string; appBundleId?: string } | null = null;
+  try {
+    const xctestResult = await dispatch(device, 'snapshot', [], flags?.out, {
+      ...contextFromFlags(
+        logPath,
+        {
+          ...flags,
+          snapshotDepth: 1,
+          snapshotCompact: true,
+          snapshotBackend: 'xctest',
+        },
+        undefined,
+        traceLogPath,
+      ),
+    });
+    xcNode = extractAppNodeFromSnapshot(xctestResult as { nodes?: RawSnapshotNode[] });
+    if (xcNode?.appName || xcNode?.appBundleId) {
+      return {
+        appName: xcNode.appName ?? xcNode.appBundleId ?? 'unknown',
+        appBundleId: xcNode.appBundleId,
+        source: 'snapshot-xctest',
+      };
+    }
+  } catch (error) {
+    xctestError = error;
+    if (device.kind === 'device') {
+      throw error;
+    }
   }
 
   if (device.kind === 'device') {
@@ -63,6 +72,10 @@ export async function resolveIosAppStateFromSnapshots(
     };
   }
 
+  if (xctestError) {
+    throw xctestError;
+  }
+
   return {
     appName: 'unknown',
     appBundleId: undefined,
diff --git a/src/platforms/ios/runner-client.ts b/src/platforms/ios/runner-client.ts
index 6edb59c3c..80615f492 100644
--- a/src/platforms/ios/runner-client.ts
+++ b/src/platforms/ios/runner-client.ts
@@ -521,17 +521,22 @@ async function waitForRunner(
   logPath?: string,
   timeoutMs: number = RUNNER_STARTUP_TIMEOUT_MS,
 ): Promise<Response> {
-  const endpoints = await resolveRunnerCommandEndpoints(device, port);
+  let endpoints = await resolveRunnerCommandEndpoints(device, port);
+  let nextEndpointRefreshAt = Date.now() + 1_000;
   const start = Date.now();
   let lastError: unknown = null;
   while (Date.now() - start < timeoutMs) {
+    if (device.kind === 'device' && Date.now() >= nextEndpointRefreshAt) {
+      endpoints = await resolveRunnerCommandEndpoints(device, port);
+      nextEndpointRefreshAt = Date.now() + 1_000;
+    }
     for (const endpoint of endpoints) {
       try {
-        const response = await fetch(endpoint, {
+        const response = await fetchWithTimeout(endpoint, {
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
           body: JSON.stringify(command),
-        });
+        }, 1_000);
         return response;
       } catch (err) {
         lastError = err;
@@ -573,6 +578,20 @@ async function resolveRunnerCommandEndpoints(
   return endpoints;
 }
 
+async function fetchWithTimeout(
+  url: string,
+  init: RequestInit,
+  timeoutMs: number,
+): Promise<Response> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetch(url, { ...init, signal: controller.signal });
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
 async function resolveDeviceTunnelIp(deviceId: string): Promise<string | null> {
   const jsonPath = path.join(
     os.tmpdir(),

From 4c658905c06dbc997031e3bafd6cd651f3629968 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Sat, 14 Feb 2026 14:03:03 +0100
Subject: [PATCH 08/13] ios: remove automatic AX fallback paths

---
 README.md                              |  6 +-
 skills/agent-device/SKILL.md           |  4 +-
 src/core/dispatch.ts                   | 10 ++-
 src/daemon/__tests__/app-state.test.ts | 92 +++++++++++---------------
 src/daemon/app-state.ts                | 70 ++++++--------------
 website/docs/docs/introduction.md      |  2 +-
 website/docs/docs/snapshots.md         |  2 +-
 7 files changed, 68 insertions(+), 118 deletions(-)

diff --git a/README.md b/README.md
index 4ca6ba314..a74a76469 100644
--- a/README.md
+++ b/README.md
@@ -101,7 +101,7 @@ agent-device swipe 540 1500 540 500 120 --count 8 --pause-ms 30 --pattern ping-p
 Notes:
 - Default backend is `xctest` on iOS simulators and iOS devices.
 - Scope snapshots with `-s "<label>"` or `-s @ref`.
-- If XCTest returns 0 nodes (e.g., foreground app changed), agent-device falls back to AX on simulators when available.
+- If XCTest returns 0 nodes (e.g., foreground app changed), agent-device fails explicitly.
 - `ax` backend is simulator-only.
 
 Flags:
@@ -215,7 +215,7 @@ 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 uses a snapshot-based guess (XCTest first; AX fallback on simulators).
+- `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.
 
 ## Debug
@@ -223,7 +223,7 @@ App state:
 - `agent-device trace start`
 - `agent-device trace stop ./trace.log`
 - The trace log includes snapshot logs and XCTest runner logs for the session.
-- Built-in retries cover transient runner connection failures, AX snapshot hiccups, and Android UI dumps.
+- 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>"`.
 
 Boot diagnostics:
diff --git a/skills/agent-device/SKILL.md b/skills/agent-device/SKILL.md
index 55fcc3ad4..11bdc52f6 100644
--- a/skills/agent-device/SKILL.md
+++ b/skills/agent-device/SKILL.md
@@ -67,7 +67,7 @@ agent-device snapshot --backend xctest # default: XCTest snapshot (fast, complet
 agent-device snapshot --backend ax     # macOS Accessibility tree (fast, needs permissions, less fidelity, optional)
 ```
 
-XCTest is the default: fast and complete and does not require permissions. Use it in most cases and only fall back to AX when something breaks.
+XCTest is the default: fast and complete and does not require permissions. Use AX only for manual diagnostics, and prefer XCTest for normal automation flows.
 
 ### Find (semantic)
 
@@ -180,7 +180,7 @@ agent-device apps --platform android --user-installed
 - Use selectors for deterministic replay artifacts and assertions (e.g. in e2e test workflows).
 - Prefer `snapshot -i` to reduce output size.
 - On iOS, `xctest` is the default and does not require Accessibility permission.
-- If XCTest returns 0 nodes (foreground app changed), agent-device falls back to AX on simulators when available.
+- If XCTest returns 0 nodes (foreground app changed), treat it as an explicit failure and retry the flow/app state.
 - `open <app|url>` can be used within an existing session to switch apps or open deep links.
 - `open <app>` updates session app bundle context; URL opens do not set an app bundle id.
 - Use `open <app> --relaunch` during React Native/Fast Refresh debugging when you need a fresh app process without ending the session.
diff --git a/src/core/dispatch.ts b/src/core/dispatch.ts
index 28e1118b6..6adbadd9f 100644
--- a/src/core/dispatch.ts
+++ b/src/core/dispatch.ts
@@ -309,12 +309,10 @@ export async function dispatchCommand(
         )) as { nodes?: RawSnapshotNode[]; truncated?: boolean };
         const nodes = result.nodes ?? [];
         if (nodes.length === 0 && device.kind === 'simulator') {
-          try {
-            const ax = await snapshotAx(device, { traceLogPath: context?.traceLogPath });
-            return { nodes: ax.nodes ?? [], truncated: false, backend: 'ax' };
-          } catch {
-            // keep the empty XCTest snapshot if AX is unavailable
-          }
+          throw new AppError(
+            'COMMAND_FAILED',
+            'XCTest snapshot returned 0 nodes on iOS simulator. You can try --backend ax for diagnostics, but AX snapshots are not recommended.',
+          );
         }
         return { nodes, truncated: result.truncated ?? false, backend: 'xctest' };
       }
diff --git a/src/daemon/__tests__/app-state.test.ts b/src/daemon/__tests__/app-state.test.ts
index fcd991b16..85d89ac97 100644
--- a/src/daemon/__tests__/app-state.test.ts
+++ b/src/daemon/__tests__/app-state.test.ts
@@ -48,107 +48,91 @@ test('appstate uses xctest first on iOS simulator', async () => {
   assert.equal(result.appBundleId, 'com.apple.Preferences');
 });
 
-test('appstate falls back to ax on simulator when xctest is empty', async () => {
+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) => {
-    const backend = context?.snapshotBackend ?? 'unknown';
-    backends.push(backend);
-    if (backend === 'xctest') {
-      return { nodes: [] };
-    }
+    backends.push(context?.snapshotBackend ?? 'unknown');
     return {
       nodes: [
         {
-          type: 'AXApplication',
-          label: 'Calculator',
-          identifier: 'com.apple.calculator',
+          type: 'XCUIElementTypeApplication',
+          label: 'Settings',
+          identifier: 'com.apple.Preferences',
         },
       ],
     };
   };
 
   const result = await resolveIosAppStateFromSnapshots(
-    iosSimulator,
+    iosDevice,
     '/tmp/daemon.log',
     undefined,
     {} as CommandFlags,
     fakeDispatch,
   );
 
-  assert.deepEqual(backends, ['xctest', 'ax']);
-  assert.equal(result.source, 'snapshot-ax');
-  assert.equal(result.appBundleId, 'com.apple.calculator');
+  assert.deepEqual(backends, ['xctest']);
+  assert.equal(result.source, 'snapshot-xctest');
+  assert.equal(result.appName, 'Settings');
 });
 
-test('appstate does not try ax on iOS device', async () => {
+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: [] };
   };
 
-  const result = await resolveIosAppStateFromSnapshots(
-    iosDevice,
-    '/tmp/daemon.log',
-    undefined,
-    {} as CommandFlags,
-    fakeDispatch,
+  await assert.rejects(
+    resolveIosAppStateFromSnapshots(
+      iosSimulator,
+      '/tmp/daemon.log',
+      undefined,
+      {} as CommandFlags,
+      fakeDispatch,
+    ),
+    /not recommended/,
   );
-
   assert.deepEqual(backends, ['xctest']);
-  assert.equal(result.source, 'snapshot-xctest');
-  assert.equal(result.appName, 'unknown');
 });
 
-test('appstate falls back to ax on simulator when xctest throws', async () => {
+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);
-    if (backend === 'xctest') {
-      throw new Error('xctest failed');
-    }
-    return {
-      nodes: [
-        {
-          type: 'AXApplication',
-          label: 'Photos',
-          identifier: 'com.apple.mobileslideshow',
-        },
-      ],
-    };
+    throw new Error('xctest failed');
   };
 
-  const result = await resolveIosAppStateFromSnapshots(
-    iosSimulator,
-    '/tmp/daemon.log',
-    undefined,
-    {} as CommandFlags,
-    fakeDispatch,
+  await assert.rejects(
+    resolveIosAppStateFromSnapshots(
+      iosSimulator,
+      '/tmp/daemon.log',
+      undefined,
+      {} as CommandFlags,
+      fakeDispatch,
+    ),
+    /not recommended/,
   );
-
-  assert.deepEqual(backends, ['xctest', 'ax']);
-  assert.equal(result.source, 'snapshot-ax');
-  assert.equal(result.appBundleId, 'com.apple.mobileslideshow');
+  assert.deepEqual(backends, ['xctest']);
 });
 
-test('appstate surfaces xctest failure on simulator when ax fallback fails', async () => {
+test('appstate fails on device when xctest throws', async () => {
+  const backends: string[] = [];
   const fakeDispatch: typeof dispatchCommand = async (_device, _command, _positionals, _outPath, context) => {
-    const backend = context?.snapshotBackend ?? 'unknown';
-    if (backend === 'xctest') {
-      throw new Error('xctest failed');
-    }
-    return { nodes: [] };
+    backends.push(context?.snapshotBackend ?? 'unknown');
+    throw new Error('xctest failed');
   };
 
   await assert.rejects(
     resolveIosAppStateFromSnapshots(
-      iosSimulator,
+      iosDevice,
       '/tmp/daemon.log',
       undefined,
       {} as CommandFlags,
       fakeDispatch,
     ),
-    /xctest failed/,
+    /not recommended/,
   );
+  assert.deepEqual(backends, ['xctest']);
 });
diff --git a/src/daemon/app-state.ts b/src/daemon/app-state.ts
index 298829d66..098674701 100644
--- a/src/daemon/app-state.ts
+++ b/src/daemon/app-state.ts
@@ -1,6 +1,7 @@
 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';
 
@@ -10,11 +11,10 @@ export async function resolveIosAppStateFromSnapshots(
   traceLogPath: string | undefined,
   flags: CommandFlags | undefined,
   dispatch: typeof dispatchCommand = dispatchCommand,
-): Promise<{ appName: string; appBundleId?: string; source: 'snapshot-ax' | 'snapshot-xctest' }> {
-  let xctestError: unknown = undefined;
-  let xcNode: { appName?: string; appBundleId?: string } | null = null;
+): Promise<{ appName: string; appBundleId?: string; source: 'snapshot-xctest' }> {
+  let xctestResult: { nodes?: RawSnapshotNode[] } | undefined;
   try {
-    const xctestResult = await dispatch(device, 'snapshot', [], flags?.out, {
+    xctestResult = (await dispatch(device, 'snapshot', [], flags?.out, {
       ...contextFromFlags(
         logPath,
         {
@@ -26,61 +26,29 @@ export async function resolveIosAppStateFromSnapshots(
         undefined,
         traceLogPath,
       ),
-    });
-    xcNode = extractAppNodeFromSnapshot(xctestResult as { nodes?: RawSnapshotNode[] });
-    if (xcNode?.appName || xcNode?.appBundleId) {
-      return {
-        appName: xcNode.appName ?? xcNode.appBundleId ?? 'unknown',
-        appBundleId: xcNode.appBundleId,
-        source: 'snapshot-xctest',
-      };
-    }
+    })) as { nodes?: RawSnapshotNode[] };
   } catch (error) {
-    xctestError = error;
-    if (device.kind === 'device') {
-      throw 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 },
+    );
   }
 
-  if (device.kind === 'device') {
+  const xcNode = extractAppNodeFromSnapshot(xctestResult);
+  if (xcNode?.appName || xcNode?.appBundleId) {
     return {
-      appName: 'unknown',
-      appBundleId: undefined,
+      appName: xcNode.appName ?? xcNode.appBundleId ?? 'unknown',
+      appBundleId: xcNode.appBundleId,
       source: 'snapshot-xctest',
     };
   }
 
-  const axResult = await dispatch(device, 'snapshot', [], flags?.out, {
-    ...contextFromFlags(
-      logPath,
-      {
-        ...flags,
-        snapshotDepth: 1,
-        snapshotCompact: true,
-        snapshotBackend: 'ax',
-      },
-      undefined,
-      traceLogPath,
-    ),
-  });
-  const axNode = extractAppNodeFromSnapshot(axResult as { nodes?: RawSnapshotNode[] });
-  if (axNode?.appName || axNode?.appBundleId) {
-    return {
-      appName: axNode.appName ?? axNode.appBundleId ?? 'unknown',
-      appBundleId: axNode.appBundleId,
-      source: 'snapshot-ax',
-    };
-  }
-
-  if (xctestError) {
-    throw xctestError;
-  }
-
-  return {
-    appName: 'unknown',
-    appBundleId: undefined,
-    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(
diff --git a/website/docs/docs/introduction.md b/website/docs/docs/introduction.md
index fb2222434..119e40f1b 100644
--- a/website/docs/docs/introduction.md
+++ b/website/docs/docs/introduction.md
@@ -28,7 +28,7 @@ If you know `agent-browser`, this is the mobile-native counterpart for iOS/Andro
 
 1. CLI sends requests to the daemon.
 2. The daemon manages sessions and dispatches to platform drivers.
-3. iOS uses XCTest runner for snapshots and input on simulators and physical devices; AX is optional simulator fallback.
+3. iOS uses XCTest runner for snapshots and input on simulators and physical devices.
 4. Android uses ADB-based tooling.
 
 ## Example
diff --git a/website/docs/docs/snapshots.md b/website/docs/docs/snapshots.md
index afd2c7ca8..dc861ad18 100644
--- a/website/docs/docs/snapshots.md
+++ b/website/docs/docs/snapshots.md
@@ -22,7 +22,7 @@ agent-device snapshot -i -c -d 5         # Combine options
 | `-d <depth>` | Limit tree depth          |
 | `-s <scope>` | Scope to label/identifier |
 
-Note: If XCTest returns 0 nodes (foreground app changed), agent-device falls back to AX on iOS simulators when available.
+Note: If XCTest returns 0 nodes (foreground app changed), agent-device fails explicitly.
 
 ## Example output:
 

From 4514a5a50fca3bfce0e48e0c738aecec9d6a6ddd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Sat, 14 Feb 2026 14:04:23 +0100
Subject: [PATCH 09/13] docs: clarify no automatic AX fallback

---
 skills/agent-device/SKILL.md                    | 4 ++--
 skills/agent-device/references/permissions.md   | 2 +-
 skills/agent-device/references/snapshot-refs.md | 1 +
 website/docs/docs/commands.md                   | 1 +
 website/docs/docs/snapshots.md                  | 1 +
 5 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/skills/agent-device/SKILL.md b/skills/agent-device/SKILL.md
index 11bdc52f6..bac99beb1 100644
--- a/skills/agent-device/SKILL.md
+++ b/skills/agent-device/SKILL.md
@@ -64,10 +64,10 @@ agent-device snapshot -d 3             # Limit depth
 agent-device snapshot -s "Camera"      # Scope to label/identifier
 agent-device snapshot --raw            # Raw node output
 agent-device snapshot --backend xctest # default: XCTest snapshot (fast, complete, no permissions)
-agent-device snapshot --backend ax     # macOS Accessibility tree (fast, needs permissions, less fidelity, optional)
+agent-device snapshot --backend ax     # macOS Accessibility tree (manual diagnostics only; no automatic fallback)
 ```
 
-XCTest is the default: fast and complete and does not require permissions. Use AX only for manual diagnostics, and prefer XCTest for normal automation flows.
+XCTest is the default: fast and complete and does not require permissions. Use AX only for manual diagnostics, and prefer XCTest for normal automation flows. agent-device does not automatically fall back to AX.
 
 ### Find (semantic)
 
diff --git a/skills/agent-device/references/permissions.md b/skills/agent-device/references/permissions.md
index dea9fd025..4fbb7ea42 100644
--- a/skills/agent-device/references/permissions.md
+++ b/skills/agent-device/references/permissions.md
@@ -2,7 +2,7 @@
 
 ## iOS AX snapshot
 
-AX snapshot is an alternative to XCTest for when it fails (which shouldn't happen usually); it uses macOS Accessibility APIs and requires permission:
+AX snapshot is available for manual diagnostics when needed; it is not used as an automatic fallback. It uses macOS Accessibility APIs and requires permission:
 
 System Settings > Privacy & Security > Accessibility
 
diff --git a/skills/agent-device/references/snapshot-refs.md b/skills/agent-device/references/snapshot-refs.md
index 2ff33dbca..360a53a3a 100644
--- a/skills/agent-device/references/snapshot-refs.md
+++ b/skills/agent-device/references/snapshot-refs.md
@@ -56,6 +56,7 @@ agent-device snapshot -i -s @e3
 - AX returns Simulator window: restart Simulator and re-run.
 - AX empty: verify Accessibility permission or use `--backend xctest` (XCTest is more complete).
 - AX backend is simulator-only; use `--backend xctest` on iOS devices.
+- agent-device does not automatically fall back to AX when XCTest fails.
 
 ## Replay note
 
diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md
index 000942822..8de962ba3 100644
--- a/website/docs/docs/commands.md
+++ b/website/docs/docs/commands.md
@@ -35,6 +35,7 @@ agent-device get attrs @e1
 
 - `--backend xctest` works on iOS simulators and iOS devices.
 - `--backend ax` is simulator-only.
+- agent-device does not automatically switch from XCTest to AX; choose AX explicitly only for diagnostics.
 
 ## Interactions
 
diff --git a/website/docs/docs/snapshots.md b/website/docs/docs/snapshots.md
index dc861ad18..31bd53603 100644
--- a/website/docs/docs/snapshots.md
+++ b/website/docs/docs/snapshots.md
@@ -23,6 +23,7 @@ agent-device snapshot -i -c -d 5         # Combine options
 | `-s <scope>` | Scope to label/identifier |
 
 Note: If XCTest returns 0 nodes (foreground app changed), agent-device fails explicitly.
+It does not automatically switch to AX.
 
 ## Example output:
 

From 55ce7c5931b16ef510286c07ea63c6b35903af23 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Sat, 14 Feb 2026 14:05:58 +0100
Subject: [PATCH 10/13] ios: replace ad-hoc runner poll sleep with retry policy

---
 src/platforms/ios/runner-client.ts | 64 ++++++++++++++++++++----------
 1 file changed, 44 insertions(+), 20 deletions(-)

diff --git a/src/platforms/ios/runner-client.ts b/src/platforms/ios/runner-client.ts
index 80615f492..a55fb8dc9 100644
--- a/src/platforms/ios/runner-client.ts
+++ b/src/platforms/ios/runner-client.ts
@@ -4,7 +4,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { AppError } from '../../utils/errors.ts';
 import { runCmd, runCmdStreaming, runCmdBackground, type ExecResult, type ExecBackgroundResult } from '../../utils/exec.ts';
-import { withRetry } from '../../utils/retry.ts';
+import { Deadline, retryWithPolicy, withRetry } from '../../utils/retry.ts';
 import type { DeviceInfo } from '../../utils/device.ts';
 import net from 'node:net';
 import { bootFailureHint, classifyBootFailure } from '../boot-diagnostics.ts';
@@ -522,28 +522,52 @@ async function waitForRunner(
   timeoutMs: number = RUNNER_STARTUP_TIMEOUT_MS,
 ): Promise<Response> {
   let endpoints = await resolveRunnerCommandEndpoints(device, port);
-  let nextEndpointRefreshAt = Date.now() + 1_000;
-  const start = Date.now();
   let lastError: unknown = null;
-  while (Date.now() - start < timeoutMs) {
-    if (device.kind === 'device' && Date.now() >= nextEndpointRefreshAt) {
-      endpoints = await resolveRunnerCommandEndpoints(device, port);
-      nextEndpointRefreshAt = Date.now() + 1_000;
-    }
-    for (const endpoint of endpoints) {
-      try {
-        const response = await fetchWithTimeout(endpoint, {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify(command),
-        }, 1_000);
-        return response;
-      } catch (err) {
-        lastError = err;
-      }
+  const deadline = Deadline.fromTimeoutMs(timeoutMs);
+  const maxAttempts = Math.max(1, Math.ceil(timeoutMs / 250));
+  try {
+    return await retryWithPolicy(
+      async () => {
+        if (device.kind === 'device') {
+          endpoints = await resolveRunnerCommandEndpoints(device, port);
+        }
+        for (const endpoint of endpoints) {
+          try {
+            const response = await fetchWithTimeout(
+              endpoint,
+              {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(command),
+              },
+              1_000,
+            );
+            return response;
+          } catch (err) {
+            lastError = err;
+          }
+        }
+        throw new AppError('COMMAND_FAILED', 'Runner endpoint probe failed', {
+          port,
+          endpoints,
+          lastError: lastError ? String(lastError) : undefined,
+        });
+      },
+      {
+        maxAttempts,
+        baseDelayMs: 100,
+        maxDelayMs: 500,
+        jitter: 0.2,
+        shouldRetry: () => true,
+      },
+      { deadline, phase: 'ios_runner_connect' },
+    );
+  } catch (error) {
+    if (!lastError) {
+      lastError = error;
     }
-    await new Promise((resolve) => setTimeout(resolve, 100));
   }
+
   if (device.kind === 'simulator') {
     const simResponse = await postCommandViaSimulator(device.id, port, command);
     return new Response(simResponse.body, { status: simResponse.status });

From 41e7ad60b013a890c3a359ba281179ae592ac719 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Sat, 14 Feb 2026 14:20:49 +0100
Subject: [PATCH 11/13] Harden iOS runner timeouts and cleanup safety

---
 README.md                                     |   1 +
 .../ios/__tests__/runner-client.test.ts       |  27 ++++
 src/platforms/ios/runner-client.ts            | 150 ++++++++++++++----
 3 files changed, 146 insertions(+), 32 deletions(-)

diff --git a/README.md b/README.md
index a74a76469..bd4d8e6d8 100644
--- a/README.md
+++ b/README.md
@@ -273,6 +273,7 @@ Environment selectors:
 - `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_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:
 - `test/screenshots/android-settings.png`
diff --git a/src/platforms/ios/__tests__/runner-client.test.ts b/src/platforms/ios/__tests__/runner-client.test.ts
index 6d085b57d..b4d72d6ee 100644
--- a/src/platforms/ios/__tests__/runner-client.test.ts
+++ b/src/platforms/ios/__tests__/runner-client.test.ts
@@ -2,6 +2,7 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 import type { DeviceInfo } from '../../../utils/device.ts';
 import {
+  assertSafeDerivedCleanup,
   resolveRunnerBuildDestination,
   resolveRunnerDestination,
   resolveRunnerMaxConcurrentDestinationsFlag,
@@ -84,3 +85,29 @@ test('resolveRunnerSigningBuildSettings applies optional overrides when provided
     'PROVISIONING_PROFILE_SPECIFIER=My Profile',
   ]);
 });
+
+test('assertSafeDerivedCleanup allows cleaning when no override is set', () => {
+  assert.doesNotThrow(() => {
+    assertSafeDerivedCleanup('/tmp/derived', {});
+  });
+});
+
+test('assertSafeDerivedCleanup rejects cleaning override path by default', () => {
+  assert.throws(
+    () => {
+      assertSafeDerivedCleanup('/tmp/custom', {
+        AGENT_DEVICE_IOS_RUNNER_DERIVED_PATH: '/tmp/custom',
+      });
+    },
+    /Refusing to clean AGENT_DEVICE_IOS_RUNNER_DERIVED_PATH automatically/,
+  );
+});
+
+test('assertSafeDerivedCleanup allows cleaning override path with explicit opt-in', () => {
+  assert.doesNotThrow(() => {
+    assertSafeDerivedCleanup('/tmp/custom', {
+      AGENT_DEVICE_IOS_RUNNER_DERIVED_PATH: '/tmp/custom',
+      AGENT_DEVICE_IOS_ALLOW_OVERRIDE_DERIVED_CLEAN: '1',
+    });
+  });
+});
diff --git a/src/platforms/ios/runner-client.ts b/src/platforms/ios/runner-client.ts
index a55fb8dc9..e314dfe79 100644
--- a/src/platforms/ios/runner-client.ts
+++ b/src/platforms/ios/runner-client.ts
@@ -4,7 +4,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { AppError } from '../../utils/errors.ts';
 import { runCmd, runCmdStreaming, runCmdBackground, type ExecResult, type ExecBackgroundResult } from '../../utils/exec.ts';
-import { Deadline, retryWithPolicy, withRetry } from '../../utils/retry.ts';
+import { Deadline, isEnvTruthy, retryWithPolicy, withRetry } from '../../utils/retry.ts';
 import type { DeviceInfo } from '../../utils/device.ts';
 import net from 'node:net';
 import { bootFailureHint, classifyBootFailure } from '../boot-diagnostics.ts';
@@ -65,8 +65,34 @@ const RUNNER_COMMAND_TIMEOUT_MS = resolveTimeoutMs(
   15_000,
   1_000,
 );
+const RUNNER_CONNECT_ATTEMPT_INTERVAL_MS = resolveTimeoutMs(
+  process.env.AGENT_DEVICE_RUNNER_CONNECT_ATTEMPT_INTERVAL_MS,
+  250,
+  50,
+);
+const RUNNER_CONNECT_RETRY_BASE_DELAY_MS = resolveTimeoutMs(
+  process.env.AGENT_DEVICE_RUNNER_CONNECT_RETRY_BASE_DELAY_MS,
+  100,
+  10,
+);
+const RUNNER_CONNECT_RETRY_MAX_DELAY_MS = resolveTimeoutMs(
+  process.env.AGENT_DEVICE_RUNNER_CONNECT_RETRY_MAX_DELAY_MS,
+  500,
+  10,
+);
+const RUNNER_CONNECT_REQUEST_TIMEOUT_MS = resolveTimeoutMs(
+  process.env.AGENT_DEVICE_RUNNER_CONNECT_REQUEST_TIMEOUT_MS,
+  1_000,
+  50,
+);
+const RUNNER_DEVICE_INFO_TIMEOUT_MS = resolveTimeoutMs(
+  process.env.AGENT_DEVICE_IOS_DEVICE_INFO_TIMEOUT_MS,
+  10_000,
+  500,
+);
 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;
@@ -294,6 +320,7 @@ async function ensureXctestrun(
 ): Promise<string> {
   const derived = resolveRunnerDerivedPath(device.kind);
   if (shouldCleanDerived()) {
+    assertSafeDerivedCleanup(derived);
     try {
       fs.rmSync(derived, { recursive: true, force: true });
     } catch {
@@ -364,8 +391,7 @@ function resolveRunnerDerivedPath(kind: DeviceInfo['kind']): string {
   if (override) {
     return path.resolve(override);
   }
-  const base = path.join(os.homedir(), '.agent-device', 'ios-runner');
-  return path.join(base, 'derived', kind);
+  return path.join(RUNNER_DERIVED_ROOT, 'derived', kind);
 }
 
 export function resolveRunnerDestination(device: DeviceInfo): string {
@@ -509,9 +535,54 @@ function isReadOnlyRunnerCommand(command: RunnerCommand['command']): boolean {
 }
 
 function shouldCleanDerived(): boolean {
-  const value = process.env.AGENT_DEVICE_IOS_CLEAN_DERIVED;
-  if (!value) return false;
-  return ['1', 'true', 'yes', 'on'].includes(value.toLowerCase());
+  return isEnvTruthy(process.env.AGENT_DEVICE_IOS_CLEAN_DERIVED);
+}
+
+export function assertSafeDerivedCleanup(
+  derivedPath: string,
+  env: NodeJS.ProcessEnv = process.env,
+): void {
+  const override = env.AGENT_DEVICE_IOS_RUNNER_DERIVED_PATH?.trim();
+  if (!override) {
+    return;
+  }
+  if (isCleanupOverrideAllowed(env)) {
+    return;
+  }
+  throw new AppError(
+    'COMMAND_FAILED',
+    'Refusing to clean AGENT_DEVICE_IOS_RUNNER_DERIVED_PATH automatically',
+    {
+      derivedPath,
+      hint: 'Unset AGENT_DEVICE_IOS_CLEAN_DERIVED, or set AGENT_DEVICE_IOS_ALLOW_OVERRIDE_DERIVED_CLEAN=1 if you trust this path.',
+    },
+  );
+}
+
+function isCleanupOverrideAllowed(env: NodeJS.ProcessEnv = process.env): boolean {
+  return isEnvTruthy(env.AGENT_DEVICE_IOS_ALLOW_OVERRIDE_DERIVED_CLEAN);
+}
+
+function buildRunnerConnectError(params: {
+  port: number;
+  endpoints: string[];
+  logPath?: string;
+  lastError: unknown;
+}): AppError {
+  const { port, endpoints, logPath, lastError } = params;
+  const message = 'Runner did not accept connection';
+  return new AppError('COMMAND_FAILED', message, {
+    port,
+    endpoints,
+    logPath,
+    lastError: lastError ? String(lastError) : undefined,
+    reason: classifyBootFailure({
+      error: lastError,
+      message,
+      context: { platform: 'ios', phase: 'connect' },
+    }),
+    hint: bootFailureHint('IOS_RUNNER_CONNECT_TIMEOUT'),
+  });
 }
 
 async function waitForRunner(
@@ -521,18 +592,31 @@ async function waitForRunner(
   logPath?: string,
   timeoutMs: number = RUNNER_STARTUP_TIMEOUT_MS,
 ): Promise<Response> {
-  let endpoints = await resolveRunnerCommandEndpoints(device, port);
-  let lastError: unknown = null;
   const deadline = Deadline.fromTimeoutMs(timeoutMs);
-  const maxAttempts = Math.max(1, Math.ceil(timeoutMs / 250));
+  let endpoints = await resolveRunnerCommandEndpoints(device, port, deadline.remainingMs());
+  let lastError: unknown = null;
+  const maxAttempts = Math.max(1, Math.ceil(timeoutMs / RUNNER_CONNECT_ATTEMPT_INTERVAL_MS));
   try {
     return await retryWithPolicy(
-      async () => {
+      async ({ deadline: attemptDeadline }) => {
+        if (attemptDeadline?.isExpired()) {
+          throw new AppError('COMMAND_FAILED', 'Runner connection deadline exceeded', {
+            port,
+            timeoutMs,
+          });
+        }
         if (device.kind === 'device') {
-          endpoints = await resolveRunnerCommandEndpoints(device, port);
+          endpoints = await resolveRunnerCommandEndpoints(device, port, attemptDeadline?.remainingMs());
         }
         for (const endpoint of endpoints) {
           try {
+            const remainingMs = attemptDeadline?.remainingMs() ?? timeoutMs;
+            if (remainingMs <= 0) {
+              throw new AppError('COMMAND_FAILED', 'Runner connection deadline exceeded', {
+                port,
+                timeoutMs,
+              });
+            }
             const response = await fetchWithTimeout(
               endpoint,
               {
@@ -540,7 +624,7 @@ async function waitForRunner(
                 headers: { 'Content-Type': 'application/json' },
                 body: JSON.stringify(command),
               },
-              1_000,
+              Math.min(RUNNER_CONNECT_REQUEST_TIMEOUT_MS, remainingMs),
             );
             return response;
           } catch (err) {
@@ -555,8 +639,8 @@ async function waitForRunner(
       },
       {
         maxAttempts,
-        baseDelayMs: 100,
-        maxDelayMs: 500,
+        baseDelayMs: RUNNER_CONNECT_RETRY_BASE_DELAY_MS,
+        maxDelayMs: RUNNER_CONNECT_RETRY_MAX_DELAY_MS,
         jitter: 0.2,
         shouldRetry: () => true,
       },
@@ -569,33 +653,27 @@ async function waitForRunner(
   }
 
   if (device.kind === 'simulator') {
-    const simResponse = await postCommandViaSimulator(device.id, port, command);
+    const remainingMs = deadline.remainingMs();
+    if (remainingMs <= 0) {
+      throw buildRunnerConnectError({ port, endpoints, logPath, lastError });
+    }
+    const simResponse = await postCommandViaSimulator(device.id, port, command, remainingMs);
     return new Response(simResponse.body, { status: simResponse.status });
   }
 
-  throw new AppError('COMMAND_FAILED', 'Runner did not accept connection', {
-    port,
-    endpoints,
-    logPath,
-    lastError: lastError ? String(lastError) : undefined,
-    reason: classifyBootFailure({
-      error: lastError,
-      message: 'Runner did not accept connection',
-      context: { platform: 'ios', phase: 'connect' },
-    }),
-    hint: bootFailureHint('IOS_RUNNER_CONNECT_TIMEOUT'),
-  });
+  throw buildRunnerConnectError({ port, endpoints, logPath, lastError });
 }
 
 async function resolveRunnerCommandEndpoints(
   device: DeviceInfo,
   port: number,
+  timeoutBudgetMs?: number,
 ): Promise<string[]> {
   const endpoints = [`http://127.0.0.1:${port}/command`];
   if (device.kind !== 'device') {
     return endpoints;
   }
-  const tunnelIp = await resolveDeviceTunnelIp(device.id);
+  const tunnelIp = await resolveDeviceTunnelIp(device.id, timeoutBudgetMs);
   if (tunnelIp) {
     endpoints.unshift(`http://[${tunnelIp}]:${port}/command`);
   }
@@ -616,12 +694,19 @@ async function fetchWithTimeout(
   }
 }
 
-async function resolveDeviceTunnelIp(deviceId: string): Promise<string | null> {
+async function resolveDeviceTunnelIp(deviceId: string, timeoutBudgetMs?: number): Promise<string | null> {
+  if (typeof timeoutBudgetMs === 'number' && timeoutBudgetMs <= 0) {
+    return null;
+  }
+  const timeoutMs = typeof timeoutBudgetMs === 'number'
+    ? Math.max(1, Math.min(RUNNER_DEVICE_INFO_TIMEOUT_MS, timeoutBudgetMs))
+    : RUNNER_DEVICE_INFO_TIMEOUT_MS;
   const jsonPath = path.join(
     os.tmpdir(),
     `agent-device-devicectl-info-${process.pid}-${Date.now()}.json`,
   );
   try {
+    const devicectlTimeoutSeconds = Math.max(1, Math.ceil(timeoutMs / 1000));
     const result = await runCmd(
       'xcrun',
       [
@@ -634,9 +719,9 @@ async function resolveDeviceTunnelIp(deviceId: string): Promise<string | null> {
         '--json-output',
         jsonPath,
         '--timeout',
-        '10',
+        String(devicectlTimeoutSeconds),
       ],
-      { allowFailure: true },
+      { allowFailure: true, timeoutMs },
     );
     if (result.exitCode !== 0 || !fs.existsSync(jsonPath)) {
       return null;
@@ -667,6 +752,7 @@ async function postCommandViaSimulator(
   udid: string,
   port: number,
   command: RunnerCommand,
+  timeoutMs: number,
 ): Promise<{ status: number; body: string }> {
   const payload = JSON.stringify(command);
   const result = await runCmd(
@@ -685,7 +771,7 @@ async function postCommandViaSimulator(
       payload,
       `http://127.0.0.1:${port}/command`,
     ],
-    { allowFailure: true },
+    { allowFailure: true, timeoutMs },
   );
   const body = result.stdout as string;
   if (result.exitCode !== 0) {

From 2b10e5b2312c6726f01b4ca7119fea62473260f1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Sat, 14 Feb 2026 14:43:30 +0100
Subject: [PATCH 12/13] args: align scrollintoview schema with capabilities

---
 src/utils/command-schema.ts | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/src/utils/command-schema.ts b/src/utils/command-schema.ts
index 66cf000ab..c484de9a8 100644
--- a/src/utils/command-schema.ts
+++ b/src/utils/command-schema.ts
@@ -443,10 +443,9 @@ export const COMMAND_SCHEMAS: Record<string, CommandSchema> = {
     allowedFlags: [],
   },
   scrollintoview: {
-    description: 'Scroll until text appears (Android only)',
+    description: 'Scroll until text appears',
     positionalArgs: ['text'],
     allowedFlags: [],
-    skipCapabilityCheck: true,
   },
   pinch: {
     description: 'Pinch/zoom gesture (iOS simulator)',

From e40623754942a8d56bcff486f160ac777b0d3435 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Sun, 15 Feb 2026 10:43:34 +0100
Subject: [PATCH 13/13] test: skip iOS integration flows on CI by default

---
 test/integration/ios.test.ts | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/test/integration/ios.test.ts b/test/integration/ios.test.ts
index 64a5d8830..b03e0e1cd 100644
--- a/test/integration/ios.test.ts
+++ b/test/integration/ios.test.ts
@@ -6,6 +6,7 @@ import { createIntegrationTestContext, runCliJson } from './test-helpers.ts';
 const session = ['--session', 'ios-test'];
 const iosTarget = ['--platform', 'ios'];
 const iosPhysicalUdid = process.env.IOS_UDID?.trim();
+const runIosIntegrationOnCi = isEnvTruthy(process.env.AGENT_DEVICE_RUN_IOS_INTEGRATION_ON_CI);
 let didRunIosPhysicalSession = false;
 
 test.after(() => {
@@ -114,9 +115,17 @@ test('ios physical device core lifecycle', { skip: shouldSkipIosPhysicalDevice()
 });
 
 function shouldSkipIos(): boolean {
-  return process.platform !== 'darwin';
+  return process.platform !== 'darwin' || (isCi() && !runIosIntegrationOnCi);
 }
 
 function shouldSkipIosPhysicalDevice(): boolean {
-  return process.platform !== 'darwin' || !iosPhysicalUdid;
+  return process.platform !== 'darwin' || !iosPhysicalUdid || isCi();
+}
+
+function isCi(): boolean {
+  return isEnvTruthy(process.env.CI);
+}
+
+function isEnvTruthy(value: string | undefined): boolean {
+  return ['1', 'true', 'yes', 'on'].includes((value ?? '').toLowerCase());
 }