@deeeed/metamask-harness 0.18.0 → 0.19.0

package/README.md

@@ -5,8 +5,7 @@ reviewable recipe evidence. Run it inside a checkout; the product, slot, ports,
 and runtime paths are detected automatically.
 
 - **Action:** one typed operation.
-- **Flow:** a reusable, parameterized sequence of actions.
-- **Recipe:** the complete proof for a task or regression.
+- **Recipe:** a reusable, parameterized graph of actions and called recipes.
 
 The generic graph engine and evidence schemas live in Farmslot packages.
 `mm-harness` owns MetaMask runtime control and domain capabilities.
@@ -71,12 +70,11 @@ mm-harness logs --source metro      # Mobile bundler
 mm-harness actions positions
 mm-harness actions --action metamask.wallet.ensure_unlocked
 mm-harness call metamask.wallet.ensure_unlocked
-mm-harness flows
-mm-harness flows describe perps.clean_market_testnet
 
 mm-harness run --list
+mm-harness run perps.clean-market-testnet --describe
 mm-harness run wallet.smoke --describe
-mm-harness run path/to/recipe.json --plan
+mm-harness run path/to/recipe.json market=ETH --plan
 mm-harness run path/to/recipe.json
 ```
 
@@ -92,11 +90,10 @@ line-buffered JSONL progress and a terminal event.
 
 ```bash
 export RECIPE_LIBRARY_PATH="team=$HOME/shared-library/team-recipes"
