zeno-mobile-runner 0.2.13 → 0.2.15

package/CHANGELOG.md

@@ -4,6 +4,26 @@ All notable changes to Zeno Mobile Runner are tracked here.
 
 ## Unreleased
 
+## 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
+
+- Added a first-class `setLocation` scenario action for simulator/emulator
+  location control. iOS simulators grant the target app location permission and
+  set coordinates through `simctl`; Android emulators best-effort grant runtime
+  location permissions before setting emulator geolocation.
+
 ## 0.2.13 (2026-06-23)
 
 ### 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.13`, a public developer preview rather than
+- Current release status is `0.2.15`, 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.13` developer preview.
+process ceiling. Current release: `0.2.15` 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.13.jar"))
+implementation(files("path/to/zeno-mobile-runner/clients/kotlin/build/libs/zmr-client-0.2.15.jar"))
 ```
 
 ```kotlin

package/clients/kotlin/build.gradle.kts

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

package/clients/python/pyproject.toml

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

package/clients/rust/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "zmr-client"
-version = "0.2.13"
+version = "0.2.15"
 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.13",
+  "version": "0.2.15",
   "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.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":1,"result":{"name":"zmr","version":"0.2.15","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.13`.
+Current runner version: `0.2.15`.
 
 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.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"]}
+{"ok":true,"status":"ready","schemaVersion":1,"runnerVersion":"0.2.15","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.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"]}
+{"ok":true,"mode":"discover","schemaVersion":1,"runnerVersion":"0.2.15","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.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"]}
+{"ok":true,"mode":"explore","schemaVersion":1,"runnerVersion":"0.2.15","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.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"]}
+{"ok":true,"mode":"draft","schemaVersion":1,"runnerVersion":"0.2.15","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.13","protocolVersion":"2026-04-28","minimumCompatibleProtocolVersion":"2026-04-28","stability":"dev-preview","breakingChangePolicy":"version-and-changelog"}
+{"name":"zmr","version":"0.2.15","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.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"]}
+{"name":"zmr","version":"0.2.15","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
@@ -373,6 +373,7 @@ zmr mcp --config .zmr/config.json --trace-dir traces/mcp-agent-session
 - `app.stop`
 - `app.openLink` with `{ "url": "exampleapp://e2e-auth?probe=1" }`
 - `app.clearState`
+- Scenario action `setLocation` with `{ "latitude": 51.5074, "longitude": -0.1278 }` for simulator/emulator geolocation
 - `observe.snapshot`
 - `observe.semanticSnapshot`
 - `ui.tap` with `{ "selector": { "text": "Sign in" } }`
@@ -432,7 +433,7 @@ Request:
 Response:
 
 ```json
-{"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":1,"result":{"name":"zmr","version":"0.2.15","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 +515,7 @@ Request:
 Response:
 
 ```json
-{"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"]}}
+{"jsonrpc":"2.0","id":25,"result":{"ok":true,"mode":"discover","schemaVersion":1,"runnerVersion":"0.2.15","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 +538,7 @@ Request:
 Response:
 
 ```json
-{"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"]}}
+{"jsonrpc":"2.0","id":27,"result":{"ok":true,"mode":"explore","schemaVersion":1,"runnerVersion":"0.2.15","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/scenario-authoring.md

@@ -84,6 +84,18 @@ The importer supports the common subset needed for smoke scenarios:
 generated JSON before committing it; native `.zmr/*.json` scenarios remain the
 runtime contract for agents and CI.
 
+Use `setLocation` before location-dependent assertions to set simulator or
+emulator coordinates through the runner instead of shelling out from the app
+test:
+
+```json
+{ "action": "setLocation", "latitude": 51.5074, "longitude": -0.1278 }
+```
+
+On iOS simulators, ZMR grants the target app location permission before setting
+the coordinate. On Android emulators, ZMR grants runtime location permissions
+best-effort and then uses emulator geolocation.
+
 `assertVisible` and `assertNotVisible` accept the same `timeoutMs` field as
 waits when a scenario needs assertion-specific timing.
 

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.13",
+  "version": "0.2.15",
   "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/schemas/scenario.schema.json

@@ -40,6 +40,7 @@
             "clearState",
             "snapshot",
             "openLink",
+            "setLocation",
             "tap",
             "typeText",
             "eraseText",
@@ -62,6 +63,8 @@
         },
         "optional": { "type": "boolean" },
         "url": { "type": "string", "minLength": 1 },
+        "latitude": { "type": "number", "minimum": -90, "maximum": 90 },
+        "longitude": { "type": "number", "minimum": -180, "maximum": 180 },
         "selector": { "$ref": "#/$defs/selector" },
         "selectors": {
           "type": "array",
@@ -90,6 +93,10 @@
           "if": { "properties": { "action": { "const": "openLink" } } },
           "then": { "required": ["url"] }
         },
+        {
+          "if": { "properties": { "action": { "const": "setLocation" } } },
+          "then": { "required": ["latitude", "longitude"] }
+        },
         {
           "if": { "properties": { "action": { "enum": ["tap", "waitVisible", "waitNotVisible", "assertVisible", "assertNotVisible", "scrollUntilVisible"] } } },
           "then": { "required": ["selector"] }

package/scripts/install-ios-shim.sh

@@ -223,6 +223,7 @@ 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"
+DERIVED_DATA_PATH_VALUE="$DERIVED_DATA_PATH"
 STDIN_FILE="\$(mktemp)"
 trap 'rm -f "\$STDIN_FILE"' EXIT
 
@@ -332,6 +333,31 @@ 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
+
+  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)
+      rm -rf "\$derived_data_abs"
+      ;;
+    *)
+      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
@@ -399,6 +425,7 @@ build_for_testing() {
   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 \\

package/shims/ios/README.md

@@ -19,7 +19,10 @@ 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
+  that directory before each `build-for-testing` refresh 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/src/android.zig

@@ -100,6 +100,20 @@ pub const AndroidDevice = struct {
         return error.AppDidNotOpen;
     }
 
+    pub fn setLocation(self: *AndroidDevice, latitude: f64, longitude: f64) !void {
+        const latitude_arg = try std.fmt.allocPrint(self.allocator, "{d:.6}", .{latitude});
+        defer self.allocator.free(latitude_arg);
+        const longitude_arg = try std.fmt.allocPrint(self.allocator, "{d:.6}", .{longitude});
+        defer self.allocator.free(longitude_arg);
+
+        try self.grantRuntimePermissionBestEffort("android.permission.ACCESS_FINE_LOCATION");
+        try self.grantRuntimePermissionBestEffort("android.permission.ACCESS_COARSE_LOCATION");
+
+        const result = try self.runAdb(&.{ "emu", "geo", "fix", longitude_arg, latitude_arg }, default_max_output);
+        defer result.deinit(self.allocator);
+        try result.ensureSuccess();
+    }
+
     pub fn tap(self: *AndroidDevice, x: i32, y: i32) !void {
         if (self.shim_path != null) return try self.runShimAction(.{ .kind = .tap, .x = x, .y = y });
         var args = try android_shell.tap(self.allocator, x, y);
@@ -284,6 +298,12 @@ pub const AndroidDevice = struct {
         return try ios_shim.parseSnapshotNodes(self.allocator, response);
     }
 
+    fn grantRuntimePermissionBestEffort(self: *AndroidDevice, permission: []const u8) !void {
+        const result = self.runAdb(&.{ "shell", "pm", "grant", self.app_id, permission }, 64 * 1024) catch return;
+        defer result.deinit(self.allocator);
+        result.ensureSuccess() catch {};
+    }
+
     fn runShimAction(self: *AndroidDevice, shim_command: ios_shim.Command) !void {
         const response = try self.runShim(shim_command);
         defer self.allocator.free(response);

package/src/errors.zig

@@ -45,6 +45,13 @@ pub fn classify(err: anyerror) PublicError {
         error.StepMissingY1,
         error.StepMissingX2,
         error.StepMissingY2,
+        error.StepMissingLatitude,
+        error.StepMissingLongitude,
+        error.StepLatitudeMustBeNumber,
+        error.StepLongitudeMustBeNumber,
+        error.StepLatitudeOutOfRange,
+        error.StepLongitudeOutOfRange,
+        error.RequiredFieldMustBeNumber,
         => .{ .code = "scenario.invalid", .message = "scenario is invalid" },
         error.SelectorMustNotBeEmpty,
         error.MissingSelector,
@@ -59,6 +66,7 @@ pub fn classify(err: anyerror) PublicError {
         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.UnsupportedDeviceCapability => .{ .code = "device.unsupported_capability", .message = "device capability is unsupported" },
         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" },

package/src/fake_device.zig

@@ -20,6 +20,8 @@ pub const FakeDevice = struct {
     opened_link: ?[]const u8 = null,
     settles: usize = 0,
     last_settle_timeout_ms: u64 = 0,
+    location_sets: usize = 0,
+    last_location: ?LocationRecord = null,
 
     pub fn init(allocator: std.mem.Allocator, snapshots: []types.ObservationSnapshot) FakeDevice {
         return .{
@@ -71,6 +73,14 @@ pub const FakeDevice = struct {
         self.opened_link = try self.allocator.dupe(u8, url);
     }
 
+    pub fn setLocation(self: *FakeDevice, latitude: f64, longitude: f64) !void {
+        self.location_sets += 1;
+        self.last_location = .{
+            .latitude = latitude,
+            .longitude = longitude,
+        };
+    }
+
     pub fn tap(self: *FakeDevice, x: i32, y: i32) !void {
         _ = x;
         _ = y;
@@ -127,6 +137,11 @@ pub const SwipeRecord = struct {
     duration_ms: u32,
 };
 
+pub const LocationRecord = struct {
+    latitude: f64,
+    longitude: f64,
+};
+
 pub fn cloneSnapshot(allocator: std.mem.Allocator, source: types.ObservationSnapshot) !types.ObservationSnapshot {
     var nodes = try allocator.alloc(types.UiNode, source.nodes.len);
     errdefer allocator.free(nodes);

package/src/ios.zig

@@ -144,6 +144,21 @@ pub const IosDevice = struct {
         self.acceptOpenURLConfirmationBestEffort(url);
     }
 
+    pub fn setLocation(self: *IosDevice, latitude: f64, longitude: f64) !void {
+        if (self.target_kind == .physical) return error.UnsupportedDeviceCapability;
+
+        const coordinate = try std.fmt.allocPrint(self.allocator, "{d:.6},{d:.6}", .{ latitude, longitude });
+        defer self.allocator.free(coordinate);
+
+        const grant = try self.runSimctl(&.{ "privacy", self.target(), "grant", "location", self.app_id }, default_max_output);
+        defer grant.deinit(self.allocator);
+        try grant.ensureSuccess();
+
+        const result = try self.runSimctl(&.{ "location", self.target(), "set", coordinate }, default_max_output);
+        defer result.deinit(self.allocator);
+        try result.ensureSuccess();
+    }
+
     pub fn tap(self: *IosDevice, x: i32, y: i32) !void {
         try self.runShimAction(.{ .kind = .tap, .x = x, .y = y });
     }
@@ -543,6 +558,70 @@ test "ios simulator openLink keeps sweeping delayed XCTest interruptions until a
     try std.testing.expectEqual(@as(u8, 6), count);
 }
 
+test "ios simulator setLocation grants app location permission and sets coordinates" {
+    const allocator = std.heap.page_allocator;
+    const argv = [_][*:0]const u8{"zmr-ios-test"};
+    stdio.initProcess(.{
+        .args = .{ .vector = argv[0..] },
+        .environ = .empty,
+    }, allocator);
+    defer stdio.deinitProcess();
+
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+
+    var xcrun = try tmp.dir.createFile(stdio.io(), "fake-xcrun-location.sh", .{ .truncate = true });
+    {
+        var buffer: [4096]u8 = undefined;
+        var writer = xcrun.writerStreaming(stdio.io(), &buffer);
+        const script = try std.fmt.allocPrint(allocator,
+            \\#!/usr/bin/env bash
+            \\set -euo pipefail
+            \\printf '%s\n' "$*" >> ".zig-cache/tmp/{s}/xcrun.log"
+            \\if [[ "${{1:-}}" != "simctl" ]]; then
+            \\  echo "expected simctl" >&2
+            \\  exit 2
+            \\fi
+            \\shift
+            \\case "${{1:-}}" in
+            \\  privacy)
+            \\    [[ "${{2:-}}" == "fake-ios-1" && "${{3:-}}" == "grant" && "${{4:-}}" == "location" && "${{5:-}}" == "com.example.mobiletest" ]] || exit 2
+            \\    ;;
+            \\  location)
+            \\    [[ "${{2:-}}" == "fake-ios-1" && "${{3:-}}" == "set" && "${{4:-}}" == "51.507400,-0.127800" ]] || exit 2
+            \\    ;;
+            \\  *)
+            \\    echo "unsupported simctl command: $*" >&2
+            \\    exit 2
+            \\    ;;
+            \\esac
+            \\
+        , .{tmp.sub_path});
+        defer allocator.free(script);
+        try writer.interface.writeAll(script);
+        try writer.interface.flush();
+    }
+    xcrun.close(stdio.io());
+
+    const xcrun_path = try std.fmt.allocPrint(allocator, ".zig-cache/tmp/{s}/fake-xcrun-location.sh", .{tmp.sub_path});
+    defer allocator.free(xcrun_path);
+    const xcrun_path_z = try allocator.dupeZ(u8, xcrun_path);
+    defer allocator.free(xcrun_path_z);
+    if (std.c.chmod(xcrun_path_z, 0o755) != 0) return error.ChmodFailed;
+
+    var device = try IosDevice.initWithShim(allocator, xcrun_path, "fake-ios-1", "com.example.mobiletest", null);
+    defer device.deinit();
+
+    try device.setLocation(51.5074, -0.1278);
+
+    const log_path = try std.fmt.allocPrint(allocator, ".zig-cache/tmp/{s}/xcrun.log", .{tmp.sub_path});
+    defer allocator.free(log_path);
+    const log = try stdio.readFileAlloc(allocator, log_path, 1024);
+    defer allocator.free(log);
+    try std.testing.expect(std.mem.indexOf(u8, log, "simctl privacy fake-ios-1 grant location com.example.mobiletest") != null);
+    try std.testing.expect(std.mem.indexOf(u8, log, "simctl location fake-ios-1 set 51.507400,-0.127800") != null);
+}
+
 pub fn listDevices(allocator: std.mem.Allocator, xcrun_path: []const u8) ![]types.DeviceInfo {
     return try ios_devices.listSimulators(allocator, xcrun_path);
 }

package/src/json_fields.zig

@@ -31,6 +31,11 @@ pub fn requiredI32FromObject(object: std.json.ObjectMap, key: []const u8, missin
     return i32Value(value, type_error);
 }
 
+pub fn requiredF64FromObject(object: std.json.ObjectMap, key: []const u8, missing_error: anyerror, type_error: anyerror) !f64 {
+    const value = object.get(key) orelse return missing_error;
+    return f64Value(value, type_error);
+}
+
 pub fn optionalU64(params: ?std.json.Value, key: []const u8, default_value: u64, type_error: anyerror) !u64 {
     const value = field(params, key) orelse return default_value;
     return u64Value(value, type_error);
@@ -72,6 +77,14 @@ fn u64Value(value: std.json.Value, type_error: anyerror) !u64 {
     };
 }
 
+fn f64Value(value: std.json.Value, type_error: anyerror) !f64 {
+    return switch (value) {
+        .float => |actual| actual,
+        .integer => |actual| @as(f64, @floatFromInt(actual)),
+        else => type_error,
+    };
+}
+
 fn boolValue(value: std.json.Value, type_error: anyerror) !bool {
     return switch (value) {
         .bool => |actual| actual,

package/src/runner.zig

@@ -8,6 +8,7 @@ const scenario = @import("scenario.zig");
 const selector = @import("selector.zig");
 const trace = @import("trace.zig");
 const types = @import("types.zig");
+const fake_device = @import("fake_device.zig");
 
 pub const RunOptions = runner_config.RunOptions;
 
@@ -86,6 +87,14 @@ pub fn executeStep(
             if (writer) |tw| try runner_events.recordActionStatus(tw, "app.openLink", "ok", null, url);
             try settleDevice(device, options);
         },
+        .set_location => |location| {
+            device.setLocation(location.latitude, location.longitude) catch |err| {
+                if (writer) |tw| try runner_events.recordSetLocation(tw, "failed", err, location.latitude, location.longitude);
+                return err;
+            };
+            if (writer) |tw| try runner_events.recordSetLocation(tw, "ok", null, location.latitude, location.longitude);
+            try settleDevice(device, options);
+        },
         .tap => |wanted| try tapSelector(device, wanted, writer, options),
         .type_text => |input| {
             if (input.selector) |wanted| return try typeTextSelector(device, wanted, input.text, writer, options);
@@ -309,6 +318,46 @@ fn settleDevice(device: anytype, options: RunOptions) !void {
     try device.settle(options.settle_ms);
 }
 
+test "setLocation dispatches through the device, records trace evidence, and settles" {
+    const allocator = std.testing.allocator;
+    const dir = "zig-cache-test-runner-set-location";
+    std.Io.Dir.cwd().deleteTree(stdio.io(), dir) catch {};
+    defer std.Io.Dir.cwd().deleteTree(stdio.io(), dir) catch {};
+
+    const script_json =
+        \\{
+        \\  "name": "set location",
+        \\  "steps": [
+        \\    {"action": "setLocation", "latitude": 51.5074, "longitude": -0.1278}
+        \\  ]
+        \\}
+    ;
+    const script = try scenario.parseSlice(allocator, script_json);
+    defer script.deinit(allocator);
+
+    var device = fake_device.FakeDevice.init(allocator, &.{});
+    defer device.deinit();
+    var tw = try trace.TraceWriter.init(allocator, dir);
+    defer tw.deinit();
+
+    try runScenario(allocator, &device, script, &tw, .{ .settle_ms = 25 });
+
+    try std.testing.expectEqual(@as(usize, 1), device.location_sets);
+    try std.testing.expectApproxEqAbs(@as(f64, 51.5074), device.last_location.?.latitude, 0.000001);
+    try std.testing.expectApproxEqAbs(@as(f64, -0.1278), device.last_location.?.longitude, 0.000001);
+    try std.testing.expectEqual(@as(usize, 1), device.settles);
+    try std.testing.expectEqual(@as(u64, 25), device.last_settle_timeout_ms);
+
+    const events_path = try std.fs.path.join(allocator, &.{ dir, "events.jsonl" });
+    defer allocator.free(events_path);
+    const events = try stdio.readFileAlloc(allocator, events_path, 1024 * 1024);
+    defer allocator.free(events);
+    try std.testing.expect(std.mem.indexOf(u8, events, "\"kind\":\"device.setLocation\"") != null);
+    try std.testing.expect(std.mem.indexOf(u8, events, "\"status\":\"ok\"") != null);
+    try std.testing.expect(std.mem.indexOf(u8, events, "\"latitude\":51.5074") != null);
+    try std.testing.expect(std.mem.indexOf(u8, events, "\"longitude\":-0.1278") != null);
+}
+
 test "whenVisible skips the conditional block when the visibility probe command fails" {
     const allocator = std.testing.allocator;
     const dir = "zig-cache-test-runner-when-visible-command-failed";
@@ -336,6 +385,12 @@ test "whenVisible skips the conditional block when the visibility probe command
             _ = url;
         }
 
+        pub fn setLocation(self: *@This(), latitude: f64, longitude: f64) !void {
+            _ = self;
+            _ = latitude;
+            _ = longitude;
+        }
+
         pub fn tap(self: *@This(), x: i32, y: i32) !void {
             _ = self;
             _ = x;

package/src/runner_events.zig

@@ -137,6 +137,20 @@ pub fn recordActionStatus(tw: *trace.TraceWriter, kind: []const u8, status: []co
     try tw.recordEvent(kind, out.buffered());
 }
 
+pub fn recordSetLocation(tw: *trace.TraceWriter, status: []const u8, err: ?anyerror, latitude: f64, longitude: f64) !void {
+    var payload: std.Io.Writer.Allocating = .init(tw.allocator);
+    defer payload.deinit();
+    const out = &payload.writer;
+    try out.writeAll("{\"status\":");
+    try trace.writeJsonString(out, status);
+    if (err) |actual| {
+        try out.writeAll(",\"error\":");
+        try trace.writeJsonString(out, @errorName(actual));
+    }
+    try out.print(",\"latitude\":{d:.6},\"longitude\":{d:.6}}}", .{ latitude, longitude });
+    try tw.recordEvent("device.setLocation", out.buffered());
+}
+
 pub fn recordSwipe(tw: *trace.TraceWriter, x1: i32, y1: i32, x2: i32, y2: i32, duration_ms: u32) !void {
     const payload = try std.fmt.allocPrint(
         tw.allocator,

package/src/scenario.zig

@@ -11,6 +11,11 @@ pub const Swipe = struct {
     duration_ms: u32 = 300,
 };
 
+pub const Location = struct {
+    latitude: f64,
+    longitude: f64,
+};
+
 pub const WaitVisible = struct {
     selector: selector.Selector,
     timeout_ms: u64 = 5000,
@@ -106,6 +111,7 @@ pub const Step = union(enum) {
     clear_state,
     snapshot,
     open_link: []const u8,
+    set_location: Location,
     tap: selector.Selector,
     type_text: TypeText,
     press_back,
@@ -224,6 +230,10 @@ fn parseRawStep(allocator: std.mem.Allocator, object: std.json.ObjectMap) anyerr
     if (std.mem.eql(u8, action, "hideKeyboard")) return .hide_keyboard;
     if (std.mem.eql(u8, action, "sleep")) return .{ .sleep_ms = try fields.optionalU64(object, "ms", 500) };
     if (std.mem.eql(u8, action, "openLink")) return .{ .open_link = try fields.requiredStringOrError(allocator, object, "url", error.StepMissingUrl) };
+    if (std.mem.eql(u8, action, "setLocation")) return .{ .set_location = .{
+        .latitude = try parseLatitude(object),
+        .longitude = try parseLongitude(object),
+    } };
     if (std.mem.eql(u8, action, "tap")) return .{ .tap = try fields.parseSelectorField(allocator, object) };
     if (std.mem.eql(u8, action, "typeText")) {
         const wanted = if (object.get("selector")) |selector_value| try selector.parseFromJson(allocator, selector_value) else null;
@@ -342,6 +352,18 @@ fn parseRawStep(allocator: std.mem.Allocator, object: std.json.ObjectMap) anyerr
     return error.unknownScenarioAction;
 }
 
+fn parseLatitude(object: std.json.ObjectMap) !f64 {
+    const latitude = try fields.requiredF64OrError(object, "latitude", error.StepMissingLatitude, error.StepLatitudeMustBeNumber);
+    if (latitude < -90.0 or latitude > 90.0) return error.StepLatitudeOutOfRange;
+    return latitude;
+}
+
+fn parseLongitude(object: std.json.ObjectMap) !f64 {
+    const longitude = try fields.requiredF64OrError(object, "longitude", error.StepMissingLongitude, error.StepLongitudeMustBeNumber);
+    if (longitude < -180.0 or longitude > 180.0) return error.StepLongitudeOutOfRange;
+    return longitude;
+}
+
 fn appendParsedSteps(allocator: std.mem.Allocator, steps: *std.ArrayList(Step), value: std.json.Value) anyerror!void {
     if (value != .array) return error.ScenarioStepsMustBeArray;
     for (value.array.items) |step_value| {
@@ -373,3 +395,27 @@ fn optionalTimeoutMs(object: std.json.ObjectMap) !?u64 {
     if (object.get("timeoutMs") == null) return null;
     return try fields.optionalU64(object, "timeoutMs", 0);
 }
+
+test "parses setLocation with latitude and longitude" {
+    const allocator = std.testing.allocator;
+    const script_json =
+        \\{
+        \\  "name": "set location smoke",
+        \\  "steps": [
+        \\    {"action": "setLocation", "latitude": 51.5074, "longitude": -0.1278}
+        \\  ]
+        \\}
+    ;
+
+    const script = try parseSlice(allocator, script_json);
+    defer script.deinit(allocator);
+
+    try std.testing.expectEqual(@as(usize, 1), script.steps.len);
+    switch (script.steps[0]) {
+        .set_location => |location| {
+            try std.testing.expectApproxEqAbs(@as(f64, 51.5074), location.latitude, 0.000001);
+            try std.testing.expectApproxEqAbs(@as(f64, -0.1278), location.longitude, 0.000001);
+        },
+        else => return error.ExpectedSetLocationStep,
+    }
+}

package/src/scenario_fields.zig

@@ -21,6 +21,10 @@ pub fn requiredI32OrError(object: std.json.ObjectMap, key: []const u8, missing_e
     return try json_fields.requiredI32FromObject(object, key, missing_error, error.RequiredFieldMustBeInteger);
 }
 
+pub fn requiredF64OrError(object: std.json.ObjectMap, key: []const u8, missing_error: anyerror, type_error: anyerror) !f64 {
+    return try json_fields.requiredF64FromObject(object, key, missing_error, type_error);
+}
+
 pub fn optionalU64(object: std.json.ObjectMap, key: []const u8, default_value: u64) !u64 {
     return try json_fields.optionalU64FromObject(object, key, default_value, error.OptionalFieldMustBeInteger);
 }

package/src/validation.zig

@@ -109,6 +109,14 @@ fn diagnoseFailure(allocator: std.mem.Allocator, content: []const u8, err: anyer
         => try pathDiagnostic(allocator, content, "$.steps[].x2", "x2"),
         error.StepMissingY2,
         => try pathDiagnostic(allocator, content, "$.steps[].y2", "y2"),
+        error.StepMissingLatitude,
+        error.StepLatitudeMustBeNumber,
+        error.StepLatitudeOutOfRange,
+        => try pathDiagnostic(allocator, content, "$.steps[].latitude", "latitude"),
+        error.StepMissingLongitude,
+        error.StepLongitudeMustBeNumber,
+        error.StepLongitudeOutOfRange,
+        => try pathDiagnostic(allocator, content, "$.steps[].longitude", "longitude"),
         error.MissingSelector,
         error.StepMissingSelector,
         error.SelectorMustNotBeEmpty,

package/src/version.zig

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