zeno-mobile-runner 0.2.15 → 0.2.17

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

package/src/main.zig

@@ -154,7 +154,7 @@ fn usage() !void {
         \\  zmr init --app [--dir <app-root>] [--app-id <id>] [--force] [--json]
         \\  zmr import flow-yaml <flow.yaml> --out <scenario.json> [--name <name>] [--app-id <id>] [--force] [--json]
         \\  zmr inspect [--json] [--dir <app-root>] [--config <path>]
-        \\  zmr run [scenario.json] [--json] [--config <path>] [--platform android|ios] [--ios-device-type simulator|physical] [--device <serial>] [--app-id <id>] [--trace-dir <path>] [--discover-out <scenario.json>] [--android-avd <name>] [--create-avd-if-missing] [--avd-system-image <pkg>] [--avd-device <profile>] [--restore-snapshot <name>] [--reset-emulator] [--wait-emulator] [--screen-record] [--no-screen-record] [--adb <path>] [--emulator <path>] [--avdmanager <path>] [--android-shim <path>] [--xcrun <path>] [--ios-shim <path>]
+        \\  zmr run [scenario.json] [--json] [--config <path>] [--platform android|ios] [--ios-device-type simulator|physical] [--device <serial>] [--app-id <id>] [--trace-dir <path>] [--discover-out <scenario.json>] [--android-avd <name>] [--create-avd-if-missing] [--avd-system-image <pkg>] [--avd-device <profile>] [--restore-snapshot <name>] [--reset-emulator] [--wait-emulator] [--ensure-device] [--no-ensure-device] [--screen-record] [--no-screen-record] [--adb <path>] [--emulator <path>] [--avdmanager <path>] [--android-shim <path>] [--xcrun <path>] [--ios-shim <path>]
         \\  zmr report <trace-or-benchmark-dir> --out <report.html> [--junit <report.xml>]
         \\  zmr explain <trace-dir> [--json]
         \\  zmr export <trace-dir> --out <bundle.zmrtrace> [--redact] [--omit-screenshots]

package/src/mcp_protocol.zig

@@ -61,6 +61,9 @@ pub fn writeId(writer: anytype, id: ?std.json.Value) !void {
     }
 }
 
+const selector_schema_json =
+    "{\"type\":\"object\",\"additionalProperties\":false,\"minProperties\":1,\"properties\":{\"id\":{\"type\":\"string\"},\"resourceId\":{\"type\":\"string\"},\"stableId\":{\"type\":\"string\"},\"text\":{\"type\":\"string\"},\"textContains\":{\"type\":\"string\"},\"contentDesc\":{\"type\":\"string\"},\"contentDescContains\":{\"type\":\"string\"},\"className\":{\"type\":\"string\"}}}";
+
 const tool_list_json =
     "{\"tools\":[" ++
     "{\"name\":\"snapshot\",\"description\":\"Capture the current mobile observation snapshot as JSON.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"properties\":{}}}," ++
@@ -69,19 +72,19 @@ const tool_list_json =
     "{\"name\":\"launch_app\",\"description\":\"Launch the configured app on the selected device.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"properties\":{}}}," ++
     "{\"name\":\"stop_app\",\"description\":\"Stop the configured app on the selected device.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"properties\":{}}}," ++
     "{\"name\":\"clear_state\",\"description\":\"Clear the configured app state where the platform supports it.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"properties\":{}}}," ++
-    "{\"name\":\"tap\",\"description\":\"Tap a visible element by selector.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"required\":[\"selector\"],\"properties\":{\"selector\":{\"type\":\"object\"}}}}," ++
-    "{\"name\":\"type\",\"description\":\"Type text, optionally after focusing an element by selector.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"required\":[\"text\"],\"properties\":{\"selector\":{\"type\":\"object\"},\"text\":{\"type\":\"string\"}}}}," ++
+    "{\"name\":\"tap\",\"description\":\"Tap a visible element by selector.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"required\":[\"selector\"],\"properties\":{\"selector\":" ++ selector_schema_json ++ "}}}," ++
+    "{\"name\":\"type\",\"description\":\"Type text, optionally after focusing an element by selector.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"required\":[\"text\"],\"properties\":{\"selector\":" ++ selector_schema_json ++ ",\"text\":{\"type\":\"string\"}}}}," ++
     "{\"name\":\"hide_keyboard\",\"description\":\"Dismiss the software keyboard when the platform can do so.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"properties\":{}}}," ++
