zeno-mobile-runner 0.2.14 → 0.2.16

package/CHANGELOG.md

@@ -4,6 +4,29 @@ All notable changes to Zeno Mobile Runner are tracked here.
 
 ## Unreleased
 
+## 0.2.16 (2026-06-25)
+
+### Fixed
+
+- iOS Expo dev-client custom-link recovery now reopens matched project entries
+  from observed launcher state instead of reporting blind coordinate taps as
+  accepted. Visible but non-hittable launcher rows are tapped by their matched
+  frame, keeping recovery selector/state based.
+- Generated iOS shim commands now fingerprint shim inputs and preserve reusable
+  app/Pods build outputs. Reinstalls reuse unchanged `build-for-testing`
+  products, and stale cleanup removes only ZMR shim products/intermediates.
+
+## 0.2.15 (2026-06-24)
+
+### Fixed
+
+- Generated iOS shim commands now remove app-local ZMR-owned derived data paths
+  ending in `ZMRDerivedData` before `build-for-testing` refreshes. This avoids
+  reusing stale Xcode absolute paths when app checkouts are copied, while
+  refusing to delete arbitrary shared DerivedData locations.
+- Release gates now verify that `ZMR_VERSION`, `package.json`, `src/version.zig`,
+  archive names, and release-smoked binaries agree before publishing.
+
 ## 0.2.14 (2026-06-23)
 
 ### Added

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.14`, a public developer preview rather than
+- Current release status is `0.2.16`, 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

@@ -199,7 +199,7 @@ comparisons against your current E2E tool, and multi-device matrices, see
 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.14` developer preview.
+process ceiling. Current release: `0.2.16` 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.14.jar"))
+implementation(files("path/to/zeno-mobile-runner/clients/kotlin/build/libs/zmr-client-0.2.16.jar"))
 ```
 
 ```kotlin

package/clients/kotlin/build.gradle.kts

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

package/clients/python/pyproject.toml

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

package/clients/rust/Cargo.toml

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

package/docs/app-integration.md

@@ -101,6 +101,10 @@ with `--ios-shim`. It caches `build-for-testing` output and uses
 `test-without-building` for selector commands through `.zmr/ios-shim-state/`.
 Set `ZMR_IOS_SHIM_FORCE_REBUILD=1` after app-side target changes, or
 `ZMR_IOS_SHIM_ONESHOT=1` when you need to debug the slower cold-start path.
+When `--derived-data-path` points at a ZMR-owned path ending in
+`ZMRDerivedData`, the generated shim removes that directory before each
+`build-for-testing` refresh so copied app checkouts do not reuse stale absolute
+Xcode paths. It refuses to delete arbitrary shared DerivedData locations.
 
 ## Recommended App Repo Layout
 

package/docs/npm.md

@@ -333,7 +333,10 @@ The generated command caches `build-for-testing` output under
 prints the last Xcode log lines when XCTest fails. Set
 `ZMR_IOS_SHIM_FORCE_REBUILD=1` after app-side target changes, or
 `ZMR_IOS_SHIM_ONESHOT=1` for a cold-start fallback while debugging app-side Xcode
-wiring.
+wiring. When `--derived-data-path` points at a ZMR-owned path ending in
+`ZMRDerivedData`, the generated command removes that directory before each
+`build-for-testing` refresh so copied app checkouts do not reuse stale absolute
+Xcode paths. It refuses to delete arbitrary shared DerivedData locations.
 
 ## Native Binary Resolution
 

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

