zeno-mobile-runner 0.2.6 → 0.2.8

package/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to Zeno Mobile Runner are tracked here.
 
 ## Unreleased
 
+## 0.2.8 (2026-06-17)
+
+### Fixed
+
+- iOS native selector waits now cap each XCTest query to the remaining scenario
+  step timeout and retry transient query command timeouts. Missing selectors can
+  no longer outlive the scenario `timeoutMs` by waiting on the shim's longer
+  cold-start command timeout.
+
+## 0.2.7 (2026-06-15)
+
+### Fixed
+
+- `assertHealthy` now uses native iOS selector probes for known crash and error
+  overlays before falling back to a broad accessibility snapshot. This avoids
+  false `CommandFailed` failures when XCTest broad snapshot enumeration races
+  with animated or reloading screens, while preserving direct overlay detection.
+
 ## 0.2.6 (2026-06-15)
 
 ### Fixed
@@ -30,7 +48,7 @@ All notable changes to Zeno Mobile Runner are tracked here.
 - Extended the iOS simulator `openLink` interruption sweep to cover Expo
   dev-client deep-link chooser sheets that appear more than six seconds after
   `simctl openurl` returns. The sweep remains bounded, but now covers the
-  delayed chooser timing observed in the Rently auth smoke.
+  delayed chooser timing observed in app auth smoke runs.
 
 ## 0.2.3 (2026-06-15)
 

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

@@ -197,7 +197,7 @@ comparisons against your current E2E tool, and multi-device matrices, see
 | Cloud device farms | Not included | ZMR focuses on local and self-managed device targets in this preview |
 
 Slow CI hardware can extend the iOS shim cold-build timeout with
-`ZMR_IOS_SHIM_TIMEOUT_MS`. Current release: `0.2.6` developer preview.
+`ZMR_IOS_SHIM_TIMEOUT_MS`. Current release: `0.2.8` developer preview.
 Protocol version: `2026-04-28`.
 
 ## Optional protocol clients

package/build.zig.zon

