@deeeed/metamask-harness 0.17.3 → 0.17.5

package/dist/commands/checklist.js

@@ -4,6 +4,9 @@ import { createRequire } from "node:module";
 import path from "node:path";
 import { EXIT } from "./shared.js";
 const require2 = createRequire(import.meta.url);
+const MARK_SCRIPT = require2.resolve(
+  "@farmslot/agent-runtime/scripts/mark-checklist-step.cjs"
+);
 const USAGE = "mm-harness checklist mark <task-dir> <step> [options]";
 function terminalSignalStatus(taskDir) {
   try {
@@ -122,7 +125,7 @@ async function handleChecklist(argv) {
   teachRecipeCompletion(resolvedTaskDir, markArgs);
   const result = spawnSync(
     process.execPath,
-    [require2.resolve("@farmslot/agent-runtime/scripts/mark-checklist-step.cjs"), resolvedTaskDir, ...markArgs],
+    [MARK_SCRIPT, resolvedTaskDir, ...markArgs],
     { stdio: "inherit" }
   );
   if (result.error) {

package/dist/commands/debug.js

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

package/dist/commands/device-target.js

@@ -1,6 +1,6 @@
 import { execFileSync } from "node:child_process";
 import { listConnectedDevices } from "../devices.js";
-import { optionString, shellQuoteArg, targetPath } from "./parse-args.js";
+import { optionString } from "./parse-args.js";
 function normalizeDeviceName(value) {
   return value.replace(/_/gu, " ").trim();
 }
@@ -75,12 +75,6 @@ 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);
@@ -90,8 +84,7 @@ 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.`,
-        userAction: `remove --device; ${adapter} has no device target`
+  Drop --device, or run this ${command} inside a metamask-mobile checkout.`
       };
     }
     return { ok: true };
@@ -104,8 +97,7 @@ 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.`,
-          userAction: deviceRecovery(options, opts.rerun)
+  To use this device intentionally, drop --platform ${platformPreference} or choose a ${platformPreference} device.`
         };
       }
       if (matched.platform === "android") setAndroidDeviceEnv(matched.id, matched.name);
@@ -134,8 +126,7 @@ 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"),
-        userAction: deviceRecovery(options, opts.rerun)
+` + byName.map((d) => `    - ${d.id}${d.name ? ` (${d.name})` : ""} [${d.state}] ${d.platform}`).join("\n")
       };
     }
     return {
@@ -143,8 +134,7 @@ 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).`),
-      userAction: deviceRecovery(options, opts.rerun)
+${formatConnectedDevices(connected2)}` : `  No devices are currently connected (adb devices / booted iOS simulators).`)
     };
   }
   const connected = listConnectedDevices();
@@ -168,8 +158,7 @@ ${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>.`,
-        userAction: deviceRecovery(options, opts.rerun)
+  To use a different connected device intentionally, pass --device <id>.`
       };
     }
     if (!configuredPin && oppositePin) {
@@ -178,8 +167,7 @@ ${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>.`,
-        userAction: deviceRecovery(options, opts.rerun)
+  To use a different connected device intentionally, pass --device <id>.`
       };
     }
     if (configuredPin) {
@@ -190,8 +178,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"}`,
-        userAction: `mm-harness launch ${platformPreference} --target ${shellQuoteArg(targetPath(options))}`
+${connected.length > 0 ? formatConnectedDevices(connected) : "    - none"}
+  Next: run mm-harness launch ${platformPreference}, or pass --device <id> to intentionally use another target.`
       };
     }
     if (platformTargetable.length === 1) {
@@ -207,8 +195,7 @@ ${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).`),
-        userAction: deviceRecovery(options, opts.rerun)
+${formatConnectedDevices(connected)}` : `  No devices are currently connected (adb devices / booted iOS simulators).`)
       };
     }
     return {
@@ -218,8 +205,7 @@ ${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("")}`,
-      userAction: deviceRecovery(options, opts.rerun)
+    --device ${d.id}`).join("")}`
     };
   }
   const selectedTargetable = targetable.filter(deviceSelected);
