zeno-mobile-runner 0.1.2 → 0.1.8

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.8`.
 
 Current protocol version: `2026-04-28`.
 
@@ -24,6 +24,10 @@ Public schemas:
 - `schemas/capabilities-output.schema.json`
 - `schemas/explain-output.schema.json`
 - `schemas/run-output.schema.json`
+- `schemas/inspect-output.schema.json`
+- `schemas/discover-output.schema.json`
+- `schemas/explore-output.schema.json`
+- `schemas/draft-output.schema.json`
 - `schemas/release-manifest.schema.json`
 - `schemas/release-readiness-output.schema.json`
 - `schemas/schemas-output.schema.json`
@@ -36,12 +40,74 @@ methods.
 form for setup scripts, generated clients, and editor integrations. The
 response is covered by `schemas/schemas-output.schema.json`.
 
+`zmr inspect --json` returns a read-only app handoff for humans and agents. It
+reports the app root, config and `.zmr/AGENTS.md` presence, configured Android
+and iOS smoke scenarios, safe next commands, claim limits, and current runner
+and protocol versions. The response is covered by
+`schemas/inspect-output.schema.json`:
+
+```json
+{"ok":true,"status":"ready","schemaVersion":1,"runnerVersion":"0.1.8","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`
+is the public trace-to-test handoff for agents. It reads the trace manifest and
+latest snapshot artifact, writes a reviewable scenario, and optionally validates
+that generated scenario before returning. With `--include-actions`, it replays
+only successful supported trace actions that contain stable replay data. It is
+offline and review-first: it does not start a device session, crawl the app,
+invent credentials, or commit files. The response is covered by
+`schemas/discover-output.schema.json`:
+
+```json
+{"ok":true,"mode":"discover","schemaVersion":1,"runnerVersion":"0.1.8","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>
+--include-actions --validate --json` is the review-first exploration handoff
+for CLI agents. It uses the same trace-backed scenario writer as `discover`,
+but carries the agent goal and explicit guardrails in the response. It does not
+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.1.8","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
+level scenario-writing primitive used by `discover`. It reads the
+trace manifest and latest semantic snapshot artifact, then writes a reviewable
+surface-smoke scenario. The generated scenario starts with `launch` and
+`snapshot`, then adds `assertVisible` steps for a small set of visible stable
+selectors. It does not start a device session, crawl the app, tap controls, type
+into fields, or commit files. The response is covered by
+`schemas/draft-output.schema.json`:
+
+```json
+{"ok":true,"mode":"draft","schemaVersion":1,"runnerVersion":"0.1.8","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
+successful supported replay steps before the final snapshot assertions. Replay
+drafts currently include app launch, deep links, selector taps, selector text
+entry, selector erase, selector/timeout-preserving visible/not-visible waits,
+matched wait-any events as `waitVisible`, back, keyboard hiding,
+coordinate-complete swipes, direction/timeout-preserving selector scrolls, and
+selector/timeout-preserving `assertVisible` and `assertNotVisible`,
+`assertNoneVisible` selector arrays plus timed `assertHealthy` checks. Events
+without enough replay data, failed events, diagnostics, underspecified swipes,
+and control events are skipped with warnings rather than guessed. Text entry
+events redacted from the trace are skipped.
+The `replay` object in draft and discover JSON reports whether action replay
+was enabled, how many trace action events were considered, how many replay
+steps were generated, and how many events were skipped.
+
 `zmr-release-readiness --json` checks one or more repeated app/device evidence
 files and emits a machine-readable readiness summary. The output is covered by
 `schemas/release-readiness-output.schema.json`:
 
 ```json
-{"ok":false,"target":"production","status":"blocked","evidence":"traces/zmr-pilots/evidence.jsonl","evidenceFiles":["traces/zmr-pilots/evidence.jsonl"],"passed":["Android emulator pilot"],"satisfied":["Android hardware pilot"],"failed":[],"planned":[],"missing":["iOS simulator hardware pilot","iOS physical hardware pilot"],"insufficient":[],"blocked":["iOS simulator hardware pilot","iOS physical hardware pilot"],"requirements":[{"name":"Android hardware pilot","status":"satisfied","evidenceName":"Android emulator pilot"},{"name":"iOS simulator hardware pilot","status":"missing","reason":"no matching passed evidence row"},{"name":"iOS physical hardware pilot","status":"missing","reason":"no matching passed evidence row"}],"nextSteps":[],"recommendedWording":"Do not call this app/device matrix ready yet. Missing evidence: iOS simulator hardware pilot, iOS physical hardware pilot.","claimLimitations":["missing evidence"]}
+{"ok":false,"target":"production","status":"blocked","evidence":"traces/zmr-pilots/evidence.jsonl","evidenceFiles":["traces/zmr-pilots/evidence.jsonl"],"passed":["local release gate","public Android emulator demo","public iOS simulator demo"],"satisfied":["local release gate","public Android demo","public iOS simulator demo","agent workflow smoke"],"failed":[],"planned":[],"missing":["physical iOS readiness","Android hardware pilot","iOS simulator hardware pilot","iOS physical hardware pilot"],"insufficient":[],"blocked":["physical iOS readiness","Android hardware pilot","iOS simulator hardware pilot","iOS physical hardware pilot"],"requirements":[{"name":"local release gate","status":"satisfied","evidenceName":"local release gate"},{"name":"public Android demo","status":"satisfied","evidenceName":"public Android emulator demo"},{"name":"public iOS simulator demo","status":"satisfied","evidenceName":"public iOS simulator demo"},{"name":"agent workflow smoke","status":"satisfied","evidenceName":"local release gate"},{"name":"physical iOS readiness","status":"missing","reason":"no matching passed evidence row"},{"name":"Android hardware pilot","status":"missing","reason":"no matching passed evidence row"},{"name":"iOS simulator hardware pilot","status":"missing","reason":"no matching passed evidence row"},{"name":"iOS physical hardware pilot","status":"missing","reason":"no matching passed evidence row"}],"nextSteps":[{"requirement":"Android hardware pilot + iOS simulator hardware pilot","command":"zmr-pilot-gate --android --ios --android-app-root /path/to/mobile-app --android-app-id <android-app-id> --android-device <android-serial> --ios-app-root /path/to/mobile-app --ios-app-path /path/to/mobile-app/build/Debug-iphonesimulator/Sample.app --ios-app-id <ios-app-id> --ios-device booted --ios-shim /path/to/mobile-app/.zmr/ios-shim --runs 20 --min-pass-rate 100 --max-failures 0 --evidence-out /path/to/mobile-app/traces/zmr-pilots/evidence.jsonl","commands":["zmr-pilot-gate --android --ios --android-app-root /path/to/mobile-app --android-app-id <android-app-id> --android-device <android-serial> --ios-app-root /path/to/mobile-app --ios-app-path /path/to/mobile-app/build/Debug-iphonesimulator/Sample.app --ios-app-id <ios-app-id> --ios-device booted --ios-shim /path/to/mobile-app/.zmr/ios-shim --runs 20 --min-pass-rate 100 --max-failures 0 --evidence-out /path/to/mobile-app/traces/zmr-pilots/evidence.jsonl"],"covers":["Android hardware pilot","iOS simulator hardware pilot"]},{"requirement":"physical iOS readiness + iOS physical hardware pilot","command":"zmr-pilot-gate --ios --ios-device-type physical --ios-device <physical-device-id> --ios-app-root /path/to/mobile-app --ios-app-path /path/to/mobile-app/build/Release-iphoneos/Sample.ipa --ios-app-id <ios-app-id> --ios-shim /path/to/mobile-app/.zmr/ios-shim --runs 20 --min-pass-rate 100 --max-failures 0 --evidence-out /path/to/mobile-app/traces/zmr-pilots/evidence.jsonl","commands":["zmr-pilot-gate --ios --ios-device-type physical --ios-device <physical-device-id> --ios-app-root /path/to/mobile-app --ios-app-path /path/to/mobile-app/build/Release-iphoneos/Sample.ipa --ios-app-id <ios-app-id> --ios-shim /path/to/mobile-app/.zmr/ios-shim --runs 20 --min-pass-rate 100 --max-failures 0 --evidence-out /path/to/mobile-app/traces/zmr-pilots/evidence.jsonl"],"covers":["physical iOS readiness","iOS physical hardware pilot"]}],"recommendedWording":"Do not publish the production claim yet. Missing evidence: physical iOS readiness, Android hardware pilot, iOS simulator hardware pilot, iOS physical hardware pilot.","claimLimitations":["missing evidence"]}
 ```
 
 Zero-dependency TypeScript, standard-library Python, standard-library Go, and
@@ -54,6 +120,12 @@ Rust reference clients live under `clients/typescript/`, `clients/python/`,
 
 `trace.json` is the stable bundle entrypoint for agents and viewers. It includes `schemaVersion`, `runnerVersion`, `protocolVersion`, `scenarioName`, `appId`, `status`, start/end/duration timestamps, failure metadata, `eventsPath`, `artifactsDir`, event/snapshot counts, partial failure count, and `reportPath` when `zmr report` has generated a single-trace HTML report.
 
+`zmr report <trace-or-benchmark-dir> --out <report.html> --junit <report.xml>`
+writes the local HTML report and a CI-friendly JUnit XML file. For trace
+directories, the XML contains one testcase for the scenario. For benchmark
+directories with `results.jsonl`, the XML contains one testcase per benchmark
+row.
+
 `zmr export <trace-dir> --out <bundle.zmrtrace>` writes a deterministic tar archive with relative paths only. V1 bundles include `trace.json`, `events.jsonl`, optional `report.html`, and every regular file under `artifacts/`.
 
 `zmr export <trace-dir> --out <bundle.zmrtrace> --redact` writes a shareable bundle without mutating the local trace directory. Redacted bundles replace PNG screenshots with placeholder frames, omit screen recording artifacts, scrub text artifacts for emails/tokens/sensitive JSON values, and add `redaction` metadata to the bundled `trace.json`. Add `--omit-screenshots` when the bundle should contain no screenshot artifacts at all.
@@ -81,14 +153,23 @@ Clients should read the last `scenario.end` event as the authoritative trace out
 scenario completes. For traced runs it mirrors the authoritative `trace.json`
 terminal fields, including trace paths, event/snapshot counts, failed step, and
 stable error name. Traced summaries also include `nextCommands` so agents can
-immediately render an HTML report, explain the failure, or export a redacted
-trace bundle. Failed scenarios still exit non-zero after writing the JSON
-summary. The response is covered by `schemas/run-output.schema.json`:
+immediately render HTML and JUnit reports, explain the failure, generate a
+reviewable scenario from the trace, or export a redacted trace bundle. Failed
+scenarios still exit non-zero after writing the JSON summary. The response is
+covered by `schemas/run-output.schema.json`:
 
 ```json
-{"ok":false,"status":"failed","scenario":"login smoke","appId":"com.example.mobiletest","traceDir":"traces/login-smoke","eventsPath":"events.jsonl","artifactsDir":"artifacts","durationMs":100,"eventCount":4,"snapshotCount":1,"failedStepIndex":2,"error":"WaitTimeout","nextCommands":["zmr report traces/login-smoke --out traces/login-smoke/report.html","zmr explain traces/login-smoke --json","zmr export traces/login-smoke --out traces/login-smoke.zmrtrace --redact"]}
+{"ok":false,"status":"failed","scenario":"login smoke","appId":"com.example.mobiletest","traceDir":"traces/login-smoke","eventsPath":"events.jsonl","artifactsDir":"artifacts","durationMs":100,"eventCount":4,"snapshotCount":1,"failedStepIndex":2,"error":"WaitTimeout","nextCommands":["zmr report traces/login-smoke --out traces/login-smoke/report.html --junit traces/login-smoke/junit.xml","zmr explain traces/login-smoke --json","zmr discover --from-trace traces/login-smoke --out .zmr/discovered/replay-smoke.json --include-actions --validate --force --json","zmr export traces/login-smoke --out traces/login-smoke.zmrtrace --redact"]}
 ```
 
+`zmr run <scenario.json> --trace-dir <trace-dir> --discover-out
+<scenario.json> --json` runs the same trace-backed discover engine before
+printing the run summary. The response includes `discovery` with the
+`zmr discover --json` payload, including validation results and next commands.
+If discovery cannot run, the run summary remains authoritative and includes
+`discoveryError` with the stable error name. `--discover-out` requires an
+effective `--trace-dir`, either passed directly or resolved from `.zmr/config.json`.
+
 When a run captures useful artifacts but a non-terminal enrichment fails, such
 as an iOS screenshot succeeding while XCTest hierarchy extraction fails, the
 terminal status is `partial` and `partialFailureCount` is greater than zero.
@@ -114,12 +195,12 @@ The text summary includes the terminal status, failed step, stable error, last d
 
 `zmr explain <trace-dir> --json` or `zmr explain --json <trace-dir>` returns
 the same failure triage fields in a stable machine-readable shape for agents
-and CI. It also includes `traceDir` and `nextCommands` for rendering an HTML
-report or exporting a redacted bundle. The response is covered by
+and CI. It also includes `traceDir` and `nextCommands` for rendering HTML and
+JUnit reports or exporting a redacted bundle. The response is covered by
 `schemas/explain-output.schema.json`:
 
 ```json
-{"ok":true,"traceDir":"traces/login-smoke","scenario":"login smoke","status":"failed","appId":"com.example.mobiletest","durationMs":100,"eventCount":4,"snapshotCount":1,"failedStepIndex":2,"error":"WaitTimeout","diagnostic":{"kind":"wait.visible","status":"timeout","snapshotId":"snapshot-7","activePackage":"com.example.mobiletest","activeActivity":".MainActivity","visibleTexts":["Sign in","Try again"],"nearestTextMatches":["Dashboards (score 1)"]},"lastEvent":"scenario.end","nextCommands":["zmr report traces/login-smoke --out traces/login-smoke/report.html","zmr export traces/login-smoke --out traces/login-smoke.zmrtrace --redact"]}
+{"ok":true,"traceDir":"traces/login-smoke","scenario":"login smoke","status":"failed","appId":"com.example.mobiletest","durationMs":100,"eventCount":4,"snapshotCount":1,"failedStepIndex":2,"error":"WaitTimeout","diagnostic":{"kind":"wait.visible","status":"timeout","snapshotId":"snapshot-7","activePackage":"com.example.mobiletest","activeActivity":".MainActivity","visibleTexts":["Sign in","Try again"],"nearestTextMatches":["Dashboards (score 1)"]},"lastEvent":"scenario.end","nextCommands":["zmr report traces/login-smoke --out traces/login-smoke/report.html --junit traces/login-smoke/junit.xml","zmr export traces/login-smoke --out traces/login-smoke.zmrtrace --redact"]}
 ```
 
 For partial visual captures, `diagnostic.kind` is
@@ -133,7 +214,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.8","protocolVersion":"2026-04-28","minimumCompatibleProtocolVersion":"2026-04-28","stability":"dev-preview","breakingChangePolicy":"version-and-changelog"}
 ```
 
 ## Capabilities Output Contract
@@ -145,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.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.8","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
@@ -307,7 +388,11 @@ zmr mcp --config .zmr/config.json --trace-dir traces/mcp-agent-session
 - `assert.visible`
 - `assert.notVisible`
 - `assert.healthy`
+- `scenario.validate`
 - `trace.events`
+- `trace.explore`
+- `trace.discover`
+- `trace.explain`
 - `trace.export`
 
 `runner.capabilities` returns both legacy `protocolVersion` and a structured `protocol` object. Clients should treat `protocol.version` as the compatibility key for method and payload shape, and should reject servers older than `protocol.minimumCompatibleVersion` unless they intentionally support that older shape. Before `v1.0.0`, `protocol.stability` is `dev-preview` and breaking changes require both a protocol version bump and changelog entry.
@@ -347,7 +432,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.8","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`
@@ -373,6 +458,90 @@ Response:
 server-side event counter; `nextSeq` is the last returned event and can be
 passed back as `afterSeq`.
 
+### `trace.explain`
+
+Summarizes the active live trace with the same JSON shape as
+`zmr explain <trace-dir> --json`. Use it when an agent needs the current trace
+status, failure diagnostic, last event, and next commands without leaving the
+JSON-RPC session.
+
+Request:
+
+```json
+{"jsonrpc":"2.0","id":26,"method":"trace.explain","params":{}}
+```
+
+Response:
+
+```json
+{"jsonrpc":"2.0","id":26,"result":{"ok":true,"traceDir":"traces/agent-session","scenario":"json-rpc session","status":"failed","appId":"com.example.mobiletest","durationMs":100,"eventCount":4,"snapshotCount":1,"failedStepIndex":2,"error":"WaitTimeout","diagnostic":{"kind":"wait.visible","status":"timeout","snapshotId":"snapshot-7","visibleTexts":["Sign in","Try again"]},"lastEvent":"scenario.end","nextCommands":["zmr report traces/agent-session --out traces/agent-session/report.html --junit traces/agent-session/junit.xml","zmr export traces/agent-session --out traces/agent-session.zmrtrace --redact"]}}
+```
+
+Without `--trace-dir`, it returns a result with `traceDir: null` and a message
+explaining how to enable live trace explanation.
+
+### `scenario.validate`
+
+Validates a ZMR scenario file and returns the same structured payload as
+`zmr validate --json`, including field paths and source locations for invalid
+files.
+
+Request:
+
+```json
+{"jsonrpc":"2.0","id":23,"method":"scenario.validate","params":{"path":".zmr/discovered/agent-smoke.json"}}
+```
+
+Response:
+
+```json
+{"jsonrpc":"2.0","id":23,"result":{"ok":true,"path":".zmr/discovered/agent-smoke.json","name":"agent smoke","appId":"com.example.mobiletest","stepCount":4,"nextCommands":["zmr run .zmr/discovered/agent-smoke.json --json --trace-dir traces/zmr-run"]}}
+```
+
+### `trace.discover`
+
+Generates a reviewable scenario candidate from the active live trace. It uses
+the same engine as `zmr discover --from-trace`, so it can include supported
+successful replay actions, add final snapshot assertions, and optionally
+validate the generated scenario before returning.
+
+Request:
+
+```json
+{"jsonrpc":"2.0","id":25,"method":"trace.discover","params":{"out":".zmr/discovered/agent-smoke.json","includeActions":true,"validate":true,"force":true,"name":"agent smoke"}}
+```
+
+Response:
+
+```json
+{"jsonrpc":"2.0","id":25,"result":{"ok":true,"mode":"discover","schemaVersion":1,"runnerVersion":"0.1.8","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
+scenarios remain review-first: ZMR does not crawl, invent credentials, or
+commit tests.
+
+### `trace.explore`
+
+Generates a review-required scenario candidate from the active live trace for a
+stated goal. It uses the same trace-backed engine as `zmr explore --from-trace`:
+the runner writes from existing trace evidence only, does not crawl the app,
+does not discover credentials or secrets, and returns `reviewRequired: true`.
+
+Request:
+
+```json
+{"jsonrpc":"2.0","id":27,"method":"trace.explore","params":{"out":".zmr/discovered/agent-goal.json","goal":"find a stable login smoke","includeActions":true,"validate":true,"force":true,"name":"agent goal smoke"}}
+```
+
+Response:
+
+```json
+{"jsonrpc":"2.0","id":27,"result":{"ok":true,"mode":"explore","schemaVersion":1,"runnerVersion":"0.1.8","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`.
+
 ### `device.list`
 
 Response:
@@ -432,10 +601,14 @@ exposes tool calls for agent runtimes that prefer MCP over raw JSON-RPC.
 zmr mcp --config .zmr/config.json --trace-dir traces/mcp-agent
 ```
 
-Core tools are `snapshot`, `semantic_snapshot`, `tap`, `type`, `press_back`,
-`open_link`, `wait_visible`, `trace_events`, and `trace_export`. The MCP
-protocol handshake is intentionally standard, while the tool names and payloads
-are versioned with the ZMR runner and public schemas.
+Core tools are `snapshot`, `semantic_snapshot`, `install_app`, `launch_app`,
+`stop_app`, `clear_state`, `tap`, `type`, `erase_text`, `hide_keyboard`,
+`swipe`, `press_back`, `open_link`, `wait_visible`, `wait_not_visible`,
+`wait_any`, `scroll_until_visible`, `assert_visible`, `assert_not_visible`,
+`assert_healthy`, `scenario_validate`, `trace_events`, `trace_explain`,
+`trace_explore`, `trace_discover`, and `trace_export`. The MCP protocol handshake is
+intentionally standard, while the tool names and payloads are versioned with
+the ZMR runner and public schemas.
 
 ### `ui.tap`
 
@@ -466,6 +639,32 @@ Request:
 {"jsonrpc":"2.0","id":7,"method":"assert.notVisible","params":{"selector":{"textContains":"Loading"},"timeoutMs":5000}}
 ```
 
+### MCP `trace_discover`
+
+`trace_discover` mirrors JSON-RPC `trace.discover` for MCP agents. Required
+argument: `out`. Optional arguments: `includeActions`, `validate`, `force`,
+`name`, and `appId`. The tool response text is the same discover JSON payload.
+
+### MCP `trace_explore`
+
+`trace_explore` mirrors JSON-RPC `trace.explore` for MCP agents. Required
+arguments: `out` and `goal`. Optional arguments: `includeActions`, `validate`,
+`force`, `name`, and `appId`. The tool response text is the same guarded
+explore JSON payload, including `autonomous:false`, `reviewRequired:true`, and
+`guardrails`.
+
+### MCP `trace_explain`
+
+`trace_explain` mirrors JSON-RPC `trace.explain` for MCP agents. It takes no
+arguments. The tool response text is the same explanation JSON payload returned
+by `zmr explain --json`.
+
+### MCP `scenario_validate`
+
+`scenario_validate` mirrors JSON-RPC `scenario.validate` for MCP agents.
+Required argument: `path`. The tool response text is the same validation JSON
+payload returned by `zmr validate --json`.
+
 ### `trace.export`
 
 When `zmr serve` is started with `--trace-dir`, live JSON-RPC sessions use the

package/docs/scenario-authoring.md

@@ -71,6 +71,9 @@ 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.
 
+`assertVisible` and `assertNotVisible` accept the same `timeoutMs` field as
+waits when a scenario needs assertion-specific timing.
+
 ## Example Templates
 
 The example directory includes templates for common app flows:

package/docs/troubleshooting.md

@@ -228,7 +228,7 @@ When a run fails, do not rerun blindly. Inspect the recorded failure:
 
 ```bash
 zmr explain traces/zmr-android
-zmr report traces/zmr-android --out traces/zmr-android/report.html
+zmr report traces/zmr-android --out traces/zmr-android/report.html --junit traces/zmr-android/junit.xml
 ```
 
 Timeout diagnostics include the active package/activity, visible text, hidden or

package/npm/agents.mjs

@@ -47,6 +47,7 @@ export function nextStepCommands(config, { android = true, ios = true, packageSc
 export function agentInstructions(appId, { android = true, ios = true, packageScripts = false, scripts = {} } = {}) {
   const command = (name, fallback) => scripts[name] ?? fallback;
   const appCommand = (scriptName, directCommand) => packageScripts ? `npm run ${scriptName}` : directCommand;
+  const inspectCommand = "zmr inspect --json --dir .";
   const doctorCommand = appCommand("zmr:doctor", command("doctor", "zmr doctor --strict --json --config .zmr/config.json"));
   const schemasCommand = appCommand("zmr:schemas", command("schemas", "zmr schemas --json"));
   const validateDirectCommand = command("validate", validateCommand({ android, ios }));
@@ -56,6 +57,7 @@ export function agentInstructions(appId, { android = true, ios = true, packageSc
   const explainCommand = appCommand("zmr:explain", command("explain", "zmr explain traces/zmr-agent --json"));
   const exportCommand = appCommand("zmr:export", command("exportTrace", "zmr export traces/zmr-agent --out traces/zmr-agent-redacted.zmrtrace --redact"));
   const setupChecks = [
+    inspectCommand,
     doctorCommand,
     schemasCommand,
     validateAppCommand,
@@ -119,6 +121,7 @@ export function agentInstructions(appId, { android = true, ios = true, packageSc
   const appSectionTitle = packageScripts ? "App Scripts" : "App Commands";
   const appSectionCommands = nextStepCommands({ scripts: nextStepScripts }, { android, ios, packageScripts })
     .map((step) => step.command);
+  appSectionCommands.unshift(inspectCommand);
   const releaseClaims = android && ios
     ? `\`\`\`bash
 ${readinessCommandText}
@@ -148,6 +151,19 @@ ${mcpCommand}
 
 Use \`semantic_snapshot\` before choosing tap or type actions. Prefer selectors from accessibility identifiers, resource ids, labels, or exact text before coordinates. Export redacted traces before sharing artifacts.
 
+## Discover From Trace
+
+\`\`\`bash
+zmr explore --from-trace traces/zmr-agent --out .zmr/discovered/login-smoke.json --goal "find a stable login smoke" --include-actions --validate --json
+zmr discover --from-trace traces/zmr-agent --out .zmr/discovered/replay-smoke.json --include-actions --validate --json
+zmr draft --from-trace traces/zmr-agent --out .zmr/discovered/surface-smoke.json --json
+zmr validate --json .zmr/discovered/surface-smoke.json
+zmr draft --from-trace traces/zmr-agent --out .zmr/discovered/replay-smoke.json --include-actions --json
+zmr validate --json .zmr/discovered/replay-smoke.json
+\`\`\`
+
+Prefer \`zmr explore\` for CLI agent loops when the goal should travel with the generated candidate. Its JSON includes \`autonomous:false\`, \`reviewRequired:true\`, \`guardrails\`, replay coverage, validation, and deterministic next commands. Treat discover output as a lower-level reviewable starting point. It writes from trace evidence and validates the generated file when \`--validate\` is present, but it does not crawl, invent missing actions, discover credentials, or commit tests. Treat draft output as a reviewable starting point when using the lower-level split workflow. The default draft contains only \`launch\`, \`snapshot\`, and conservative \`assertVisible\` checks. Use \`--include-actions\` only when the trace came from a reviewed agent session; unsupported events are skipped with warnings instead of guessed. Do not commit a discovered or drafted scenario until a human has reviewed and rerun it.
+
 ## Failure Triage
 
 \`\`\`bash

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/commands.mjs

@@ -13,8 +13,8 @@ export function smokeRunCommand({ platform, androidShim = "", iosShim = "" }) {
 }
 
 export function smokeReportCommand({ platform }) {
-  if (platform === "android") return "zmr report traces/zmr-android --out traces/zmr-android/report.html";
-  if (platform === "ios") return "zmr report traces/zmr-ios --out traces/zmr-ios/report.html";
+  if (platform === "android") return reportCommand("zmr", "traces/zmr-android");
+  if (platform === "ios") return reportCommand("zmr", "traces/zmr-ios");
   throw new Error(`unsupported smoke report platform: ${platform}`);
 }
 
@@ -71,7 +71,7 @@ export function reliabilityCommand({ scenario, platform = "", device, appId, xcr
     "--max-p95-ms",
     String(maxP95Ms),
   );
-  return `export ZMR_BIN="\${ZMR_BIN:-zmr}"; ${shellJoin(args)} && "$ZMR_BIN" report ${shellQuote(traceRoot)} --out ${shellQuote(`${traceRoot}/report.html`)}`;
+  return `export ZMR_BIN="\${ZMR_BIN:-zmr}"; ${shellJoin(args)} && ${reportCommand('"$ZMR_BIN"', traceRoot)}`;
 }
 
 export function devClientRunCommand({ platform }) {
@@ -85,11 +85,15 @@ export function devClientRunCommand({ platform }) {
 }
 
 export function devClientReportCommand({ platform }) {
-  if (platform === "android") return "zmr report traces/zmr-android-dev-client --out traces/zmr-android-dev-client/report.html";
-  if (platform === "ios") return "zmr report traces/zmr-ios-dev-client --out traces/zmr-ios-dev-client/report.html";
+  if (platform === "android") return reportCommand("zmr", "traces/zmr-android-dev-client");
+  if (platform === "ios") return reportCommand("zmr", "traces/zmr-ios-dev-client");
   throw new Error(`unsupported dev-client report platform: ${platform}`);
 }
 
+function reportCommand(bin, traceRoot) {
+  return `${bin} report ${shellQuote(traceRoot)} --out ${shellQuote(`${traceRoot}/report.html`)} --junit ${shellQuote(`${traceRoot}/junit.xml`)}`;
+}
+
 export function shellJoin(args) {
   return args.map((arg, index) => {
     if (index === 0 && /^[A-Za-z_][A-Za-z0-9_]*=/.test(arg)) return arg;

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.8",
   "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/schemas/README.md

@@ -19,6 +19,10 @@ This directory contains draft 2020-12 JSON Schemas for public ZMR file and proto
 - `capabilities-output.schema.json`: machine-readable `runner.capabilities` JSON-RPC result for protocol, platform support, transport, and method discovery
 - `explain-output.schema.json`: machine-readable `zmr explain --json` failure triage output for agents and CI
 - `run-output.schema.json`: machine-readable `zmr run --json` terminal run summary output
+- `inspect-output.schema.json`: machine-readable `zmr inspect --json` app and agent handoff output
+- `discover-output.schema.json`: machine-readable `zmr discover --json` trace-backed scenario discovery output with replay coverage metadata
+- `explore-output.schema.json`: machine-readable `zmr explore --json` review-first trace exploration output with goal and guardrail metadata
+- `draft-output.schema.json`: machine-readable `zmr draft --json` trace-backed scenario draft output with replay coverage metadata
 - `release-manifest.schema.json`: machine-readable `RELEASE_MANIFEST.json` emitted with release archives
 - `release-readiness-output.schema.json`: machine-readable `zmr-release-readiness --json` release evidence gate output
 - `schemas-output.schema.json`: machine-readable `zmr schemas --json` index of public schema names, paths, ids, and descriptions