@deeeed/metamask-harness 0.15.2 → 0.17.0

package/dist/commands/provision.js

@@ -1,7 +1,7 @@
 import { detectAdapter } from "../harness.js";
 import { assertAdapter } from "../paths.js";
 import { getAdapterSurface } from "../adapters/surface.js";
-import { ADAPTER_DETECT_NEXT, usageOut } from "./shared.js";
+import { ADAPTER_DETECT_NEXT, usageOut, writeInteractiveProgress } from "./shared.js";
 import {
   applyWatcherPortOption,
   optionFlag,
@@ -25,9 +25,13 @@ async function handleProvision({ positional, options, rawArgv }) {
   }
   const surface = getAdapterSurface(adapter);
   const rerunCommand = provisionRerunCommand(rawArgv, options, adapter, target);
+  const platform = optionString(options, "platform") ?? optionString(options, "devicePlatform") ?? (positional[0] === "runway" ? positional[1] : positional[0]) ?? "ios";
+  if (adapter === "mobile") {
+    writeInteractiveProgress(json, `\u2192 provision mobile ${platform} \u2014 resolving simulator and Runway artifact`);
+  }
   const result = await surface.runwayProvision.run(target, {
     json,
-    platform: optionString(options, "platform") ?? optionString(options, "devicePlatform") ?? (positional[0] === "runway" ? positional[1] : positional[0]) ?? "ios",
+    platform,
     branch: optionString(options, "branch"),
     defaultBranch: optionString(options, "defaultBranch"),
     run: optionString(options, "run"),
@@ -42,8 +46,10 @@ async function handleProvision({ positional, options, rawArgv }) {
     resolveOnly: optionFlag(options, "resolveOnly"),
     rerunCommand
   });
+  const next = result.status === "pass" && adapter === "mobile" && result.resolveOnly !== true ? `mm-harness launch ${String(result.platform ?? platform)} --adapter mobile --target ${shellQuote(target)}` : void 0;
+  const output = next ? { ...result, next } : result;
   if (json) {
-    console.log(JSON.stringify(result, null, 2));
+    console.log(JSON.stringify(output, null, 2));
   } else if (result.status === "pass") {
     const cache = typeof result.cache === "object" && result.cache ? result.cache : void 0;
     const simulator = typeof result.simulator === "object" && result.simulator ? result.simulator : void 0;
@@ -54,6 +60,7 @@ async function handleProvision({ positional, options, rawArgv }) {
       const action = result.skipped ? "already provisioned" : "provisioned";
       console.error(`\u2713 ${action} ${adapter} ${result.platform ?? ""} simulator=${simulator?.name ?? "unknown"} cache=${cache?.status ?? "unknown"}`);
     }
+    if (next) console.error(`  Next: ${next}`);
   } else {
     console.error(`\u2717 mm-harness provision: ${result.error?.message ?? "provision failed"}
   Next: ${result.error?.userAction ?? rerunCommand}`);

package/dist/commands/run-engine.js

@@ -20,12 +20,18 @@ import {
 import { captureHelperSupportsRecordSessionSnapshots } from "../recording-target.js";
 import { listRecipeFiles } from "../recipe-files.js";
 import { startRecipeRecording, stopRecipeRecording } from "../run-recording.js";
+import {
+  beginRunDiagnostics,
+  finishRunDiagnostics,
+  stopRunDiagnostics
+} from "../run-diagnostics.js";
 import { EXIT } from "./shared.js";
 import {
   actionManifestPathOption,
   optionString,
   isRecord,
   shellQuoteArg,
+  targetPath,
   usageError
 } from "./parse-args.js";
 async function runRecipe(adapter, recipe, artifactsDir, projectRoot, actionManifestPath, runtimeOptions = {}) {
@@ -49,6 +55,7 @@ async function runRecipe(adapter, recipe, artifactsDir, projectRoot, actionManif
   try {
     await prepareRuntimeIfNeeded(adapter, projectRoot, runtimeOptions);
     const absoluteArtifactsDir = path.resolve(artifactsDir);
+    const diagnosticBaseline = await beginRunDiagnostics(adapter, projectRoot);
     const recordVideo = runtimeOptions.recordVideo ?? false;
     const useFramedExtensionRecording = adapter === "extension" && recordVideo === "full-run" && captureHelperSupportsRecordSessionSnapshots(projectRoot);
     const recording = useFramedExtensionRecording ? await startRecipeRecording(adapter, projectRoot, absoluteArtifactsDir, {
@@ -60,7 +67,8 @@ async function runRecipe(adapter, recipe, artifactsDir, projectRoot, actionManif
       await validateManifest(manifest);
       const { createMetaMaskRunner } = await import("../runner.js");
       const runner = await createMetaMaskRunner(adapter, manifest, {
-        quietStdout: runtimeOptions.stdoutIsMachineContract === true
+        quietStdout: runtimeOptions.stdoutIsMachineContract === true,
+        onActionEvent: runtimeOptions.onActionEvent
       });
       const runRequest = {
         recipePath: path.resolve(recipe),
@@ -80,8 +88,9 @@ async function runRecipe(adapter, recipe, artifactsDir, projectRoot, actionManif
         }
       }
       await stopRecipeRecording(recording, result);
-      return result;
+      return finishRunDiagnostics(diagnosticBaseline, result);
     } finally {
+      stopRunDiagnostics(diagnosticBaseline);
       await stopRecipeRecording(recording);
     }
   } finally {
@@ -341,6 +350,7 @@ async function actionInsteadOfRecipeHint(recipeArg, adapter, options) {
     const device = optionString(options, "device");
     const actionManifest = optionString(options, "actionManifest");
     const parts = ["mm-harness", "call", matches[0]];
+    parts.push("--adapter", adapter, "--target", shellQuoteArg(targetPath(options)));
     if (device) parts.push("--device", shellQuoteArg(device));
     if (actionManifest) parts.push("--action-manifest", shellQuoteArg(actionManifest));
     return ` This is an action, not a recipe. Use: ${parts.join(" ")}.`;
@@ -398,10 +408,12 @@ async function runOneNode(adapter, action, args, target, actionManifest) {
 async function prepareHeal(adapter, target, options, json, prepareOptions = {}) {
   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 ${shellQuoteArg(target)} --json; retry after the active recipe finishes`;
     if (json) {
-      console.log(JSON.stringify({ schemaVersion: 1, status: "fail", recoverable: false, error: { code: "RECIPE_RUNNING", message: msg } }, null, 2));
+      console.log(JSON.stringify({ schemaVersion: 1, status: "fail", recoverable: false, error: { code: "RECIPE_RUNNING", message: msg, userAction } }, null, 2));
     } else {
-      console.error(`\u2717 mm-harness: ${msg}`);
+      console.error(`\u2717 mm-harness: ${msg}
+  Next: ${userAction}`);
     }
     return EXIT.bounded;
   }
@@ -414,21 +426,25 @@ async function prepareHeal(adapter, target, options, json, prepareOptions = {})
     return EXIT.usage;
   }
   const state = newHealState();
+  prepareOptions.onPhase?.("install");
   const ensured = await ensureOverlay(adapter, target, heal, state, json);
   if (!ensured.ok) {
+    const userAction = `mm-harness install --adapter ${adapter} --target ${shellQuoteArg(target)}`;
     if (json) {
       console.log(
         JSON.stringify(
-          { schemaVersion: 1, status: "fail", recoverable: false, mutations: state.mutations, error: { code: "OVERLAY_INSTALL_FAILED", message: ensured.error } },
+          { schemaVersion: 1, status: "fail", recoverable: false, mutations: state.mutations, error: { code: "OVERLAY_INSTALL_FAILED", message: ensured.error, userAction } },
           null,
           2
         )
       );
     } else {
-      console.error(`\u2717 overlay auto-ensure failed: ${ensured.error}`);
+      console.error(`\u2717 overlay auto-ensure failed: ${ensured.error}
+  Next: ${userAction}`);
     }
     return EXIT.infra;
   }
+  prepareOptions.onPhase?.("healthcheck");
   if (adapter === "extension") {
     const previousCdpPort = process.env.CDP_PORT;
     const previousRecipeCdpPort = process.env.RECIPE_CDP_PORT;
@@ -441,7 +457,9 @@ async function prepareHeal(adapter, target, options, json, prepareOptions = {})
     }
     if (explicitWatcherPort) process.env.WATCHER_PORT = explicitWatcherPort;
     try {
-      const current = await ensureExtensionProofRuntime(target, heal, state, json);
+      const current = await ensureExtensionProofRuntime(target, heal, state, json, {
+        onRecovery: (code) => prepareOptions.onPhase?.("recover", { code })
+      });
       if (current !== null) return current;
     } finally {
       restoreEnv("CDP_PORT", previousCdpPort);
@@ -450,7 +468,9 @@ async function prepareHeal(adapter, target, options, json, prepareOptions = {})
     }
   }
   if (adapter === "mobile" && prepareOptions.skipMobileSourceFreshness !== true) {
-    const current = await ensureMobileProofRuntime(target, heal, state, json);
+    const current = await ensureMobileProofRuntime(target, heal, state, json, {
+      onRecovery: (code) => prepareOptions.onPhase?.("recover", { code })
+    });
     if (current !== null) return current;
   }
   return { state, heal };
@@ -495,6 +515,7 @@ async function ensureMobileProofRuntime(target, heal, state, json, deps = {}) {
   }
   const recoveryCode = "mobile.source_reloaded";
   state.attemptedRecoveries.push(recoveryCode);
+  deps.onRecovery?.(recoveryCode);
   if (!json) console.error(`\u2192 Mobile proof preflight: source ${initial.status}; restarting the app before execution`);
   const restart = deps.restart ?? (async () => {
     const result2 = await runOneNode(
@@ -581,6 +602,7 @@ async function ensureExtensionProofRuntime(target, heal, state, json, deps = {})
   }
   const recoveryCode = tier === "build" ? "extension.runtime_rebuilt" : "extension.runtime_reloaded";
   state.attemptedRecoveries.push(recoveryCode);
+  deps.onRecovery?.(recoveryCode);
   if (!json) console.error(`\u2192 Extension proof preflight: ${initial.reasonCode}; ${tier === "build" ? "rebuilding" : "reloading"} before execution`);
   const launch = deps.launch ?? (async (requestedTier) => {
     const { launchExtension } = await import("./launch/extension.js");
@@ -635,7 +657,7 @@ function readRunFailureText(result) {
     return "";
   }
 }
-async function executeWithHealBounds(exec, adapter, target, heal, state, recover = () => recoverRunInfra(adapter, target, false)) {
+async function executeWithHealBounds(exec, adapter, target, heal, state, recover = () => recoverRunInfra(adapter, target, false), onRecovery = () => void 0) {
   let result = await exec();
   for (; ; ) {
     if (result.status === "pass") return { result, violation: null };
@@ -644,6 +666,7 @@ async function executeWithHealBounds(exec, adapter, target, heal, state, recover
     if (heal === "off") return { result, violation: null };
     const recoveryCode = RUN_RECOVERY_CODE[adapter];
     state.attemptedRecoveries.push(recoveryCode);
+    onRecovery(recoveryCode);
     await recover();
     result = await exec();
     if (result.status === "pass") {
@@ -653,7 +676,7 @@ async function executeWithHealBounds(exec, adapter, target, heal, state, recover
   }
 }
 function emitHealViolation(json, command, result, violation, state, adapter) {
-  const userAction = adapter === "core" && violation.code === "WALLET_STATE_REQUIRED" ? 'set MM_TEST_ACCOUNT_ADDRESS=<0x\u2026> in env, or add "account": "<0x\u2026>" to the node block in the recipe' : violation.userAction;
+  const userAction = adapter === "core" && violation.code === "WALLET_STATE_REQUIRED" ? 'set MM_TEST_ACCOUNT_ADDRESS=<0x\u2026> in env, or add "account": "<0x\u2026>" to the node block in the recipe' : violation.userAction ?? `inspect ${shellQuoteArg(result.summaryPath)} and ${shellQuoteArg(result.tracePath)}; fix the application or recipe failure before retrying`;
   if (json) {
     console.log(
       JSON.stringify(
@@ -673,7 +696,7 @@ function emitHealViolation(json, command, result, violation, state, adapter) {
             code: violation.code,
             message: violation.message,
             retryable: false,
-            userAction: userAction ?? null,
+            userAction,
             originalError: violation.originalError ?? null
           }
         },

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); see diagnostics.json (non-blocking)`
+    );
+  }
+  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,7 +3,7 @@ import path from "node:path";
 import { walletFixturePath } from "../paths.js";
 import { color } from "../cli-color.js";
 import { recipeRunning } from "../heal-bounds.js";
-import { checkoutBusyOut, EXIT, usageOut } from "./shared.js";
+import { checkoutBusyOut, EXIT, usageOut, writeInteractiveProgress } from "./shared.js";
 import {
   optionFlag,
   optionString,
@@ -11,6 +11,8 @@ import {
   resolveAdapter,
   runtimeOptionsFromCli,
   isRecord,
+  shellQuote,
+  targetPath,
   usageError
 } from "./parse-args.js";
 import {
@@ -28,54 +30,118 @@ 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";
+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 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, "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);
+  if (optionFlag(options, "plan")) return handleRunPlan(targetRecipe, 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)) {
-    return usageOut(
-      json,
-      "run",
-      `target does not exist: ${target}`,
-      "pass --target <metamask-checkout> pointing to an existing checkout"
-    );
+    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 (recipeRunning(target)) return emitRunRecipeRunning(jsonOutput, stream, target);
   if (optionString(options, "artifactsDir") === void 0 && runArgLooksLikeRecipeFile(targetRecipe)) {
     requiredOption(options, "artifactsDir", "run requires --artifacts-dir <dir>.");
   }
+  stream.phase("validate");
   const validated = await validateRunRecipeStatic(targetRecipe, adapter, options);
   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;
   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>.");
   const lock = acquireCheckoutLock(target, "run");
-  if ("message" in lock) return checkoutBusyOut(json, "run", lock.message, lock.path);
+  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
+      stdoutIsMachineContract: machine,
+      onActionEvent: ({ nodeId, action, status }) => stream.node(nodeId, action, status)
     };
+    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.
@@ -84,12 +150,42 @@ async function handleRun({ positional, options }) {
       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(
           {
@@ -101,7 +197,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
@@ -116,6 +213,7 @@ async function handleRun({ positional, options }) {
       }
       console.log(`${out("label", "report:")} ${out("path", report.path)}`);
       console.log(`${out("label", "artifacts:")} ${out("path", result.artifactManifestPath)}`);
+      if (result.status === "fail") console.error(`  Next: ${failureUserAction}`);
     }
     return exitCode;
   } finally {
@@ -193,12 +291,29 @@ function loadFlowCatalogs(librarySources) {
 function actionUsesCoreController(action) {
   return typeof action === "string" && action.startsWith("metamask.perps.");
 }
-async function handleRunPlan(recipeArg, options) {
+async function handleRunPlan(recipeArg, options, stream) {
   const json = optionFlag(options, "json");
+  const jsonOutput = json && !stream.enabled;
   const { adapter, target } = resolveAdapter(options);
+  stream.phase("resolve", { adapter, target, recipe: recipeArg });
+  stream.phase("validate");
   const validated = await validateRunRecipeStatic(recipeArg, adapter, options);
   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 status = errorCount === 0 ? "pass" : "fail";
@@ -252,9 +367,27 @@ 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,
+    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}`);
@@ -268,52 +401,61 @@ 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(
@@ -327,7 +469,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
@@ -338,9 +480,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
 };

package/dist/commands/shared.js

@@ -3,6 +3,15 @@ import path from "node:path";
 import { detectAdapter } from "../harness.js";
 import { resolveLeafInvoke, shellLeafMissing } from "../leaf-invoke.js";
 const EXIT = { ok: 0, runtime: 1, usage: 2, infra: 3, bounded: 4, validation: 5 };
+function writeInteractiveProgress(json, message, {
+  stdoutIsTTY = Boolean(process.stdout.isTTY),
+  stream = process.stderr
+} = {}) {
+  if (json || !stdoutIsTTY) return false;
+  stream.write(`${message}
+`);
+  return true;
+}
 function parseFlags(argv, booleans) {
   const positional = [];
   const options = {};
@@ -262,5 +271,6 @@ export {
   spawnScriptStreaming,
   str,
   targetOf,
-  usageOut
+  usageOut,
+  writeInteractiveProgress
 };

package/dist/commands/status.js

@@ -31,7 +31,7 @@ async function handleStatus({ options }) {
   if (adapter === "mobile") {
     const dtResult = applyDeviceTargeting("status", adapter, options, { gate: false, rerun: "" });
     if ("code" in dtResult) {
-      return usageOut(json, "status", dtResult.message, "mm-harness status --device <id> or --all-devices");
+      return usageOut(json, "status", dtResult.message, dtResult.userAction);
     }
   }
   const next = surface.hints.relaunch;