-mm-harness flows
 mm-harness run --list
 ```
 
-Shared libraries hold durable actions, flows, and recipes. Task acceptance
+Shared libraries hold durable actions and composable recipes. Task acceptance
 criteria remain task-local. See [Recipes](docs/RECIPES.md).
 
 ## Recover

package/adapters/core/inject.sh

@@ -110,12 +110,7 @@ install_v1_runner_assets() {
   if [ -d "$METAMASK_RUNNER_DIR/library/recipes" ]; then
     rsync -a --delete "$METAMASK_RUNNER_DIR/library/recipes/" "$HARNESS_DIR/runner/recipes/"
   fi
-  # Canonical recipe-library snapshot: flows/ + library.json so the installed
-  # harness mirrors the runner's library layout.
-  if [ -d "$METAMASK_RUNNER_DIR/library/flows" ]; then
-    mkdir -p "$HARNESS_DIR/runner/flows"
-    rsync -a --delete "$METAMASK_RUNNER_DIR/library/flows/" "$HARNESS_DIR/runner/flows/"
-  fi
+  rm -rf "$HARNESS_DIR/runner/flows"
   if [ -f "$METAMASK_RUNNER_DIR/library/library.json" ]; then
     cp "$METAMASK_RUNNER_DIR/library/library.json" "$HARNESS_DIR/runner/library.json"
   fi

package/adapters/extension/inject.mjs

@@ -90,11 +90,8 @@ copyFile(path.join(runnerDir, 'library/manifests/mobile.action-manifest.json'),
 copyFile(path.join(runnerDir, 'library/manifests/extension.action-manifest.json'), path.join(harnessDir, 'runner/manifests/extension.action-manifest.json'));
 copyFile(path.join(runnerDir, 'library/manifests/extension.action-manifest.json'), path.join(harnessDir, 'action-manifest.json'));
 copyDir(path.join(runnerDir, 'library/recipes'), path.join(harnessDir, 'runner/recipes'));
-// Canonical recipe-library snapshot: flows/ + library.json so the installed
-// harness mirrors the runner's library layout.
 copyFile(path.join(runnerDir, 'library/library.json'), path.join(harnessDir, 'runner/library.json'));
-fs.mkdirSync(path.join(harnessDir, 'runner/flows'), { recursive: true });
-copyDir(path.join(runnerDir, 'library/flows'), path.join(harnessDir, 'runner/flows'));
+fs.rmSync(path.join(harnessDir, 'runner/flows'), { recursive: true, force: true });
 // The installed overlay has a flat scripts/ runtime API independent of the
 // package's source layout.
 copyFile(path.join(runnerDir, 'adapters/extension/launch-browser.cjs'), path.join(harnessDir, 'scripts/launch-browser.cjs'));

package/adapters/extension/verify.sh

@@ -434,7 +434,7 @@ if [ "$STATIC_ONLY" = false ]; then
 
     if (
       cd "$TARGET"
-      "$RUNNER_BIN" run "$SMOKE_RECIPE" --adapter extension --project-root "$TARGET" --cdp-port "$CDP_PORT" --artifacts-dir "$ARTIFACTS/runner-smoke" --json
+      "$RUNNER_BIN" run "$SMOKE_RECIPE" --adapter extension --target "$TARGET" --cdp-port "$CDP_PORT" --artifacts-dir "$ARTIFACTS/runner-smoke" --json
     ) > "$ARTIFACTS/logs/runner-smoke.log" 2>&1; then
       checks+=("{\"name\":\"runner v1 smoke\",\"status\":\"pass\"}")
     else

package/adapters/mobile/inject.sh

@@ -75,8 +75,7 @@ cp "$RUNNER_DIR/library/manifests/mobile.action-manifest.json" "$HARNESS_DIR/run
 cp "$RUNNER_DIR/library/manifests/extension.action-manifest.json" "$HARNESS_DIR/runner/manifests/extension.action-manifest.json"
 rsync -a --delete "$RUNNER_DIR/library/recipes/" "$HARNESS_DIR/runner/recipes/"
 cp "$RUNNER_DIR/library/library.json" "$HARNESS_DIR/runner/library.json"
-mkdir -p "$HARNESS_DIR/runner/flows"
-rsync -a --delete "$RUNNER_DIR/library/flows/" "$HARNESS_DIR/runner/flows/"
+rm -rf "$HARNESS_DIR/runner/flows"
 cp "$RUNNER_DIR/adapters/mobile/verify.sh" "$HARNESS_DIR/scripts/verify.sh"
 cp "$RUNNER_DIR/adapters/shared/harness-path.sh" "$HARNESS_DIR/scripts/lib/harness-path.sh"
 cp "$RUNNER_DIR/adapters/shared/path-defaults.json" "$HARNESS_DIR/scripts/lib/path-defaults.json"
@@ -96,18 +95,20 @@ if [ "$GIT_EXCLUDE" = true ]; then
 fi
 
 RUNNER_REV="$(git -C "$RUNNER_DIR" rev-parse HEAD 2>/dev/null || echo unknown)"
+SOURCE_FINGERPRINT="$(node "$RUNNER_DIR/adapters/shared/harness-source-fingerprint.mjs" "$RUNNER_DIR" mobile)"
 CLEANUP_Q="$(printf '%q' "$SCRIPT_DIR/cleanup.sh")"
 TARGET_CLEANUP_Q="$(printf '%q' "$TARGET")"
 CLEANUP_COMMAND="RECIPE_HARNESS_ROOT=$(printf '%q' "$HARNESS_ROOT") $CLEANUP_Q --target $TARGET_CLEANUP_Q"
-node - "$HARNESS_DIR/manifest.json" "$TARGET_REV" "$RUNNER_DIR" "$RUNNER_REV" "$TARGET" "$HARNESS_REL" "$HARNESS_ROOT" "$CLEANUP_COMMAND" <<'NODE'
+node - "$HARNESS_DIR/manifest.json" "$TARGET_REV" "$RUNNER_DIR" "$RUNNER_REV" "$SOURCE_FINGERPRINT" "$TARGET" "$HARNESS_REL" "$HARNESS_ROOT" "$CLEANUP_COMMAND" <<'NODE'
 const fs = require('node:fs');
-const [manifestPath, targetRevision, runnerDir, runnerRevision, target, harnessRel, harnessRoot, cleanupCommand] = process.argv.slice(2);
+const [manifestPath, targetRevision, runnerDir, runnerRevision, sourceFingerprint, target, harnessRel, harnessRoot, cleanupCommand] = process.argv.slice(2);
 fs.writeFileSync(manifestPath, JSON.stringify({
   adapter: 'mobile',
   installMode: 'product-owned',
   targetRevision,
   installedAt: new Date().toISOString(),
   source: { runnerDir, runnerRevision },
+  sourceFingerprint,
   target,
   protocolVersion: 'v1',
   actionManifestPath: `${harnessRel}/action-manifest.json`,

package/adapters/mobile/verify.sh

@@ -305,16 +305,14 @@ live_status_ok() {
   local device_target="$2"
   cat > "$ARTIFACTS/mobile-status-smoke.recipe.json" <<'JSON'
 {
-  "schema_version": 1,
+  "$schema": "https://farmslot.io/schemas/recipe-v1.schema.json",
   "title": "Mobile runner status smoke",
   "description": "Checks that the installed runner can read Mobile app status before live verification.",
-  "validate": {
-    "workflow": {
-      "entry": "status",
-      "nodes": {
-        "status": { "action": "app.status", "intent": "Read Mobile app status through the runner-owned bridge", "next": "done" },
-        "done": { "action": "end", "status": "pass" }
-      }
+  "workflow": {
+    "entry": "status",
+    "nodes": {
+      "status": { "action": "app.status", "intent": "Read Mobile app status through the runner-owned bridge", "next": "done" },
+      "done": { "action": "end", "status": "pass" }
     }
   }
 }
@@ -323,7 +321,7 @@ JSON
     cd "$TARGET"
     device_args=()
     [ -n "$device_target" ] && device_args=(--device "$device_target")
-    "$RUNNER_BIN" run "$ARTIFACTS/mobile-status-smoke.recipe.json" --adapter mobile --project-root "$TARGET" "${device_args[@]}" --artifacts-dir "$ARTIFACTS/runner-status-smoke" --json
+    "$RUNNER_BIN" run "$ARTIFACTS/mobile-status-smoke.recipe.json" --adapter mobile --target "$TARGET" "${device_args[@]}" --artifacts-dir "$ARTIFACTS/runner-status-smoke" --json
   ) > "$log_path" 2>&1
 }
 
@@ -389,17 +387,15 @@ if [ "$STATIC_ONLY" = false ]; then
 
   cat > "$ARTIFACTS/mobile-v1-live-smoke.recipe.json" <<'JSON'
 {
-  "schema_version": 1,
+  "$schema": "https://farmslot.io/schemas/recipe-v1.schema.json",
   "title": "Mobile v1 runner live bridge smoke",
   "description": "Verifies the installed MetaMask runner can read the React Native debug bridge without mutating wallet state.",
-  "validate": {
-    "workflow": {
-      "entry": "status",
-      "nodes": {
-        "status": { "action": "app.status", "intent": "Read Mobile app status through the v1 runner", "next": "cdp-probe" },
-        "cdp-probe": { "action": "cdp.target", "intent": "Verify the React Native debug bridge target is reachable", "required": true, "timeout_ms": 15000, "next": "done" },
-        "done": { "action": "end", "status": "pass" }
-      }
+  "workflow": {
+    "entry": "status",
+    "nodes": {
+      "status": { "action": "app.status", "intent": "Read Mobile app status through the v1 runner", "next": "cdp-probe" },
+      "cdp-probe": { "action": "cdp.target", "intent": "Verify the React Native debug bridge target is reachable", "require_reachable": true, "timeout_ms": 15000, "next": "done" },
+      "done": { "action": "end", "status": "pass" }
     }
   }
 }
@@ -415,7 +411,7 @@ JSON
     IOS_SIMULATOR="${IOS_SIMULATOR:-$ios_simulator_resolved}" \
     ADB_SERIAL="${ADB_SERIAL:-$adb_serial_resolved}" \
     ANDROID_SERIAL="${ANDROID_SERIAL:-$adb_serial_resolved}" \
-    "$RUNNER_BIN" run "$ARTIFACTS/mobile-v1-live-smoke.recipe.json" --adapter mobile --project-root "$TARGET" "${device_args[@]}" --artifacts-dir "$ARTIFACTS/runner-live-smoke" --json
+    "$RUNNER_BIN" run "$ARTIFACTS/mobile-v1-live-smoke.recipe.json" --adapter mobile --target "$TARGET" "${device_args[@]}" --artifacts-dir "$ARTIFACTS/runner-live-smoke" --json
   ) > "$ARTIFACTS/logs/runner-live-smoke.log" 2>&1; then
     checks+=("{\"name\":\"runner v1 live bridge smoke\",\"status\":\"pass\"}")
   else

package/adapters/shared/harness-source-fingerprint.mjs

@@ -12,27 +12,29 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
+import { pathToFileURL } from 'node:url';
 
-// Trees whose contents are copied into <slot>/harness by inject.mjs. Any change
-// here means injected slots are stale.
-const SOURCE_DIRS = ['adapters/extension', 'adapters/shared', 'library'];
-
-export function harnessSourceFingerprint(runnerDir) {
+export function harnessSourceFingerprint(runnerDir, adapter = 'extension') {
+  if (adapter !== 'extension' && adapter !== 'mobile') {
+    throw new Error(`Unsupported harness fingerprint adapter: ${adapter}`);
+  }
+  const sourceDirs = [`adapters/${adapter}`, 'adapters/shared', 'library'];
   const entries = [];
-  for (const rel of SOURCE_DIRS) {
+  for (const rel of sourceDirs) {
     collect(path.join(runnerDir, rel), runnerDir, entries);
   }
   entries.sort();
   return crypto.createHash('sha256').update(entries.join('\n')).digest('hex');
 }
 
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  process.stdout.write(`${harnessSourceFingerprint(path.resolve(process.argv[2] ?? '.'), process.argv[3])}\n`);
+}
+
 function collect(dir, root, out) {
-  let dirents;
-  try {
-    dirents = fs.readdirSync(dir, { withFileTypes: true });
-  } catch {
-    return; // absent tree contributes nothing
-  }
+  // These trees are required runner inputs. Fail closed instead of producing a
+  // weaker fingerprint that could make a stale injected harness appear current.
+  const dirents = fs.readdirSync(dir, { withFileTypes: true });
   for (const dirent of dirents) {
     // Skip hidden noise (.DS_Store, editor swap files) so the fingerprint tracks
     // only real source and does not thrash re-injects.

package/dist/adapters/harness-freshness.js

@@ -0,0 +1,49 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { recipeHarnessPath, runnerDir } from "../paths.js";
+async function ensureHarnessFresh(target, adapter) {
+  if (!fs.existsSync(path.join(target, "package.json")) || !hasCheckoutHead(target)) return;
+  let current;
+  try {
+    const mod = await import(pathToFileURL(path.join(runnerDir, "adapters/shared/harness-source-fingerprint.mjs")).href);
+    current = mod.harnessSourceFingerprint(runnerDir, adapter);
+  } catch (error) {
+    const detail = error instanceof Error ? `: ${error.message}` : "";
+    throw new Error(`could not fingerprint the ${adapter} harness source${detail}`);
+  }
+  const manifestPath = recipeHarnessPath(target, adapter, "manifest.json");
+  const installed = readInstalledFingerprint(manifestPath);
+  if (installed === current) return;
+  const reason = installed === null ? "harness not installed" : "runner changed";
+  const injector = path.join(runnerDir, `adapters/${adapter}/inject.${adapter === "extension" ? "mjs" : "sh"}`);
+  try {
+    execFileSync(adapter === "extension" ? process.execPath : "bash", [injector, "--target", target], {
+      stdio: ["ignore", "ignore", "inherit"]
+    });
+    console.error(`\u2192 refreshed ${adapter} harness overlay (${reason})`);
+  } catch (error) {
+    const detail = error instanceof Error ? `: ${error.message}` : "";
+    throw new Error(`could not refresh the ${adapter} harness overlay (${reason})${detail}`);
+  }
+}
+function hasCheckoutHead(target) {
+  try {
+    execFileSync("git", ["-C", target, "rev-parse", "--verify", "HEAD"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function readInstalledFingerprint(manifestPath) {
+  try {
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+    return typeof manifest.sourceFingerprint === "string" ? manifest.sourceFingerprint : null;
+  } catch {
+    return null;
+  }
+}
+export {
+  ensureHarnessFresh
+};

package/dist/cli.js

@@ -11,7 +11,6 @@ import { handleRun } from "./commands/run.js";
 import { handleSelfTest } from "./commands/self-test.js";
 import { handleCall } from "./commands/call.js";
 import { handleStop } from "./commands/stop.js";
-import { handleFlows } from "./commands/flows.js";
 import { handleCompletionCandidates, invalidateCompletionCache } from "./commands/completion-candidates.js";
 import { handleLaunch } from "./commands/launch/index.js";
 import { handleLogs } from "./commands/logs.js";
@@ -53,8 +52,6 @@ DAILY LOOP \u2014 what a teammate runs many times a day:
 PROVE \u2014 run recipes and inspect capabilities:
   run        Run a recipe and write evidence (summary/trace/artifacts).
                mm-harness run recipe.json
-  flows      List/promote recipe library flows (personal/team win over canonical).
-               mm-harness flows list
   doctor     Readiness check for a checkout (no app launch).
                mm-harness doctor
   check      Run bounded repo-local checks for an active diff.
@@ -92,7 +89,6 @@ async function main(argv) {
   if (command === "status" || command === "health" || command === "home") {
     return handleStatus(parseArgs(argv.slice(1), "status"));
   }
-  if (command === "flows") return handleFlows(argv.slice(1));
   if (command === "call") return handleCall(argv.slice(1));
   if (command === "completion-candidates") return handleCompletionCandidates(argv.slice(1));
   if (command === "provision") return handleProvision(parseArgs(argv.slice(1), command));

package/dist/command-contract.js

@@ -5,7 +5,7 @@ const options = (...groups) => Object.assign({}, ...groups);
 const HELP = { "--help": bool(), "-h": bool() };
 const JSON = { "--json": bool() };
 const JSON_STREAM = { "--json-stream": bool() };
-const TARGET = { "--target": value(), "--project-root": value() };
+const TARGET = { "--target": value() };
 const ADAPTER = { "--adapter": value(["mobile", "extension", "core"]) };
 const MOBILE_PLATFORM = { "--platform": value(["ios", "android"]) };
 const ADAPTER_OR_MOBILE_PLATFORM = { "--platform": value(["mobile", "extension", "core", "ios", "android"]) };
@@ -25,9 +25,8 @@ const RECIPE_RUNTIME = {
   "--validation-runtime-dir": value(),
   "--launch-existing-dist": bool(),
   "--record-video": optionalValue(["full-run", "off"]),
-  "--record": bool(),
   "--source-trust": value(["trusted", "untrusted", "unknown"]),
-  "--source-kind": value(["bundled", "operator", "task", "recipe-file", "uses-catalog", "library", "custom-adapter"]),
+  "--source-kind": value(["bundled", "operator", "task", "recipe-file", "library", "custom-adapter"]),
   "--source-name": value(),
   "--source-digest": value(),
   "--approve-plan": value()
@@ -46,6 +45,10 @@ const RUNWAY = {
   "--force": bool(),
   "--resolve-only": bool()
 };
+const REMOVED_OPTION_REPLACEMENTS = {
+  "--project-root": "--target",
+  "--record": "--record-video"
+};
 const PUBLIC_COMMAND_CONTRACTS = {
   status: {
     aliases: ["health", "home"],
@@ -100,7 +103,7 @@ const PUBLIC_COMMAND_CONTRACTS = {
     })
   },
   call: {
-    options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, DEVICE, RUNTIME_PORTS, RECIPE_RUNTIME, {
+    options: options(HELP, JSON, TARGET, ADAPTER, MOBILE_PLATFORM, DEVICE, RUNTIME_PORTS, RECIPE_RUNTIME, {
       "--list": bool(),
       "--arg": value()
     }),
@@ -111,23 +114,8 @@ const PUBLIC_COMMAND_CONTRACTS = {
     leadingPositionals: 1,
     variadic: { label: "key=value", pattern: /^[^=\s]+=.*/u }
   },
-  flows: {
-    options: options(HELP, JSON, TARGET, {
-      "--library": value(),
-      "--from": value(),
-      "--flow": value(),
-      "--to": value(),
-      "--domain": value(),
-      "--run": value(),
-      "--force": bool()
-    }),
-    positionals: [
-      { label: "action", choices: ["list", "describe", "promote"] },
-      { label: "ref" }
-    ]
-  },
   run: {
-    options: options(HELP, JSON, JSON_STREAM, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, DEVICE, RUNTIME_PORTS, RECIPE_RUNTIME, {
+    options: options(HELP, JSON, JSON_STREAM, TARGET, ADAPTER, MOBILE_PLATFORM, DEVICE, RUNTIME_PORTS, RECIPE_RUNTIME, {
       "--list": bool(),
       "--plan": bool(),
       "--describe": bool()
@@ -135,7 +123,8 @@ const PUBLIC_COMMAND_CONTRACTS = {
     positionals: [{ label: "recipe" }],
     minimumPositionals: 1,
     requiredUnless: ["--list"],
-    noPositionalsWith: ["--list"]
+    noPositionalsWith: ["--list"],
+    variadic: { label: "key=value", pattern: /^[^=\s]+=.*/u }
   },
   last: {
     options: options(HELP, JSON, TARGET, {
@@ -238,7 +227,7 @@ const PUBLIC_COMMAND_CONTRACTS = {
       "--action-manifest": value()
     }),
     positionals: [{ label: "action", choices: ["init", "sync", "set", "generate", "finalize"] }],
-    minimumPositionals: 1
+    minimumPositionals: 0
   }
 };
 function validatePublicInvocation(argv, examples = {}) {
@@ -285,11 +274,11 @@ function validatePublicInvocation(argv, examples = {}) {
     const inlineValue = equals === -1 ? void 0 : argument.slice(equals + 1);
     const spec = contract.options[optionName];
     if (!spec) {
-      const suggestion = closest(optionName, validOptions);
+      const suggestion = REMOVED_OPTION_REPLACEMENTS[optionName] ?? closest(optionName, validOptions);
       return {
         code: "CLI_UNKNOWN_OPTION",
         command: name,
-        message: `unknown option '${optionName}'. Valid options for mm-harness ${name}: ${formatOptions(contract)}.`,
+        message: `unknown option '${optionName}'.`,
         userAction: actionFor(optionName, suggestion, exampleFor(name, examples))
       };
     }
@@ -312,7 +301,7 @@ function validatePublicInvocation(argv, examples = {}) {
       return {
         code: "CLI_INVALID_OPTION_VALUE",
         command: name,
-        message: `${optionName} must be ${formatChoiceList(spec.choices)}; received '${optionValue}'. Valid options for mm-harness ${name}: ${formatOptions(contract)}.`,
+        message: `${optionName} must be ${formatChoiceList(spec.choices)}; received '${optionValue}'.`,
         userAction: actionFor(optionValue, suggestion, exampleFor(name, examples))
       };
     }
@@ -320,7 +309,7 @@ function validatePublicInvocation(argv, examples = {}) {
   if (seenOptions.has("--help") || seenOptions.has("-h")) return null;
   if (contract.leadingPositionals && !contract.requiredUnless?.some((option) => seenOptions.has(option)) && tokens.slice(0, contract.leadingPositionals).some((argument) => !argument || argument.startsWith("-"))) {
     const missing = contract.positionals?.[0]?.label ?? "argument";
-    return usageFailure("CLI_MISSING_POSITIONAL", name, `${name} requires <${missing}> first.`, contract, examples);
+    return missingPositionalFailure(name, `${name} requires <${missing}> first.`, contract, examples);
   }
   const forbiddingOption = contract.noPositionalsWith?.find((option) => seenOptions.has(option));
   if (forbiddingOption && positionals.length > 0) {
@@ -338,7 +327,7 @@ function validatePublicInvocation(argv, examples = {}) {
     const missing = missingSpec?.label ?? "argument";
     const valid = missingSpec?.choices?.length ? ` Choose one: ${missingSpec.choices.join("|")}.` : "";
     const usage = contract.usage ? ` Usage: ${contract.usage}.` : "";
-    return usageFailure("CLI_MISSING_POSITIONAL", name, `missing required <${missing}>.${valid}${usage}`, contract, examples);
+    return missingPositionalFailure(name, `missing required <${missing}>.${valid}${usage}`, contract, examples);
   }
   const fixed = contract.positionals ?? [];
   for (let index = 0; index < Math.min(positionals.length, fixed.length); index += 1) {
@@ -376,21 +365,44 @@ function resolveCommand(token) {
   }
   return null;
 }
-function usageFailure(code, command, message, contract, examples) {
+function usageFailure(code, command, message, _contract, examples) {
   return {
     code,
     command,
-    message: `${message} Valid options for mm-harness ${command}: ${formatOptions(contract)}.`,
+    message,
     userAction: `Try: ${exampleFor(command, examples)}. Inspect options: mm-harness ${command} --help`
   };
 }
-function positionalFailure(command, received, spec, contract, examples) {
+function missingPositionalFailure(command, message, contract, examples) {
+  if (command === "run") {
+    return {
+      code: "CLI_MISSING_POSITIONAL",
+      command,
+      message,
+      userAction: `List recipes: mm-harness run --list
+  Example: ${exampleFor(command, examples)}
+  More: mm-harness run --help`
+    };
+  }
+  if (command === "call") {
+    return {
+      code: "CLI_MISSING_POSITIONAL",
+      command,
+      message,
+      userAction: `List actions: mm-harness call --list
+  Example: ${exampleFor(command, examples)}
+  More: mm-harness call --help`
+    };
+  }
+  return usageFailure("CLI_MISSING_POSITIONAL", command, message, contract, examples);
+}
+function positionalFailure(command, received, spec, _contract, examples) {
   const valid = spec.validDescription ?? (spec.choices ? spec.choices.join(", ") : spec.pattern || spec.validate ? `a valid <${spec.label}>` : `<${spec.label}>`);
   const suggestion = spec.choices ? closest(received, spec.choices) : void 0;
   return {
     code: "CLI_INVALID_POSITIONAL",
     command,
-    message: `invalid <${spec.label}> '${received}'. Valid values: ${valid}. Valid options for mm-harness ${command}: ${formatOptions(contract)}.`,
+    message: `invalid <${spec.label}> '${received}'. Valid values: ${valid}.`,
     userAction: actionFor(received, suggestion, exampleFor(command, examples))
   };
 }
@@ -400,13 +412,6 @@ function invalidPositional(value2, spec) {
   if (spec.validate && !spec.validate(value2)) return true;
   return Boolean(spec.pattern && !spec.pattern.test(value2));
 }
-function formatOptions(contract) {
-  return Object.entries(contract.options).map(([name, spec]) => {
-    if (spec.kind === "boolean") return name;
-    const valueLabel = spec.choices?.join("|") ?? "value";
-    return spec.kind === "optional-value" ? `${name}[=${valueLabel}]` : `${name} <${valueLabel}>`;
-  }).join(", ");
-}
 function formatChoiceList(choices) {
   if (choices.length === 1) return choices[0] ?? "";
   if (choices.length === 2) return `${choices[0]} or ${choices[1]}`;
@@ -432,19 +437,25 @@ function closest(input, candidates) {
   return best.distance <= threshold ? best.candidate : void 0;
 }
 function levenshtein(left, right) {
-  const prior = Array.from({ length: right.length + 1 }, (_, index) => index);
+  let twoBack;
+  let prior = Array.from({ length: right.length + 1 }, (_, index) => index);
   for (let leftIndex = 1; leftIndex <= left.length; leftIndex += 1) {
     const current = [leftIndex];
     for (let rightIndex = 1; rightIndex <= right.length; rightIndex += 1) {
       const substitution = prior[rightIndex - 1] + (left[leftIndex - 1] === right[rightIndex - 1] ? 0 : 1);
       current[rightIndex] = Math.min((current[rightIndex - 1] ?? 0) + 1, (prior[rightIndex] ?? 0) + 1, substitution);
+      if (twoBack && leftIndex > 1 && rightIndex > 1 && left[leftIndex - 1] === right[rightIndex - 2] && left[leftIndex - 2] === right[rightIndex - 1]) {
+        current[rightIndex] = Math.min(current[rightIndex] ?? 0, (twoBack[rightIndex - 2] ?? 0) + 1);
+      }
     }
-    for (let index = 0; index < current.length; index += 1) prior[index] = current[index] ?? 0;
+    twoBack = prior;
+    prior = current;
   }
   return prior[right.length] ?? right.length;
 }
 export {
   PUBLIC_COMMAND_CONTRACTS,
+  closest,
   publicCommandNames,
   publicCommandTokens,
   validatePublicInvocation