@deeeed/metamask-harness 0.17.5 → 0.18.0

package/dist/commands/doctor.js

@@ -4,9 +4,10 @@ import fs from "node:fs";
 import path from "node:path";
 import { color } from "../cli-color.js";
 import { createDoctorReport, fixtureSummary, renderRuntimeContext, requiredDoctorCheckSummary } from "../doctor.js";
-import { detectAdapter } from "../harness.js";
+import { detectAdapter, resolveRuntimeContextPath } from "../harness.js";
 import { assertAdapter, runnerDir } from "../paths.js";
 import { getAdapterSurface } from "../adapters/surface.js";
+import { extensionProductConfigBlock } from "../adapters/extension/product-config.js";
 import { ensureMobilePerpsEnvironment, mobilePerpsEnvironment } from "../adapters/mobile/perps-env.js";
 import { loadActionManifest, validateManifest } from "../manifest.js";
 import { ensureOverlay, newHealState, recipeRunning } from "../heal-bounds.js";
@@ -21,12 +22,13 @@ import {
 import { farmslotReadyIndicator } from "./farmslot-ready.js";
 import { ensureRuntimeContext } from "../runtime-context.js";
 import { acquireCheckoutLock } from "../checkout-lock.js";
-import { ADAPTER_DETECT_NEXT, EXIT, usageOut } from "./shared.js";
+import { ADAPTER_DETECT_NEXT, checkoutBusyOut, EXIT, usageOut } from "./shared.js";
 import {
   actionManifestPathOption,
   applyRuntimeDirOption,
   optionFlag,
   optionString,
+  shellQuote,
   targetPath
 } from "./parse-args.js";
 function applyDoctorRuntimePorts(options) {
@@ -56,6 +58,14 @@ async function handleDoctor({ options }) {
     return usageOut(json, "doctor", `could not detect the MetaMask repo type for ${target}`, ADAPTER_DETECT_NEXT);
   }
   assertAdapter(adapter);
+  if (!fs.existsSync(target)) {
+    return usageOut(
+      json,
+      "doctor",
+      `target does not exist: ${target}`,
+      "pass --target <metamask-checkout> pointing to an existing checkout"
+    );
+  }
   if (printReady && json) {
     return usageOut(
       json,
@@ -72,12 +82,12 @@ 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");
     if ("message" in lock) {
-      return usageOut(json, "doctor", lock.message, `wait for the current owner, or inspect ${lock.path} if its process has exited`);
+      return checkoutBusyOut(json, "doctor", lock.message, lock.path);
     }
     let fixed;
     let failed;
@@ -87,11 +97,36 @@ async function handleDoctor({ options }) {
       lock.release();
     }
     const result2 = createDoctorReport(adapter, target, manifestValidation, actionManifestPath);
-    const nextActions = doctorFixNextActions(failed, result2.fixture);
+    let runtime2;
+    let runtimeProbeError2;
+    try {
+      runtime2 = await surface.runtimeStatus(target);
+    } catch (error2) {
+      runtimeProbeError2 = error2 instanceof Error ? error2.message : String(error2);
+    }
+    const ready = runtime2?.decision === "ready";
+    if (adapter === "extension" && runtime2?.reasonCode === "product-config-required") {
+      failed.push("extension-product-config");
+    }
+    const nextActions = doctorFixNextActions(failed, result2.fixture, adapter, target);
+    if (failed.length === 0 && !ready && runtime2?.nextAction) nextActions.push(runtime2.nextAction);
     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, ready, runtime: runtime2, ...runtimeProbeError2 ? { runtimeProbeError: runtimeProbeError2 } : {}, nextActions, ...error ? { error } : {} }, null, 2));
     else {
-      console.log(`${status} ${adapter} ${result2.compatibilityMode} manifest=${actionManifestPath} fixed=[${fixed.join(",")}] failed=[${failed.join(",")}]`);
+      console.log(`${status} ${adapter} ${result2.compatibilityMode} ready=${ready} manifest=${actionManifestPath} fixed=[${fixed.join(",")}] failed=[${failed.join(",")}]`);
+      if (runtime2) {
+        console.log(`runtime: decision=${runtime2.decision}${runtime2.reasonCode ? ` (${runtime2.reasonCode})` : ""}`);
+        for (const reason of runtime2.reasons) console.log(`  ${reason}`);
+      } else if (runtimeProbeError2) {
+        console.log(`runtime probe failed: ${runtimeProbeError2}`);
+      }
       for (const action of nextActions) console.error(`  Next: ${action}`);
     }
     return status === "pass" ? 0 : 1;
@@ -104,8 +139,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);
@@ -123,7 +159,7 @@ async function handleDoctor({ options }) {
     requiredChecks
   };
   const orphanMetros = adapter === "mobile" ? detectOrphanMetros(target, process.env.WATCHER_PORT) : [];