@@ -1,6 +1,6 @@
 .{
     .name = .zeno_mobile_runner,
-    .version = "0.2.6",
+    .version = "0.2.7",
     .minimum_zig_version = "0.16.0",
     .paths = .{""},
     .fingerprint = 0xcc2c8187874868fc,

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.6.jar"))
+implementation(files("path/to/zeno-mobile-runner/clients/kotlin/build/libs/zmr-client-0.2.8.jar"))
 ```
 
 ```kotlin

package/clients/kotlin/build.gradle.kts

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

package/clients/python/pyproject.toml

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

package/clients/rust/Cargo.toml

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

package/docs/npm.md

@@ -431,6 +431,14 @@ Publish the generated tarball from `dist/`:
 npm publish ./dist/zeno-mobile-runner-<version>.tgz --access public
 ```
 
+If npm returns `EOTP`, the account or organization requires a TOTP-style
+one-time password for this publish command. The browser/passkey login flow can
+authenticate the local CLI session, but `npm publish` itself only accepts the
+publish-time second factor through `--otp`. Prefer the tagged trusted-publishing
+workflow for normal releases; otherwise enter the TOTP locally or use a granular
+automation token configured to bypass 2FA. Do not send OTPs or tokens through
+issue comments, chat, or commit history.
+
 If npm returns `E403` with a two-factor authentication message, the account or
 organization requires either a current interactive 2FA challenge or a granular
 automation token configured to bypass 2FA. For local passkey accounts, rerun

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

@@ -1,4 +1,4 @@
-{"jsonrpc":"2.0","id":1,"result":{"name":"zmr","version":"0.2.6","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.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"]}}
 {"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.6`.
+Current runner version: `0.2.8`.
 
 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.6","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.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`
@@ -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.6","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.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>
@@ -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.6","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.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
@@ -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.6","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.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
@@ -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.6","protocolVersion":"2026-04-28","minimumCompatibleProtocolVersion":"2026-04-28","stability":"dev-preview","breakingChangePolicy":"version-and-changelog"}
+{"name":"zmr","version":"0.2.8","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.6","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.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
@@ -432,7 +432,7 @@ Request:
 Response:
 
 ```json
-{"jsonrpc":"2.0","id":1,"result":{"name":"zmr","version":"0.2.6","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.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`
@@ -514,7 +514,7 @@ Request:
 Response:
 
 ```json
-{"jsonrpc":"2.0","id":25,"result":{"ok":true,"mode":"discover","schemaVersion":1,"runnerVersion":"0.2.6","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.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
@@ -537,7 +537,7 @@ Request:
 Response:
 
 ```json
-{"jsonrpc":"2.0","id":27,"result":{"ok":true,"mode":"explore","schemaVersion":1,"runnerVersion":"0.2.6","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.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`.

package/package.json

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

package/src/cli_devices.zig

@@ -48,11 +48,16 @@ pub fn run(allocator: std.mem.Allocator, args: *std.process.Args.Iterator) !void
     stdout_io.init(.stdout());
     defer stdout_io.deinit();
     const stdout = stdout_io.writer();
-    if (json) return try device_registry.writeJson(stdout, registryPlatform(platform), devices);
-    if (devices.len == 0) return try stdout.print("No {s} devices found.\n", .{@tagName(platform)});
-    for (devices) |device| {
-        try stdout.print("{s}\t{s}\n", .{ device.serial, device.state });
+    if (json) {
+        try device_registry.writeJson(stdout, registryPlatform(platform), devices);
+    } else if (devices.len == 0) {
+        try stdout.print("No {s} devices found.\n", .{@tagName(platform)});
+    } else {
+        for (devices) |device| {
+            try stdout.print("{s}\t{s}\n", .{ device.serial, device.state });
+        }
     }
+    try stdout_io.flush();
 }
 
 fn parsePlatform(value: []const u8) !run_options.Platform {

package/src/cli_discover.zig

@@ -106,6 +106,7 @@ pub fn run(allocator: std.mem.Allocator, args: *std.process.Args.Iterator) !void
         try cli_output.writeShellArg(stdout, discovered.summary.draft.out_path);
         try stdout.writeAll("\n");
     }
+    try stdout_io.flush();
     if (!discovered.summary.ok) std.process.exit(1);
 }
 

package/src/cli_doctor.zig

@@ -114,5 +114,6 @@ fn runParsed(allocator: std.mem.Allocator, parsed: ParsedArgs) !void {
     } else {
         try cli_output.writeDoctorText(stdout, config_check, checks);
     }
+    try stdout_io.flush();
     if (parsed.strict and !cli_output.doctorChecksHealthy(config_check, checks)) std.process.exit(1);
 }

package/src/cli_draft.zig

@@ -125,13 +125,13 @@ pub fn run(allocator: std.mem.Allocator, args: *std.process.Args.Iterator) !void
     const stdout = stdout_io.writer();
     if (parsed.json) {
         try writeJson(stdout, draft.summary);
-        return;
+    } else {
+        try stdout.print("wrote {s}\n", .{draft.summary.out_path});
+        try stdout.writeAll("next: zmr validate --json ");
+        try cli_output.writeShellArg(stdout, draft.summary.out_path);
+        try stdout.writeAll("\n");
     }
-
-    try stdout.print("wrote {s}\n", .{draft.summary.out_path});
-    try stdout.writeAll("next: zmr validate --json ");
-    try cli_output.writeShellArg(stdout, draft.summary.out_path);
-    try stdout.writeAll("\n");
+    try stdout_io.flush();
 }
 
 pub fn draftFromTrace(allocator: std.mem.Allocator, parsed: ParsedArgs) !OwnedDraft {

package/src/cli_explore.zig

@@ -99,6 +99,7 @@ pub fn run(allocator: std.mem.Allocator, args: *std.process.Args.Iterator) !void
         try cli_output.writeShellArg(stdout, explored.discovered.summary.draft.out_path);
         try stdout.writeAll("\n");
     }
+    try stdout_io.flush();
     if (!explored.summary.ok) std.process.exit(1);
 }
 

package/src/cli_import.zig

@@ -82,9 +82,13 @@ pub fn run(allocator: std.mem.Allocator, args: *std.process.Args.Iterator) !void
     stdout_io.init(.stdout());
     defer stdout_io.deinit();
     const stdout = stdout_io.writer();
-    if (parsed.json) return try cli_output.writeImportJson(stdout, parsed.format, parsed.source_path, result);
-    try stdout.print("wrote {s}\n", .{result.out_path});
-    try stdout.writeAll("next: zmr validate ");
-    try cli_output.writeShellArg(stdout, result.out_path);
-    try stdout.writeAll("\n");
+    if (parsed.json) {
+        try cli_output.writeImportJson(stdout, parsed.format, parsed.source_path, result);
+    } else {
+        try stdout.print("wrote {s}\n", .{result.out_path});
+        try stdout.writeAll("next: zmr validate ");
+        try cli_output.writeShellArg(stdout, result.out_path);
+        try stdout.writeAll("\n");
+    }
+    try stdout_io.flush();
 }

package/src/cli_info.zig