@@ -238,8 +224,7 @@ ${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("")}`),
-      userAction: deviceRecovery(options, opts.rerun)
+    --device ${d.id}`).join("")}`)
     };
   }
   return { ok: true };

package/dist/commands/doctor.js

@@ -4,7 +4,7 @@ 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, resolveRuntimeContextPath } from "../harness.js";
+import { detectAdapter } from "../harness.js";
 import { assertAdapter, runnerDir } from "../paths.js";
 import { getAdapterSurface } from "../adapters/surface.js";
 import { ensureMobilePerpsEnvironment, mobilePerpsEnvironment } from "../adapters/mobile/perps-env.js";
@@ -21,13 +21,12 @@ import {
 import { farmslotReadyIndicator } from "./farmslot-ready.js";
 import { ensureRuntimeContext } from "../runtime-context.js";
 import { acquireCheckoutLock } from "../checkout-lock.js";
-import { ADAPTER_DETECT_NEXT, checkoutBusyOut, EXIT, usageOut } from "./shared.js";
+import { ADAPTER_DETECT_NEXT, EXIT, usageOut } from "./shared.js";
 import {
   actionManifestPathOption,
   applyRuntimeDirOption,
   optionFlag,
   optionString,
-  shellQuote,
   targetPath
 } from "./parse-args.js";
 function applyDoctorRuntimePorts(options) {
@@ -57,14 +56,6 @@ 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,
@@ -81,12 +72,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, dtResult.userAction);
+      return usageOut(json, "doctor", dtResult.message, "mm-harness doctor --fix --adapter mobile --device <adb-serial|simulator-udid>");
     }
     applyDoctorRuntimePorts(options);
     const lock = acquireCheckoutLock(target, "doctor-fix");
     if ("message" in lock) {
-      return checkoutBusyOut(json, "doctor", lock.message, lock.path);
+      return usageOut(json, "doctor", lock.message, `wait for the current owner, or inspect ${lock.path} if its process has exited`);
     }
     let fixed;
     let failed;
@@ -96,16 +87,9 @@ async function handleDoctor({ options }) {
       lock.release();
     }
     const result2 = createDoctorReport(adapter, target, manifestValidation, actionManifestPath);
-    const nextActions = doctorFixNextActions(failed, result2.fixture, adapter, target);
+    const nextActions = doctorFixNextActions(failed, result2.fixture);
     const status = result2.status === "pass" && failed.length === 0 ? "pass" : "fail";
-    const retryDoctor = `mm-harness doctor --fix --adapter ${adapter} --target ${shellQuote(target)} --json`;
-    const fixUserAction = failed.includes("wallet-fixture") ? `choose one wallet fixture source from nextActions, run it, then retry: ${retryDoctor}` : nextActions[0] ?? retryDoctor;
-    const error = status === "fail" ? {
-      code: "DOCTOR_FIX_INCOMPLETE",
-      message: "doctor --fix could not make every required check pass",
-      userAction: fixUserAction
-    } : void 0;
-    if (json) console.log(JSON.stringify({ ...result2, status, fixed, failed, nextActions, ...error ? { error } : {} }, null, 2));
+    if (json) console.log(JSON.stringify({ ...result2, status, fixed, failed, nextActions }, null, 2));
     else {
       console.log(`${status} ${adapter} ${result2.compatibilityMode} manifest=${actionManifestPath} fixed=[${fixed.join(",")}] failed=[${failed.join(",")}]`);
       for (const action of nextActions) console.error(`  Next: ${action}`);
@@ -120,9 +104,8 @@ 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, userAction: dtResult.userAction } }, null, 2));
-      else console.error(`\u2717 doctor: ${dtResult.message}
-  Next: ${dtResult.userAction}`);
+      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}`);
       return EXIT.usage;
     }
     applyDoctorRuntimePorts(options);
@@ -140,7 +123,7 @@ async function handleDoctor({ options }) {
     requiredChecks
   };
   const orphanMetros = adapter === "mobile" ? detectOrphanMetros(target, process.env.WATCHER_PORT) : [];
-  const capture = captureHealth(adapter);
+  const capture = captureHelperHealth();
   const deviceView = adapter === "mobile" ? mobileDeviceView(allDevices) : null;
   const liveView = deviceView ? await mobileDeviceLiveView(target, deviceView) : null;
   const devices = liveView?.devicesWithLive ?? deviceView?.devices ?? [];
@@ -159,9 +142,7 @@ async function handleDoctor({ options }) {
       printReady
     );
   }
