@deeeed/metamask-harness 0.16.0 → 0.17.1

package/dist/harness.js

@@ -4,13 +4,8 @@ import path from "node:path";
 import { resolveLeafInvoke, shellLeafMissing, missingShellLeafMessage } from "./leaf-invoke.js";
 import { resolveExtensionSlotPorts } from "./adapters/slot-ports.js";
 import { recipeHarnessPath, recipeRuntimeDir, runnerDir } from "./paths.js";
-import { prepareMobile } from "./adapters/mobile/prepare.js";
-const HARNESS_ACTIONS = ["install", "verify", "cleanup", "live"];
+const HARNESS_ACTIONS = ["install", "verify", "cleanup"];
 const ADAPTERS = ["mobile", "extension", "core"];
-function isValidAdapterAction(adapter, action) {
-  if (adapter === "core") return action === "install" || action === "verify" || action === "cleanup";
-  return true;
-}
 function harnessUsage() {
   console.error(`mm-harness \u2014 install and validate the MetaMask recipe runtime in a checkout.
 
@@ -50,6 +45,12 @@ function failureHint(adapter, action) {
   const helper = adapter === "mobile" ? "mm-harness launch ios   # or launch android" : "mm-harness launch";
   return `Read the error above for the specific cause. To (re)start the runtime, run: ${helper}`;
 }
+function successNext(adapter, action, target) {
+  const base = `--adapter ${adapter} --target ${shellQuote(target)}`;
+  if (action === "install") return `mm-harness verify ${base}`;
+  if (action === "cleanup") return `mm-harness install ${base}`;
+  return `mm-harness status --target ${shellQuote(target)} --json`;
+}
 function hasArg(args, needle) {
   return args.some((arg) => arg === needle || arg.startsWith(`${needle}=`));
 }
@@ -161,7 +162,7 @@ function readRuntimeContextField(contextPath, field) {
   if (node === void 0 || node === null || node === "") return void 0;
   return String(node);
 }
-function applyExtensionRuntimeEnv(target, action, args) {
+function applyExtensionRuntimeEnv(target, args) {
   const contextPath = resolveRuntimeContextPath(target);
   const contextExists = fs.existsSync(contextPath);
   if (contextExists) {
@@ -174,19 +175,6 @@ function applyExtensionRuntimeEnv(target, action, args) {
       const extensionId = readRuntimeContextField(contextPath, "extensionId");
       if (extensionId) process.env.RECIPE_HARNESS_EXTENSION_ID = extensionId;
     }
-    if (process.env.RECIPE_RUNTIME_START_APPROVED === void 0) {
-      const approved = readRuntimeContextField(contextPath, "runtimeStart.approved");
-      if (approved === "true" || approved === "True" || approved === "1") process.env.RECIPE_RUNTIME_START_APPROVED = "1";
-      else if (approved === "false" || approved === "False" || approved === "0") process.env.RECIPE_RUNTIME_START_APPROVED = "0";
-    }
-    if (!process.env.RECIPE_RUNTIME_START_CMD) {
-      const command = readRuntimeContextField(contextPath, "runtimeStart.command");
-      if (command) process.env.RECIPE_RUNTIME_START_CMD = command;
-    }
-    if (!process.env.RECIPE_RUNTIME_READY_URL) {
-      const readyUrl = readRuntimeContextField(contextPath, "runtimeStart.readyUrl");
-      if (readyUrl) process.env.RECIPE_RUNTIME_READY_URL = readyUrl;
-    }
   } else {
     delete process.env.RECIPE_RUNTIME_CONTEXT;
   }
@@ -200,11 +188,6 @@ function applyExtensionRuntimeEnv(target, action, args) {
       result = [...result, "--cdp-port", cdpPort];
     }
   }
-  if (action === "live" && !hasArg(result, "--prepare-cmd")) {
-    if (process.env.RECIPE_RUNTIME_START_APPROVED === "1" && process.env.RECIPE_RUNTIME_START_CMD) {
-      result = [...result, "--prepare-cmd", process.env.RECIPE_RUNTIME_START_CMD];
-    }
-  }
   return result;
 }
 function resolveEntry(base, candidates, mode) {
@@ -281,81 +264,6 @@ Next: mm-harness install --platform core --target ${target}`
   );
   return { command, prefixArgs: [] };
 }
