@deeeed/metamask-harness 0.17.5 → 0.19.0

package/dist/commands/run-report.js

@@ -25,10 +25,19 @@ function renderRunReport(summary, entries) {
     "",
     `Status: ${String(summary.status ?? "unknown")}`,
     `Duration: ${formatDuration(Number(summary.durationMs ?? 0))}`,
-    `Nodes: ${Number(summary.passed ?? 0)}/${Number(summary.total ?? entries.length)} passed`,
-    "",
-    "## Steps"
+    `Nodes: ${Number(summary.passed ?? 0)}/${Number(summary.total ?? entries.length)} passed`
   ];
+  const sideFindings = isRecord(summary.sideFindings) ? summary.sideFindings : void 0;
+  const sideFindingCounts = sideFindings && isRecord(sideFindings.counts) ? sideFindings.counts : void 0;
+  const sideFindingTotal = Number(sideFindingCounts?.total ?? 0);
+  if (sideFindingTotal > 0) {
+    lines.push(
+      "",
+      "## Side findings",
+      `- REVIEW ${sideFindingTotal} distinct application warning/error event(s) (non-blocking; expanded below and stored in diagnostics.json)`
+    );
+  }
+  lines.push("", "## Steps");
   for (const entry of entries) {
     if (!isRecord(entry)) continue;
     const mark = entry.ok === false ? "FAIL" : "PASS";

package/dist/commands/run.js

@@ -3,85 +3,283 @@ import path from "node:path";
 import { walletFixturePath } from "../paths.js";
 import { color } from "../cli-color.js";
 import { recipeRunning } from "../heal-bounds.js";
-import { EXIT } from "./shared.js";
+import { checkoutBusyOut, EXIT, usageOut, writeInteractiveProgress } from "./shared.js";
 import {
   optionFlag,
   optionString,
-  requiredOption,
   resolveAdapter,
   runtimeOptionsFromCli,
   isRecord,
+  parseRecipeParamAssignments,
+  shellQuote,
+  targetPath,
   usageError
 } from "./parse-args.js";
 import {
   countRecipeNodes,
   emitHealViolation,
   executeWithHealBounds,
+  preflightRecipe,
   prepareHeal,
   recoverRunInfra,
   runRecipe,
   validateRunRecipeStatic
 } from "./run-engine.js";
-import { handleListExecutables } from "./list-executables.js";
+import { handleDescribeRecipe, handleListExecutables } from "./list-executables.js";
 import { applyDeviceTargeting } from "./device-target.js";
 import { getAdapterSurface } from "../adapters/surface.js";
 import { coreDependencyBlock } from "./core-readiness.js";
 import { writeRunReport } from "./run-report.js";
 import { acquireCheckoutLock } from "../checkout-lock.js";
-async function handleRun({ positional, options }) {
-  if (optionFlag(options, "list")) return handleListExecutables("run", options);
+import { JsonStreamWriter } from "../json-stream.js";
+import { formatRunDiagnosticsForHuman, readRunDiagnosticsDocument } from "../run-diagnostics.js";
+import { recipeTrustFailure } from "../recipe-security.js";
+import { recordCommandEvidence, redactStructuredValue } from "../command-journal.js";
+async function handleRun(parsed) {
+  const stream = new JsonStreamWriter("run", optionFlag(parsed.options, "jsonStream"));
+  const restoreStdout = stream.isolateStdout();
+  const target = targetPath(parsed.options);
+  try {
+    const exitCode = await handleRunInner(parsed, stream);
+    stream.complete(exitCode === EXIT.ok ? "pass" : "fail", exitCode);
+    return exitCode;
+  } catch (error) {
+    const trustFailure = recipeTrustFailure(error);
+    if (trustFailure) {
+      if (stream.enabled) {
+        stream.error(trustFailure);
+        stream.complete("fail", EXIT.validation);
+      } else if (optionFlag(parsed.options, "json")) {
+        console.log(JSON.stringify({
+          schemaVersion: 1,
+          command: "run",
+          status: "fail",
+          error: trustFailure,
+          exitCode: EXIT.validation
+        }, null, 2));
+      } else {
+        console.error(`\u2717 mm-harness run: ${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 exitCode = error !== null && typeof error === "object" && "exitCode" in error && typeof error.exitCode === "number" ? error.exitCode : EXIT.runtime;
+    stream.error({
+      code: exitCode === EXIT.usage ? "CLI_USAGE_ERROR" : "RUN_FAILED",
+      message: error instanceof Error ? error.message : String(error),
+      userAction: `mm-harness doctor --target ${shellQuote(target)} --json`
+    });
+    stream.complete("fail", exitCode);
+    throw error;
+  } finally {
+    restoreStdout();
+  }
+}
+async function handleRunInner({ positional, options }, stream) {
+  if (optionFlag(options, "describe") && (optionFlag(options, "list") || optionFlag(options, "plan"))) {
+    const message = "--describe cannot be combined with --list or --plan.";
+    const userAction = "choose one: mm-harness run --list, mm-harness run <recipe> --describe, or mm-harness run <recipe> --plan";
+    if (stream.enabled) {
+      stream.error({ code: "CLI_USAGE_ERROR", message, userAction });
+      return EXIT.usage;
+    }
+    return usageOut(optionFlag(options, "json"), "run", message, userAction);
+  }
+  if (optionFlag(options, "list")) {
+    if (stream.enabled) {
+      const message = "--json-stream is for recipe execution; use run --list --json for discovery.";
+      stream.error({ code: "JSON_STREAM_UNSUPPORTED_MODE", message, userAction: "mm-harness run --list --json" });
+      return EXIT.usage;
+    }
+    return handleListExecutables("run", options);
+  }
   const targetRecipe = positional[0];
   if (!targetRecipe) throw usageError("run requires <recipe.json>.");
-  if (optionFlag(options, "plan")) return handleRunPlan(targetRecipe, options);
+  const paramAssignments = positional.slice(1);
+  if (optionFlag(options, "describe")) {
+    if (paramAssignments.length > 0) {
+      throw usageError("run --describe does not accept parameter values; inspect the declaration first.");
+    }
+    if (stream.enabled) {
+      const message = "--json-stream is for recipe execution; use --describe --json for discovery.";
+      stream.error({
+        code: "JSON_STREAM_UNSUPPORTED_MODE",
+        message,
+        userAction: `mm-harness run ${shellQuote(targetRecipe)} --describe --json`
+      });
+      return EXIT.usage;
+    }
+    return handleDescribeRecipe(targetRecipe, options);
+  }
+  const params = parseRecipeParamAssignments(paramAssignments);
+  if (optionFlag(options, "plan")) return handleRunPlan(targetRecipe, params, options, stream);
   const { adapter, target } = resolveAdapter(options);
   const json = optionFlag(options, "json");
+  const jsonOutput = json && !stream.enabled;
+  const machine = json || stream.enabled;
+  stream.phase("resolve", { adapter, target, recipe: targetRecipe });
+  if (!fs.existsSync(target)) {
+    const message = `target does not exist: ${target}`;
+    const userAction = "pass --target <metamask-checkout> pointing to an existing checkout";
+    if (stream.enabled) {
+      stream.error({ code: "TARGET_NOT_FOUND", message, userAction });
+      return EXIT.usage;
+    }
+    return usageOut(jsonOutput, "run", message, userAction);
+  }
+  writeInteractiveProgress(machine, `\u2192 recipe run \u2014 validating ${targetRecipe} \xB7 ${adapter}`);
   getAdapterSurface(adapter).resolveSlotPorts(target);
   const dtResult = applyDeviceTargeting("run", adapter, options, { gate: true, rerun: "" });
   if ("code" in dtResult) {
-    return emitRunUsageError(json, adapter, targetRecipe, dtResult.code, dtResult.message);
+    return emitRunUsageError(jsonOutput, stream, adapter, targetRecipe, dtResult.code, dtResult.message, dtResult.userAction);
   }
-  if (recipeRunning(target)) return emitRunRecipeRunning(json);
-  if (optionString(options, "artifactsDir") === void 0 && runArgLooksLikeRecipeFile(targetRecipe)) {
-    requiredOption(options, "artifactsDir", "run requires --artifacts-dir <dir>.");
-  }
-  const validated = await validateRunRecipeStatic(targetRecipe, adapter, options);
+  if (recipeRunning(target)) return emitRunRecipeRunning(jsonOutput, stream, target);
+  stream.phase("validate");
+  const validated = await validateRunRecipeStatic(targetRecipe, adapter, options, params);
   if (validated.usageError) {
-    return emitRunUsageError(json, adapter, validated.recipeFile, validated.usageError.code, validated.usageError.message);
+    const userAction = runUsageRecovery(
+      validated.usageError.code,
+      validated.usageError.message,
+      adapter,
+      validated.recipeFile
+    );
+    return emitRunUsageError(
+      jsonOutput,
+      stream,
+      adapter,
+      validated.recipeFile,
+      validated.usageError.code,
+      validated.usageError.message,
+      userAction
+    );
   }
   if (validated.errorCount > 0) {
-    return emitRunValidationError(json, adapter, validated.recipeFile, validated.findings, validated.errorCount);
+    return emitRunValidationError(jsonOutput, stream, adapter, validated.recipeFile, validated.findings, validated.errorCount);
   }
-  const depsBlock = adapter === "core" && recipeUsesCoreController(validated.recipe, validated.librarySources) ? coreDependencyBlock(target) : null;
+  const depsBlock = adapter === "core" && await recipeUsesCoreController(validated.recipe, validated.librarySources) ? coreDependencyBlock(target) : null;
   if (depsBlock) {
-    return emitRunUsageError(json, adapter, validated.recipeFile, depsBlock.code, depsBlock.message, depsBlock.userAction);
+    return emitRunUsageError(jsonOutput, stream, adapter, validated.recipeFile, depsBlock.code, depsBlock.message, depsBlock.userAction);
   }
-  const artifactsDir = requiredOption(options, "artifactsDir", "run requires --artifacts-dir <dir>.");
+  let artifactsDir;
+  try {
+    artifactsDir = resolveRunArtifactsDir(target, optionString(options, "artifactsDir"));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return emitRunUsageError(
+      jsonOutput,
+      stream,
+      adapter,
+      validated.recipeFile,
+      "ARTIFACT_DIR_INVALID",
+      message,
+      "set RECIPE_TASK_DIR/FARMSLOT_TASK_DIR inside the checkout or pass --artifacts-dir <path>"
+    );
+  }
+  recordCommandEvidence(artifactsDir);
+  const librarySources = validated.librarySources;
+  const runtimeOptions = {
+    ...runtimeOptionsFromCli(options),
+    params,
+    ...librarySources ? { librarySources } : {},
+    stdoutIsMachineContract: machine,
+    onActionEvent: ({ nodeId, action, status }) => stream.node(nodeId, action, status)
+  };
+  stream.phase("authorize");
+  let preflightedExecution = await preflightRecipe(
+    adapter,
+    validated.recipeFile,
+    artifactsDir,
+    target,
+    optionString(options, "actionManifest"),
+    runtimeOptions
+  );
   const lock = acquireCheckoutLock(target, "run");
-  if ("message" in lock) return emitRunRecipeRunning(json, lock.message);
+  if ("message" in lock) {
+    const userAction = `wait for the current owner, or inspect ${lock.path} if its process has exited`;
+    stream.error({ code: "SANDBOX_BUSY", message: lock.message, userAction });
+    return checkoutBusyOut(jsonOutput, "run", lock.message, lock.path);
+  }
   try {
-    const prepared = await prepareHeal(adapter, target, options, json);
-    if (typeof prepared === "number") return prepared;
+    const prepared = await prepareHeal(adapter, target, options, machine, {
+      onPhase: (phase, fields) => stream.phase(phase, fields)
+    });
+    if (typeof prepared === "number") {
+      stream.error({
+        code: "RUN_PREPARE_FAILED",
+        message: "runtime preparation failed; inspect stderr for the exact probe",
+        userAction: `mm-harness doctor --fix --adapter ${adapter} --target ${shellQuote(target)} --json`
+      });
+      return prepared;
+    }
     const { state, heal } = prepared;
-    const librarySources = validated.librarySources;
-    const runtimeOptions = {
-      ...runtimeOptionsFromCli(options),
-      ...librarySources ? { librarySources } : {},
-      stdoutIsMachineContract: json
-    };
+    stream.phase("execute");
     const { result, violation } = await executeWithHealBounds(
       // validated.recipeFile, not the raw arg: the arg may be a library recipe NAME
       // that only the resolver knows how to turn into a file.
-      () => runRecipe(adapter, validated.recipeFile, artifactsDir, target, optionString(options, "actionManifest"), runtimeOptions),
+      () => {
+        const execution = preflightedExecution;
+        preflightedExecution = void 0;
+        return runRecipe(
+          adapter,
+          validated.recipeFile,
+          artifactsDir,
+          target,
+          optionString(options, "actionManifest"),
+          runtimeOptions,
+          execution
+        );
+      },
       adapter,
       target,
       heal,
       state,
-      () => recoverRunInfra(adapter, target, json)
+      () => recoverRunInfra(adapter, target, machine),
+      (code) => stream.phase("recover", { code })
     );
-    if (violation !== null) return emitHealViolation(json, "run", result, violation, state, adapter);
+    for (const mutation of state.mutations) stream.mutation(mutation);
+    for (const recovery of state.recovered) stream.recovery(recovery);
+    if (violation !== null) {
+      const userAction = violation.userAction ?? `inspect ${shellQuote(result.summaryPath)} and ${shellQuote(result.tracePath)}; fix the application or recipe failure before retrying`;
+      stream.error({
+        code: violation.code,
+        message: violation.message,
+        userAction,
+        originalError: violation.originalError ?? null
+      });
+      return emitHealViolation(jsonOutput, "run", result, violation, state, adapter);
+    }
     const report = writeRunReport(result);
     const exitCode = result.status === "pass" ? EXIT.ok : EXIT.runtime;
-    if (json) {
+    const failureUserAction = `mm-harness last --target ${shellQuote(target)} --json`;
+    if (stream.enabled) {
+      if (result.status === "fail") {
+        stream.error({
+          code: "RECIPE_EXECUTION_FAILED",
+          message: "recipe execution failed; inspect the persisted result and evidence paths",
+          userAction: failureUserAction
+        });
+      }
+      stream.complete(result.status === "pass" ? "pass" : "fail", exitCode, {
+        adapter,
+        reportPath: report.path,
+        summaryPath: result.summaryPath,
+        tracePath: result.tracePath,
+        artifactManifestPath: result.artifactManifestPath,
+        recovered: state.recovered,
+        mutations: state.mutations
+      });
+    } else if (json) {
       console.log(
         JSON.stringify(
           {
@@ -93,7 +291,8 @@ async function handleRun({ positional, options }) {
             recovered: state.recovered,
             mutations: state.mutations,
             reportPath: report.path,
-            result
+            result,
+            ...result.status === "fail" ? { error: { code: "RECIPE_EXECUTION_FAILED", message: "recipe execution failed; inspect the persisted result and evidence paths", userAction: failureUserAction } } : {}
           },
           null,
           2
@@ -106,14 +305,75 @@ async function handleRun({ positional, options }) {
         console.log(out("label", "summary:"));
         for (const line of report.preview) console.log(`  ${formatPreviewLine(line, out)}`);
       }
-      console.log(`${out("label", "report:")} ${out("path", report.path)}`);
-      console.log(`${out("label", "artifacts:")} ${out("path", result.artifactManifestPath)}`);
+      const artifacts = runArtifactInventory(result.artifactManifestPath);
+      console.log(out("label", `artifacts (${artifacts.length}):`));
+      for (const artifact of artifacts) {
+        console.log(`  ${out("dim", `${artifact.label}:`)} ${out("path", artifact.absolutePath)}`);
+      }
+      if (result.status === "fail") {
+        console.error(`  Next: ${failureUserAction}`);
+      }
+      console.log(out("label", "diagnostics:"));
+      const diagnostics = readRunDiagnosticsDocument(result.diagnosticsPath);
+      for (const line of formatRunDiagnosticsForHuman(diagnostics, adapter)) {
+        console.log(`  ${formatDiagnosticLine(line, out)}`);
+      }
     }
     return exitCode;
   } finally {
     lock.release();
   }
 }
+function formatDiagnosticLine(line, out) {
+  const match = /^(CLEAN|REVIEW|UNAVAILABLE|N\/A|WARNING|ERROR|EXCEPTION)(.*)$/u.exec(line);
+  if (!match) return line;
+  const status = match[1];
+  const style = status === "CLEAN" ? "ok" : status === "ERROR" || status === "EXCEPTION" ? "err" : "warn";
+  return `${out(style, status)}${match[2]}`;
+}
+function resolveRunArtifactsDir(target, explicit) {
+  if (explicit !== void 0) return path.resolve(explicit);
+  const taskDir = process.env.RECIPE_TASK_DIR || process.env.FARMSLOT_TASK_DIR;
+  if (taskDir) {
+    const resolvedTask = path.resolve(target, taskDir);
+    const relative = path.relative(path.resolve(target), resolvedTask);
+    if (!relative.startsWith(`..${path.sep}`) && relative !== "..") {
+      return path.join(resolvedTask, "artifacts");
+    }
+    throw new Error(`task directory must be inside the target checkout: ${taskDir}`);
+  }
+  const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[-:.TZ]/gu, "");
+  return path.join(target, "temp", "recipe", "runs", `${stamp}-${process.pid}`);
+}
+function runArtifactInventory(manifestPathValue) {
+  const manifestPath = path.resolve(String(manifestPathValue));
+  const root = path.dirname(manifestPath);
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  } catch {
+    return [{ absolutePath: manifestPath, basename: path.basename(manifestPath), label: "Artifact manifest" }];
+  }
+  const entries = isRecord(manifest) && Array.isArray(manifest.artifacts) ? manifest.artifacts : [];
+  const artifacts = [];
+  for (const entry of entries) {
+    if (!isRecord(entry) || typeof entry.path !== "string" || entry.path.length === 0) continue;
+    const absolutePath = path.resolve(root, entry.path);
+    const basename = path.basename(absolutePath);
+    const label = typeof entry.label === "string" && entry.label.length > 0 ? entry.label : basename;
+    artifacts.push({ absolutePath, basename, label });
+  }
+  artifacts.push({ absolutePath: manifestPath, basename: path.basename(manifestPath), label: "Artifact manifest" });
+  const priority = /* @__PURE__ */ new Map([
+    ["diagnostics.json", 0],
+    ["report.md", 1],
+    ["summary.json", 2],
+    ["trace.json", 3],
+    ["recipe.json", 4],
+    ["artifact-manifest.json", 100]
+  ]);
+  return artifacts.filter((artifact, index, all) => all.findIndex((candidate) => candidate.absolutePath === artifact.absolutePath) === index).sort((left, right) => (priority.get(left.basename) ?? 50) - (priority.get(right.basename) ?? 50));
+}
 function formatPreviewLine(line, out) {
   const match = /^(PASS|FAIL)\s+(.+)$/u.exec(line);
   if (!match) return line;
@@ -121,19 +381,22 @@ function formatPreviewLine(line, out) {
   const rest = match[2];
   return `${out(status === "PASS" ? "ok" : "err", status)} ${rest}`;
 }
-function recipeUsesCoreController(recipe, librarySources) {
+async function recipeUsesCoreController(recipe, librarySources) {
   if (objectUsesCoreController(recipe)) return true;
   const refs = collectCallRefs(recipe);
   if (refs.length === 0) return false;
-  const flows = loadFlowCatalogs(librarySources ?? []);
+  const sources = librarySources ?? [];
+  if (sources.length === 0) return false;
+  const { loadRecipeLibraries } = await import("@farmslot/recipe-harness");
+  const recipes = (await loadRecipeLibraries(sources, { adapter: "core" })).recipes;
   const visited = /* @__PURE__ */ new Set();
   const visit = (ref) => {
     if (visited.has(ref)) return false;
     visited.add(ref);
-    const flow = flows.get(ref);
-    if (!flow) return false;
-    if (objectUsesCoreController(flow)) return true;
-    return collectCallRefs(flow).some(visit);
+    const dependency = recipes.get(ref);
+    if (!dependency) return false;
+    if (objectUsesCoreController(dependency.document)) return true;
+    return collectCallRefs(dependency.document).some(visit);
   };
   return refs.some(visit);
 }
@@ -157,42 +420,34 @@ function collectCallRefs(value) {
   visit(value);
   return [...new Set(refs)];
 }
-function loadFlowCatalogs(librarySources) {
-  const flows = /* @__PURE__ */ new Map();
-  for (const source of librarySources) {
-    const flowsDir = path.join(source.root, "flows");
-    let entries;
-    try {
-      entries = fs.readdirSync(flowsDir);
-    } catch {
-      continue;
-    }
-    for (const entry of entries) {
-      if (!entry.endsWith(".json")) continue;
-      try {
-        const parsed = JSON.parse(fs.readFileSync(path.join(flowsDir, entry), "utf8"));
-        if (!isRecord(parsed) || !isRecord(parsed.flows)) continue;
-        for (const [id, flow] of Object.entries(parsed.flows)) {
-          if (!flows.has(id)) flows.set(id, flow);
-        }
-      } catch {
-        continue;
-      }
-    }
-  }
-  return flows;
-}
 function actionUsesCoreController(action) {
   return typeof action === "string" && action.startsWith("metamask.perps.");
 }
-async function handleRunPlan(recipeArg, options) {
+async function handleRunPlan(recipeArg, params, options, stream) {
   const json = optionFlag(options, "json");
+  const jsonOutput = json && !stream.enabled;
   const { adapter, target } = resolveAdapter(options);
-  const validated = await validateRunRecipeStatic(recipeArg, adapter, options);
+  stream.phase("resolve", { adapter, target, recipe: recipeArg });
+  stream.phase("validate");
+  const validated = await validateRunRecipeStatic(recipeArg, adapter, options, params);
   if (validated.usageError) {
-    return emitPlanUsageError(json, adapter, validated.recipeFile, validated.usageError.code, validated.usageError.message);
+    const userAction = runUsageRecovery(
+      validated.usageError.code,
+      validated.usageError.message,
+      adapter,
+      validated.recipeFile
+    );
+    return emitPlanUsageError(
+      jsonOutput,
+      stream,
+      adapter,
+      validated.recipeFile,
+      validated.usageError.code,
+      validated.usageError.message,
+      userAction
+    );
   }
-  const { recipe, recipeFile, findings, errorCount, manifestOk, schemaValid } = validated;
+  const { recipe, recipeFile, findings, errorCount, manifestOk, schemaValid, effectiveParams } = validated;
   const status = errorCount === 0 ? "pass" : "fail";
   const nodeCount = countRecipeNodes(recipe);
   const artifactsDir = optionString(options, "artifactsDir");
@@ -244,9 +499,28 @@ async function handleRunPlan(recipeArg, options) {
       detail: nodeCount === void 0 ? "would execute the recipe nodes" : `would execute ${nodeCount} recipe node(s)`
     }
   ];
-  if (json) {
-    const payload = { schemaVersion: 1, command: "run", mode: "plan", status, adapter, recipe: recipeFile, findings, plan };
-    if (status === "fail") payload.error = { code: "RECIPE_VALIDATION_FAILED", message: `recipe validation found ${errorCount} error(s)` };
+  const payload = {
+    schemaVersion: 1,
+    command: "run",
+    mode: "plan",
+    status,
+    adapter,
+    recipe: recipeFile,
+    params: redactStructuredValue(effectiveParams),
+    findings,
+    plan
+  };
+  if (status === "fail") {
+    payload.error = {
+      code: "RECIPE_VALIDATION_FAILED",
+      message: `recipe validation found ${errorCount} error(s)`,
+      userAction: runPlanProbe(adapter, recipeFile)
+    };
+  }
+  if (stream.enabled) {
+    if (status === "fail") stream.error(payload.error);
+    stream.complete(status, status === "pass" ? EXIT.ok : EXIT.validation, { mode: "plan", adapter, recipe: recipeFile, findings, plan });
+  } else if (json) {
     console.log(JSON.stringify(payload, null, 2));
   } else {
     console.log(`plan ${status} \u2014 ${adapter} \u2014 ${recipeFile}`);
@@ -260,52 +534,58 @@ async function handleRunPlan(recipeArg, options) {
         console.log(`  ${finding.severity === "error" ? "\u2717" : "\u26A0"} ${finding.code} ${finding.path} \u2014 ${finding.message}`);
       }
     }
+    if (status === "fail") console.error(`  Next: ${runPlanProbe(adapter, recipeFile)}`);
   }
   return status === "pass" ? EXIT.ok : EXIT.validation;
 }
-function emitPlanUsageError(json, adapter, recipeFile, code, message) {
+function emitPlanUsageError(json, stream, adapter, recipeFile, code, message, userAction) {
+  stream.error({ code, message, userAction, mode: "plan", adapter, recipe: recipeFile });
   if (json) {
     console.log(
       JSON.stringify(
-        { schemaVersion: 1, command: "run", mode: "plan", status: "fail", adapter, recipe: recipeFile, error: { code, message } },
+        { schemaVersion: 1, command: "run", mode: "plan", status: "fail", adapter, recipe: recipeFile, error: { code, message, userAction } },
         null,
         2
       )
     );
   } else {
-    console.error(`\u2717 run --plan: ${message}`);
+    console.error(`\u2717 run --plan: ${message}
+  Next: ${userAction}`);
   }
   return EXIT.usage;
 }
-function runArgLooksLikeRecipeFile(value) {
-  return path.isAbsolute(value) || value.includes("/") || value.includes(path.sep) || value.endsWith(".json") || fs.existsSync(path.resolve(value));
-}
-function emitRunRecipeRunning(json, detail) {
+function emitRunRecipeRunning(json, stream, target, detail) {
   const message = detail ?? "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`;
+  stream.error({ code: "RECIPE_RUNNING", message, userAction, recoverable: false });
   if (json) {
-    console.log(JSON.stringify({ schemaVersion: 1, status: "fail", recoverable: false, error: { code: "RECIPE_RUNNING", message } }, null, 2));
+    console.log(JSON.stringify({ schemaVersion: 1, status: "fail", recoverable: false, error: { code: "RECIPE_RUNNING", message, userAction } }, null, 2));
   } else {
-    console.error(`\u2717 mm-harness: ${message}`);
+    console.error(`\u2717 mm-harness: ${message}
+  Next: ${userAction}`);
   }
   return EXIT.bounded;
 }
-function emitRunUsageError(json, adapter, recipeFile, code, message, userAction) {
+function emitRunUsageError(json, stream, adapter, recipeFile, code, message, userAction) {
+  stream.error({ code, message, userAction });
   if (json) {
     console.log(
       JSON.stringify(
-        { schemaVersion: 1, command: "run", adapter, status: "fail", exitCode: EXIT.usage, recipe: recipeFile, error: { code, message, ...userAction ? { userAction } : {} } },
+        { schemaVersion: 1, command: "run", adapter, status: "fail", exitCode: EXIT.usage, recipe: recipeFile, error: { code, message, userAction } },
         null,
         2
       )
     );
   } else {
     console.error(`\u2717 run: ${message}`);
-    if (userAction) console.error(`  Next: ${userAction}`);
+    console.error(`  Next: ${userAction}`);
   }
   return EXIT.usage;
 }
-function emitRunValidationError(json, adapter, recipeFile, findings, errorCount) {
+function emitRunValidationError(json, stream, adapter, recipeFile, findings, errorCount) {
   const message = `recipe validation found ${errorCount} error(s)`;
+  const userAction = runPlanProbe(adapter, recipeFile);
+  stream.error({ code: "RECIPE_VALIDATION_FAILED", message, userAction, findings });
   if (json) {
     console.log(
       JSON.stringify(
@@ -319,7 +599,7 @@ function emitRunValidationError(json, adapter, recipeFile, findings, errorCount)
           mutations: [],
           recipe: recipeFile,
           findings,
-          error: { code: "RECIPE_VALIDATION_FAILED", message }
+          error: { code: "RECIPE_VALIDATION_FAILED", message, userAction }
         },
         null,
         2
@@ -330,9 +610,22 @@ function emitRunValidationError(json, adapter, recipeFile, findings, errorCount)
     for (const finding of findings) {
       if (finding.severity === "error") console.error(`  ${finding.code} ${finding.path} \u2014 ${finding.message}`);
     }
+    console.error(`  Next: ${userAction}`);
   }
   return EXIT.validation;
 }
+function runPlanProbe(adapter, recipeFile) {
+  return `mm-harness run --plan ${shellQuote(recipeFile)} --adapter ${adapter} --json`;
+}
+function runUsageRecovery(code, message, adapter, recipeFile) {
+  const actionCommand = /This is an action, not a recipe\. Use: (mm-harness call .+)\.$/u.exec(message)?.[1];
+  if (actionCommand) return actionCommand;
+  if (code === "RECIPE_NOT_FOUND") return `mm-harness run --list --adapter ${adapter} --json`;
+  if (code === "RECIPE_UNPARSEABLE") {
+    return `fix the JSON syntax in ${shellQuote(recipeFile)}, then retry: ${runPlanProbe(adapter, recipeFile)}`;
+  }
+  return runPlanProbe(adapter, recipeFile);
+}
 export {
   handleRun
 };