@deeeed/metamask-harness 0.14.5 → 0.15.0

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 { EXIT } from "./shared.js";
+import { checkoutBusyOut, EXIT, usageOut } from "./shared.js";
 import {
   optionFlag,
   optionString,
@@ -18,6 +18,7 @@ import {
   emitHealViolation,
   executeWithHealBounds,
   prepareHeal,
+  recoverRunInfra,
   runRecipe,
   validateRunRecipeStatic
 } from "./run-engine.js";
@@ -26,6 +27,7 @@ import { applyDeviceTargeting } from "./device-target.js";
 import { getAdapterSurface } from "../adapters/surface.js";
 import { coreDependencyBlock } from "./core-readiness.js";
 import { writeRunReport } from "./run-report.js";
+import { acquireCheckoutLock } from "../checkout-lock.js";
 async function handleRun({ positional, options }) {
   if (optionFlag(options, "list")) return handleListExecutables("run", options);
   const targetRecipe = positional[0];
@@ -33,6 +35,14 @@ async function handleRun({ positional, options }) {
   if (optionFlag(options, "plan")) return handleRunPlan(targetRecipe, options);
   const { adapter, target } = resolveAdapter(options);
   const json = optionFlag(options, "json");
+  if (!fs.existsSync(target)) {
+    return usageOut(
+      json,
+      "run",
+      `target does not exist: ${target}`,
+      "pass --target <metamask-checkout> pointing to an existing checkout"
+    );
+  }
   getAdapterSurface(adapter).resolveSlotPorts(target);
   const dtResult = applyDeviceTargeting("run", adapter, options, { gate: true, rerun: "" });
   if ("code" in dtResult) {
@@ -54,56 +64,63 @@ async function handleRun({ positional, options }) {
     return emitRunUsageError(json, adapter, validated.recipeFile, depsBlock.code, depsBlock.message, depsBlock.userAction);
   }
   const artifactsDir = requiredOption(options, "artifactsDir", "run requires --artifacts-dir <dir>.");
-  const prepared = await prepareHeal(adapter, target, options, json);
-  if (typeof prepared === "number") return prepared;
-  const { state, heal } = prepared;
-  const librarySources = validated.librarySources;
-  const runtimeOptions = {
-    ...runtimeOptionsFromCli(options),
-    ...librarySources ? { librarySources } : {},
-    stdoutIsMachineContract: json
-  };
-  const { result, violation } = await executeWithHealBounds(
-    // validated.recipeFile, not the raw arg: the arg may be a library recipe NAME
-    // that only the resolver knows how to turn into a file.
-    () => runRecipe(adapter, validated.recipeFile, artifactsDir, target, optionString(options, "actionManifest"), runtimeOptions),
-    adapter,
-    target,
-    heal,
-    state
-  );
-  if (violation !== null) return emitHealViolation(json, "run", result, violation, state, adapter);
-  const report = writeRunReport(result);
-  const exitCode = result.status === "pass" ? EXIT.ok : EXIT.runtime;
-  if (json) {
-    console.log(
-      JSON.stringify(
-        {
-          schemaVersion: 1,
-          command: "run",
-          adapter,
-          status: result.status,
-          exitCode,
-          recovered: state.recovered,
-          mutations: state.mutations,
-          reportPath: report.path,
-          result
-        },
-        null,
-        2
-      )
+  const lock = acquireCheckoutLock(target, "run");
+  if ("message" in lock) return checkoutBusyOut(json, "run", lock.message, lock.path);
+  try {
+    const prepared = await prepareHeal(adapter, target, options, json);
+    if (typeof prepared === "number") return prepared;
+    const { state, heal } = prepared;
+    const librarySources = validated.librarySources;
+    const runtimeOptions = {
+      ...runtimeOptionsFromCli(options),
+      ...librarySources ? { librarySources } : {},
+      stdoutIsMachineContract: json
+    };
+    const { result, violation } = await executeWithHealBounds(
+      // validated.recipeFile, not the raw arg: the arg may be a library recipe NAME
+      // that only the resolver knows how to turn into a file.
+      () => runRecipe(adapter, validated.recipeFile, artifactsDir, target, optionString(options, "actionManifest"), runtimeOptions),
+      adapter,
+      target,
+      heal,
+      state,
+      () => recoverRunInfra(adapter, target, json)
     );
-  } else {
-    const out = (style, text) => color(style, text, { stream: process.stdout });
-    console.log(`${out(result.status === "pass" ? "ok" : "err", result.status.toUpperCase())} ${out("bold", "recipe run")} ${out("dim", `[${adapter}]`)}`);
-    if (report.preview.length > 0) {
-      console.log(out("label", "summary:"));
-      for (const line of report.preview) console.log(`  ${formatPreviewLine(line, out)}`);
+    if (violation !== null) return emitHealViolation(json, "run", result, violation, state, adapter);
+    const report = writeRunReport(result);
+    const exitCode = result.status === "pass" ? EXIT.ok : EXIT.runtime;
+    if (json) {
+      console.log(
+        JSON.stringify(
+          {
+            schemaVersion: 1,
+            command: "run",
+            adapter,
+            status: result.status,
+            exitCode,
+            recovered: state.recovered,
+            mutations: state.mutations,
+            reportPath: report.path,
+            result
+          },
+          null,
+          2
+        )
+      );
+    } else {
+      const out = (style, text) => color(style, text, { stream: process.stdout });
+      console.log(`${out(result.status === "pass" ? "ok" : "err", result.status.toUpperCase())} ${out("bold", "recipe run")} ${out("dim", `[${adapter}]`)}`);
+      if (report.preview.length > 0) {
+        console.log(out("label", "summary:"));
+        for (const line of report.preview) console.log(`  ${formatPreviewLine(line, out)}`);
+      }
+      console.log(`${out("label", "report:")} ${out("path", report.path)}`);
+      console.log(`${out("label", "artifacts:")} ${out("path", result.artifactManifestPath)}`);
     }
-    console.log(`${out("label", "report:")} ${out("path", report.path)}`);
-    console.log(`${out("label", "artifacts:")} ${out("path", result.artifactManifestPath)}`);
+    return exitCode;
+  } finally {
+    lock.release();
   }
-  return exitCode;
 }
 function formatPreviewLine(line, out) {
   const match = /^(PASS|FAIL)\s+(.+)$/u.exec(line);
@@ -271,8 +288,8 @@ function emitPlanUsageError(json, adapter, recipeFile, code, message) {
 function runArgLooksLikeRecipeFile(value) {
   return path.isAbsolute(value) || value.includes("/") || value.includes(path.sep) || value.endsWith(".json") || fs.existsSync(path.resolve(value));
 }
-function emitRunRecipeRunning(json) {
-  const message = "a recipe is currently running \u2014 refusing to start while another recipe executes.";
+function emitRunRecipeRunning(json, detail) {
+  const message = detail ?? "a recipe is currently running \u2014 refusing to start while another recipe executes.";
   if (json) {
     console.log(JSON.stringify({ schemaVersion: 1, status: "fail", recoverable: false, error: { code: "RECIPE_RUNNING", message } }, null, 2));
   } else {

package/dist/commands/shared.js

@@ -111,7 +111,8 @@ function spawnInherit(script, args, cwd) {
   if (result.status !== null) return result.status;
   return result.signal === "SIGINT" || result.signal === "SIGTERM" ? 0 : 1;
 }
-function spawnScriptStreaming(script, args, cwd, env) {
+function spawnScriptStreaming(script, args, cwd, options) {
+  const spawnOptions = options && ("env" in options || "timeoutMs" in options) ? options : { env: options };
   const isNodeScript = script === process.execPath && args.length > 0;
   const stem = isNodeScript ? path.basename(args[0]).replace(/[^A-Za-z0-9]/gu, "_").toUpperCase() : path.basename(script).replace(/[^A-Za-z0-9]/gu, "_").toUpperCase();
   const override = process.env[`MM_HARNESS_SCRIPT_BIN_${stem}`];
@@ -126,12 +127,58 @@ function spawnScriptStreaming(script, args, cwd, env) {
   }
   const { bin: invokeBin, args: spawnArgs } = resolveLeafInvoke(bin, directArgs);
   return new Promise((resolve) => {
+    const ownsProcessGroup = process.platform !== "win32" && Number(spawnOptions.timeoutMs) > 0;
     const child = spawn(invokeBin, spawnArgs, {
       cwd,
-      env: env ? { ...process.env, ...env } : process.env,
-      stdio: ["ignore", "pipe", "pipe"]
+      env: spawnOptions.env ? { ...process.env, ...spawnOptions.env } : process.env,
+      stdio: ["ignore", "pipe", "pipe"],
+      detached: ownsProcessGroup
     });
     let output = "";
+    let settled = false;
+    let didTimeout = false;
+    let escalation;
+    const parentSignals = ["SIGINT", "SIGTERM"];
+    const removeParentSignalHandlers = () => {
+      for (const signal of parentSignals) process.removeListener(signal, parentSignalHandlers[signal]);
+    };
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      if (escalation) clearTimeout(escalation);
+      removeParentSignalHandlers();
+      resolve(result);
+    };
+    const signalChildTree = (signal) => {
+      try {
+        if (ownsProcessGroup && child.pid) process.kill(-child.pid, signal);
+        else child.kill(signal);
+      } catch {
+      }
+    };
+    const parentSignalHandlers = Object.fromEntries(parentSignals.map((signal) => [signal, () => {
+      signalChildTree(signal);
+      removeParentSignalHandlers();
+      process.kill(process.pid, signal);
+    }]));
+    if (ownsProcessGroup) {
+      for (const signal of parentSignals) process.once(signal, parentSignalHandlers[signal]);
+    }
+    const timeoutMs = spawnOptions.timeoutMs;
+    const timer = Number.isFinite(timeoutMs) && Number(timeoutMs) > 0 ? setTimeout(() => {
+      didTimeout = true;
+      const message = `leaf timed out after ${String(timeoutMs)}ms: ${path.basename(script)}`;
+      output += `${output.endsWith("\n") || output.length === 0 ? "" : "\n"}${message}
+`;
+      process.stderr.write(`${message}
+`);
+      signalChildTree("SIGTERM");
+      escalation = setTimeout(() => {
+        signalChildTree("SIGKILL");
+        finish({ status: 1, output, timedOut: true, timeoutMs: Number(timeoutMs) });
+      }, 1e3);
+    }, Number(timeoutMs)) : void 0;
     const tee = (chunk) => {
       const text = chunk.toString("utf8");
       output += text;
@@ -146,10 +193,20 @@ function spawnScriptStreaming(script, args, cwd, env) {
   Next: reinstall mm-harness (npm i -g @deeeed/metamask-harness) \u2014 the shell leaf is missing or not executable`;
       process.stderr.write(`${message}
 `);
-      resolve({ status: 1, output: message });
+      finish({ status: 1, output: message });
+    });
+    child.on("exit", () => {
+      if (!didTimeout) return;
+      signalChildTree("SIGKILL");
+      finish({ status: 1, output, timedOut: true, timeoutMs: Number(timeoutMs) });
     });
     child.on("close", (status) => {
-      resolve({ status: status ?? 1, output });
+      if (didTimeout) signalChildTree("SIGKILL");
+      finish({
+        status: didTimeout ? 1 : status ?? 1,
+        output,
+        ...didTimeout ? { timedOut: true, timeoutMs: Number(timeoutMs) } : {}
+      });
     });
   });
 }
@@ -169,9 +226,33 @@ function usageOut(json, command, message, userAction) {
   }
   return EXIT.usage;
 }
+function checkoutBusyOut(json, command, message, lockPath) {
+  const userAction = `wait for the current owner, or inspect ${lockPath} if its process has exited`;
+  if (json) {
+    console.log(
+      JSON.stringify(
+        {
+          schemaVersion: 1,
+          command,
+          status: "fail",
+          exitCode: EXIT.bounded,
+          recoverable: false,
+          error: { code: "SANDBOX_BUSY", message, userAction }
+        },
+        null,
+        2
+      )
+    );
+  } else {
+    console.error(`\u2717 mm-harness ${command}: ${message}
+  Next: ${userAction}`);
+  }
+  return EXIT.bounded;
+}
 export {
   ADAPTER_DETECT_NEXT,
   EXIT,
+  checkoutBusyOut,
   flag,
   parseFlags,
   resolveAdapter,

package/dist/commands/stop.js

@@ -12,12 +12,11 @@ async function handleStop(argv) {
   const json = optionFlag(options, "json");
   const { adapter, target } = resolveAdapter(options);
   const surface = getAdapterSurface(adapter);
+  surface.resolveSlotPorts(target);
   const explicitPort = optionString(options, "port") ?? optionString(options, "watcherPort");
   if (explicitPort) {
     process.env.WATCHER_PORT = explicitPort;
     process.env.METRO_PORT = explicitPort;
-  } else {
-    surface.resolveSlotPorts(target);
   }
   const stop = surface.devServer.stop(target);
   if (stop.kind === "headless") {

package/dist/doctor.js

@@ -1,8 +1,19 @@
 import fs from "node:fs";
 import path from "node:path";
 import { color } from "./cli-color.js";
+import { mobilePerpsEnvironment } from "./adapters/mobile/perps-env.js";
 import { readRuntimeContextField, resolveRuntimeContextPath } from "./harness.js";
 import { manifestPath, readJson, recipeHarnessRoot, recipeRuntimeDir, runnerDir } from "./paths.js";
+function requiredDoctorCheckSummary(checks) {
+  const required = checks.filter((check) => check.required);
+  const failed = required.filter((check) => check.status === "fail").map((check) => check.id);
+  return {
+    status: failed.length === 0 ? "pass" : "fail",
+    total: required.length,
+    passed: required.length - failed.length,
+    failed
+  };
+}
 function repoShape(target) {
   const exists = (rel) => fs.existsSync(path.join(target, rel));
   const packageInfo = readPackageInfo(target);
@@ -56,31 +67,36 @@ function readPackageInfo(target) {
     };
   }
 }
-function fixtureSummary(target) {
+function fixtureSummary(target, adapter) {
   const candidates = [
     `${recipeRuntimeDir()}/wallet-fixture.json`
   ];
   const rel = candidates.find((candidate) => fs.existsSync(path.join(target, candidate)));
   if (!rel) return { status: "missing", path: null };
+  return fixtureFileSummary(path.join(target, rel), adapter, rel);
+}
+function fixtureFileSummary(file, adapter, reportedPath = file) {
   try {
-    const data = readJsonObject(path.join(target, rel));
+    const data = readJsonObject(file);
+    const hasAccounts = Array.isArray(data.accounts) && data.accounts.length > 0;
+    const hasPassword = typeof data.password === "string" && data.password.length > 0;
     return {
-      status: Array.isArray(data.accounts) && data.accounts.length > 0 ? "ready" : "incomplete",
-      path: rel,
+      status: hasAccounts && (adapter === "core" || hasPassword) ? "ready" : "incomplete",
+      path: reportedPath,
       accountCount: Array.isArray(data.accounts) ? data.accounts.length : 0,
-      hasPassword: typeof data.password === "string" && data.password.length > 0
+      hasPassword
     };
   } catch (error) {
-    return { status: "invalid", path: rel, error: error instanceof Error ? error.message : String(error) };
+    return { status: "invalid", path: reportedPath, error: error instanceof Error ? error.message : String(error) };
   }
 }
 const RUNTIME_CONTEXT_FIELDS = [
-  { key: "slotId", envVars: ["RECIPE_SLOT_ID"], envVar: "RECIPE_SLOT_ID", customize: "farmslot dispatch writes this", adapters: ["mobile", "extension", "core"] },
-  { key: "extensionId", envVars: ["RECIPE_HARNESS_EXTENSION_ID"], envVar: "RECIPE_HARNESS_EXTENSION_ID", customize: "auto-resolved; edit file to pin", adapters: ["extension"] },
-  { key: "cdpPort", envVars: ["RECIPE_CDP_PORT", "CDP_PORT"], envVar: "CDP_PORT", customize: "edit file or pass --cdp-port", adapters: ["extension"] },
-  { key: "runtimeStart.approved", envVars: ["RECIPE_RUNTIME_START_APPROVED"], envVar: "RECIPE_RUNTIME_START_APPROVED", customize: "edit file (true/false)", adapters: ["mobile", "extension"] },
-  { key: "runtimeStart.command", envVars: [], envVar: null, customize: "edit file", adapters: ["mobile", "extension"] },
-  { key: "runtimeStart.readyUrl", envVars: ["RECIPE_RUNTIME_READY_URL"], envVar: "RECIPE_RUNTIME_READY_URL", customize: "edit file", adapters: ["mobile", "extension"] }
+  { key: "slotId", envVars: ["RECIPE_SLOT_ID"], envVar: "RECIPE_SLOT_ID", customize: "doctor --fix creates local identity; Farmslot may override", adapters: ["mobile", "extension", "core"] },
+  { key: "extensionId", envVars: ["RECIPE_HARNESS_EXTENSION_ID"], envVar: "RECIPE_HARNESS_EXTENSION_ID", customize: "resolved from the built extension", adapters: ["extension"] },
+  { key: "cdpPort", envVars: ["RECIPE_CDP_PORT", "CDP_PORT"], envVar: "CDP_PORT", customize: "doctor --fix claims one; --cdp-port overrides", adapters: ["extension"] },
+  { key: "runtimeStart.approved", envVars: ["RECIPE_RUNTIME_START_APPROVED"], envVar: "RECIPE_RUNTIME_START_APPROVED", customize: "optional orchestrator-provided legacy live context", adapters: ["mobile", "extension"] },
+  { key: "runtimeStart.command", envVars: [], envVar: null, customize: "optional orchestrator-provided legacy live context", adapters: ["mobile", "extension"] },
+  { key: "runtimeStart.readyUrl", envVars: ["RECIPE_RUNTIME_READY_URL"], envVar: "RECIPE_RUNTIME_READY_URL", customize: "optional orchestrator-provided legacy live context", adapters: ["mobile", "extension"] }
 ];
 function runtimeContextSummary(target, adapter) {
   const contextPath = resolveRuntimeContextPath(target);
@@ -104,7 +120,7 @@ function renderRuntimeContext(runtimeContext) {
   const out = (style, text) => color(style, text, { stream: process.stdout });
   const lines = [];
   lines.push(
-    runtimeContext.fileExists ? `${out("label", "runtime-context:")} ${runtimeContext.file} ${out("ok", "(present)")}` : `${out("label", "runtime-context:")} ${runtimeContext.file} ${out("dim", "(absent \u2014 written by farmslot prepare/dispatch)")}`
+    runtimeContext.fileExists ? `${out("label", "runtime-context:")} ${runtimeContext.file} ${out("ok", "(present)")}` : `${out("label", "runtime-context:")} ${runtimeContext.file} ${out("dim", "(absent \u2014 run mm-harness doctor --fix)")}`
   );
   for (const [key, field] of Object.entries(runtimeContext.fields)) {
     const isSet = field.value !== void 0 && field.value !== null && field.value !== "";
@@ -118,25 +134,28 @@ function renderRuntimeContext(runtimeContext) {
 function createDoctorReport(adapter, target, manifestValidation, actionManifestPath = manifestPath(adapter)) {
   const mode = compatibilityMode(adapter, target);
   const manifestErrors = Number(manifestValidation.summary?.errors ?? 0);
-  const status = manifestErrors > 0 ? "fail" : "pass";
   const checks = [
     {
       id: "manifest",
       status: manifestErrors === 0 ? "pass" : "fail",
+      required: true,
       message: manifestErrors === 0 ? "Action manifest is valid Recipe v1." : `Action manifest has ${manifestErrors} validation error(s).`
     },
     {
       id: "bridge",
       status: mode === "unsupported/no bridge" ? "fail" : "pass",
+      required: false,
       message: mode === "unsupported/no bridge" ? `No ${adapter} bridge is available for this checkout.` : `${adapter} compatibility mode: ${mode}.`
     }
   ];
+  const requiredChecks = requiredDoctorCheckSummary(checks);
   return {
     schemaVersion: 1,
     protocolVersion: "v1",
     runner_protocol_version: 1,
-    status,
-    checks: [...checks],
+    status: requiredChecks.status,
+    checks,
+    requiredChecks,
     adapter,
     target,
     runner: {
@@ -147,7 +166,8 @@ function createDoctorReport(adapter, target, manifestValidation, actionManifestP
     },
     compatibilityMode: mode,
     shape: repoShape(target),
-    fixture: fixtureSummary(target),
+    fixture: fixtureSummary(target, adapter),
+    environment: adapter === "mobile" ? { mobilePerps: mobilePerpsEnvironment(target) } : {},
     runtimeContext: runtimeContextSummary(target, adapter),
     manifestValidation: manifestValidation.summary
   };
@@ -162,8 +182,10 @@ function readJsonObject(file) {
 export {
   compatibilityMode,
   createDoctorReport,
+  fixtureFileSummary,
   fixtureSummary,
   renderRuntimeContext,
   repoShape,
+  requiredDoctorCheckSummary,
   runtimeContextSummary
 };

package/dist/harness.js

@@ -2,6 +2,7 @@ import { execFileSync, spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { resolveLeafInvoke, shellLeafMissing, missingShellLeafMessage } from "./leaf-invoke.js";
+import { resolveExtensionSlotPorts } from "./adapters/slot-ports.js";
 import { recipeHarnessPath, recipeRuntimeDir, runnerDir } from "./paths.js";
 import { prepareMobile } from "./adapters/mobile/prepare.js";
 const HARNESS_ACTIONS = ["install", "verify", "cleanup", "live"];
@@ -186,11 +187,13 @@ function applyExtensionRuntimeEnv(target, action, args) {
       const readyUrl = readRuntimeContextField(contextPath, "runtimeStart.readyUrl");
       if (readyUrl) process.env.RECIPE_RUNTIME_READY_URL = readyUrl;
     }
+  } else {
+    delete process.env.RECIPE_RUNTIME_CONTEXT;
   }
+  resolveExtensionSlotPorts(target);
   let result = [...args];
   if (!hasArg(result, "--cdp-port")) {
-    const contextPort = contextExists ? readRuntimeContextField(contextPath, "cdpPort") : void 0;
-    const cdpPort = contextPort ?? process.env.RECIPE_CDP_PORT ?? process.env.CDP_PORT;
+    const cdpPort = process.env.RECIPE_CDP_PORT ?? process.env.CDP_PORT;
     if (cdpPort) {
       process.env.RECIPE_CDP_PORT = cdpPort;
       process.env.CDP_PORT = cdpPort;

package/dist/heal-bounds.js

@@ -103,7 +103,7 @@ function checkHealBounds(target, output, state) {
     return {
       code: "SAME_RECOVERY_TWICE",
       exitCode: EXIT.bounded,
-      message: "same recovery already failed once this invocation \u2014 refusing to loop.",
+      message: state.recovered.length > 0 ? "one recovery already succeeded this invocation \u2014 bounded policy refuses a second recovery." : "one recovery was already attempted this invocation \u2014 refusing to loop.",
       originalError
     };
   }

package/dist/mm-harness-cli.js

@@ -51,6 +51,22 @@ Example:
   mm-harness status --json
   mm-harness status --fast`
   },
+  {
+    name: "checklist",
+    summary: "Mark task-local checklist progress through the bundled agent runtime.",
+    example: "mm-harness checklist mark <task-dir> start",
+    helpText: `mm-harness checklist mark <task-dir> <step> [options]
+
+  Mark checklist progress through mm-harness's bundled @farmslot/agent-runtime.
+  The task directory must contain CHECKLIST.md and checklist-target.json.
+
+  Steps: start | 1 | 2 | ... | complete | no-change | blocked
+
+Example:
+  mm-harness checklist mark temp/tasks/recipe-cook/<task> start
+  mm-harness checklist mark temp/tasks/recipe-cook/<task> 1
+  mm-harness checklist mark temp/tasks/recipe-cook/<task> complete --mark-last`
+  },
   {
     name: "actions",
     summary: "List the action vocabulary + field schemas (--raw dumps the raw action registry JSON).",
@@ -72,18 +88,18 @@ Example:
   },
   {
     name: "stop",
-    summary: "Stop the dev server this checkout owns (mobile Metro / extension webpack watcher) and close its log window.",
+    summary: "Stop this checkout runtime (mobile Metro / Extension watcher + owned browser) and close its log windows.",
     example: "mm-harness stop",
     helpText: `mm-harness stop [flags]
 
-  Stop the dev server this checkout owns and close its tmux log-tail window,
+  Stop the runtime this checkout owns and close its tmux log-tail windows,
   scoped to this checkout so concurrent slots are untouched. Idempotent \u2014
   nothing running is success, not an error. Behavior is per platform:
     mobile     stop the port-scoped Metro dev server
-    extension  stop the checkout's webpack watcher (pid file + orphan scan)
+    extension  stop webpack watcher, owned Chrome/CDP profile processes, viewers, and stale markers
     core       headless \u2014 no dev server to stop (teaching error)
 
-  --port <port>                      Dev-server port (default: the checkout's slot context)
+  --port <port>                      Metro/webpack port override; Extension CDP remains checkout-context scoped
   --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
   --target <path>                    Checkout path (default: cwd)
   --json                             Machine-readable output
@@ -101,7 +117,8 @@ Example:
   Run one action in isolation as a one-node recipe through the real engine path.
   Fuzzy short-name: 'ensure_unlocked' resolves to 'metamask.wallet.ensure_unlocked'
   if unique; ambiguous = exit 2. Pass action fields as key=value shorthand or
-  with --arg k=v. Actions differ per adapter \u2014 list this checkout's with:
+  with --arg k=v; numbers, booleans, arrays, and objects are parsed as JSON-like values.
+  Actions differ per adapter \u2014 list this checkout's with:
   mm-harness actions.
 
   --list                             List everything invocable for the adapter (actions + flows); no <action> needed
@@ -171,19 +188,20 @@ Example:
   sections so there is no hunting for files.
 
   --fix                              Repair the overlay/runtime-context WITHOUT launching (no fixture reseed); --json adds fixed[]/failed[]
-  --expect-live                      Exit 0 iff the runtime is live (extension: watcher+CDP; mobile: Metro+bridge; core: deps), non-zero + teaching escape otherwise
+  --expect-live                      Exit-coded liveness gate only (human verdict on stderr). Use without --print-ready when callers need pass/fail without a Farmslot indicator line
+  --print-ready                      Farmslot health_check mode: implies --expect-live and prints health.ready_indicator on stdout (extension/mobile: OK; core: ready)
   --cdp-port <port>                  Extension CDP port for the liveness probe (env: CDP_PORT / RECIPE_CDP_PORT)
   --device <udid|serial|name>        Mobile only: target this device (env: IOS_SIMULATOR / ADB_SERIAL). doctor reports the connected devices; it never gates on ambiguity.
   --all-devices                      Mobile only: show every connected device instead of the slot-scoped target
   --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
   --target <path>                    Checkout path (default: cwd)
   --runtime-dir <dir>                Runtime dir containing agentic-runtime.json (relative to target)
-  --json                             Machine-readable output
+  --json                             Machine-readable output (incompatible with --print-ready)
 
 Example:
   mm-harness doctor
   mm-harness doctor --fix --json
-  mm-harness doctor --adapter extension --target /path/to/checkout --cdp-port 6662 --expect-live
+  mm-harness doctor --adapter extension --target /path/to/checkout --cdp-port 6662 --print-ready
   mm-harness doctor --adapter mobile --target /path/to/checkout`
   },
   {
@@ -200,11 +218,12 @@ Example:
   --adapter <mobile|extension|core>  Adapter label (auto-detected when possible)
   --base <ref>                       Diff base (default: PR base, then remote HEAD, then repo fallback)
   --profile <fast|full>              Validation depth (default: fast)
+  --fix                              Fix changed files, then validate them
   --artifacts-dir <dir>              Write validation-summary.json/.md and per-check logs
   --json                             Machine-readable envelope
 
 Example:
-  mm-harness check diff --profile fast --artifacts-dir artifacts/validation
+  mm-harness check diff --fix --profile fast --artifacts-dir artifacts/validation
   mm-harness check diff --profile full --json`
   },
   {
@@ -305,6 +324,8 @@ Example:
     helpText: `mm-harness verify [flags]
 
   Check the runtime overlay is present and healthy (no app launch).
+  Extension live checks infer the checkout CDP port from runtime context,
+  pool, or slot suffix when --cdp-port is omitted.
 
   --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
   --target <path>                    Checkout path (default: cwd)
@@ -394,6 +415,7 @@ Example:
 
   --worker                           Extension service-worker DevTools
   --dev-menu                         Mobile RN developer menu
+  --no-open                          Resolve target/method/endpoint without opening a UI
   --adapter <mobile|extension>       Target adapter (auto-detected inside a checkout)
   --target <path>                    Checkout path (default: cwd)
   --json                             Machine-readable output
@@ -424,11 +446,13 @@ Example:
   },
   {
     name: "fixtures",
-    summary: "Manage the canonical wallet fixture (wallet DATA only) \u2014 sync / set / generate / finalize.",
+    summary: "Manage the canonical wallet fixture (wallet DATA only) \u2014 init / sync / set / generate / finalize.",
     example: "mm-harness fixtures set",
-    helpText: `mm-harness fixtures <sync|set|generate|finalize> [flags]
+    helpText: `mm-harness fixtures <init|sync|set|generate|finalize> [flags]
 
   Manage the ONE canonical wallet fixture per checkout \u2014 wallet DATA only.
+  init       Create it from --from <path>, or explicitly choose --dev for a
+             disposable public test wallet that must never hold real funds.
   sync       Refresh the wallet fixture files on the target.
   set        Apply the canonical fixture (SRP/password/accounts); the password is
              read FROM the fixture, never typed.
@@ -440,6 +464,9 @@ Example:
   Want different accounts? Edit the fixture file directly:
     <checkout>/temp/recipe/runtime/wallet-fixture.json
 
+  --from <path>                       Existing wallet fixture source (init)
+  --dev                               Create a disposable public test wallet (init)
+  --force                             Replace an existing canonical fixture (init)
   --fixture <path>                   Wallet fixture path (generate/finalize input; agent override for set/sync \u2014 env: RECIPE_WALLET_FIXTURE)
   --out <path>                       generate: output fixture-state.json; finalize: optional validation report
   --state <path>                     finalize: the pre-launch fixture-state.json to seed
@@ -452,6 +479,8 @@ Example:
   --json                             Machine-readable output
 
 Example:
+  mm-harness fixtures init --from /secure/path/wallet-fixture.json
+  mm-harness fixtures init --dev
   mm-harness fixtures sync
   mm-harness fixtures set
   mm-harness fixtures generate --fixture wallet-fixture.json --out fixture-state.json
@@ -487,7 +516,7 @@ const HELP_GROUPS = [
   {
     title: "PROVE",
     blurb: "run recipes and inspect readiness",
-    commands: ["run", "doctor", "check", "recipe-quality"]
+    commands: ["run", "doctor", "check", "checklist", "recipe-quality"]
   },
   {
     title: "RUNTIME OVERLAY",