-async function handleMobileLive(target, forwardArgs, json, autoDetected) {
-  const platform = argValue(forwardArgs, "--platform") ?? "ios";
-  const watcherPortStr = argValue(forwardArgs, "--watcher-port") ?? process.env.WATCHER_PORT;
-  const watcherPort = watcherPortStr ? parseInt(watcherPortStr, 10) : void 0;
-  const start = Date.now();
-  if (!json) {
-    const detected = autoDetected ? ", auto-detected" : "";
-    console.error(`\u2192 live (mobile${detected}) \u2014 target: ${target}`);
-  }
-  const prepResult = await prepareMobile(target, { platform, json, watcherPort });
-  if (prepResult.status !== 0) {
-    const elapsed2 = ((Date.now() - start) / 1e3).toFixed(1);
-    if (json) {
-      console.log(
-        harnessSummary("live", "mobile", target, "fail", prepResult.status, autoDetected, {
-          code: "MOBILE_PREPARE_FAILED",
-          message: `mobile prepare failed (exit ${prepResult.status})`,
-          userAction: failureHint("mobile", "live")
-        })
-      );
-    } else {
-      console.error(
-        `\u2717 live mobile failed (exit ${prepResult.status}, ${elapsed2}s)
-  ${failureHint("mobile", "live")}`
-      );
-    }
-    return prepResult.status;
-  }
-  const installedVerify = path.join(recipeHarnessPath(target, "mobile"), "scripts", "verify.sh");
-  const verifySh = fs.existsSync(installedVerify) ? installedVerify : resolveEntry(runnerDir, ["adapters/mobile/verify.sh", "scripts/mobile/verify.sh"], "file");
-  const verifyArgs = hasArg(forwardArgs, "--no-auto-start") ? [...forwardArgs] : ["--no-auto-start", ...forwardArgs];
-  if (shellLeafMissing(verifySh)) {
-    const message = missingShellLeafMessage(verifySh);
-    if (json) {
-      console.log(
-        harnessSummary("live", "mobile", target, "fail", 1, autoDetected, {
-          code: "HARNESS_SPAWN_FAILED",
-          message,
-          userAction: failureHint("mobile", "live")
-        })
-      );
-    } else {
-      console.error(`\u2717 ${message}`);
-    }
-    return 1;
-  }
-  const { bin: verifyBin, args: verifySpawnArgs } = resolveLeafInvoke(verifySh, verifyArgs);
-  const result = spawnSync(verifyBin, verifySpawnArgs, {
-    stdio: json ? ["inherit", 2, "inherit"] : "inherit",
-    env: process.env
-  });
-  const elapsed = ((Date.now() - start) / 1e3).toFixed(1);
-  const exitCode = result.status ?? 1;
-  if (json) {
-    console.log(
-      harnessSummary(
-        "live",
-        "mobile",
-        target,
-        exitCode === 0 ? "pass" : "fail",
-        exitCode,
-        autoDetected,
-        exitCode === 0 ? void 0 : { code: "MOBILE_VERIFY_FAILED", message: `mobile live verify failed (exit ${exitCode})`, userAction: failureHint("mobile", "live") }
-      )
-    );
-  } else if (exitCode === 0) {
-    console.error(`\u2713 live mobile passed (${elapsed}s)`);
-  } else {
-    console.error(
-      `\u2717 live mobile failed (exit ${exitCode}, ${elapsed}s)
-  ${failureHint("mobile", "live")}`
-    );
-  }
-  return exitCode;
-}
 async function handleHarness(argv) {
   const action = argv[0];
   if (!action || action === "-h" || action === "--help") {
@@ -387,32 +295,13 @@ async function handleHarness(argv) {
     }
     return 2;
   }
-  if (!isValidAdapterAction(adapter, harnessAction)) {
-    if (json) {
-      console.log(
-        harnessSummary(harnessAction, adapter, target, "fail", 2, parsedAdapter === void 0, {
-          code: "UNSUPPORTED_ACTION",
-          message: `${harnessAction} is not supported for ${adapter} (core supports install, verify, cleanup).`,
-          userAction: "run mm-harness doctor to see which actions are supported for this adapter"
-        })
-      );
-    } else {
-      console.error(
-        `\u2717 ${harnessAction} is not supported for ${adapter} (core supports install, verify, cleanup).`
-      );
-    }
-    return 2;
-  }
   const autoDetected = parsedAdapter === void 0;
   let forwardArgs = hasArg(forward, "--target") ? [...forward] : ["--target", target, ...forward];
   if (harnessAction === "install" && hasArg(forward, "--runway")) {
     return handleRunwayInstall(adapter, target, forward, json);
   }
-  if (adapter === "extension" && (harnessAction === "live" || harnessAction === "verify")) {
-    forwardArgs = applyExtensionRuntimeEnv(target, harnessAction, forwardArgs);
-  }
-  if (adapter === "mobile" && harnessAction === "live") {
-    return handleMobileLive(target, forwardArgs, json, autoDetected);
+  if (adapter === "extension" && harnessAction === "verify") {
+    forwardArgs = applyExtensionRuntimeEnv(target, forwardArgs);
   }
   const dispatch = resolveHarnessDispatch(adapter, harnessAction, target);
   if ("error" in dispatch) {
@@ -492,7 +381,8 @@ async function handleHarness(argv) {
       )
     );
   } else if (exitCode === 0) {
-    console.error(`\u2713 ${harnessAction} ${adapter} passed (${seconds}s)`);
+    console.error(`\u2713 ${harnessAction} ${adapter} passed (${seconds}s)
+  Next: ${successNext(adapter, harnessAction, target)}`);
   } else {
     console.error(`\u2717 ${harnessAction} ${adapter} failed (exit ${exitCode}, ${seconds}s)
   ${failureHint(adapter, harnessAction)}`);
@@ -522,8 +412,10 @@ async function handleRunwayInstall(adapter, target, forward, json) {
     resolveOnly: hasArg(forward, "--resolve-only"),
     rerunCommand
   });
+  const next = result.status === "pass" && adapter === "mobile" && result.resolveOnly !== true ? `mm-harness launch ${String(result.platform ?? "ios")} --adapter mobile --target ${shellQuote(target)}` : void 0;
+  const output = next ? { ...result, next } : result;
   if (json) {
-    console.log(JSON.stringify(result, null, 2));
+    console.log(JSON.stringify(output, null, 2));
   } else if (result.status === "pass") {
     const cache = typeof result.cache === "object" && result.cache ? result.cache : void 0;
     const simulator = typeof result.simulator === "object" && result.simulator ? result.simulator : void 0;
@@ -534,6 +426,7 @@ async function handleRunwayInstall(adapter, target, forward, json) {
       const action = result.skipped ? "already provisioned" : "installed Runway app";
       console.error(`\u2713 ${action} for ${adapter} ${result.platform ?? ""} simulator=${simulator?.name ?? "unknown"} cache=${cache?.status ?? "skip"}`);
     }
+    if (next) console.error(`  Next: ${next}`);
   } else {
     console.error(`\u2717 mm-harness install --runway: ${result.error?.message ?? "runway install failed"}
   Next: ${result.error?.userAction ?? rerunCommand}`);
@@ -576,9 +469,10 @@ function harnessSummary(action, adapter, target, status, exitCode, autoDetected,
     status,
     exitCode,
     // Error contract: every --json failure carries a stable machine code + human
-    // message (CLI-SPEC.md §5.1). userAction is included when present so callers
+    // message. userAction is included when present so callers
     // can surface the reachable escape without parsing the human message.
-    ...status === "fail" && error ? { error } : {}
+    ...status === "fail" && error ? { error } : {},
+    ...status === "pass" && adapter ? { next: successNext(adapter, action, target) } : {}
   });
 }
 export {

package/dist/json-stream.js

@@ -0,0 +1,57 @@
+class JsonStreamWriter {
+  enabled;
+  command;
+  completed = false;
+  writeLine;
+  constructor(command, enabled, output = process.stdout) {
+    this.command = command;
+    this.enabled = enabled;
+    const write = output.write.bind(output);
+    this.writeLine = (line) => {
+      write(`${line}
+`);
+    };
+  }
+  isolateStdout() {
+    if (!this.enabled) return () => void 0;
+    const original = process.stdout.write;
+    const redirect = ((chunk, encoding, callback) => process.stderr.write(chunk, encoding, callback));
+    process.stdout.write = redirect;
+    return () => {
+      if (process.stdout.write === redirect) process.stdout.write = original;
+    };
+  }
+  emit(event, fields = {}) {
+    if (!this.enabled || this.completed) return;
+    this.writeLine(JSON.stringify({
+      schemaVersion: 1,
+      command: this.command,
+      event,
+      ...fields,
+      ts: (/* @__PURE__ */ new Date()).toISOString()
+    }));
+  }
+  phase(phase, fields = {}) {
+    this.emit("phase", { phase, ...fields });
+  }
+  node(nodeId, action, status) {
+    this.emit("node", { nodeId, action, status });
+  }
+  mutation(mutation) {
+    this.emit("mutation", { mutation });
+  }
+  recovery(code) {
+    this.emit("recovery", { code });
+  }
+  error(error) {
+    this.emit("error", { error });
+  }
+  complete(status, exitCode, fields = {}) {
+    if (!this.enabled || this.completed) return;
+    this.emit("complete", { status, exitCode, ...fields });
+    this.completed = true;
+  }
+}
+export {
+  JsonStreamWriter
+};

package/dist/live-adapter-contract.js

@@ -46,29 +46,16 @@ function candidatePaths(platform, action) {
       }
       pushDomainDispatcherFiles(files, root, platform, family);
     }
