zeno-mobile-runner 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to Zeno Mobile Runner are tracked here.
 
 ## Unreleased
 
+## 0.1.3 (2026-06-03)
+
+### Fixed
+
+- Hardened the iOS XCTest shim for clean Expo/RN prebuilds by giving cold
+  `build-for-testing` runs a 90-minute default timeout with explicit progress
+  logging.
+- Made iOS simulator `app.stop` idempotent when `simctl terminate` reports the
+  app is already stopped.
+- Improved selector actions so native `selector.not_found` and
+  `selector.not_hittable` responses return a typed unavailable result instead
+  of failing the command parser.
+- Reused a resolved booted simulator UDID across `build-for-testing` and
+  `test-without-building`, and cleared stale shim PID/server/destination state
+  when reinstalling the app-local shim.
+- Avoided stale XCTest snapshot elements and replaced broad selector scans with
+  native predicate-based fallback queries.
+
 ## 0.1.2 (2026-05-28)
 
 ### Fixed

package/FEATURES.md

@@ -99,7 +99,7 @@ state, and writes deterministic traces. It does not embed an LLM.
 
 ## Current Limitations
 
-- Current release status is `0.1.2`, a public developer preview rather than
+- Current release status is `0.1.3`, 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

@@ -121,6 +121,11 @@ zmr mcp --config .zmr/config.json --trace-dir traces/zmr-agent
 The MCP server exposes mobile-specific tools such as `semantic_snapshot`, `tap`,
 `type`, `wait_visible`, `trace_events`, and `trace_export`.
 
+For agent-led discovery and test authoring, see
+[docs/agent-discovery.md](docs/agent-discovery.md). ZMR supports that loop
+through MCP and JSON-RPC today; a built-in autonomous crawler is not shipped in
+this preview.
+
 ## Optional Protocol Clients
 
 Clients are thin wrappers around `zmr serve --transport stdio`. They do not
@@ -153,7 +158,7 @@ and [docs/client-installation.md](docs/client-installation.md).
 | iOS physical device | Supported, validate locally | `devicectl` lifecycle plus app-local XCTest/XCUIAutomation shim; run pilots on your own app/device before relying on it in CI |
 | Cloud device farms | Not included | ZMR is focused on local and self-managed device targets in this preview |
 
-Current release: `0.1.2` developer preview. Protocol version:
+Current release: `0.1.3` developer preview. Protocol version:
 `2026-04-28`.
 
 ## Documentation
@@ -161,8 +166,10 @@ Current release: `0.1.2` developer preview. Protocol version:
 - [FEATURES.md](FEATURES.md): complete feature list and limitations
 - [docs/install.md](docs/install.md): source, npm, Homebrew, and app setup
 - [docs/frameworks.md](docs/frameworks.md): React Native, Expo, Flutter, and native app guidance
+- [docs/expo-smoke.md](docs/expo-smoke.md): reproducible Expo and iOS smoke test
 - [docs/app-integration.md](docs/app-integration.md): app-side Android/iOS shims
 - [docs/scenario-authoring.md](docs/scenario-authoring.md): selectors, waits, and scenario design