-  const doctorUserAction = `mm-harness doctor --fix --adapter ${adapter} --target ${shellQuote(target)} --json`;
-  const doctorError = doctorResult.status === "fail" ? { code: "DOCTOR_CHECKS_FAILED", message: "one or more required doctor checks failed", userAction: doctorUserAction } : void 0;
-  if (json) console.log(JSON.stringify({ ...doctorResult, ready: runtime?.decision === "ready", runtime, orphanMetros, capture, devices, additionalReachableDevices, ...doctorError ? { error: doctorError } : {} }, null, 2));
+  if (json) console.log(JSON.stringify({ ...doctorResult, ready: runtime?.decision === "ready", runtime, orphanMetros, capture, devices, additionalReachableDevices }, null, 2));
   else {
     const out = (style, text) => color(style, text, { stream: process.stdout });
     const stateStyle = (value, good) => value === good ? "ok" : "warn";
@@ -192,13 +173,18 @@ async function handleDoctor({ options }) {
       );
       console.log(`  ${out("dim", "Next: mm-harness stop   # reaps every bundler this checkout leaked")}`);
     }
-    if (capture) renderCaptureHealth(capture, out);
+    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 (adapter === "mobile") {
       if (deviceView) renderMobileDeviceList(deviceView, out);
       if (additionalReachableDevices.length > 0) renderAdditionalReachableDevices(additionalReachableDevices, out);
       if (liveView) renderMobileLiveBlock(deviceView?.devices ?? [], liveView.liveMap, out);
     }
-    if (doctorError) console.log(`  ${out("dim", `Next: ${doctorUserAction}`)}`);
   }
   return doctorResult.status === "pass" ? 0 : 1;
 }
@@ -221,21 +207,15 @@ function doctorRuntimeCheck(runtime, error, expectLive) {
     detail: runtime?.reasons.join(" | ") || "Runtime readiness probe returned no result."
   };
 }
-function doctorFixNextActions(failed, fixture, adapter, target) {
+function doctorFixNextActions(failed, fixture) {
   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) ${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}`
-    );
+    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`);
   }
-  if (failed.includes("overlay")) actions.push(`${executable} install ${scope}`);
+  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) {
@@ -261,9 +241,7 @@ function emitExpectLive(adapter, target, runtime, result, orphanMetros, capture,
     return EXIT.runtime;
   }
   if (json) {
-    const userAction = adapter === "extension" ? `mm-harness launch --adapter extension --target ${shellQuote(target)}` : adapter === "core" ? `mm-harness verify --adapter core --target ${shellQuote(target)}` : `mm-harness status --target ${shellQuote(target)} --json`;
-    const error = live ? void 0 : { code: "RUNTIME_NOT_LIVE", message: `${adapter} runtime is not live`, userAction };
-    console.log(JSON.stringify({ ...result, ready: live, runtime, orphanMetros, capture, devices, additionalReachableDevices, ...error ? { error } : {} }, null, 2));
+    console.log(JSON.stringify({ ...result, ready: live, runtime, orphanMetros, capture, devices, additionalReachableDevices }, null, 2));
     return live ? EXIT.ok : EXIT.runtime;
   }
   const out = (style, text) => color(style, text, { stream: process.stdout });
@@ -274,25 +252,6 @@ 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";
@@ -305,18 +264,6 @@ 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");
@@ -434,7 +381,6 @@ function readTextSnapshot(file) {
   }
 }
 export {
-  doctorFixNextActions,
   ensureExtensionPerpsBuildFlag,
   handleDoctor
 };

package/dist/commands/fixtures.js

@@ -6,9 +6,9 @@ import { getAdapterSurface } from "../adapters/surface.js";
 import { fixtureFileSummary, fixtureSummary } from "../doctor.js";
 import { acquireCheckoutLock } from "../checkout-lock.js";
 import { applyDeviceTargeting } from "./device-target.js";
-import { ADAPTER_DETECT_NEXT, checkoutBusyOut, EXIT, flag, parseFlags, resolveAdapter, scriptOverride, spawnScript, spawnScriptStreaming, str, targetOf, usageOut } from "./shared.js";
+import { ADAPTER_DETECT_NEXT, EXIT, flag, parseFlags, resolveAdapter, scriptOverride, spawnScript, spawnScriptStreaming, str, targetOf, usageOut } from "./shared.js";
 const FIXTURES_BOOLEANS = /* @__PURE__ */ new Set(["dev", "force", "json"]);