@@ -22,8 +22,12 @@ pub fn runVersion(allocator: std.mem.Allocator, args: *std.process.Args.Iterator
     stdout_io.init(.stdout());
     defer stdout_io.deinit();
     const stdout = stdout_io.writer();
-    if (json) return try version.writeJson(stdout);
-    try version.writePlain(stdout);
+    if (json) {
+        try version.writeJson(stdout);
+    } else {
+        try version.writePlain(stdout);
+    }
+    try stdout_io.flush();
 }
 
 pub fn runSchemas(allocator: std.mem.Allocator, args: *std.process.Args.Iterator) !void {
@@ -32,10 +36,14 @@ pub fn runSchemas(allocator: std.mem.Allocator, args: *std.process.Args.Iterator
     stdout_io.init(.stdout());
     defer stdout_io.deinit();
     const stdout = stdout_io.writer();
-    if (json) return try schema_registry.writeJson(stdout);
-    for (schema_registry.all()) |schema_info| {
-        try stdout.print("{s}\t{s}\n", .{ schema_info.name, schema_info.path });
+    if (json) {
+        try schema_registry.writeJson(stdout);
+    } else {
+        for (schema_registry.all()) |schema_info| {
+            try stdout.print("{s}\t{s}\n", .{ schema_info.name, schema_info.path });
+        }
     }
+    try stdout_io.flush();
 }
 
 fn parseArgIterator(allocator: std.mem.Allocator, args: *std.process.Args.Iterator) !bool {

package/src/cli_init.zig

@@ -57,20 +57,28 @@ pub fn run(allocator: std.mem.Allocator, args: *std.process.Args.Iterator) !void
     const stdout = stdout_io.writer();
     if (parsed.app_scaffold) {
         try scaffold.writeAppScaffold(allocator, parsed.dir, parsed.app_id, parsed.force);
-        if (parsed.json) return try cli_output.writeInitAppJson(stdout, parsed.dir, parsed.app_id);
-        for (scaffold.app_created_files) |path| {
-            try stdout.print("created {s}/{s}\n", .{ parsed.dir, path });
+        if (parsed.json) {
+            try cli_output.writeInitAppJson(stdout, parsed.dir, parsed.app_id);
+        } else {
+            for (scaffold.app_created_files) |path| {
+                try stdout.print("created {s}/{s}\n", .{ parsed.dir, path });
+            }
+            try stdout.writeAll("next: zmr doctor --strict --json --config ");
+            try cli_output.writeJoinedPathShellArg(stdout, parsed.dir, scaffold.app_config_file);
+            try stdout.writeAll("\n");
         }
-        try stdout.writeAll("next: zmr doctor --strict --json --config ");
-        try cli_output.writeJoinedPathShellArg(stdout, parsed.dir, scaffold.app_config_file);
-        try stdout.writeAll("\n");
+        try stdout_io.flush();
         return;
     }
 
     try scaffold.writeStarterScenario(allocator, parsed.path, parsed.app_id, parsed.force);
-    if (parsed.json) return try cli_output.writeInitScenarioJson(stdout, parsed.path, parsed.app_id);
-    try stdout.print("created {s}\n", .{parsed.path});
-    try stdout.writeAll("next: zmr validate ");
-    try cli_output.writeShellArg(stdout, parsed.path);
-    try stdout.writeAll("\n");
+    if (parsed.json) {
+        try cli_output.writeInitScenarioJson(stdout, parsed.path, parsed.app_id);
+    } else {
+        try stdout.print("created {s}\n", .{parsed.path});
+        try stdout.writeAll("next: zmr validate ");
+        try cli_output.writeShellArg(stdout, parsed.path);
+        try stdout.writeAll("\n");
+    }
+    try stdout_io.flush();
 }

package/src/cli_inspect.zig

@@ -84,6 +84,7 @@ pub fn run(allocator: std.mem.Allocator, args: *std.process.Args.Iterator) !void
     } else {
         try writeText(stdout, owned.inspection);
     }
+    try stdout_io.flush();
 }
 
 fn inspect(allocator: std.mem.Allocator, parsed: ParsedArgs) !OwnedInspection {

package/src/cli_run.zig

@@ -226,6 +226,7 @@ pub fn run(allocator: std.mem.Allocator, args: *std.process.Args.Iterator) !void
             run_error,
             run_discovery,
         );
+        try stdout_io.flush();
     }
     if (run_error) |err| return err;
 }

package/src/cli_trace.zig

@@ -120,6 +120,7 @@ pub fn runReport(allocator: std.mem.Allocator, args: *std.process.Args.Iterator)
         try report.writeJUnitReport(allocator, parsed.input_path, junit_path);
         try stdout.print("wrote {s}\n", .{junit_path});
     }
+    try stdout_io.flush();
 }
 
 pub fn runExplain(allocator: std.mem.Allocator, args: *std.process.Args.Iterator) !void {
@@ -132,8 +133,12 @@ pub fn runExplain(allocator: std.mem.Allocator, args: *std.process.Args.Iterator
     stdout_io.init(.stdout());
     defer stdout_io.deinit();
     const stdout = stdout_io.writer();
-    if (parsed.json) return try report.writeTraceExplanationJson(allocator, parsed.trace_dir.?, stdout);
-    try report.writeTraceExplanation(allocator, parsed.trace_dir.?, stdout);
+    if (parsed.json) {
+        try report.writeTraceExplanationJson(allocator, parsed.trace_dir.?, stdout);
+    } else {
+        try report.writeTraceExplanation(allocator, parsed.trace_dir.?, stdout);
+    }
+    try stdout_io.flush();
 }
 
 pub fn runExport(allocator: std.mem.Allocator, args: *std.process.Args.Iterator) !void {
@@ -151,4 +156,5 @@ pub fn runExport(allocator: std.mem.Allocator, args: *std.process.Args.Iterator)
     defer stdout_io.deinit();
     const stdout = stdout_io.writer();
     try stdout.print("wrote {s}\n", .{parsed.out_path.?});
+    try stdout_io.flush();
 }

package/src/cli_validate.zig

@@ -47,5 +47,6 @@ pub fn run(allocator: std.mem.Allocator, args: *std.process.Args.Iterator) !void
     } else {
         try cli_output.writeValidationText(stdout, parsed.path, result);
     }
+    try stdout_io.flush();
     if (!result.ok) std.process.exit(1);
 }

package/src/command.zig

@@ -1,3 +1,4 @@
+const builtin = @import("builtin");
 const std = @import("std");
 const stdio = @import("stdio.zig");
 
@@ -61,6 +62,7 @@ pub fn runWithInputTimeout(
         .stdin = .pipe,
         .stdout = .pipe,
         .stderr = .pipe,
+        .pgid = processGroupForTimeout(timeout_ms),
     });
     defer if (child.id != null) child.kill(stdio.io());
 