-  const capture = captureHelperHealth();
+  const capture = captureHealth(adapter);
   const deviceView = adapter === "mobile" ? mobileDeviceView(allDevices) : null;
   const liveView = deviceView ? await mobileDeviceLiveView(target, deviceView) : null;
   const devices = liveView?.devicesWithLive ?? deviceView?.devices ?? [];
@@ -142,11 +178,17 @@ 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;
+  const next = doctorError?.userAction ?? (runtime?.decision === "ready" ? void 0 : runtime?.nextAction);
+  if (json) console.log(JSON.stringify({ ...doctorResult, ready: runtime?.decision === "ready", runtime, orphanMetros, capture, devices, additionalReachableDevices, ...next ? { next } : {}, ...doctorError ? { error: doctorError } : {} }, null, 2));
   else {
     const out = (style, text) => color(style, text, { stream: process.stdout });
     const stateStyle = (value, good) => value === good ? "ok" : "warn";
     console.log(`${out(doctorResult.status === "pass" ? "ok" : "err", doctorResult.status)} ${out("bold", adapter)} ${doctorResult.compatibilityMode} ${out("dim", `manifest=${actionManifestPath}`)}`);
+    console.log(
+      `${out("label", "harness:")} ${doctorResult.runner.packageName}@${doctorResult.runner.version} ${out("accent", doctorResult.runner.installKind)} ${out("dim", `executable=${doctorResult.runner.executablePath}`)}`
+    );
     if (runtime) {
       const provisionedDepsPending = runtime.reasonCode === "app-installed-deps-pending";
       const decisionStyle = provisionedDepsPending ? "info" : runtime.decision === "ready" ? "ok" : runtime.decision === "blocked" ? "err" : "warn";
@@ -173,18 +215,13 @@ async function handleDoctor({ options }) {
       );
       console.log(`  ${out("dim", "Next: mm-harness stop   # reaps every bundler this checkout leaked")}`);
     }
-    if (capture) {
-      console.log(`${out("label", "capture:")} ${out(capture.status === "pass" ? "ok" : "warn", capture.status)} ${out("dim", "(capture-helper: screenshots + --record video)")}`);
-      if (capture.status !== "pass") {
-        if (capture.failing.length > 0) console.log(`  ${out("dim", `failing: ${capture.failing.join(", ")}`)}`);
-        console.log(`  ${out("dim", "Next: grant Screen Recording (System Settings \u2192 Privacy & Security \u2192 Screen Recording), or run: capture-helper doctor --open-permissions")}`);
-      }
-    }
+    if (capture) renderCaptureHealth(capture, out);
     if (adapter === "mobile") {
       if (deviceView) renderMobileDeviceList(deviceView, out);
       if (additionalReachableDevices.length > 0) renderAdditionalReachableDevices(additionalReachableDevices, out);
       if (liveView) renderMobileLiveBlock(deviceView?.devices ?? [], liveView.liveMap, out);
     }
+    if (next) console.log(`  ${out("dim", `Next: ${next}`)}`);
   }
   return doctorResult.status === "pass" ? 0 : 1;
 }
@@ -207,15 +244,25 @@ function doctorRuntimeCheck(runtime, error, expectLive) {
     detail: runtime?.reasons.join(" | ") || "Runtime readiness probe returned no result."
   };
 }