+- [docs/agent-discovery.md](docs/agent-discovery.md): agent-led discovery and scenario authoring loop
 - [docs/protocol.md](docs/protocol.md): JSON-RPC methods and schemas
 - [docs/ai-agents.md](docs/ai-agents.md): JSON-RPC and MCP agent workflows
 - [docs/clients.md](docs/clients.md): language client guide

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.1.2.jar"))
+implementation(files("path/to/zeno-mobile-runner/clients/kotlin/build/libs/zmr-client-0.1.3.jar"))
 ```
 
 The Kotlin client is host-side. It is useful for Android teams that want test

package/clients/kotlin/build.gradle.kts

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

package/clients/python/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "zmr-client"
-version = "0.1.2.dev1"
+version = "0.1.3.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.1.2"
+version = "0.1.3"
 dependencies = [
  "serde",
  "serde_json",

package/clients/rust/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "zmr-client"
-version = "0.1.2"
+version = "0.1.3"
 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.1.2",
+  "version": "0.1.3",
   "type": "module",
   "main": "index.mjs",
   "types": "index.d.ts",

package/docs/agent-discovery.md

@@ -0,0 +1,83 @@
+# Agent Discovery
+
+ZMR supports agent-led discovery today through its JSON-RPC and MCP interfaces.
+An external agent can observe the app, choose typed actions, inspect trace
+events, and write a repeatable scenario file as it learns a flow.
+
+ZMR does not include a built-in autonomous crawler or test writer in this
+developer preview. Keep the planning loop in the agent, and keep ZMR as the
+deterministic mobile control plane.
+
+## Recommended Loop
+
+1. Validate local setup:
+
+   ```bash
+   zmr doctor --json --config .zmr/config.json
+   zmr validate --json .zmr/ios-smoke.json
+   ```
+
+2. Start a live session:
+
+   ```bash
+   zmr serve --transport stdio --config .zmr/config.json --trace-dir traces/zmr-agent
+   ```
+
+   Agents that speak MCP can use:
+
+   ```bash
+   zmr mcp --config .zmr/config.json --trace-dir traces/zmr-agent
+   ```
+
+3. Call `runner.capabilities`, then `session.create`.
+4. Call `observe.semanticSnapshot` before choosing an action.
+5. Choose one typed action, such as `ui.tap`, `ui.type`, `app.openLink`, or
+   `wait.until`.
+6. Observe again and inspect `trace.events`.
+7. Write successful steps into a candidate scenario, for example
+   `.zmr/discovered/login-smoke.json`.
+8. Validate the candidate scenario:
+
+   ```bash
+   zmr validate --json .zmr/discovered/login-smoke.json
+   ```
+
+9. Re-run it deterministically:
+
+   ```bash
+   zmr run .zmr/discovered/login-smoke.json \
+     --platform ios \
+     --device booted \
+     --trace-dir traces/zmr-login-smoke \
+     --json
+   ```
+
+10. Export a redacted bundle before sharing artifacts:
+
+    ```bash
+    zmr export traces/zmr-login-smoke \
+      --out traces/zmr-login-smoke-redacted.zmrtrace \
+      --redact
+    ```
+
+## Guardrails
+
+- Set a step budget and a time budget before discovery starts.
+- Restrict discovery to known app ids, deep-link schemes, and test accounts.
+- Do not ask an agent to discover credentials or secrets.
+- Prefer accessibility identifiers, resource ids, stable labels, and exact text
+  over coordinates.
+- Require human review before committing generated tests.
+- Redact traces before sharing them outside the local team.
+
+## Future Shape
+
+A future command could wrap this loop:
+
+```bash
+zmr explore --goal "find the login flow" --out .zmr/discovered/login-smoke.json
+```
+
+That command is not shipped today. The safer product direction is to make
+scenario discovery explicit, reviewable, and trace-backed before it becomes a
+one-command workflow.

package/docs/ai-agents.md

@@ -68,6 +68,17 @@ The MCP server exposes mobile-specific tools:
 Prefer `semantic_snapshot` for action planning. It avoids forcing an agent to
 infer intent from platform-specific Android/UI Automator or XCTest class names.
 
+## Agent-Led Discovery
+
+Agents can use ZMR to discover flows and draft scenarios by looping over
+`observe.semanticSnapshot`, one typed action, trace events, and scenario
+validation. See [Agent Discovery](agent-discovery.md) for the recommended
+reviewable loop.
+
+ZMR does not ship a built-in autonomous crawler or test writer in this developer
+preview. Keep autonomous planning outside the runner, then commit only reviewed
+scenario JSON.
+
 ## Scenario File Workflow
 
 For repeatable tests, generate or edit `.zmr/*.json` scenarios:

package/docs/expo-smoke.md

@@ -0,0 +1,79 @@
+# Expo Smoke Test
+
+This is the quickest public smoke path for an Expo app. It proves that the npm
+package installs, the wizard scaffolds a scenario, ZMR can launch an iOS app,
+and the runner can produce screenshots, traces, HTML reports, and redacted trace
+bundles.
+
+The flow below was verified locally with `zeno-mobile-runner@0.1.3` on an iOS
+simulator.
+
+```bash
+npx create-expo-app@latest /tmp/zmr-expo-smoke --template blank --yes
+cd /tmp/zmr-expo-smoke
+npm install --save-dev zeno-mobile-runner
+
+npx zmr-wizard --yes --dir . \
+  --app-id com.example.zenoexposmoke \
+  --ios \
+  --package-json
+```
+
+Boot a simulator, then build and launch the app:
+
+```bash
+xcrun simctl boot <simulator-udid>
+npx expo run:ios --device <simulator-name>
+```
+
+Run the generated ZMR scenario:
+
+```bash
+npx zmr run .zmr/ios-smoke.json \
+  --platform ios \
+  --device booted \
+  --trace-dir traces/zmr-ios \
+  --json
+
+npx zmr report traces/zmr-ios --out traces/zmr-ios/report.html
+npx zmr export traces/zmr-ios --out traces/zmr-ios-redacted.zmrtrace --redact
+```
+
+Expected result shape:
+
+```json
+{
+  "ok": true,
+  "status": "passed",
+  "scenario": "iOS smoke",
+  "appId": "com.example.zenoexposmoke",
+  "traceDir": "traces/zmr-ios",
+  "eventCount": 8,
+  "snapshotCount": 2,
+  "partialFailureCount": 0
+}
+```
+
+This smoke validates the platform-level loop: app launch, health check,
+screenshot capture, trace collection, report generation, and redacted export.
+For selector-grade React Native or Expo assertions on iOS, add the XCTest shim
+described in [app integration](app-integration.md).
+
+Android follows the same pattern with a connected emulator or device:
+
+```bash
+npx zmr-wizard --yes --dir . \
+  --app-id com.example.zenoexposmoke \
+  --android \
+  --package-json
+
+npx zmr run .zmr/android-smoke.json \
+  --platform android \
+  --device emulator-5554 \
+  --trace-dir traces/zmr-android \
+  --json
+```
+
+Do not commit traces, screenshots, bundle identifiers, private app names, or
+credentials from a real product app. Use `zmr export --redact`, and add
+`--omit-screenshots` when visual artifacts may contain sensitive data.

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

@@ -1,4 +1,4 @@
-{"jsonrpc":"2.0","id":1,"result":{"name":"zmr","version":"0.1.2","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","trace.events","trace.export"]}}
+{"jsonrpc":"2.0","id":1,"result":{"name":"zmr","version":"0.1.3","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","trace.events","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.1.2`.
+Current runner version: `0.1.3`.
 
 Current protocol version: `2026-04-28`.
 
@@ -133,7 +133,7 @@ installers, setup scripts, and generated clients. The response is covered by
 `schemas/version-output.schema.json`:
 
 ```json
-{"name":"zmr","version":"0.1.2","protocolVersion":"2026-04-28","minimumCompatibleProtocolVersion":"2026-04-28","stability":"dev-preview","breakingChangePolicy":"version-and-changelog"}
+{"name":"zmr","version":"0.1.3","protocolVersion":"2026-04-28","minimumCompatibleProtocolVersion":"2026-04-28","stability":"dev-preview","breakingChangePolicy":"version-and-changelog"}
 ```
 
 ## Capabilities Output Contract
@@ -145,7 +145,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.1.2","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","observe.snapshot","observe.semanticSnapshot"]}
+{"name":"zmr","version":"0.1.3","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","observe.snapshot","observe.semanticSnapshot"]}
 ```
 
 ## Doctor Output Contract
@@ -347,7 +347,7 @@ Request:
 Response:
 
 ```json
-{"jsonrpc":"2.0","id":1,"result":{"name":"zmr","version":"0.1.2","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","trace.events","trace.export"]}}
+{"jsonrpc":"2.0","id":1,"result":{"name":"zmr","version":"0.1.3","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","trace.events","trace.export"]}}
 ```
 
 ### `trace.events`

package/npm/build-zmr.mjs

@@ -5,7 +5,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
-const out = path.join(root, "zig-out", "bin", process.platform === "win32" ? "zmr.exe" : "zmr");
+const out = process.env.ZMR_BUILD_OUT || path.join(root, "zig-out", "bin", process.platform === "win32" ? "zmr.exe" : "zmr");
 fs.mkdirSync(path.dirname(out), { recursive: true });
 
 const args = ["build-exe", "src/main.zig", "-O", "ReleaseSafe", `-femit-bin=${out}`];

package/npm/postinstall.mjs

@@ -1,21 +1,47 @@
 #!/usr/bin/env node
 import { spawnSync } from "node:child_process";
+import fs from "node:fs";
 import { resolveBinary } from "./index.mjs";
 
-if (resolveBinary()) process.exit(0);
+const pkg = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+const binary = resolveBinary();
+
+if (binary && binaryMatchesPackageVersion(binary, pkg.version)) process.exit(0);
+if (binary && process.env.ZMR_BIN) {
+  console.warn(`zeno-mobile-runner: ZMR_BIN points to a zmr binary that does not report package version ${pkg.version}: ${binary}`);
+  process.exit(0);
+}
 if (process.env.ZMR_SKIP_POSTINSTALL_BUILD === "1") process.exit(0);
 
 const hasZig = spawnSync("zig", ["version"], { stdio: "ignore" }).status === 0;
 if (!hasZig) {
-  console.warn("zeno-mobile-runner: no prebuilt zmr binary found and Zig is not installed.");
+  if (binary) {
+    console.warn(`zeno-mobile-runner: prebuilt zmr binary does not report package version ${pkg.version}: ${binary}`);
+  } else {
+    console.warn("zeno-mobile-runner: no prebuilt zmr binary found and Zig is not installed.");
+  }
   console.warn("zeno-mobile-runner: install a release package with prebuilds, install Zig and run `npm run build:zmr`, or set ZMR_BIN.");
   process.exit(0);
 }
 
 const result = spawnSync(process.execPath, [new URL("./build-zmr.mjs", import.meta.url).pathname], {
   stdio: "inherit",
+  env: {
+    ...process.env,
+    ...(binary ? { ZMR_BUILD_OUT: binary } : {}),
+  },
 });
 
 if (result.status !== 0) {
   console.warn("zeno-mobile-runner: postinstall build failed; set ZMR_BIN or run `npm run build:zmr` after fixing Zig.");
 }
+
+function binaryMatchesPackageVersion(binaryPath, expectedVersion) {
+  const result = spawnSync(binaryPath, ["version", "--json"], { encoding: "utf8" });
+  if (result.status !== 0) return false;
+  try {
+    return JSON.parse(result.stdout).version === expectedVersion;
+  } catch {
+    return false;
+  }
+}

package/npm/verify-publish.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+const exe = process.platform === "win32" ? "zmr.exe" : "zmr";
+const hostPrebuild = path.join(root, "prebuilds", `${process.platform}-${process.arch}`, exe);
+
+if (!fs.existsSync(hostPrebuild)) {
+  fail(`missing host prebuild for ${process.platform}-${process.arch}: ${hostPrebuild}`);
+}
+
+const version = spawnSync(hostPrebuild, ["version", "--json"], { encoding: "utf8" });
+if (version.status !== 0) {
+  fail(`host prebuild is not runnable: ${hostPrebuild}`);
+}
+
+let actual;
+try {
+  actual = JSON.parse(version.stdout).version;
+} catch {
+  fail(`host prebuild did not return valid version JSON: ${hostPrebuild}`);
+}
+
+if (actual !== pkg.version) {
+  fail(`host prebuild reports ${actual}, expected ${pkg.version}: ${hostPrebuild}`);
+}
+
+function fail(message) {
+  console.error(`zeno-mobile-runner: ${message}`);
+  console.error("zeno-mobile-runner: run `npm run pack:npm` before publishing so prebuilds match package.json.");
+  process.exit(1);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zeno-mobile-runner",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Agent-native mobile app test runner for React Native, Expo, Flutter, and native Android/iOS.",
   "main": "npm/index.mjs",
   "repository": {
@@ -92,6 +92,7 @@
   ],
   "scripts": {
     "postinstall": "node npm/postinstall.mjs",
+    "prepublishOnly": "node npm/verify-publish.mjs",
     "build:zmr": "node npm/build-zmr.mjs",
     "pack:npm": "bash scripts/build-npm-package.sh",
     "zmr:demo": "node npm/zmr.mjs validate examples/demo-fake.json",

package/scripts/install-ios-shim.sh

@@ -167,6 +167,10 @@ mkdir -p "$APP_ROOT"
 APP_ROOT="$(cd "$APP_ROOT" && pwd)"
 mkdir -p "$APP_ROOT/.zmr" "$APP_ROOT/.zmr/shims/ios"
 rm -f "$APP_ROOT/.zmr/ios-shim-state/build-for-testing.ready"
+rm -f "$APP_ROOT/.zmr/ios-shim-state/destination.id"
+rm -f "$APP_ROOT/.zmr/ios-shim-state/xcodebuild.pid"
+rm -f "$APP_ROOT/.zmr/ios-shim-state/xcodebuild.log"
+rm -rf "$APP_ROOT/.zmr/ios-shim-state/server"
 cp "$ROOT/shims/ios/ZMRShim.swift" "$APP_ROOT/.zmr/shims/ios/ZMRShim.swift"
 cp "$ROOT/shims/ios/ZMRShimUITestCase.swift" "$APP_ROOT/.zmr/ZMRShimUITestCase.swift"
 cp "$ROOT/scripts/ensure-ios-shim-target.rb" "$APP_ROOT/.zmr/ensure-ios-shim-target.rb"
@@ -216,6 +220,7 @@ STATE_DIR="$APP_ROOT/.zmr/ios-shim-state"
 SERVER_DIR="\$STATE_DIR/server"
 PID_FILE="\$STATE_DIR/xcodebuild.pid"
 READY_FILE="\$SERVER_DIR/ready"
+DESTINATION_ID_FILE="\$STATE_DIR/destination.id"
 BUILD_READY_FILE="\$STATE_DIR/build-for-testing.ready"
 LOG_FILE="\$STATE_DIR/xcodebuild.log"
 STDIN_FILE="\$(mktemp)"
@@ -241,6 +246,52 @@ tail_log() {
   fi
 }
 
+tail_log_path() {
+  local log_file="\$1"
+  if [[ -f "\$log_file" ]]; then
+    tail -120 "\$log_file" >&2
+  fi
+}
+
+run_xcodebuild_with_timeout() {
+  local label="\$1"
+  local timeout_seconds="\$2"
+  local log_file="\$3"
+  shift 3
+
+  local pid started_at next_progress progress_seconds elapsed
+  progress_seconds="\${ZMR_IOS_SHIM_PROGRESS_SECONDS:-30}"
+  "\$@" >"\$log_file" 2>&1 &
+  pid="\$!"
+  started_at="\$SECONDS"
+  next_progress=\$((started_at + progress_seconds))
+
+  while kill -0 "\$pid" 2>/dev/null; do
+    elapsed=\$((SECONDS - started_at))
+    if (( elapsed >= timeout_seconds )); then
+      echo "timed out waiting for \$label after \${timeout_seconds}s" >&2
+      kill -TERM "\$pid" 2>/dev/null || true
+      sleep 2
+      if kill -0 "\$pid" 2>/dev/null; then
+        kill -KILL "\$pid" 2>/dev/null || true
+      fi
+      wait "\$pid" 2>/dev/null || true
+      tail_log_path "\$log_file"
+      exit 1
+    fi
+    if (( SECONDS >= next_progress )); then
+      echo "still waiting for \$label after \${elapsed}s; log: \$log_file" >&2
+      next_progress=\$((SECONDS + progress_seconds))
+    fi
+    sleep 1
+  done
+
+  if ! wait "\$pid"; then
+    tail_log_path "\$log_file"
+    exit 1
+  fi
+}
+
 resolve_destination() {
   local destination_id="$DEVICE"
   if [[ "\$destination_id" == "booted" ]]; then
@@ -248,7 +299,20 @@ resolve_destination() {
       echo "physical iOS shim requires an explicit --device id" >&2
       exit 2
     fi
+    if [[ -f "\$DESTINATION_ID_FILE" ]]; then
+      destination_id="\$(cat "\$DESTINATION_ID_FILE" 2>/dev/null || true)"
+      if [[ -n "\$destination_id" ]] && xcrun simctl list devices available | grep -F "\$destination_id" >/dev/null 2>&1; then
+        # Reuse the first resolved booted simulator so build-for-testing and
+        # test-without-building target the same simulator even if it shuts down
+        # while Xcode is compiling the shim target.
+        printf '%s' "\$destination_id"
+        return 0
+      fi
+    fi
     destination_id="\$(xcrun simctl list devices booted | sed -n 's/.*(\([0-9A-Fa-f-][0-9A-Fa-f-]*\)) (Booted).*/\1/p' | head -n 1)"
