@deeeed/metamask-harness 0.6.2 → 0.7.0

package/adapters/shared/resolve-slot-ports-core.mjs

@@ -0,0 +1,213 @@
+// Slot-pool + slot-suffix port resolution — pure JS for runner and overlay leaves.
+// Reads the orchestrator's pool JSON (the on-disk `pool/` directory) when a slot
+// repo matches, else the local-extension-N suffix formula.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const coreDir = path.dirname(fileURLToPath(import.meta.url));
+
+function pathDefault(key) {
+  for (const candidate of [
+    path.join(coreDir, 'path-defaults.json'),
+    path.join(coreDir, '../../adapters/shared/path-defaults.json'),
+  ]) {
+    if (!fs.existsSync(candidate)) continue;
+    const value = JSON.parse(fs.readFileSync(candidate, 'utf8'))[key];
+    if (value) return value;
+  }
+  throw new Error(`Missing path default: ${key}`);
+}
+
+function recipeRuntimeDir() {
+  return process.env.RECIPE_RUNTIME_DIR || pathDefault('recipeRuntimeDir');
+}
+
+export function formatKvLines(kv) {
+  const lines = [];
+  if (kv.CDP_PORT !== undefined) lines.push(`CDP_PORT=${kv.CDP_PORT}`);
+  if (kv.WATCHER_PORT !== undefined) lines.push(`WATCHER_PORT=${kv.WATCHER_PORT}`);
+  if (kv.SLOT_ID) lines.push(`SLOT_ID=${kv.SLOT_ID}`);
+  if (kv.IOS_SIMULATOR) lines.push(`IOS_SIMULATOR=${kv.IOS_SIMULATOR}`);
+  return lines.length ? `${lines.join('\n')}\n` : '';
+}
+
+export function realRepoPath(repo) {
+  if (!repo) return null;
+  try {
+    return fs.realpathSync(repo);
+  } catch {
+    return null;
+  }
+}
+
+export function inferSlotSuffix(repo) {
+  const base = path.basename(repo);
+  const m = /-(\d+)$/u.exec(base);
+  return m ? m[1] : null;
+}
+
+function scoreSlot(slot, slotSuffix) {
+  const resources = slot.resources ?? {};
+  const cdp = resources.browser?.cdp_port;
+  const port = resources['dev-server']?.port;
+  const simulator = resources['ios-sim']?.simulator;
+  const session = slot.session ?? '';
+  const slotId = slot.id ?? '';
+  let score = 0;
+  if (cdp !== undefined) score += 100;
+  if (port !== undefined) score += 10;
+  if (slotSuffix) {
+    if (session === `mme-${slotSuffix}`) score += 50;
+    if (slotId.endsWith(`mme-${slotSuffix}`) || slotId.includes(`-mme-${slotSuffix}`)) score += 40;
+  }
+  if (!slotId.toLowerCase().includes('demo')) score += 5;
+  return [score, cdp, port, slotId, simulator];
+}
+
+export function resolveSlotPortsByRepo(repo) {
+  const realRepo = realRepoPath(repo);
+  if (!realRepo) return null;
+
+  const slotSuffix = inferSlotSuffix(realRepo);
+  const roots = [];
+  // A slot checkout lives at <workspace>/repos/<slot>; that workspace's own
+  // pool is the authoritative one for this repo — machine-global fallbacks
+  // (env root, dev checkout) apply only when the repo is not workspace-shaped.
+  if (path.basename(path.dirname(realRepo)) === 'repos') {
+    roots.push(path.join(path.dirname(path.dirname(realRepo)), 'farmslot'));
+  }
+  if (process.env.FARMSLOT_ROOT) roots.push(process.env.FARMSLOT_ROOT);
+  roots.push(path.join(os.homedir(), 'dev', 'farmslot'));
+
+  for (const root of roots) {
+    if (!root || !fs.existsSync(path.join(root, 'pool'))) continue;
+    const poolDir = path.join(root, 'pool');
+    let best = null;
+
+    for (const name of fs.readdirSync(poolDir).sort()) {
+      if (!name.endsWith('.json') || name.includes('.bak.')) continue;
+      let data;
+      try {
+        data = JSON.parse(fs.readFileSync(path.join(poolDir, name), 'utf8'));
+      } catch {
+        continue;
+      }
+      for (const slot of data.slots ?? []) {
+        const slotRepo = slot.repo ?? '';
+        if (!slotRepo) continue;
+        let slotReal;
+        try {
+          slotReal = fs.realpathSync(slotRepo);
+        } catch {
+          continue;
+        }
+        if (slotReal !== realRepo) continue;
+        const scored = scoreSlot(slot, slotSuffix);
+        if (!best || scored[0] > best[0]) best = scored;
+      }
+    }
+
+    if (best) {
+      const [, cdp, port, slotId, simulator] = best;
+      return formatKvLines({
+        ...(cdp !== undefined ? { CDP_PORT: cdp } : {}),
+        ...(port !== undefined ? { WATCHER_PORT: port } : {}),
+        ...(slotId ? { SLOT_ID: slotId } : {}),
+        ...(simulator ? { IOS_SIMULATOR: simulator } : {}),
+      });
+    }
+  }
+  return null;
+}
+
+export function resolveDefaultExtensionPorts(repo) {
+  const n = inferSlotSuffix(repo);
+  if (!n) return null;
+  return formatKvLines({
+    CDP_PORT: 6660 + Number(n),
+    WATCHER_PORT: 9010 + Number(n),
+    SLOT_ID: `local-extension-${n}`,
+  });
+}
+
+export function resolveExtensionRuntimePorts(repo) {
+  return resolveSlotPortsByRepo(repo) ?? resolveDefaultExtensionPorts(repo) ?? '';
+}
+
+export function resolveMobileSlotDefaults(repo) {
+  const n = inferSlotSuffix(repo);
+  if (!n) return null;
+  return formatKvLines({
+    WATCHER_PORT: 8060 + Number(n),
+    IOS_SIMULATOR: `mm-${n}`,
+    SLOT_ID: `local-mobile-${n}`,
+  });
+}
+
+export function resolveMobileRuntimeContext(repo) {
+  const ctxPath = path.join(repo, recipeRuntimeDir(), 'agentic-runtime.json');
+  if (fs.existsSync(ctxPath)) {
+    try {
+      const c = JSON.parse(fs.readFileSync(ctxPath, 'utf8'));
+      if (c.simulator || (c.metroPort != null && c.metroPort !== '')) {
+        return formatKvLines({
+          ...(c.metroPort != null && c.metroPort !== '' ? { WATCHER_PORT: c.metroPort } : {}),
+          ...(c.simulator ? { IOS_SIMULATOR: c.simulator } : {}),
+          ...(c.slotId ? { SLOT_ID: c.slotId } : {}),
+        });
+      }
+    } catch {
+      /* unreadable context falls through to the provision baseline */
+    }
+  }
+  return resolveMobileProvisionBaseline(repo);
+}
+
+// A provisioned-but-unprepared slot has no agentic-runtime.json yet, but the
+// provision baseline records the same authoritative simulator/port identity —
+// without it, a fresh slot's first launch degrades to the simctl `booted`
+// alias and misses the installed dev client entirely.
+function resolveMobileProvisionBaseline(repo) {
+  const basePath = path.join(repo, recipeRuntimeDir(), 'runway-provision.json');
+  if (!fs.existsSync(basePath)) return null;
+  try {
+    const c = JSON.parse(fs.readFileSync(basePath, 'utf8'));
+    const simulator = c.simulator?.name || c.simulator?.udid;
+    const watcherPort = c.watcherPort != null && c.watcherPort !== '' ? c.watcherPort : undefined;
+    if (!simulator && watcherPort === undefined) return null;
+    return formatKvLines({
+      ...(watcherPort !== undefined ? { WATCHER_PORT: watcherPort } : {}),
+      ...(simulator ? { IOS_SIMULATOR: simulator } : {}),
+      ...(c.slotId ? { SLOT_ID: c.slotId } : {}),
+    });
+  } catch {
+    return null;
+  }
+}
+
+export function resolveMobileRuntimePorts(repo) {
+  return (
+    resolveMobileRuntimeContext(repo)
+    ?? resolveSlotPortsByRepo(repo)
+    ?? resolveMobileSlotDefaults(repo)
+    ?? ''
+  );
+}
+
+// Back-compat: the previous name for resolveSlotPortsByRepo, kept as an alias for
+// one release so existing importers keep resolving.
+export const resolveFarmslotPortsByRepo = resolveSlotPortsByRepo;
+
+export const cliFns = {
+  resolve_slot_ports_by_repo: resolveSlotPortsByRepo,
+  // Back-compat cli key for one release.
+  resolve_farmslot_ports_by_repo: resolveSlotPortsByRepo,
+  resolve_default_extension_ports: resolveDefaultExtensionPorts,
+  resolve_extension_runtime_ports: (repo) => resolveExtensionRuntimePorts(repo) || null,
+  resolve_mobile_runtime_context: resolveMobileRuntimeContext,
+  resolve_mobile_slot_defaults: resolveMobileSlotDefaults,
+  resolve_mobile_runtime_ports: (repo) => resolveMobileRuntimePorts(repo) || null,
+};