@@ -1,4 +1,4 @@
-{"jsonrpc":"2.0","id":1,"result":{"name":"zmr","version":"0.2.14","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.16","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.14`.
+Current runner version: `0.2.16`.
 
 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.14","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.16","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.14","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.16","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.14","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.16","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.14","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.16","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.14","protocolVersion":"2026-04-28","minimumCompatibleProtocolVersion":"2026-04-28","stability":"dev-preview","breakingChangePolicy":"version-and-changelog"}
+{"name":"zmr","version":"0.2.16","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.14","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.16","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
@@ -433,7 +433,7 @@ Request:
 Response:
 
 ```json
-{"jsonrpc":"2.0","id":1,"result":{"name":"zmr","version":"0.2.14","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.16","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`
@@ -515,7 +515,7 @@ Request:
 Response:
 
 ```json
-{"jsonrpc":"2.0","id":25,"result":{"ok":true,"mode":"discover","schemaVersion":1,"runnerVersion":"0.2.14","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.16","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
@@ -538,7 +538,7 @@ Request:
 Response:
 
 ```json
-{"jsonrpc":"2.0","id":27,"result":{"ok":true,"mode":"explore","schemaVersion":1,"runnerVersion":"0.2.14","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.16","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

@@ -208,8 +208,10 @@ This avoids failing the whole demo when one local simulator cannot start
 `launchd_sim`, while still surfacing a setup error if every available simulator
 fails to boot.
 
-If a previous Xcode build was interrupted, remove only the app-local ZMR derived
-data path configured for the shim, then rerun the shim once to prewarm it:
+The generated shim now removes app-local ZMR derived data paths ending in
+`ZMRDerivedData` before each `build-for-testing` refresh. If you intentionally
+configured a different shared DerivedData path, clean only the app-local ZMR
+cache you own, then rerun the shim once to prewarm it:
 
 ```bash
 rm -rf ios/build/ZMRDerivedData

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zeno-mobile-runner",
-  "version": "0.2.14",
+  "version": "0.2.16",
   "description": "Agent-native mobile app test runner for React Native, Expo, Flutter, and native Android/iOS.",
   "main": "npm/index.mjs",
   "repository": {
@@ -82,6 +82,7 @@
     "!scripts/release-candidate.sh",
     "!scripts/release-gate.sh",
     "!scripts/release-smoke.sh",
+    "!scripts/verify-release-version.sh",
     "!scripts/sign-macos-release.sh",
     "!scripts/verify-release-artifacts.sh",
     "!scripts/__pycache__/",

package/scripts/install-ios-shim.sh

@@ -165,8 +165,28 @@ fi
 
 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"
+SHIM_INSTALL_FINGERPRINT="$(
+  {
+    printf '%s\n' \
+      "$SCHEME" \
+      "$TEST_TARGET" \
+      "$TEST_BUNDLE_ID" \
+      "$WORKSPACE" \
+      "$PROJECT" \
+      "$APP_TARGET" \
+      "$BUNDLE_ID" \
+      "$DERIVED_DATA_PATH" \
+      "$DEVICE_TYPE" \
+      "$CONFIGURATION" \
+      "$DEPLOYMENT_TARGET"
+    shasum -a 256 \
+      "$ROOT/scripts/install-ios-shim.sh" \
+      "$ROOT/scripts/ensure-ios-shim-target.rb" \
+      "$ROOT/shims/ios/ZMRShim.swift" \
+      "$ROOT/shims/ios/ZMRShimUITestCase.swift"
+  } | shasum -a 256 | awk '{print $1}'
+)"
+mkdir -p "$APP_ROOT/.zmr" "$APP_ROOT/.zmr/shims/ios" "$APP_ROOT/.zmr/ios-shim-state"
 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"
@@ -222,7 +242,13 @@ 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"
+BUILD_FINGERPRINT_FILE="\$STATE_DIR/build-for-testing.fingerprint"
+DERIVED_DATA_CLEAN_FINGERPRINT_FILE="\$STATE_DIR/derived-data-clean.fingerprint"
 LOG_FILE="\$STATE_DIR/xcodebuild.log"
+DERIVED_DATA_PATH_VALUE="$DERIVED_DATA_PATH"
+INSTALL_FINGERPRINT_VALUE="$SHIM_INSTALL_FINGERPRINT"
+ZMR_TEST_TARGET_NAME="$TEST_TARGET"
+ZMR_SCHEME_NAME="$SCHEME"
 STDIN_FILE="\$(mktemp)"
 trap 'rm -f "\$STDIN_FILE"' EXIT
 
@@ -332,6 +358,40 @@ destination_spec() {
   printf 'platform=%s,id=%s' "\$platform_name" "\$destination_id"
 }
 
+clean_zmr_derived_data() {
+  if [[ -z "\$DERIVED_DATA_PATH_VALUE" ]]; then
+    return 0
+  fi
+  if [[ "\${ZMR_IOS_SHIM_FORCE_REBUILD:-}" != "1" && -f "\$DERIVED_DATA_CLEAN_FINGERPRINT_FILE" ]] && [[ "\$(cat "\$DERIVED_DATA_CLEAN_FINGERPRINT_FILE" 2>/dev/null || true)" == "\$INSTALL_FINGERPRINT_VALUE" ]]; then
+    return 0
+  fi
+
+  local derived_data_abs
+  if [[ "\$DERIVED_DATA_PATH_VALUE" == /* ]]; then
+    derived_data_abs="\$DERIVED_DATA_PATH_VALUE"
+  else
+    derived_data_abs="$APP_ROOT/\$DERIVED_DATA_PATH_VALUE"
+  fi
+  while [[ "\$derived_data_abs" == */ && "\$derived_data_abs" != "/" ]]; do
+    derived_data_abs="\${derived_data_abs%/}"
+  done
+
+  case "\$derived_data_abs" in
+    "$APP_ROOT/ZMRDerivedData"|"$APP_ROOT"/*/ZMRDerivedData)
+      if [[ -d "\$derived_data_abs/Build/Products" ]]; then
+        find "\$derived_data_abs/Build/Products" -depth \\( -name "\$ZMR_TEST_TARGET_NAME*" -o -name "\$ZMR_SCHEME_NAME*" \\) -exec rm -rf {} +
+      fi
+      if [[ -d "\$derived_data_abs/Build/Intermediates.noindex" ]]; then
+        find "\$derived_data_abs/Build/Intermediates.noindex" -depth \\( -name "\$ZMR_TEST_TARGET_NAME.build" -o -name "\$ZMR_SCHEME_NAME.build" \\) -exec rm -rf {} +
+      fi
+      printf '%s\\n' "\$INSTALL_FINGERPRINT_VALUE" > "\$DERIVED_DATA_CLEAN_FINGERPRINT_FILE"
+      ;;
+    *)
+      echo "warning: refusing to delete non-ZMR derived data path: \$DERIVED_DATA_PATH_VALUE" >&2
+      ;;
+  esac
+}
+
 is_server_running() {
   if [[ ! -f "\$PID_FILE" ]]; then
     return 1
@@ -392,13 +452,14 @@ wait_for_ready() {
 }
 
 build_for_testing() {
-  if [[ "\${ZMR_IOS_SHIM_FORCE_REBUILD:-}" != "1" && -f "\$BUILD_READY_FILE" ]]; then
+  if [[ "\${ZMR_IOS_SHIM_FORCE_REBUILD:-}" != "1" && -f "\$BUILD_READY_FILE" && -f "\$BUILD_FINGERPRINT_FILE" ]] && [[ "\$(cat "\$BUILD_FINGERPRINT_FILE" 2>/dev/null || true)" == "\$INSTALL_FINGERPRINT_VALUE" ]]; then
     return 0
   fi
 
   local destination_id build_log
   destination_id="\$(destination_spec)"
   build_log="\$STATE_DIR/xcodebuild.build.log"
+  clean_zmr_derived_data
 
   run_xcodebuild_with_timeout "iOS shim build-for-testing" "\${ZMR_IOS_SHIM_BUILD_TIMEOUT_SECONDS:-5400}" "\$build_log" \\
     xcodebuild build-for-testing \\
@@ -410,6 +471,7 @@ build_for_testing() {
       ZMR_SHIM_SERVER_DIR="\$SERVER_DIR" \\
       ZMR_APP_BUNDLE_ID="$BUNDLE_ID"
 
+  printf '%s\\n' "\$INSTALL_FINGERPRINT_VALUE" > "\$BUILD_FINGERPRINT_FILE"
   touch "\$BUILD_READY_FILE"
 }
 

package/shims/ios/README.md

@@ -19,7 +19,11 @@ Current status:
   selector commands through `test-without-building`, exchanging per-command
   files under `.zmr/ios-shim-state/`. Set `ZMR_IOS_SHIM_FORCE_REBUILD=1` to
   refresh the cached test bundle, or `ZMR_IOS_SHIM_ONESHOT=1` to force the
-  slower one-command XCTest fallback for debugging.
+  slower one-command XCTest fallback for debugging. When configured with a
+  ZMR-owned derived data path ending in `ZMRDerivedData`, the command removes
+  only stale shim target products and intermediates before a needed
+  `build-for-testing` refresh, preserves app and Pods build outputs, and
+  refuses to delete arbitrary shared DerivedData paths.
 - The iOS adapter still uses `xcrun simctl` for simulator install, launch,
   terminate, open link, screenshots, and logs. It uses `xcrun devicectl` for
   physical-device lifecycle where Apple exposes a supported local command, and

package/shims/ios/ZMRShimUITestCase.swift

@@ -2,6 +2,8 @@ import Foundation
 import XCTest
 
 final class ZMRShimUITestCase: XCTestCase {
+    private let expoDevClientRecoveryTimeout: TimeInterval = 10
+
     func testRunZMRCommand() throws {
         let environment = ProcessInfo.processInfo.environment
         let app = makeApplication(bundleIdentifier: shimRuntimeValue("ZMR_APP_BUNDLE_ID", environment: environment))
@@ -318,6 +320,7 @@ final class ZMRShimUITestCase: XCTestCase {
 
         if app.staticTexts["Deep link received:"].waitForExistence(timeout: 1) {
             if tapFirstMatchingExpoCandidate(
+                app: app,
                 queries: [app.buttons, app.cells, app.staticTexts],
                 predicate: predicate
             ) {
@@ -328,12 +331,29 @@ final class ZMRShimUITestCase: XCTestCase {
         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 waitForExpoDevClientRecovery(app: app, deepLinkPredicate: predicate)
+        }
+
+        return (false, "")
+    }
+
+    private func waitForExpoDevClientRecovery(
+        app: XCUIApplication,
+        deepLinkPredicate: NSPredicate
+    ) -> (accepted: Bool, label: String) {
+        let deadline = Date().addingTimeInterval(expoDevClientRecoveryTimeout)
+        while Date() < deadline {
+            if app.staticTexts["Deep link received:"].exists,
+               tapExpoDevClientDeepLinkCandidateFallback(app: app, predicate: deepLinkPredicate) {
                 return (true, "expo-dev-client-deep-link-candidate")
             }
+
+            let homeSelection = resumeExpoDevClientHome(app: app)
+            if homeSelection.accepted {
+                return homeSelection
+            }
+
+            Thread.sleep(forTimeInterval: 0.2)
         }
 
         return (false, "")
@@ -367,6 +387,7 @@ final class ZMRShimUITestCase: XCTestCase {
 
         let predicate = NSPredicate(format: "label CONTAINS[c] %@ OR label CONTAINS[c] %@", " http://", " https://")
         if tapFirstMatchingExpoCandidate(
+            app: app,
             queries: [app.buttons, app.cells, app.staticTexts],
             predicate: predicate
         ) {
@@ -399,6 +420,7 @@ final class ZMRShimUITestCase: XCTestCase {
     }
 
     private func tapFirstMatchingExpoCandidate(
+        app: XCUIApplication,
         queries: [XCUIElementQuery],
         predicate: NSPredicate
     ) -> Bool {
@@ -410,19 +432,44 @@ final class ZMRShimUITestCase: XCTestCase {
                     break
                 }
 
-                guard element.isHittable else {
-                    continue
+                if tapMatchedExpoCandidate(element: element, app: app) {
+                    return true
                 }
-
-                element.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.5)).tap()
-                Thread.sleep(forTimeInterval: 1.0)
-                return true
             }
         }
 
         return false
     }
 
+    private func tapMatchedExpoCandidate(element: XCUIElement, app: XCUIApplication) -> Bool {
+        if element.isHittable {
+            element.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.5)).tap()
+            Thread.sleep(forTimeInterval: 1.0)
+            return true
+        }
+
+        let visibleFrame = element.frame.intersection(app.frame)
+        guard !visibleFrame.isNull,
+              !visibleFrame.isEmpty,
+              app.frame.width > 0,
+              app.frame.height > 0 else {
+            return false
+        }
+
+        let normalizedX = (visibleFrame.midX - app.frame.minX) / app.frame.width
+        let normalizedY = (visibleFrame.midY - app.frame.minY) / app.frame.height
+        guard normalizedX >= 0,
+              normalizedX <= 1,
+              normalizedY >= 0,
+              normalizedY <= 1 else {
+            return false
+        }
+
+        app.coordinate(withNormalizedOffset: CGVector(dx: normalizedX, dy: normalizedY)).tap()
+        Thread.sleep(forTimeInterval: 1.0)
+        return true
+    }
+
     private func isCustomSchemeURL(_ value: String?) -> Bool {
         guard let value else {
             return false
@@ -437,15 +484,9 @@ final class ZMRShimUITestCase: XCTestCase {
         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(
+            app: app,
             queries: [app.buttons, app.cells, app.staticTexts],
             predicate: predicate
         )

package/src/version.zig

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