@deeeed/metamask-harness 0.6.3 → 0.7.1

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/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

@@ -11,11 +11,11 @@ const SPEC = {
     { name: "ports", desc: "Slot ports and runtime paths", flags: ["--json"] },
     { name: "up", desc: "Decide + run minimum work to reach ready", flags: ["--json", "--dry-run"] },
     { name: "sync", desc: "Refresh harness + canonicalize wallet fixture", flags: ["--json"] },
-    { name: "logs", aliases: ["tail"], desc: "Compact build events or full log", flags: ["--full", "-f"] },
+    { name: "logs", aliases: ["tail"], desc: "Compact build events or full log", flags: ["--full", "-f", "--window", "--events", "--source", "--json"] },
     { 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: "doctor", desc: "Check harness/orchestration health", flags: ["--json", "--target", "--adapter", "--runtime-dir", "--expect-live", "--cdp-port"] },
+    { 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

@@ -7,7 +7,7 @@ import { assertAdapter, runnerDir } from "../paths.js";
 import { getAdapterSurface } from "../adapters/surface.js";
 import { loadActionManifest, validateManifest } from "../manifest.js";
 import { ensureOverlay, newHealState, recipeRunning } from "../heal-bounds.js";
-import { ADAPTER_DETECT_NEXT, usageOut } from "./shared.js";
+import { ADAPTER_DETECT_NEXT, EXIT, usageOut } from "./shared.js";
 import {
   actionManifestPathOption,
   applyRuntimeDirOption,
@@ -15,10 +15,24 @@ import {
   optionString,
   targetPath
 } from "./parse-args.js";
+function applyDoctorRuntimePorts(options) {
+  const cdpPort = optionString(options, "cdpPort");
+  if (cdpPort) {
+    process.env.CDP_PORT = cdpPort;
+    process.env.RECIPE_CDP_PORT = cdpPort;
+  }
+  const watcherPort = optionString(options, "watcherPort") ?? optionString(options, "port") ?? optionString(options, "metroPort");
+  if (watcherPort) {
+    process.env.WATCHER_PORT = watcherPort;
+    process.env.METRO_PORT = watcherPort;
+    process.env.RECIPE_WATCHER_PORT = watcherPort;
+  }
+}
 async function handleDoctor({ options }) {
   applyRuntimeDirOption(options);
   const target = targetPath(options);
   const json = optionFlag(options, "json");
+  const expectLive = optionFlag(options, "expectLive");
   const explicitAdapter = optionString(options, "adapter") ?? optionString(options, "platform");
   const adapter = explicitAdapter ?? detectAdapter(target);
   if (!adapter) {
@@ -40,11 +54,14 @@ async function handleDoctor({ options }) {
   try {
     const surface = getAdapterSurface(adapter);
     surface.resolveSlotPorts(target);
+    applyDoctorRuntimePorts(options);
     runtime = await surface.runtimeStatus(target);
   } 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 (expectLive) return emitExpectLive(adapter, target, runtime, result, orphanMetros, capture, json);
+  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 +84,45 @@ 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 emitExpectLive(adapter, target, runtime, result, orphanMetros, capture, json) {
+  const live = runtime?.decision === "ready";
+  if (json) {
+    console.log(JSON.stringify({ ...result, runtime, orphanMetros, capture }, null, 2));
+    return live ? EXIT.ok : EXIT.runtime;
+  }
+  const out = (style, text) => color(style, text, { stream: process.stdout });
+  if (live) {
+    console.log(`${out("ok", "live")} ${out("bold", adapter)} runtime ready`);
+    return EXIT.ok;
+  }
+  const detail = runtime ? `${runtime.decision}${runtime.reasonCode ? ` (${runtime.reasonCode})` : ""}` : "runtime probe unavailable";
+  console.error(`${out("err", "not-live")} ${out("bold", adapter)} ${detail} ${out("dim", target)}`);
+  for (const reason of runtime?.reasons ?? []) console.error(`  ${out("dim", reason)}`);
+  console.error(`  Next: ${getAdapterSurface(adapter).hints.relaunch}`);
+  return EXIT.runtime;
+}
+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";

package/dist/commands/launch/extension.js

@@ -2,10 +2,26 @@ import { execFileSync } from "node:child_process";
 import http from "node:http";
 import fs from "node:fs";
 import path from "node:path";
+import { depsCheck } from "@farmslot/recipe-harness/runtime/deps-readiness";
 import { recipeHarnessPath, recipeRuntimeDir, runnerDir } from "../../paths.js";
 import { isExtensionDistStale } from "../../adapters/extension/runtime-decision.js";
 import { stopExtensionWatcher } from "../../adapters/slot-ports.js";
 import { spawnScriptStreaming } from "../shared.js";
+function extensionDepsBlock(target) {
+  if (!fs.existsSync(path.join(target, "package.json"))) return null;
+  const deps = depsCheck(target);
+  const userAction = "yarn install --immutable   # then re-run: mm-harness launch";
+  if (deps.status === "missing") {
+    return { message: "extension dependencies are not installed (no yarn install-state markers).", userAction };
+  }
+  if (deps.status === "stale") {
+    return {
+      message: "extension dependencies are stale (package.json/yarn.lock changed since the last install) \u2014 webpack would crash mid-build.",
+      userAction
+    };
+  }
+  return null;
+}
 async function launchExtension(target, tier, wantWatch) {
   if (wantWatch) {
     const startWatchSh = path.join(runnerDir, "adapters/extension/start-watch.sh");
@@ -90,7 +106,9 @@ async function extensionRebuild(target) {
   return result;
 }
 export {
+  extensionDepsBlock,
   extensionReattach,
   extensionRebuild,
+  extensionRuntimeReusable,
   launchExtension
 };

package/dist/commands/launch/index.js

@@ -23,7 +23,7 @@ import {
   newHealState,
   parseHeal
 } from "../../heal-bounds.js";
-import { launchExtension } from "./extension.js";
+import { extensionDepsBlock, extensionRuntimeReusable, launchExtension } from "./extension.js";
 import { launchMobile } from "./mobile.js";
 const LAUNCH_BOOLEANS = /* @__PURE__ */ new Set([
   "build",
@@ -32,9 +32,7 @@ const LAUNCH_BOOLEANS = /* @__PURE__ */ new Set([
   "sidepanel",
   "fullscreen",
   "runway",
-  "json",
-  "jsonStream",
-  "yes"
+  "json"
 ]);
 async function handleLaunch(argv) {
   const { positional, options } = parseFlags(argv, LAUNCH_BOOLEANS);
@@ -111,6 +109,15 @@ async function handleLaunch(argv) {
     if (json) liveArgs.push("--json");
     return handleHarness(liveArgs);
   }
+  if (adapter === "extension") {
+    const willBuild = wantWatch || tier === "build" || !await extensionRuntimeReusable(target);
+    if (willBuild) {
+      const depsBlock = extensionDepsBlock(target);
+      if (depsBlock) {
+        return usageOut(json, "launch", depsBlock.message, depsBlock.userAction);
+      }
+    }
+  }
   let attempt = await executeComposition(adapter, mobileTarget, tier, wantWatch, target, json);
   if (attempt.status === 0) {
     return finishLaunch(json, adapter, mobileTarget, tier, displayMode, target, state);

package/dist/commands/list-executables.js

@@ -0,0 +1,48 @@
+import { loadActionManifest } from "../manifest.js";
+import { importRecipeHarness, importRecipeProtocol } from "../paths.js";
+import { EXIT } from "./shared.js";
+import { optionFlag, optionString, resolveAdapter } from "./parse-args.js";
+import { resolveMetaMaskLibrarySources } from "./run-engine.js";
+const finalSegment = (name) => name.split(".").pop() ?? name;
+async function listFlowIds() {
+  try {
+    const sources = await resolveMetaMaskLibrarySources(void 0);
+    if (!sources || sources.length === 0) return [];
+    const harness = await importRecipeHarness();
+    const resolution = await harness.loadRecipeLibraries(sources);
+    return [...resolution.flows.keys()].sort();
+  } catch {
+    return [];
+  }
+}
+async function handleListExecutables(command, options) {
+  const json = optionFlag(options, "json");
+  const { adapter } = resolveAdapter(options);
+  const manifest = loadActionManifest(adapter, optionString(options, "actionManifest"));
+  const { getRecipeActionManifestActionNames } = await importRecipeProtocol();
+  const names = getRecipeActionManifestActionNames(manifest).slice().sort();
+  const shortCounts = /* @__PURE__ */ new Map();
+  for (const name of names) shortCounts.set(finalSegment(name), (shortCounts.get(finalSegment(name)) ?? 0) + 1);
+  const actions = names.map((name) => {
+    const short = finalSegment(name);
+    return { name, short: shortCounts.get(short) === 1 ? short : null };
+  });
+  const flows = await listFlowIds();
+  if (json) {
+    console.log(JSON.stringify({ schemaVersion: 1, command, action: "list", adapter, actions, flows }, null, 2));
+    return EXIT.ok;
+  }
+  console.log(`invocable for ${adapter}:`);
+  console.log(`  actions (mm-harness call <name> \u2014 short or full):`);
+  for (const entry of actions) {
+    console.log(entry.short ? `    ${entry.short}  (${entry.name})` : `    ${entry.name}  (full name only \u2014 ambiguous short)`);
+  }
+  if (flows.length > 0) {
+    console.log(`  flows (mm-harness run <flow>):`);
+    for (const flow of flows) console.log(`    ${flow}`);
+  }
+  return EXIT.ok;
+}
+export {
+  handleListExecutables
+};

package/dist/commands/logs.js

@@ -2,8 +2,8 @@ import fs from "node:fs";
 import path from "node:path";
 import { runnerDir } from "../paths.js";
 import { getAdapterSurface } from "../adapters/surface.js";
-import { ADAPTER_DETECT_NEXT, EXIT, flag, parseFlags, resolveAdapter, spawnInherit, str, targetOf, usageOut } from "./shared.js";
-const LOGS_BOOLEANS = /* @__PURE__ */ new Set(["full", "json"]);
+import { ADAPTER_DETECT_NEXT, EXIT, flag, parseFlags, resolveAdapter, spawnInherit, spawnScript, str, targetOf, usageOut } from "./shared.js";
+const LOGS_BOOLEANS = /* @__PURE__ */ new Set(["full", "json", "window"]);
 async function handleLogs(argv) {
   const { options } = parseFlags(argv, LOGS_BOOLEANS);
   const json = flag(options, "json");
@@ -43,6 +43,29 @@ async function handleLogs(argv) {
       surface.hints.launch
     );
   }
+  if (flag(options, "window")) {
+    surface.resolveSlotPorts(target);
+    const port = process.env.WATCHER_PORT ?? process.env.METRO_PORT ?? "default";
+    const windowName = adapter === "mobile" ? `metro-${port}` : `webpack-${port}`;
+    const devLog = logSources[0].path;
+    const leaf = path.join(runnerDir, "adapters/shared/open-log-window.sh");
+    const result = spawnScript(
+      leaf,
+      ["--window", windowName, "--log", devLog, "--runtime-dir", path.dirname(devLog)],
+      target,
+      json
+    );
+    if (json) {
+      console.log(
+        JSON.stringify(
+          { schemaVersion: 1, command: "logs", action: "window", adapter, window: windowName, logFile: devLog, exitCode: result.status === 0 ? EXIT.ok : EXIT.runtime },
+          null,
+          2
+        )
+      );
+    }
+    return result.status === 0 ? EXIT.ok : EXIT.runtime;
+  }
   if (json) {
     console.log(JSON.stringify({ schemaVersion: 1, command: "logs", adapter, source, logFile, exitCode: EXIT.ok }, null, 2));
     return EXIT.ok;

package/dist/commands/manifest.js

@@ -1,4 +1,5 @@
 import { loadActionManifest, validateManifest } from "../manifest.js";
+import { EXIT } from "./shared.js";
 import {
   actionManifestPathOption,
   isRecord,
@@ -19,9 +20,22 @@ async function handleActions({ options }) {
   const { adapter } = resolveAdapter(options);
   const manifest = loadActionManifest(adapter, optionString(options, "actionManifest"));
   await validateManifest(manifest);
+  const json = optionFlag(options, "json");
   const action = optionString(options, "action");
-  const actions = describeManifestActions(manifest, action);
-  if (optionFlag(options, "json")) {
+  const all = describeManifestActions(manifest);
+  const actions = action ? fuzzyResolveActions(all, action) : all;
+  if (action && actions.length === 0) {
+    const message = `no action matches "${action}" for the ${adapter} adapter.`;
+    const userAction = `mm-harness actions --adapter ${adapter}   # list the vocabulary`;
+    if (json) {
+      console.log(JSON.stringify({ schemaVersion: 1, command: "actions", adapter, action, error: { code: "ACTION_UNKNOWN", message, userAction } }, null, 2));
+    } else {
+      console.error(`\u2717 mm-harness actions: ${message}
+  Next: ${userAction}`);
+    }
+    return EXIT.usage;
+  }
+  if (json) {
     console.log(JSON.stringify({ adapter, actions }, null, 2));
   } else {
     for (const entry of actions) {
@@ -31,7 +45,15 @@ async function handleActions({ options }) {
   }
   return 0;
 }
-function describeManifestActions(manifest, filterAction) {
+function fuzzyResolveActions(entries, query) {
+  const exactFull = entries.filter((e) => e.name === query);
+  if (exactFull.length > 0) return exactFull;
+  const finalSegment = (name) => name.split(".").pop() ?? name;
+  const exactSegment = entries.filter((e) => finalSegment(e.name) === query);
+  if (exactSegment.length > 0) return exactSegment;
+  return entries.filter((e) => finalSegment(e.name).includes(query));
+}
+function describeManifestActions(manifest) {
   const manifestRecord = isRecord(manifest) ? manifest : {};
   const metadata = isRecord(manifestRecord.action_metadata) ? manifestRecord.action_metadata : {};
   const official = Array.isArray(manifestRecord.supported_official_actions) ? manifestRecord.supported_official_actions.filter((value) => typeof value === "string") : [];
@@ -45,12 +67,10 @@ function describeManifestActions(manifest, filterAction) {
     }
     return [];
   }) : [];
-  const entries = [
+  return [
     ...official.map((name) => describeManifestAction(name, "official", metadata[name])),
     ...custom.map((entry) => describeManifestAction(entry.name, "custom", entry.metadata))
-  ].filter((entry) => !filterAction || entry.name === filterAction);
-  if (filterAction && entries.length === 0) throw new Error(`Action not found in manifest: ${filterAction}`);
-  return entries;
+  ];
 }
 function describeManifestAction(name, kind, metadata) {
   const record = isRecord(metadata) ? metadata : {};

package/dist/commands/parse-args.js

@@ -23,10 +23,12 @@ function parseArgs(argv, command) {
     "startWatch",
     "record",
     "plan",
+    "list",
     "raw",
     "fix",
     "force",
     "resolveOnly",
+    "expectLive",
     "help"
   ]);
   for (let i = 0; i < argv.length; i += 1) {

package/dist/commands/run.js

@@ -3,13 +3,11 @@ import path from "node:path";
 import { walletFixturePath } from "../paths.js";
 import { EXIT } from "./shared.js";
 import {
-  adapterOption,
   optionFlag,
   optionString,
   requiredOption,
   resolveAdapter,
   runtimeOptionsFromCli,
-  targetPath,
   usageError
 } from "./parse-args.js";
 import {
@@ -21,13 +19,14 @@ import {
   runRecipe,
   validateRunRecipeStatic
 } from "./run-engine.js";
+import { handleListExecutables } from "./list-executables.js";
 async function handleRun({ positional, options }) {
+  if (optionFlag(options, "list")) return handleListExecutables("run", options);
   const targetRecipe = positional[0];
   if (!targetRecipe) throw usageError("run requires <recipe.json>.");
   if (optionFlag(options, "plan")) return handleRunPlan(targetRecipe, options);
-  const adapter = adapterOption(options);
+  const { adapter, target } = resolveAdapter(options);
   const json = optionFlag(options, "json");
-  const target = targetPath(options);
   const artifactsDir = requiredOption(options, "artifactsDir", "run requires --artifacts-dir <dir>.");
   const prepared = await prepareHeal(adapter, target, options, json);
   if (typeof prepared === "number") return prepared;

package/dist/live-adapter-contract.js

@@ -119,18 +119,39 @@ function runProcess(command, args, options) {
     });
   });
 }
-function commandFor(file) {
+function commandFor(file, projectRoot, platform) {
   if (file.endsWith(".sh")) return { command: "bash", args: [file] };
-  if (file.endsWith(".mjs") || file.endsWith(".js")) {
-    if (!importsSourceTypescript(file)) return { command: process.execPath, args: [file] };
+  const needsTsx = platform === "core" || importsSourceTypescript(file);
+  if (!needsTsx && (file.endsWith(".mjs") || file.endsWith(".js"))) {
+    return { command: process.execPath, args: [file] };
+  }
+  const tsxBin = resolveTsxBin(projectRoot);
+  if (!tsxBin) {
+    const where = projectRoot ?? "the checkout";
+    const error = new Error(
+      `this action runs TypeScript from the checkout but no tsx runtime was found.
+  Next: run 'yarn install' in ${where} (tsx is a dev dependency of the checkout); if package imports still fail, run 'yarn build' there`
+    );
+    error.exitCode = 2;
+    throw error;
   }
-  const localTsx = path.join(runnerDir, "node_modules/.bin/tsx");
-  const tsxBin = process.env.TSX_BIN || (existsSync(localTsx) ? localTsx : path.join(
-    resolveRequiredLocalProtocolRoot("TypeScript live adapter execution"),
-    "node_modules/.bin/tsx"
-  ));
   return { command: tsxBin, args: [file] };
 }
+function resolveTsxBin(projectRoot) {
+  if (process.env.TSX_BIN) return process.env.TSX_BIN;
+  const candidates = [];
+  if (projectRoot) candidates.push(path.join(projectRoot, "node_modules/.bin/tsx"));
+  candidates.push(path.join(runnerDir, "node_modules/.bin/tsx"));
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return candidate;
+  }
+  try {
+    const protocolTsx = path.join(resolveRequiredLocalProtocolRoot("TypeScript live adapter execution"), "node_modules/.bin/tsx");
+    if (existsSync(protocolTsx)) return protocolTsx;
+  } catch {
+  }
+  return null;
+}
 function importsSourceTypescript(file) {
   return importsSourceTypescriptFrom(file, /* @__PURE__ */ new Set());
 }
@@ -201,7 +222,7 @@ async function runLiveAdapterScript({ platform, action, node, context }) {
   };
   await writeFile(inputPath, `${JSON.stringify(input, null, 2)}
 `);
-  const command = commandFor(script);
+  const command = commandFor(script, context.projectRoot, platform);
   const platformEnv = await platformAdapterEnv(platform, context.projectRoot, tempDir);
   const result = await runProcess(command.command, [...command.args, inputPath], {
     cwd: context.projectRoot,