+    if [[ -n "\$destination_id" ]]; then
+      printf '%s' "\$destination_id" > "\$DESTINATION_ID_FILE"
+    fi
   fi
   if [[ -z "\$destination_id" ]]; then
     echo "no booted iOS simulator found" >&2
@@ -272,9 +336,13 @@ is_server_running() {
   if [[ ! -f "\$PID_FILE" ]]; then
     return 1
   fi
-  local pid
+  local pid command
   pid="\$(cat "\$PID_FILE" 2>/dev/null || true)"
-  [[ -n "\$pid" ]] && kill -0 "\$pid" 2>/dev/null
+  if [[ -z "\$pid" ]] || ! kill -0 "\$pid" 2>/dev/null; then
+    return 1
+  fi
+  command="\$(ps -p "\$pid" -o command= 2>/dev/null || true)"
+  [[ "\$command" == *xcodebuild* && "\$command" == *ZMRShimUITests* ]]
 }
 
 run_oneshot() {
@@ -332,18 +400,15 @@ build_for_testing() {
   destination_id="\$(destination_spec)"
   build_log="\$STATE_DIR/xcodebuild.build.log"
 
-  if ! xcodebuild build-for-testing \\
-    "\${XCODEBUILD_ARGS[@]}" \\
-    -scheme "$SCHEME" \\
-    -configuration "$CONFIGURATION" \\
-    -destination "\$destination_id" \\
-    ZMR_SHIM_MODE="server" \\
-    ZMR_SHIM_SERVER_DIR="\$SERVER_DIR" \\
-    ZMR_APP_BUNDLE_ID="$BUNDLE_ID" \\
-    >"\$build_log" 2>&1; then
-    tail -120 "\$build_log" >&2
-    exit 1
-  fi
+  run_xcodebuild_with_timeout "iOS shim build-for-testing" "\${ZMR_IOS_SHIM_BUILD_TIMEOUT_SECONDS:-5400}" "\$build_log" \\
+    xcodebuild build-for-testing \\
+      "\${XCODEBUILD_ARGS[@]}" \\
+      -scheme "$SCHEME" \\
+      -configuration "$CONFIGURATION" \\
+      -destination "\$destination_id" \\
+      ZMR_SHIM_MODE="server" \\
+      ZMR_SHIM_SERVER_DIR="\$SERVER_DIR" \\
+      ZMR_APP_BUNDLE_ID="$BUNDLE_ID"
 
   touch "\$BUILD_READY_FILE"
 }

package/shims/ios/ZMRShim.swift

@@ -58,6 +58,9 @@ enum ZMRShim {
                 guard nodes.count < 256 else {
                     return nodes
                 }
+                guard element.exists else {
+                    continue
+                }
                 nodes.append(node(index: nodes.count, type: type, element: element))
             }
         }