-    "{\"name\":\"erase_text\",\"description\":\"Erase text, optionally after focusing an element by selector.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"properties\":{\"selector\":{\"type\":\"object\"},\"maxChars\":{\"type\":\"integer\",\"minimum\":0}}}}," ++
+    "{\"name\":\"erase_text\",\"description\":\"Erase text, optionally after focusing an element by selector.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"properties\":{\"selector\":" ++ selector_schema_json ++ ",\"maxChars\":{\"type\":\"integer\",\"minimum\":0}}}}," ++
     "{\"name\":\"swipe\",\"description\":\"Swipe between absolute screen coordinates.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"required\":[\"x1\",\"y1\",\"x2\",\"y2\"],\"properties\":{\"x1\":{\"type\":\"integer\"},\"y1\":{\"type\":\"integer\"},\"x2\":{\"type\":\"integer\"},\"y2\":{\"type\":\"integer\"},\"durationMs\":{\"type\":\"integer\",\"minimum\":0}}}}," ++
     "{\"name\":\"press_back\",\"description\":\"Press Android back or the platform-equivalent navigation action.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"properties\":{}}}," ++
     "{\"name\":\"open_link\",\"description\":\"Open a deep link URL in the target app.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"required\":[\"url\"],\"properties\":{\"url\":{\"type\":\"string\"}}}}," ++
-    "{\"name\":\"wait_visible\",\"description\":\"Wait for an element selector to become visible.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"required\":[\"selector\"],\"properties\":{\"selector\":{\"type\":\"object\"},\"timeoutMs\":{\"type\":\"integer\",\"minimum\":0}}}}," ++
-    "{\"name\":\"wait_not_visible\",\"description\":\"Wait for an element selector to no longer be visible.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"required\":[\"selector\"],\"properties\":{\"selector\":{\"type\":\"object\"},\"timeoutMs\":{\"type\":\"integer\",\"minimum\":0}}}}," ++
-    "{\"name\":\"wait_any\",\"description\":\"Wait for the first visible selector from an ordered selector list.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"required\":[\"selectors\"],\"properties\":{\"selectors\":{\"type\":\"array\",\"minItems\":1,\"items\":{\"type\":\"object\"}},\"timeoutMs\":{\"type\":\"integer\",\"minimum\":0}}}}," ++
-    "{\"name\":\"scroll_until_visible\",\"description\":\"Scroll until an element selector is visible.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"required\":[\"selector\"],\"properties\":{\"selector\":{\"type\":\"object\"},\"direction\":{\"type\":\"string\",\"enum\":[\"down\",\"up\"]},\"timeoutMs\":{\"type\":\"integer\",\"minimum\":0}}}}," ++
-    "{\"name\":\"assert_visible\",\"description\":\"Assert that an element selector is visible within the timeout.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"required\":[\"selector\"],\"properties\":{\"selector\":{\"type\":\"object\"},\"timeoutMs\":{\"type\":\"integer\",\"minimum\":0}}}}," ++
-    "{\"name\":\"assert_not_visible\",\"description\":\"Assert that an element selector is not visible within the timeout.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"required\":[\"selector\"],\"properties\":{\"selector\":{\"type\":\"object\"},\"timeoutMs\":{\"type\":\"integer\",\"minimum\":0}}}}," ++
+    "{\"name\":\"wait_visible\",\"description\":\"Wait for an element selector to become visible.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"required\":[\"selector\"],\"properties\":{\"selector\":" ++ selector_schema_json ++ ",\"timeoutMs\":{\"type\":\"integer\",\"minimum\":0}}}}," ++
+    "{\"name\":\"wait_not_visible\",\"description\":\"Wait for an element selector to no longer be visible.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"required\":[\"selector\"],\"properties\":{\"selector\":" ++ selector_schema_json ++ ",\"timeoutMs\":{\"type\":\"integer\",\"minimum\":0}}}}," ++
+    "{\"name\":\"wait_any\",\"description\":\"Wait for the first visible selector from an ordered selector list.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"required\":[\"selectors\"],\"properties\":{\"selectors\":{\"type\":\"array\",\"minItems\":1,\"items\":" ++ selector_schema_json ++ "},\"timeoutMs\":{\"type\":\"integer\",\"minimum\":0}}}}," ++
+    "{\"name\":\"scroll_until_visible\",\"description\":\"Scroll until an element selector is visible.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"required\":[\"selector\"],\"properties\":{\"selector\":" ++ selector_schema_json ++ ",\"direction\":{\"type\":\"string\",\"enum\":[\"down\",\"up\"]},\"timeoutMs\":{\"type\":\"integer\",\"minimum\":0}}}}," ++
+    "{\"name\":\"assert_visible\",\"description\":\"Assert that an element selector is visible within the timeout.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"required\":[\"selector\"],\"properties\":{\"selector\":" ++ selector_schema_json ++ ",\"timeoutMs\":{\"type\":\"integer\",\"minimum\":0}}}}," ++
+    "{\"name\":\"assert_not_visible\",\"description\":\"Assert that an element selector is not visible within the timeout.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"required\":[\"selector\"],\"properties\":{\"selector\":" ++ selector_schema_json ++ ",\"timeoutMs\":{\"type\":\"integer\",\"minimum\":0}}}}," ++
     "{\"name\":\"assert_healthy\",\"description\":\"Assert that the app is free of common crash and error overlays.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"properties\":{\"timeoutMs\":{\"type\":\"integer\",\"minimum\":0}}}}," ++
     "{\"name\":\"scenario_validate\",\"description\":\"Validate a ZMR scenario file and return structured diagnostics.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"required\":[\"path\"],\"properties\":{\"path\":{\"type\":\"string\"}}}}," ++
     "{\"name\":\"trace_events\",\"description\":\"Read live trace events from a traced MCP session.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"properties\":{\"afterSeq\":{\"type\":\"integer\",\"minimum\":0},\"limit\":{\"type\":\"integer\",\"minimum\":1}}}}," ++