-    for (const candidateStem of stems) {
-      pushFlatCandidateFiles(files, root, platform, candidateStem);
-    }
   }
   return files;
 }
 function pushCandidateFiles(files, root, platform, family, stem) {
-  for (const extension of ["mjs", "js", "sh"]) {
-    files.push(path.join(root, platform, family, `${stem}.${extension}`));
-    files.push(path.join(root, "shared", family, `${stem}.${extension}`));
-  }
+  files.push(path.join(root, platform, family, `${stem}.mjs`));
+  files.push(path.join(root, "shared", family, `${stem}.mjs`));
 }
 function pushDomainDispatcherFiles(files, root, platform, family) {
-  for (const extension of ["mjs", "js", "sh"]) {
-    files.push(path.join(root, platform, family, `${family}.${extension}`));
-    files.push(path.join(root, "shared", family, `${family}.${extension}`));
-  }
-}
-function pushFlatCandidateFiles(files, root, platform, stem) {
-  for (const extension of ["mjs", "js", "sh"]) {
-    files.push(path.join(root, platform, `${stem}.${extension}`));
-    files.push(path.join(root, "shared", `${stem}.${extension}`));
-  }
+  files.push(path.join(root, platform, family, `${family}.mjs`));
+  files.push(path.join(root, "shared", family, `${family}.mjs`));
 }
 async function firstExecutablePath(paths) {
   for (const file of paths) {
@@ -120,9 +107,8 @@ function runProcess(command, args, options) {
   });
 }
 function commandFor(file, projectRoot, platform) {
-  if (file.endsWith(".sh")) return { command: "bash", args: [file] };
   const needsTsx = platform === "core" || importsSourceTypescript(file);
-  if (!needsTsx && (file.endsWith(".mjs") || file.endsWith(".js"))) {
+  if (!needsTsx) {
     return { command: process.execPath, args: [file] };
   }
   const tsxBin = resolveTsxBin(projectRoot);
@@ -165,7 +151,7 @@ function importsSourceTypescriptFrom(file, visited) {
     const specifier = match[1] ?? "";
     if (specifier.endsWith(".ts")) return true;
     if (!specifier.startsWith(".")) continue;
-    if (!specifier.endsWith(".mjs") && !specifier.endsWith(".js")) continue;
+    if (!specifier.endsWith(".mjs")) continue;
     if (importsSourceTypescriptFrom(path.resolve(path.dirname(absolute), specifier), visited)) {
       return true;
     }

package/dist/mm-harness-cli.js

@@ -4,10 +4,17 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
 import { color } from "./cli-color.js";
+import { withCommandJournal } from "./command-journal.js";
+import { JsonStreamWriter } from "./json-stream.js";
 import { handleUpdate, maybeNudge } from "./commands/update.js";
 import { handleCallHelp } from "./commands/call.js";
 import { getAdapterSurface } from "./adapters/surface.js";
 import { detectAdapter } from "./harness.js";
+import {
+  PUBLIC_COMMAND_CONTRACTS,
+  publicCommandNames,
+  validatePublicInvocation
+} from "./command-contract.js";
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 globalThis.__MM_HARNESS_WRAPPER__ = true;
 const { main: recipeMain } = await import("./cli.js");
@@ -71,10 +78,11 @@ Example:
     name: "actions",
     summary: "List the action vocabulary + field schemas (--raw dumps the raw action registry JSON).",
     example: "mm-harness actions --adapter mobile",
-    helpText: `mm-harness actions [flags]
+    helpText: `mm-harness actions [query] [flags]
 
   List the action vocabulary + field schemas for the checkout adapter.
 
+  query                              Search names, categories, fields, and descriptions (typo-tolerant)
   --action <name>                    Describe one action; fuzzy-resolves like call (short or full name)
   --categories                       List compact action categories and counts
   --category <name>                  List only one category (for example ui, wallet, or perps)
@@ -85,6 +93,7 @@ Example:
 
 Example:
   mm-harness actions --adapter mobile
+  mm-harness actions positions --adapter mobile
   mm-harness actions --adapter mobile --categories --json
   mm-harness actions --adapter mobile --category ui --json
   mm-harness actions --adapter mobile --action assert_orders
@@ -176,12 +185,29 @@ Example:
   --library <name=path>              Add/override a recipe-library source (repeatable)
   --heal <off|infra-only|auto>       Healing policy (default: infra-only); auto-ensures the overlay
   --json                             Machine-readable output
+  --json-stream                      Line-flushed JSONL progress + terminal event
   --record-video=full-run            Record a video of the run
 
 Example:
   mm-harness run recipe.json --plan --adapter mobile
   mm-harness run recipe.json --adapter extension --artifacts-dir ./out`
   },
+  {
+    name: "last",
+    summary: "Show the last significant command, verdict, timestamps, and evidence paths for this checkout.",
+    example: "mm-harness last --json",
+    helpText: `mm-harness last [flags]
+
+  Read the atomic per-checkout resumability journal. Discovery commands do not
+  replace it, and an interrupted process remains recorded as verdict=running.
+
+  --target <path>                    Checkout path (default: cwd)
+  --runtime-dir <dir>                Runtime dir containing last-command.json
+  --json                             Machine-readable envelope
+
+Example:
+  mm-harness last --json`
+  },
   {
     name: "doctor",
     summary: "Readiness check for a checkout \u2014 no app launch. --fix repairs the overlay/runtime without launching.",
@@ -379,6 +405,7 @@ Example:
   --adapter <mobile|extension>       Target adapter (auto-detected inside a checkout)
   --target <path>                    Checkout path (default: cwd)
   --json                             Machine-readable summary (recovered[] / mutations[] / phase)
+  --json-stream                      Line-flushed JSONL progress + terminal event
 
 Example:
   mm-harness launch ios
@@ -397,8 +424,8 @@ Example:
   --full                             Raw log tail (default = compact) (env: RECIPE_LOG_UI)
   --window                           (Re)open the read-only tmux tail window for the resolved dev-server port (leaves the process untouched)
   --events <n>                       Compact event count (default 10) (env: RECIPE_LOG_EVENTS)
-  --source <label>                   Log source per adapter \u2014 mobile: metro|app (default metro);
-                                     extension: webpack|watcher|rebuild|app (default webpack).
+  --source <label>                   Log source per adapter \u2014 mobile: metro|app;
+                                     extension: extension|dapp|webpack|watcher|rebuild.
                                      Core is headless (teaching error).
   --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
   --target <path>                    Checkout path (default: cwd)
@@ -477,6 +504,7 @@ Example:
   --cdp-port <port>                  finalize: CDP port of the running extension
   --extension-dir <path>             finalize: loaded extension dist (e.g. dist/chrome)
   --extension-id-file <path>         finalize: optional file to read/write the resolved extension id
+  --action-manifest <path>           Extension set: override the wallet action manifest
   --adapter <mobile|extension>       Target adapter (auto-detected inside a checkout)
   --target <path>                    Checkout path (default: cwd)
   --device <udid|serial|name>        Mobile only: target this device for sync/set
@@ -491,21 +519,28 @@ Example:
   mm-harness fixtures finalize --fixture wallet-fixture.json --state fixture-state.json --cdp-port 6661 --extension-dir dist/chrome`
   }
 ];
-const RETIRED = [
-  {
-    name: "live",
-    message: `mm-harness live is retired (exit 2).
-
-Replacement: mm-harness launch --verify (install overlay \u2192 launch \u2192 CDP/bridge poll \u2192 smoke verify).`
-  },
-  {
-    name: "manifest",
-    message: `mm-harness manifest is retired (exit 2).
-
-Replacement: mm-harness actions --raw   (works now \u2014 dumps the raw action registry JSON,
-identical to the old \`manifest --json\`). Manifest validation moved into doctor / run --plan.`
+const PUBLIC_COMMAND_EXAMPLES = Object.fromEntries(
+  REAL.map((command) => [command.name, command.example])
+);
+function assertPublicContractMatchesSurface() {
+  const registered = REAL.map((command) => command.name).sort();
+  const contracted = publicCommandNames().sort();
+  if (registered.join("\n") !== contracted.join("\n")) {
+    throw new Error(
+      `public command contract drift: registered=[${registered.join(", ")}], contracted=[${contracted.join(", ")}]`
+    );
   }
-];
+  for (const command of REAL) {
+    const registeredAliases = [...command.aliases ?? []].sort();
+    const contractedAliases = [...PUBLIC_COMMAND_CONTRACTS[command.name]?.aliases ?? []].sort();
+    if (registeredAliases.join("\n") !== contractedAliases.join("\n")) {
+      throw new Error(
+        `public command alias contract drift for ${command.name}: registered=[${registeredAliases.join(", ")}], contracted=[${contractedAliases.join(", ")}]`
+      );
+    }
+  }
+}
+assertPublicContractMatchesSurface();
 const HELP_GROUPS = [
   {
     title: "DAILY LOOP",
@@ -520,7 +555,7 @@ const HELP_GROUPS = [
   {
     title: "PROVE",
     blurb: "run recipes and inspect readiness",
-    commands: ["run", "doctor", "check", "checklist", "recipe-quality"]
+    commands: ["run", "last", "doctor", "check", "checklist", "recipe-quality"]
   },
   {
     title: "RUNTIME OVERLAY",
@@ -608,7 +643,7 @@ function groupedHelp() {
   lines.push("DEV/PROD \u2014 the global npm install is prod; set MM_HARNESS_BIN to a dev checkout to override:");
   lines.push("  MM_HARNESS_BIN=/path/to/checkout/bin/mm-harness   # unset = the installed/global bin");
   lines.push("");
-  lines.push("See docs/MENTAL-MODEL.md (overview) and docs/CLI-SPEC.md (full contract).");
+  lines.push("See README.md for the workflow and docs/CHEATSHEET.md for examples.");
   return `${lines.join("\n")}
 `;
 }
@@ -620,11 +655,6 @@ async function delegate(argv) {
     return error !== null && typeof error === "object" && "exitCode" in error && typeof error.exitCode === "number" ? error.exitCode : 1;
   }
 }
-function translateActionsRaw(argv) {
-  const rest = argv.slice(1).filter((arg) => arg !== "--raw");
-  const withJson = rest.includes("--json") ? rest : [...rest, "--json"];
-  return ["manifest", ...withJson];
-}
 const pkgVersion = (() => {
   try {
     return JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8")).version ?? "unknown";
@@ -642,8 +672,7 @@ for (const command of REAL) {
     if (command.name === "update") {
       process.exit(await handleUpdate(rawArgv.slice(1)));
     }
-    const argv = command.name === "actions" && rawArgv.includes("--raw") ? translateActionsRaw(rawArgv) : rawArgv;
-    process.exit(await delegate(argv));
+    process.exit(await withCommandJournal(command.name, rawArgv, () => delegate(rawArgv)));
   });
 }
 const HIDDEN = [
@@ -665,21 +694,6 @@ program.command("completions").description("Install/print bundled shell tab-comp
   const result = spawnSync("bash", [script, ...rawArgv.slice(1)], { stdio: "inherit" });
   process.exit(result.status ?? 1);
 });
-for (const retired of RETIRED) {
-  program.command(retired.name).description(`${retired.name} is retired (see teaching error)`).allowUnknownOption().helpOption(false).argument("[args...]").action(async () => {
-    if (retired.name === "live") {
-      const adapterIdx = rawArgv.indexOf("--adapter");
-      const aliasIdx = rawArgv.indexOf("-a");
-      const adapterVal = adapterIdx !== -1 ? rawArgv[adapterIdx + 1] : aliasIdx !== -1 ? rawArgv[aliasIdx + 1] : void 0;
-      if (adapterVal === "mobile" || adapterVal === "android") {
-        process.exit(await delegate(rawArgv));
-        return;
-      }
-    }
-    console.error(retired.message);
-    process.exit(2);
-  });
-}
 const NUDGE_SKIP = ["update", "completions", "completion-candidates"];
 if (rawArgv.length > 0 && !NUDGE_SKIP.includes(rawArgv[0])) {
   setImmediate(() => void maybeNudge());
@@ -696,10 +710,66 @@ function isCallActionHelp(argv) {
   const scope = divider === -1 ? argv : argv.slice(0, divider);
   return scope.includes("--help") || scope.includes("-h");
 }
+function jsonRequestedBeforePassthrough(argv) {
+  const divider = argv.indexOf("--");
+  const scope = divider === -1 ? argv : argv.slice(0, divider);
+  return scope.some((argument) => argument === "--json" || argument.startsWith("--json="));
+}
+function jsonStreamRequestedBeforePassthrough(argv) {
+  const divider = argv.indexOf("--");
+  const scope = divider === -1 ? argv : argv.slice(0, divider);
+  return scope.includes("--json-stream");
+}
+function emitUsageError(error, json, jsonStream) {
+  if (jsonStream) {
+    const stream = new JsonStreamWriter(error.command, true);
+    stream.error({ code: error.code, message: error.message, userAction: error.userAction });
+    stream.complete("fail", 2);
+  } else if (json) {
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          schemaVersion: 1,
+          command: error.command,
+          status: "fail",
+          error: {
+            code: error.code,
+            message: error.message,
+            userAction: error.userAction
+          },
+          exitCode: 2
+        },
+        null,
+        2
+      )}
+`
+    );
+  } else {
+    const scope = error.command === "mm-harness" ? "" : ` ${error.command}`;
+    process.stderr.write(`\u2717 mm-harness${scope}: ${error.message}
+  Next: ${error.userAction}
+`);
+  }
+  process.exit(2);
+}
 if (rawArgv.length === 0) {
   process.stdout.write(groupedHelp());
   process.exit(0);
 }
+const preflightBypass = /* @__PURE__ */ new Set([
+  ...HIDDEN,
+  "completions"
+]);
+if (!preflightBypass.has(rawArgv[0] ?? "")) {
+  const usageError = validatePublicInvocation(rawArgv, PUBLIC_COMMAND_EXAMPLES);
+  if (usageError) {
+    emitUsageError(
+      usageError,
+      jsonRequestedBeforePassthrough(rawArgv),
+      jsonStreamRequestedBeforePassthrough(rawArgv)
+    );
+  }
+}
 if (hasPassthroughHelp(rawArgv)) {
   process.exit(await delegate(rawArgv));
 }

package/dist/paths.js

@@ -47,10 +47,7 @@ function recipeWatchLogCandidates() {
 }
 function resolveLocalProtocolRoot() {
   const candidates = [
-    // Orchestrator-neutral name is primary; FARMSLOT_ROOT stays a back-compat alias
-    // for one release (the installer injects METAMASK_RUNNER_PROTOCOL_ROOT).
     process.env.METAMASK_RUNNER_PROTOCOL_ROOT,
-    process.env.FARMSLOT_ROOT,
     readConfiguredProtocolRoot(),
     findProtocolRoot(runnerDir),
     findProtocolRoot(process.cwd())
@@ -62,7 +59,7 @@ function resolveRequiredLocalProtocolRoot(reason) {
   const root = resolveLocalProtocolRoot();
   if (!root) {
     throw new Error(
-      `${reason} requires a local protocol/runtime checkout. Set METAMASK_RUNNER_PROTOCOL_ROOT (or the legacy FARMSLOT_ROOT), or create .farmslot-root for this dev-only path.`
+      `${reason} requires a local protocol/runtime checkout. Set METAMASK_RUNNER_PROTOCOL_ROOT or create .farmslot-root for this dev-only path.`
     );
   }
   return root;
@@ -152,7 +149,7 @@ async function importProtocolPackage(packageName, localSourceEntry) {
   const root = resolveLocalProtocolRoot();
   if (!root) {
     throw new Error(
-      `${packageName} is not installed. Install @farmslot/* packages normally, or set FARMSLOT_ROOT/use npm run dev:link-farmslot while co-developing protocol packages locally.`
+      `${packageName} is not installed. Install @farmslot/* packages normally, or set METAMASK_RUNNER_PROTOCOL_ROOT/use npm run dev:link-farmslot while co-developing protocol packages locally.`
     );
   }
   return import(pathToFileURL(path.join(root, localSourceEntry)).href);