@deeeed/metamask-harness 0.15.2 → 0.17.0

package/dist/command-journal.js

@@ -0,0 +1,225 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { recipeRuntimeDir } from "./paths.js";
+const COMMAND_JOURNAL_FILE = "last-command.json";
+const JOURNALED_COMMANDS = /* @__PURE__ */ new Set([
+  "call",
+  "check",
+  "checklist",
+  "cleanup",
+  "doctor",
+  "fixtures",
+  "install",
+  "launch",
+  "provision",
+  "recipe-quality",
+  "run",
+  "stop",
+  "verify"
+]);
+const SENSITIVE_KEY = /(?:auth|credential|mnemonic|pass(?:word)?|private[-_]?key|secret|seed|srp|token)/iu;
+const EVIDENCE_OPTIONS = /* @__PURE__ */ new Set(["--artifacts-dir", "--out", "--output"]);
+async function withCommandJournal(command, argv, execute) {
+  if (!JOURNALED_COMMANDS.has(command)) return execute();
+  const handle = tryBeginCommandJournal(command, argv);
+  try {
+    const exitCode = await execute();
+    tryFinishCommandJournal(handle, exitCode);
+    return exitCode;
+  } catch (error) {
+    tryFinishCommandJournal(handle, 1);
+    throw error;
+  }
+}
+function commandJournalPath(target, runtimeDir) {
+  const relative = runtimeDir ?? recipeRuntimeDir();
+  assertRelativeRuntimeDir(relative);
+  return path.join(path.resolve(target), relative, COMMAND_JOURNAL_FILE);
+}
+function readCommandJournal(target, runtimeDir) {
+  const file = commandJournalPath(target, runtimeDir);
+  let descriptor;
+  try {
+    const noFollow = typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0;
+    descriptor = fs.openSync(file, fs.constants.O_RDONLY | noFollow);
+    const descriptorStat = fs.fstatSync(descriptor, { bigint: true });
+    const pathStat = fs.lstatSync(file, { bigint: true });
+    if (!descriptorStat.isFile() || !pathStat.isFile() || pathStat.isSymbolicLink() || pathStat.dev === 0n && pathStat.ino === 0n || descriptorStat.dev !== pathStat.dev || descriptorStat.ino !== pathStat.ino) {
+      return { file, record: null };
+    }
+    const parsed = JSON.parse(fs.readFileSync(descriptor, "utf8"));
+    return isCommandJournalRecord(parsed) ? { file, record: parsed } : { file, record: null };
+  } catch {
+    return { file, record: null };
+  } finally {
+    if (descriptor !== void 0) fs.closeSync(descriptor);
+  }
+}
+function redactCommandArgs(argv) {
+  const redacted = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index] ?? "";
+    const equals = token.indexOf("=");
+    if (token.startsWith("--") && equals !== -1) {
+      const option = token.slice(0, equals);
+      const value = token.slice(equals + 1);
+      redacted.push(`${option}=${option === "--arg" ? redactAssignment(value) : SENSITIVE_KEY.test(option) ? "<redacted>" : redactUrl(value)}`);
+      continue;
+    }
+    if (token.startsWith("--") && SENSITIVE_KEY.test(token)) {
+      redacted.push(token);
+      const value = argv[index + 1];
+      if (value !== void 0 && !value.startsWith("--")) {
+        redacted.push("<redacted>");
+        index += 1;
+      }
+      continue;
+    }
+    if (token === "--arg") {
+      redacted.push(token);
+      const value = argv[index + 1];
+      if (value !== void 0) {
+        redacted.push(redactAssignment(value));
+        index += 1;
+      }
+      continue;
+    }
+    redacted.push(redactAssignment(redactUrl(token)));
+  }
+  return redacted;
+}
+function tryBeginCommandJournal(command, argv) {
+  try {
+    const target = invocationTarget(argv);
+    if (!fs.existsSync(target)) return void 0;
+    const runtimeDir = optionValue(argv, "--runtime-dir");
+    const file = commandJournalPath(target, runtimeDir);
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const record = {
+      schemaVersion: 1,
+      command,
+      args: redactCommandArgs(argv.slice(1)),
+      target,
+      verdict: "running",
+      exitCode: null,
+      evidencePaths: evidencePaths(argv),
+      startedAt: now,
+      finishedAt: null
+    };
+    writeAtomic(file, record);
+    return { file, record };
+  } catch (error) {
+    process.stderr.write(`mm-harness: resumability journal unavailable: ${errorMessage(error)}
+`);
+    return void 0;
+  }
+}
+function tryFinishCommandJournal(handle, exitCode) {
+  if (!handle) return;
+  try {
+    writeAtomic(handle.file, {
+      ...handle.record,
+      verdict: exitCode === 0 ? "pass" : "fail",
+      exitCode,
+      finishedAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  } catch (error) {
+    process.stderr.write(`mm-harness: resumability journal could not finalize: ${errorMessage(error)}
+`);
+  }
+}
+function writeAtomic(file, record) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
+  let descriptor;
+  try {
+    descriptor = fs.openSync(temporary, "wx", 384);
+    fs.writeFileSync(descriptor, `${JSON.stringify(record, null, 2)}
+`);
+    fs.fsyncSync(descriptor);
+    fs.closeSync(descriptor);
+    descriptor = void 0;
+    fs.renameSync(temporary, file);
+  } finally {
+    if (descriptor !== void 0) fs.closeSync(descriptor);
+    fs.rmSync(temporary, { force: true });
+  }
+}
+function invocationTarget(argv) {
+  return path.resolve(optionValue(argv, "--target") ?? optionValue(argv, "--project-root") ?? process.cwd());
+}
+function evidencePaths(argv) {
+  const values = /* @__PURE__ */ new Set();
+  for (const option of EVIDENCE_OPTIONS) {
+    const value = optionValue(argv, option);
+    if (value) values.add(path.resolve(value));
+  }
+  return [...values];
+}
+function optionValue(argv, option) {
+  const divider = argv.indexOf("--");
+  const end = divider === -1 ? argv.length : divider;
+  for (let index = 1; index < end; index += 1) {
+    const token = argv[index] ?? "";
+    if (token === option) {
+      const value = argv[index + 1];
+      return value && !value.startsWith("--") ? value : void 0;
+    }
+    if (token.startsWith(`${option}=`)) return token.slice(option.length + 1);
+  }
+  return void 0;
+}
+function redactAssignment(token) {
+  const equals = token.indexOf("=");
+  if (equals <= 0) return token;
+  const key = token.slice(0, equals);
+  const value = token.slice(equals + 1);
+  return `${key}=${SENSITIVE_KEY.test(key) ? "<redacted>" : redactValue(value)}`;
+}
+function redactUrl(token) {
+  return token.replace(/(\w+:\/\/)[^/@\s:]+:[^/@\s]+@/gu, "$1<redacted>@");
+}
+function redactValue(value) {
+  try {
+    return JSON.stringify(redactStructuredValue(JSON.parse(value)));
+  } catch {
+    return value.replace(
+      /((?:auth|credential|mnemonic|pass(?:word)?|private[-_]?key|secret|seed|srp|token)=)[^\s]+/giu,
+      "$1<redacted>"
+    );
+  }
+}
+function redactStructuredValue(value) {
+  if (Array.isArray(value)) return value.map(redactStructuredValue);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(
+    Object.entries(value).map(([key, entry]) => [
+      key,
+      SENSITIVE_KEY.test(key) ? "<redacted>" : redactStructuredValue(entry)
+    ])
+  );
+}
+function assertRelativeRuntimeDir(value) {
+  if (!value || path.isAbsolute(value) || !/^[A-Za-z0-9._/-]+$/u.test(value)) {
+    throw new Error(`--runtime-dir must be a safe relative path: ${value}`);
+  }
+  if (value.split("/").some((part) => !part || part === "." || part === "..")) {
+    throw new Error(`--runtime-dir contains an unsafe path component: ${value}`);
+  }
+}
+function isCommandJournalRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const record = value;
+  return record.schemaVersion === 1 && typeof record.command === "string" && Array.isArray(record.args) && record.args.every((entry) => typeof entry === "string") && typeof record.target === "string" && (record.verdict === "running" || record.verdict === "pass" || record.verdict === "fail") && (record.exitCode === null || typeof record.exitCode === "number") && Array.isArray(record.evidencePaths) && record.evidencePaths.every((entry) => typeof entry === "string") && typeof record.startedAt === "string" && (record.finishedAt === null || typeof record.finishedAt === "string");
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+export {
+  COMMAND_JOURNAL_FILE,
+  commandJournalPath,
+  readCommandJournal,
+  redactCommandArgs,
+  withCommandJournal
+};

package/dist/commands/call.js

@@ -15,6 +15,7 @@ import {
   optionString,
   resolveAdapter,
   runtimeOptionsFromCli,
+  shellQuote,
   usageError
 } from "./parse-args.js";
 import { getAdapterSurface } from "../adapters/surface.js";
@@ -59,7 +60,13 @@ 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;
@@ -76,16 +83,19 @@ async function handleCall(argv) {
   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;
   }
@@ -95,16 +105,19 @@ async function handleCall(argv) {
   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;
@@ -121,11 +134,13 @@ async function handleCall(argv) {
   const recipe = synthesizeOneNodeRecipe(resolvedAction, args);
   const validation = await validateRecipeAdapterAware(recipe, manifest);
   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 userAction = `mm-harness actions --action ${resolvedAction} --adapter ${adapter} --json`;
+    if (json) console.log(JSON.stringify({ schemaVersion: 1, command: "call", adapter, action: shortName, resolvedAction, args, findings: validation.findings, error: { code: "RECIPE_VALIDATION_FAILED", message, userAction } }, null, 2));
     else {
-      console.error(message);
+      console.error(`\u2717 ${message}`);
       for (const finding of validation.findings) console.error(`  ${finding.code} ${finding.path} \u2014 ${finding.message}`);
+      console.error(`  Next: ${userAction}`);
     }
     return EXIT.validation;
   }
@@ -160,6 +175,7 @@ async function handleCall(argv) {
     );
     if (violation !== null) return emitHealViolation(json, "call", result, violation, state, adapter);
     const callOutput = readCallOutput(result.tracePath);
+    const failureUserAction = `mm-harness last --target ${shellQuote(target)} --json`;
     if (json) {
       console.log(
         JSON.stringify(
@@ -174,10 +190,13 @@ async function handleCall(argv) {
             summaryPath: result.summaryPath,
             tracePath: result.tracePath,
             artifactManifestPath: result.artifactManifestPath,
+            ...result.diagnosticsPath ? { diagnosticsPath: result.diagnosticsPath } : {},
+            ...result.sideFindings ? { sideFindings: result.sideFindings } : {},
             ...callOutput !== void 0 ? { output: callOutput } : {},
             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
@@ -187,12 +206,16 @@ async function handleCall(argv) {
       const rendered = callOutput !== void 0 ? `
 Result:
 ${formatCallOutput(callOutput)}` : "";
+      const sideFindingTotal = result.sideFindings?.counts.total ?? 0;
       const out = (style, text) => color(style, text, { stream: process.stdout });
+      const sideFindings = sideFindingTotal > 0 ? `${out("label", "Side findings:")} REVIEW ${sideFindingTotal} distinct application warning/error event(s); see ${out("path", result.diagnosticsPath ?? "diagnostics.json")} (non-blocking)
+` : "";
       console.log(
         `${out("label", "call")} ${out("cmd", resolvedAction)}: ${out(result.status === "pass" ? "ok" : "err", result.status)}${rendered ? `
 ${out("label", "Result:")}
 ${formatCallOutput(callOutput)}` : ""}
-${out("label", "Artifacts:")} ${out("path", result.artifactManifestPath)}`
+` + sideFindings + `${out("label", "Artifacts:")} ${out("path", result.artifactManifestPath)}` + (result.status === "fail" ? `
+  Next: ${failureUserAction}` : "")
       );
     }
     return result.status === "pass" ? EXIT.ok : EXIT.runtime;

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;
@@ -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/device-target.js

@@ -1,6 +1,6 @@
 import { execFileSync } from "node:child_process";
 import { listConnectedDevices } from "../devices.js";
-import { optionString } from "./parse-args.js";
+import { optionString, shellQuoteArg, targetPath } from "./parse-args.js";
 function normalizeDeviceName(value) {
   return value.replace(/_/gu, " ").trim();
 }
@@ -75,6 +75,12 @@ function configuredPinForPlatform(platform) {
 function oppositePlatform(platform) {
   return platform === "ios" ? "android" : "ios";
 }
+function deviceProbe(options) {
+  return `mm-harness status --target ${shellQuoteArg(targetPath(options))} --all-devices --json`;
+}
+function deviceRecovery(options, rerun) {
+  return rerun ? `${deviceProbe(options)}; then retry: ${rerun}` : deviceProbe(options);
+}
 function applyDeviceTargeting(command, adapter, options, opts) {
   const device = optionString(options, "device");
   const platformPreference = mobilePlatformPreference(options);
@@ -84,7 +90,8 @@ function applyDeviceTargeting(command, adapter, options, opts) {
         ok: false,
         code: "DEVICE_WRONG_ADAPTER",
         message: `--device is only supported on the mobile adapter (the ${adapter} adapter has no device to target).
-  Drop --device, or run this ${command} inside a metamask-mobile checkout.`
+  Drop --device, or run this ${command} inside a metamask-mobile checkout.`,
+        userAction: `remove --device; ${adapter} has no device target`
       };
     }
     return { ok: true };
@@ -97,7 +104,8 @@ function applyDeviceTargeting(command, adapter, options, opts) {
           ok: false,
           code: "DEVICE_PLATFORM_CONFLICT",
           message: `--device ${device} resolves to ${matched.platform}, but --platform ${platformPreference} was requested.
-  To use this device intentionally, drop --platform ${platformPreference} or choose a ${platformPreference} device.`
+  To use this device intentionally, drop --platform ${platformPreference} or choose a ${platformPreference} device.`,
+          userAction: deviceRecovery(options, opts.rerun)
         };
       }
       if (matched.platform === "android") setAndroidDeviceEnv(matched.id, matched.name);
@@ -126,7 +134,8 @@ function applyDeviceTargeting(command, adapter, options, opts) {
         ok: false,
         code: "DEVICE_NAME_AMBIGUOUS",
         message: `device name '${device}' is ambiguous; use the id:
-` + byName.map((d) => `    - ${d.id}${d.name ? ` (${d.name})` : ""} [${d.state}] ${d.platform}`).join("\n")
+` + byName.map((d) => `    - ${d.id}${d.name ? ` (${d.name})` : ""} [${d.state}] ${d.platform}`).join("\n"),
+        userAction: deviceRecovery(options, opts.rerun)
       };
     }
     return {
@@ -134,7 +143,8 @@ function applyDeviceTargeting(command, adapter, options, opts) {
       code: "DEVICE_NOT_FOUND",
       message: `--device ${device} did not match any connected device.
 ` + (connected2.length > 0 ? `  Connected devices:
-${formatConnectedDevices(connected2)}` : `  No devices are currently connected (adb devices / booted iOS simulators).`)
+${formatConnectedDevices(connected2)}` : `  No devices are currently connected (adb devices / booted iOS simulators).`),
+      userAction: deviceRecovery(options, opts.rerun)
     };
   }
   const connected = listConnectedDevices();
@@ -158,7 +168,8 @@ ${formatConnectedDevices(connected2)}` : `  No devices are currently connected (
         message: `--platform ${platformPreference} conflicts with the current slot-selected device.
   Selected devices:
 ${formatConnectedDevices(selectedTargetable2)}
-  To use a different connected device intentionally, pass --device <id>.`
+  To use a different connected device intentionally, pass --device <id>.`,
+        userAction: deviceRecovery(options, opts.rerun)
       };
     }
     if (!configuredPin && oppositePin) {
@@ -167,7 +178,8 @@ ${formatConnectedDevices(selectedTargetable2)}
         code: "DEVICE_PLATFORM_CONFLICT",
         message: `--platform ${platformPreference} conflicts with the configured slot target.
   Configured ${oppositePlatform(platformPreference)} target: ${oppositePin}
-  To use a different connected device intentionally, pass --device <id>.`
+  To use a different connected device intentionally, pass --device <id>.`,
+        userAction: deviceRecovery(options, opts.rerun)
       };
     }
     if (configuredPin) {
@@ -178,8 +190,8 @@ ${formatConnectedDevices(selectedTargetable2)}
         message: `--platform ${platformPreference} matches the configured slot target, but that target is not ready.
   Configured target: ${configuredPin}
   Connected devices:
-${connected.length > 0 ? formatConnectedDevices(connected) : "    - none"}
-  Next: run mm-harness launch ${platformPreference}, or pass --device <id> to intentionally use another target.`
+${connected.length > 0 ? formatConnectedDevices(connected) : "    - none"}`,
+        userAction: `mm-harness launch ${platformPreference} --target ${shellQuoteArg(targetPath(options))}`
       };
     }
     if (platformTargetable.length === 1) {
@@ -195,7 +207,8 @@ ${connected.length > 0 ? formatConnectedDevices(connected) : "    - none"}
         code: "DEVICE_PLATFORM_NOT_FOUND",
         message: `--platform ${platformPreference} did not match any ready connected device.
 ` + (connected.length > 0 ? `  Connected devices:
-${formatConnectedDevices(connected)}` : `  No devices are currently connected (adb devices / booted iOS simulators).`)
+${formatConnectedDevices(connected)}` : `  No devices are currently connected (adb devices / booted iOS simulators).`),
+        userAction: deviceRecovery(options, opts.rerun)
       };
     }
     return {
@@ -205,7 +218,8 @@ ${formatConnectedDevices(connected)}` : `  No devices are currently connected (a
   Connected devices:
 ${formatConnectedDevices(connected)}
   Add --device <id> to disambiguate, e.g.:${platformTargetable.map((d) => `
-    --device ${d.id}`).join("")}`
+    --device ${d.id}`).join("")}`,
+      userAction: deviceRecovery(options, opts.rerun)
     };
   }
   const selectedTargetable = targetable.filter(deviceSelected);
@@ -224,7 +238,8 @@ ${formatConnectedDevices(connected)}
   Connected devices:
 ${formatConnectedDevices(connected)}
 ` + (selectedTargetable.length > 1 ? `  The current slot context selects more than one target; fix the slot device pins or add --device <id>.` : `  Add --device <id> to disambiguate, e.g.:${targetable.map((d) => `
-    --device ${d.id}`).join("")}`)
+    --device ${d.id}`).join("")}`),
+      userAction: deviceRecovery(options, opts.rerun)
     };
   }
   return { ok: true };

package/dist/commands/doctor.js

@@ -81,7 +81,7 @@ async function handleDoctor({ options }) {
     surface.resolveSlotPorts(target);
     const dtResult = applyDeviceTargeting("doctor", adapter, options, { gate: false, rerun: "" });
     if ("code" in dtResult) {
-      return usageOut(json, "doctor", dtResult.message, "mm-harness doctor --fix --adapter mobile --device <adb-serial|simulator-udid>");
+      return usageOut(json, "doctor", dtResult.message, dtResult.userAction);
     }
     applyDoctorRuntimePorts(options);
     const lock = acquireCheckoutLock(target, "doctor-fix");
@@ -98,7 +98,14 @@ async function handleDoctor({ options }) {
     const result2 = createDoctorReport(adapter, target, manifestValidation, actionManifestPath);
     const nextActions = doctorFixNextActions(failed, result2.fixture, adapter, target);
     const status = result2.status === "pass" && failed.length === 0 ? "pass" : "fail";
-    if (json) console.log(JSON.stringify({ ...result2, status, fixed, failed, nextActions }, null, 2));
+    const retryDoctor = `mm-harness doctor --fix --adapter ${adapter} --target ${shellQuote(target)} --json`;
+    const fixUserAction = failed.includes("wallet-fixture") ? `choose one wallet fixture source from nextActions, run it, then retry: ${retryDoctor}` : nextActions[0] ?? retryDoctor;
+    const error = status === "fail" ? {
+      code: "DOCTOR_FIX_INCOMPLETE",
+      message: "doctor --fix could not make every required check pass",
+      userAction: fixUserAction
+    } : void 0;
+    if (json) console.log(JSON.stringify({ ...result2, status, fixed, failed, nextActions, ...error ? { error } : {} }, null, 2));
     else {
       console.log(`${status} ${adapter} ${result2.compatibilityMode} manifest=${actionManifestPath} fixed=[${fixed.join(",")}] failed=[${failed.join(",")}]`);
       for (const action of nextActions) console.error(`  Next: ${action}`);
@@ -113,8 +120,9 @@ async function handleDoctor({ options }) {
     surface.resolveSlotPorts(target);
     const dtResult = applyDeviceTargeting("doctor", adapter, options, { gate: false, rerun: "" });
     if ("code" in dtResult) {
-      if (json) console.log(JSON.stringify({ schemaVersion: 1, command: "doctor", adapter, target, error: { code: dtResult.code, message: dtResult.message } }, null, 2));
-      else console.error(`\u2717 doctor: ${dtResult.message}`);
+      if (json) console.log(JSON.stringify({ schemaVersion: 1, command: "doctor", adapter, target, error: { code: dtResult.code, message: dtResult.message, userAction: dtResult.userAction } }, null, 2));
+      else console.error(`\u2717 doctor: ${dtResult.message}
+  Next: ${dtResult.userAction}`);
       return EXIT.usage;
     }
     applyDoctorRuntimePorts(options);
@@ -151,7 +159,9 @@ async function handleDoctor({ options }) {
       printReady
     );
   }
-  if (json) console.log(JSON.stringify({ ...doctorResult, ready: runtime?.decision === "ready", runtime, orphanMetros, capture, devices, additionalReachableDevices }, null, 2));
+  const doctorUserAction = `mm-harness doctor --fix --adapter ${adapter} --target ${shellQuote(target)} --json`;
+  const doctorError = doctorResult.status === "fail" ? { code: "DOCTOR_CHECKS_FAILED", message: "one or more required doctor checks failed", userAction: doctorUserAction } : void 0;
+  if (json) console.log(JSON.stringify({ ...doctorResult, ready: runtime?.decision === "ready", runtime, orphanMetros, capture, devices, additionalReachableDevices, ...doctorError ? { error: doctorError } : {} }, null, 2));
   else {
     const out = (style, text) => color(style, text, { stream: process.stdout });
     const stateStyle = (value, good) => value === good ? "ok" : "warn";
@@ -194,6 +204,7 @@ async function handleDoctor({ options }) {
       if (additionalReachableDevices.length > 0) renderAdditionalReachableDevices(additionalReachableDevices, out);
       if (liveView) renderMobileLiveBlock(deviceView?.devices ?? [], liveView.liveMap, out);
     }
+    if (doctorError) console.log(`  ${out("dim", `Next: ${doctorUserAction}`)}`);
   }
   return doctorResult.status === "pass" ? 0 : 1;
 }
@@ -256,7 +267,9 @@ function emitExpectLive(adapter, target, runtime, result, orphanMetros, capture,
     return EXIT.runtime;
   }
   if (json) {
-    console.log(JSON.stringify({ ...result, ready: live, runtime, orphanMetros, capture, devices, additionalReachableDevices }, null, 2));
+    const userAction = adapter === "extension" ? `mm-harness launch --adapter extension --target ${shellQuote(target)}` : adapter === "core" ? `mm-harness verify --adapter core --target ${shellQuote(target)}` : `mm-harness status --target ${shellQuote(target)} --json`;
+    const error = live ? void 0 : { code: "RUNTIME_NOT_LIVE", message: `${adapter} runtime is not live`, userAction };
+    console.log(JSON.stringify({ ...result, ready: live, runtime, orphanMetros, capture, devices, additionalReachableDevices, ...error ? { error } : {} }, null, 2));
     return live ? EXIT.ok : EXIT.runtime;
   }
   const out = (style, text) => color(style, text, { stream: process.stdout });

package/dist/commands/fixtures.js

@@ -65,7 +65,7 @@ async function handleFixturesLocked(argv, deps) {
   surface.resolveSlotPorts(target);
   const dtResult = applyDeviceTargeting("fixtures", adapter, options, { gate: false, rerun: "" });
   if ("code" in dtResult) {
-    return usageOut(json, "fixtures", dtResult.message, "mm-harness fixtures set --adapter mobile --device <adb-serial|simulator-udid>");
+    return usageOut(json, "fixtures", dtResult.message, dtResult.userAction);
   }
   if (sub === "generate") return fixturesGenerate(adapter, target, options, json);
   if (sub === "finalize") return fixturesFinalize(adapter, target, options, json);

package/dist/commands/last.js

@@ -0,0 +1,52 @@
+import { readCommandJournal } from "../command-journal.js";
+import { EXIT } from "./shared.js";
+import {
+  optionFlag,
+  optionString,
+  targetPath
+} from "./parse-args.js";
+async function handleLast({ options }) {
+  const target = targetPath(options);
+  const { file, record } = readCommandJournal(target, optionString(options, "runtimeDir"));
+  const json = optionFlag(options, "json");
+  if (!record) {
+    const message = `no resumability journal exists for ${target}`;
+    const userAction = "run a proof or runtime command in this checkout, then re-run mm-harness last --json";
+    if (json) {
+      console.log(JSON.stringify({
+        schemaVersion: 1,
+        command: "last",
+        target,
+        journalPath: file,
+        status: "fail",
+        exitCode: EXIT.runtime,
+        error: { code: "LAST_NOT_FOUND", message, userAction }
+      }, null, 2));
+    } else {
+      console.error(`\u2717 mm-harness last: ${message}
+  Next: ${userAction}`);
+    }
+    return EXIT.runtime;
+  }
+  if (json) {
+    console.log(JSON.stringify({
+      schemaVersion: 1,
+      command: "last",
+      target,
+      journalPath: file,
+      status: "pass",
+      exitCode: EXIT.ok,
+      last: record
+    }, null, 2));
+  } else {
+    const end = record.finishedAt ?? "still running or interrupted";
+    console.log(`${record.verdict.toUpperCase()} ${record.command} (exit ${record.exitCode ?? "pending"})`);
+    console.log(`started: ${record.startedAt}`);
+    console.log(`finished: ${end}`);
+    if (record.evidencePaths.length > 0) console.log(`evidence: ${record.evidencePaths.join(", ")}`);
+  }
+  return EXIT.ok;
+}
+export {
+  handleLast
+};