@deeeed/metamask-harness 0.17.5 → 0.19.0

package/dist/commands/call.js

@@ -1,20 +1,21 @@
 import fs from "node:fs";
-import { mkdtemp } from "node:fs/promises";
-import os from "node:os";
+import { createHash } from "node:crypto";
 import path from "node:path";
-import { loadActionManifest } from "../manifest.js";
+import { resolveActionManifest } from "../manifest.js";
 import { importRecipeProtocol } from "../paths.js";
-import { recipeRunning } from "../heal-bounds.js";
+import { conciseFailureForHuman, recipeRunning } from "../heal-bounds.js";
 import { color } from "../cli-color.js";
-import { EXIT } from "./shared.js";
-import { describeManifestActions, fuzzyResolveActions } from "./manifest.js";
+import { checkoutBusyOut, EXIT, usageOut } from "./shared.js";
+import { actionExampleCommand, describeManifestActions, fuzzyResolveActions } from "./manifest.js";
 import {
   parseArgs,
   isRecord,
   optionFlag,
   optionString,
+  optionStrings,
   resolveAdapter,
   runtimeOptionsFromCli,
+  shellQuote,
   usageError
 } from "./parse-args.js";
 import { getAdapterSurface } from "../adapters/surface.js";
@@ -27,11 +28,16 @@ import {
   prepareHeal,
   recoverRunInfra,
   resolveMetaMaskLibrarySources,
+  preflightRecipe,
   runRecipe,
   synthesizeOneNodeRecipe,
   validateRecipeAdapterAware
 } from "./run-engine.js";
 import { acquireCheckoutLock } from "../checkout-lock.js";
