diff --git a/README.md b/README.md
index 4e34732e1..bd4d8e6d8 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 fails explicitly.
+- `ax` backend is simulator-only.
 
 Flags:
 - `--version, -V` print version and exit
@@ -150,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
@@ -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. 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 resolves via XCTest snapshot.
 - `apps --metadata` returns app list with minimal metadata.
 
 ## Debug
@@ -222,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:
@@ -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: `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
 
@@ -266,6 +268,12 @@ 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.
+- `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/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 1afe5727c..bac99beb1 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)
 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
@@ -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 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. agent-device does not automatically fall back to AX.
 
 ### Find (semantic)
 
@@ -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.
 
 ### 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
@@ -174,19 +175,21 @@ 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.
 - 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), 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.
 - 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.
 - 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..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
 
@@ -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.
+
+## 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..22eaa7b56 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.
 - 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..360a53a3a 100644
--- a/skills/agent-device/references/snapshot-refs.md
+++ b/skills/agent-device/references/snapshot-refs.md
@@ -55,6 +55,8 @@ 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; use `--backend xctest` on iOS devices.
+- agent-device does not automatically fall back to AX when XCTest fails.
 
 ## Replay note
 
diff --git a/skills/agent-device/references/video-recording.md b/skills/agent-device/references/video-recording.md
index 09cec7949..a590ad056 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.
+
 ## 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..a5f6fef6e 100644