@@ -84,21 +86,16 @@ pub fn runWithTimeout(
 ) !ExecResult {
     if (timeout_ms == 0) return run(allocator, argv, max_output_bytes);
 
-    const result = std.process.run(allocator, stdio.io(), .{
+    var child = try std.process.spawn(stdio.io(), .{
         .argv = argv,
-        .stdout_limit = .limited(max_output_bytes),
-        .stderr_limit = .limited(max_output_bytes),
-        .timeout = timeoutForMs(timeout_ms),
-    }) catch |err| switch (err) {
-        error.Timeout => return timedOutResult(allocator),
-        else => |actual| return actual,
-    };
-    return .{
-        .stdout = result.stdout,
-        .stderr = result.stderr,
-        .term = result.term,
-        .timed_out = false,
-    };
+        .stdin = .ignore,
+        .stdout = .pipe,
+        .stderr = .pipe,
+        .pgid = processGroupForTimeout(timeout_ms),
+    });
+    defer if (child.id != null) child.kill(stdio.io());
+
+    return try collectSpawnedOutput(allocator, &child, max_output_bytes, timeoutForMs(timeout_ms));
 }
 
 fn collectSpawnedOutput(
@@ -121,7 +118,7 @@ fn collectSpawnedOutput(
     } else |err| switch (err) {
         error.EndOfStream => {},
         error.Timeout => {
-            child.kill(stdio.io());
+            terminateTimedOutChild(child);
             return timedOutResult(allocator);
         },
         else => |actual| return actual,
@@ -143,6 +140,34 @@ fn collectSpawnedOutput(
     };
 }
 
+fn processGroupForTimeout(timeout_ms: u64) ?std.posix.pid_t {
+    if (timeout_ms == 0) return null;
+    return switch (builtin.os.tag) {
+        .linux,
+        .macos,
+        .ios,
+        .tvos,
+        .watchos,
+        .visionos,
+        .freebsd,
+        .netbsd,
+        .openbsd,
+        .haiku,
+        .illumos,
+        => 0,
+        else => null,
+    };
+}
+
+fn terminateTimedOutChild(child: *std.process.Child) void {
+    if (child.id) |pid| {
+        if (processGroupForTimeout(1) != null and pid > 0) {
+            std.posix.kill(-pid, .TERM) catch {};
+        }
+    }
+    child.kill(stdio.io());
+}
+
 fn timedOutResult(allocator: std.mem.Allocator) !ExecResult {
     return .{
         .stdout = try allocator.dupe(u8, ""),

package/src/ios.zig

@@ -149,11 +149,18 @@ pub const IosDevice = struct {
     }
 
     pub fn visibleBySelector(self: *IosDevice, wanted: selector.Selector) !?bool {
+        return try self.visibleBySelectorWithTimeout(wanted, shimTimeoutMs());
+    }
+
+    pub fn visibleBySelectorWithTimeout(self: *IosDevice, wanted: selector.Selector, timeout_ms: u64) !?bool {
         if (self.shim_path == null) return null;
         const shim_selector = try ios_shim.selectorString(self.allocator, wanted) orelse return null;
         defer self.allocator.free(shim_selector);
 
-        const response = try self.runShim(.{ .kind = .query, .selector = shim_selector });
+        const response = try self.runShimWithTimeout(.{
+            .kind = .query,
+            .selector = shim_selector,
+        }, @max(timeout_ms, 1));
         defer self.allocator.free(response);
         return try ios_shim.parseQueryResponse(response);
     }
@@ -460,7 +467,7 @@ test "ios simulator openLink keeps sweeping delayed XCTest interruptions until a
             \\if [[ "$count" -lt 6 ]]; then
             \\  printf '{{"status":"ok","accepted":false,"count":0}}\n'
             \\else
-            \\  printf '{{"status":"ok","accepted":true,"label":"Brick Rewards Test","count":1}}\n'
+            \\  printf '{{"status":"ok","accepted":true,"label":"Demo App","count":1}}\n'
             \\fi
             \\
         , .{ tmp.sub_path, tmp.sub_path });

package/src/main.zig

@@ -165,4 +165,5 @@ fn usage() !void {
         \\assertNotVisible, assertNoneVisible, assertHealthy, snapshot, sleep. Any step may use "optional": true.
         \\
     );
+    try stdout_io.flush();
 }

package/src/runner.zig

@@ -455,3 +455,186 @@ test "assertHealthy retries through a transient observation command failure" {
     try std.testing.expect(std.mem.indexOf(u8, events, "\"kind\":\"assert.healthy\"") != null);
     try std.testing.expect(std.mem.indexOf(u8, events, "\"status\":\"ok\"") != null);
 }
+
+test "native selector waits pass bounded query timeouts instead of legacy blocking queries" {
+    const allocator = std.testing.allocator;
+    const dir = "zig-cache-test-runner-native-wait-bounded-query-timeout";
+    std.Io.Dir.cwd().deleteTree(stdio.io(), dir) catch {};
+    defer std.Io.Dir.cwd().deleteTree(stdio.io(), dir) catch {};
+
+    const NativeBoundedWaitDevice = struct {
+        allocator: std.mem.Allocator,
+        legacy_queries: usize = 0,
+        bounded_queries: usize = 0,
+        largest_query_timeout_ms: u64 = 0,
+        snapshots: usize = 0,
+
+        pub fn visibleBySelector(self: *@This(), wanted: selector.Selector) !?bool {
+            _ = wanted;
+            self.legacy_queries += 1;
+            return false;
+        }
+
+        pub fn visibleBySelectorWithTimeout(self: *@This(), wanted: selector.Selector, timeout_ms: u64) !?bool {
+            _ = wanted;
+            self.bounded_queries += 1;
+            self.largest_query_timeout_ms = @max(self.largest_query_timeout_ms, timeout_ms);
+            return false;
+        }
+
+        pub fn snapshot(self: *@This(), writer: anytype) !types.ObservationSnapshot {
+            _ = writer;
+            self.snapshots += 1;
+            const nodes = try self.allocator.alloc(types.UiNode, 0);
+            return .{
+                .id = try self.allocator.dupe(u8, "native-bounded-timeout-final"),
+                .timestamp_ms = 1,
+                .nodes = nodes,
+            };
+        }
+    };
+
+    var device = NativeBoundedWaitDevice{ .allocator = allocator };
+    var tw = try trace.TraceWriter.init(allocator, dir);
+    defer tw.deinit();
+
+    try std.testing.expect(!try waitUntilVisible(&device, .{ .id = "never-visible" }, 25, &tw, .{ .poll_ms = 0 }));
+    try std.testing.expect(device.bounded_queries > 0);
+    try std.testing.expectEqual(@as(usize, 0), device.legacy_queries);
+    try std.testing.expect(device.largest_query_timeout_ms > 0);
+    try std.testing.expect(device.largest_query_timeout_ms <= 25);
+    try std.testing.expectEqual(@as(usize, 1), device.snapshots);
+}
+
+test "native selector wait retries bounded query command timeouts before falling back" {
+    const allocator = std.testing.allocator;
+    const dir = "zig-cache-test-runner-native-wait-retries-bounded-query-timeout";
+    std.Io.Dir.cwd().deleteTree(stdio.io(), dir) catch {};
+    defer std.Io.Dir.cwd().deleteTree(stdio.io(), dir) catch {};
+
+    const NativeFlakyBoundedWaitDevice = struct {
+        allocator: std.mem.Allocator,
+        legacy_queries: usize = 0,
+        bounded_queries: usize = 0,
+        snapshots: usize = 0,
+
+        pub fn visibleBySelector(self: *@This(), wanted: selector.Selector) !?bool {
+            _ = wanted;
+            self.legacy_queries += 1;
+            return error.LegacyNativeQueryUsed;
+        }
+
+        pub fn visibleBySelectorWithTimeout(self: *@This(), wanted: selector.Selector, timeout_ms: u64) !?bool {
+            _ = wanted;
+            try std.testing.expect(timeout_ms > 0);
+            self.bounded_queries += 1;
+            if (self.bounded_queries == 1) return error.CommandTimedOut;
+            return true;
+        }
+
+        pub fn snapshot(self: *@This(), writer: anytype) !types.ObservationSnapshot {
+            _ = writer;
+            self.snapshots += 1;
+            return error.UnexpectedSnapshotFallback;
+        }
+    };
+
+    var device = NativeFlakyBoundedWaitDevice{ .allocator = allocator };
+    var tw = try trace.TraceWriter.init(allocator, dir);
+    defer tw.deinit();
+
+    try std.testing.expect(try waitUntilVisible(&device, .{ .text = "Ready" }, 100, &tw, .{ .poll_ms = 0 }));
+    try std.testing.expectEqual(@as(usize, 0), device.legacy_queries);
+    try std.testing.expectEqual(@as(usize, 2), device.bounded_queries);
+    try std.testing.expectEqual(@as(usize, 0), device.snapshots);
+
+    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\":\"observe.retry\"") != null);
+    try std.testing.expect(std.mem.indexOf(u8, events, "\"error\":\"CommandTimedOut\"") != null);
+}
+
+test "assertHealthy uses native selector probes before broad snapshots" {
+    const allocator = std.testing.allocator;
+    const dir = "zig-cache-test-runner-assert-healthy-native-selector";
+    std.Io.Dir.cwd().deleteTree(stdio.io(), dir) catch {};
+    defer std.Io.Dir.cwd().deleteTree(stdio.io(), dir) catch {};
+
+    const NativeHealthDevice = struct {
+        allocator: std.mem.Allocator,
+        queries: usize = 0,
+        snapshots: usize = 0,
+
+        pub fn visibleBySelector(self: *@This(), wanted: selector.Selector) !?bool {
+            _ = wanted;
+            self.queries += 1;
+            return false;
+        }
+
+        pub fn snapshot(self: *@This(), writer: anytype) !types.ObservationSnapshot {
+            _ = writer;
+            self.snapshots += 1;
+            return error.UnexpectedSnapshotFallback;
+        }
+    };
+
+    var device = NativeHealthDevice{ .allocator = allocator };
+    var tw = try trace.TraceWriter.init(allocator, dir);
+    defer tw.deinit();
+
+    try std.testing.expect(try assertHealthy(&device, 100, &tw, .{ .settle_ms = 0, .poll_ms = 0 }));
+    try std.testing.expect(device.queries > 0);
+    try std.testing.expectEqual(@as(usize, 0), device.snapshots);
+
+    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\":\"assert.healthy\"") != null);
+    try std.testing.expect(std.mem.indexOf(u8, events, "\"status\":\"ok\"") != null);
+    try std.testing.expect(std.mem.indexOf(u8, events, "\"strategy\":\"nativeSelector\"") != null);
+}
+
+test "assertHealthy reports unhealthy native selector matches" {
+    const allocator = std.testing.allocator;
+    const dir = "zig-cache-test-runner-assert-healthy-native-unhealthy";
+    std.Io.Dir.cwd().deleteTree(stdio.io(), dir) catch {};
+    defer std.Io.Dir.cwd().deleteTree(stdio.io(), dir) catch {};
+
+    const NativeUnhealthyDevice = struct {
+        allocator: std.mem.Allocator,
+        queries: usize = 0,
+        snapshots: usize = 0,
+
+        pub fn visibleBySelector(self: *@This(), wanted: selector.Selector) !?bool {
+            self.queries += 1;
+            if (wanted.text_contains) |text| return std.mem.eql(u8, text, "ReferenceError");
+            return false;
+        }
+
+        pub fn snapshot(self: *@This(), writer: anytype) !types.ObservationSnapshot {
+            _ = writer;
+            self.snapshots += 1;
+            return error.UnexpectedSnapshotFallback;
+        }
+    };
+
+    var device = NativeUnhealthyDevice{ .allocator = allocator };
+    var tw = try trace.TraceWriter.init(allocator, dir);
+    defer tw.deinit();
+
+    try std.testing.expect(!try assertHealthy(&device, 100, &tw, .{ .settle_ms = 0, .poll_ms = 0 }));
+    try std.testing.expect(device.queries > 0);
+    try std.testing.expectEqual(@as(usize, 0), device.snapshots);
+
+    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\":\"assert.healthy\"") != null);
+    try std.testing.expect(std.mem.indexOf(u8, events, "\"status\":\"unhealthy\"") != null);
+    try std.testing.expect(std.mem.indexOf(u8, events, "\"strategy\":\"nativeSelector\"") != null);
+    try std.testing.expect(std.mem.indexOf(u8, events, "\"matchedIndex\"") != null);
+}