package/adapters/shared/resolve-slot-ports.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+// Node leaf for port resolution — self-contained for runner and injected overlay copies.
+
+import { cliFns } from './resolve-slot-ports-core.mjs';
+
+const [, , fn, repo] = process.argv;
+if (!fn || fn === '-h' || fn === '--help') {
+  process.stderr.write('Usage: resolve-slot-ports.mjs <fn> <repo>\n');
+  process.exit(fn ? 0 : 2);
+}
+
+const handler = cliFns[fn];
+if (!handler) {
+  process.stderr.write(`resolve-slot-ports: unknown fn: ${fn}\n`);
+  process.exit(2);
+}
+
+const out = handler(repo ?? '.');
+if (!out?.trim()) process.exit(1);
+process.stdout.write(out.endsWith('\n') ? out : `${out}\n`);

package/adapters/shared/resolve-slot-ports.sh

@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+# resolve-slot-ports.sh — bash-compat wrapper over resolve-slot-ports.mjs
+#
+# The orchestrator's pool JSON is authoritative when a slot repo matches; otherwise
+# fall back to the local-extension-N formula (6660+N / 9010+N).
+#
+# Usage:
+#   . resolve-slot-ports.sh
+#   resolve_extension_runtime_ports /path/to/metamask-extension-N
+#     -> prints CDP_PORT=... WATCHER_PORT=... SLOT_ID=... lines
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+_RESOLVE_PORTS_MJS="$SCRIPT_DIR/resolve-slot-ports.mjs"
+
+_resolve_ports_cli() {
+  node "$_RESOLVE_PORTS_MJS" "$1" "${2:-.}"
+}
+
+resolve_slot_ports_by_repo() {
+  _resolve_ports_cli resolve_slot_ports_by_repo "$1"
+}
+
+# Back-compat alias for the previous function name (one release).
+resolve_farmslot_ports_by_repo() {
+  resolve_slot_ports_by_repo "$1"
+}
+
+infer_extension_slot_suffix() {
+  local repo="$1" base
+  base="$(basename "$repo")"
+  if [[ "$base" =~ -([0-9]+)$ ]]; then
+    printf '%s' "${BASH_REMATCH[1]}"
+    return 0
+  fi
+  return 1
+}
+
+resolve_default_extension_ports() {
+  _resolve_ports_cli resolve_default_extension_ports "$1"
+}
+
+resolve_extension_runtime_ports() {
+  _resolve_ports_cli resolve_extension_runtime_ports "${1:-.}"
+}
+
+apply_resolved_extension_ports() {
+  local repo="${1:-.}" line key val from_pool=false resolved=""
+  if resolved="$(_resolve_ports_cli resolve_slot_ports_by_repo "$repo" 2>/dev/null)"; then
+    from_pool=true
+  elif resolved="$(_resolve_ports_cli resolve_default_extension_ports "$repo" 2>/dev/null)"; then
+    from_pool=false
+  else
+    return 0
+  fi
+  while IFS= read -r line; do
+    [ -n "$line" ] || continue
+    key="${line%%=*}"
+    val="${line#*=}"
+    case "$key" in
+      CDP_PORT)
+        if [ "$from_pool" = true ] || [ -z "${CDP_PORT:-}" ]; then CDP_PORT="$val"; fi
+        ;;
+      WATCHER_PORT)
+        if [ "$from_pool" = true ] || [ -z "${WATCHER_PORT:-}" ]; then WATCHER_PORT="$val"; fi
+        ;;
+      SLOT_ID)
+        if [ "$from_pool" = true ] || [ -z "${RECIPE_SLOT_ID:-}" ]; then RECIPE_SLOT_ID="$val"; fi
+        ;;
+    esac
+  done <<< "$resolved"
+}
+
+resolve_mobile_slot_defaults() {
+  _resolve_ports_cli resolve_mobile_slot_defaults "$1"
+}
+
+resolve_mobile_runtime_context() {
+  _resolve_ports_cli resolve_mobile_runtime_context "$1"
+}
+
+resolve_mobile_runtime_ports() {
+  _resolve_ports_cli resolve_mobile_runtime_ports "${1:-.}"
+}
+
+apply_resolved_mobile_ports() {
+  local repo="${1:-.}" line key val from_pool=false resolved=""
+  if resolved="$(_resolve_ports_cli resolve_slot_ports_by_repo "$repo" 2>/dev/null)"; then
+    from_pool=true
+  elif resolved="$(_resolve_ports_cli resolve_mobile_slot_defaults "$repo" 2>/dev/null)"; then
+    from_pool=false
+  else
+    return 0
+  fi
+  while IFS= read -r line; do
+    [ -n "$line" ] || continue
+    key="${line%%=*}"
+    val="${line#*=}"
+    case "$key" in
+      WATCHER_PORT)
+        if [ "$from_pool" = true ] || [ -z "${WATCHER_PORT:-}" ]; then WATCHER_PORT="$val"; fi
+        ;;
+      IOS_SIMULATOR)
+        if [ "$from_pool" = true ] || [ -z "${IOS_SIMULATOR:-}" ]; then IOS_SIMULATOR="$val"; fi
+        ;;
+      SLOT_ID)
+        if [ "$from_pool" = true ] || [ -z "${RECIPE_SLOT_ID:-}" ]; then RECIPE_SLOT_ID="$val"; fi
+        ;;
+    esac
+  done <<< "$resolved"
+}