+import { formatRunDiagnosticsForHuman, readRunDiagnosticsDocument } from "../run-diagnostics.js";
+import { recipeTrustFailure } from "../recipe-security.js";
+import { isSensitiveKey, recordCommandEvidence, redactStructuredValue } from "../command-journal.js";
+import { closest } from "../command-contract.js";
 async function handleCall(argv) {
   if (argv.includes("--list")) {
     const { options: options2 } = parseArgs(argv, "call");
@@ -50,7 +56,8 @@ async function handleCall(argv) {
     let discovery = "mm-harness actions";
     try {
       const { adapter: adapter2 } = resolveAdapter(options);
-      const manifest2 = loadActionManifest(adapter2, optionString(options, "actionManifest"));
+      const librarySources2 = await resolveMetaMaskLibrarySources(optionStrings(options, "library"));
+      const { manifest: manifest2 } = await resolveActionManifest(adapter2, optionString(options, "actionManifest"), librarySources2);
       const { getRecipeActionManifestActionNames: getRecipeActionManifestActionNames2 } = await importRecipeProtocol();
       const exampleAction = pickCallExampleAction(getRecipeActionManifestActionNames2(manifest2));
       example = `mm-harness call ${exampleAction} --adapter ${adapter2}`;
@@ -59,47 +66,70 @@ async function handleCall(argv) {
     }
     const message = `call requires <action>. Example: ${example}`;
     const userAction = `${example}   # see the vocabulary: ${discovery}`;
-    if (json) console.log(JSON.stringify({ schemaVersion: 1, command: "call", error: { code: "USAGE", message, userAction } }, null, 2));
+    if (json) console.log(JSON.stringify({
+      schemaVersion: 1,
+      command: "call",
+      status: "fail",
+      error: { code: "CLI_MISSING_POSITIONAL", message, userAction },
+      exitCode: EXIT.usage
+    }, null, 2));
     else console.error(`${message}
   See the vocabulary: ${discovery}`);
     return EXIT.usage;
   }
   const { adapter, target } = resolveAdapter(options);
+  if (!fs.existsSync(target)) {
+    return usageOut(
+      json,
+      "call",
+      `target does not exist: ${target}`,
+      "pass --target <metamask-checkout> pointing to an existing checkout"
+    );
+  }
   getAdapterSurface(adapter).resolveSlotPorts(target);
   const dtResult = applyDeviceTargeting("call", adapter, options, { gate: true, rerun: "" });
   if ("code" in dtResult) {
-    if (json) console.log(JSON.stringify({ schemaVersion: 1, command: "call", adapter, error: { code: dtResult.code, message: dtResult.message } }, null, 2));
-    else console.error(`\u2717 call: ${dtResult.message}`);
+    if (json) console.log(JSON.stringify({ schemaVersion: 1, command: "call", adapter, error: { code: dtResult.code, message: dtResult.message, userAction: dtResult.userAction } }, null, 2));
+    else console.error(`\u2717 call: ${dtResult.message}
+  Next: ${dtResult.userAction}`);
     return EXIT.usage;
   }
   if (recipeRunning(target)) {
     const msg = "a recipe is currently running \u2014 refusing to start while another recipe executes.";
+    const userAction = `inspect the checkout state with: mm-harness status --target ${shellQuote(target)} --json; retry after the active recipe finishes`;
     if (json) {
-      console.log(JSON.stringify({ schemaVersion: 1, command: "call", status: "fail", recoverable: false, error: { code: "RECIPE_RUNNING", message: msg } }, null, 2));
+      console.log(JSON.stringify({ schemaVersion: 1, command: "call", status: "fail", recoverable: false, error: { code: "RECIPE_RUNNING", message: msg, userAction } }, null, 2));
     } else {
-      console.error(`\u2717 mm-harness call: ${msg}`);
+      console.error(`\u2717 mm-harness call: ${msg}
+  Next: ${userAction}`);
     }
     return EXIT.bounded;
   }
   const actionManifestOverride = optionString(options, "actionManifest");
-  const manifest = loadActionManifest(adapter, actionManifestOverride);
+  const librarySources = await resolveMetaMaskLibrarySources(optionStrings(options, "library"));
+  const { manifest, actionSources } = await resolveActionManifest(adapter, actionManifestOverride, librarySources);
   const { getRecipeActionManifestActionNames } = await importRecipeProtocol();
   const names = getRecipeActionManifestActionNames(manifest);
   const resolution = resolveActionName(shortName, names);
   if (resolution.status === "unknown") {
-    const message = `\u2717 call: unknown action "${shortName}" for the ${adapter} adapter.
-  See the vocabulary: mm-harness actions --adapter ${adapter} --json`;
-    if (json) console.log(JSON.stringify({ schemaVersion: 1, command: "call", adapter, action: shortName, error: { code: "ACTION_UNKNOWN", message } }, null, 2));
-    else console.error(message);
+    const message = `unknown action "${shortName}" for the ${adapter} adapter.`;
+    const userAction = `mm-harness actions --adapter ${adapter} --json`;
+    if (json) console.log(JSON.stringify({ schemaVersion: 1, command: "call", adapter, action: shortName, error: { code: "ACTION_UNKNOWN", message, userAction } }, null, 2));
+    else console.error(`\u2717 call: ${message}
+  Next: ${userAction}`);
     return EXIT.usage;
   }
   if (resolution.status === "ambiguous") {
-    const message = `\u2717 call: "${shortName}" is ambiguous: ${resolution.candidates.join(", ")} \u2014 use the full name.`;
-    if (json) console.log(JSON.stringify({ schemaVersion: 1, command: "call", adapter, action: shortName, error: { code: "ACTION_AMBIGUOUS", message, candidates: resolution.candidates } }, null, 2));
-    else console.error(message);
+    const message = `"${shortName}" is ambiguous: ${resolution.candidates.join(", ")} \u2014 use the full name.`;
+    const userAction = `mm-harness actions --action ${resolution.candidates[0]} --adapter ${adapter} --json`;
+    if (json) console.log(JSON.stringify({ schemaVersion: 1, command: "call", adapter, action: shortName, error: { code: "ACTION_AMBIGUOUS", message, candidates: resolution.candidates, userAction } }, null, 2));
+    else console.error(`\u2717 call: ${message}
+  Next: ${userAction}`);
     return EXIT.usage;
   }
   const resolvedAction = resolution.resolved;
+  const describedAction = describeManifestActions(manifest, actionSources).find((entry) => entry.name === resolvedAction);
+  const defaultsUsed = actionDefaultsUsed(describedAction, args);
   const depsBlock = adapter === "core" && resolvedAction.startsWith("metamask.perps.") ? coreDependencyBlock(target) : null;
   if (depsBlock) {
     if (json) {
@@ -111,21 +141,91 @@ async function handleCall(argv) {
     return EXIT.usage;
   }
   const recipe = synthesizeOneNodeRecipe(resolvedAction, args);
-  const validation = await validateRecipeAdapterAware(recipe, manifest);
+  const validation = await validateRecipeAdapterAware(adapter, recipe, manifest, librarySources);
   if (validation.status === "invalid") {
-    const message = `\u2717 call ${resolvedAction}: recipe validation failed`;
-    if (json) console.log(JSON.stringify({ schemaVersion: 1, command: "call", adapter, action: shortName, resolvedAction, args, findings: validation.findings, error: { code: "RECIPE_VALIDATION_FAILED", message } }, null, 2));
+    const message = `call ${resolvedAction}: recipe validation failed`;
+    const parameterHelp = parameterValidationHelp(describedAction, validation.findings, args);
+    const userAction = describedAction ? actionExampleCommand(
+      describedAction,
+      adapter,
+      target,
+      process.env.MM_HARNESS_INVOKED_AS ?? process.env.MM_HARNESS_EXECUTABLE ?? "mm-harness"
+    ) ?? `mm-harness actions --action ${resolvedAction} --adapter ${adapter}` : `mm-harness actions --action ${resolvedAction} --adapter ${adapter}`;
+    if (json) console.log(JSON.stringify({ schemaVersion: 1, command: "call", adapter, action: shortName, resolvedAction, args: redactCallValue(args), findings: validation.findings, ...parameterHelp.length > 0 ? { parameterHelp } : {}, error: { code: "RECIPE_VALIDATION_FAILED", message, userAction } }, null, 2));
     else {
-      console.error(message);
-      for (const finding of validation.findings) console.error(`  ${finding.code} ${finding.path} \u2014 ${finding.message}`);
+      console.error(`\u2717 ${message}`);
+      const taught = new Set(parameterHelp.map((entry) => `${entry.issue}:${entry.name}`));
+      for (const entry of parameterHelp) console.error(renderParameterValidationHelp(entry));
+      for (const finding of validation.findings) {
+        const name = finding.path.split(".").at(-1);
+        const issue = parameterIssue(finding.code);
+        if (issue && name && taught.has(`${issue}:${name}`)) continue;
+        console.error(`  ${finding.code} ${finding.path} \u2014 ${finding.message}`);
+      }
+      console.error(`  Next: ${userAction}`);
+    }
+    return EXIT.validation;
+  }
+  const artifactsDir = optionString(options, "artifactsDir") ?? defaultCallArtifactsDir(target, resolvedAction, args);
+  recordCommandEvidence(artifactsDir);
+  const requestedRuntimeOptions = runtimeOptionsFromCli(options);
+  const callRuntimeOptions = {
+    ...requestedRuntimeOptions,
+    ...librarySources ? { librarySources } : {},
+    autoHud: false,
+    suppressLibraryResolutionLogs: true,
+    stdoutIsMachineContract: json,
+    source: requestedRuntimeOptions.source ?? {
+      kind: "operator",
+      trust: "trusted",
+      name: "mm-harness call"
+    }
+  };
+  let preflightedExecution;
+  try {
+    preflightedExecution = await preflightRecipe(
+      adapter,
+      recipe,
+      artifactsDir,
+      target,
+      actionManifestOverride,
+      callRuntimeOptions
+    );
+  } catch (error) {
+    const trustFailure = recipeTrustFailure(error);
+    if (!trustFailure) throw error;
+    const planDigest = trustFailure.details?.recipeDigest;
+    if (planDigest) {
+      trustFailure.userAction = `review the plan, then rerun this call with --artifacts-dir ${shellQuote(artifactsDir)} --approve-plan ${shellQuote(planDigest)}; managed callers must keep the same artifact directory and execution environment, then set FARMSLOT_RECIPE_APPROVE_PLAN=${shellQuote(planDigest)}`;
+    }
+    if (json) {
+      console.log(JSON.stringify({
+        schemaVersion: 1,
+        command: "call",
+        status: "fail",
+        error: trustFailure,
+        exitCode: EXIT.validation
+      }, null, 2));
+    } else {
+      console.error(`\u2717 mm-harness call: ${trustFailure.message}`);
+      const blocked = trustFailure.details?.blocked;
+      if (blocked?.length) {
+        console.error("  Restricted plan nodes:");
+        for (const node of blocked.slice(0, 10)) {
+          const implementation = node.implementation?.digest ? ` implementation=${node.implementation.kind ?? "custom"}@${node.implementation.digest}` : "";
+          console.error(
+            `  - ${node.nodeId}: ${node.action} [${node.capabilities.join(", ")}] source=${node.source}${implementation}`
+          );
+        }
+        if (blocked.length > 10) console.error(`  - \u2026 ${blocked.length - 10} more (use --json)`);
+      }
+      console.error(`  Next: ${trustFailure.userAction}`);
     }
     return EXIT.validation;
   }
   const lock = acquireCheckoutLock(target, "call");
   if ("message" in lock) {
-    if (json) console.log(JSON.stringify({ schemaVersion: 1, command: "call", status: "fail", recoverable: false, error: { code: "SANDBOX_BUSY", message: lock.message } }, null, 2));
-    else console.error(`\u2717 mm-harness call: ${lock.message}`);
-    return EXIT.bounded;
+    return checkoutBusyOut(json, "call", lock.message, lock.path);
   }
   try {
     const prepared = await prepareHeal(adapter, target, options, json, {
@@ -133,27 +233,41 @@ async function handleCall(argv) {
     });
     if (typeof prepared === "number") return prepared;
     const { state, heal } = prepared;
-    const scratch = await mkdtemp(path.join(os.tmpdir(), "mm-harness-call-"));
-    const recipeFile = path.join(scratch, "call.recipe.json");
-    fs.writeFileSync(recipeFile, `${JSON.stringify(recipe, null, 2)}
-`);
-    const artifactsDir = optionString(options, "artifactsDir") ?? path.join(scratch, "artifacts");
-    const librarySources = await resolveMetaMaskLibrarySources(optionString(options, "library"));
-    const callRuntimeOptions = {
-      ...runtimeOptionsFromCli(options),
-      ...librarySources ? { librarySources } : {},
-      stdoutIsMachineContract: json
-    };
     const { result, violation } = await executeWithHealBounds(
-      () => runRecipe(adapter, recipeFile, artifactsDir, target, actionManifestOverride, callRuntimeOptions),
+      () => {
+        const execution = preflightedExecution;
+        preflightedExecution = void 0;
+        return runRecipe(
+          adapter,
+          recipe,
+          artifactsDir,
+          target,
+          actionManifestOverride,
+          callRuntimeOptions,
+          execution
+        );
+      },
       adapter,
       target,
       heal,
       state,
       () => recoverRunInfra(adapter, target, json)
     );
-    if (violation !== null) return emitHealViolation(json, "call", result, violation, state, adapter);
+    if (violation !== null) {
+      const conciseFailure = violation.originalError ? conciseFailureForHuman(violation.originalError) : "";
+      const example = describedAction ? actionExampleCommand(
+        describedAction,
+        adapter,
+        target,
+        process.env.MM_HARNESS_INVOKED_AS ?? process.env.MM_HARNESS_EXECUTABLE ?? "mm-harness"
+      ) : void 0;
+      const taughtViolation = violation.code === "APP_LOGIC_FAILURE" && conciseFailure.includes(" requires ") && example ? { ...violation, userAction: example } : violation;
+      return emitHealViolation(json, "call", result, taughtViolation, state, adapter);
+    }
     const callOutput = readCallOutput(result.tracePath);
+    const safeArgs = redactCallValue(args);
+    const safeCallOutput = redactCallValue(callOutput);
+    const failureUserAction = `mm-harness last --target ${shellQuote(target)} --json`;
     if (json) {
       console.log(
         JSON.stringify(
@@ -163,30 +277,43 @@ async function handleCall(argv) {
             adapter,
             action: shortName,
             resolvedAction,
-            args,
+            args: safeArgs,
+            ...Object.keys(defaultsUsed).length > 0 ? { defaultsUsed } : {},
             status: result.status,
             summaryPath: result.summaryPath,
             tracePath: result.tracePath,
             artifactManifestPath: result.artifactManifestPath,
-            ...callOutput !== void 0 ? { output: callOutput } : {},
+            ...result.diagnosticsPath ? { diagnosticsPath: result.diagnosticsPath } : {},
+            ...result.sideFindings ? { sideFindings: result.sideFindings } : {},
+            ...callOutput !== void 0 ? { output: safeCallOutput } : {},
             recovered: state.recovered,
             mutations: state.mutations,
-            exitCode: result.status === "pass" ? EXIT.ok : EXIT.runtime
+            exitCode: result.status === "pass" ? EXIT.ok : EXIT.runtime,
+            ...result.status === "fail" ? { error: { code: "ACTION_EXECUTION_FAILED", message: `${resolvedAction} failed; inspect the persisted result and evidence paths`, userAction: failureUserAction } } : {}
           },
           null,
           2
         )
       );
     } else {
-      const rendered = callOutput !== void 0 ? `
-Result:
-${formatCallOutput(callOutput)}` : "";
+      const renderedInputs = Object.keys(args).length > 0 ? formatCallOutput(safeArgs) : "";
       const out = (style, text) => color(style, text, { stream: process.stdout });
+      const diagnostics = formatRunDiagnosticsForHuman(
+        readRunDiagnosticsDocument(result.diagnosticsPath),
+        adapter
+      );
+      const renderedDiagnostics = `${out("label", "Diagnostics:")}
+${diagnostics.map((line) => `  ${line}`).join("\n")}
+`;
       console.log(
-        `${out("label", "call")} ${out("cmd", resolvedAction)}: ${out(result.status === "pass" ? "ok" : "err", result.status)}${rendered ? `
+        `${out("label", "call")} ${out("cmd", resolvedAction)}: ${out(result.status === "pass" ? "ok" : "err", result.status)}${renderedInputs ? `
+${out("label", "Inputs:")}
+${renderedInputs}` : ""}${Object.keys(defaultsUsed).length > 0 ? `
+${renderDefaultsUsed(defaultsUsed, process.stdout)}` : ""}${callOutput !== void 0 ? `
 ${out("label", "Result:")}
-${formatCallOutput(callOutput)}` : ""}
-${out("label", "Artifacts:")} ${out("path", result.artifactManifestPath)}`
+${formatCallOutput(safeCallOutput)}` : ""}
+` + renderedDiagnostics + `${out("label", "Artifacts:")} ${out("path", result.artifactManifestPath)}` + (result.status === "fail" ? `
+  Next: ${failureUserAction}` : "")
       );
     }
     return result.status === "pass" ? EXIT.ok : EXIT.runtime;
@@ -194,6 +321,59 @@ ${out("label", "Artifacts:")} ${out("path", result.artifactManifestPath)}`
     lock.release();
   }
 }
+function parameterValidationHelp(action, findings, args) {
+  const schema = isRecord(action?.schema) ? action.schema : {};
+  const properties = isRecord(schema.properties) ? schema.properties : {};
+  return findings.flatMap((finding) => {
+    const issue = parameterIssue(finding.code);
+    if (!issue) return [];
+    const name = finding.path.split(".").at(-1);
+    const property = name && isRecord(properties[name]) ? properties[name] : void 0;
+    if (!name || !property) return [];
+    const validValues = Array.isArray(property.enum) ? property.enum : void 0;
+    const received = Object.hasOwn(args, name) ? args[name] : void 0;
+    const suggestion = issue === "invalid" && received !== void 0 && validValues ? closest(String(received), validValues.map(String)) : void 0;
+    return [{
+      issue,
+      name,
+      ...typeof property.type === "string" ? { type: property.type } : {},
+      ...validValues ? { validValues } : {},
+      ...typeof property.description === "string" ? { description: property.description } : {},
+      ...issue === "invalid" && received !== void 0 ? { received } : {},
+      ...suggestion ? { suggestion } : {}
+    }];
+  });
+}
+function parameterIssue(code) {
+  if (code === "recipe.missing_param") return "missing";
+  if (code === "recipe.invalid_param_value_enum") return "invalid";
+  return void 0;
+}
+function renderParameterValidationHelp(parameter) {
+  const out = (style, text) => color(style, text, { stream: process.stderr });
+  const heading = parameter.issue === "missing" ? `${out("cmd", parameter.name)}${parameter.type ? ` (${parameter.type}, required)` : " (required)"}` : `${out("cmd", parameter.name)} received ${out("err", JSON.stringify(parameter.received) ?? String(parameter.received))}`;
+  const values = parameter.validValues?.length ? ` Valid values: ${parameter.validValues.map((value) => out("accent", String(value))).join(", ")}.` : "";
+  const suggestion = parameter.suggestion ? ` Did you mean ${out("accent", JSON.stringify(parameter.suggestion))}?` : "";
+  const description = parameter.description ? ` ${parameter.description}` : "";
+  return `  ${heading}.${values}${suggestion}${description}`;
+}
+function actionDefaultsUsed(action, args) {
+  const schema = isRecord(action?.schema) ? action.schema : {};
+  const properties = isRecord(schema.properties) ? schema.properties : {};
+  return Object.fromEntries(
+    Object.entries(properties).filter(([name, entry]) => !Object.hasOwn(args, name) && isRecord(entry) && Object.hasOwn(entry, "default")).map(([name, entry]) => [name, entry.default])
+  );
+}
+function renderDefaultsUsed(defaults, stream) {
+  const out = (style, text) => color(style, text, { stream });
+  const values = Object.entries(defaults).map(([name, value]) => `${out("cmd", name)}=${out("accent", JSON.stringify(value) ?? String(value))}`).join(", ");
+  return `${out("label", "Defaults used:")} ${values}`;
+}
+function defaultCallArtifactsDir(target, action, args) {
+  const actionStem = action.replace(/[^a-zA-Z0-9._-]/gu, "_");
+  const digest = createHash("sha256").update(JSON.stringify({ action, args })).digest("hex").slice(0, 12);
+  return path.join(target, "temp", "recipe", "calls", `${actionStem}-${digest}`);
+}
 function readCallOutput(tracePath) {
   try {
     const trace = JSON.parse(fs.readFileSync(tracePath, "utf8"));
@@ -209,20 +389,27 @@ function formatCallOutput(value) {
   if (typeof value === "number" || typeof value === "boolean" || value === null) return String(value);
   return JSON.stringify(value, null, 2);
 }
+function redactCallValue(value, key = "") {
+  return key && isSensitiveKey(key) ? "<redacted>" : redactStructuredValue(value);
+}
 async function handleCallHelp(argv, genericHelp) {
   const { action: shortName, rest } = parseCallArgs(argv.filter((arg) => arg !== "--help" && arg !== "-h"));
   const { options } = parseArgs(rest, "call");
   let adapter;
   let manifest;
+  let actionSources = /* @__PURE__ */ new Map();
   try {
     ({ adapter } = resolveAdapter(options));
-    manifest = loadActionManifest(adapter, optionString(options, "actionManifest"));
+    const librarySources = await resolveMetaMaskLibrarySources(optionStrings(options, "library"));
+    const resolution = await resolveActionManifest(adapter, optionString(options, "actionManifest"), librarySources);
+    manifest = resolution.manifest;
+    actionSources = resolution.actionSources;
   } catch {
     process.stdout.write(`${genericHelp}
 `);
     return EXIT.ok;
   }
-  const matches = shortName ? fuzzyResolveActions(describeManifestActions(manifest), shortName) : [];
+  const matches = shortName ? fuzzyResolveActions(describeManifestActions(manifest, actionSources), shortName) : [];
   if (matches.length === 0) {
     process.stdout.write(`${genericHelp}
 `);
@@ -250,7 +437,8 @@ function renderCallActionHelp(entry) {
   );
   const lines = [`mm-harness call ${entry.name} [key=value ...] [--arg k=v ...] [flags]`, ""];
   if (entry.description) lines.push(`  ${entry.description}`, "");
-  const names = Object.keys(properties).sort();
+  lines.push(`  Source: ${entry.source}${entry.sourceManifest ? ` (${entry.sourceManifest})` : ""}`, "");
+  const names = Object.keys(properties).filter((name) => name !== "action" && name !== "next").sort();
   if (names.length === 0) {
     lines.push("  Fields: (none)");
   } else {
@@ -262,7 +450,8 @@ function renderCallActionHelp(entry) {
       const req = required.has(name) ? " (required)" : "";
       const desc = typeof prop.description === "string" ? ` \u2014 ${prop.description}` : "";
       const enumVals = Array.isArray(prop.enum) ? ` [one of: ${prop.enum.join(", ")}]` : "";
-      lines.push(`    ${name.padEnd(width)}  ${type}${req}${desc}${enumVals}`);
+      const defaultValue = Object.hasOwn(prop, "default") ? ` [default: ${JSON.stringify(prop.default)}]` : "";
+      lines.push(`    ${name.padEnd(width)}  ${type}${req}${defaultValue}${desc}${enumVals}`);
     }
   }
   const examples = renderCallExamples(short, entry.examples);
@@ -320,7 +509,7 @@ function parseCallValue(value) {
     const number = Number(value);
     if (Number.isFinite(number)) return number;
   }
-  if (value.startsWith("[") && value.endsWith("]") || value.startsWith("{") && value.endsWith("}")) {
+  if (value.startsWith("[") && value.endsWith("]") || value.startsWith("{") && value.endsWith("}") || value.startsWith('"') && value.endsWith('"')) {
     try {
       return JSON.parse(value);
     } catch {
@@ -340,6 +529,7 @@ function isForwardedOptionValue(argv, index) {
 }
 const VALUE_TAKING_CALL_FLAGS = /* @__PURE__ */ new Set([
   "action-manifest",
+  "approve-plan",
   "adapter",
   "artifacts-dir",
   "cdp-port",
@@ -348,8 +538,11 @@ const VALUE_TAKING_CALL_FLAGS = /* @__PURE__ */ new Set([
   "library",
   "metro-port",
   "platform",
-  "project-root",
   "slot",
+  "source-digest",
+  "source-kind",
+  "source-name",
+  "source-trust",
   "target",
   "validation-runtime-dir",
   "watcher-port"
@@ -373,6 +566,8 @@ function pickCallExampleAction(names) {
   return names[0] ?? "command";
 }
 export {
+  defaultCallArtifactsDir,
   handleCall,
-  handleCallHelp
+  handleCallHelp,
+  redactCallValue
 };

package/dist/commands/check.js

@@ -3,7 +3,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { detectAdapter } from "../harness.js";
 import { EXIT, usageOut } from "./shared.js";
-import { optionFlag, optionString, parseArgs } from "./parse-args.js";
+import { optionFlag, optionString, parseArgs, shellQuote } from "./parse-args.js";
 const USAGE = "mm-harness check diff [--fix] [--target <repo>] [--adapter mobile|extension|core] [--base <ref>] [--profile fast|full] [--artifacts-dir <dir>] [--json]";
 const JS_TS_EXT_RE = /\.(?:c|m)?jsx?$|\.tsx?$/u;
 const FORMAT_EXT_RE = /\.(?:c|m)?jsx?$|\.tsx?$|\.json$|\.md$|\.css$|\.scss$|\.ya?ml$/u;
@@ -18,7 +18,7 @@ async function handleCheck(argv) {
     const message = action ? `unknown action '${action}'` : "missing action";
     return usageOut(json, "check", message, USAGE);
   }
-  const target = path.resolve(optionString(options, "target") ?? optionString(options, "projectRoot") ?? process.cwd());
+  const target = path.resolve(optionString(options, "target") ?? process.cwd());
   const explicitAdapter = optionString(options, "adapter") ?? optionString(options, "platform");
   const detected = explicitAdapter ?? detectAdapter(target);
   if (detected && !["mobile", "extension", "core"].includes(detected)) {
@@ -111,6 +111,7 @@ async function handleCheck(argv) {
   const status = [...fixes, ...checks].some((check) => check.status === "fail") ? "fail" : "pass";
   const exitCode = status === "pass" ? EXIT.ok : EXIT.validation;
   const guidance = policyFailed ? ["Remove the newly added eslint-disable directive(s). Fix the underlying violation with existing named styles, project tokens, or another established source pattern; then rerun mm-harness check diff [--fix]. Other checks were skipped until this policy failure is removed."] : checks.some((check) => check.id === "eslint" && check.status === "fail") ? ["Fix the reported violations in changed source using existing project patterns and tokens; do not suppress rules, hide violations behind indirection, weaken configuration, or bypass check diff. Then rerun mm-harness check diff [--fix]."] : [];
+  const failureUserAction = guidance[0] ?? `inspect ${path.join(artifactsDir, "validation-summary.json")}, fix the failing check, then retry: mm-harness check diff --target ${shellQuote(target)} --base ${shellQuote(baseRef)} --profile ${profile} --json`;
   const summary = {
     schemaVersion: 1,
     command: "check",
@@ -129,6 +130,7 @@ async function handleCheck(argv) {
     fixes,
     checks,
     guidance,
+    ...status === "fail" ? { error: { code: "CHECK_DIFF_FAILED", message: "one or more bounded checks failed", userAction: failureUserAction } } : {},
     artifacts: {
       dir: artifactsDir,
       summaryJson: path.join(artifactsDir, "validation-summary.json"),
@@ -518,10 +520,14 @@ function renderHuman(summary) {
     if (check.status === "fail" && check.logPath) console.log(`    log: ${check.logPath}`);
   }
   for (const item of summary.guidance) console.log(`  Next: ${item}`);
+  if (summary.guidance.length === 0 && summary.status === "fail" && summary.error?.userAction) {
+    console.log(`  Next: ${summary.error.userAction}`);
+  }
   console.log(`Artifacts: ${summary.artifacts.summaryJson}`);
 }
 function failEnvelope(input) {
   const exitCode = EXIT.usage;
+  const userAction = USAGE;
   const body = {
     schemaVersion: 1,
     command: "check",
@@ -534,11 +540,11 @@ function failEnvelope(input) {
     baseRef: input.baseRef,
     baseSource: "unknown",
     artifacts: { dir: input.artifactsDir },
-    error: { code: input.code, message: input.message }
+    error: { code: input.code, message: input.message, userAction }
   };
   if (input.json) console.log(JSON.stringify(body, null, 2));
   else console.error(`\u2717 check diff: ${input.message}
-  Next: ${USAGE}`);
+  Next: ${userAction}`);
   return exitCode;
 }
 export {

package/dist/commands/completion-candidates.js

@@ -1,25 +1,26 @@
-import { loadActionManifest } from "../manifest.js";
+import { resolveActionManifest } from "../manifest.js";
 import {
   invalidateCompletionCache,
   readFreshCandidates,
   writeCompletionCandidates
 } from "../completions-cache.js";
-import { importRecipeHarness, importRecipeProtocol } from "../paths.js";
+import { importRecipeProtocol } from "../paths.js";
 import { EXIT } from "./shared.js";
 import {
   parseArgs,
   optionFlag,
   optionString,
+  optionStrings,
   resolveAdapter,
   targetPath
 } from "./parse-args.js";
-import { resolveMetaMaskLibrarySources } from "./run-engine.js";
+import { listRunnableRecipes, resolveMetaMaskLibrarySources } from "./run-engine.js";
 async function handleCompletionCandidates(argv) {
   const kind = argv[0];
   const { options } = parseArgs(argv.slice(1), "completion-candidates");
   const json = optionFlag(options, "json");
-  if (kind !== "actions" && kind !== "flows") {
-    console.error("completion-candidates requires <actions|flows>.");
+  if (kind !== "actions" && kind !== "recipes") {
+    console.error("completion-candidates requires <actions|recipes>.");
     return EXIT.usage;
   }
   const target = targetPath(options);
@@ -27,25 +28,19 @@ async function handleCompletionCandidates(argv) {
   let candidates;
   if (kind === "actions") {
     adapter = resolveAdapter(options).adapter;
-    candidates = readFreshCandidates(target, "actions");
-    if (!candidates) {
-      const manifest = loadActionManifest(adapter, optionString(options, "actionManifest"));
-      const { getRecipeActionManifestActionNames } = await importRecipeProtocol();
-      candidates = getRecipeActionManifestActionNames(manifest);
-      writeCompletionCandidates(target, "actions", candidates);
-    }
+    const sources = await resolveMetaMaskLibrarySources(optionStrings(options, "library"));
+    const { manifest } = await resolveActionManifest(adapter, optionString(options, "actionManifest"), sources);
+    const { getRecipeActionManifestActionNames } = await importRecipeProtocol();
+    candidates = getRecipeActionManifestActionNames(manifest);
+    writeCompletionCandidates(target, "actions", candidates);
   } else {
-    candidates = readFreshCandidates(target, "flows");
+    adapter = resolveAdapter(options).adapter;
+    const cacheKey = `recipes:${adapter}`;
+    candidates = readFreshCandidates(target, cacheKey);
     if (!candidates) {
-      const sources = await resolveMetaMaskLibrarySources(void 0).catch(() => void 0);
-      if (!sources) {
-        candidates = [];
-      } else {
-        const harness = await importRecipeHarness();
-        const resolution = await harness.loadRecipeLibraries(sources);
-        candidates = [...resolution.flows.keys()].sort();
-        writeCompletionCandidates(target, "flows", candidates);
-      }
+      const sources = await resolveMetaMaskLibrarySources(optionStrings(options, "library")).catch(() => void 0);
+      candidates = sources ? (await listRunnableRecipes(adapter, sources)).map((recipe) => recipe.name) : [];
+      writeCompletionCandidates(target, cacheKey, candidates);
     }
   }
   if (json) console.log(JSON.stringify({ schemaVersion: 1, kind, adapter, candidates }, null, 2));