package/src/runner_events.zig

@@ -48,6 +48,23 @@ pub fn recordNativeWaitTimeoutWithDiagnostics(device: anytype, tw: *trace.TraceW
     try recordDiagnosticWithStrategyAndTimeout(tw, kind, "timeout", "nativeSelector", selectors, snap, timeout_ms);
 }
 
+pub fn recordNativeSelectorArrayStatus(tw: *trace.TraceWriter, kind: []const u8, status: []const u8, selectors: []const selector.Selector, matched_index: ?usize, timeout_ms: u64) !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);
+    try out.writeAll(",\"strategy\":\"nativeSelector\"");
+    if (matched_index) |index| try out.print(",\"matchedIndex\":{d}", .{index});
+    try out.writeAll(",\"selectors\":[");
+    for (selectors, 0..) |wanted, index| {
+        if (index > 0) try out.writeAll(",");
+        try trace.writeSelectorJson(out, wanted);
+    }
+    try out.print("],\"timeoutMs\":{d}}}", .{timeout_ms});
+    try tw.recordEvent(kind, out.buffered());
+}
+
 pub fn recordSelectorArrayStatus(tw: *trace.TraceWriter, kind: []const u8, status: []const u8, selectors: []const selector.Selector, timeout_ms: u64) !void {
     var payload: std.Io.Writer.Allocating = .init(tw.allocator);
     defer payload.deinit();

package/src/runner_waits.zig

@@ -3,7 +3,6 @@ const stdio = @import("stdio.zig");
 const health = @import("health.zig");
 const runner_config = @import("runner_config.zig");
 const runner_events = @import("runner_events.zig");
-const runner_native = @import("runner_native.zig");
 const scenario = @import("scenario.zig");
 const selector = @import("selector.zig");
 const trace = @import("trace.zig");
@@ -40,18 +39,28 @@ fn untilVisibleKind(
 ) !bool {
     const deadline = stdio.nowMs() + @as(i64, @intCast(timeout_ms));
     while (true) {
-        if (try nativeVisibleBySelector(device, wanted)) |visible| {
-            if (visible) {
-                if (writer) |tw| try runner_events.recordNativeWait(tw, kind, wanted, null, timeout_ms);
-                return true;
-            }
-            if (stdio.nowMs() >= deadline) {
-                if (writer) |tw| try runner_events.recordNativeWaitTimeoutWithDiagnostics(device, tw, kind, &[_]selector.Selector{wanted}, timeout_ms);
-                return false;
+        if (nativeSelectorQueryTimeoutMs(deadline)) |query_timeout_ms| {
+            const native_result = nativeVisibleBySelector(device, wanted, query_timeout_ms) catch |err| {
+                if (try retryTransientObservation(err, kind, writer, deadline, options)) continue;
+                return err;
+            };
+            if (native_result) |visible| {
+                if (visible) {
+                    if (writer) |tw| try runner_events.recordNativeWait(tw, kind, wanted, null, timeout_ms);
+                    return true;
+                }
+                if (stdio.nowMs() >= deadline) {
+                    if (writer) |tw| try runner_events.recordNativeWaitTimeoutWithDiagnostics(device, tw, kind, &[_]selector.Selector{wanted}, timeout_ms);
+                    return false;
+                }
+                try sleepMs(options.poll_ms);
+                continue;
             }
-            try sleepMs(options.poll_ms);
-            continue;
+        } else if (hasNativeSelectorQuery(device)) {
+            if (writer) |tw| try runner_events.recordNativeWaitTimeoutWithDiagnostics(device, tw, kind, &[_]selector.Selector{wanted}, timeout_ms);
+            return false;
         }
+
         var snap = device.snapshot(writer) catch |err| {
             if (try retryTransientObservation(err, kind, writer, deadline, options)) continue;
             return err;
@@ -110,18 +119,28 @@ fn untilNotVisibleKind(
 ) !bool {
     const deadline = stdio.nowMs() + @as(i64, @intCast(timeout_ms));
     while (true) {
-        if (try nativeVisibleBySelector(device, wanted)) |visible| {
-            if (!visible) {
-                if (writer) |tw| try runner_events.recordNativeWait(tw, kind, wanted, null, timeout_ms);
-                return true;
-            }
-            if (stdio.nowMs() >= deadline) {
-                if (writer) |tw| try runner_events.recordNativeWaitTimeoutWithDiagnostics(device, tw, kind, &[_]selector.Selector{wanted}, timeout_ms);
-                return false;
+        if (nativeSelectorQueryTimeoutMs(deadline)) |query_timeout_ms| {
+            const native_result = nativeVisibleBySelector(device, wanted, query_timeout_ms) catch |err| {
+                if (try retryTransientObservation(err, kind, writer, deadline, options)) continue;
+                return err;
+            };
+            if (native_result) |visible| {
+                if (!visible) {
+                    if (writer) |tw| try runner_events.recordNativeWait(tw, kind, wanted, null, timeout_ms);
+                    return true;
+                }
+                if (stdio.nowMs() >= deadline) {
+                    if (writer) |tw| try runner_events.recordNativeWaitTimeoutWithDiagnostics(device, tw, kind, &[_]selector.Selector{wanted}, timeout_ms);
+                    return false;
+                }
+                try sleepMs(options.poll_ms);
+                continue;
             }
-            try sleepMs(options.poll_ms);
-            continue;
+        } else if (hasNativeSelectorQuery(device)) {
+            if (writer) |tw| try runner_events.recordNativeWaitTimeoutWithDiagnostics(device, tw, kind, &[_]selector.Selector{wanted}, timeout_ms);
+            return false;
         }
+
         var snap = device.snapshot(writer) catch |err| {
             if (try retryTransientObservation(err, kind, writer, deadline, options)) continue;
             return err;
@@ -161,7 +180,19 @@ pub fn waitUntilAnyVisible(
     while (true) {
         var all_native = true;
         for (selectors, 0..) |wanted, index| {
-            if (try nativeVisibleBySelector(device, wanted)) |visible| {
+            const query_timeout_ms = nativeSelectorQueryTimeoutMs(deadline) orelse {
+                if (hasNativeSelectorQuery(device)) {
+                    if (writer) |tw| try runner_events.recordNativeWaitTimeoutWithDiagnostics(device, tw, "wait.any", selectors, timeout_ms);
+                    return null;
+                }
+                all_native = false;
+                break;
+            };
+            const native_result = nativeVisibleBySelector(device, wanted, query_timeout_ms) catch |err| {
+                if (try retryTransientObservation(err, "wait.any", writer, deadline, options)) continue;
+                return err;
+            };
+            if (native_result) |visible| {
                 if (visible) {
                     if (writer) |tw| try runner_events.recordNativeWait(tw, "wait.any", wanted, index, timeout_ms);
                     return index;
@@ -171,6 +202,7 @@ pub fn waitUntilAnyVisible(
                 break;
             }
         }
+
         if (all_native) {
             if (stdio.nowMs() >= deadline) {
                 if (writer) |tw| try runner_events.recordNativeWaitTimeoutWithDiagnostics(device, tw, "wait.any", selectors, timeout_ms);
@@ -179,6 +211,7 @@ pub fn waitUntilAnyVisible(
             try sleepMs(options.poll_ms);
             continue;
         }
+
         var snap = device.snapshot(writer) catch |err| {
             if (try retryTransientObservation(err, "wait.any", writer, deadline, options)) continue;
             return err;
@@ -251,6 +284,7 @@ pub fn assertHealthy(
 ) !bool {
     const health_selectors = health.defaultSelectors();
     const deadline = stdio.nowMs() + @as(i64, @intCast(timeout_ms));
+    if (try nativeAssertHealthy(device, health_selectors, timeout_ms, writer, deadline, options)) |healthy| return healthy;
     while (true) {
         var snap = device.snapshot(writer) catch |err| {
             if (try retryTransientObservation(err, "assert.healthy", writer, deadline, options)) continue;
@@ -276,6 +310,35 @@ pub fn assertHealthy(
     }
 }
 
+fn nativeAssertHealthy(
+    device: anytype,
+    health_selectors: []const selector.Selector,
+    timeout_ms: u64,
+    writer: ?*trace.TraceWriter,
+    deadline: i64,
+    options: RunOptions,
+) !?bool {
+    if (!hasNativeSelectorQuery(device)) return null;
+
+    probe: while (true) {
+        for (health_selectors, 0..) |wanted, index| {
+            const query_timeout_ms = nativeSelectorQueryTimeoutMs(deadline) orelse return false;
+            const result = nativeVisibleBySelector(device, wanted, query_timeout_ms) catch |err| {
+                if (try retryTransientObservation(err, "assert.healthy", writer, deadline, options)) continue :probe;
+                return err;
+            };
+            const visible = result orelse return null;
+            if (visible) {
+                if (writer) |tw| try runner_events.recordNativeSelectorArrayStatus(tw, "assert.healthy", "unhealthy", health_selectors, index, timeout_ms);
+                return false;
+            }
+        }
+
+        if (writer) |tw| try runner_events.recordNativeSelectorArrayStatus(tw, "assert.healthy", "ok", health_selectors, null, timeout_ms);
+        return true;
+    }
+}
+
 pub fn scrollUntilVisible(
     device: anytype,
     wanted: selector.Selector,
@@ -340,11 +403,22 @@ pub fn scrollUntilVisible(
     }
 }
 
-fn nativeVisibleBySelector(device: anytype, wanted: selector.Selector) !?bool {
+fn hasNativeSelectorQuery(device: anytype) bool {
+    return @hasDecl(@TypeOf(device.*), "visibleBySelectorWithTimeout") or @hasDecl(@TypeOf(device.*), "visibleBySelector");
+}
+
+fn nativeVisibleBySelector(device: anytype, wanted: selector.Selector, timeout_ms: u64) !?bool {
+    if (@hasDecl(@TypeOf(device.*), "visibleBySelectorWithTimeout")) return try device.visibleBySelectorWithTimeout(wanted, timeout_ms);
     if (!@hasDecl(@TypeOf(device.*), "visibleBySelector")) return null;
     return try device.visibleBySelector(wanted);
 }
 
+fn nativeSelectorQueryTimeoutMs(deadline: i64) ?u64 {
+    const now = stdio.nowMs();
+    if (now >= deadline) return null;
+    return @as(u64, @intCast(deadline - now));
+}
+
 fn retryTransientObservation(
     err: anyerror,
     kind: []const u8,

package/src/stdio.zig

@@ -1,3 +1,4 @@
+const builtin = @import("builtin");
 const std = @import("std");
 
 const default_buffer_size = 8192;
@@ -6,6 +7,7 @@ var process_threaded: ?std.Io.Threaded = null;
 
 fn processIo() std.Io {
     if (process_threaded) |*threaded| return threaded.io();
+    if (builtin.is_test) return std.testing.io;
     return std.Io.Threaded.global_single_threaded.io();
 }
 
@@ -46,7 +48,12 @@ pub fn nowMs() i64 {
 }
 
 pub fn getenv(name: []const u8) ?[]const u8 {
-    const environ = process_environ orelse return null;
+    const environ = process_environ orelse {
+        if (builtin.is_test) {
+            return std.process.Environ.getPosix(std.testing.environ, name);
+        }
+        return null;
+    };
     const block = environ.block;
     const Block = @TypeOf(block);
     if (Block != std.process.Environ.PosixBlock) return null;
@@ -86,7 +93,15 @@ pub const Output = struct {
     }
 
     pub fn flush(self: *Output) !void {
-        if (self.initialized) try self.file_writer.interface.flush();
+        if (!self.initialized) return;
+        self.file_writer.interface.flush() catch |err| switch (err) {
+            error.WriteFailed => {
+                if (self.file_writer.err) |actual| return actual;
+                if (self.file_writer.write_file_err) |actual| return actual;
+                return err;
+            },
+            else => |actual| return actual,
+        };
     }
 
     pub fn deinit(self: *Output) void {

package/src/test_io.zig

@@ -0,0 +1,60 @@
+const std = @import("std");
+const stdio = @import("stdio.zig");
+
+pub fn cwd() Cwd {
+    return .{};
+}
+
+pub const Cwd = struct {
+    pub fn makePath(_: Cwd, path: []const u8) !void {
+        return std.Io.Dir.cwd().createDirPath(stdio.io(), path);
+    }
+
+    pub fn writeFile(_: Cwd, options: std.Io.Dir.WriteFileOptions) !void {
+        return std.Io.Dir.cwd().writeFile(stdio.io(), options);
+    }
+
+    pub fn readFileAlloc(_: Cwd, allocator: std.mem.Allocator, path: []const u8, limit: usize) ![]u8 {
+        return std.Io.Dir.cwd().readFileAlloc(stdio.io(), path, allocator, .limited(limit));
+    }
+
+    pub fn createFile(_: Cwd, path: []const u8, flags: std.Io.Dir.CreateFileOptions) !File {
+        return createFileIn(std.Io.Dir.cwd(), path, flags);
+    }
+
+    pub fn deleteTree(_: Cwd, path: []const u8) !void {
+        return std.Io.Dir.cwd().deleteTree(stdio.io(), path);
+    }
+
+    pub fn deleteFile(_: Cwd, path: []const u8) !void {
+        return std.Io.Dir.cwd().deleteFile(stdio.io(), path);
+    }
+
+    pub fn access(_: Cwd, path: []const u8, options: std.Io.Dir.AccessOptions) !void {
+        return std.Io.Dir.cwd().access(stdio.io(), path, options);
+    }
+};
+
+pub const File = struct {
+    inner: std.Io.File,
+
+    pub fn writeAll(self: *File, bytes: []const u8) !void {
+        return std.Io.File.writeStreamingAll(self.inner, stdio.io(), bytes);
+    }
+
+    pub fn chmod(self: *File, mode: std.posix.mode_t) !void {
+        return self.inner.setPermissions(stdio.io(), .fromMode(mode));
+    }
+
+    pub fn close(self: *File) void {
+        self.inner.close(stdio.io());
+    }
+};
+
+pub fn createFileIn(dir: std.Io.Dir, path: []const u8, flags: std.Io.Dir.CreateFileOptions) !File {
+    return .{ .inner = try dir.createFile(stdio.io(), path, flags) };
+}
+
+pub fn readFileAllocIn(dir: std.Io.Dir, allocator: std.mem.Allocator, path: []const u8, limit: usize) ![]u8 {
+    return dir.readFileAlloc(stdio.io(), path, allocator, .limited(limit));
+}

package/src/version.zig

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