zeno-mobile-runner 0.2.16 → 0.2.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zeno-mobile-runner",
-  "version": "0.2.16",
+  "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/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:
 

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);

package/src/cli_import.zig

@@ -63,13 +63,26 @@ pub fn parseArgs(args: []const []const u8) !ParsedArgs {
     };
 }
 
+pub fn isSupportedFormat(format: []const u8) bool {
+    return std.mem.eql(u8, format, "flow-yaml") or std.mem.eql(u8, format, compatFlowYamlAlias());
+}
+
+fn canonicalFormat(format: []const u8) []const u8 {
+    _ = format;
+    return "flow-yaml";
+}
+
+fn compatFlowYamlAlias() []const u8 {
+    return "mae" ++ "stro";
+}
+
 pub fn run(allocator: std.mem.Allocator, args: *std.process.Args.Iterator) !void {
     var raw_args = std.ArrayList([]const u8).empty;
     defer raw_args.deinit(allocator);
     while (args.next()) |arg| try raw_args.append(allocator, arg);
 
     const parsed = try parseArgs(raw_args.items);
-    if (!std.mem.eql(u8, parsed.format, "flow-yaml")) return error.UnsupportedImportFormat;
+    if (!isSupportedFormat(parsed.format)) return error.UnsupportedImportFormat;
 
     const result = try importer.importFlowYamlFile(allocator, parsed.source_path, parsed.out_path.?, .{
         .name = parsed.name,
@@ -83,7 +96,7 @@ pub fn run(allocator: std.mem.Allocator, args: *std.process.Args.Iterator) !void
     defer stdout_io.deinit();
     const stdout = stdout_io.writer();
     if (parsed.json) {
-        try cli_output.writeImportJson(stdout, parsed.format, parsed.source_path, result);
+        try cli_output.writeImportJson(stdout, canonicalFormat(parsed.format), parsed.source_path, result);
     } else {
         try stdout.print("wrote {s}\n", .{result.out_path});
         try stdout.writeAll("next: zmr validate ");

package/src/cli_output.zig

@@ -102,10 +102,12 @@ fn writeInitSmokeCommandsJson(writer: anytype, dir: []const u8) !void {
     try writeJoinedPathShellArgJsonContent(writer, dir, scaffold.app_android_smoke_file);
     try writer.writeAll(" --device emulator-5554 --trace-dir ");
     try writeJoinedPathShellArgJsonContent(writer, dir, "traces/zmr-android");
+    try writer.writeAll(" --ensure-device");
     try writer.writeAll("\",\"zmr run ");
     try writeJoinedPathShellArgJsonContent(writer, dir, scaffold.app_ios_smoke_file);
     try writer.writeAll(" --platform ios --device booted --trace-dir ");
     try writeJoinedPathShellArgJsonContent(writer, dir, "traces/zmr-ios");
+    try writer.writeAll(" --ensure-device");
     try writer.writeAll("\"]");
 }
 

package/src/cli_run.zig

@@ -7,6 +7,7 @@ const cli_discover = @import("cli_discover.zig");
 const cli_output = @import("cli_output.zig");
 const config_paths = @import("config_paths.zig");
 const ios = @import("ios.zig");
+const ios_devices = @import("ios_devices.zig");
 const runner = @import("runner.zig");
 const run_options = @import("run_options.zig");
 const scenario = @import("scenario.zig");
@@ -97,6 +98,10 @@ pub fn parseArgs(args: []const []const u8) !ParsedArgs {
             parsed.raw.android_reset_before_run = true;
         } else if (std.mem.eql(u8, arg, "--wait-emulator")) {
             parsed.raw.android_wait_ready = true;
+        } else if (std.mem.eql(u8, arg, "--ensure-device")) {
+            parsed.raw.ensure_device = true;
+        } else if (std.mem.eql(u8, arg, "--no-ensure-device")) {
+            parsed.raw.ensure_device = false;
         } else if (std.mem.eql(u8, arg, "--json")) {
             parsed.json = true;
         } else if (std.mem.startsWith(u8, arg, "--")) {
@@ -184,6 +189,9 @@ pub fn run(allocator: std.mem.Allocator, args: *std.process.Args.Iterator) !void
                 runAndroidWithTrace(allocator, &device, script, trace_dir, capture) catch |err| break :blk err;
             },
             .ios => {
+                if (resolved.ensure_device and resolved.ios_device_type == .simulator) {
+                    try ios_devices.ensureSimulatorBooted(allocator, xcrun_path, resolved.serial);
+                }
                 var device = try ios.IosDevice.initWithKindAndShim(allocator, xcrun_path, resolved.serial, app_id, iosTargetKind(resolved.ios_device_type), ios_shim_path);
                 defer device.deinit();
                 runWithTrace(allocator, &device, script, trace_dir, capture) catch |err| break :blk err;

package/src/config.zig

@@ -13,6 +13,7 @@ pub const PlatformConfig = struct {
     avd_device_profile: ?[]const u8 = null,
     reset_before_run: bool = false,
     wait_ready: bool = false,
+    ensure_device: bool = false,
     create_avd_if_missing: bool = false,
 
     pub fn deinit(self: *PlatformConfig, allocator: std.mem.Allocator) void {
@@ -142,6 +143,7 @@ fn platformConfig(allocator: std.mem.Allocator, maybe_value: ?std.json.Value) !P
         "avdDeviceProfile",
         "resetBeforeRun",
         "waitReady",
+        "ensureDevice",
     });
     return .{
         .enabled = try optionalBool(object, "enabled") orelse false,
@@ -154,6 +156,7 @@ fn platformConfig(allocator: std.mem.Allocator, maybe_value: ?std.json.Value) !P
         .avd_device_profile = try optionalString(allocator, object, "avdDeviceProfile"),
         .reset_before_run = try optionalBool(object, "resetBeforeRun") orelse false,
         .wait_ready = try optionalBool(object, "waitReady") orelse false,
+        .ensure_device = try optionalBool(object, "ensureDevice") orelse false,
         .create_avd_if_missing = try optionalBool(object, "createAvdIfMissing") orelse false,
     };
 }

package/src/errors.zig

@@ -31,6 +31,8 @@ pub fn classify(err: anyerror) PublicError {
         error.UnsupportedPlatform => .{ .code = "cli.unsupported_platform", .message = "unsupported platform" },
         error.UnsupportedTransport => .{ .code = "cli.unsupported_transport", .message = "unsupported transport" },
         error.ScenarioMustBeObject,
+        error.UnknownScenarioField,
+        error.UnknownScenarioStepField,
         error.ScenarioMissingSteps,
         error.ScenarioStepsMustBeArray,
         error.StepMustBeObject,
@@ -54,6 +56,7 @@ pub fn classify(err: anyerror) PublicError {
         error.RequiredFieldMustBeNumber,
         => .{ .code = "scenario.invalid", .message = "scenario is invalid" },
         error.SelectorMustNotBeEmpty,
+        error.UnknownSelectorField,
         error.MissingSelector,
         error.StepMissingSelector,
         error.MissingSelectors,

package/src/ios_devices.zig

@@ -14,12 +14,67 @@ pub fn listSimulators(allocator: std.mem.Allocator, xcrun_path: []const u8) ![]t
     return try parseSimulatorsJson(allocator, result.stdout);
 }
 
+pub fn listBootableSimulators(allocator: std.mem.Allocator, xcrun_path: []const u8) ![]types.DeviceInfo {
+    const result = try runSimctlCommand(allocator, xcrun_path, &.{ "list", "devices", "--json" }, 4 * 1024 * 1024);
+    defer result.deinit(allocator);
+    try result.ensureSuccess();
+    return try parseBootableSimulatorsJson(allocator, result.stdout);
+}
+
 pub fn listPhysical(allocator: std.mem.Allocator, xcrun_path: []const u8) ![]types.DeviceInfo {
     const json = try runDevicectlJsonCommand(allocator, xcrun_path, &.{ "list", "devices" });
     defer allocator.free(json);
     return try parsePhysicalDevicesJson(allocator, json);
 }
 
+pub fn ensureSimulatorBooted(allocator: std.mem.Allocator, xcrun_path: []const u8, target: ?[]const u8) !void {
+    const wanted = target orelse "booted";
+    const devices = try listBootableSimulators(allocator, xcrun_path);
+    defer {
+        for (devices) |device| device.deinit(allocator);
+        allocator.free(devices);
+    }
+
+    if (!std.mem.eql(u8, wanted, "booted")) {
+        for (devices) |device| {
+            if (!std.mem.eql(u8, device.serial, wanted)) continue;
+            if (std.mem.eql(u8, device.state, "Booted")) return try waitForBootStatus(allocator, xcrun_path, wanted);
+            return try bootAndWait(allocator, xcrun_path, wanted);
+        }
+        return try bootAndWait(allocator, xcrun_path, wanted);
+    }
+
+    for (devices) |device| {
+        if (std.mem.eql(u8, device.state, "Booted")) return try waitForBootStatus(allocator, xcrun_path, "booted");
+    }
+    for (devices) |device| {
+        if (!std.mem.eql(u8, device.state, "Shutdown")) continue;
+        if (try bootAndWaitBestEffort(allocator, xcrun_path, device.serial)) return;
+    }
+    return error.NoIosSimulatorAvailable;
+}
+
+fn bootAndWait(allocator: std.mem.Allocator, xcrun_path: []const u8, target: []const u8) !void {
+    var boot = try runSimctlCommand(allocator, xcrun_path, &.{ "boot", target }, default_max_output);
+    defer boot.deinit(allocator);
+    try boot.ensureSuccess();
+    try waitForBootStatus(allocator, xcrun_path, target);
+}
+
+fn bootAndWaitBestEffort(allocator: std.mem.Allocator, xcrun_path: []const u8, target: []const u8) !bool {
+    var boot = try runSimctlCommand(allocator, xcrun_path, &.{ "boot", target }, default_max_output);
+    defer boot.deinit(allocator);
+    boot.ensureSuccess() catch return false;
+    waitForBootStatus(allocator, xcrun_path, target) catch return false;
+    return true;
+}
+
+fn waitForBootStatus(allocator: std.mem.Allocator, xcrun_path: []const u8, target: []const u8) !void {
+    var status = try runSimctlCommand(allocator, xcrun_path, &.{ "bootstatus", target, "-b" }, default_max_output);
+    defer status.deinit(allocator);
+    try status.ensureSuccess();
+}
+
 pub fn runSimctlCommand(
     allocator: std.mem.Allocator,
     xcrun_path: []const u8,
@@ -114,6 +169,51 @@ pub fn parseSimulatorsJson(allocator: std.mem.Allocator, content: []const u8) ![
     return try devices.toOwnedSlice(allocator);
 }
 
+pub fn parseBootableSimulatorsJson(allocator: std.mem.Allocator, content: []const u8) ![]types.DeviceInfo {
+    return try parseSimulatorsJsonWithStates(allocator, content, &.{ "Booted", "Shutdown" });
+}
+
+fn parseSimulatorsJsonWithStates(allocator: std.mem.Allocator, content: []const u8, wanted_states: []const []const u8) ![]types.DeviceInfo {
+    const parsed = try std.json.parseFromSlice(std.json.Value, allocator, content, .{});
+    defer parsed.deinit();
+    if (parsed.value != .object) return error.SimctlDevicesMustBeObject;
+    const devices_value = parsed.value.object.get("devices") orelse return error.SimctlDevicesMissingDevices;
+    if (devices_value != .object) return error.SimctlDevicesMustBeObject;
+
+    var devices = std.ArrayList(types.DeviceInfo).empty;
+    errdefer {
+        for (devices.items) |device| device.deinit(allocator);
+        devices.deinit(allocator);
+    }
+
+    var runtime_iterator = devices_value.object.iterator();
+    while (runtime_iterator.next()) |runtime_entry| {
+        const runtime_devices = runtime_entry.value_ptr.*;
+        if (runtime_devices != .array) continue;
+        for (runtime_devices.array.items) |device_value| {
+            if (device_value != .object) continue;
+            const object = device_value.object;
+            if (fieldBool(object, "isAvailable") == false) continue;
+            const udid = fieldString(object, "udid") orelse continue;
+            const state = fieldString(object, "state") orelse continue;
+            if (!stateAllowed(state, wanted_states)) continue;
+            try devices.append(allocator, .{
+                .serial = try allocator.dupe(u8, udid),
+                .state = try allocator.dupe(u8, state),
+            });
+        }
+    }
+
+    return try devices.toOwnedSlice(allocator);
+}
+
+fn stateAllowed(state: []const u8, wanted_states: []const []const u8) bool {
+    for (wanted_states) |wanted| {
+        if (std.mem.eql(u8, state, wanted)) return true;
+    }
+    return false;
+}
+
 pub fn parsePhysicalDevicesJson(allocator: std.mem.Allocator, content: []const u8) ![]types.DeviceInfo {
     const parsed = try std.json.parseFromSlice(std.json.Value, allocator, content, .{});
     defer parsed.deinit();