package/adapters/shared/tmux-session.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# tmux-session — resolve the run-owned tmux session a log-tail window belongs in.
+#
+# Responsibility split: the orchestrator (farmslot) NAMES the session; the harness
+# only POPULATES windows inside it. The name is therefore never guessed from the
+# slot number — a renamed pool or a manual run would land the window (and its
+# tail -F) in the wrong place. Resolution ladder, first hit wins:
+#   1. RECIPE_TMUX_SESSION            — the orchestrator's explicit hand-off.
+#   2. agentic-runtime.json `session` — the prepared checkout's recorded session.
+#   3. the current session            — but ONLY inside a tmux client (never the
+#      last-attached session reported outside one, which would be a foreign leak).
+# Prints the resolved name (empty when none). Callers still gate on has-session
+# before creating a window.
+
+# shellcheck disable=SC2329  # sourced by leaves and by contract tests.
+resolve_run_tmux_session() {
+  local runtime_dir="${1:-}" ctx="" session=""
+  if [ -n "${RECIPE_TMUX_SESSION:-}" ]; then
+    printf '%s\n' "$RECIPE_TMUX_SESSION"
+    return 0
+  fi
+  ctx="${RECIPE_RUNTIME_CONTEXT:-}"
+  if [ -z "$ctx" ] && [ -n "$runtime_dir" ]; then ctx="$runtime_dir/agentic-runtime.json"; fi
+  if [ -n "$ctx" ] && [ -f "$ctx" ] && command -v node >/dev/null 2>&1; then
+    session="$(RUN_TMUX_CTX="$ctx" node -e 'try{const d=JSON.parse(require("fs").readFileSync(process.env.RUN_TMUX_CTX,"utf8"));const s=d&&d.session;if(s!==undefined&&s!==null&&s!=="")process.stdout.write(String(s));}catch{}' 2>/dev/null || true)"
+    if [ -n "$session" ]; then
+      printf '%s\n' "$session"
+      return 0
+    fi
+  fi
+  if [ -n "${TMUX:-}" ]; then
+    tmux display-message -p '#S' 2>/dev/null || true
+  fi
+  return 0
+}

