zeno-mobile-runner 0.2.15 → 0.2.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zeno-mobile-runner",
-  "version": "0.2.15",
+  "version": "0.2.17",
   "description": "Agent-native mobile app test runner for React Native, Expo, Flutter, and native Android/iOS.",
   "main": "npm/index.mjs",
   "repository": {
@@ -104,7 +104,7 @@
     "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",
-    "test": "node --test tests/viewer-parser.test.mjs tests/npm-scaffold-helpers.test.mjs tests/npm-cli.test.mjs tests/npm-package.test.mjs tests/typescript-client.test.mjs && python3 -W error -m unittest tests/python_client_test.py && bash tests/go-client-test.sh && bash tests/rust-client-test.sh"
+    "test": "npm run build:zmr && node --test tests/viewer-parser.test.mjs tests/npm-scaffold-helpers.test.mjs tests/npm-cli.test.mjs tests/npm-package.test.mjs tests/typescript-client.test.mjs && python3 -W error -m unittest tests/python_client_test.py && bash tests/go-client-test.sh && bash tests/rust-client-test.sh"
   },
   "keywords": [
     "mobile-testing",

package/schemas/README.md

@@ -1,6 +1,8 @@
 # ZMR Schemas
 
-This directory contains draft 2020-12 JSON Schemas for public ZMR file and protocol payloads.
+This directory contains draft 2020-12 JSON Schemas for public ZMR files,
+commands, diagnostics, and protocol payloads. Agents and app setup scripts
+should use these schemas for validation instead of inferring shapes from prose.
 
 - `scenario.schema.json`: scenario files consumed by `zmr run` and `zmr validate`
 - `snapshot.schema.json`: `ObservationSnapshot` JSON emitted by live RPC and persisted trace snapshots, including viewport and optional display density metrics
@@ -13,7 +15,7 @@ This directory contains draft 2020-12 JSON Schemas for public ZMR file and proto
 - `doctor-output.schema.json`: machine-readable `zmr doctor --json` setup diagnostics, including remediation hints for actionable checks
 - `init-output.schema.json`: machine-readable `zmr init --json` bootstrap output for scenario and app-local `.zmr/` initialization
 - `import-output.schema.json`: machine-readable `zmr import --json` output for one-time scenario migration helpers
-- `devices-output.schema.json`: machine-readable `zmr devices --json` output for Android, iOS simulator, and physical iOS discovery
+- `devices-output.schema.json`: machine-readable `zmr devices --json` output for Android, iOS/iPadOS simulator, and physical iOS/iPadOS discovery
 - `validate-output.schema.json`: machine-readable `zmr validate --json` scenario preflight output
 - `version-output.schema.json`: machine-readable `zmr version --json` output for runner and protocol compatibility discovery
 - `capabilities-output.schema.json`: machine-readable `runner.capabilities` JSON-RPC result for protocol, platform support, transport, and method discovery
@@ -27,4 +29,5 @@ This directory contains draft 2020-12 JSON Schemas for public ZMR file and proto
 - `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
 
-The Zig test suite verifies these files parse as JSON. Full schema validation is intentionally left to client tooling for now.
+The Zig test suite verifies these files parse as JSON. Full schema validation is
+intentionally left to client tooling for now.

package/schemas/import-output.schema.json

@@ -7,7 +7,7 @@
   "required": ["ok", "format", "source", "out", "name", "appId", "stepCount", "next", "nextCommands"],
   "properties": {
     "ok": { "const": true },
-    "format": { "enum": ["flow-yaml"] },
+    "format": { "const": "flow-yaml" },
     "source": { "type": "string", "minLength": 1 },
     "out": { "type": "string", "minLength": 1 },
     "name": { "type": "string", "minLength": 1 },

package/schemas/scenario.schema.json

@@ -22,6 +22,7 @@
       "properties": {
         "id": { "type": "string" },
         "resourceId": { "type": "string" },
+        "stableId": { "type": "string" },
         "text": { "type": "string" },
         "textContains": { "type": "string" },
         "contentDesc": { "type": "string" },
@@ -31,6 +32,7 @@
     },
     "step": {
       "type": "object",
+      "additionalProperties": false,
       "required": ["action"],
       "properties": {
         "action": {

package/schemas/zmr-config.schema.json

@@ -68,7 +68,8 @@
         "avdSystemImage": { "type": "string", "minLength": 1 },
         "avdDeviceProfile": { "type": "string", "minLength": 1 },
         "resetBeforeRun": { "type": "boolean", "default": false },
-        "waitReady": { "type": "boolean", "default": false }
+        "waitReady": { "type": "boolean", "default": false },
+        "ensureDevice": { "type": "boolean", "default": false }
       }
     }
   }

package/scripts/install-ios-shim.sh

@@ -165,8 +165,28 @@ fi
 
 mkdir -p "$APP_ROOT"
 APP_ROOT="$(cd "$APP_ROOT" && pwd)"
-mkdir -p "$APP_ROOT/.zmr" "$APP_ROOT/.zmr/shims/ios"
-rm -f "$APP_ROOT/.zmr/ios-shim-state/build-for-testing.ready"
+SHIM_INSTALL_FINGERPRINT="$(
+  {
+    printf '%s\n' \
+      "$SCHEME" \
+      "$TEST_TARGET" \
+      "$TEST_BUNDLE_ID" \
+      "$WORKSPACE" \
+      "$PROJECT" \
+      "$APP_TARGET" \
+      "$BUNDLE_ID" \
+      "$DERIVED_DATA_PATH" \
+      "$DEVICE_TYPE" \
+      "$CONFIGURATION" \
+      "$DEPLOYMENT_TARGET"
+    shasum -a 256 \
+      "$ROOT/scripts/install-ios-shim.sh" \
+      "$ROOT/scripts/ensure-ios-shim-target.rb" \
+      "$ROOT/shims/ios/ZMRShim.swift" \
+      "$ROOT/shims/ios/ZMRShimUITestCase.swift"
+  } | shasum -a 256 | awk '{print $1}'
+)"
+mkdir -p "$APP_ROOT/.zmr" "$APP_ROOT/.zmr/shims/ios" "$APP_ROOT/.zmr/ios-shim-state"
 rm -f "$APP_ROOT/.zmr/ios-shim-state/destination.id"
 rm -f "$APP_ROOT/.zmr/ios-shim-state/xcodebuild.pid"
 rm -f "$APP_ROOT/.zmr/ios-shim-state/xcodebuild.log"
@@ -222,8 +242,13 @@ PID_FILE="\$STATE_DIR/xcodebuild.pid"
 READY_FILE="\$SERVER_DIR/ready"
 DESTINATION_ID_FILE="\$STATE_DIR/destination.id"
 BUILD_READY_FILE="\$STATE_DIR/build-for-testing.ready"
+BUILD_FINGERPRINT_FILE="\$STATE_DIR/build-for-testing.fingerprint"
+DERIVED_DATA_CLEAN_FINGERPRINT_FILE="\$STATE_DIR/derived-data-clean.fingerprint"
 LOG_FILE="\$STATE_DIR/xcodebuild.log"
 DERIVED_DATA_PATH_VALUE="$DERIVED_DATA_PATH"
+INSTALL_FINGERPRINT_VALUE="$SHIM_INSTALL_FINGERPRINT"
+ZMR_TEST_TARGET_NAME="$TEST_TARGET"
+ZMR_SCHEME_NAME="$SCHEME"
 STDIN_FILE="\$(mktemp)"
 trap 'rm -f "\$STDIN_FILE"' EXIT
 
@@ -337,6 +362,9 @@ clean_zmr_derived_data() {
   if [[ -z "\$DERIVED_DATA_PATH_VALUE" ]]; then
     return 0
   fi
+  if [[ "\${ZMR_IOS_SHIM_FORCE_REBUILD:-}" != "1" && -f "\$DERIVED_DATA_CLEAN_FINGERPRINT_FILE" ]] && [[ "\$(cat "\$DERIVED_DATA_CLEAN_FINGERPRINT_FILE" 2>/dev/null || true)" == "\$INSTALL_FINGERPRINT_VALUE" ]]; then
+    return 0
+  fi
 
   local derived_data_abs
   if [[ "\$DERIVED_DATA_PATH_VALUE" == /* ]]; then
@@ -350,7 +378,13 @@ clean_zmr_derived_data() {
 
   case "\$derived_data_abs" in
     "$APP_ROOT/ZMRDerivedData"|"$APP_ROOT"/*/ZMRDerivedData)
-      rm -rf "\$derived_data_abs"
+      if [[ -d "\$derived_data_abs/Build/Products" ]]; then
+        find "\$derived_data_abs/Build/Products" -depth \\( -name "\$ZMR_TEST_TARGET_NAME*" -o -name "\$ZMR_SCHEME_NAME*" \\) -exec rm -rf {} +
+      fi
+      if [[ -d "\$derived_data_abs/Build/Intermediates.noindex" ]]; then
+        find "\$derived_data_abs/Build/Intermediates.noindex" -depth \\( -name "\$ZMR_TEST_TARGET_NAME.build" -o -name "\$ZMR_SCHEME_NAME.build" \\) -exec rm -rf {} +
+      fi
+      printf '%s\\n' "\$INSTALL_FINGERPRINT_VALUE" > "\$DERIVED_DATA_CLEAN_FINGERPRINT_FILE"
       ;;
     *)
       echo "warning: refusing to delete non-ZMR derived data path: \$DERIVED_DATA_PATH_VALUE" >&2
@@ -418,7 +452,7 @@ wait_for_ready() {
 }
 
 build_for_testing() {
-  if [[ "\${ZMR_IOS_SHIM_FORCE_REBUILD:-}" != "1" && -f "\$BUILD_READY_FILE" ]]; then
+  if [[ "\${ZMR_IOS_SHIM_FORCE_REBUILD:-}" != "1" && -f "\$BUILD_READY_FILE" && -f "\$BUILD_FINGERPRINT_FILE" ]] && [[ "\$(cat "\$BUILD_FINGERPRINT_FILE" 2>/dev/null || true)" == "\$INSTALL_FINGERPRINT_VALUE" ]]; then
     return 0
   fi
 
@@ -437,6 +471,7 @@ build_for_testing() {
       ZMR_SHIM_SERVER_DIR="\$SERVER_DIR" \\
       ZMR_APP_BUNDLE_ID="$BUNDLE_ID"
 
+  printf '%s\\n' "\$INSTALL_FINGERPRINT_VALUE" > "\$BUILD_FINGERPRINT_FILE"
   touch "\$BUILD_READY_FILE"
 }
 

package/scripts/public-metadata-guard.sh

@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+usage() {
+  cat <<'USAGE'
+Usage:
+  scripts/public-metadata-guard.sh [--repo <path>]
+
+Rejects unwanted public contributor/client strings in public docs, public branch
+commit metadata, and tag metadata. Local backup refs are intentionally ignored.
+USAGE
+}
+
+die() {
+  echo "error: $*" >&2
+  exit 2
+}
+
+require_value() {
+  local flag="$1"
+  local value="${2-}"
+  if [[ -z "$value" || "$value" == --* ]]; then
+    die "$flag requires a value"
+  fi
+}
+
+while [[ "$#" -gt 0 ]]; do
+  case "$1" in
+    --repo)
+      require_value "$1" "${2-}"
+      ROOT="$2"
+      shift 2
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "unknown argument: $1" >&2
+      usage >&2
+      exit 2
+      ;;
+  esac
+done
+
+ROOT="$(cd "$ROOT" && pwd)"
+
+bad_claude="Clau""de"
+bad_claude_lower="clau""de"
+bad_anthropic="anth""ropic"
+metadata_deny_regex="(${bad_claude} Fable|noreply@${bad_anthropic}[.]com|Co-Authored-By:[[:space:]]*${bad_claude})"
+doc_deny_regex="(${metadata_deny_regex}|${bad_claude} Code|${bad_claude_lower}[[:space:]]+mcp[[:space:]]+add)"
+
+scan_public_files() {
+  git -C "$ROOT" ls-files -z -- \
+    README.md \
+    FEATURES.md \
+    CHANGELOG.md \
+    SECURITY.md \
+    CONTRIBUTING.md \
+    docs \
+    skills \
+    .github
+}
+
+while IFS= read -r -d '' path; do
+  if LC_ALL=C grep -nI -i -E "$doc_deny_regex" "$ROOT/$path" >/dev/null 2>&1; then
+    echo "denied public metadata string in file contents: $path" >&2
+    exit 1
+  fi
+done < <(scan_public_files)
+
+current_ref="$(git -C "$ROOT" symbolic-ref -q HEAD || true)"
+{
+  if [[ -n "$current_ref" ]]; then
+    printf '%s\n' "$current_ref"
+  else
+    printf '%s\n' HEAD
+  fi
+  git -C "$ROOT" for-each-ref --format='%(refname)' refs/remotes/origin refs/tags |
+    grep -v '^refs/remotes/origin/HEAD$' || true
+} | sort -u | while IFS= read -r ref; do
+  if [[ -z "$ref" ]]; then
+    continue
+  fi
+  if git -C "$ROOT" log "$ref" --format='%H%n%an <%ae>%n%cn <%ce>%n%B' |
+    LC_ALL=C grep -i -E "$metadata_deny_regex" >/dev/null 2>&1; then
+    echo "denied public metadata string in commit metadata: $ref" >&2
+    exit 1
+  fi
+
+  if git -C "$ROOT" for-each-ref "$ref" --format='%(taggername) %(taggeremail)%0a%(contents)' |
+    LC_ALL=C grep -i -E "$metadata_deny_regex" >/dev/null 2>&1; then
+    echo "denied public metadata string in tag metadata: $ref" >&2
+    exit 1
+  fi
+done
+
+printf 'public metadata verified: %s\n' "$ROOT"

package/shims/android/README.md

@@ -1,7 +1,8 @@
 # ZMR Android Shim
 
-This directory contains the native Android instrumentation shim scaffold that
-supplements the current ADB/UI Automator adapter.
+This directory contains the app-local Android instrumentation shim scaffold.
+The shim supplements the ADB/UI Automator adapter; it does not replace the
+public scenario or JSON-RPC contracts.
 
 Current status:
 
@@ -13,7 +14,7 @@ Current status:
   command and copies the instrumentation source file into the app repo for
   inclusion in `androidTest`.
 
-V1 target:
+Target behavior:
 
 - Faster hierarchy retrieval than repeated shell UI Automator dumps.
 - Reliable tap, type, swipe, and key actions with ADB fallback.

package/shims/android/protocol.md

@@ -1,8 +1,9 @@
 # Android Shim Protocol
 
-The Android shim protocol is internal and may change before `v1.0.0`.
+The Android shim protocol is internal. It may change before `v1.0.0` without a
+public protocol version bump.
 
-The first implementation should mirror the public ZMR action model:
+The implementation should mirror the public ZMR action model:
 
 - `snapshot`
 - `tap`

package/shims/ios/README.md

@@ -1,11 +1,11 @@
 # ZMR iOS Shim
 
-This directory contains the XCTest/XCUIAutomation shim scaffold used for
-selector-grade iOS automation.
+This directory contains the app-local XCTest/XCUIAutomation shim scaffold used
+for selector-grade iOS and iPadOS automation.
 
-The public ZMR API remains the scenario file and JSON-RPC protocol. The shim
-protocol is an internal local transport between the Zig runner and an app-local
-UI test runner.
+The public ZMR API remains scenario JSON, JSON-RPC, MCP tools, and CLI flags.
+The shim protocol is an internal local transport between the Zig runner and an
+app-local UI test runner.
 
 Current status:
 
@@ -21,8 +21,9 @@ Current status:
   refresh the cached test bundle, or `ZMR_IOS_SHIM_ONESHOT=1` to force the
   slower one-command XCTest fallback for debugging. When configured with a
   ZMR-owned derived data path ending in `ZMRDerivedData`, the command removes
-  that directory before each `build-for-testing` refresh and refuses to delete
-  arbitrary shared DerivedData paths.
+  only stale shim target products and intermediates before a needed
+  `build-for-testing` refresh, preserves app and Pods build outputs, and
+  refuses to delete arbitrary shared DerivedData paths.
 - The iOS adapter still uses `xcrun simctl` for simulator install, launch,
   terminate, open link, screenshots, and logs. It uses `xcrun devicectl` for
   physical-device lifecycle where Apple exposes a supported local command, and

package/shims/ios/ZMRShimUITestCase.swift

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

package/shims/ios/protocol.md

@@ -1,6 +1,7 @@
 # iOS Shim Protocol
 
-The iOS shim protocol is internal and may change before `v1.0.0`.
+The iOS shim protocol is internal. It may change before `v1.0.0` without a
+public protocol version bump.
 
 Commands are newline-delimited JSON objects:
 

package/skills/zmr-mobile-testing/SKILL.md

@@ -5,9 +5,9 @@ description: Use when testing mobile apps with Zeno Mobile Runner, integrating a
 
 # ZMR Mobile Testing
 
-Use ZMR as the typed control plane for mobile app testing. Keep model reasoning
-outside the runner; use ZMR for device discovery, observations, actions, waits,
-assertions, traces, and diagnostics.
+Use ZMR as the typed mobile control plane for agent-led app verification. Keep
+model reasoning outside the runner; use ZMR for device discovery, observations,
+actions, waits, assertions, traces, diagnostics, and redacted evidence.
 
 ## Start From App-Local State
 
@@ -15,7 +15,7 @@ assertions, traces, and diagnostics.
 2. If it is missing, scaffold it:
 
    ```bash
-   npx zmr-wizard --app-id com.example.mobiletest --package-json
+   zmr init --app --app-id com.example.mobiletest
    ```
 
 3. Run setup diagnostics before touching a device:
@@ -30,7 +30,7 @@ Use `zmr doctor --strict --json` for CI-style gates.
 
 ## Agent Session Pattern
 
-Prefer JSON-RPC over stdio for interactive agent work:
+Prefer a long-running JSON-RPC session for interactive agent work:
 
 ```bash
 zmr serve --transport stdio --config .zmr/config.json --trace-dir traces/zmr-agent
@@ -96,9 +96,10 @@ zmr run .zmr/<scenario>.json --json --trace-dir traces/zmr-<scenario>
 zmr explain --json traces/zmr-<scenario>
 ```
 
-Prefer stable selectors: resource id or accessibility identifier first,
-content description/accessibility label second, exact text third, textContains
-only when copy varies, coordinates last.
+Prefer stable selectors: resource id or accessibility identifier first, content
+description/accessibility label second, exact text third, `textContains` only
+when copy varies, `stableId` only as a live-session fallback, and coordinates
+last.
 
 Use `waitAny` for valid branches and `whenVisible` for optional screens. Keep
 credentials, private app terms, and private traces out of public docs and

package/src/android_emulator.zig

@@ -1,5 +1,6 @@
 const std = @import("std");
 const stdio = @import("stdio.zig");
+const android_device_info = @import("android_device_info.zig");
 const command = @import("command.zig");
 
 const default_timeout_ms = 15_000;
@@ -16,17 +17,38 @@ pub const PreflightOptions = struct {
     avd_device_profile: ?[]const u8 = null,
     reset_before_run: bool = false,
     wait_ready: bool = false,
+    ensure_ready: bool = false,
     event_log_path: ?[]const u8 = null,
 };
 
 pub fn hasWork(options: PreflightOptions) bool {
-    return options.reset_before_run or options.wait_ready or options.create_avd_if_missing or options.avd_name != null or options.restore_snapshot != null;
+    return options.ensure_ready or options.reset_before_run or options.wait_ready or options.create_avd_if_missing or options.avd_name != null or options.restore_snapshot != null;
 }
 
 pub fn runPreflight(allocator: std.mem.Allocator, options: PreflightOptions) !void {
     if (!hasWork(options)) return;
 
-    if ((options.reset_before_run or options.restore_snapshot != null or options.create_avd_if_missing or options.avd_name != null) and options.avd_name == null) {
+    const must_run_lifecycle = options.reset_before_run or options.restore_snapshot != null or options.create_avd_if_missing;
+    if (options.ensure_ready and !must_run_lifecycle and try requestedDeviceReady(allocator, options)) {
+        if (options.wait_ready) try waitReady(allocator, options);
+        return;
+    }
+
+    var owned_avd: ?[]u8 = null;
+    defer if (owned_avd) |avd| allocator.free(avd);
+    const avd_name = if (options.avd_name) |avd|
+        avd
+    else blk: {
+        if (!options.ensure_ready) break :blk null;
+        var list = try runEmulator(allocator, options, &.{"-list-avds"});
+        defer list.deinit(allocator);
+        try list.ensureSuccess();
+        const first = (try firstAvdNameFromList(list.stdout)) orelse return error.NoAndroidAvdAvailable;
+        owned_avd = try allocator.dupe(u8, first);
+        break :blk owned_avd.?;
+    };
+
+    if ((options.reset_before_run or options.restore_snapshot != null or options.create_avd_if_missing or avd_name != null) and avd_name == null) {
         return error.MissingAndroidAvdName;
     }
     if (options.create_avd_if_missing and options.avd_system_image == null) {
@@ -34,7 +56,7 @@ pub fn runPreflight(allocator: std.mem.Allocator, options: PreflightOptions) !vo
     }
 
     if (options.create_avd_if_missing) {
-        try createAvdIfMissing(allocator, options, options.avd_name.?);
+        try createAvdIfMissing(allocator, options, avd_name.?);
     }
 
     if (options.reset_before_run) {
@@ -42,15 +64,32 @@ pub fn runPreflight(allocator: std.mem.Allocator, options: PreflightOptions) !vo
         if (reset) |result| result.deinit(allocator);
     }
 
-    if (options.avd_name) |avd| {
+    if (avd_name) |avd| {
         try startEmulator(allocator, options, avd);
     }
 
-    if (options.wait_ready) {
+    if (options.wait_ready or options.ensure_ready) {
         try waitReady(allocator, options);
     }
 }
 
+fn requestedDeviceReady(allocator: std.mem.Allocator, options: PreflightOptions) !bool {
+    const devices = android_device_info.listDevices(allocator, options.adb_path) catch return false;
+    defer {
+        for (devices) |device| device.deinit(allocator);
+        allocator.free(devices);
+    }
+    for (devices) |device| {
+        if (!std.mem.eql(u8, device.state, "device")) continue;
+        if (options.device_serial) |serial| {
+            if (std.mem.eql(u8, device.serial, serial)) return true;
+        } else {
+            return true;
+        }
+    }
+    return false;
+}
+
 fn createAvdIfMissing(allocator: std.mem.Allocator, options: PreflightOptions, avd: []const u8) !void {
     var list = try runEmulator(allocator, options, &.{"-list-avds"});
     defer list.deinit(allocator);
@@ -79,6 +118,16 @@ fn avdListContains(output: []const u8, avd: []const u8) bool {
     return false;
 }
 
+pub fn firstAvdNameFromList(output: []const u8) !?[]const u8 {
+    var lines = std.mem.splitScalar(u8, output, '\n');
+    while (lines.next()) |raw_line| {
+        const line = std.mem.trim(u8, raw_line, " \t\r\n");
+        if (line.len == 0) continue;
+        return line;
+    }
+    return null;
+}
+
 fn runEmulator(allocator: std.mem.Allocator, options: PreflightOptions, extra: []const []const u8) !command.ExecResult {
     var argv = std.ArrayList([]const u8).empty;
     defer argv.deinit(allocator);