--- a/src/core/capabilities.ts
+++ b/src/core/capabilities.ts
@@ -13,33 +13,34 @@ 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 }, 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..6adbadd9f 100644
--- a/src/core/dispatch.ts
+++ b/src/core/dispatch.ts
@@ -283,6 +283,13 @@ 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',
+            '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,13 +308,11 @@ 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) {
-          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
-          }
+        if (nodes.length === 0 && device.kind === 'simulator') {
+          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.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/__tests__/app-state.test.ts b/src/daemon/__tests__/app-state.test.ts
new file mode 100644
index 000000000..85d89ac97
--- /dev/null
+++ b/src/daemon/__tests__/app-state.test.ts
@@ -0,0 +1,138 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import type { DeviceInfo } from '../../utils/device.ts';
+import { resolveIosAppStateFromSnapshots } from '../app-state.ts';
+import type { CommandFlags, dispatchCommand } from '../../core/dispatch.ts';
+
+const iosSimulator: DeviceInfo = {
+  platform: 'ios',
+  id: 'sim-1',
+  name: 'iPhone Simulator',
+  kind: 'simulator',
+  booted: true,
+};
+
+const iosDevice: DeviceInfo = {
+  platform: 'ios',
+  id: '00008110-000E12341234002E',
+  name: 'iPhone',
+  kind: 'device',
+  booted: true,
+};
+
+test('appstate uses xctest first on iOS simulator', async () => {
+  const backends: string[] = [];
+  const fakeDispatch: typeof dispatchCommand = async (_device, _command, _positionals, _outPath, context) => {
+    backends.push(context?.snapshotBackend ?? 'unknown');
+    return {
+      nodes: [
+        {
+          type: 'XCUIElementTypeApplication',
+          label: 'Settings',
+          identifier: 'com.apple.Preferences',
+        },
+      ],
+    };
+  };
+
+  const result = await resolveIosAppStateFromSnapshots(
+    iosSimulator,
+    '/tmp/daemon.log',
+    undefined,
+    {} as CommandFlags,
+    fakeDispatch,
+  );
+
+  assert.deepEqual(backends, ['xctest']);
+  assert.equal(result.source, 'snapshot-xctest');
+  assert.equal(result.appBundleId, 'com.apple.Preferences');
+});
+
+test('appstate does not try ax on iOS device when xctest succeeds', async () => {
+  const backends: string[] = [];
+  const fakeDispatch: typeof dispatchCommand = async (_device, _command, _positionals, _outPath, context) => {
+    backends.push(context?.snapshotBackend ?? 'unknown');
+    return {
+      nodes: [
+        {
+          type: 'XCUIElementTypeApplication',
+          label: 'Settings',
+          identifier: 'com.apple.Preferences',
+        },
+      ],
+    };
+  };
+
+  const result = await resolveIosAppStateFromSnapshots(
+    iosDevice,
+    '/tmp/daemon.log',
+    undefined,
+    {} as CommandFlags,
+    fakeDispatch,
+  );
+
+  assert.deepEqual(backends, ['xctest']);
+  assert.equal(result.source, 'snapshot-xctest');
+  assert.equal(result.appName, 'Settings');
+});
+
+test('appstate fails on simulator when xctest is empty', async () => {
+  const backends: string[] = [];
+  const fakeDispatch: typeof dispatchCommand = async (_device, _command, _positionals, _outPath, context) => {
+    backends.push(context?.snapshotBackend ?? 'unknown');
+    return { nodes: [] };
+  };
+
+  await assert.rejects(
+    resolveIosAppStateFromSnapshots(
+      iosSimulator,
+      '/tmp/daemon.log',
+      undefined,
+      {} as CommandFlags,
+      fakeDispatch,
+    ),
+    /not recommended/,
+  );
+  assert.deepEqual(backends, ['xctest']);
+});
+
+test('appstate fails on simulator when xctest throws', async () => {
+  const backends: string[] = [];
+  const fakeDispatch: typeof dispatchCommand = async (_device, _command, _positionals, _outPath, context) => {
+    const backend = context?.snapshotBackend ?? 'unknown';
+    backends.push(backend);
+    throw new Error('xctest failed');
+  };
+
+  await assert.rejects(
+    resolveIosAppStateFromSnapshots(
+      iosSimulator,
+      '/tmp/daemon.log',
+      undefined,
+      {} as CommandFlags,
+      fakeDispatch,
+    ),
+    /not recommended/,
+  );
+  assert.deepEqual(backends, ['xctest']);
+});
+
+test('appstate fails on device when xctest throws', async () => {
+  const backends: string[] = [];
+  const fakeDispatch: typeof dispatchCommand = async (_device, _command, _positionals, _outPath, context) => {
+    backends.push(context?.snapshotBackend ?? 'unknown');
+    throw new Error('xctest failed');
+  };
+
+  await assert.rejects(
+    resolveIosAppStateFromSnapshots(
+      iosDevice,
+      '/tmp/daemon.log',
+      undefined,
+      {} as CommandFlags,
+      fakeDispatch,
+    ),
+    /not recommended/,
+  );
+  assert.deepEqual(backends, ['xctest']);
+});
diff --git a/src/daemon/app-state.ts b/src/daemon/app-state.ts
index 82438fd1d..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';
 
@@ -9,47 +10,45 @@ export async function resolveIosAppStateFromSnapshots(
   logPath: string,
   traceLogPath: string | undefined,
   flags: CommandFlags | undefined,
-): Promise<{ appName: string; appBundleId?: string; source: 'snapshot-ax' | 'snapshot-xctest' }> {
-  const axResult = await dispatchCommand(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) {
+  dispatch: typeof dispatchCommand = dispatchCommand,
+): Promise<{ appName: string; appBundleId?: string; source: 'snapshot-xctest' }> {
+  let xctestResult: { nodes?: RawSnapshotNode[] } | undefined;
+  try {
+    xctestResult = (await dispatch(device, 'snapshot', [], flags?.out, {
+      ...contextFromFlags(
+        logPath,
+        {
+          ...flags,
+          snapshotDepth: 1,
+          snapshotCompact: true,
+          snapshotBackend: 'xctest',
+        },
+        undefined,
+        traceLogPath,
+      ),
+    })) as { nodes?: RawSnapshotNode[] };
+  } catch (error) {
+    const cause = error instanceof Error ? error.message : String(error);
+    throw new AppError(
+      'COMMAND_FAILED',
+      'Unable to resolve iOS app state from XCTest snapshot. You can try snapshot --backend ax for diagnostics, but AX snapshots are not recommended.',
+      { cause },
+    );
+  }
+
+  const xcNode = extractAppNodeFromSnapshot(xctestResult);
+  if (xcNode?.appName || xcNode?.appBundleId) {
     return {
-      appName: axNode.appName ?? axNode.appBundleId ?? 'unknown',
-      appBundleId: axNode.appBundleId,
-      source: 'snapshot-ax',
+      appName: xcNode.appName ?? xcNode.appBundleId ?? 'unknown',
+      appBundleId: xcNode.appBundleId,
+      source: 'snapshot-xctest',
     };
   }
-  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',
-  };
+
+  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/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/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/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..887dafccb 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 },
@@ -260,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',
         },
       };
     }
