@swmansion/argent 0.32.1-next.1 → 0.32.1-next.11

package/dist/cli-cmds.mjs

@@ -8917,7 +8917,7 @@ var require_src = __commonJS({
 
 // ../argent-cli/src/run.ts
 import * as fs12 from "node:fs";
-import * as path17 from "node:path";
+import * as path18 from "node:path";
 
 // ../argent-tools-client/src/launcher.ts
 import * as net from "node:net";
@@ -10452,6 +10452,8 @@ var FAILURE_CODES = {
   CLI_RUN_ARGS_JSON_INVALID: "CLI_RUN_ARGS_JSON_INVALID",
   CLI_RUN_INPUT_VALIDATION_FAILED: "CLI_RUN_INPUT_VALIDATION_FAILED",
   CLI_RUN_TOOL_CALL_FAILED: "CLI_RUN_TOOL_CALL_FAILED",
+  // The result carried the tool-server's `failure` field.
+  CLI_RUN_TOOL_RESULT_FAILED: "CLI_RUN_TOOL_RESULT_FAILED",
   CLI_RUN_SAVE_IMAGE_FAILED: "CLI_RUN_SAVE_IMAGE_FAILED",
   TOOL_CAPABILITY_UNSUPPORTED_OPERATION: "TOOL_CAPABILITY_UNSUPPORTED_OPERATION",
   TOOL_PLATFORM_NOT_IMPLEMENTED: "TOOL_PLATFORM_NOT_IMPLEMENTED",
@@ -10550,15 +10552,21 @@ var FAILURE_CODES = {
   ANDROID_LAUNCH_AM_START_FAILED: "ANDROID_LAUNCH_AM_START_FAILED",
   ANDROID_OPEN_URL_FAILED: "ANDROID_OPEN_URL_FAILED",
   ANDROID_REINSTALL_INSTALL_FAILED: "ANDROID_REINSTALL_INSTALL_FAILED",
+  ANDROID_REINSTALL_UNINSTALL_FAILED: "ANDROID_REINSTALL_UNINSTALL_FAILED",
   ANDROID_RESTART_FAILED: "ANDROID_RESTART_FAILED",
   ANDROID_SETTINGS_PERMISSION_FAILED: "ANDROID_SETTINGS_PERMISSION_FAILED",
   IOS_LAUNCH_SIMCTL_FAILED: "IOS_LAUNCH_SIMCTL_FAILED",
   IOS_OPEN_URL_FAILED: "IOS_OPEN_URL_FAILED",
   IOS_REINSTALL_INSTALL_FAILED: "IOS_REINSTALL_INSTALL_FAILED",
+  IOS_REINSTALL_UNINSTALL_FAILED: "IOS_REINSTALL_UNINSTALL_FAILED",
   IOS_RESTART_LAUNCH_FAILED: "IOS_RESTART_LAUNCH_FAILED",
+  IOS_RESTART_TERMINATE_FAILED: "IOS_RESTART_TERMINATE_FAILED",
+  IOS_TERMINATE_APP_FAILED: "IOS_TERMINATE_APP_FAILED",
   IOS_SETTINGS_PERMISSION_FAILED: "IOS_SETTINGS_PERMISSION_FAILED",
   IOS_SHAKE_FAILED: "IOS_SHAKE_FAILED",
   ANDROID_SHAKE_FAILED: "ANDROID_SHAKE_FAILED",
+  STOP_METRO_PORT_PROBE_FAILED: "STOP_METRO_PORT_PROBE_FAILED",
+  STOP_METRO_SIGNAL_FAILED: "STOP_METRO_SIGNAL_FAILED",
   // The hinge of a foldable iOS simulator: the server refused the request on a
   // foldable (a bad angle, a hinge that would not move) vs. nothing to fold —
   // a device that is not foldable, no hinge route, a remote simulator.
@@ -10704,10 +10712,13 @@ var FAILURE_CODES = {
   FLOW_NAME_INVALID: "FLOW_NAME_INVALID",
   FLOW_NO_ACTIVE_RECORDING: "FLOW_NO_ACTIVE_RECORDING",
   FLOW_FILE_INVALID: "FLOW_FILE_INVALID",
+  FLOW_FILE_NEWER_VERSION: "FLOW_FILE_NEWER_VERSION",
   FLOW_FILE_WRITE_FAILED: "FLOW_FILE_WRITE_FAILED",
   FLOW_ENTRY_UNRECOGNIZED: "FLOW_ENTRY_UNRECOGNIZED",
   FLOW_E2E_HAS_PREREQUISITE: "FLOW_E2E_HAS_PREREQUISITE",
   FLOW_DEVICE_RESOLUTION: "FLOW_DEVICE_RESOLUTION",
+  // The target does not satisfy the test's `requires:` block; a directory run skips it.
+  FLOW_REQUIREMENTS_UNMET: "FLOW_REQUIREMENTS_UNMET",
   PROFILER_QUERY_MODE_INVALID: "PROFILER_QUERY_MODE_INVALID",
   PROFILER_QUERY_REQUIRED_PARAM_MISSING: "PROFILER_QUERY_REQUIRED_PARAM_MISSING",
   PROFILER_DATA_NOT_LOADED: "PROFILER_DATA_NOT_LOADED",
@@ -10726,6 +10737,7 @@ var FAILURE_CODES = {
   CHROMIUM_STORAGE_EVAL_FAILED: "CHROMIUM_STORAGE_EVAL_FAILED",
   CHROMIUM_TAB_NOT_FOUND: "CHROMIUM_TAB_NOT_FOUND",
   CHROMIUM_TAB_OPEN_FAILED: "CHROMIUM_TAB_OPEN_FAILED",
+  CHROMIUM_NAVIGATE_FAILED: "CHROMIUM_NAVIGATE_FAILED",
   CHROMIUM_DESCRIBE_FAILED: "CHROMIUM_DESCRIBE_FAILED",
   CHROMIUM_ELECTRON_APP_PATH_INVALID: "CHROMIUM_ELECTRON_APP_PATH_INVALID",
   CHROMIUM_ELECTRON_SPAWN_FAILED: "CHROMIUM_ELECTRON_SPAWN_FAILED",
@@ -10742,6 +10754,8 @@ var FAILURE_CODES = {
   SCREENSHOT_DIFF_INPUT_INVALID: "SCREENSHOT_DIFF_INPUT_INVALID",
   BOOT_DEVICE_TARGET_SELECTION_INVALID: "BOOT_DEVICE_TARGET_SELECTION_INVALID",
   BOOT_IOS_UNSUPPORTED_HOST: "BOOT_IOS_UNSUPPORTED_HOST",
+  BOOT_IOS_SIMCTL_LIST_TIMEOUT: "BOOT_IOS_SIMCTL_LIST_TIMEOUT",
+  BOOT_IOS_SIMCTL_TIMEOUT: "BOOT_IOS_SIMCTL_TIMEOUT",
   BOOT_ANDROID_NO_AVDS: "BOOT_ANDROID_NO_AVDS",
   BOOT_ANDROID_AVD_NOT_FOUND: "BOOT_ANDROID_AVD_NOT_FOUND",
   BOOT_ANDROID_ADB_UNAVAILABLE: "BOOT_ANDROID_ADB_UNAVAILABLE",
@@ -31639,7 +31653,8 @@ async function consumeToolStream(name, body, onProgress, signal) {
       final = {
         data: msg.data,
         note: msg.note,
-        ...msg.profiling === true ? { profiling: true } : {}
+        ...msg.profiling === true ? { profiling: true } : {},
+        ...typeof msg.failure === "string" ? { failure: msg.failure } : {}
       };
     } else if (msg.event === "error") {
       throw new ToolInvocationError(msg.error ?? "tool invocation failed", {
@@ -31691,7 +31706,8 @@ async function consumeToolStream(name, body, onProgress, signal) {
   return {
     data: final.data,
     note: final.note,
-    ...final.profiling ? { profiling: true } : {}
+    ...final.profiling ? { profiling: true } : {},
+    ...final.failure !== void 0 ? { failure: final.failure } : {}
   };
 }
 function errorBodyMessage(body) {
@@ -31856,6 +31872,7 @@ function createToolsClient(options = {}) {
     }
     const shadowWarning = await e2eShadowWarningFor(name, args);
     const baselineDirs = [];
+    let unwrittenBaselines2 = [];
     if (meta3?.fileInputs?.length) {
       if (remote) assertRequiredPresent(meta3, finalArgs);
       finalArgs = await prepareFileInputs(meta3.fileInputs, finalArgs ?? {}, {
@@ -31869,8 +31886,9 @@ function createToolsClient(options = {}) {
         signal: opts?.signal
       });
     }
-    const settle2 = async (data) => {
-      const applied = await applyClientFileDirectives(data, { allowedDirs: baselineDirs });
+    const settle2 = async (data2) => {
+      const applied = await applyClientFileDirectives(data2, { allowedDirs: baselineDirs });
+      unwrittenBaselines2 = applied.failed.map((f) => f.path);
       for (const { path: file2, error: error63 } of applied.failed) {
         diagnose(`The baseline ${file2} was not written on this client: ${error63}`);
       }
@@ -31887,6 +31905,7 @@ function createToolsClient(options = {}) {
       }
       return { ...result, warning: shadowWarning };
     };
+    const unwrittenFailure = () => unwrittenBaselines2.length > 0 ? `Baselines not written on this client: ${unwrittenBaselines2.join(", ")}` : void 0;
     const stream = opts?.onProgress !== void 0 || carriesMembers(finalArgs);
     const sentOnce = carriesUpload(finalArgs);
     const forwarded = remote ? await forwardedSecrets(finalArgs) : void 0;
@@ -31950,11 +31969,14 @@ function createToolsClient(options = {}) {
         }),
         opts?.signal
       );
+      const data2 = await settle2(streamed.data);
+      const failure3 = streamed.failure ?? unwrittenFailure();
       return {
-        data: await settle2(streamed.data),
+        data: data2,
         note: streamed.note,
         outputHint: meta3?.outputHint,
-        ...streamed.profiling ? { profiling: true } : {}
+        ...streamed.profiling ? { profiling: true } : {},
+        ...failure3 !== void 0 ? { failure: failure3 } : {}
       };
     }
     let json2;
@@ -31990,11 +32012,14 @@ function createToolsClient(options = {}) {
       });
     }
     opts?.signal?.throwIfAborted();
+    const data = await settle2(json2.data);
+    const failure2 = (typeof json2.failure === "string" ? json2.failure : void 0) ?? unwrittenFailure();
     return {
-      data: await settle2(json2.data),
+      data,
       note: json2.note,
       outputHint: meta3?.outputHint,
-      ...json2.profiling === true ? { profiling: true } : {}
+      ...json2.profiling === true ? { profiling: true } : {},
+      ...failure2 !== void 0 ? { failure: failure2 } : {}
     };
   }
   return { fetchTools, fetchTool, callTool, baseUrl };
@@ -35809,7 +35834,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID2 = randomUUID5();
 function readCliVersion() {
   if (true) {
-    return "0.32.1-next.0";
+    return "0.32.1-next.10";
   }
   return "0.0.0";
 }
@@ -36748,391 +36773,106 @@ function isValidationIssue(value) {
   return typeof issue2.code === "string" && Array.isArray(issue2.path) && typeof issue2.message === "string";
 }
 
-// ../argent-cli/src/run.ts
-function splitOptions(argv) {
-  let json2 = false;
-  let outPath = null;
-  const rest = [];
+// ../argent-cli/src/e2e.ts
+import * as fsp from "node:fs/promises";
+import { constants as fsConstants2 } from "node:fs";
+import { createHash as createHash5 } from "node:crypto";
+import * as path17 from "node:path";
+
+// ../argent-cli/src/command-args.ts
+var UsageError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UsageError";
+  }
+};
+function listChoices(choices) {
+  const quoted = choices.map((c2) => `"${c2}"`);
+  if (quoted.length <= 1) return quoted.join("");
+  return `${quoted.slice(0, -1).join(", ")} or ${quoted[quoted.length - 1]}`;
+}
+function resolveName(tok, specs) {
+  if (tok.startsWith("--")) return tok.slice(2) in specs ? tok.slice(2) : null;
+  const short = tok.slice(1);
+  for (const [name, spec] of Object.entries(specs)) {
+    if (spec.alias === short) return name;
+  }
+  return null;
+}
+function parseCommandArgs(argv, specs) {
+  const positionals = [];
+  const options = {};
   for (let i2 = 0; i2 < argv.length; i2++) {
     const tok = argv[i2];
-    if (tok === "--json") {
-      json2 = true;
-      continue;
+    if (tok === "--") {
+      positionals.push(...argv.slice(i2 + 1));
+      break;
     }
-    if (tok === "--out") {
-      const v = argv[i2 + 1];
-      if (!v) throw new FlagParseException("--out requires a path");
-      outPath = v;
-      i2 += 1;
+    if (!tok.startsWith("-") || tok === "-") {
+      positionals.push(tok);
       continue;
     }
-    if (tok.startsWith("--out=")) {
-      outPath = tok.slice("--out=".length);
+    const eq = tok.startsWith("--") ? tok.indexOf("=") : -1;
+    const flag = eq === -1 ? tok : tok.slice(0, eq);
+    const inlineValue = eq === -1 ? void 0 : tok.slice(eq + 1);
+    const name = resolveName(flag, specs);
+    if (name === null) throw new UsageError(`Unknown flag: ${tok}`);
+    const spec = specs[name];
+    const display = `--${name}`;
+    if (spec.kind === "boolean") {
+      if (inlineValue !== void 0) throw new UsageError(`${display} does not take a value`);
+      const next = argv[i2 + 1]?.trim().toLowerCase();
+      if (next === "true" || next === "false") {
+        throw new UsageError(
+          `${display} does not take a value \u2014 it is a switch; omit it to leave the option off`
+        );
+      }
+      options[name] = true;
       continue;
     }
-    rest.push(tok);
-  }
-  return { json: json2, outPath, argvForFlags: rest };
-}
-async function readStdin() {
-  return new Promise((resolve13, reject) => {
-    let data = "";
-    process.stdin.setEncoding("utf8");
-    process.stdin.on("data", (chunk) => {
-      data += chunk;
-    });
-    process.stdin.on("end", () => resolve13(data));
-    process.stdin.on("error", reject);
-  });
-}
-function printToolHelp(meta3) {
-  const description = meta3.description?.trim() ?? "";
-  const schema = meta3.inputSchema;
-  const hasOwnArgsField = schema?.properties?.args !== void 0;
-  console.log(`argent run ${meta3.name} [flags]`);
-  if (description) console.log(`
-${description}
-`);
-  console.log("Flags:");
-  console.log(formatSchemaUsage(schema));
-  console.log("\nGlobal flags:");
-  if (!hasOwnArgsField) {
-    console.log("  --args <json>          Pass the entire payload as JSON (overrides flags)");
-    console.log("  --args -               Read the entire payload as JSON from stdin");
-  }
-  console.log("  --<field>-json <json>  Pass a single field as JSON (objects/nested arrays)");
-  console.log("  --json                 Print the raw JSON result");
-  console.log("  --out <path>           For image results, save to <path> instead of fetching URL");
-  console.log("  --help, -h             Show this help");
-}
-async function fetchImageToFile(result, outPath) {
-  const url2 = result.url;
-  if (!url2) {
-    throw new Error("Tool result did not include a `url`; cannot save image");
-  }
-  const res = await fetch(url2);
-  if (!res.ok) throw new Error(`Failed to download image: ${res.status} ${res.statusText}`);
-  const buf = Buffer.from(await res.arrayBuffer());
-  fs12.mkdirSync(path17.dirname(path17.resolve(outPath)), { recursive: true });
-  fs12.writeFileSync(outPath, buf);
-}
-function renderResult(result, outputHint, images, json2) {
-  if (json2) return JSON.stringify(result, null, 2);
-  if (outputHint === "image") {
-    if (images.length > 0) return `Saved screenshot: ${images[0].localPath}`;
-    if (result && typeof result === "object" && "path" in result && typeof result.path === "string") {
-      return `Saved screenshot: ${result.path}`;
+    let value = inlineValue;
+    if (value === void 0) {
+      const next = argv[i2 + 1];
+      if (next !== void 0 && (!next.startsWith("-") || next === "-")) {
+        value = next;
+        i2 += 1;
+      }
+    } else if (value === "") {
+      value = void 0;
+    }
+    if (value === void 0) throw new UsageError(`${display} requires a value`);
+    if (spec.choices && !spec.choices.includes(value)) {
+      throw new UsageError(`${display} must be ${listChoices(spec.choices)}, got "${value}"`);
     }
+    options[name] = value;
   }
-  if (typeof result === "string") return result;
-  return JSON.stringify(result, null, 2);
+  return { positionals, options };
 }
-var SAFE_TOOL_RE = /^[a-z][a-z0-9_-]{0,63}$/;
-function safeToolName(toolName) {
-  return toolName && SAFE_TOOL_RE.test(toolName) ? toolName : "unknown";
+
+// ../argent-cli/src/e2e.ts
+var STATUS_GLYPH = {
+  pass: "\u2713",
+  fail: "\u2717",
+  error: "\u2717",
+  skip: "\xB7"
+};
+var MAX_RENDER_DEPTH = 20;
+function stepIndent(depth) {
+  if (typeof depth !== "number" || !Number.isInteger(depth) || depth <= 0) return "";
+  return "  ".repeat(Math.min(depth, MAX_RENDER_DEPTH));
 }
-async function trackRunFailure(toolName, startedAt, signal) {
-  const tool = toolName ? canonicalToolId(toolName) : toolName;
-  track("cli:run_fail", {
-    tool: safeToolName(tool),
-    ...tool !== toolName ? { alias_used: true } : {},
-    duration_ms: performance.now() - startedAt,
-    ...signal
-  });
-  await shutdown();
+function durationSuffix(ms) {
+  if (typeof ms !== "number" || !Number.isFinite(ms) || ms < 0) return "";
+  const tenths = Math.round(ms / 100);
+  if (tenths < 600) return ` (${(tenths / 10).toFixed(1)}s)`;
+  const seconds = Math.round(ms / 1e3);
+  return ` (${Math.floor(seconds / 60)}m ${seconds % 60}s)`;
 }
-async function run(argv, options) {
-  init("cli");
-  const startedAt = performance.now();
-  const { fetchTool, callTool, baseUrl } = createToolsClient({ paths: options.paths });
-  const [toolName, ...rest] = argv;
-  if (!toolName || toolName === "--help" || toolName === "-h") {
-    console.log(`Usage: argent run <tool> [flags]
+function printHelp(toStderr = false) {
+  const print = toStderr ? console.error : console.log;
+  print(`Usage: argent e2e <subcommand> [options]
 
-Invoke a tool exposed by the argent tool-server. Run \`argent tools\` to list
-available tools, or \`argent tools describe <name>\` to see one tool's flags.
-
-Examples:
-  argent run list-devices
-  argent run gesture-tap --udid <UDID> --x 0.5 --y 0.5
-  argent run screenshot --udid <UDID> --out ./screen.png
-  argent run run-sequence --udid <UDID> --steps-json '[{"tool":"button","args":{"button":"home"}}]'
-  argent run gesture-tap --args '{"udid":"<UDID>","x":0.5,"y":0.5}'
-`);
-    return;
-  }
-  let cliOptions;
-  try {
-    cliOptions = splitOptions(rest);
-  } catch (err) {
-    if (err instanceof FlagParseException) {
-      console.error(`Error: ${err.message}
-`);
-      console.error(`Run \`argent run ${toolName} --help\` to see this tool's flags.`);
-      await trackRunFailure(toolName, startedAt, {
-        error_code: FAILURE_CODES.CLI_RUN_FLAG_PARSE_FAILED,
-        failure_stage: "cli_run_split_options",
-        failure_area: "cli",
-        error_kind: "validation"
-      });
-      process.exit(2);
-    }
-    throw err;
-  }
-  const { json: json2, outPath, argvForFlags } = cliOptions;
-  const meta3 = await fetchTool(toolName);
-  if (!meta3) {
-    console.error(`Tool "${toolName}" not found. Run \`argent tools\` to list available tools.`);
-    await trackRunFailure(toolName, startedAt, {
-      error_code: FAILURE_CODES.CLI_RUN_TOOL_NOT_FOUND,
-      failure_stage: "cli_run_fetch_tool",
-      failure_area: "cli",
-      error_kind: "not_found"
-    });
-    process.exit(1);
-  }
-  const schema = meta3.inputSchema;
-  const failInvocation = async (summary, report, failure2) => {
-    if (json2) {
-      console.error(
-        JSON.stringify(
-          {
-            error: summary,
-            missing: report ? missingFlagNames(report, schema) : [],
-            issues: report?.rawIssues ?? []
-          },
-          null,
-          2
-        )
-      );
-    } else {
-      console.error(`Error: ${summary}
-`);
-      printToolHelp(meta3);
-    }
-    await trackRunFailure(toolName, startedAt, {
-      ...failure2,
-      failure_area: "cli",
-      error_kind: "validation"
-    });
-    process.exit(2);
-  };
-  const failValidation = (report, stage) => failInvocation(formatValidationError(report, schema), report, {
-    error_code: FAILURE_CODES.CLI_RUN_INPUT_VALIDATION_FAILED,
-    failure_stage: stage
-  });
-  let parsed;
-  try {
-    parsed = parseFlags(argvForFlags, schema);
-  } catch (err) {
-    if (err instanceof FlagParseException) {
-      await failInvocation(err.message, null, {
-        error_code: FAILURE_CODES.CLI_RUN_FLAG_PARSE_FAILED,
-        failure_stage: "cli_run_parse_flags"
-      });
-    }
-    throw err;
-  }
-  if (parsed.helpRequested) {
-    printToolHelp(meta3);
-    return;
-  }
-  if (parsed.positional.length > 0) {
-    console.error(
-      `Note: ignoring unused argument(s): ${parsed.positional.join(", ")}. Pass values as --flag <value> or --flag=<value>.`
-    );
-  }
-  let payload = {};
-  if (parsed.rawArgs !== null) {
-    let rawJson = parsed.rawArgs;
-    if (rawJson === "-") {
-      rawJson = await readStdin();
-    }
-    try {
-      const parsedRaw = JSON.parse(rawJson);
-      if (parsedRaw === null || typeof parsedRaw !== "object" || Array.isArray(parsedRaw)) {
-        console.error("--args must be a JSON object");
-        await trackRunFailure(toolName, startedAt, {
-          error_code: FAILURE_CODES.CLI_RUN_ARGS_NOT_OBJECT,
-          failure_stage: "cli_run_parse_raw_args",
-          failure_area: "cli",
-          error_kind: "validation"
-        });
-        process.exit(2);
-      }
-      payload = parsedRaw;
-    } catch (err) {
-      console.error(`--args is not valid JSON: ${err instanceof Error ? err.message : err}`);
-      await trackRunFailure(toolName, startedAt, {
-        error_code: FAILURE_CODES.CLI_RUN_ARGS_JSON_INVALID,
-        failure_stage: "cli_run_parse_raw_args",
-        failure_area: "cli",
-        error_kind: "validation"
-      });
-      process.exit(2);
-    }
-  }
-  for (const [k, v] of Object.entries(parsed.args)) {
-    payload[k] = v;
-  }
-  const missing = findMissingRequired(payload, schema);
-  if (missing.length > 0) {
-    await failValidation({ missing, invalid: [], rawIssues: null }, "cli_run_required_flags");
-  }
-  let result;
-  let note;
-  let images = [];
-  try {
-    const resp = await callTool(toolName, payload);
-    const { url: url2, token } = await baseUrl();
-    const materialized = await materializeArtifacts(resp.data, {
-      toolsUrl: url2,
-      authToken: token,
-      deviceId: getDeviceIdFromArgs(payload)
-    });
-    result = materialized.result;
-    images = materialized.images;
-    note = resp.note;
-  } catch (err) {
-    const report = describeServerValidationFailure(err, payload, schema);
-    if (report) {
-      await failValidation(report, "cli_run_server_validation");
-    }
-    console.error(err instanceof Error ? err.message : String(err));
-    await trackRunFailure(toolName, startedAt, {
-      error_code: FAILURE_CODES.CLI_RUN_TOOL_CALL_FAILED,
-      failure_stage: "cli_run_call_tool",
-      failure_area: "cli",
-      error_kind: "unknown"
-    });
-    process.exit(1);
-  }
-  if (outPath && meta3.outputHint === "image") {
-    try {
-      if (images.length > 0) {
-        fs12.mkdirSync(path17.dirname(path17.resolve(outPath)), { recursive: true });
-        fs12.writeFileSync(outPath, images[0].data);
-      } else if (result && typeof result === "object") {
-        await fetchImageToFile(result, outPath);
-      }
-    } catch (err) {
-      console.error(`Failed to save image: ${err instanceof Error ? err.message : err}`);
-      await trackRunFailure(toolName, startedAt, {
-        error_code: FAILURE_CODES.CLI_RUN_SAVE_IMAGE_FAILED,
-        failure_stage: "cli_run_save_image",
-        failure_area: "cli",
-        error_kind: "unknown"
-      });
-      process.exit(1);
-    }
-  }
-  if (note) console.error(note);
-  console.log(renderResult(result, meta3.outputHint, images, json2));
-  if (outPath && meta3.outputHint === "image" && !json2) {
-    console.log(`Wrote: ${outPath}`);
-  }
-}
-
-// ../argent-cli/src/e2e.ts
-import * as fsp from "node:fs/promises";
-import { constants as fsConstants2 } from "node:fs";
-import { createHash as createHash5 } from "node:crypto";
-import * as path18 from "node:path";
-
-// ../argent-cli/src/command-args.ts
-var UsageError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "UsageError";
-  }
-};
-function listChoices(choices) {
-  const quoted = choices.map((c2) => `"${c2}"`);
-  if (quoted.length <= 1) return quoted.join("");
-  return `${quoted.slice(0, -1).join(", ")} or ${quoted[quoted.length - 1]}`;
-}
-function resolveName(tok, specs) {
-  if (tok.startsWith("--")) return tok.slice(2) in specs ? tok.slice(2) : null;
-  const short = tok.slice(1);
-  for (const [name, spec] of Object.entries(specs)) {
-    if (spec.alias === short) return name;
-  }
-  return null;
-}
-function parseCommandArgs(argv, specs) {
-  const positionals = [];
-  const options = {};
-  for (let i2 = 0; i2 < argv.length; i2++) {
-    const tok = argv[i2];
-    if (tok === "--") {
-      positionals.push(...argv.slice(i2 + 1));
-      break;
-    }
-    if (!tok.startsWith("-") || tok === "-") {
-      positionals.push(tok);
-      continue;
-    }
-    const eq = tok.startsWith("--") ? tok.indexOf("=") : -1;
-    const flag = eq === -1 ? tok : tok.slice(0, eq);
-    const inlineValue = eq === -1 ? void 0 : tok.slice(eq + 1);
-    const name = resolveName(flag, specs);
-    if (name === null) throw new UsageError(`Unknown flag: ${tok}`);
-    const spec = specs[name];
-    const display = `--${name}`;
-    if (spec.kind === "boolean") {
-      if (inlineValue !== void 0) throw new UsageError(`${display} does not take a value`);
-      const next = argv[i2 + 1]?.trim().toLowerCase();
-      if (next === "true" || next === "false") {
-        throw new UsageError(
-          `${display} does not take a value \u2014 it is a switch; omit it to leave the option off`
-        );
-      }
-      options[name] = true;
-      continue;
-    }
-    let value = inlineValue;
-    if (value === void 0) {
-      const next = argv[i2 + 1];
-      if (next !== void 0 && (!next.startsWith("-") || next === "-")) {
-        value = next;
-        i2 += 1;
-      }
-    } else if (value === "") {
-      value = void 0;
-    }
-    if (value === void 0) throw new UsageError(`${display} requires a value`);
-    if (spec.choices && !spec.choices.includes(value)) {
-      throw new UsageError(`${display} must be ${listChoices(spec.choices)}, got "${value}"`);
-    }
-    options[name] = value;
-  }
-  return { positionals, options };
-}
-
-// ../argent-cli/src/e2e.ts
-var STATUS_GLYPH = {
-  pass: "\u2713",
-  fail: "\u2717",
-  error: "\u2717",
-  skip: "\xB7"
-};
-var MAX_RENDER_DEPTH = 20;
-function stepIndent(depth) {
-  if (typeof depth !== "number" || !Number.isInteger(depth) || depth <= 0) return "";
-  return "  ".repeat(Math.min(depth, MAX_RENDER_DEPTH));
-}
-function durationSuffix(ms) {
-  if (typeof ms !== "number" || !Number.isFinite(ms) || ms < 0) return "";
-  const tenths = Math.round(ms / 100);
-  if (tenths < 600) return ` (${(tenths / 10).toFixed(1)}s)`;
-  const seconds = Math.round(ms / 1e3);
-  return ` (${Math.floor(seconds / 60)}m ${seconds % 60}s)`;
-}
-function printHelp(toStderr = false) {
-  const print = toStderr ? console.error : console.log;
-  print(`Usage: argent e2e <subcommand> [options]
-
-Run a YAML e2e test without an LLM in the loop. \`run\` takes any of these forms:
+Run a YAML e2e test without an LLM in the loop. \`run\` takes any of these forms:
 
   a name   An e2e test saved under .argent/e2e or .argent/flows, resolved
            from the current directory. "checkout" runs
@@ -37150,8 +36890,9 @@ contain only letters, numbers, "_", or "-" \u2014 the same charset a name must
 match. A test is standalone when its first non-\`echo\`/\`script\` step is \`launch\`.
 Other tests are fragments and use the device's current state. Exception: a fragment whose first step \`run:\`s a chromium standalone
 test boots that test's app before step 1 \u2014 when that launch is unambiguously
-chromium (a lone \`{ chromium: ... }\` target, or --platform chromium); a
-multi-platform launch auto-detects a device instead. Pass --device to attach to
+chromium (a lone \`{ chromium: ... }\` target, --platform chromium, or a
+\`requires:\` block that allows only chromium); a multi-platform launch
+auto-detects a device instead. Pass --device to attach to
 a running instance.
 
 A directory run prints only the steps that need attention (each failure, each
@@ -37164,6 +36905,12 @@ file, or a device it cannot resolve. A transport failure, a rejection the server
 does not mark as validation, or a reply that is not a report stops the batch and
 counts the remaining tests skipped.
 
+A test can declare a \`requires:\` block (platform, runtimeKind) that names the
+targets it supports. A directory run skips each test whose requirements the
+target does not meet, so the same directory runs on each platform without a
+separate list of tests. A single-test run fails instead. A directory run where
+no test ran exits 2.
+
 The CLI sends a run to its tool-server: the local one that starts
 automatically, or the one that \`argent link\` or ARGENT_TOOLS_URL names. Over
 a link, the CLI uploads these files and writes the new baselines that the run
@@ -37346,7 +37093,8 @@ function renderFailedSteps(report) {
   return lines;
 }
 function renderBatchSummary(counts, durationMs) {
-  return `${counts.failed === 0 ? "PASS" : "FAIL"} \u2014 ${counts.total} e2e test${counts.total === 1 ? "" : "s"}: ${counts.passed} passed, ${counts.failed} failed, ${counts.skipped} skipped${durationSuffix(durationMs)}`;
+  const verdict = counts.failed > 0 ? "FAIL" : counts.passed === 0 ? "NONE RAN" : "PASS";
+  return `${verdict} \u2014 ${counts.total} e2e test${counts.total === 1 ? "" : "s"}: ${counts.passed} passed, ${counts.failed} failed, ${counts.skipped} skipped${durationSuffix(durationMs)}`;
 }
 function summarizeFailure(report) {
   let n3 = 0;
@@ -37385,14 +37133,14 @@ function shellQuoteArg(arg) {
   return `'${arg.replaceAll("'", "'\\''")}'`;
 }
 function rerunCommand(flowPath, rel, projectRoot, args) {
-  const pathArg = (p) => shellQuoteArg(p.startsWith("-") ? `.${path18.sep}${p}` : p);
-  const fromCwd = path18.relative(projectRoot, flowPath);
-  const shown = path18.isAbsolute(fromCwd) || fromCwd.split(/[\\/]+/).includes("..") ? flowPath : fromCwd;
+  const pathArg = (p) => shellQuoteArg(p.startsWith("-") ? `.${path17.sep}${p}` : p);
+  const fromCwd = path17.relative(projectRoot, flowPath);
+  const shown = path17.isAbsolute(fromCwd) || fromCwd.split(/[\\/]+/).includes("..") ? flowPath : fromCwd;
   const parts = ["argent e2e run", pathArg(shown)];
   if (args.device) parts.push("--device", shellQuoteArg(args.device));
   if (args.platform) parts.push("--platform", shellQuoteArg(args.platform));
   if (args.updateBaselines) parts.push("--update-baselines");
-  if (args.output) parts.push("--output", pathArg(path18.join(args.output, path18.dirname(rel))));
+  if (args.output) parts.push("--output", pathArg(path17.join(args.output, path17.dirname(rel))));
   return parts.join(" ");
 }
 var EXPORT_SOURCE_MARKER = ".argent-e2e-source";
@@ -37400,8 +37148,8 @@ var LEGACY_EXPORT_SOURCE_MARKER = ".argent-flow-source";
 var MARKER_READ_RETRIES = 4;
 var MARKER_READ_DELAY_MS = 5;
 async function readExportMarker(dir) {
-  const owner = await readMarkerFile(path18.join(dir, EXPORT_SOURCE_MARKER));
-  return owner !== void 0 ? owner : await readMarkerFile(path18.join(dir, LEGACY_EXPORT_SOURCE_MARKER));
+  const owner = await readMarkerFile(path17.join(dir, EXPORT_SOURCE_MARKER));
+  return owner !== void 0 ? owner : await readMarkerFile(path17.join(dir, LEGACY_EXPORT_SOURCE_MARKER));
 }
 async function readMarkerFile(marker) {
   for (let attempt = 0; ; attempt++) {
@@ -37438,7 +37186,7 @@ function occupiedBy(owner) {
 async function takeExportDir(dir, flowPath) {
   try {
     await fsp.mkdir(dir, { recursive: true });
-    await fsp.writeFile(path18.join(dir, EXPORT_SOURCE_MARKER), `${flowPath}
+    await fsp.writeFile(path17.join(dir, EXPORT_SOURCE_MARKER), `${flowPath}
 `, { flag: "wx" });
     return null;
   } catch (err) {
@@ -37457,7 +37205,7 @@ async function claimExportDirName(outputDir, flowPath, stem) {
   }
   const avoided = [];
   for (const name of candidates) {
-    const dir = path18.join(outputDir, name);
+    const dir = path17.join(outputDir, name);
     const claim2 = await classifyExportDir(dir, flowPath);
     const reason = claim2.state === "foreign" ? occupiedBy(claim2.owner) : await takeExportDir(dir, flowPath);
     if (reason !== null) {
@@ -37477,7 +37225,7 @@ async function claimExportDirName(outputDir, flowPath, stem) {
   return null;
 }
 async function exportFailureArtifacts(report, outputDir, flowPath, ctx) {
-  const stem = path18.basename(flowPath, ".yaml");
+  const stem = path17.basename(flowPath, ".yaml");
   if (!SAFE_ARTIFACT_NAME.test(stem)) {
     console.error(
       `warning: skipping artifact export for unsafe e2e test filename ${JSON.stringify(stem)}`
@@ -37510,11 +37258,11 @@ async function exportFailureArtifacts(report, outputDir, flowPath, ctx) {
       if (dir === null) {
         const dirName = await claimExportDirName(outputDir, flowPath, stem);
         if (dirName === null) return;
-        dir = path18.join(outputDir, dirName);
+        dir = path17.join(outputDir, dirName);
       }
-      const dest = path18.join(dir, fileName(role));
-      const rel = path18.relative(outputDir, dest);
-      if (rel.startsWith("..") || path18.isAbsolute(rel)) continue;
+      const dest = path17.join(dir, fileName(role));
+      const rel = path17.relative(outputDir, dest);
+      if (rel.startsWith("..") || path17.isAbsolute(rel)) continue;
       try {
         await fsp.copyFile(value, dest);
         s.artifacts[role] = dest;
@@ -37529,7 +37277,7 @@ async function exportFailureArtifacts(report, outputDir, flowPath, ctx) {
 function keyFromBaselinePath(artifacts) {
   const baseline = artifacts.baseline;
   if (typeof baseline !== "string") return null;
-  return path18.basename(baseline).replace(/\.png$/, "");
+  return path17.basename(baseline).replace(/\.png$/, "");
 }
 function resolveArtifactDisplayPaths(report) {
   for (const s of report.steps) {
@@ -37586,17 +37334,17 @@ async function collectRunnableFlowPaths(dir, relDir = "") {
   const found = [];
   const entries = await fsp.readdir(dir, { withFileTypes: true });
   for (const entry of entries) {
-    const rel = relDir ? path18.join(relDir, entry.name) : entry.name;
+    const rel = relDir ? path17.join(relDir, entry.name) : entry.name;
     if (entry.isDirectory()) {
       if (entry.name === "__baselines__") continue;
       found.push(
-        ...await collectRunnableFlowPaths(path18.join(dir, entry.name), rel).catch(() => [])
+        ...await collectRunnableFlowPaths(path17.join(dir, entry.name), rel).catch(() => [])
       );
       continue;
     }
     if (!entry.name.endsWith(".yaml")) continue;
-    if (!SAFE_FLOW_NAME.test(path18.basename(entry.name, ".yaml"))) continue;
-    if (await isRunnableFlowFile(path18.join(dir, entry.name))) found.push(rel);
+    if (!SAFE_FLOW_NAME.test(path17.basename(entry.name, ".yaml"))) continue;
+    if (await isRunnableFlowFile(path17.join(dir, entry.name))) found.push(rel);
   }
   return found;
 }
@@ -37604,26 +37352,26 @@ async function resolveFlowRef(ref, projectRoot) {
   if (!SAFE_FLOW_NAME.test(ref)) return { suppliedPath: ref, fromName: false };
   const picked = await resolveE2eFile(projectRoot, ref);
   return {
-    suppliedPath: path18.relative(projectRoot, picked.path),
+    suppliedPath: path17.relative(projectRoot, picked.path),
     fromName: true,
-    ...picked.shadowed === void 0 ? {} : { shadowed: path18.relative(projectRoot, picked.shadowed) }
+    ...picked.shadowed === void 0 ? {} : { shadowed: path17.relative(projectRoot, picked.shadowed) }
   };
 }
 async function savedFlowHint(projectRoot, missingPath) {
-  const dirs = E2E_DIRS.map((rel) => ({ rel, abs: path18.resolve(projectRoot, rel) }));
+  const dirs = E2E_DIRS.map((rel) => ({ rel, abs: path17.resolve(projectRoot, rel) }));
   for (const { abs } of dirs) {
-    const within = path18.relative(abs, missingPath);
-    if (!within.startsWith("..") && !path18.isAbsolute(within)) return "";
+    const within = path17.relative(abs, missingPath);
+    if (!within.startsWith("..") && !path17.isAbsolute(within)) return "";
   }
-  const wanted = `${path18.basename(missingPath, ".yaml")}.yaml`;
+  const wanted = `${path17.basename(missingPath, ".yaml")}.yaml`;
   for (const { rel, abs } of dirs) {
     const entries = await fsp.readdir(abs).catch(() => null);
     if (entries === null) continue;
     const actual = entries.includes(wanted) ? wanted : entries.find((name2) => name2.toLowerCase() === wanted.toLowerCase());
     if (actual === void 0) continue;
-    const name = path18.basename(actual, ".yaml");
+    const name = path17.basename(actual, ".yaml");
     if (!SAFE_FLOW_NAME.test(name)) return "";
-    if (!await isRunnableFlowFile(path18.join(abs, actual))) return "";
+    if (!await isRunnableFlowFile(path17.join(abs, actual))) return "";
     return `
 An e2e test named "${name}" is saved under ${rel} \u2014 did you mean: argent e2e run ${name}`;
   }
@@ -37633,17 +37381,17 @@ async function collectFlowFiles(dir, recursive2) {
   const found = [];
   const walk = async (current, rel) => {
     for (const entry of await fsp.readdir(current, { withFileTypes: true })) {
-      const entryRel = rel ? path18.join(rel, entry.name) : entry.name;
+      const entryRel = rel ? path17.join(rel, entry.name) : entry.name;
       if (entry.isDirectory()) {
         if (recursive2 && !entry.name.startsWith(".") && entry.name !== "node_modules") {
-          await walk(path18.join(current, entry.name), entryRel).catch(() => {
+          await walk(path17.join(current, entry.name), entryRel).catch(() => {
           });
         }
         continue;
       }
       if (!entry.name.endsWith(".yaml")) continue;
-      if (!SAFE_FLOW_NAME.test(path18.basename(entry.name, ".yaml"))) continue;
-      if (await isRunnableFlowFile(path18.join(current, entry.name))) found.push(entryRel);
+      if (!SAFE_FLOW_NAME.test(path17.basename(entry.name, ".yaml"))) continue;
+      if (await isRunnableFlowFile(path17.join(current, entry.name))) found.push(entryRel);
     }
   };
   await walk(dir, "");
@@ -37732,8 +37480,12 @@ function rejectionVerdict(code) {
     case FAILURE_CODES.FLOW_ENTRY_UNRECOGNIZED:
     case FAILURE_CODES.FLOW_E2E_HAS_PREREQUISITE:
       return "not run (invalid e2e test)";
+    case FAILURE_CODES.FLOW_FILE_NEWER_VERSION:
+      return "not run (needs a newer Argent)";
     case FAILURE_CODES.FLOW_DEVICE_RESOLUTION:
       return "not run (no device resolved)";
+    case FAILURE_CODES.FLOW_REQUIREMENTS_UNMET:
+      return "not run (requires not met)";
     case FAILURE_CODES.FILE_INPUT_UPLOAD_FAILED:
       return "not run (upload failed)";
     default:
@@ -37786,7 +37538,7 @@ async function runFlowDirectory(dir, args, projectRoot, options) {
     );
   }
   const { callTool, baseUrl } = runToolsClient(args, options);
-  const outputBase = args.output ? path18.resolve(args.output) : void 0;
+  const outputBase = args.output ? path17.resolve(args.output) : void 0;
   const results = [];
   const failures = [];
   const batchStartedAt = Date.now();
@@ -37799,7 +37551,7 @@ async function runFlowDirectory(dir, args, projectRoot, options) {
       if (!args.json) console.log(`  ${STATUS_GLYPH.skip} not run (batch stopped)`);
       continue;
     }
-    const flowPath = path18.join(dir, rel);
+    const flowPath = path17.join(dir, rel);
     const rerun = rerunCommand(flowPath, rel, projectRoot, args);
     let report;
     try {
@@ -37810,6 +37562,14 @@ async function runFlowDirectory(dir, args, projectRoot, options) {
       const err = unreachableErr ?? thrown;
       const message = err instanceof Error ? err.message : String(err);
       const toolErr = err instanceof ToolInvocationError ? err : void 0;
+      if (toolErr?.errorCode === FAILURE_CODES.FLOW_REQUIREMENTS_UNMET) {
+        const reason = message.replace(/^\[Tool:[^\]]+\] /, "");
+        results.push({ path: rel, status: "skip", reason });
+        if (!args.json)
+          console.log(`  ${STATUS_GLYPH.skip} skipped (requires not met)
+    ${reason}`);
+        continue;
+      }
       const rejectedThisFlowOnly = toolErr?.errorKind === "validation";
       const verdict = unreachableErr ? UNREACHABLE_VERDICT : rejectedThisFlowOnly ? rejectionVerdict(toolErr?.errorCode) : "did not finish (run error)";
       if (!args.json) console.log(`  ${STATUS_GLYPH.error} ${verdict}`);
@@ -37833,7 +37593,7 @@ async function runFlowDirectory(dir, args, projectRoot, options) {
     printWarnings(nestedStepWarnings(report.steps), args.json);
     await exportAndResolveArtifacts(
       report,
-      outputBase ? path18.join(outputBase, path18.dirname(rel)) : void 0,
+      outputBase ? path17.join(outputBase, path17.dirname(rel)) : void 0,
       flowPath,
       baseUrl
     );
@@ -37860,11 +37620,18 @@ async function runFlowDirectory(dir, args, projectRoot, options) {
     skipped: results.filter((r2) => r2.status === "skip").length
   };
   const durationMs = Date.now() - batchStartedAt;
+  const noneRan = counts.passed === 0 && counts.failed === 0;
   if (args.json) {
     console.log(
       JSON.stringify(
         // `flows` is the deprecated spelling of `e2eTests`.
-        { ok: counts.failed === 0, ...counts, durationMs, e2eTests: results, flows: results },
+        {
+          ok: counts.failed === 0 && !noneRan,
+          ...counts,
+          durationMs,
+          e2eTests: results,
+          flows: results
+        },
         null,
         2
       )
@@ -37873,8 +37640,9 @@ async function runFlowDirectory(dir, args, projectRoot, options) {
     for (const line of renderFailedFlows(failures)) console.log(line);
     console.log(`
 ${renderBatchSummary(counts, durationMs)}`);
+    if (noneRan) console.error(`No e2e test in ${dir} ran on the selected target.`);
   }
-  return exitAfterFlush(unreachable ? 2 : counts.failed === 0 ? 0 : 1);
+  return exitAfterFlush(unreachable || noneRan ? 2 : counts.failed === 0 ? 0 : 1);
 }
 async function e2e(argv, options) {
   const [sub, ...rest] = argv;
@@ -37891,14 +37659,14 @@ async function e2e(argv, options) {
     for (const dir of E2E_DIRS) {
       let rels;
       try {
-        rels = (await collectRunnableFlowPaths(path18.join(process.cwd(), dir))).sort();
+        rels = (await collectRunnableFlowPaths(path17.join(process.cwd(), dir))).sort();
       } catch {
         continue;
       }
       anyDir = true;
       for (const rel of rels) {
-        const shown = path18.join(dir, rel);
-        const name = path18.dirname(rel) === "." ? path18.basename(rel, ".yaml") : void 0;
+        const shown = path17.join(dir, rel);
+        const name = path17.dirname(rel) === "." ? path17.basename(rel, ".yaml") : void 0;
         const usedByName = name === void 0 ? void 0 : byName.get(name);
         if (name !== void 0 && usedByName === void 0) byName.set(name, shown);
         lines.push(shown);
@@ -37969,10 +37737,10 @@ async function e2e(argv, options) {
   }
   if (suppliedPath.split(/[\\/]+/).includes("..")) {
     let recovery = "Pass the fully resolved path to the e2e test's YAML.";
-    const suppliedBase2 = path18.basename(suppliedPath);
+    const suppliedBase2 = path17.basename(suppliedPath);
     if (suppliedBase2 !== ".." && suppliedBase2 !== ".") {
       try {
-        const resolved = path18.join(await fsp.realpath(path18.dirname(suppliedPath)), suppliedBase2);
+        const resolved = path17.join(await fsp.realpath(path17.dirname(suppliedPath)), suppliedBase2);
         await fsp.stat(resolved);
         recovery = `Did you mean: argent e2e run ${shellQuoteArg(resolved)}`;
       } catch {
@@ -37984,7 +37752,7 @@ async function e2e(argv, options) {
       2
     );
   }
-  const resolvedPath = path18.resolve(projectRoot, suppliedPath);
+  const resolvedPath = path17.resolve(projectRoot, suppliedPath);
   let isDirectory = false;
   try {
     isDirectory = (await fsp.stat(resolvedPath)).isDirectory();
@@ -38007,16 +37775,16 @@ async function e2e(argv, options) {
   }
   const separatorTrimmedPath = suppliedPath.replace(/[\\/]+$/, "");
   if (separatorTrimmedPath !== suppliedPath && separatorTrimmedPath !== "") {
-    const hint = SAFE_FLOW_NAME.test(separatorTrimmedPath) ? `.${path18.sep}${separatorTrimmedPath}` : separatorTrimmedPath;
+    const hint = SAFE_FLOW_NAME.test(separatorTrimmedPath) ? `.${path17.sep}${separatorTrimmedPath}` : separatorTrimmedPath;
     return fail(
       `E2E test path must not end in a path separator \u2014 the separator claims a directory, which the kernel would refuse to open as a file, so the CLI would run a file this string does not name: ${suppliedPath}
 Did you mean: argent e2e run ${shellQuoteArg(hint)}`,
       2
     );
   }
-  if (path18.extname(suppliedPath) !== ".yaml") {
-    const looksLikeName = !suppliedPath.includes("/") && !suppliedPath.includes("\\") && path18.extname(suppliedPath) === "";
-    if (path18.basename(suppliedPath).toLowerCase() === ".yaml") {
+  if (path17.extname(suppliedPath) !== ".yaml") {
+    const looksLikeName = !suppliedPath.includes("/") && !suppliedPath.includes("\\") && path17.extname(suppliedPath) === "";
+    if (path17.basename(suppliedPath).toLowerCase() === ".yaml") {
       return fail(
         `E2E test filename must have a non-empty name containing only letters, numbers, "_", or "-": ${suppliedPath}`,
         2
@@ -38029,15 +37797,15 @@ Names run \`${E2E_DIRS.map((dir) => `${dir}/<name>.yaml`).join("` or `")}\`; pas
         2
       );
     }
-    if (path18.extname(suppliedPath).toLowerCase() === ".yaml") {
+    if (path17.extname(suppliedPath).toLowerCase() === ".yaml") {
       return fail(
-        `E2E test extension must be lowercase .yaml, not ${path18.extname(suppliedPath)}: ${suppliedPath}`,
+        `E2E test extension must be lowercase .yaml, not ${path17.extname(suppliedPath)}: ${suppliedPath}`,
         2
       );
     }
     return fail(`E2E test path must end in .yaml: ${suppliedPath}`, 2);
   }
-  const flowName = path18.basename(suppliedPath, ".yaml");
+  const flowName = path17.basename(suppliedPath, ".yaml");
   if (!SAFE_FLOW_NAME.test(flowName)) {
     return fail(
       `E2E test filename must have a non-empty name containing only letters, numbers, "_", or "-": ${suppliedPath}`,
@@ -38061,12 +37829,12 @@ No e2e test named "${args.flowRef}" is saved in ${E2E_DIRS.join(" or ")} \u2014
     }
     return fail(`${detail}: ${flowPath}${recovery}`, 2);
   }
-  const suppliedBase = path18.basename(flowPath);
-  const siblings = await fsp.readdir(path18.dirname(flowPath)).catch(() => null);
+  const suppliedBase = path17.basename(flowPath);
+  const siblings = await fsp.readdir(path17.dirname(flowPath)).catch(() => null);
   if (siblings !== null && !siblings.includes(suppliedBase)) {
     const actual = siblings.find((name) => name.toLowerCase() === suppliedBase.toLowerCase());
-    const actualRunnable = actual !== void 0 && path18.extname(actual) === ".yaml" && SAFE_FLOW_NAME.test(path18.basename(actual, ".yaml"));
-    const recovery = actualRunnable ? fromName ? `Did you mean: argent e2e run ${path18.basename(actual, ".yaml")}` : `Did you mean: argent e2e run ${shellQuoteArg(path18.join(path18.dirname(suppliedPath), actual))}` : actual !== void 0 ? `Rename ${actual} to ${suppliedBase} to run it \u2014 e2e test files must be lowercase .yaml.` : "Pass the e2e test file's name exactly as it appears on disk.";
+    const actualRunnable = actual !== void 0 && path17.extname(actual) === ".yaml" && SAFE_FLOW_NAME.test(path17.basename(actual, ".yaml"));
+    const recovery = actualRunnable ? fromName ? `Did you mean: argent e2e run ${path17.basename(actual, ".yaml")}` : `Did you mean: argent e2e run ${shellQuoteArg(path17.join(path17.dirname(suppliedPath), actual))}` : actual !== void 0 ? `Rename ${actual} to ${suppliedBase} to run it \u2014 e2e test files must be lowercase .yaml.` : "Pass the e2e test file's name exactly as it appears on disk.";
     return fail(
       `E2E test path must name the file as it appears on disk \u2014 this filesystem matched ${JSON.stringify(suppliedBase)} case-insensitively${actual !== void 0 ? ` to ${JSON.stringify(actual)}` : ""}, so the test name (which keys the report, __baselines__/, and --output) would be one no file carries: ${suppliedPath}
 ${recovery}`,
@@ -38125,7 +37893,7 @@ ${recovery}`,
   try {
     await exportAndResolveArtifacts(
       report,
-      args.output ? path18.resolve(args.output) : void 0,
+      args.output ? path17.resolve(args.output) : void 0,
       flowPath,
       baseUrl
     );
@@ -38154,6 +37922,313 @@ ${renderSummary(report, { withDevice: true })}`);
   return exitAfterFlush(report.ok && unwritten.length === 0 ? 0 : 1);
 }
 
+// ../argent-cli/src/run.ts
+function splitOptions(argv) {
+  let json2 = false;
+  let outPath = null;
+  const rest = [];
+  for (let i2 = 0; i2 < argv.length; i2++) {
+    const tok = argv[i2];
+    if (tok === "--json") {
+      json2 = true;
+      continue;
+    }
+    if (tok === "--out") {
+      const v = argv[i2 + 1];
+      if (!v) throw new FlagParseException("--out requires a path");
+      outPath = v;
+      i2 += 1;
+      continue;
+    }
+    if (tok.startsWith("--out=")) {
+      outPath = tok.slice("--out=".length);
+      continue;
+    }
+    rest.push(tok);
+  }
+  return { json: json2, outPath, argvForFlags: rest };
+}
+async function readStdin() {
+  return new Promise((resolve13, reject) => {
+    let data = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on("end", () => resolve13(data));
+    process.stdin.on("error", reject);
+  });
+}
+function printToolHelp(meta3) {
+  const description = meta3.description?.trim() ?? "";
+  const schema = meta3.inputSchema;
+  const hasOwnArgsField = schema?.properties?.args !== void 0;
+  console.log(`argent run ${meta3.name} [flags]`);
+  if (description) console.log(`
+${description}
+`);
+  console.log("Flags:");
+  console.log(formatSchemaUsage(schema));
+  console.log("\nGlobal flags:");
+  if (!hasOwnArgsField) {
+    console.log("  --args <json>          Pass the entire payload as JSON (overrides flags)");
+    console.log("  --args -               Read the entire payload as JSON from stdin");
+  }
+  console.log("  --<field>-json <json>  Pass a single field as JSON (objects/nested arrays)");
+  console.log("  --json                 Print the raw JSON result");
+  console.log("  --out <path>           For image results, save to <path> instead of fetching URL");
+  console.log("  --help, -h             Show this help");
+}
+async function fetchImageToFile(result, outPath) {
+  const url2 = result.url;
+  if (!url2) {
+    throw new Error("Tool result did not include a `url`; cannot save image");
+  }
+  const res = await fetch(url2);
+  if (!res.ok) throw new Error(`Failed to download image: ${res.status} ${res.statusText}`);
+  const buf = Buffer.from(await res.arrayBuffer());
+  fs12.mkdirSync(path18.dirname(path18.resolve(outPath)), { recursive: true });
+  fs12.writeFileSync(outPath, buf);
+}
+function renderResult(result, outputHint, images, json2) {
+  if (json2) return JSON.stringify(result, null, 2);
+  if (outputHint === "image") {
+    if (images.length > 0) return `Saved screenshot: ${images[0].localPath}`;
+    if (result && typeof result === "object" && "path" in result && typeof result.path === "string") {
+      return `Saved screenshot: ${result.path}`;
+    }
+  }
+  if (typeof result === "string") return result;
+  return JSON.stringify(result, null, 2);
+}
+var SAFE_TOOL_RE = /^[a-z][a-z0-9_-]{0,63}$/;
+function safeToolName(toolName) {
+  return toolName && SAFE_TOOL_RE.test(toolName) ? toolName : "unknown";
+}
+async function trackRunFailure(toolName, startedAt, signal) {
+  const tool = toolName ? canonicalToolId(toolName) : toolName;
+  track("cli:run_fail", {
+    tool: safeToolName(tool),
+    ...tool !== toolName ? { alias_used: true } : {},
+    duration_ms: performance.now() - startedAt,
+    ...signal
+  });
+  await shutdown();
+}
+async function run(argv, options) {
+  init("cli");
+  const startedAt = performance.now();
+  const { fetchTool, callTool, baseUrl } = createToolsClient({ paths: options.paths });
+  const [toolName, ...rest] = argv;
+  if (!toolName || toolName === "--help" || toolName === "-h") {
+    console.log(`Usage: argent run <tool> [flags]
+
+Invoke a tool exposed by the argent tool-server. Run \`argent tools\` to list
+available tools, or \`argent tools describe <name>\` to see one tool's flags.
+
+Examples:
+  argent run list-devices
+  argent run gesture-tap --udid <UDID> --x 0.5 --y 0.5
+  argent run screenshot --udid <UDID> --out ./screen.png
+  argent run run-sequence --udid <UDID> --steps-json '[{"tool":"button","args":{"button":"home"}}]'
+  argent run gesture-tap --args '{"udid":"<UDID>","x":0.5,"y":0.5}'
+
+Exits 1 when the tool fails. Also exits 1 when the result reports that the
+call did not do its job: an e2e test that does not pass, an await-ui-element
+wait with success=false, a run-sequence that a step stopped, a debugger tool
+with no connection or an error, a native-devtools precheck that stopped the
+tool, a native-profiler-analyze with status analysis_failed, an e2e recording
+call that recorded nothing, or a baseline that was not written on this client.
+Other results exit 0, also a negative answer such as await-screen-idle's
+settled=false or debugger-status's not_connected.
+`);
+    return;
+  }
+  let cliOptions;
+  try {
+    cliOptions = splitOptions(rest);
+  } catch (err) {
+    if (err instanceof FlagParseException) {
+      console.error(`Error: ${err.message}
+`);
+      console.error(`Run \`argent run ${toolName} --help\` to see this tool's flags.`);
+      await trackRunFailure(toolName, startedAt, {
+        error_code: FAILURE_CODES.CLI_RUN_FLAG_PARSE_FAILED,
+        failure_stage: "cli_run_split_options",
+        failure_area: "cli",
+        error_kind: "validation"
+      });
+      process.exit(2);
+    }
+    throw err;
+  }
+  const { json: json2, outPath, argvForFlags } = cliOptions;
+  const meta3 = await fetchTool(toolName);
+  if (!meta3) {
+    console.error(`Tool "${toolName}" not found. Run \`argent tools\` to list available tools.`);
+    await trackRunFailure(toolName, startedAt, {
+      error_code: FAILURE_CODES.CLI_RUN_TOOL_NOT_FOUND,
+      failure_stage: "cli_run_fetch_tool",
+      failure_area: "cli",
+      error_kind: "not_found"
+    });
+    process.exit(1);
+  }
+  const schema = meta3.inputSchema;
+  const failInvocation = async (summary, report, failure3) => {
+    if (json2) {
+      console.error(
+        JSON.stringify(
+          {
+            error: summary,
+            missing: report ? missingFlagNames(report, schema) : [],
+            issues: report?.rawIssues ?? []
+          },
+          null,
+          2
+        )
+      );
+    } else {
+      console.error(`Error: ${summary}
+`);
+      printToolHelp(meta3);
+    }
+    await trackRunFailure(toolName, startedAt, {
+      ...failure3,
+      failure_area: "cli",
+      error_kind: "validation"
+    });
+    process.exit(2);
+  };
+  const failValidation = (report, stage) => failInvocation(formatValidationError(report, schema), report, {
+    error_code: FAILURE_CODES.CLI_RUN_INPUT_VALIDATION_FAILED,
+    failure_stage: stage
+  });
+  let parsed;
+  try {
+    parsed = parseFlags(argvForFlags, schema);
+  } catch (err) {
+    if (err instanceof FlagParseException) {
+      await failInvocation(err.message, null, {
+        error_code: FAILURE_CODES.CLI_RUN_FLAG_PARSE_FAILED,
+        failure_stage: "cli_run_parse_flags"
+      });
+    }
+    throw err;
+  }
+  if (parsed.helpRequested) {
+    printToolHelp(meta3);
+    return;
+  }
+  if (parsed.positional.length > 0) {
+    console.error(
+      `Note: ignoring unused argument(s): ${parsed.positional.join(", ")}. Pass values as --flag <value> or --flag=<value>.`
+    );
+  }
+  let payload = {};
+  if (parsed.rawArgs !== null) {
+    let rawJson = parsed.rawArgs;
+    if (rawJson === "-") {
+      rawJson = await readStdin();
+    }
+    try {
+      const parsedRaw = JSON.parse(rawJson);
+      if (parsedRaw === null || typeof parsedRaw !== "object" || Array.isArray(parsedRaw)) {
+        console.error("--args must be a JSON object");
+        await trackRunFailure(toolName, startedAt, {
+          error_code: FAILURE_CODES.CLI_RUN_ARGS_NOT_OBJECT,
+          failure_stage: "cli_run_parse_raw_args",
+          failure_area: "cli",
+          error_kind: "validation"
+        });
+        process.exit(2);
+      }
+      payload = parsedRaw;
+    } catch (err) {
+      console.error(`--args is not valid JSON: ${err instanceof Error ? err.message : err}`);
+      await trackRunFailure(toolName, startedAt, {
+        error_code: FAILURE_CODES.CLI_RUN_ARGS_JSON_INVALID,
+        failure_stage: "cli_run_parse_raw_args",
+        failure_area: "cli",
+        error_kind: "validation"
+      });
+      process.exit(2);
+    }
+  }
+  for (const [k, v] of Object.entries(parsed.args)) {
+    payload[k] = v;
+  }
+  const missing = findMissingRequired(payload, schema);
+  if (missing.length > 0) {
+    await failValidation({ missing, invalid: [], rawIssues: null }, "cli_run_required_flags");
+  }
+  let result;
+  let note;
+  let failure2;
+  let images = [];
+  try {
+    const resp = await callTool(toolName, payload);
+    const { url: url2, token } = await baseUrl();
+    const materialized = await materializeArtifacts(resp.data, {
+      toolsUrl: url2,
+      authToken: token,
+      deviceId: getDeviceIdFromArgs(payload)
+    });
+    result = materialized.result;
+    images = materialized.images;
+    note = resp.note;
+    failure2 = resp.failure;
+  } catch (err) {
+    const report = describeServerValidationFailure(err, payload, schema);
+    if (report) {
+      await failValidation(report, "cli_run_server_validation");
+    }
+    console.error(err instanceof Error ? err.message : String(err));
+    await trackRunFailure(toolName, startedAt, {
+      error_code: FAILURE_CODES.CLI_RUN_TOOL_CALL_FAILED,
+      failure_stage: "cli_run_call_tool",
+      failure_area: "cli",
+      error_kind: "unknown"
+    });
+    process.exit(1);
+  }
+  if (outPath && meta3.outputHint === "image") {
+    try {
+      if (images.length > 0) {
+        fs12.mkdirSync(path18.dirname(path18.resolve(outPath)), { recursive: true });
+        fs12.writeFileSync(outPath, images[0].data);
+      } else if (result && typeof result === "object") {
+        await fetchImageToFile(result, outPath);
+      }
+    } catch (err) {
+      console.error(`Failed to save image: ${err instanceof Error ? err.message : err}`);
+      await trackRunFailure(toolName, startedAt, {
+        error_code: FAILURE_CODES.CLI_RUN_SAVE_IMAGE_FAILED,
+        failure_stage: "cli_run_save_image",
+        failure_area: "cli",
+        error_kind: "unknown"
+      });
+      process.exit(1);
+    }
+  }
+  if (note) console.error(note);
+  console.log(renderResult(result, meta3.outputHint, images, json2));
+  if (outPath && meta3.outputHint === "image" && !json2) {
+    console.log(`Wrote: ${outPath}`);
+  }
+  if (failure2) {
+    await new Promise((resolve13) => process.stdout.write("", () => resolve13()));
+    console.error(failure2);
+    await trackRunFailure(toolName, startedAt, {
+      error_code: FAILURE_CODES.CLI_RUN_TOOL_RESULT_FAILED,
+      failure_stage: "cli_run_tool_result",
+      failure_area: "cli",
+      error_kind: "unknown"
+    });
+    await exitAfterFlush(1, [process.stderr]);
+  }
+}
+
 // ../argent-cli/src/tools.ts
 function summarize(description, max = 80) {
   if (!description) return "";