-const FIXTURE_STREAM_TIMEOUT_MS = 12e4;
+const MOBILE_FIXTURE_TIMEOUT_MS = 12e4;
 async function handleFixtures(argv, deps) {
   const { options } = parseFlags(argv, FIXTURES_BOOLEANS);
   const json = flag(options, "json");
@@ -16,7 +16,7 @@ async function handleFixtures(argv, deps) {
   if (!fs.existsSync(target)) return handleFixturesLocked(argv, deps);
   const lock = acquireCheckoutLock(target, "fixtures");
   if ("message" in lock) {
-    return checkoutBusyOut(json, "fixtures", lock.message, lock.path);
+    return usageOut(json, "fixtures", lock.message, `wait for the current owner, or inspect ${lock.path} if its process has exited`);
   }
   try {
     return await handleFixturesLocked(argv, deps);
@@ -56,14 +56,6 @@ async function handleFixturesLocked(argv, deps) {
   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) {
@@ -73,7 +65,7 @@ async function handleFixturesLocked(argv, deps) {
   surface.resolveSlotPorts(target);
   const dtResult = applyDeviceTargeting("fixtures", adapter, options, { gate: false, rerun: "" });
   if ("code" in dtResult) {
-    return usageOut(json, "fixtures", dtResult.message, dtResult.userAction);
+    return usageOut(json, "fixtures", dtResult.message, "mm-harness fixtures set --adapter mobile --device <adb-serial|simulator-udid>");
   }
   if (sub === "generate") return fixturesGenerate(adapter, target, options, json);
   if (sub === "finalize") return fixturesFinalize(adapter, target, options, json);
@@ -104,14 +96,6 @@ 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"
-    );
-  }
   process.stderr.write(`\u2192 fixtures set ${adapter} \u2014 connecting bridge + applying wallet fixture (can take ~30s)\u2026
 `);
   let status;
@@ -121,8 +105,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 ?? FIXTURE_STREAM_TIMEOUT_MS);
-      const timeoutMs = Number.isFinite(configuredTimeout) && configuredTimeout > 0 ? configuredTimeout : FIXTURE_STREAM_TIMEOUT_MS;
+      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;
       mobileSetupResult = await spawnScriptStreaming(
         setupWalletSh,
         ["--fixture", fixturePath],
@@ -145,6 +129,14 @@ async function handleFixturesLocked(argv, deps) {
       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 {
@@ -158,7 +150,7 @@ async function handleFixturesLocked(argv, deps) {
       console.error(`  Next: ${retryHint}`);
     }
   }
-  const teaching = status === "pass" ? `Wallet fixture applied.  Want different accounts? Edit: ${canonicalFixture}` : "Wallet fixture was not applied.";
+  const teaching = `Wallet fixture applied.  Want different accounts? Edit: ${canonicalFixture}`;
   if (json) {
     console.log(
       JSON.stringify(
@@ -182,7 +174,7 @@ async function handleFixturesLocked(argv, deps) {
         2
       )
     );
-  } else if (status === "pass") {
+  } else {
     console.error(teaching);
   }
   return status === "pass" ? EXIT.ok : EXIT.runtime;
@@ -306,9 +298,7 @@ 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, {
-    timeoutMs: FIXTURE_STREAM_TIMEOUT_MS
-  });
+  const result = await spawnScriptStreaming(process.execPath, leafArgs, target);
   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/launch/extension.js

@@ -7,6 +7,7 @@ import { recipeHarnessPath, recipeRuntimeDir, runnerDir } from "../../paths.js";
 import { extensionIdFromKey } from "../../adapters/extension/extension-id.js";
 import { isExtensionDistStale } from "../../adapters/extension/runtime-decision.js";
 import { checkExtensionRuntimeHealth } from "../../adapters/extension/runtime.js";
+import { ensureExtensionHarnessFresh } from "../../adapters/extension/harness-freshness.js";
 import { stopExtensionWatcher } from "../../adapters/slot-ports.js";
 import { spawnScriptStreaming } from "../shared.js";
 function extensionDepsBlock(target) {
@@ -29,6 +30,7 @@ function installExtensionDeps(target) {
   return spawnScriptStreaming(installScript, ["--target", target], target);
 }
 async function launchExtension(target, tier, wantWatch, displayMode = "fullscreen") {
+  await ensureExtensionHarnessFresh(target);
   if (wantWatch) {
     const startWatchSh = path.join(runnerDir, "adapters/extension/start-watch.sh");
     const watchArgs = ["--target", target];