@@ -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..b4d72d6ee
--- /dev/null
+++ b/src/platforms/ios/__tests__/runner-client.test.ts
@@ -0,0 +1,113 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import type { DeviceInfo } from '../../../utils/device.ts';
+import {
+  assertSafeDerivedCleanup,
+  resolveRunnerBuildDestination,
+  resolveRunnerDestination,
+  resolveRunnerMaxConcurrentDestinationsFlag,
+  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('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({}), []);
+});
+
+test('resolveRunnerSigningBuildSettings enables automatic signing for device builds without forcing identity', () => {
+  assert.deepEqual(resolveRunnerSigningBuildSettings({}, true), [
+    'CODE_SIGN_STYLE=Automatic',
+  ]);
+});
+
+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',
+    AGENT_DEVICE_IOS_SIGNING_IDENTITY: 'Apple Development',
+    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',
+  ]);
+});
+
+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/devices.ts b/src/platforms/ios/devices.ts
index ab70426be..e465e7a24 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';
@@ -38,26 +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 result = await runCmd('xcrun', ['devicectl', 'list', 'devices', '--json']);
-      const payload = JSON.parse(result.stdout as string) as {
-        devices: { identifier: string; name: string; platform: 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.devices ?? []) {
-        if (device.platform?.toLowerCase().includes('ios')) {
-          devices.push({
-            platform: 'ios',
-            id: device.identifier,
-            name: device.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/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/src/platforms/ios/runner-client.ts b/src/platforms/ios/runner-client.ts
index 2c7a8c0e9..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 { 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;
@@ -92,6 +118,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),
@@ -106,10 +133,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 +244,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 +262,12 @@ async function ensureRunnerSession(
       'NO',
       '-test-timeouts-enabled',
       'NO',
-      '-maximum-concurrent-test-simulator-destinations',
+      resolveRunnerMaxConcurrentDestinationsFlag(device),
       '1',
       '-xctestrun',
       xctestrunPath,
       '-destination',
-      `platform=iOS Simulator,id=${device.id}`,
+      resolveRunnerDestination(device),
     ],
     {
       allowFailure: true,
@@ -292,11 +315,12 @@ 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()) {
+    assertSafeDerivedCleanup(derived);
     try {
       fs.rmSync(derived, { recursive: true, force: true });
     } catch {
@@ -313,6 +337,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 +350,14 @@ async function ensureXctestrun(
         'AgentDeviceRunner',
         '-parallel-testing-enabled',
         'NO',
-        '-maximum-concurrent-test-simulator-destinations',
+        resolveRunnerMaxConcurrentDestinationsFlag(device),
         '1',
         '-destination',
-        `platform=iOS Simulator,id=${udid}`,
+        resolveRunnerBuildDestination(device),
         '-derivedDataPath',
         derived,
+        ...provisioningArgs,
+        ...signingBuildSettings,
       ],
       {
         onStdoutChunk: (chunk) => {
@@ -342,10 +370,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 +386,90 @@ 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(RUNNER_DERIVED_ROOT, '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);
+}
+
+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() || '';
+  const args = ['CODE_SIGN_STYLE=Automatic'];
+  if (teamId) {
+    args.push(`DEVELOPMENT_TEAM=${teamId}`);
+  }
+  if (configuredIdentity) {
+    args.push(`CODE_SIGN_IDENTITY=${configuredIdentity}`);
+  }
+  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 {
@@ -428,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(
@@ -440,43 +592,167 @@ async function waitForRunner(
   logPath?: string,
   timeoutMs: number = RUNNER_STARTUP_TIMEOUT_MS,
 ): Promise<Response> {
-  const start = Date.now();
+  const deadline = Deadline.fromTimeoutMs(timeoutMs);
+  let endpoints = await resolveRunnerCommandEndpoints(device, port, deadline.remainingMs());
   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));
+  const maxAttempts = Math.max(1, Math.ceil(timeoutMs / RUNNER_CONNECT_ATTEMPT_INTERVAL_MS));
+  try {
+    return await retryWithPolicy(
+      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, 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,
+              {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(command),
+              },
+              Math.min(RUNNER_CONNECT_REQUEST_TIMEOUT_MS, remainingMs),
+            );
+            return response;
+          } catch (err) {
+            lastError = err;
+          }
+        }
+        throw new AppError('COMMAND_FAILED', 'Runner endpoint probe failed', {
+          port,
+          endpoints,
+          lastError: lastError ? String(lastError) : undefined,
+        });
+      },
+      {
+        maxAttempts,
+        baseDelayMs: RUNNER_CONNECT_RETRY_BASE_DELAY_MS,
+        maxDelayMs: RUNNER_CONNECT_RETRY_MAX_DELAY_MS,
+        jitter: 0.2,
+        shouldRetry: () => true,
+      },
+      { deadline, phase: 'ios_runner_connect' },
+    );
+  } catch (error) {
+    if (!lastError) {
+      lastError = error;
     }
   }
+
   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,
-    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, timeoutBudgetMs);
+  if (tunnelIp) {
+    endpoints.unshift(`http://[${tunnelIp}]:${port}/command`);
+  }
+  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, 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',
+      [
+        'devicectl',
+        'device',
+        'info',
+        'details',
+        '--device',
+        deviceId,
+        '--json-output',
+        jsonPath,
+        '--timeout',
+        String(devicectlTimeoutSeconds),
+      ],
+      { allowFailure: true, timeoutMs },
+    );
+    if (result.exitCode !== 0 || !fs.existsSync(jsonPath)) {
+      return null;
+    }
+    const payload = JSON.parse(fs.readFileSync(jsonPath, 'utf8')) as {
+      info?: { outcome?: string };
+      result?: {
+        connectionProperties?: { tunnelIPAddress?: string };
+        device?: { connectionProperties?: { tunnelIPAddress?: string } };
+      };
+    };
+    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;
+  } finally {
+    cleanupTempFile(jsonPath);
+  }
 }
 
 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(
@@ -495,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) {
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)',
diff --git a/test/integration/ios.test.ts b/test/integration/ios.test.ts
index 67feb716a..b03e0e1cd 100644
--- a/test/integration/ios.test.ts
+++ b/test/integration/ios.test.ts
@@ -5,9 +5,15 @@ 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(() => {
   runCliJson(['close', ...iosTarget, '--json', ...session]);
+  if (iosPhysicalUdid && didRunIosPhysicalSession) {
+    runCliJson(['close', '--platform', 'ios', '--udid', iosPhysicalUdid, '--json', '--session', 'ios-device-test']);
+  }
 });
 
 test('ios settings commands', { skip: shouldSkipIos() }, async () => {
@@ -79,6 +85,47 @@ 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];
+  didRunIosPhysicalSession = true;
+
+  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';
+  return process.platform !== 'darwin' || (isCi() && !runIosIntegrationOnCi);
+}
+
+function shouldSkipIosPhysicalDevice(): boolean {
+  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());
 }
diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md
index 525fb7028..8de962ba3 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.
 
 ## Snapshot and inspect
 
@@ -32,6 +33,10 @@ agent-device get text @e1
 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
 
 ```bash
@@ -54,7 +59,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)
 
@@ -84,7 +89,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
@@ -98,6 +103,9 @@ agent-device settings location on
 agent-device settings location off
 ```
 
+- iOS `settings` support is simulator-only.
+- Android `settings` support works on emulators and devices.
+
 ## Media and logs
 
 ```bash
@@ -107,3 +115,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.
+
+## 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` (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)
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..119e40f1b 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: `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.
 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..d30fb5476 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.
+
 ## JSON output
 
 For programmatic parsing in scripts:
diff --git a/website/docs/docs/sessions.md b/website/docs/docs/sessions.md
index 609173403..16898de98 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.
 - 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..31bd53603 100644
--- a/website/docs/docs/snapshots.md
+++ b/website/docs/docs/snapshots.md
@@ -22,7 +22,8 @@ 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 fails explicitly.
+It does not automatically switch to AX.
 
 ## Example output:
 
@@ -43,5 +44,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