package/src/run_options.zig

@@ -28,6 +28,7 @@ pub const RawRunOptions = struct {
     android_avd_device_profile: ?[]const u8 = null,
     android_reset_before_run: ?bool = null,
     android_wait_ready: ?bool = null,
+    ensure_device: ?bool = null,
     platform: Platform = .android,
     ios_device_type: IosDeviceType = .simulator,
 };
@@ -46,6 +47,7 @@ pub const ResolvedRunOptions = struct {
     android_avd_device_profile: ?[]const u8,
     android_reset_before_run: bool,
     android_wait_ready: bool,
+    ensure_device: bool,
     platform: Platform,
     ios_device_type: IosDeviceType,
 };
@@ -86,6 +88,7 @@ pub fn resolveRun(raw: RawRunOptions, cfg: ?config.Config) ResolvedRunOptions {
         .android_avd_device_profile = raw.android_avd_device_profile orelse if (platform_cfg) |pc| pc.avd_device_profile else null,
         .android_reset_before_run = raw.android_reset_before_run orelse if (platform_cfg) |pc| pc.reset_before_run else false,
         .android_wait_ready = raw.android_wait_ready orelse if (platform_cfg) |pc| pc.wait_ready else false,
+        .ensure_device = raw.ensure_device orelse if (platform_cfg) |pc| pc.ensure_device else false,
         .platform = raw.platform,
         .ios_device_type = raw.ios_device_type,
     };
@@ -122,6 +125,7 @@ pub fn androidPreflight(
         .avd_device_profile = resolved.android_avd_device_profile,
         .reset_before_run = resolved.android_reset_before_run,
         .wait_ready = resolved.android_wait_ready,
+        .ensure_ready = resolved.ensure_device,
     };
     return if (android_emulator.hasWork(options)) options else null;
 }

