@deeeed/metamask-harness 0.17.5 → 0.19.0

package/dist/manifest.js

@@ -1,5 +1,10 @@
+import fs from "node:fs";
 import path from "node:path";
 import { manifestPath, readJson, importRecipeProtocol } from "./paths.js";
+import {
+  actionSourceIntegrity,
+  metaMaskActionExecutionCapabilities
+} from "./recipe-security.js";
 function loadMetaMaskMobileActionManifest() {
   return asActionManifest(readJson(manifestPath("mobile")));
 }
@@ -15,6 +20,130 @@ function loadActionManifest(adapter, overridePath) {
   if (adapter === "core") return loadMetaMaskCoreActionManifest();
   return loadMetaMaskExtensionActionManifest();
 }
+async function resolveActionManifest(adapter, overridePath, librarySources, taskActionRoot) {
+  if (overridePath) {
+    const manifestPath2 = path.resolve(overridePath);
+    const implementationRoot = path.resolve(
+      taskActionRoot ?? defaultImplementationRoot(manifestPath2)
+    );
+    const manifest = withMetaMaskExecutionCapabilities(loadActionManifest(adapter, manifestPath2));
+    await validateManifest(manifest);
+    const integrity = await actionSourceIntegrity(manifestPath2, "task", implementationRoot);
+    return {
+      manifest,
+      actionSources: describeManifestSources(manifest, {
+        name: "task",
+        tier: "task",
+        manifestPath: manifestPath2,
+        implementationRoot,
+        trust: "unknown",
+        ...integrity
+      })
+    };
+  }
+  const canonicalPath = manifestPath(adapter);
+  const sources = librarySources?.length ? librarySources : [{ name: "metamask", root: path.dirname(path.dirname(canonicalPath)) }];
+  const manifests = [];
+  for (const source of sources) {
+    const file = path.join(source.root, "manifests", `${adapter}.action-manifest.json`);
+    if (!fs.existsSync(file)) continue;
+    const manifest = asActionManifest(readJson(file));
+    await validateManifest(manifest);
+    manifests.push({ source, file, manifest });
+  }
+  if (!manifests.some((entry) => path.resolve(entry.file) === path.resolve(canonicalPath))) {
+    const manifest = loadActionManifest(adapter);
+    await validateManifest(manifest);
+    manifests.push({ source: { name: "metamask", root: path.dirname(path.dirname(canonicalPath)) }, file: canonicalPath, manifest });
+  }
+  const canonical = manifests.find((entry) => entry.source.name === "metamask") ?? manifests.at(-1);
+  if (!canonical) throw new Error(`No ${adapter} action manifest could be resolved.`);
+  const base = cloneManifest(canonical.manifest);
+  const official = new Set(stringArray(recordOf(base).supported_official_actions));
+  const custom = /* @__PURE__ */ new Map();
+  const customMetadata = /* @__PURE__ */ new Map();
+  const bindings = /* @__PURE__ */ new Map();
+  const canonicalImplementationRoot = path.join(canonical.source.root, "actions");
+  const canonicalIntegrity = await actionSourceIntegrity(
+    canonical.file,
+    "canonical",
+    canonicalImplementationRoot
+  );
+  const actionSources = describeManifestSources(base, {
+    name: "metamask",
+    tier: "canonical",
+    manifestPath: canonical.file,
+    implementationRoot: canonicalImplementationRoot,
+    trust: "trusted",
+    ...canonicalIntegrity
+  });
+  for (const entry of manifests) {
+    const sourceName = entry.source.name ?? path.basename(entry.source.root);
+    const tier = sourceName === "metamask" ? "canonical" : sourceName === "personal" ? "personal" : "team";
+    const implementationRoot = path.join(entry.source.root, "actions");
+    const integrity = await actionSourceIntegrity(entry.file, tier, implementationRoot);
+    const sourceInfo = {
+      name: sourceName,
+      tier,
+      manifestPath: entry.file,
+      implementationRoot,
+      trust: entry.source.provenance?.trust ?? (tier === "canonical" ? "trusted" : "unknown"),
+      ...integrity
+    };
+    const manifestRecord = recordOf(entry.manifest);
+    const metadata = recordOf(manifestRecord.action_metadata);
+    for (const action of customActions(manifestRecord.custom_actions)) {
+      if (official.has(action.name)) {
+        throw new Error(`Library action ${action.name} from ${entry.file} conflicts with an official action.`);
+      }
+      if (custom.has(action.name)) {
+        const existing = actionSources.get(action.name);
+        if (existing && existing.name !== sourceName) {
+          existing.shadows = [...existing.shadows ?? [], sourceName];
+        }
+        continue;
+      }
+      custom.set(action.name, action.value);
+      customMetadata.set(action.name, metadata[action.name]);
+      actionSources.set(action.name, { ...sourceInfo });
+    }
+    for (const binding of objectArray(manifestRecord.native_bindings)) {
+      const action = typeof binding.action === "string" ? binding.action : void 0;
+      if (action && !bindings.has(action)) bindings.set(action, binding);
+    }
+  }
+  const baseRecord = recordOf(base);
+  baseRecord.custom_actions = [...custom.values()];
+  const baseMetadata = recordOf(baseRecord.action_metadata);
+  for (const [name, metadata] of customMetadata) {
+    if (metadata !== void 0) baseMetadata[name] = metadata;
+  }
+  baseRecord.action_metadata = baseMetadata;
+  baseRecord.native_bindings = [...bindings.values()];
+  return { manifest: withMetaMaskExecutionCapabilities(base), actionSources };
+}
+function defaultImplementationRoot(selectedManifestPath) {
+  const manifestDirectory = path.dirname(selectedManifestPath);
+  return path.basename(manifestDirectory) === "manifests" ? path.join(path.dirname(manifestDirectory), "actions") : path.join(manifestDirectory, "actions");
+}
+function withMetaMaskExecutionCapabilities(manifest) {
+  const result = cloneManifest(manifest);
+  const record = recordOf(result);
+  if (!Array.isArray(record.custom_actions)) return result;
+  record.custom_actions = record.custom_actions.map((entry) => {
+    const name = typeof entry === "string" ? entry : recordOf(entry).name;
+    if (typeof name !== "string") return entry;
+    const capabilities = metaMaskActionExecutionCapabilities(name);
+    if (capabilities.length === 0) return entry;
+    const declaredValue = typeof entry === "string" ? void 0 : recordOf(entry).execution_capabilities;
+    const declared = Array.isArray(declaredValue) ? declaredValue.filter(
+      (capability) => typeof capability === "string"
+    ) : [];
+    const executionCapabilities = [.../* @__PURE__ */ new Set([...declared, ...capabilities])];
+    return typeof entry === "string" ? { name, execution_capabilities: executionCapabilities } : { ...recordOf(entry), execution_capabilities: executionCapabilities };
+  });
+  return result;
+}
 async function validateManifest(manifest) {
   const { validateRecipeActionManifestDocument } = await importRecipeProtocol();
   const result = validateRecipeActionManifestDocument(manifest);
@@ -28,10 +157,41 @@ async function validateManifest(manifest) {
 function asActionManifest(value) {
   return value;
 }
+function cloneManifest(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+function recordOf(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function stringArray(value) {
+  return Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
+}
+function objectArray(value) {
+  return Array.isArray(value) ? value.filter((entry) => Boolean(entry) && typeof entry === "object" && !Array.isArray(entry)) : [];
+}
+function customActions(value) {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((entry) => {
+    if (typeof entry === "string") return [{ name: entry, value: entry }];
+    const record = recordOf(entry);
+    return typeof record.name === "string" ? [{ name: record.name, value: entry }] : [];
+  });
+}
+function describeManifestSources(manifest, customSource) {
+  const record = recordOf(manifest);
+  const sources = /* @__PURE__ */ new Map();
+  for (const name of stringArray(record.supported_official_actions)) {
+    sources.set(name, { name: "official", tier: "official", manifestPath: customSource.manifestPath });
+  }
+  for (const action of customActions(record.custom_actions)) sources.set(action.name, { ...customSource });
+  return sources;
+}
 export {
   loadActionManifest,
   loadMetaMaskCoreActionManifest,
   loadMetaMaskExtensionActionManifest,
   loadMetaMaskMobileActionManifest,
-  validateManifest
+  resolveActionManifest,
+  validateManifest,
+  withMetaMaskExecutionCapabilities
 };

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");
@@ -69,13 +76,16 @@ Example:
   },
   {
     name: "actions",
-    summary: "List the action vocabulary + field schemas (--raw dumps the raw action registry JSON).",
+    summary: "Discover typed single operations and their fields.",
     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.
+  Discover typed single operations and their field schemas for this checkout.
 
+  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)
   --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
   --target <path>                    Checkout path (default: cwd)
   --raw                              Dump raw action registry JSON
@@ -83,6 +93,9 @@ 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
   mm-harness actions --adapter extension --raw`
   },
@@ -121,7 +134,7 @@ Example:
   Actions differ per adapter \u2014 list this checkout's with:
   mm-harness actions.
 
-  --list                             List everything invocable for the adapter (actions + flows); no <action> needed
+  --list                             List actions accepted by call for this adapter; no <action> needed
   --arg k=v                          Action field value (repeatable; equivalent to key=value shorthand)
   --device <udid|serial|name>        Mobile only: target this device (env: IOS_SIMULATOR / ADB_SERIAL). Without it, >1 connected mobile device fails fast and lists them.
   --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
@@ -137,46 +150,61 @@ Example (real actions; run mm-harness actions for this checkout's full set):
   mm-harness call navigate page=perps --adapter mobile
   mm-harness call command cmd="echo hi" --adapter core   # the universal action (all adapters)`
   },
-  {
-    name: "flows",
-    summary: "Browse the reusable flow library (bare = list; `flows promote` publishes a flow up a tier). Resolves across libraries \u2014 personal > team > canonical, highest tier wins.",
-    example: "mm-harness flows",
-    helpText: `mm-harness flows [flags]
-
-  Browse the reusable flow library. Flows resolve across libraries by precedence
-  (personal > team > canonical); the highest-tier copy wins and shadows lower ones.
-  Flow resolution is adapter-global, so there is no --adapter flag here.
-
-  --library <name=path>              Add/override a library source (repeatable)
-  --target <path>                    Checkout path (default: cwd)
-  --json                             Machine-readable output
-
-Example:
-  mm-harness flows`
-  },
   {
     name: "run",
-    summary: "Validate + run a recipe and write evidence (summary/trace/artifacts). --plan validates + prints the plan, touching nothing.",
+    summary: "Execute a complete proof and write its evidence.",
     example: "mm-harness run recipe.json",
-    helpText: `mm-harness run <recipe.json> [flags]
+    helpText: `mm-harness run <recipe|recipe.json> [key=value ...] [flags]
 
-  Validate + run a recipe and write evidence (summary / trace / artifacts).
+  Validate and execute a complete proof, then write summary, trace, diagnostics,
+  and artifacts. Inside a checkout, the adapter, target, ports, and artifact
+  directory are normally detected automatically.
 
-  --list                             List everything invocable for the adapter (actions + flows); no <recipe> needed
+Discovery:
+  --list                             List complete recipes accepted by run for this adapter; no <recipe> needed
+  --describe                         Show one recipe's parameters, composed actions/recipes, and runnable command
   --plan                             Validate + print execution plan, touching nothing. Exit 5 if invalid.
+
+Common overrides:
   --device <udid|serial|name>        Mobile only: target this device (env: IOS_SIMULATOR / ADB_SERIAL). Without it, >1 connected mobile device fails fast and lists them.
   --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
+  --platform <ios|android>           Mobile platform preference; use --adapter for the product adapter
   --target <path>                    Checkout path (default: cwd)
-  --artifacts-dir <dir>              Where to write evidence (required unless --plan)
-  --action-manifest <path>           Override the action manifest
+  --artifacts-dir <dir>              Override evidence output (default: active task/artifacts, otherwise a checkout-local temp/recipe/runs/<run>)
   --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
 
+Advanced integrations:
+  runtime: --cdp-port, --watcher-port/--metro-port, --runtime-dir, --slot,
+           --validation-runtime-dir, --launch-existing-dist
+  managed trust boundary (not needed for normal runs; Farmslot supplies it):
+           --source-trust, --source-kind, --source-name, --source-digest,
+           --approve-plan (binds approval to the exact reviewed plan)
+  schema:  --action-manifest
+
 Example:
-  mm-harness run recipe.json --plan --adapter mobile
-  mm-harness run recipe.json --adapter extension --artifacts-dir ./out`
+  mm-harness run wallet.smoke --describe
+  mm-harness run perps.clean-market-testnet market=BTC --plan
+  mm-harness run recipe.json market=ETH --adapter extension`
+  },
+  {
+    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",
@@ -375,6 +403,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
@@ -393,8 +422,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)
@@ -448,9 +477,10 @@ Example:
     name: "fixtures",
     summary: "Manage the canonical wallet fixture (wallet DATA only) \u2014 init / sync / set / generate / finalize.",
     example: "mm-harness fixtures set",
-    helpText: `mm-harness fixtures <init|sync|set|generate|finalize> [flags]
+    helpText: `mm-harness fixtures [<init|sync|set|generate|finalize>] [flags]
 
   Manage the ONE canonical wallet fixture per checkout \u2014 wallet DATA only.
+  With no action, show the current fixture status and safe next command.
   init       Create it from --from <path>, or explicitly choose --dev for a
              disposable public test wallet that must never hold real funds.
   sync       Refresh the wallet fixture files on the target.
@@ -473,6 +503,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
@@ -487,21 +518,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",
@@ -510,13 +548,13 @@ const HELP_GROUPS = [
   },
   {
     title: "DISCOVER",
-    blurb: "compose recipes from the action vocabulary + flow library (--json is the agent-primary form)",
-    commands: ["actions", "call", "flows"]
+    blurb: "discover atomic actions and reusable recipes (--json is the agent-primary form)",
+    commands: ["actions", "call"]
   },
   {
     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",
@@ -604,7 +642,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/RECIPES.md for proof authoring.");
   return `${lines.join("\n")}
 `;
 }
@@ -616,11 +654,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";
@@ -638,8 +671,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 = [
@@ -661,24 +693,9 @@ 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());
+  maybeNudge();
 }
 function hasPassthroughHelp(argv) {
   const divider = argv.indexOf("--");
@@ -692,10 +709,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);