@deeeed/metamask-harness 0.17.5 → 0.19.0

package/dist/commands/device-target.js

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

package/dist/commands/doctor.js

@@ -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,25 +5,75 @@ 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 { options } = parseFlags(argv, FIXTURES_BOOLEANS);
+const FIXTURE_STREAM_TIMEOUT_MS = 12e4;
+async function handleFixtures(argv) {
+  const { positional, options } = parseFlags(argv, FIXTURES_BOOLEANS);
+  if (!positional[0]) return fixturesStatus(options);
   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();
   }
 }
+function fixturesStatus(options) {
+  const json = flag(options, "json");
+  const statusOptions = /* @__PURE__ */ new Set(["json", "target", "adapter", "platform", "device"]);
+  const actionOption = Object.keys(options).find((key) => !statusOptions.has(key));
+  if (actionOption) {
+    return usageOut(
+      json,
+      "fixtures",
+      `--${actionOption.replace(/[A-Z]/gu, (letter) => `-${letter.toLowerCase()}`)} requires a fixture action.`,
+      "mm-harness fixtures --help"
+    );
+  }
+  const target = targetOf(options);
+  const adapter = resolveAdapter(options, target);
+  if (!adapter) {
+    return usageOut(json, "fixtures", `could not detect the MetaMask repo type for ${target}`, ADAPTER_DETECT_NEXT);
+  }
+  const canonical = walletFixturePath(target);
+  const summary = fixtureSummary(target, adapter);
+  const fixture = { ...summary, path: canonical };
+  const ready = summary.status === "ready";
+  const nextCommand = ready ? "mm-harness fixtures set" : "mm-harness fixtures init --from <path>   # or: mm-harness fixtures init --dev";
+  const operations = adapter === "extension" ? ["init", "sync", "set", "generate", "finalize"] : ["init", "sync", "set"];
+  if (json) {
+    console.log(JSON.stringify({
+      schemaVersion: 1,
+      command: "fixtures",
+      action: "status",
+      adapter,
+      target,
+      status: "pass",
+      fixture,
+      operations,
+      nextCommand,
+      exitCode: EXIT.ok
+    }, null, 2));
+    return EXIT.ok;
+  }
+  console.log(`wallet fixture (${adapter}): ${String(summary.status).toUpperCase()}`);
+  console.log(`path: ${canonical}`);
+  if (typeof summary.accountCount === "number") {
+    const password = summary.hasPassword === true ? "present" : "missing";
+    console.log(`accounts: ${summary.accountCount} \xB7 password: ${password}`);
+  }
+  console.log(`operations: ${operations.join(", ")}`);
+  console.log(`Next: ${nextCommand}`);
+  return EXIT.ok;
+}
 function ensureFixturePublicationParent(target) {
   const repoRoot = fs.realpathSync(target);
   const parent = path.dirname(walletFixturePath(repoRoot));
@@ -49,13 +99,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 +123,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 +154,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 +174,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 +197,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 +222,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 +403,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}`;