zeno-mobile-runner 0.2.11 → 0.2.13

package/CHANGELOG.md

@@ -4,6 +4,35 @@ All notable changes to Zeno Mobile Runner are tracked here.
 
 ## Unreleased
 
+## 0.2.13 (2026-06-23)
+
+### Fixed
+
+- iOS native selector waits now cap each XCTest query to the action timeout,
+  retry one transient native command failure, and then fall back to semantic
+  snapshots with diagnostics. This prevents one stuck XCTest selector query from
+  consuming the whole wait budget while still allowing transient native queries
+  to recover.
+- iOS native selector scrolling now reads the app-frame viewport from the XCTest
+  shim before generating swipe coordinates, so native scrolls use iOS point
+  dimensions instead of Android fallback dimensions.
+- Expo dev-client URL opening now uses URL-aware fallback handling and avoids
+  broad static-text enumeration while accepting deep-link chooser prompts.
+
+## 0.2.12 (2026-06-22)
+
+### Fixed
+
+- iOS XCTest-shim command failures now classify generated shim timeout and
+  server-exit stderr into typed ZMR errors, so traces and CLI output distinguish
+  response timeouts, server-start timeouts, build timeouts, and server exits from
+  generic device command failures.
+- iOS native selector actions and semantic snapshot extraction now emit
+  `started` trace events before entering XCTest, making long-running simulator
+  commands visible while they are in flight.
+- The generated app-local iOS shim removes completed request files together with
+  response files, preventing stale request buildup during long E2E sessions.
+
 ## 0.2.11 (2026-06-22)
 
 ### Fixed

package/FEATURES.md

@@ -142,7 +142,7 @@ state, and writes deterministic traces. It does not embed an LLM.
 
 ## Current Limitations
 
-- Current release status is `0.2.11`, a public developer preview rather than
+- Current release status is `0.2.13`, a public developer preview rather than
   a production-stable `1.0.0`.
 - Physical iOS log capture is still simulator-first. Physical iOS screenshots
   are available when the XCTest/XCUIAutomation shim is configured.

package/README.md

@@ -196,8 +196,10 @@ comparisons against your current E2E tool, and multi-device matrices, see
 | iOS physical device | Supported, validate locally | `devicectl` lifecycle plus XCTest shim; pilot on your own app/device before relying on it in CI |
 | Cloud device farms | Not included | ZMR focuses on local and self-managed device targets in this preview |
 
-Slow CI hardware can extend the iOS shim cold-build timeout with
-`ZMR_IOS_SHIM_TIMEOUT_MS`. Current release: `0.2.11` developer preview.
+Slow CI hardware can extend the generated iOS shim build timeout with
+`ZMR_IOS_SHIM_BUILD_TIMEOUT_SECONDS`; `ZMR_IOS_SHIM_RESPONSE_TIMEOUT_SECONDS`
+bounds each in-flight request, and `ZMR_IOS_SHIM_TIMEOUT_MS` remains the outer
+process ceiling. Current release: `0.2.13` developer preview.
 Protocol version: `2026-04-28`.
 
 ## Optional protocol clients

package/clients/kotlin/README.md

@@ -27,7 +27,7 @@ gradle -p clients/kotlin runFakeSession \
 ```
 
 ```kotlin
-implementation(files("path/to/zeno-mobile-runner/clients/kotlin/build/libs/zmr-client-0.2.11.jar"))
+implementation(files("path/to/zeno-mobile-runner/clients/kotlin/build/libs/zmr-client-0.2.13.jar"))
 ```
 
 ```kotlin

package/clients/kotlin/build.gradle.kts

@@ -4,7 +4,7 @@ plugins {
 }
 
 group = "dev.zmr"