-function doctorFixNextActions(failed, fixture) {
+function doctorFixNextActions(failed, fixture, adapter, target) {
   const actions = [];
+  const executable = process.env.MM_HARNESS_EXECUTABLE ? shellQuote(process.env.MM_HARNESS_EXECUTABLE) : "mm-harness";
+  const scope = `--adapter ${adapter} --target ${shellQuote(target)}`;
   if (failed.includes("wallet-fixture")) {
     const force = fixture.status === "invalid" || fixture.status === "incomplete" ? " --force" : "";
-    actions.push(`1) mm-harness fixtures init --from <path>${force}   # existing team/test fixture`);
-    actions.push(`2) mm-harness fixtures init --dev${force}           # disposable public test wallet; never real funds`);
+    actions.push(`1) ${executable} fixtures init --from <path>${force} ${scope}   # existing team/test fixture`);
+    actions.push(`2) ${executable} fixtures init --dev${force} ${scope}           # disposable public test wallet; never real funds`);
+  }
+  if (failed.includes("runtime-context")) {
+    actions.push(
+      `inspect ${shellQuote(resolveRuntimeContextPath(target))}, then retry ${executable} doctor --fix ${scope}`
+    );
+  }
+  if (failed.includes("overlay")) actions.push(`${executable} install ${scope}`);
+  if (adapter === "extension" && failed.includes("extension-product-config")) {
+    const block = extensionProductConfigBlock(target);
+    if (block) actions.push(block.userAction);
   }
-  if (failed.includes("runtime-context")) actions.push("inspect temp/recipe/runtime/agentic-runtime.json, then retry mm-harness doctor --fix");
-  if (failed.includes("overlay")) actions.push("mm-harness install --target .");
   return actions;
 }
 function emitExpectLiveVerdict(adapter, target, runtime, verdict) {
@@ -223,7 +270,7 @@ function emitExpectLiveVerdict(adapter, target, runtime, verdict) {
   const detail = runtime ? `${runtime.decision}${runtime.reasonCode ? ` (${runtime.reasonCode})` : ""}` : "runtime probe unavailable";
   console.error(`${out("err", verdict)} ${out("bold", adapter)} ${detail} ${out("dim", target)}`);
   for (const reason of runtime?.reasons ?? []) console.error(`  ${out("dim", reason)}`);
-  console.error(`  Next: ${getAdapterSurface(adapter).hints.relaunch}`);
+  console.error(`  Next: ${runtime?.nextAction ?? getAdapterSurface(adapter).hints.runtimeProbeRecovery(target)}`);
 }
 function emitExpectLive(adapter, target, runtime, result, orphanMetros, capture, devices, additionalReachableDevices, json, printReady) {
   const live = runtime?.decision === "ready";
@@ -241,7 +288,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 = runtime?.nextAction ?? getAdapterSurface(adapter).hints.runtimeProbeRecovery(target);
+    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 });
@@ -252,6 +301,25 @@ function emitExpectLive(adapter, target, runtime, result, orphanMetros, capture,
   emitExpectLiveVerdict(adapter, target, runtime, "not-live");
   return EXIT.runtime;
 }
+function captureHealth(adapter) {
+  if (adapter === "core") return null;
+  const fallback = adapter === "extension" ? ["cdp"] : ["simctl", "adb"];
+  const helper = captureHelperHealth();
+  if (!helper) {
+    return {
+      status: "fallback",
+      failing: [],
+      screenshots: { available: true, providers: fallback },
+      recording: { available: false, provider: null }
+    };
+  }
+  return {
+    status: helper.status,
+    failing: helper.failing,
+    screenshots: { available: true, providers: ["capture-helper", ...fallback] },
+    recording: { available: helper.status === "pass", provider: helper.status === "pass" ? "capture-helper" : null }
+  };
+}
 function captureHelperHealth() {
   if (process.platform !== "darwin") return null;
   const bin = process.env.CAPTURE_HELPER_PATH || "capture-helper";
@@ -264,6 +332,18 @@ function captureHelperHealth() {
     return null;
   }
 }
+function renderCaptureHealth(capture, out) {
+  const video = capture.recording.available ? "capture-helper" : "unavailable";
+  console.log(
+    `${out("label", "capture:")} ${out(capture.status === "pass" ? "ok" : "warn", capture.status)} ${out("dim", `(screenshots: ${capture.screenshots.providers.join(" \u2192 ")}; video: ${video})`)}`
+  );
+  if (capture.status === "warn") {
+    if (capture.failing.length > 0) console.log(`  ${out("dim", `failing: ${capture.failing.join(", ")}`)}`);
+    console.log(`  ${out("dim", "Next: grant Screen Recording (System Settings \u2192 Privacy & Security \u2192 Screen Recording), or run: capture-helper doctor --open-permissions")}`);
+  } else if (capture.status === "fallback") {
+    console.log(`  ${out("dim", "Next: screenshots work without capture-helper; install/configure capture-helper only when recipe video is required")}`);
+  }
+}
 function detectOrphanMetros(target, livePort) {
   try {
     const script = path.join(runnerDir, "adapters/shared/reap-checkout-metros.sh");
@@ -381,6 +461,7 @@ function readTextSnapshot(file) {
   }
 }
 export {
+  doctorFixNextActions,
   ensureExtensionPerpsBuildFlag,
   handleDoctor
 };

package/dist/commands/fixtures.js

@@ -5,21 +5,22 @@ import { runnerDir, walletFixturePath } from "../paths.js";
 import { getAdapterSurface } from "../adapters/surface.js";
 import { fixtureFileSummary, fixtureSummary } from "../doctor.js";
 import { acquireCheckoutLock } from "../checkout-lock.js";
+import { colorHumanMessage } from "../cli-color.js";
 import { applyDeviceTargeting } from "./device-target.js";
-import { ADAPTER_DETECT_NEXT, EXIT, flag, parseFlags, resolveAdapter, scriptOverride, spawnScript, spawnScriptStreaming, str, targetOf, usageOut } from "./shared.js";
+import { ADAPTER_DETECT_NEXT, checkoutBusyOut, EXIT, flag, parseFlags, resolveAdapter, scriptOverride, spawnScript, spawnScriptStreaming, str, targetOf, usageOut } from "./shared.js";
 const FIXTURES_BOOLEANS = /* @__PURE__ */ new Set(["dev", "force", "json"]);
-const MOBILE_FIXTURE_TIMEOUT_MS = 12e4;
-async function handleFixtures(argv, deps) {
+const FIXTURE_STREAM_TIMEOUT_MS = 12e4;
+async function handleFixtures(argv) {
   const { options } = parseFlags(argv, FIXTURES_BOOLEANS);
   const json = flag(options, "json");
   const target = targetOf(options);
-  if (!fs.existsSync(target)) return handleFixturesLocked(argv, deps);
+  if (!fs.existsSync(target)) return handleFixturesLocked(argv);
   const lock = acquireCheckoutLock(target, "fixtures");
   if ("message" in lock) {
-    return usageOut(json, "fixtures", lock.message, `wait for the current owner, or inspect ${lock.path} if its process has exited`);
+    return checkoutBusyOut(json, "fixtures", lock.message, lock.path);
   }
   try {
-    return await handleFixturesLocked(argv, deps);
+    return await handleFixturesLocked(argv);
   } finally {
     lock.release();
   }
@@ -49,13 +50,21 @@ function ensureFixturePublicationParent(target) {
   }
   return fs.realpathSync(parent) === parent ? null : `wallet fixture runtime path escapes the checkout: ${parent}`;
 }
-async function handleFixturesLocked(argv, deps) {
+async function handleFixturesLocked(argv) {
   const { positional, options } = parseFlags(argv, FIXTURES_BOOLEANS);
   const json = flag(options, "json");
   const sub = positional[0];
   if (sub !== "init" && sub !== "sync" && sub !== "set" && sub !== "generate" && sub !== "finalize") {
     return usageOut(json, "fixtures", "fixtures requires a subcommand: mm-harness fixtures <init|sync|set|generate|finalize>", "mm-harness fixtures init --from <path>   or   mm-harness fixtures init --dev");
   }
+  if (sub !== "init" && (flag(options, "dev") || flag(options, "force") || str(options, "from"))) {
+    return usageOut(
+      json,
+      "fixtures",
+      "--dev, --from, and --force belong to fixtures init; they do not apply a fixture.",
+      "mm-harness fixtures init --dev && mm-harness fixtures set"
+    );
+  }
   const target = targetOf(options);
   const adapter = resolveAdapter(options, target);
   if (!adapter) {
@@ -65,7 +74,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);
@@ -96,6 +105,17 @@ async function handleFixturesLocked(argv, deps) {
     return exitCode;
   }
   const fixturePath = path.resolve(str(options, "fixture") ?? process.env.RECIPE_WALLET_FIXTURE ?? canonicalFixture);
+  if (!fs.existsSync(fixturePath)) {
+    return usageOut(
+      json,
+      "fixtures",
+      `no wallet fixture at ${fixturePath}.`,
+      "mm-harness fixtures init --dev && mm-harness fixtures set"
+    );
+  }
+  if (adapter === "extension") {
+    return applyExtensionFixture(target, fixturePath, canonicalFixture, json);
+  }
   process.stderr.write(`\u2192 fixtures set ${adapter} \u2014 connecting bridge + applying wallet fixture (can take ~30s)\u2026
 `);
   let status;
@@ -105,8 +125,8 @@ async function handleFixturesLocked(argv, deps) {
     const previousAppRoot = process.env.APP_ROOT;
     process.env.APP_ROOT = target;
     try {
-      const configuredTimeout = Number(process.env.MM_HARNESS_FIXTURES_SET_TIMEOUT_MS ?? MOBILE_FIXTURE_TIMEOUT_MS);
-      const timeoutMs = Number.isFinite(configuredTimeout) && configuredTimeout > 0 ? configuredTimeout : MOBILE_FIXTURE_TIMEOUT_MS;
+      const configuredTimeout = Number(process.env.MM_HARNESS_FIXTURES_SET_TIMEOUT_MS ?? FIXTURE_STREAM_TIMEOUT_MS);
+      const timeoutMs = Number.isFinite(configuredTimeout) && configuredTimeout > 0 ? configuredTimeout : FIXTURE_STREAM_TIMEOUT_MS;
       mobileSetupResult = await spawnScriptStreaming(
         setupWalletSh,
         ["--fixture", fixturePath],
@@ -128,29 +148,8 @@ async function handleFixturesLocked(argv, deps) {
     if (!json && status === "fail") {
       console.error(`  Next: ${retryHint}`);
     }
-  } else {
-    if (!fs.existsSync(fixturePath)) {
-      return usageOut(
-        json,
-        "fixtures",
-        `no wallet fixture at ${fixturePath}.`,
-        "create it (or pass --fixture <path>), then re-run: mm-harness fixtures set"
-      );
-    }
-    const previousFixtureEnv = process.env.RECIPE_WALLET_FIXTURE;
-    process.env.RECIPE_WALLET_FIXTURE = fixturePath;
-    try {
-      const result = await deps.runOneNode("extension", "metamask.wallet.setup", {}, target, str(options, "actionManifest"));
-      status = result.status;
-    } finally {
-      if (previousFixtureEnv === void 0) delete process.env.RECIPE_WALLET_FIXTURE;
-      else process.env.RECIPE_WALLET_FIXTURE = previousFixtureEnv;
-    }
-    if (!json && status === "fail") {
-      console.error(`  Next: ${retryHint}`);
-    }
   }
-  const teaching = `Wallet fixture applied.  Want different accounts? Edit: ${canonicalFixture}`;
+  const teaching = status === "pass" ? `Wallet fixture applied.  Want different accounts? Edit: ${canonicalFixture}` : "Wallet fixture was not applied.";
   if (json) {
     console.log(
       JSON.stringify(
@@ -174,11 +173,68 @@ async function handleFixturesLocked(argv, deps) {
         2
       )
     );
-  } else {
+  } else if (status === "pass") {
     console.error(teaching);
   }
   return status === "pass" ? EXIT.ok : EXIT.runtime;
 }
+async function applyExtensionFixture(target, fixturePath, canonicalFixture, json) {
+  const distManifest = path.join(target, "dist/chrome/manifest.json");
+  const userAction = `mm-harness launch --build --verify --target ${JSON.stringify(target)}`;
+  if (!fs.existsSync(distManifest)) {
+    const message2 = `Extension fixture needs an existing dist/chrome build; no manifest was found at ${distManifest}.`;
+    if (json) {
+      console.log(JSON.stringify({
+        schemaVersion: 1,
+        command: "fixtures",
+        action: "set",
+        adapter: "extension",
+        fixture: fixturePath,
+        canonicalFixture,
+        status: "fail",
+        exitCode: EXIT.runtime,
+        error: { code: "EXTENSION_FIXTURE_BUILD_REQUIRED", message: message2, userAction }
+      }, null, 2));
+    } else {
+      console.error(`\u2717 mm-harness fixtures set: ${message2}
+  Next: ${userAction}`);
+    }
+    return EXIT.runtime;
+  }
+  process.stderr.write(`${colorHumanMessage("\u2192 fixtures set extension \u2014 resetting and seeding the slot-owned profile from the existing build\u2026")}
+`);
+  const liveScript = path.join(runnerDir, "adapters/extension/live.sh");
+  const args = ["--target", target, "--launch-existing-dist"];
+  if (process.env.CDP_PORT) args.push("--cdp-port", process.env.CDP_PORT);
+  const result = await spawnScriptStreaming(liveScript, args, target, {
+    env: { RECIPE_WALLET_FIXTURE: fixturePath },
+    timeoutMs: FIXTURE_STREAM_TIMEOUT_MS
+  });
+  const status = result.status === 0 ? "pass" : "fail";
+  const exitCode = status === "pass" ? EXIT.ok : EXIT.runtime;
+  const message = status === "pass" ? `Wallet fixture applied and validated. Want different accounts? Edit: ${canonicalFixture}` : "Extension wallet fixture could not be applied and validated.";
+  if (json) {
+    console.log(JSON.stringify({
+      schemaVersion: 1,
+      command: "fixtures",
+      action: "set",
+      adapter: "extension",
+      fixture: fixturePath,
+      canonicalFixture,
+      status,
+      exitCode,
+      profileReset: status === "pass",
+      message,
+      error: status === "fail" ? { code: "EXTENSION_FIXTURE_APPLY_FAILED", message, userAction } : null
+    }, null, 2));
+  } else if (status === "pass") {
+    console.error(message);
+  } else {
+    console.error(`\u2717 mm-harness fixtures set: ${message}
+  Next: ${userAction}`);
+  }
+  return exitCode;
+}
 const EXT_FIXTURE_LEAF = "adapters/extension/wallet-fixture-state.cjs";
 function emitLeafMissing(json, action, fields, leaf) {
   const message = `leaf could not start: ${path.basename(leaf)} (ENOENT).`;
@@ -298,7 +354,9 @@ async function fixturesFinalize(adapter, target, options, json) {
   if (outPath) leafArgs.push("--out", outPath);
   process.stderr.write(`\u2192 fixtures finalize extension \u2014 seeding account labels via CDP on port ${cdpPort} (can take ~30s)\u2026
 `);
-  const result = await spawnScriptStreaming(process.execPath, leafArgs, target);
+  const result = await spawnScriptStreaming(process.execPath, leafArgs, target, {
+    timeoutMs: FIXTURE_STREAM_TIMEOUT_MS
+  });
   const status = result.status === 0 ? "pass" : "fail";
   const exitCode = result.status === 0 ? EXIT.ok : EXIT.runtime;
   const retry = `mm-harness fixtures finalize --fixture ${fixturePath} --state ${statePath} --cdp-port ${cdpPort} --extension-dir ${extensionDirPath}`;

package/dist/commands/flows.js

@@ -2,18 +2,18 @@ import path from "node:path";
 import { color } from "../cli-color.js";
 import { importRecipeHarnessCli } from "../paths.js";
 import { EXIT } from "./shared.js";
-import { usageError } from "./parse-args.js";
+import { parseArgs, usageError } from "./parse-args.js";
 import { resolveMetaMaskLibrarySources } from "./run-engine.js";
-const FLOWS_SUBCOMMANDS = ["list", "promote"];
-function stripTargetFlag(argv) {
+const FLOWS_SUBCOMMANDS = ["list", "describe", "promote"];
+function stripFrontOnlyFlags(argv) {
   const out = [];
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
-    if (arg === "--target") {
+    if (arg === "--target" || arg === "--library") {
       i += 1;
       continue;
     }
-    if (arg.startsWith("--target=")) continue;
+    if (arg.startsWith("--target=") || arg.startsWith("--library=")) continue;
     out.push(arg);
   }
   return out;
@@ -30,14 +30,37 @@ function restoreEnv(key, value) {
   if (value === void 0) delete process.env[key];
   else process.env[key] = value;
 }
+function libraryEntries(argv) {
+  const entries = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === "--library") {
+      const value = argv[index + 1];
+      if (value !== void 0) entries.push(value);
+      index += 1;
+    } else if (argument.startsWith("--library=")) {
+      entries.push(argument.slice("--library=".length));
+    }
+  }
+  return entries;
+}
 async function handleFlows(argv) {
-  const sources = await resolveMetaMaskLibrarySources(void 0);
+  const { positional } = parseArgs(argv);
+  const subcommand = positional[0];
+  if (subcommand === "describe" && !positional[1]) {
+    throw usageError("flows describe requires <ref>. Next: mm-harness flows list");
+  }
+  if (subcommand !== "describe" && positional[1]) {
+    throw usageError(`flows ${subcommand ?? "list"} does not accept positional ${positional[1]}.`);
+  }
+  const configuredLibraries = libraryEntries(argv);
+  const sources = await resolveMetaMaskLibrarySources(configuredLibraries);
   if (!sources) {
     throw usageError(
       "flows requires @farmslot/recipe-harness >= 0.3.3 (recipe-library support; flows resolve personal > team > canonical). Next: update the dependency and run yarn install."
     );
   }
-  const forwarded = stripTargetFlag(argv);
+  const forwarded = stripFrontOnlyFlags(argv);
   const jsonMode = forwarded.includes("--json");
   if (!jsonMode) {
     console.error(color("label", "flows resolve by precedence (highest wins; local shadows canonical):"));
@@ -46,16 +69,22 @@ async function handleFlows(argv) {
       console.error(`  ${index + 1}. ${color("cmd", name)} ${color("dim", `[${flowSourceTier(source, index, sources.length)}]`)}`);
     });
   }
-  const withSubcommand = FLOWS_SUBCOMMANDS.includes(forwarded[0]) ? forwarded : ["list", ...forwarded];
+  const resolvedSubcommand = subcommand && FLOWS_SUBCOMMANDS.includes(subcommand) ? subcommand : "list";
+  const forwardedSubcommandIndex = forwarded.indexOf(resolvedSubcommand);
+  const delegatedArgs = forwardedSubcommandIndex === -1 ? forwarded : forwarded.filter((_, index) => index !== forwardedSubcommandIndex);
+  const withSubcommand = [resolvedSubcommand, ...delegatedArgs];
   const { runRecipeHarnessCli } = await importRecipeHarnessCli();
   const previousLibraryPath = process.env.RECIPE_LIBRARY_PATH;
+  const previousExitCode = process.exitCode;
   process.env.RECIPE_LIBRARY_PATH = serializeLibrarySources(sources);
+  process.exitCode = void 0;
   try {
-    await runRecipeHarnessCli(["flows", ...withSubcommand]);
+    await runRecipeHarnessCli(["flows", ...withSubcommand], { commandName: "mm-harness" });
+    return typeof process.exitCode === "number" ? process.exitCode : EXIT.ok;
   } finally {
     restoreEnv("RECIPE_LIBRARY_PATH", previousLibraryPath);
+    process.exitCode = previousExitCode;
   }
-  return EXIT.ok;
 }
 export {
   handleFlows

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