feat: add iOS device record support via runner (#83)

* feat: add iOS device record support via runner

* refactor: simplify record command pathways

* fix: harden iOS record runner failure handling

* chore: emit diagnostic on iOS record stop runner failure

* fix: clear ios device runner cache in build:xcuitest

* chore: drop unused clean-derived env from build script

* fix: stage iOS device recordings via runner temp file

* fix: prefer requested iOS record path with permission fallback

* fix: disable iOS record fallback for explicit output paths

* refactor: remove iOS record fallback staging path flow

* fix: resolve record output paths from request cwd

* chore: log resolved record output path in diagnostics

* fix: avoid app activation when starting iOS recording

* refactor: streamline iOS recording setup paths

* fix: copy iOS device recordings back to host path

* fix: copy iOS recordings from runner test container

* feat: add configurable iOS recording fps

* fix: disable xcode test diagnostics for runner sessions

* fix: use wall-clock timestamps for iOS recording

* feat: default iOS recording to uncapped fps

* fix: recover stale ios runner recording state

* fix: preserve app focus when starting iOS recording

* docs: clarify iOS device recording capture model

* fix: tighten iOS device record start ownership checks

* refactor: collocate iOS record context checks

* refactor: derive uncapped recorder timescale from interval

Author: thymikee

README.md

@@ -324,7 +324,14 @@ Diagnostics files:
 
 ## iOS notes
 - Core runner commands: `snapshot`, `wait`, `click`, `fill`, `get`, `is`, `find`, `press`, `longpress`, `focus`, `type`, `scroll`, `scrollintoview`, `back`, `home`, `app-switcher`.
-- Simulator-only commands: `alert`, `pinch`, `record`, `settings`.
+- Simulator-only commands: `alert`, `pinch`, `settings`.
+- `record` supports iOS simulators and physical iOS devices.
+  - iOS simulator recording uses native `simctl io ... recordVideo`.
+  - Physical iOS device recording is runner-based and built from repeated `XCUIScreen.main.screenshot()` frames (no native video stream/audio capture).
+  - Physical iOS device recording requires an active app session context (`open <app>` first) so capture targets your app instead of the runner host app.
+  - Physical iOS device capture is best-effort: dropped frames are expected and true 60 FPS is not guaranteed even with `--fps 60`.
+  - Physical iOS device recording defaults to uncapped (max available) FPS.
+  - Use `agent-device record start [path] --fps <n>` (1-120) to set an explicit FPS cap on physical iOS devices.
 - 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
@@ -356,7 +363,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, simulator uses `~/.agent-device/ios-runner/derived` and physical device uses `~/.agent-device/ios-runner/derived/device`. If you set this override, use separate paths per kind to avoid simulator/device artifact collisions.
-- `AGENT_DEVICE_IOS_CLEAN_DERIVED=1` rebuild iOS runner artifacts from scratch. When `AGENT_DEVICE_IOS_RUNNER_DERIVED_PATH` is set, cleanup is blocked by default; set `AGENT_DEVICE_IOS_ALLOW_OVERRIDE_DERIVED_CLEAN=1` only for trusted custom paths.
+- `AGENT_DEVICE_IOS_CLEAN_DERIVED=1` rebuild iOS runner artifacts from scratch for runtime daemon-triggered builds (`pnpm ad ...`) on the selected path. `pnpm build:xcuitest`/`pnpm build:all` already clear `~/.agent-device/ios-runner/derived/device` and do not require this variable. 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`