package/src/scaffold.zig

@@ -131,13 +131,15 @@ fn writeAppConfig(path: []const u8, app_id: []const u8, force: bool) !void {
         \\    "enabled": true,
         \\    "defaultDevice": "emulator-5554",
         \\    "smokeScenario": ".zmr/android-smoke.json",
-        \\    "traceDir": "traces/zmr-android"
+        \\    "traceDir": "traces/zmr-android",
+        \\    "ensureDevice": true
         \\  },
         \\  "ios": {
         \\    "enabled": true,
         \\    "defaultDevice": "booted",
         \\    "smokeScenario": ".zmr/ios-smoke.json",
-        \\    "traceDir": "traces/zmr-ios"
+        \\    "traceDir": "traces/zmr-ios",
+        \\    "ensureDevice": true
         \\  },
         \\  "artifacts": {
         \\    "screenshots": true,
@@ -149,7 +151,7 @@ fn writeAppConfig(path: []const u8, app_id: []const u8, force: bool) !void {
         \\    "doctor": "zmr doctor --strict --json --config .zmr/config.json",
         \\    "schemas": "zmr schemas --json",
         \\    "validate": "zmr validate --json .zmr/android-smoke.json && zmr validate --json .zmr/ios-smoke.json",
-        \\    "android": "zmr run .zmr/android-smoke.json --device emulator-5554 --trace-dir traces/zmr-android",
+        \\    "android": "zmr run .zmr/android-smoke.json --device emulator-5554 --trace-dir traces/zmr-android --ensure-device",
         \\    "androidReport": "zmr report traces/zmr-android --out traces/zmr-android/report.html --junit traces/zmr-android/junit.xml",
         \\    "androidReliability": "export ZMR_BIN=\"${ZMR_BIN:-zmr}\"; zmr-benchmark --zmr .zmr/android-smoke.json --device emulator-5554 --app-id
     );
@@ -157,7 +159,7 @@ fn writeAppConfig(path: []const u8, app_id: []const u8, force: bool) !void {
     try writeJsonShellArg(writer, app_id);
     try writer.writeAll(
         \\ --runs 20 --trace-root traces/zmr-android-reliability --min-pass-rate 100 --max-failures 0 --max-p95-ms 30000 && \"$ZMR_BIN\" report traces/zmr-android-reliability --out traces/zmr-android-reliability/report.html --junit traces/zmr-android-reliability/junit.xml",
-        \\    "ios": "zmr run .zmr/ios-smoke.json --platform ios --device booted --trace-dir traces/zmr-ios",
+        \\    "ios": "zmr run .zmr/ios-smoke.json --platform ios --device booted --trace-dir traces/zmr-ios --ensure-device",
         \\    "iosReport": "zmr report traces/zmr-ios --out traces/zmr-ios/report.html --junit traces/zmr-ios/junit.xml",
         \\    "iosReliability": "export ZMR_BIN=\"${ZMR_BIN:-zmr}\"; zmr-benchmark --zmr .zmr/ios-smoke.json --platform ios --device booted --app-id
     );
@@ -366,7 +368,7 @@ fn writeAgentInstructions(path: []const u8, app_id: []const u8, force: bool) !vo
         \\## Direct Smoke Runs
         \\
         \\```bash
-        \\zmr run .zmr/android-smoke.json --device emulator-5554 --trace-dir traces/zmr-android
+        \\zmr run .zmr/android-smoke.json --device emulator-5554 --trace-dir traces/zmr-android --ensure-device
         \\zmr report traces/zmr-android --out traces/zmr-android/report.html --junit traces/zmr-android/junit.xml
         \\export ZMR_BIN="${ZMR_BIN:-zmr}"; zmr-benchmark --zmr .zmr/android-smoke.json --device emulator-5554 --app-id
     );
@@ -374,7 +376,7 @@ fn writeAgentInstructions(path: []const u8, app_id: []const u8, force: bool) !vo
     try writeShellArg(writer, app_id);
     try writer.writeAll(
         \\ --runs 20 --trace-root traces/zmr-android-reliability --min-pass-rate 100 --max-failures 0 --max-p95-ms 30000 && "$ZMR_BIN" report traces/zmr-android-reliability --out traces/zmr-android-reliability/report.html --junit traces/zmr-android-reliability/junit.xml
-        \\zmr run .zmr/ios-smoke.json --platform ios --device booted --trace-dir traces/zmr-ios
+        \\zmr run .zmr/ios-smoke.json --platform ios --device booted --trace-dir traces/zmr-ios --ensure-device
         \\zmr report traces/zmr-ios --out traces/zmr-ios/report.html --junit traces/zmr-ios/junit.xml
         \\export ZMR_BIN="${ZMR_BIN:-zmr}"; zmr-benchmark --zmr .zmr/ios-smoke.json --platform ios --device booted --app-id
     );
@@ -399,7 +401,7 @@ fn writeAgentInstructions(path: []const u8, app_id: []const u8, force: bool) !vo
         \\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 run .zmr/android-smoke.json --device emulator-5554 --trace-dir traces/zmr-android
+        \\zmr run .zmr/android-smoke.json --device emulator-5554 --trace-dir traces/zmr-android --ensure-device
         \\zmr report traces/zmr-android --out traces/zmr-android/report.html --junit traces/zmr-android/junit.xml
         \\export ZMR_BIN="${ZMR_BIN:-zmr}"; zmr-benchmark --zmr .zmr/android-smoke.json --device emulator-5554 --app-id
     );
@@ -407,7 +409,7 @@ fn writeAgentInstructions(path: []const u8, app_id: []const u8, force: bool) !vo
     try writeShellArg(writer, app_id);
     try writer.writeAll(
         \\ --runs 20 --trace-root traces/zmr-android-reliability --min-pass-rate 100 --max-failures 0 --max-p95-ms 30000 && "$ZMR_BIN" report traces/zmr-android-reliability --out traces/zmr-android-reliability/report.html --junit traces/zmr-android-reliability/junit.xml
-        \\zmr run .zmr/ios-smoke.json --platform ios --device booted --trace-dir traces/zmr-ios
+        \\zmr run .zmr/ios-smoke.json --platform ios --device booted --trace-dir traces/zmr-ios --ensure-device
         \\zmr report traces/zmr-ios --out traces/zmr-ios/report.html --junit traces/zmr-ios/junit.xml
         \\export ZMR_BIN="${ZMR_BIN:-zmr}"; zmr-benchmark --zmr .zmr/ios-smoke.json --platform ios --device booted --app-id
     );

package/src/scenario.zig

@@ -179,6 +179,7 @@ pub fn parseSlice(allocator: std.mem.Allocator, content: []const u8) !Scenario {
     defer parsed.deinit();
     if (parsed.value != .object) return error.ScenarioMustBeObject;
     const root = parsed.value.object;
+    try rejectUnknownRootFields(root);
 
     const name = try fields.requiredString(allocator, root, "name");
     errdefer allocator.free(name);
@@ -204,6 +205,7 @@ pub fn parseSlice(allocator: std.mem.Allocator, content: []const u8) !Scenario {
 fn parseStep(allocator: std.mem.Allocator, value: std.json.Value) anyerror!Step {
     if (value != .object) return error.StepMustBeObject;
     const object = value.object;
+    try rejectUnknownStepFields(object);
     var parsed = try parseRawStep(allocator, object);
     errdefer parsed.deinit(allocator);
 
@@ -352,6 +354,47 @@ fn parseRawStep(allocator: std.mem.Allocator, object: std.json.ObjectMap) anyerr
     return error.unknownScenarioAction;
 }
 
+fn rejectUnknownRootFields(object: std.json.ObjectMap) !void {
+    var iterator = object.iterator();
+    while (iterator.next()) |entry| {
+        const key = entry.key_ptr.*;
+        if (std.mem.eql(u8, key, "name") or
+            std.mem.eql(u8, key, "appId") or
+            std.mem.eql(u8, key, "steps")) continue;
+        return error.UnknownScenarioField;
+    }
+}
+
+fn rejectUnknownStepFields(object: std.json.ObjectMap) !void {
+    var iterator = object.iterator();
+    while (iterator.next()) |entry| {
+        if (!isKnownStepField(entry.key_ptr.*)) return error.UnknownScenarioStepField;
+    }
+}
+
+fn isKnownStepField(key: []const u8) bool {
+    return std.mem.eql(u8, key, "action") or
+        std.mem.eql(u8, key, "optional") or
+        std.mem.eql(u8, key, "url") or
+        std.mem.eql(u8, key, "latitude") or
+        std.mem.eql(u8, key, "longitude") or
+        std.mem.eql(u8, key, "selector") or
+        std.mem.eql(u8, key, "selectors") or
+        std.mem.eql(u8, key, "text") or
+        std.mem.eql(u8, key, "maxChars") or
+        std.mem.eql(u8, key, "x1") or
+        std.mem.eql(u8, key, "y1") or
+        std.mem.eql(u8, key, "x2") or
+        std.mem.eql(u8, key, "y2") or
+        std.mem.eql(u8, key, "durationMs") or
+        std.mem.eql(u8, key, "timeoutMs") or
+        std.mem.eql(u8, key, "direction") or
+        std.mem.eql(u8, key, "times") or
+        std.mem.eql(u8, key, "steps") or
+        std.mem.eql(u8, key, "step") or
+        std.mem.eql(u8, key, "ms");
+}
+
 fn parseLatitude(object: std.json.ObjectMap) !f64 {
     const latitude = try fields.requiredF64OrError(object, "latitude", error.StepMissingLatitude, error.StepLatitudeMustBeNumber);
     if (latitude < -90.0 or latitude > 90.0) return error.StepLatitudeOutOfRange;

package/src/selector.zig

@@ -3,6 +3,7 @@ const types = @import("types.zig");
 
 pub const Selector = struct {
     id: ?[]const u8 = null,
+    stable_id: ?[]const u8 = null,
     text: ?[]const u8 = null,
     text_contains: ?[]const u8 = null,
     content_desc: ?[]const u8 = null,
@@ -11,6 +12,7 @@ pub const Selector = struct {
 
     pub fn deinit(self: Selector, allocator: std.mem.Allocator) void {
         if (self.id) |value| allocator.free(value);
+        if (self.stable_id) |value| allocator.free(value);
         if (self.text) |value| allocator.free(value);
         if (self.text_contains) |value| allocator.free(value);
         if (self.content_desc) |value| allocator.free(value);
@@ -21,6 +23,7 @@ pub const Selector = struct {
     pub fn clone(self: Selector, allocator: std.mem.Allocator) !Selector {
         return .{
             .id = try types.dupeOptional(allocator, self.id),
+            .stable_id = try types.dupeOptional(allocator, self.stable_id),
             .text = try types.dupeOptional(allocator, self.text),
             .text_contains = try types.dupeOptional(allocator, self.text_contains),
             .content_desc = try types.dupeOptional(allocator, self.content_desc),
@@ -28,12 +31,26 @@ pub const Selector = struct {
             .class_name = try types.dupeOptional(allocator, self.class_name),
         };
     }
+
+    pub fn hasAny(self: Selector) bool {
+        return self.id != null or
+            self.stable_id != null or
+            self.text != null or
+            self.text_contains != null or
+            self.content_desc != null or
+            self.content_desc_contains != null or
+            self.class_name != null;
+    }
 };
 
 pub fn matches(node: types.UiNode, wanted: Selector) bool {
+    if (!wanted.hasAny()) return false;
     if (wanted.id) |id| {
         if (node.resource_id == null or !std.mem.eql(u8, node.resource_id.?, id)) return false;
     }
+    if (wanted.stable_id) |stable_id| {
+        if (!std.mem.eql(u8, node.stable_id, stable_id)) return false;
+    }
     if (wanted.text) |text| {
         if (node.text == null or !std.mem.eql(u8, node.text.?, text)) return false;
     }
@@ -62,15 +79,42 @@ pub fn find(nodes: []const types.UiNode, wanted: Selector) ?types.UiNode {
 pub fn parseFromJson(allocator: std.mem.Allocator, value: std.json.Value) !Selector {
     if (value != .object) return error.SelectorMustBeObject;
     const object = value.object;
-    const id = try stringField(allocator, object, "id") orelse try stringField(allocator, object, "resourceId");
-    return .{
-        .id = id,
-        .text = try stringField(allocator, object, "text"),
-        .text_contains = try stringField(allocator, object, "textContains"),
-        .content_desc = try stringField(allocator, object, "contentDesc"),
-        .content_desc_contains = try stringField(allocator, object, "contentDescContains"),
-        .class_name = try stringField(allocator, object, "className"),
-    };
+    try rejectUnknownFields(object);
+    var parsed: Selector = .{};
+    errdefer parsed.deinit(allocator);
+    parsed.id = try stringField(allocator, object, "id");
+    const resource_id = try stringField(allocator, object, "resourceId");
+    if (parsed.id == null) {
+        parsed.id = resource_id;
+    } else if (resource_id) |resource_id_value| {
+        allocator.free(resource_id_value);
+    }
+    parsed.stable_id = try stringField(allocator, object, "stableId");
+    parsed.text = try stringField(allocator, object, "text");
+    parsed.text_contains = try stringField(allocator, object, "textContains");
+    parsed.content_desc = try stringField(allocator, object, "contentDesc");
+    parsed.content_desc_contains = try stringField(allocator, object, "contentDescContains");
+    parsed.class_name = try stringField(allocator, object, "className");
+    if (!parsed.hasAny()) return error.SelectorMustNotBeEmpty;
+    return parsed;
+}
+
+fn rejectUnknownFields(object: std.json.ObjectMap) !void {
+    var iterator = object.iterator();
+    while (iterator.next()) |entry| {
+        if (!isKnownField(entry.key_ptr.*)) return error.UnknownSelectorField;
+    }
+}
+
+fn isKnownField(key: []const u8) bool {
+    return std.mem.eql(u8, key, "id") or
+        std.mem.eql(u8, key, "resourceId") or
+        std.mem.eql(u8, key, "stableId") or
+        std.mem.eql(u8, key, "text") or
+        std.mem.eql(u8, key, "textContains") or
+        std.mem.eql(u8, key, "contentDesc") or
+        std.mem.eql(u8, key, "contentDescContains") or
+        std.mem.eql(u8, key, "className");
 }
 
 fn stringField(

package/src/trace_json.zig

@@ -109,6 +109,10 @@ pub fn writeSelectorJson(writer: anytype, wanted: selector.Selector) !void {
         try jsonField(writer, "id", value, first);
         first = false;
     }
+    if (wanted.stable_id) |value| {
+        try jsonField(writer, "stableId", value, first);
+        first = false;
+    }
     if (wanted.text) |value| {
         try jsonField(writer, "text", value, first);
         first = false;

package/src/validation.zig

@@ -87,9 +87,13 @@ fn diagnoseFailure(allocator: std.mem.Allocator, content: []const u8, err: anyer
     if (syntaxLocation(allocator, content)) |location| return location;
     return switch (err) {
         error.ScenarioMustBeObject => try pathDiagnostic(allocator, content, "$", null),
+        error.UnknownScenarioField,
+        => try pathDiagnostic(allocator, content, "$", null),
         error.ScenarioMissingSteps,
         error.ScenarioStepsMustBeArray,
         => try pathDiagnostic(allocator, content, "$.steps", "steps"),
+        error.UnknownScenarioStepField,
+        => try pathDiagnostic(allocator, content, "$.steps[]", null),
         error.StepMissingAction,
         error.StepActionMustBeString,
         error.unknownAction,
@@ -120,6 +124,7 @@ fn diagnoseFailure(allocator: std.mem.Allocator, content: []const u8, err: anyer
         error.MissingSelector,
         error.StepMissingSelector,
         error.SelectorMustNotBeEmpty,
+        error.UnknownSelectorField,
         => try pathDiagnostic(allocator, content, "$.steps[].selector", "selector"),
         error.MissingSelectors,
         error.StepMissingSelectors,

package/src/version.zig

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