package/shims/ios/ZMRShimUITestCase.swift

@@ -128,7 +128,7 @@ final class ZMRShimUITestCase: XCTestCase {
             guard isFastQueryable(parts: parts) else {
                 return error("selector.unsupported", "unsupported query selector: \(selector)")
             }
-            let element = resolveFastElement(selector: selector, app: app, preferredTypes: [])
+            let element = resolveElement(selector: selector, app: app, preferredTypes: [])
             return [
                 "status": "ok",
                 "exists": element?.exists ?? false,
@@ -328,19 +328,49 @@ final class ZMRShimUITestCase: XCTestCase {
             return fast
         }
 
-        let matchedElements = app.descendants(matching: .any).allElementsBoundByIndex.filter { element in
-            matches(selector: selector, element: element)
-        }
-        if let preferred = matchedElements.first(where: { preferredTypes.contains($0.elementType) && $0.isHittable }) {
-            return preferred
+        return resolveBroadElement(selector: selector, app: app)
+    }
+
+    private func resolveBroadElement(selector: String, app: XCUIApplication) -> XCUIElement? {
+        guard let parts = selectorParts(selector) else {
+            return nil
         }
-        if let preferred = matchedElements.first(where: { preferredTypes.contains($0.elementType) }) {
-            return preferred
+
+        let query: XCUIElementQuery?
+        switch parts.field {
+        case "text", "label":
+            let predicate = parts.contains
+                ? NSPredicate(format: "label CONTAINS[c] %@", parts.value)
+                : NSPredicate(format: "label == %@", parts.value)
+            query = app.descendants(matching: .any).matching(predicate)
+        case "identifier", "resourceId":
+            let predicate = parts.contains
+                ? NSPredicate(format: "identifier CONTAINS[c] %@", parts.value)
+                : NSPredicate(format: "identifier == %@", parts.value)
+            query = app.descendants(matching: .any).matching(predicate)
+        case "value":
+            let predicate = parts.contains
+                ? NSPredicate(format: "value CONTAINS[c] %@", parts.value)
+                : NSPredicate(format: "value == %@", parts.value)
+            query = app.descendants(matching: .any).matching(predicate)
+        case "id":
+            if parts.value.hasPrefix("id:") {
+                let identifier = String(parts.value.dropFirst("id:".count))
+                query = app.descendants(matching: .any).matching(identifier: identifier)
+            } else if parts.value.hasPrefix("label:") {
+                let label = String(parts.value.dropFirst("label:".count))
+                query = app.descendants(matching: .any).matching(NSPredicate(format: "label == %@", label))
+            } else {
+                query = nil
+            }
+        default:
+            query = nil
         }
-        if let hittable = matchedElements.first(where: { $0.isHittable }) {
-            return hittable
+
+        guard let element = query?.firstMatch, element.exists else {
+            return nil
         }
-        return matchedElements.first
+        return element
     }
 
     private func resolveFastElement(selector: String, app: XCUIApplication, preferredTypes: [XCUIElement.ElementType]) -> XCUIElement? {

package/src/ios.zig

@@ -9,7 +9,9 @@ const trace = @import("trace.zig");
 const types = @import("types.zig");
 
 const default_max_output = 32 * 1024 * 1024;
-const shim_timeout_ms = 600_000;
+// Clean iOS prebuilds can force the XCTest shim script through a full native
+// dependency build before it can answer the first selector query.
+const shim_timeout_ms = 5_400_000;
 const shim_best_effort_timeout_ms = 10_000;
 const shim_command_attempts = 2;
 const shim_bootstrap_retry_delay_ms = 500;
@@ -107,6 +109,7 @@ pub const IosDevice = struct {
         if (self.target_kind == .physical) return try self.stopPhysicalBestEffort();
         const result = try self.runSimctl(&.{ "terminate", self.target(), self.app_id }, default_max_output);
         defer result.deinit(self.allocator);
+        if (ios_lifecycle.isAppNotRunning(result)) return;
         try result.ensureSuccess();
     }
 
@@ -307,8 +310,12 @@ pub const IosDevice = struct {
 
         var command_with_selector = shim_command;
         command_with_selector.selector = shim_selector;
-        try self.runShimAction(command_with_selector);
-        return true;
+        const response = try self.runShim(command_with_selector);
+        defer self.allocator.free(response);
+        return switch (try ios_shim.parseSelectorActionResponse(response)) {
+            .ok => true,
+            .selector_unavailable => false,
+        };
     }
 
     fn runShim(self: *IosDevice, shim_command: ios_shim.Command) ![]u8 {
@@ -394,6 +401,6 @@ pub fn parsePhysicalDevicesJson(allocator: std.mem.Allocator, content: []const u
 }
 
 test "ios xctest shim timeout allows cold xcodebuild startup" {
-    try std.testing.expect(shim_timeout_ms >= 300_000);
+    try std.testing.expect(shim_timeout_ms >= 5_400_000);
     try std.testing.expect(shim_best_effort_timeout_ms <= 15_000);
 }

package/src/ios_lifecycle.zig

@@ -70,3 +70,39 @@ pub fn isMissingInstalledApp(result: command.ExecResult) bool {
     }
     return std.mem.indexOf(u8, result.stderr, "No installed application with bundle identifier") != null;
 }
+
+pub fn isAppNotRunning(result: command.ExecResult) bool {
+    switch (result.term) {
+        .Exited => |code| if (code == 0) return false,
+        else => return false,
+    }
+    return std.mem.indexOf(u8, result.stderr, "found nothing to terminate") != null;
+}
+
+test "simctl terminate missing running app is best-effort" {
+    const allocator = std.testing.allocator;
+    const stdout = try allocator.dupe(u8, "");
+    defer allocator.free(stdout);
+    const stderr = try allocator.dupe(u8, "The request to terminate \"com.example.mobiletest\" failed. found nothing to terminate");
+    defer allocator.free(stderr);
+
+    try std.testing.expect(isAppNotRunning(.{
+        .stdout = stdout,
+        .stderr = stderr,
+        .term = .{ .Exited = 3 },
+    }));
+}
+
+test "simctl terminate success is not classified as already stopped" {
+    const allocator = std.testing.allocator;
+    const stdout = try allocator.dupe(u8, "");
+    defer allocator.free(stdout);
+    const stderr = try allocator.dupe(u8, "");
+    defer allocator.free(stderr);
+
+    try std.testing.expect(!isAppNotRunning(.{
+        .stdout = stdout,
+        .stderr = stderr,
+        .term = .{ .Exited = 0 },
+    }));
+}

package/src/ios_shim.zig

@@ -109,6 +109,48 @@ pub fn parseOkResponse(content: []const u8) !void {
     if (!std.mem.eql(u8, status, "ok")) return error.IosShimResponseNotOk;
 }
 
+pub const SelectorActionResponse = enum {
+    ok,
+    selector_unavailable,
+};
+
+pub fn parseSelectorActionResponse(content: []const u8) !SelectorActionResponse {
+    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 .ok;
+
+    const code = fieldString(parsed.value.object, "code") orelse return error.IosShimResponseNotOk;
+    if (std.mem.eql(u8, code, "selector.not_found") or
+        std.mem.eql(u8, code, "selector.not_hittable"))
+    {
+        return .selector_unavailable;
+    }
+
+    return error.IosShimResponseNotOk;
+}
+
+test "selector action response maps native selector misses to unavailable" {
+    try std.testing.expectEqual(SelectorActionResponse.ok, try parseSelectorActionResponse("{\"status\":\"ok\"}"));
+    try std.testing.expectEqual(
+        SelectorActionResponse.selector_unavailable,
+        try parseSelectorActionResponse("{\"status\":\"error\",\"code\":\"selector.not_found\",\"message\":\"missing\"}"),
+    );
+    try std.testing.expectEqual(
+        SelectorActionResponse.selector_unavailable,
+        try parseSelectorActionResponse("{\"status\":\"error\",\"code\":\"selector.not_hittable\",\"message\":\"covered\"}"),
+    );
+}
+
+test "selector action response keeps unsupported selectors as hard errors" {
+    try std.testing.expectError(
+        error.IosShimResponseNotOk,
+        parseSelectorActionResponse("{\"status\":\"error\",\"code\":\"selector.unsupported\",\"message\":\"bad\"}"),
+    );
+}
+
 pub fn parseQueryResponse(content: []const u8) !bool {
     var arena = std.heap.ArenaAllocator.init(std.heap.page_allocator);
     defer arena.deinit();

package/src/version.zig

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