package/dist/adapters/extension/runtime-decision.js

@@ -181,6 +181,9 @@ function distCheck(target) {
   }
   return { status: "fresh", distGitId: distShort, head: headShort };
 }
+function isExtensionDistStale(target) {
+  return distCheck(path.resolve(target)).status === "stale";
+}
 async function cdpCheck(target, cdpPort) {
   if (!cdpPort) return { status: "skipped" };
   try {
@@ -301,5 +304,6 @@ function buildAction(target, clean) {
 }
 export {
   decideExtensionReadiness,
+  isExtensionDistStale,
   recordReadinessBaseline
 };

package/dist/adapters/mobile/provision.js

@@ -4,7 +4,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { recipeRuntimeDir } from "../../paths.js";
-import { resolveFarmslotPortsByRepo } from "../../../adapters/shared/resolve-farmslot-ports-core.mjs";
+import { resolveSlotPortsByRepo } from "../../../adapters/shared/resolve-slot-ports-core.mjs";
 const RUNWAY_IOS_METADATA = {
   artifactName: "ios-app-main-dev-expo",
   workflow: "expo-dev-build.yml",
@@ -13,7 +13,7 @@ const RUNWAY_IOS_METADATA = {
   fallbackRepo: "MetaMask/metamask-mobile"
 };
 function resolvePoolIdentity(target) {
-  const out = resolveFarmslotPortsByRepo(target);
+  const out = resolveSlotPortsByRepo(target);
   const id = {};
   if (!out) return id;
   for (const line of String(out).split("\n")) {
@@ -95,6 +95,7 @@ async function provisionRunwayMobile(target, options) {
     log(options, `runway: installing ${cache.artifact.appPath} on ${sim.name}`);
     bootSimulator(sim.udid ?? sim.name, options);
     execFileSync("xcrun", ["simctl", "install", sim.udid ?? sim.name, cache.artifact.appPath], { stdio: ["ignore", "ignore", "pipe"] });
+    preapproveDeepLinkScheme(sim.udid ?? sim.name, RUNWAY_IOS_METADATA.bundleId, options);
     const baselinePath = writeRunwayBaseline(resolvedTarget, slot, platform, resolved, cache.artifact, sim, false, options.runtimeDir);
     return {
       schemaVersion: 1,
@@ -412,6 +413,28 @@ function bootSimulator(device, options) {
     log(options, `runway: bootstatus wait for ${device} did not confirm; continuing to install`);
   }
 }
+function preapproveDeepLinkScheme(device, bundleId, options) {
+  const scheme = process.env.IOS_DEV_CLIENT_SCHEME ?? "expo-metamask";
+  try {
+    execFileSync(
+      "xcrun",
+      [
+        "simctl",
+        "spawn",
+        device,
+        "defaults",
+        "write",
+        "com.apple.launchservices.schemeapproval",
+        `com.apple.CoreSimulator.CoreSimulatorBridge-->${scheme}`,
+        "-string",
+        bundleId
+      ],
+      { stdio: ["ignore", "ignore", "ignore"], timeout: 15e3 }
+    );
+    log(options, `runway: pre-approved deep-link scheme ${scheme} \u2192 ${bundleId}`);
+  } catch {
+  }
+}
 function ensureSimulator(name, runtime, deviceType) {
   const existing = findSimulator(name);
   if (existing) return { name, udid: existing, created: false, runtime, deviceType };

package/dist/adapters/{resolve-farmslot-ports.js → resolve-slot-ports.js}

@@ -4,11 +4,12 @@ import {
   realRepoPath,
   resolveDefaultExtensionPorts,
   resolveExtensionRuntimePorts,
+  resolveSlotPortsByRepo,
   resolveFarmslotPortsByRepo,
   resolveMobileRuntimeContext,
   resolveMobileRuntimePorts,
   resolveMobileSlotDefaults
-} from "../../adapters/shared/resolve-farmslot-ports-core.mjs";
+} from "../../adapters/shared/resolve-slot-ports-core.mjs";
 export {
   formatKvLines,
   inferSlotSuffix,
@@ -18,5 +19,6 @@ export {
   resolveFarmslotPortsByRepo,
   resolveMobileRuntimeContext,
   resolveMobileRuntimePorts,
-  resolveMobileSlotDefaults
+  resolveMobileSlotDefaults,
+  resolveSlotPortsByRepo
 };

package/dist/adapters/slot-ports.js

@@ -5,10 +5,10 @@ import { readRuntimeContextField, resolveRuntimeContextPath } from "../harness.j
 import { recipeRuntimeDir } from "../paths.js";
 import {
   resolveDefaultExtensionPorts,
-  resolveFarmslotPortsByRepo,
+  resolveSlotPortsByRepo,
   resolveMobileRuntimeContext,
   resolveMobileSlotDefaults
-} from "./resolve-farmslot-ports.js";
+} from "./resolve-slot-ports.js";
 function applyKVLines(output, overwrite) {
   for (const line of output.split("\n")) {
     const m = /^([A-Z_]+)=(.+)$/u.exec(line.trim());
@@ -41,7 +41,7 @@ function applyKVLines(output, overwrite) {
 function resolveMobileSlotPorts(target) {
   const ctxOut = resolveMobileRuntimeContext(target);
   if (ctxOut?.trim()) applyKVLines(ctxOut, true);
-  const poolOut = resolveFarmslotPortsByRepo(target);
+  const poolOut = resolveSlotPortsByRepo(target);
   if (poolOut?.trim()) applyKVLines(poolOut, false);
   const defOut = resolveMobileSlotDefaults(target);
   if (defOut?.trim()) applyKVLines(defOut, false);
@@ -58,14 +58,12 @@ function resolveExtensionSlotPorts(target) {
     process.env["WATCHER_PORT"] = dev;
     process.env["RECIPE_WATCHER_PORT"] = dev;
   }
-  if (process.env["CDP_PORT"]) return;
-  const poolOut = resolveFarmslotPortsByRepo(target);
-  if (poolOut?.trim()) {
-    applyKVLines(poolOut, true);
-    return;
+  if (!process.env["CDP_PORT"] || !process.env["WATCHER_PORT"]) {
+    const poolOut = resolveSlotPortsByRepo(target);
+    if (poolOut?.trim()) applyKVLines(poolOut, false);
+    const defOut = resolveDefaultExtensionPorts(target);
+    if (defOut?.trim()) applyKVLines(defOut, false);
   }
-  const defOut = resolveDefaultExtensionPorts(target);
-  if (defOut?.trim()) applyKVLines(defOut, false);
 }
 function stopExtensionWatcher(target) {
   const runtimeAbs = path.join(target, recipeRuntimeDir());

package/dist/cli-commands.js

@@ -15,7 +15,7 @@ const SPEC = {
     { name: "debug", aliases: ["devtools", "inspect"], desc: "Open DevTools UI", flags: ["--json", "--no-open"] },
     { name: "actions", desc: "List runnable recipe actions", flags: ["--json"] },
     { name: "doctor", desc: "Check harness/orchestration health", flags: ["--json", "--target", "--adapter", "--runtime-dir"] },
-    { name: "run", desc: "Execute a proof recipe", args: ["recipe.json"] },
+    { name: "run", desc: "Execute a proof recipe", args: ["recipe.json"], flags: ["--list"] },
     { name: "interactive", aliases: ["menu"], desc: "Interactive command menu" },
     { name: "prepare", desc: "Install harness (+ optional validate)", flags: ["--target", "--runtime-dir", "--json"] },
     { name: "runtime-status", desc: "Structured runtime status JSON", flags: ["--json", "--target", "--cdp-port", "--runtime-dir"] }

package/dist/commands/call.js

@@ -14,6 +14,7 @@ import {
   runtimeOptionsFromCli,
   usageError
 } from "./parse-args.js";
+import { handleListExecutables } from "./list-executables.js";
 import {
   emitHealViolation,
   executeWithHealBounds,
@@ -24,6 +25,10 @@ import {
   validateRecipeAdapterAware
 } from "./run-engine.js";
 async function handleCall(argv) {
+  if (argv.includes("--list")) {
+    const { options: options2 } = parseArgs(argv, "call");
+    return handleListExecutables("call", options2);
+  }
   if (argv.length > 0 && argv[0].startsWith("--")) {
     const message = "call requires <action> first: mm-harness call <action> [--arg k=v ...] [flags]";
     console.error(message);

package/dist/commands/doctor.js

@@ -44,7 +44,8 @@ async function handleDoctor({ options }) {
   } catch {
   }
   const orphanMetros = adapter === "mobile" ? detectOrphanMetros(target, process.env.WATCHER_PORT) : [];
-  if (json) console.log(JSON.stringify({ ...result, runtime, orphanMetros }, null, 2));
+  const capture = captureHelperHealth();
+  if (json) console.log(JSON.stringify({ ...result, runtime, orphanMetros, capture }, null, 2));
   else {
     const out = (style, text) => color(style, text, { stream: process.stdout });
     const stateStyle = (value, good) => value === good ? "ok" : "warn";
@@ -67,9 +68,28 @@ async function handleDoctor({ options }) {
       );
       console.log(`  ${out("dim", "Next: mm-harness stop   # reaps every bundler this checkout leaked")}`);
     }
+    if (capture) {
+      console.log(`${out("label", "capture:")} ${out(capture.status === "pass" ? "ok" : "warn", capture.status)} ${out("dim", "(capture-helper: screenshots + --record video)")}`);
+      if (capture.status !== "pass") {
+        if (capture.failing.length > 0) console.log(`  ${out("dim", `failing: ${capture.failing.join(", ")}`)}`);
+        console.log(`  ${out("dim", "Next: grant Screen Recording (System Settings \u2192 Privacy & Security \u2192 Screen Recording), or run: capture-helper doctor --open-permissions")}`);
+      }
+    }
   }
   return result.status === "pass" ? 0 : 1;
 }
+function captureHelperHealth() {
+  if (process.platform !== "darwin") return null;
+  const bin = process.env.CAPTURE_HELPER_PATH || "capture-helper";
+  try {
+    const out = execFileSync(bin, ["doctor", "--json"], { encoding: "utf8", timeout: 1e4, stdio: ["ignore", "pipe", "ignore"] });
+    const parsed = JSON.parse(out);
+    const failing = (parsed.checks ?? []).filter((c) => c.required === true && c.ok === false).map((c) => c.name ?? c.id ?? "check");
+    return { status: parsed.ok === true && failing.length === 0 ? "pass" : "warn", failing };
+  } catch {
+    return null;
+  }
+}
 function detectOrphanMetros(target, livePort) {
   try {
     const script = path.join(runnerDir, "adapters/shared/reap-checkout-metros.sh");

package/dist/commands/fixtures.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { runnerDir, walletFixturePath } from "../paths.js";
 import { getAdapterSurface } from "../adapters/surface.js";
-import { ADAPTER_DETECT_NEXT, EXIT, flag, parseFlags, resolveAdapter, spawnScript, str, targetOf, usageOut } from "./shared.js";
+import { ADAPTER_DETECT_NEXT, EXIT, flag, parseFlags, resolveAdapter, spawnScript, spawnScriptStreaming, str, targetOf, usageOut } from "./shared.js";
 const FIXTURES_BOOLEANS = /* @__PURE__ */ new Set(["json"]);
 const RECOVERABLE_SETUP_WALLET_PATTERNS = [
   "CDP not reachable",
@@ -49,13 +49,15 @@ async function handleFixtures(argv, deps) {
     return exitCode;
   }
   const fixturePath = path.resolve(str(options, "fixture") ?? process.env.RECIPE_WALLET_FIXTURE ?? canonicalFixture);
+  process.stderr.write(`\u2192 fixtures set ${adapter} \u2014 connecting bridge + applying wallet fixture (can take ~30s)\u2026
+`);
   let status;
   if (adapter === "mobile") {
     const setupWalletSh = path.join(runnerDir, "adapters/mobile/bridge-runtime/setup-wallet.sh");
     const previousAppRoot = process.env.APP_ROOT;
     process.env.APP_ROOT = target;
     try {
-      let result = spawnScript(setupWalletSh, ["--fixture", fixturePath], target, json);
+      let result = await spawnScriptStreaming(setupWalletSh, ["--fixture", fixturePath], target);
       if (result.status !== 0 && isRecoverableSetupWalletFailure(result.output) && !process.env["RECIPE_SETUP_WALLET_RETRIED"]) {
         process.env["RECIPE_SETUP_WALLET_RETRIED"] = "1";
         if (!json) process.stderr.write("  setup-wallet: recoverable failure \u2014 restarting Metro and retrying\n  Next: wait for relaunch, then wallet setup will retry automatically\n");
@@ -63,7 +65,7 @@ async function handleFixtures(argv, deps) {
         const platform = str(options, "platform") ?? process.env["MOBILE_PLATFORM"] ?? "ios";
         const relaunchResult = await prepareMobile(target, { platform, json, preflightMode: "auto", clearMetro: true });
         if (relaunchResult.status === 0) {
-          result = spawnScript(setupWalletSh, ["--fixture", fixturePath], target, json);
+          result = await spawnScriptStreaming(setupWalletSh, ["--fixture", fixturePath], target);
         }
       }
       status = result.status === 0 ? "pass" : "fail";