-version = "0.2.11"
+version = "0.2.13"
 
 kotlin {
     jvmToolchain(17)

package/clients/python/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "zmr-client"
-version = "0.2.11.dev1"
+version = "0.2.13.dev1"
 description = "Python JSON-RPC client for Zeno Mobile Runner."
 requires-python = ">=3.9"
 license = { text = "MIT" }

package/clients/rust/Cargo.lock

@@ -100,7 +100,7 @@ checksum = "b8848ee67ecc8aedbaf3e4122217aff892639231befc6a1b58d29fff4c2cabaa"
 
 [[package]]
 name = "zmr-client"
-version = "0.2.11"
+version = "0.2.13"
 dependencies = [
  "serde",
  "serde_json",

package/clients/rust/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "zmr-client"
-version = "0.2.11"
+version = "0.2.13"
 edition = "2021"
 license = "MIT"
 description = "Rust JSON-RPC client for Zeno Mobile Runner."

package/clients/typescript/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zmr/client",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "type": "module",
   "main": "index.mjs",
   "types": "index.d.ts",

package/docs/protocol-fixtures/core-session.responses.jsonl

@@ -1,4 +1,4 @@
-{"jsonrpc":"2.0","id":1,"result":{"name":"zmr","version":"0.2.11","protocolVersion":"2026-04-28","protocol":{"version":"2026-04-28","minimumCompatibleVersion":"2026-04-28","stability":"dev-preview","breakingChangePolicy":"version-and-changelog"},"platforms":["android","ios"],"platformSupport":{"android":{"status":"supported","deviceTypes":["emulator","physical"],"automation":["adb","uiautomator","android-shim"]},"ios":{"status":"supported","deviceTypes":["simulator","physical"],"automation":["simctl","devicectl","xctest-shim"],"physicalDevices":true}},"iosPreview":false,"transports":["stdio","tcp"],"methods":["runner.capabilities","device.list","session.create","session.close","app.install","app.launch","app.stop","app.openLink","app.clearState","observe.snapshot","observe.semanticSnapshot","ui.tap","ui.type","ui.eraseText","ui.hideKeyboard","ui.swipe","ui.pressBack","ui.scrollUntilVisible","wait.until","wait.any","wait.gone","assert.visible","assert.notVisible","assert.healthy","scenario.validate","trace.events","trace.explore","trace.discover","trace.explain","trace.export"]}}
+{"jsonrpc":"2.0","id":1,"result":{"name":"zmr","version":"0.2.13","protocolVersion":"2026-04-28","protocol":{"version":"2026-04-28","minimumCompatibleVersion":"2026-04-28","stability":"dev-preview","breakingChangePolicy":"version-and-changelog"},"platforms":["android","ios"],"platformSupport":{"android":{"status":"supported","deviceTypes":["emulator","physical"],"automation":["adb","uiautomator","android-shim"]},"ios":{"status":"supported","deviceTypes":["simulator","physical"],"automation":["simctl","devicectl","xctest-shim"],"physicalDevices":true}},"iosPreview":false,"transports":["stdio","tcp"],"methods":["runner.capabilities","device.list","session.create","session.close","app.install","app.launch","app.stop","app.openLink","app.clearState","observe.snapshot","observe.semanticSnapshot","ui.tap","ui.type","ui.eraseText","ui.hideKeyboard","ui.swipe","ui.pressBack","ui.scrollUntilVisible","wait.until","wait.any","wait.gone","assert.visible","assert.notVisible","assert.healthy","scenario.validate","trace.events","trace.explore","trace.discover","trace.explain","trace.export"]}}
 {"jsonrpc":"2.0","id":2,"result":[{"serial":"fake-device-1","state":"device","ready":true}]}
 {"jsonrpc":"2.0","id":3,"result":{"sessionId":"default"}}
 {"jsonrpc":"2.0","id":4,"result":true}

package/docs/protocol.md

@@ -2,7 +2,7 @@
 
 ZMR exposes newline-delimited JSON-RPC 2.0 over stdio or localhost TCP in v1. Each request is one JSON object followed by `\n`. Each response is one JSON object followed by `\n`.
 
-Current runner version: `0.2.11`.
+Current runner version: `0.2.13`.
 
 Current protocol version: `2026-04-28`.
 
@@ -47,7 +47,7 @@ and protocol versions. The response is covered by
 `schemas/inspect-output.schema.json`:
 
 ```json
-{"ok":true,"status":"ready","schemaVersion":1,"runnerVersion":"0.2.11","protocolVersion":"2026-04-28","dir":".","configPath":".zmr/config.json","configExists":true,"agentInstructionsPath":".zmr/AGENTS.md","agentInstructionsExists":true,"platforms":[{"name":"android","enabled":true,"defaultDevice":"emulator-5554","smokeScenario":".zmr/android-smoke.json","smokeScenarioExists":true,"traceDir":"traces/zmr-android"},{"name":"ios","enabled":true,"defaultDevice":"booted","smokeScenario":".zmr/ios-smoke.json","smokeScenarioExists":true,"traceDir":"traces/zmr-ios"}],"recommendedCommands":["zmr doctor --strict --json --config .zmr/config.json","zmr schemas --json","zmr validate --json .zmr/android-smoke.json","zmr validate --json .zmr/ios-smoke.json","zmr serve --transport stdio --config .zmr/config.json --trace-dir traces/zmr-agent","zmr mcp --config .zmr/config.json --trace-dir traces/zmr-agent"],"claimsPolicy":["verify runs with trace evidence before making readiness claims","do not claim Flutter widget-tree inspection"],"limitations":["inspect is read-only and does not launch devices","autonomous crawling is not shipped; generate or edit scenarios for human review"]}
+{"ok":true,"status":"ready","schemaVersion":1,"runnerVersion":"0.2.13","protocolVersion":"2026-04-28","dir":".","configPath":".zmr/config.json","configExists":true,"agentInstructionsPath":".zmr/AGENTS.md","agentInstructionsExists":true,"platforms":[{"name":"android","enabled":true,"defaultDevice":"emulator-5554","smokeScenario":".zmr/android-smoke.json","smokeScenarioExists":true,"traceDir":"traces/zmr-android"},{"name":"ios","enabled":true,"defaultDevice":"booted","smokeScenario":".zmr/ios-smoke.json","smokeScenarioExists":true,"traceDir":"traces/zmr-ios"}],"recommendedCommands":["zmr doctor --strict --json --config .zmr/config.json","zmr schemas --json","zmr validate --json .zmr/android-smoke.json","zmr validate --json .zmr/ios-smoke.json","zmr serve --transport stdio --config .zmr/config.json --trace-dir traces/zmr-agent","zmr mcp --config .zmr/config.json --trace-dir traces/zmr-agent"],"claimsPolicy":["verify runs with trace evidence before making readiness claims","do not claim Flutter widget-tree inspection"],"limitations":["inspect is read-only and does not launch devices","autonomous crawling is not shipped; generate or edit scenarios for human review"]}
 ```
 
 `zmr discover --from-trace <trace-dir> --out <scenario.json> --validate --json`
@@ -60,7 +60,7 @@ invent credentials, or commit files. The response is covered by
 `schemas/discover-output.schema.json`:
 
 ```json
-{"ok":true,"mode":"discover","schemaVersion":1,"runnerVersion":"0.2.11","protocolVersion":"2026-04-28","out":".zmr/discovered/replay-smoke.json","traceDir":"traces/zmr-agent","sourceSnapshot":"traces/zmr-agent/artifacts/snapshot-2.json","name":"draft from login smoke","appId":"com.example.mobiletest","selectorCount":2,"stepCount":6,"replay":{"enabled":true,"eventCount":4,"stepCount":3,"skippedEventCount":1},"warnings":["draft requires human review before commit"],"validated":true,"validation":{"ok":true,"path":".zmr/discovered/replay-smoke.json","name":"draft from login smoke","appId":"com.example.mobiletest","stepCount":6},"nextCommands":["zmr validate --json .zmr/discovered/replay-smoke.json","zmr run .zmr/discovered/replay-smoke.json --json --trace-dir traces/zmr-agent"]}
+{"ok":true,"mode":"discover","schemaVersion":1,"runnerVersion":"0.2.13","protocolVersion":"2026-04-28","out":".zmr/discovered/replay-smoke.json","traceDir":"traces/zmr-agent","sourceSnapshot":"traces/zmr-agent/artifacts/snapshot-2.json","name":"draft from login smoke","appId":"com.example.mobiletest","selectorCount":2,"stepCount":6,"replay":{"enabled":true,"eventCount":4,"stepCount":3,"skippedEventCount":1},"warnings":["draft requires human review before commit"],"validated":true,"validation":{"ok":true,"path":".zmr/discovered/replay-smoke.json","name":"draft from login smoke","appId":"com.example.mobiletest","stepCount":6},"nextCommands":["zmr validate --json .zmr/discovered/replay-smoke.json","zmr run .zmr/discovered/replay-smoke.json --json --trace-dir traces/zmr-agent"]}
 ```
 
 `zmr explore --from-trace <trace-dir> --out <scenario.json> --goal <goal>
@@ -71,7 +71,7 @@ launch devices, crawl the app, invent missing actions, discover credentials, or
 commit files. The response is covered by `schemas/explore-output.schema.json`:
 
 ```json
-{"ok":true,"mode":"explore","schemaVersion":1,"runnerVersion":"0.2.11","protocolVersion":"2026-04-28","goal":"find a stable login smoke","autonomous":false,"reviewRequired":true,"guardrails":["writes from existing trace evidence only","does not crawl the app","does not discover credentials or secrets","requires human review before commit"],"out":".zmr/discovered/login-smoke.json","traceDir":"traces/zmr-agent","sourceSnapshot":"traces/zmr-agent/artifacts/snapshot-2.json","name":"draft from login smoke","appId":"com.example.mobiletest","selectorCount":2,"stepCount":6,"replay":{"enabled":true,"eventCount":4,"stepCount":3,"skippedEventCount":1},"warnings":["draft requires human review before commit"],"validated":true,"validation":{"ok":true,"path":".zmr/discovered/login-smoke.json","name":"draft from login smoke","appId":"com.example.mobiletest","stepCount":6},"nextCommands":["zmr validate --json .zmr/discovered/login-smoke.json","zmr run .zmr/discovered/login-smoke.json --json --trace-dir traces/zmr-agent"]}
+{"ok":true,"mode":"explore","schemaVersion":1,"runnerVersion":"0.2.13","protocolVersion":"2026-04-28","goal":"find a stable login smoke","autonomous":false,"reviewRequired":true,"guardrails":["writes from existing trace evidence only","does not crawl the app","does not discover credentials or secrets","requires human review before commit"],"out":".zmr/discovered/login-smoke.json","traceDir":"traces/zmr-agent","sourceSnapshot":"traces/zmr-agent/artifacts/snapshot-2.json","name":"draft from login smoke","appId":"com.example.mobiletest","selectorCount":2,"stepCount":6,"replay":{"enabled":true,"eventCount":4,"stepCount":3,"skippedEventCount":1},"warnings":["draft requires human review before commit"],"validated":true,"validation":{"ok":true,"path":".zmr/discovered/login-smoke.json","name":"draft from login smoke","appId":"com.example.mobiletest","stepCount":6},"nextCommands":["zmr validate --json .zmr/discovered/login-smoke.json","zmr run .zmr/discovered/login-smoke.json --json --trace-dir traces/zmr-agent"]}
 ```
 
 `zmr draft --from-trace <trace-dir> --out <scenario.json> --json` is the lower
@@ -84,7 +84,7 @@ into fields, or commit files. The response is covered by
 `schemas/draft-output.schema.json`:
 
 ```json
-{"ok":true,"mode":"draft","schemaVersion":1,"runnerVersion":"0.2.11","protocolVersion":"2026-04-28","out":".zmr/discovered/surface-smoke.json","traceDir":"traces/zmr-agent","sourceSnapshot":"traces/zmr-agent/artifacts/snapshot-2.json","name":"draft from login smoke","appId":"com.example.mobiletest","selectorCount":2,"stepCount":4,"replay":{"enabled":false,"eventCount":0,"stepCount":0,"skippedEventCount":0},"warnings":["draft requires human review before commit"],"nextCommands":["zmr validate --json .zmr/discovered/surface-smoke.json","zmr run .zmr/discovered/surface-smoke.json --json --trace-dir traces/zmr-agent"]}
+{"ok":true,"mode":"draft","schemaVersion":1,"runnerVersion":"0.2.13","protocolVersion":"2026-04-28","out":".zmr/discovered/surface-smoke.json","traceDir":"traces/zmr-agent","sourceSnapshot":"traces/zmr-agent/artifacts/snapshot-2.json","name":"draft from login smoke","appId":"com.example.mobiletest","selectorCount":2,"stepCount":4,"replay":{"enabled":false,"eventCount":0,"stepCount":0,"skippedEventCount":0},"warnings":["draft requires human review before commit"],"nextCommands":["zmr validate --json .zmr/discovered/surface-smoke.json","zmr run .zmr/discovered/surface-smoke.json --json --trace-dir traces/zmr-agent"]}
 ```
 
 `zmr draft --include-actions` additionally parses `events.jsonl` and prepends
@@ -214,7 +214,7 @@ installers, setup scripts, and generated clients. The response is covered by
 `schemas/version-output.schema.json`:
 
 ```json
-{"name":"zmr","version":"0.2.11","protocolVersion":"2026-04-28","minimumCompatibleProtocolVersion":"2026-04-28","stability":"dev-preview","breakingChangePolicy":"version-and-changelog"}
+{"name":"zmr","version":"0.2.13","protocolVersion":"2026-04-28","minimumCompatibleProtocolVersion":"2026-04-28","stability":"dev-preview","breakingChangePolicy":"version-and-changelog"}
 ```
 
 ## Capabilities Output Contract
@@ -226,7 +226,7 @@ and method inventory for JSON-RPC clients. The result object is covered by
 iOS simulator, or physical iOS workflows are available.
 
 ```json
-{"name":"zmr","version":"0.2.11","protocolVersion":"2026-04-28","protocol":{"version":"2026-04-28","minimumCompatibleVersion":"2026-04-28","stability":"dev-preview","breakingChangePolicy":"version-and-changelog"},"platforms":["android","ios"],"platformSupport":{"android":{"status":"supported","deviceTypes":["emulator","physical"],"automation":["adb","uiautomator","android-shim"]},"ios":{"status":"supported","deviceTypes":["simulator","physical"],"automation":["simctl","devicectl","xctest-shim"],"physicalDevices":true}},"iosPreview":false,"transports":["stdio","tcp"],"methods":["runner.capabilities","device.list","session.create","session.close","app.install","app.launch","app.stop","app.openLink","app.clearState","observe.snapshot","observe.semanticSnapshot","ui.tap","ui.type","ui.eraseText","ui.hideKeyboard","ui.swipe","ui.pressBack","ui.scrollUntilVisible","wait.until","wait.any","wait.gone","assert.visible","assert.notVisible","assert.healthy","scenario.validate","trace.events","trace.explore","trace.discover","trace.explain","trace.export"]}
+{"name":"zmr","version":"0.2.13","protocolVersion":"2026-04-28","protocol":{"version":"2026-04-28","minimumCompatibleVersion":"2026-04-28","stability":"dev-preview","breakingChangePolicy":"version-and-changelog"},"platforms":["android","ios"],"platformSupport":{"android":{"status":"supported","deviceTypes":["emulator","physical"],"automation":["adb","uiautomator","android-shim"]},"ios":{"status":"supported","deviceTypes":["simulator","physical"],"automation":["simctl","devicectl","xctest-shim"],"physicalDevices":true}},"iosPreview":false,"transports":["stdio","tcp"],"methods":["runner.capabilities","device.list","session.create","session.close","app.install","app.launch","app.stop","app.openLink","app.clearState","observe.snapshot","observe.semanticSnapshot","ui.tap","ui.type","ui.eraseText","ui.hideKeyboard","ui.swipe","ui.pressBack","ui.scrollUntilVisible","wait.until","wait.any","wait.gone","assert.visible","assert.notVisible","assert.healthy","scenario.validate","trace.events","trace.explore","trace.discover","trace.explain","trace.export"]}
 ```
 
 ## Doctor Output Contract
@@ -432,7 +432,7 @@ Request:
 Response:
 
 ```json
-{"jsonrpc":"2.0","id":1,"result":{"name":"zmr","version":"0.2.11","protocolVersion":"2026-04-28","protocol":{"version":"2026-04-28","minimumCompatibleVersion":"2026-04-28","stability":"dev-preview","breakingChangePolicy":"version-and-changelog"},"platforms":["android","ios"],"platformSupport":{"android":{"status":"supported","deviceTypes":["emulator","physical"],"automation":["adb","uiautomator","android-shim"]},"ios":{"status":"supported","deviceTypes":["simulator","physical"],"automation":["simctl","devicectl","xctest-shim"],"physicalDevices":true}},"iosPreview":false,"transports":["stdio","tcp"],"methods":["runner.capabilities","device.list","session.create","session.close","app.install","app.launch","app.stop","app.openLink","app.clearState","observe.snapshot","observe.semanticSnapshot","ui.tap","ui.type","ui.eraseText","ui.hideKeyboard","ui.swipe","ui.pressBack","ui.scrollUntilVisible","wait.until","wait.any","wait.gone","assert.visible","assert.notVisible","assert.healthy","scenario.validate","trace.events","trace.explore","trace.discover","trace.explain","trace.export"]}}
+{"jsonrpc":"2.0","id":1,"result":{"name":"zmr","version":"0.2.13","protocolVersion":"2026-04-28","protocol":{"version":"2026-04-28","minimumCompatibleVersion":"2026-04-28","stability":"dev-preview","breakingChangePolicy":"version-and-changelog"},"platforms":["android","ios"],"platformSupport":{"android":{"status":"supported","deviceTypes":["emulator","physical"],"automation":["adb","uiautomator","android-shim"]},"ios":{"status":"supported","deviceTypes":["simulator","physical"],"automation":["simctl","devicectl","xctest-shim"],"physicalDevices":true}},"iosPreview":false,"transports":["stdio","tcp"],"methods":["runner.capabilities","device.list","session.create","session.close","app.install","app.launch","app.stop","app.openLink","app.clearState","observe.snapshot","observe.semanticSnapshot","ui.tap","ui.type","ui.eraseText","ui.hideKeyboard","ui.swipe","ui.pressBack","ui.scrollUntilVisible","wait.until","wait.any","wait.gone","assert.visible","assert.notVisible","assert.healthy","scenario.validate","trace.events","trace.explore","trace.discover","trace.explain","trace.export"]}}
 ```
 
 ### `trace.events`
@@ -514,7 +514,7 @@ Request:
 Response:
 
 ```json
-{"jsonrpc":"2.0","id":25,"result":{"ok":true,"mode":"discover","schemaVersion":1,"runnerVersion":"0.2.11","protocolVersion":"2026-04-28","out":".zmr/discovered/agent-smoke.json","traceDir":"traces/agent-session","sourceSnapshot":"traces/agent-session/artifacts/snapshot-1.json","name":"agent smoke","appId":"com.example.mobiletest","selectorCount":1,"stepCount":4,"replay":{"enabled":true,"eventCount":2,"stepCount":1,"skippedEventCount":1},"warnings":["draft requires human review before commit"],"validated":true,"validation":{"ok":true,"path":".zmr/discovered/agent-smoke.json","name":"agent smoke","appId":"com.example.mobiletest","stepCount":4},"nextCommands":["zmr validate --json .zmr/discovered/agent-smoke.json","zmr run .zmr/discovered/agent-smoke.json --json --trace-dir traces/agent-session"]}}
+{"jsonrpc":"2.0","id":25,"result":{"ok":true,"mode":"discover","schemaVersion":1,"runnerVersion":"0.2.13","protocolVersion":"2026-04-28","out":".zmr/discovered/agent-smoke.json","traceDir":"traces/agent-session","sourceSnapshot":"traces/agent-session/artifacts/snapshot-1.json","name":"agent smoke","appId":"com.example.mobiletest","selectorCount":1,"stepCount":4,"replay":{"enabled":true,"eventCount":2,"stepCount":1,"skippedEventCount":1},"warnings":["draft requires human review before commit"],"validated":true,"validation":{"ok":true,"path":".zmr/discovered/agent-smoke.json","name":"agent smoke","appId":"com.example.mobiletest","stepCount":4},"nextCommands":["zmr validate --json .zmr/discovered/agent-smoke.json","zmr run .zmr/discovered/agent-smoke.json --json --trace-dir traces/agent-session"]}}
 ```
 
 Without `--trace-dir`, it returns `ok: false` with `traceDir: null`. Generated
@@ -537,7 +537,7 @@ Request:
 Response:
 
 ```json
-{"jsonrpc":"2.0","id":27,"result":{"ok":true,"mode":"explore","schemaVersion":1,"runnerVersion":"0.2.11","protocolVersion":"2026-04-28","out":".zmr/discovered/agent-goal.json","traceDir":"traces/agent-session","sourceSnapshot":"traces/agent-session/artifacts/snapshot-1.json","name":"agent goal smoke","appId":"com.example.mobiletest","selectorCount":1,"stepCount":4,"replay":{"enabled":true,"eventCount":2,"stepCount":1,"skippedEventCount":1},"warnings":["draft requires human review before commit"],"validated":true,"validation":{"ok":true,"path":".zmr/discovered/agent-goal.json","name":"agent goal smoke","appId":"com.example.mobiletest","stepCount":4},"nextCommands":["zmr validate --json .zmr/discovered/agent-goal.json","zmr run .zmr/discovered/agent-goal.json --json --trace-dir traces/agent-session"],"goal":"find a stable login smoke","autonomous":false,"reviewRequired":true,"guardrails":["writes from existing trace evidence only","does not crawl the app","does not discover credentials or secrets","requires human review before commit"]}}
+{"jsonrpc":"2.0","id":27,"result":{"ok":true,"mode":"explore","schemaVersion":1,"runnerVersion":"0.2.13","protocolVersion":"2026-04-28","out":".zmr/discovered/agent-goal.json","traceDir":"traces/agent-session","sourceSnapshot":"traces/agent-session/artifacts/snapshot-1.json","name":"agent goal smoke","appId":"com.example.mobiletest","selectorCount":1,"stepCount":4,"replay":{"enabled":true,"eventCount":2,"stepCount":1,"skippedEventCount":1},"warnings":["draft requires human review before commit"],"validated":true,"validation":{"ok":true,"path":".zmr/discovered/agent-goal.json","name":"agent goal smoke","appId":"com.example.mobiletest","stepCount":4},"nextCommands":["zmr validate --json .zmr/discovered/agent-goal.json","zmr run .zmr/discovered/agent-goal.json --json --trace-dir traces/agent-session"],"goal":"find a stable login smoke","autonomous":false,"reviewRequired":true,"guardrails":["writes from existing trace evidence only","does not crawl the app","does not discover credentials or secrets","requires human review before commit"]}}
 ```
 
 Without `--trace-dir`, it returns `ok: false` with `traceDir: null`.

package/docs/troubleshooting.md

@@ -188,11 +188,13 @@ app targets. Pass `--project` explicitly for still-ambiguous multi-project
 workspaces. Run with `--ios-shim ./.zmr/ios-shim` or set
 `tools.iosShimPath` in `.zmr/config.json`.
 
-A clean prebuild can push the shim's first `build-for-testing` through a full
-native dependency compile. ZMR waits up to 90 minutes by default; on slower CI
-hardware, raise the ceiling with the `ZMR_IOS_SHIM_TIMEOUT_MS` environment
-variable (milliseconds), for example `ZMR_IOS_SHIM_TIMEOUT_MS=10800000` for
-three hours.
+A clean prebuild can push the generated shim's first `build-for-testing` through
+a full native dependency compile. The app-local shim waits up to 90 minutes by
+default; on slower CI hardware, raise the build ceiling with
+`ZMR_IOS_SHIM_BUILD_TIMEOUT_SECONDS=10800` for three hours. Individual shim
+requests are bounded separately by `ZMR_IOS_SHIM_RESPONSE_TIMEOUT_SECONDS`
+(default 180 seconds), while `ZMR_IOS_SHIM_TIMEOUT_MS` remains the outer ZMR
+process ceiling for the whole shim command.
 
 If a real iOS run fails with CoreSimulator or Xcode cache errors such as
 `Operation not permitted`, `CoreSimulatorService connection became invalid`, or

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zeno-mobile-runner",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "description": "Agent-native mobile app test runner for React Native, Expo, Flutter, and native Android/iOS.",
   "main": "npm/index.mjs",
   "repository": {

package/scripts/install-ios-shim.sh

@@ -456,7 +456,7 @@ send_request() {
     if [[ -f "\$response_file" ]]; then
       cat "\$response_file"
       printf '\\n'
-      rm -f "\$response_file"
+      rm -f "\$request_file" "\$response_file"
       return 0
     fi
     if ! is_server_running; then

package/shims/ios/ZMRShim.swift

@@ -5,6 +5,8 @@ struct ZMRShimCommand: Decodable {
     let cmd: String
     let selector: String?
     let text: String?
+    let url: String?
+    let expoDevClientFallback: Bool?
     let x: Int?
     let y: Int?
     let x1: Int?

package/shims/ios/ZMRShimUITestCase.swift

@@ -116,6 +116,11 @@ final class ZMRShimUITestCase: XCTestCase {
                 "viewport": ZMRShim.viewport(app: app).json,
                 "nodes": ZMRShim.snapshot(app: app).map { $0.json }
             ]
+        case "viewport":
+            return [
+                "status": "ok",
+                "viewport": ZMRShim.viewport(app: app).json
+            ]
         case "screenshot":
             let screenshot = XCUIScreen.main.screenshot()
             return [
@@ -187,7 +192,12 @@ final class ZMRShimUITestCase: XCTestCase {
         case "appState":
             return ["status": "ok", "state": app.state.rawValue]
         case "acceptSystemAlert":
-            return acceptSystemAlert(buttonText: command.text ?? "Open", app: app)
+            return acceptSystemAlert(
+                buttonText: command.text ?? "Open",
+                openedURL: command.url,
+                expoDevClientFallback: command.expoDevClientFallback ?? false,
+                app: app
+            )
         default:
             return error("unknown.command", "unsupported command: \(command.cmd)")
         }
@@ -195,7 +205,7 @@ final class ZMRShimUITestCase: XCTestCase {
 
     private func commandRequiresForeground(_ command: ZMRShimCommand) -> Bool {
         switch command.cmd {
-        case "snapshot", "query", "tap", "type", "eraseText", "hideKeyboard", "swipe", "settle":
+        case "snapshot", "viewport", "query", "tap", "type", "eraseText", "hideKeyboard", "swipe", "settle":
             return true
         default:
             return false
@@ -229,7 +239,12 @@ final class ZMRShimUITestCase: XCTestCase {
         ["status": "error", "code": code, "message": message]
     }
 
-    private func acceptSystemAlert(buttonText: String, app: XCUIApplication) -> [String: Any] {
+    private func acceptSystemAlert(
+        buttonText: String,
+        openedURL: String?,
+        expoDevClientFallback: Bool,
+        app: XCUIApplication
+    ) -> [String: Any] {
         let springboard = XCUIApplication(bundleIdentifier: "com.apple.springboard")
         var labels = [buttonText, "Open", "Allow", "OK", "Continue"]
         labels = labels.reduce(into: [String]()) { unique, label in
@@ -264,7 +279,11 @@ final class ZMRShimUITestCase: XCTestCase {
             }
         }
 
-        let expoDeepLinkSelection = acceptExpoDevClientDeepLink(app: app)
+        let expoDeepLinkSelection = acceptExpoDevClientDeepLink(
+            openedURL: openedURL,
+            expoDevClientFallback: expoDevClientFallback,
+            app: app
+        )
         if expoDeepLinkSelection.accepted {
             acceptedCount += 1
             lastAcceptedLabel = expoDeepLinkSelection.label
@@ -282,27 +301,38 @@ final class ZMRShimUITestCase: XCTestCase {
         return ["status": "ok", "accepted": false, "count": 0]
     }
 
-    private func acceptExpoDevClientDeepLink(app: XCUIApplication) -> (accepted: Bool, label: String) {
-        guard app.staticTexts["Deep link received:"].waitForExistence(timeout: 1) else {
-            return (false, "")
-        }
-
-        let candidateQueries = [
-            app.buttons.allElementsBoundByIndex,
-            app.cells.allElementsBoundByIndex,
-            app.staticTexts.allElementsBoundByIndex
-        ]
+    private func acceptExpoDevClientDeepLink(
+        openedURL: String?,
+        expoDevClientFallback: Bool,
+        app: XCUIApplication
+    ) -> (accepted: Bool, label: String) {
+        let predicate = NSPredicate(
+            format: "label != '' AND label != %@ AND label != %@ AND label != %@ AND NOT label CONTAINS[c] %@ AND NOT label BEGINSWITH[c] %@ AND NOT label CONTAINS[c] %@",
+            "Deep link received:",
+            "Select an app to open it:",
+            "Go back",
+            "://",
+            "Note:",
+            "next app you open"
+        )
 
-        for elements in candidateQueries {
-            for element in elements {
-                let label = element.label.trimmingCharacters(in: .whitespacesAndNewlines)
-                guard isExpoDevClientDeepLinkTarget(label: label), element.isHittable else {
-                    continue
-                }
+        if app.staticTexts["Deep link received:"].waitForExistence(timeout: 1) {
+            if tapFirstMatchingExpoCandidate(
+                queries: [app.buttons, app.cells, app.staticTexts],
+                predicate: predicate
+            ) {
+                return (true, "expo-dev-client-deep-link")
+            }
+        }
 
-                element.tap()
-                Thread.sleep(forTimeInterval: 1.0)
-                return (true, label)
+        if expoDevClientFallback,
+           isCustomSchemeURL(openedURL),
+           !isExpoDevClientURL(openedURL) {
+            if tapExpoDevClientDeepLinkCoordinateFallback(app: app) {
+                return (true, "expo-dev-client-deep-link-coordinate")
+            }
+            if tapExpoDevClientDeepLinkCandidateFallback(app: app, predicate: predicate) {
+                return (true, "expo-dev-client-deep-link-candidate")
             }
         }
 
@@ -335,23 +365,12 @@ final class ZMRShimUITestCase: XCTestCase {
             return (false, "")
         }
 
-        let candidateQueries = [
-            app.buttons.allElementsBoundByIndex,
-            app.cells.allElementsBoundByIndex,
-            app.staticTexts.allElementsBoundByIndex
-        ]
-
-        for elements in candidateQueries {
-            for element in elements {
-                let label = element.label.trimmingCharacters(in: .whitespacesAndNewlines)
-                guard isExpoDevClientProjectTarget(label: label), element.exists else {
-                    continue
-                }
-
-                element.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.5)).tap()
-                Thread.sleep(forTimeInterval: 1.0)
-                return (true, label)
-            }
+        let predicate = NSPredicate(format: "label CONTAINS[c] %@ OR label CONTAINS[c] %@", " http://", " https://")
+        if tapFirstMatchingExpoCandidate(
+            queries: [app.buttons, app.cells, app.staticTexts],
+            predicate: predicate
+        ) {
+            return (true, "expo-dev-client-home")
         }
 
         return (false, "")
@@ -379,6 +398,59 @@ final class ZMRShimUITestCase: XCTestCase {
         return label.contains(" http://") || label.contains(" https://")
     }
 
+    private func tapFirstMatchingExpoCandidate(
+        queries: [XCUIElementQuery],
+        predicate: NSPredicate
+    ) -> Bool {
+        for query in queries {
+            let matching = query.matching(predicate)
+            for candidateIndex in 0..<6 {
+                let element = matching.element(boundBy: candidateIndex)
+                guard element.exists else {
+                    break
+                }
+
+                guard element.isHittable else {
+                    continue
+                }
+
+                element.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.5)).tap()
+                Thread.sleep(forTimeInterval: 1.0)
+                return true
+            }
+        }
+
+        return false
+    }
+
+    private func isCustomSchemeURL(_ value: String?) -> Bool {
+        guard let value else {
+            return false
+        }
+        return value.contains("://") && !value.hasPrefix("http://") && !value.hasPrefix("https://")
+    }
+
+    private func isExpoDevClientURL(_ value: String?) -> Bool {
+        guard let value else {
+            return false
+        }
+        return value.hasPrefix("exp+") && value.contains("://expo-development-client/")
+    }
+
+    private func tapExpoDevClientDeepLinkCoordinateFallback(app: XCUIApplication) -> Bool {
+        Thread.sleep(forTimeInterval: 1.5)
+        app.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.6)).tap()
+        Thread.sleep(forTimeInterval: 1.0)
+        return true
+    }
+
+    private func tapExpoDevClientDeepLinkCandidateFallback(app: XCUIApplication, predicate: NSPredicate) -> Bool {
+        tapFirstMatchingExpoCandidate(
+            queries: [app.buttons, app.cells, app.staticTexts],
+            predicate: predicate
+        )
+    }
+
     private func hideKeyboard(app: XCUIApplication) -> [String: Any] {
         guard app.keyboards.firstMatch.exists else {
             return ok()

package/shims/ios/protocol.md

@@ -6,6 +6,7 @@ Commands are newline-delimited JSON objects:
 
 ```json
 {"cmd":"snapshot"}
+{"cmd":"viewport"}
 {"cmd":"tap","selector":"text=Continue","x":20,"y":40}
 {"cmd":"type","selector":"identifier=email","text":"hello"}
 {"cmd":"eraseText","selector":"identifier=email","maxChars":20}
@@ -43,6 +44,13 @@ that XCTest can evaluate natively. It returns:
 {"status":"ok","format":"png","base64":"..."}
 ```
 
+`viewport` returns the target application frame in XCTest point coordinates
+without crawling the element hierarchy:
+
+```json
+{"status":"ok","viewport":{"width":390,"height":844}}
+```
+
 Snapshot responses return bounded XCTest element data in a shape Zig can map
 into `UiNode`. The shim captures common interactive and readable element
 families and caps the response at 256 nodes so large application trees do not

package/src/errors.zig

@@ -58,7 +58,12 @@ pub fn classify(err: anyerror) PublicError {
         error.AssertionFailed => .{ .code = "runner.assertion_failed", .message = "assertion failed" },
         error.SelectorNotFound => .{ .code = "runner.selector_not_found", .message = "selector not found" },
         error.CommandFailed => .{ .code = "device.command_failed", .message = "device command failed" },
+        error.CommandTimedOut => .{ .code = "device.command_timed_out", .message = "device command timed out" },
         error.IosXCTestShimRequired => .{ .code = "ios.xctest_shim_required", .message = "iOS selector interaction requires the XCTest shim" },
+        error.IosXCTestShimResponseTimedOut => .{ .code = "ios.xctest_shim_response_timeout", .message = "iOS XCTest shim response timed out" },
+        error.IosXCTestShimStartTimedOut => .{ .code = "ios.xctest_shim_start_timeout", .message = "iOS XCTest shim server startup timed out" },
+        error.IosXCTestShimBuildTimedOut => .{ .code = "ios.xctest_shim_build_timeout", .message = "iOS XCTest shim build timed out" },
+        error.IosXCTestShimServerExited => .{ .code = "ios.xctest_shim_server_exited", .message = "iOS XCTest shim server exited" },
         else => .{ .code = "internal.error", .message = @errorName(err) },
     };
 }

package/src/ios.zig

@@ -33,6 +33,7 @@ pub const IosDevice = struct {
     app_id: []const u8,
     shim_path: ?[]const u8 = null,
     target_kind: TargetKind = .simulator,
+    expo_dev_client_open_link_mode: bool = false,
 
     pub fn init(
         allocator: std.mem.Allocator,
@@ -131,13 +132,16 @@ pub const IosDevice = struct {
         const result = try self.runSimctl(&.{ "openurl", self.target(), url }, default_max_output);
         defer result.deinit(self.allocator);
         try result.ensureSuccess();
+        if (isExpoDevClientOpenLink(url)) {
+            self.expo_dev_client_open_link_mode = true;
+        }
         // Opening a URL on the simulator can raise a SpringBoard "Open in <App>?"
         // confirmation for universal links (http/https) and, just as often, for
         // custom schemes — the common Expo dev-client case
         // (exp+scheme://expo-development-client/...). Attempt a best-effort accept
         // whenever a shim is configured; the shim probes briefly and returns fast
         // when no dialog is present, so this stays cheap on the no-prompt path.
-        self.acceptOpenURLConfirmationBestEffort();
+        self.acceptOpenURLConfirmationBestEffort(url);
     }
 
     pub fn tap(self: *IosDevice, x: i32, y: i32) !void {
@@ -189,6 +193,12 @@ pub const IosDevice = struct {
         try self.runShimAction(.{ .kind = .swipe, .x1 = x1, .y1 = y1, .x2 = x2, .y2 = y2, .duration_ms = duration_ms });
     }
 
+    pub fn scrollViewport(self: *IosDevice) !types.Viewport {
+        const response = try self.runShim(.{ .kind = .viewport });
+        defer self.allocator.free(response);
+        return try ios_shim.parseViewportResponse(response);
+    }
+
     pub fn pressBack(self: *IosDevice) !void {
         try self.runShimAction(.{ .kind = .press_back });
     }
@@ -232,6 +242,7 @@ pub const IosDevice = struct {
         errdefer self.allocator.free(active_package);
         var shim_viewport: ?types.Viewport = null;
         const nodes = if (self.shim_path != null) blk: {
+            if (writer) |tw| try self.recordSnapshotSemanticStarted(tw);
             const shim_snapshot = self.snapshotFromShim() catch |err| {
                 if (screenshot_artifact == null) return err;
                 if (writer) |tw| try self.recordSnapshotSemanticFailure(tw, screenshot_artifact.?, err);
@@ -291,6 +302,11 @@ pub const IosDevice = struct {
         return try ios_shim.parseSnapshotResponse(self.allocator, response);
     }
 
+    fn recordSnapshotSemanticStarted(self: *IosDevice, writer: *trace.TraceWriter) !void {
+        try writer.recordEvent("observe.snapshot.semanticExtraction", "{\"status\":\"started\",\"source\":\"ios-xctest-shim\"}");
+        _ = self;
+    }
+
     fn recordSnapshotSemanticFailure(self: *IosDevice, writer: *trace.TraceWriter, screenshot_artifact: []const u8, err: anyerror) !void {
         var payload: std.Io.Writer.Allocating = .init(writer.allocator);
         defer payload.deinit();
@@ -316,20 +332,25 @@ pub const IosDevice = struct {
         try ios_shim.parseOkResponse(response);
     }
 
-    fn acceptOpenURLConfirmationBestEffort(self: *IosDevice) void {
+    fn acceptOpenURLConfirmationBestEffort(self: *IosDevice, url: []const u8) void {
         if (self.shim_path == null) return;
         var attempt: usize = 0;
         while (attempt < open_link_interruption_attempts) {
             attempt += 1;
-            if (self.acceptOpenURLConfirmationOnce() catch return) return;
+            if (self.acceptOpenURLConfirmationOnce(url) catch return) return;
             if (attempt < open_link_interruption_attempts) {
                 stdio.sleepNs(open_link_interruption_retry_delay_ms * std.time.ns_per_ms);
             }
         }
     }
 
-    fn acceptOpenURLConfirmationOnce(self: *IosDevice) !bool {
-        const response = try self.runShimWithTimeout(.{ .kind = .accept_system_alert, .text = "Open" }, shim_best_effort_timeout_ms);
+    fn acceptOpenURLConfirmationOnce(self: *IosDevice, url: []const u8) !bool {
+        const response = try self.runShimWithTimeout(.{
+            .kind = .accept_system_alert,
+            .text = "Open",
+            .url = url,
+            .expo_dev_client_fallback = self.expo_dev_client_open_link_mode,
+        }, shim_best_effort_timeout_ms);
         defer self.allocator.free(response);
         return try ios_shim.parseAcceptSystemAlertResponse(response);
     }
@@ -378,7 +399,7 @@ pub const IosDevice = struct {
                     stdio.sleepNs(shim_bootstrap_retry_delay_ms * std.time.ns_per_ms);
                     continue;
                 }
-                return err;
+                return classifyShimCommandFailure(result);
             };
             return try self.allocator.dupe(u8, result.stdout);
         }
@@ -422,6 +443,27 @@ fn isTransientShimBootstrapFailure(result: command.ExecResult) bool {
         std.mem.indexOf(u8, result.stderr, "operation never finished bootstrapping") != null;
 }
 
+fn classifyShimCommandFailure(result: command.ExecResult) anyerror {
+    if (result.timed_out) return error.CommandTimedOut;
+    if (std.mem.indexOf(u8, result.stderr, "timed out waiting for iOS shim response") != null) {
+        return error.IosXCTestShimResponseTimedOut;
+    }
+    if (std.mem.indexOf(u8, result.stderr, "timed out waiting for iOS shim server readiness") != null) {
+        return error.IosXCTestShimStartTimedOut;
+    }
+    if (std.mem.indexOf(u8, result.stderr, "timed out waiting for iOS shim build-for-testing") != null) {
+        return error.IosXCTestShimBuildTimedOut;
+    }
+    if (std.mem.indexOf(u8, result.stderr, "iOS shim server exited before it became ready") != null or
+        std.mem.indexOf(u8, result.stderr, "iOS shim server exited while waiting for response") != null or
+        std.mem.indexOf(u8, result.stderr, "Early unexpected exit") != null or
+        std.mem.indexOf(u8, result.stderr, "operation never finished bootstrapping") != null)
+    {
+        return error.IosXCTestShimServerExited;
+    }
+    return error.CommandFailed;
+}
+
 fn shimTimeoutMs() u64 {
     return parseShimTimeoutMs(stdio.getenv(shim_timeout_env));
 }
@@ -433,6 +475,11 @@ fn parseShimTimeoutMs(raw: ?[]const u8) u64 {
     return parsed;
 }
 
+fn isExpoDevClientOpenLink(url: []const u8) bool {
+    return std.mem.startsWith(u8, url, "exp+") and
+        std.mem.indexOf(u8, url, "://expo-development-client/") != null;
+}
+
 test "ios simulator openLink keeps sweeping delayed XCTest interruptions until accepted" {
     const allocator = std.heap.page_allocator;
     const argv = [_][*:0]const u8{"zmr-ios-test"};
@@ -523,3 +570,25 @@ test "ios xctest shim timeout env override" {
     try std.testing.expectEqual(@as(u64, default_shim_timeout_ms), parseShimTimeoutMs("not-a-number"));
     try std.testing.expectEqual(@as(u64, default_shim_timeout_ms), parseShimTimeoutMs("0"));
 }
+
+test "ios xctest shim command failures classify generated shim timeout causes" {
+    try expectClassifiedShimFailure(error.IosXCTestShimResponseTimedOut, "timed out waiting for iOS shim response 12345\n");
+    try expectClassifiedShimFailure(error.IosXCTestShimStartTimedOut, "timed out waiting for iOS shim server readiness\n");
+    try expectClassifiedShimFailure(error.IosXCTestShimBuildTimedOut, "timed out waiting for iOS shim build-for-testing after 5400s\n");
+    try expectClassifiedShimFailure(error.IosXCTestShimServerExited, "iOS shim server exited while waiting for response 12345\n");
+    try expectClassifiedShimFailure(error.CommandFailed, "xcodebuild failed for another reason\n");
+}
+
+fn expectClassifiedShimFailure(expected: anyerror, stderr: []const u8) !void {
+    const allocator = std.testing.allocator;
+    const stdout_owned = try allocator.dupe(u8, "");
+    defer allocator.free(stdout_owned);
+    const stderr_owned = try allocator.dupe(u8, stderr);
+    defer allocator.free(stderr_owned);
+    const result = command.ExecResult{
+        .stdout = stdout_owned,
+        .stderr = stderr_owned,
+        .term = .{ .exited = 1 },
+    };
+    try std.testing.expectEqual(expected, classifyShimCommandFailure(result));
+}

package/src/ios_shim.zig

@@ -5,6 +5,7 @@ const types = @import("types.zig");
 
 pub const CommandKind = enum {
     snapshot,
+    viewport,
     screenshot,
     tap,
     type_text,
@@ -22,6 +23,8 @@ pub const Command = struct {
     kind: CommandKind,
     selector: ?[]const u8 = null,
     text: ?[]const u8 = null,
+    url: ?[]const u8 = null,
+    expo_dev_client_fallback: bool = false,
     x: ?i32 = null,
     y: ?i32 = null,
     x1: ?i32 = null,
@@ -42,6 +45,19 @@ pub const SnapshotResponse = struct {
     }
 };
 
+pub fn parseViewportResponse(content: []const u8) !types.Viewport {
+    var arena = std.heap.ArenaAllocator.init(std.heap.page_allocator);
+    defer arena.deinit();
+    const parsed = try std.json.parseFromSlice(std.json.Value, arena.allocator(), content, .{});
+    if (parsed.value != .object) return error.IosShimResponseMustBeObject;
+    const status = fieldString(parsed.value.object, "status") orelse return error.IosShimMissingStatus;
+    if (!std.mem.eql(u8, status, "ok")) return error.IosShimResponseNotOk;
+    const viewport_value = parsed.value.object.get("viewport") orelse return error.IosShimMissingViewport;
+    const viewport = parseViewport(viewport_value);
+    if (viewport.width == 0 or viewport.height == 0) return error.IosShimInvalidViewport;
+    return viewport;
+}
+
 pub fn writeCommandJson(writer: anytype, command: Command) !void {
     try writer.writeAll("{\"cmd\":");
     try trace.writeJsonString(writer, commandName(command.kind));
@@ -53,6 +69,13 @@ pub fn writeCommandJson(writer: anytype, command: Command) !void {
         try writer.writeAll(",\"text\":");
         try trace.writeJsonString(writer, text);
     }
+    if (command.url) |url| {
+        try writer.writeAll(",\"url\":");
+        try trace.writeJsonString(writer, url);
+    }
+    if (command.expo_dev_client_fallback) {
+        try writer.writeAll(",\"expoDevClientFallback\":true");
+    }
     if (command.x) |value| try writer.print(",\"x\":{d}", .{value});
     if (command.y) |value| try writer.print(",\"y\":{d}", .{value});
     if (command.x1) |value| try writer.print(",\"x1\":{d}", .{value});
@@ -270,6 +293,7 @@ pub fn selectorString(allocator: std.mem.Allocator, wanted: selectors.Selector)
 fn commandName(kind: CommandKind) []const u8 {
     return switch (kind) {
         .snapshot => "snapshot",
+        .viewport => "viewport",
         .screenshot => "screenshot",
         .tap => "tap",
         .type_text => "type",

package/src/main.zig

@@ -94,7 +94,10 @@ fn writeTopLevelError(err: anyerror) void {
     defer stderr_io.deinit();
     const stderr = stderr_io.writer();
     stderr.print("error[{s}]: {s}\n", .{ public.code, public.message }) catch {};
-    if (err == error.CommandFailed) {
+    if (err == error.CommandFailed or err == error.CommandTimedOut or
+        err == error.IosXCTestShimResponseTimedOut or err == error.IosXCTestShimStartTimedOut or
+        err == error.IosXCTestShimBuildTimedOut or err == error.IosXCTestShimServerExited)
+    {
         stderr.writeAll("hint: run `zmr doctor --json` for setup diagnostics.\n") catch {};
     }
     if (err == error.unknownFlag) {

package/src/runner_events.zig

@@ -26,6 +26,23 @@ pub fn recordNativeWait(tw: *trace.TraceWriter, kind: []const u8, wanted: select
     try tw.recordEvent(kind, writer.buffered());
 }
 
+pub fn recordNativeScrollUntilVisible(
+    tw: *trace.TraceWriter,
+    wanted: selector.Selector,
+    direction: []const u8,
+    timeout_ms: u64,
+) !void {
+    var payload: std.Io.Writer.Allocating = .init(tw.allocator);
+    defer payload.deinit();
+    const writer = &payload.writer;
+    try writer.writeAll("{\"status\":\"ok\",\"strategy\":\"nativeSelector\",\"selector\":");
+    try trace.writeSelectorJson(writer, wanted);
+    try writer.writeAll(",\"direction\":");
+    try trace.writeJsonString(writer, direction);
+    try writer.print(",\"timeoutMs\":{d}}}", .{timeout_ms});
+    try tw.recordEvent("ui.scrollUntilVisible", writer.buffered());
+}
+
 pub fn recordNativeWaitTimeout(tw: *trace.TraceWriter, kind: []const u8, selectors: []const selector.Selector, timeout_ms: u64) !void {
     var payload: std.Io.Writer.Allocating = .init(tw.allocator);
     defer payload.deinit();

package/src/runner_native.zig

@@ -9,6 +9,7 @@ pub fn tryTapSelector(
     settle_ms: u64,
 ) !bool {
     if (!@hasDecl(@TypeOf(device.*), "tapBySelector")) return false;
+    if (writer) |tw| try recordSelectorActionStarted(tw, "ui.tap", wanted);
     const tapped = device.tapBySelector(wanted) catch |err| {
         if (writer) |tw| try recordSelectorActionFailure(tw, "ui.tap", wanted, err);
         return err;
@@ -27,6 +28,7 @@ pub fn tryTypeTextSelector(
     settle_ms: u64,
 ) !bool {
     if (!@hasDecl(@TypeOf(device.*), "typeTextBySelector")) return false;
+    if (writer) |tw| try recordSelectorActionStarted(tw, "ui.type", wanted);
     const typed = device.typeTextBySelector(wanted, text) catch |err| {
         if (writer) |tw| try recordSelectorActionFailure(tw, "ui.type", wanted, err);
         return err;
@@ -45,6 +47,7 @@ pub fn tryEraseTextSelector(
     settle_ms: u64,
 ) !bool {
     if (!@hasDecl(@TypeOf(device.*), "eraseTextBySelector")) return false;
+    if (writer) |tw| try recordSelectorActionStarted(tw, "ui.eraseText", wanted);
     const erased = device.eraseTextBySelector(wanted, max_chars) catch |err| {
         if (writer) |tw| try recordSelectorActionFailure(tw, "ui.eraseText", wanted, err);
         return err;
@@ -55,6 +58,20 @@ pub fn tryEraseTextSelector(
     return true;
 }
 
+fn recordSelectorActionStarted(
+    tw: *trace.TraceWriter,
+    kind: []const u8,
+    wanted: selector.Selector,
+) !void {
+    var payload: std.Io.Writer.Allocating = .init(tw.allocator);
+    defer payload.deinit();
+    const writer = &payload.writer;
+    try writer.writeAll("{\"status\":\"started\",\"strategy\":\"nativeSelector\",\"selector\":");
+    try trace.writeSelectorJson(writer, wanted);
+    try writer.writeAll("}");
+    try tw.recordEvent(kind, writer.buffered());
+}
+
 fn recordSelectorAction(
     tw: *trace.TraceWriter,
     kind: []const u8,

package/src/runner_waits.zig

@@ -9,6 +9,7 @@ const trace = @import("trace.zig");
 
 const RunOptions = runner_config.RunOptions;
 const native_health_probe_timeout_ms: u64 = 1000;
+const native_selector_transient_retry_limit: usize = 1;
 
 pub fn waitUntilVisible(
     device: anytype,
@@ -39,23 +40,36 @@ fn untilVisibleKind(
     kind: []const u8,
 ) !bool {
     const deadline = stdio.nowMs() + @as(i64, @intCast(timeout_ms));
+    var native_query_failures: usize = 0;
     while (true) {
-        if (nativeSelectorQueryTimeoutMs(deadline)) |query_timeout_ms| {
-            const native_result = nativeVisibleBySelector(device, wanted, query_timeout_ms) catch |err| {
-                if (try retryTransientObservation(err, kind, writer, deadline, options)) continue;
+        if (nativeSelectorQueryTimeoutMs(deadline, options)) |query_timeout_ms| {
+            var native_query_failed = false;
+            const native_result = nativeVisibleBySelector(device, wanted, query_timeout_ms) catch |err| blk: {
+                if (try recordTransientNativeSelectorObservation(err, kind, writer)) {
+                    native_query_failures += 1;
+                    if (native_query_failures <= native_selector_transient_retry_limit and stdio.nowMs() < deadline) {
+                        try sleepMs(options.poll_ms);
+                        continue;
+                    }
+                    native_query_failed = true;
+                    break :blk null;
+                }
                 return err;
             };
-            if (native_result) |visible| {
-                if (visible) {
-                    if (writer) |tw| try runner_events.recordNativeWait(tw, kind, wanted, null, timeout_ms);
-                    return true;
-                }
-                if (stdio.nowMs() >= deadline) {
-                    if (writer) |tw| try runner_events.recordNativeWaitTimeoutWithDiagnostics(device, tw, kind, &[_]selector.Selector{wanted}, timeout_ms);
-                    return false;
+            if (!native_query_failed) native_query_failures = 0;
+            if (!native_query_failed) {
+                if (native_result) |visible| {
+                    if (visible) {
+                        if (writer) |tw| try runner_events.recordNativeWait(tw, kind, wanted, null, timeout_ms);
+                        return true;
+                    }
+                    if (stdio.nowMs() >= deadline) {
+                        if (writer) |tw| try runner_events.recordNativeWaitTimeoutWithDiagnostics(device, tw, kind, &[_]selector.Selector{wanted}, timeout_ms);
+                        return false;
+                    }
+                    try sleepMs(options.poll_ms);
+                    continue;
                 }
-                try sleepMs(options.poll_ms);
-                continue;
             }
         } else if (hasNativeSelectorQuery(device)) {
             if (writer) |tw| try runner_events.recordNativeWaitTimeoutWithDiagnostics(device, tw, kind, &[_]selector.Selector{wanted}, timeout_ms);
@@ -119,23 +133,36 @@ fn untilNotVisibleKind(
     kind: []const u8,
 ) !bool {
     const deadline = stdio.nowMs() + @as(i64, @intCast(timeout_ms));
+    var native_query_failures: usize = 0;
     while (true) {
-        if (nativeSelectorQueryTimeoutMs(deadline)) |query_timeout_ms| {
-            const native_result = nativeVisibleBySelector(device, wanted, query_timeout_ms) catch |err| {
-                if (try retryTransientObservation(err, kind, writer, deadline, options)) continue;
+        if (nativeSelectorQueryTimeoutMs(deadline, options)) |query_timeout_ms| {
+            var native_query_failed = false;
+            const native_result = nativeVisibleBySelector(device, wanted, query_timeout_ms) catch |err| blk: {
+                if (try recordTransientNativeSelectorObservation(err, kind, writer)) {
+                    native_query_failures += 1;
+                    if (native_query_failures <= native_selector_transient_retry_limit and stdio.nowMs() < deadline) {
+                        try sleepMs(options.poll_ms);
+                        continue;
+                    }
+                    native_query_failed = true;
+                    break :blk null;
+                }
                 return err;
             };
-            if (native_result) |visible| {
-                if (!visible) {
-                    if (writer) |tw| try runner_events.recordNativeWait(tw, kind, wanted, null, timeout_ms);
-                    return true;
-                }
-                if (stdio.nowMs() >= deadline) {
-                    if (writer) |tw| try runner_events.recordNativeWaitTimeoutWithDiagnostics(device, tw, kind, &[_]selector.Selector{wanted}, timeout_ms);
-                    return false;
+            if (!native_query_failed) native_query_failures = 0;
+            if (!native_query_failed) {
+                if (native_result) |visible| {
+                    if (!visible) {
+                        if (writer) |tw| try runner_events.recordNativeWait(tw, kind, wanted, null, timeout_ms);
+                        return true;
+                    }
+                    if (stdio.nowMs() >= deadline) {
+                        if (writer) |tw| try runner_events.recordNativeWaitTimeoutWithDiagnostics(device, tw, kind, &[_]selector.Selector{wanted}, timeout_ms);
+                        return false;
+                    }
+                    try sleepMs(options.poll_ms);
+                    continue;
                 }
-                try sleepMs(options.poll_ms);
-                continue;
             }
         } else if (hasNativeSelectorQuery(device)) {
             if (writer) |tw| try runner_events.recordNativeWaitTimeoutWithDiagnostics(device, tw, kind, &[_]selector.Selector{wanted}, timeout_ms);
@@ -178,10 +205,11 @@ pub fn waitUntilAnyVisible(
     options: RunOptions,
 ) !?usize {
     const deadline = stdio.nowMs() + @as(i64, @intCast(timeout_ms));
-    while (true) {
+    var native_query_failures: usize = 0;
+    native_poll: while (true) {
         var all_native = true;
         for (selectors, 0..) |wanted, index| {
-            const query_timeout_ms = nativeSelectorQueryTimeoutMs(deadline) orelse {
+            const query_timeout_ms = nativeSelectorQueryTimeoutMs(deadline, options) orelse {
                 if (hasNativeSelectorQuery(device)) {
                     if (writer) |tw| try runner_events.recordNativeWaitTimeoutWithDiagnostics(device, tw, "wait.any", selectors, timeout_ms);
                     return null;
@@ -190,9 +218,18 @@ pub fn waitUntilAnyVisible(
                 break;
             };
             const native_result = nativeVisibleBySelector(device, wanted, query_timeout_ms) catch |err| {
-                if (try retryTransientObservation(err, "wait.any", writer, deadline, options)) continue;
+                if (try recordTransientNativeSelectorObservation(err, "wait.any", writer)) {
+                    native_query_failures += 1;
+                    if (native_query_failures <= native_selector_transient_retry_limit and stdio.nowMs() < deadline) {
+                        try sleepMs(options.poll_ms);
+                        continue :native_poll;
+                    }
+                    all_native = false;
+                    break;
+                }
                 return err;
             };
+            native_query_failures = 0;
             if (native_result) |visible| {
                 if (visible) {
                     if (writer) |tw| try runner_events.recordNativeWait(tw, "wait.any", wanted, index, timeout_ms);
@@ -322,7 +359,7 @@ fn nativeAssertHealthy(
 
     const deadline = stdio.nowMs() + @as(i64, @intCast(timeout_ms));
     native_probe: while (true) {
-        const remaining_ms = nativeSelectorQueryTimeoutMs(deadline) orelse return null;
+        const remaining_ms = nativeSelectorRemainingTimeoutMs(deadline) orelse return null;
         const query_timeout_ms = @min(remaining_ms, nativeHealthProbeTimeoutMs(timeout_ms, options));
 
         for (health_selectors, 0..) |wanted, index| {
@@ -356,7 +393,47 @@ pub fn scrollUntilVisible(
     options: RunOptions,
 ) !bool {
     const deadline = stdio.nowMs() + @as(i64, @intCast(timeout_ms));
+    var native_query_failures: usize = 0;
     while (true) {
+        if (nativeSelectorQueryTimeoutMs(deadline, options)) |query_timeout_ms| {
+            var native_query_failed = false;
+            const native_result = nativeVisibleBySelector(device, wanted, query_timeout_ms) catch |err| blk: {
+                if (try recordTransientNativeSelectorObservation(err, "ui.scrollUntilVisible", writer)) {
+                    native_query_failures += 1;
+                    if (native_query_failures <= native_selector_transient_retry_limit and stdio.nowMs() < deadline) {
+                        try sleepMs(options.poll_ms);
+                        continue;
+                    }
+                    native_query_failed = true;
+                    break :blk null;
+                }
+                return err;
+            };
+            if (!native_query_failed) native_query_failures = 0;
+            if (!native_query_failed) {
+                if (native_result) |visible| {
+                    if (visible) {
+                        if (writer) |tw| try runner_events.recordNativeScrollUntilVisible(
+                            tw,
+                            wanted,
+                            if (direction == .down) "down" else "up",
+                            timeout_ms,
+                        );
+                        return true;
+                    }
+                    if (stdio.nowMs() >= deadline) {
+                        if (writer) |tw| try runner_events.recordNativeWaitTimeoutWithDiagnostics(device, tw, "ui.scrollUntilVisible", &[_]selector.Selector{wanted}, timeout_ms);
+                        return false;
+                    }
+                    try scrollDevice(device, direction, writer, options);
+                    continue;
+                }
+            }
+        } else if (hasNativeSelectorQuery(device)) {
+            if (writer) |tw| try runner_events.recordNativeWaitTimeoutWithDiagnostics(device, tw, "ui.scrollUntilVisible", &[_]selector.Selector{wanted}, timeout_ms);
+            return false;
+        }
+
         var snap = device.snapshot(writer) catch |err| {
             if (try retryTransientObservation(err, "ui.scrollUntilVisible", writer, deadline, options)) continue;
             return err;
@@ -385,29 +462,7 @@ pub fn scrollUntilVisible(
             return false;
         }
 
-        const width = if (snap.viewport.width == 0) @as(i32, 720) else @as(i32, @intCast(snap.viewport.width));
-        const height = if (snap.viewport.height == 0) @as(i32, 1280) else @as(i32, @intCast(snap.viewport.height));
-        const x = @divTrunc(width, 2);
-        const start_y = switch (direction) {
-            .down => @divTrunc(height * 4, 5),
-            .up => @divTrunc(height * 3, 10),
-        };
-        const end_y = switch (direction) {
-            .down => @divTrunc(height * 3, 10),
-            .up => @divTrunc(height * 4, 5),
-        };
-        try device.swipe(x, start_y, x, end_y, 350);
-        if (writer) |tw| {
-            const payload = try std.fmt.allocPrint(tw.allocator, "{{\"direction\":\"{s}\",\"x\":{d},\"y1\":{d},\"y2\":{d}}}", .{
-                if (direction == .down) "down" else "up",
-                x,
-                start_y,
-                end_y,
-            });
-            defer tw.allocator.free(payload);
-            try tw.recordEvent("ui.scroll", payload);
-        }
-        try settleDevice(device, options);
+        try scrollDeviceWithViewport(device, direction, writer, options, snap.viewport);
     }
 }
 
@@ -421,7 +476,13 @@ fn nativeVisibleBySelector(device: anytype, wanted: selector.Selector, timeout_m
     return try device.visibleBySelector(wanted);
 }
 
-fn nativeSelectorQueryTimeoutMs(deadline: i64) ?u64 {
+fn nativeSelectorQueryTimeoutMs(deadline: i64, options: RunOptions) ?u64 {
+    const remaining_ms = nativeSelectorRemainingTimeoutMs(deadline) orelse return null;
+    if (options.action_timeout_ms == 0) return remaining_ms;
+    return @max(@as(u64, 1), @min(remaining_ms, options.action_timeout_ms));
+}
+
+fn nativeSelectorRemainingTimeoutMs(deadline: i64) ?u64 {
     const now = stdio.nowMs();
     if (now >= deadline) return null;
     return @as(u64, @intCast(deadline - now));
@@ -434,6 +495,16 @@ fn nativeHealthProbeTimeoutMs(timeout_ms: u64, options: RunOptions) u64 {
     return @max(probe_timeout_ms, 1);
 }
 
+fn recordTransientNativeSelectorObservation(
+    err: anyerror,
+    kind: []const u8,
+    writer: ?*trace.TraceWriter,
+) !bool {
+    if (err != error.CommandTimedOut and err != error.CommandFailed) return false;
+    if (writer) |tw| try runner_events.recordObservationRetry(tw, kind, err);
+    return true;
+}
+
 fn retryTransientObservation(
     err: anyerror,
     kind: []const u8,
@@ -448,6 +519,54 @@ fn retryTransientObservation(
     return true;
 }
 
+fn scrollDevice(
+    device: anytype,
+    direction: scenario.ScrollDirection,
+    writer: ?*trace.TraceWriter,
+    options: RunOptions,
+) !void {
+    try scrollDeviceWithViewport(device, direction, writer, options, try scrollViewport(device));
+}
+
+fn scrollViewport(device: anytype) !@import("types.zig").Viewport {
+    if (@hasDecl(@TypeOf(device.*), "scrollViewport")) {
+        return try device.scrollViewport();
+    }
+    return .{};
+}
+
+fn scrollDeviceWithViewport(
+    device: anytype,
+    direction: scenario.ScrollDirection,
+    writer: ?*trace.TraceWriter,
+    options: RunOptions,
+    viewport: @import("types.zig").Viewport,
+) !void {
+    const width = if (viewport.width == 0) @as(i32, 720) else @as(i32, @intCast(viewport.width));
+    const height = if (viewport.height == 0) @as(i32, 1280) else @as(i32, @intCast(viewport.height));
+    const x = @divTrunc(width, 2);
+    const start_y = switch (direction) {
+        .down => @divTrunc(height * 4, 5),
+        .up => @divTrunc(height * 3, 10),
+    };
+    const end_y = switch (direction) {
+        .down => @divTrunc(height * 3, 10),
+        .up => @divTrunc(height * 4, 5),
+    };
+    try device.swipe(x, start_y, x, end_y, 350);
+    if (writer) |tw| {
+        const payload = try std.fmt.allocPrint(tw.allocator, "{{\"direction\":\"{s}\",\"x\":{d},\"y1\":{d},\"y2\":{d}}}", .{
+            if (direction == .down) "down" else "up",
+            x,
+            start_y,
+            end_y,
+        });
+        defer tw.allocator.free(payload);
+        try tw.recordEvent("ui.scroll", payload);
+    }
+    try settleDevice(device, options);
+}
+
 fn settleDevice(device: anytype, options: RunOptions) !void {
     try device.settle(options.settle_ms);
 }

package/src/version.zig

@@ -1,4 +1,4 @@
-pub const runner_version = "0.2.11";
+pub const runner_version = "0.2.13";
 pub const protocol_version = "2026-04-28";
 pub const protocol_min_compatible_version = "2026-04-28";
 pub const protocol_stability = "dev-preview";