@deeeed/metamask-harness 0.16.0 → 0.17.1

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";
@@ -32,6 +33,7 @@ import {
   validateRecipeAdapterAware
 } from "./run-engine.js";
 import { acquireCheckoutLock } from "../checkout-lock.js";
+import { formatRunDiagnosticsForHuman, readRunDiagnosticsDocument } from "../run-diagnostics.js";
 async function handleCall(argv) {
   if (argv.includes("--list")) {
     const { options: options2 } = parseArgs(argv, "call");
@@ -59,7 +61,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 +84,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 +106,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 +135,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 +176,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(
@@ -179,7 +196,8 @@ async function handleCall(argv) {
             ...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
@@ -189,15 +207,20 @@ 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)
-` : "";
+      const diagnostics = formatRunDiagnosticsForHuman(
+        readRunDiagnosticsDocument(result.diagnosticsPath),
+        adapter
+      );
+      const renderedDiagnostics = `${out("label", "Diagnostics:")}
+${diagnostics.map((line) => `  ${line}`).join("\n")}
+`;
       console.log(
         `${out("label", "call")} ${out("cmd", resolvedAction)}: ${out(result.status === "pass" ? "ok" : "err", result.status)}${rendered ? `
 ${out("label", "Result:")}
 ${formatCallOutput(callOutput)}` : ""}
-` + sideFindings + `${out("label", "Artifacts:")} ${out("path", result.artifactManifestPath)}`
+` + renderedDiagnostics + `${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/debug.js

@@ -1,7 +1,8 @@
 import path from "node:path";
 import { runnerDir } from "../paths.js";
+import { acquireCheckoutLock } from "../checkout-lock.js";
 import { getAdapterSurface } from "../adapters/surface.js";
-import { ADAPTER_DETECT_NEXT, EXIT, flag, parseFlags, resolveAdapter, spawnScript, targetOf, usageOut } from "./shared.js";
+import { ADAPTER_DETECT_NEXT, checkoutBusyOut, EXIT, flag, parseFlags, resolveAdapter, spawnScript, targetOf, usageOut } from "./shared.js";
 const DEBUG_BOOLEANS = /* @__PURE__ */ new Set(["worker", "devMenu", "json", "noOpen"]);
 async function handleDebug(argv) {
   const { options } = parseFlags(argv, DEBUG_BOOLEANS);
@@ -31,37 +32,43 @@ async function handleDebug(argv) {
       "mm-harness debug --worker"
     );
   }
-  const openDebug = path.join(runnerDir, "adapters/shared/open-debug.mjs");
-  const debugArgs = ["--adapter", adapter];
-  if (adapter === "extension") {
-    if (process.env.CDP_PORT) debugArgs.push("--cdp-port", process.env.CDP_PORT);
-    debugArgs.push("--target", worker ? "worker" : "page");
-  } else {
-    if (process.env.WATCHER_PORT) debugArgs.push("--port", process.env.WATCHER_PORT);
-    debugArgs.push("--action", devMenu ? "dev-menu" : "debug");
-  }
-  if (json) debugArgs.push("--json");
-  if (noOpen) debugArgs.push("--no-open");
-  const result = spawnScript(process.execPath, [openDebug, ...debugArgs], target, json);
-  if (json) {
-    const leaf = parseDebugLeaf(result.output);
-    console.log(
-      JSON.stringify(
-        {
-          ...leaf,
-          schemaVersion: 1,
-          command: "debug",
-          adapter,
-          mode: worker ? "worker" : devMenu ? "dev-menu" : "default",
-          opened: leaf.opened === true,
-          exitCode: result.status === 0 ? EXIT.ok : EXIT.runtime
-        },
-        null,
-        2
-      )
-    );
+  const lock = acquireCheckoutLock(target, "debug");
+  if ("message" in lock) return checkoutBusyOut(json, "debug", lock.message, lock.path);
+  try {
+    const openDebug = path.join(runnerDir, "adapters/shared/open-debug.mjs");
+    const debugArgs = ["--adapter", adapter];
+    if (adapter === "extension") {
+      if (process.env.CDP_PORT) debugArgs.push("--cdp-port", process.env.CDP_PORT);
+      debugArgs.push("--target", worker ? "worker" : "page");
+    } else {
+      if (process.env.WATCHER_PORT) debugArgs.push("--port", process.env.WATCHER_PORT);
+      debugArgs.push("--action", devMenu ? "dev-menu" : "debug");
+    }
+    if (json) debugArgs.push("--json");
+    if (noOpen) debugArgs.push("--no-open");
+    const result = spawnScript(process.execPath, [openDebug, ...debugArgs], target, json);
+    if (json) {
+      const leaf = parseDebugLeaf(result.output);
+      console.log(
+        JSON.stringify(
+          {
+            ...leaf,
+            schemaVersion: 1,
+            command: "debug",
+            adapter,
+            mode: worker ? "worker" : devMenu ? "dev-menu" : "default",
+            opened: leaf.opened === true,
+            exitCode: result.status === 0 ? EXIT.ok : EXIT.runtime
+          },
+          null,
+          2
+        )
+      );
+    }
+    return result.status === 0 ? EXIT.ok : EXIT.runtime;
+  } finally {
+    lock.release();
   }
-  return result.status === 0 ? EXIT.ok : EXIT.runtime;
 }
 function parseDebugLeaf(output) {
   try {

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 };