@deeeed/metamask-harness 0.14.7 → 0.15.1

package/dist/commands/doctor.js

@@ -1,10 +1,13 @@
 import { execFileSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
 import path from "node:path";
 import { color } from "../cli-color.js";
-import { createDoctorReport, renderRuntimeContext } from "../doctor.js";
-import { detectAdapter } from "../harness.js";
+import { createDoctorReport, fixtureSummary, renderRuntimeContext, requiredDoctorCheckSummary } from "../doctor.js";
+import { detectAdapter, resolveRuntimeContextPath } from "../harness.js";
 import { assertAdapter, runnerDir } from "../paths.js";
 import { getAdapterSurface } from "../adapters/surface.js";
+import { ensureMobilePerpsEnvironment, mobilePerpsEnvironment } from "../adapters/mobile/perps-env.js";
 import { loadActionManifest, validateManifest } from "../manifest.js";
 import { ensureOverlay, newHealState, recipeRunning } from "../heal-bounds.js";
 import { applyDeviceTargeting } from "./device-target.js";
@@ -16,12 +19,15 @@ import {
   renderMobileLiveBlock
 } from "./mobile-device-view.js";
 import { farmslotReadyIndicator } from "./farmslot-ready.js";
-import { ADAPTER_DETECT_NEXT, EXIT, usageOut } from "./shared.js";
+import { ensureRuntimeContext } from "../runtime-context.js";
+import { acquireCheckoutLock } from "../checkout-lock.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) {
@@ -51,6 +57,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,
@@ -63,14 +77,37 @@ async function handleDoctor({ options }) {
   const manifest = loadActionManifest(adapter, optionString(options, "actionManifest"));
   const manifestValidation = await validateManifest(manifest);
   if (optionFlag(options, "fix")) {
-    const { fixed, failed } = await runDoctorFix(adapter, target, manifestValidation, json);
+    const surface = getAdapterSurface(adapter);
+    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>");
+    }
+    applyDoctorRuntimePorts(options);
+    const lock = acquireCheckoutLock(target, "doctor-fix");
+    if ("message" in lock) {
+      return checkoutBusyOut(json, "doctor", lock.message, lock.path);
+    }
+    let fixed;
+    let failed;
+    try {
+      ({ fixed, failed } = await runDoctorFix(adapter, target, manifestValidation, json));
+    } finally {
+      lock.release();
+    }
     const result2 = createDoctorReport(adapter, target, manifestValidation, actionManifestPath);
-    if (json) console.log(JSON.stringify({ ...result2, fixed, failed }, null, 2));
-    else console.log(`${result2.status} ${adapter} ${result2.compatibilityMode} manifest=${actionManifestPath} fixed=[${fixed.join(",")}] failed=[${failed.join(",")}]`);
-    return failed.length === 0 ? 0 : 1;
+    const nextActions = doctorFixNextActions(failed, result2.fixture, adapter, target);
+    const status = result2.status === "pass" && failed.length === 0 ? "pass" : "fail";
+    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}`);
+    }
+    return status === "pass" ? 0 : 1;
   }
   const result = createDoctorReport(adapter, target, manifestValidation, actionManifestPath);
   let runtime;
+  let runtimeProbeError;
   try {
     const surface = getAdapterSurface(adapter);
     surface.resolveSlotPorts(target);
@@ -82,8 +119,18 @@ async function handleDoctor({ options }) {
     }
     applyDoctorRuntimePorts(options);
     runtime = await surface.runtimeStatus(target);
-  } catch {
+  } catch (error) {
+    runtimeProbeError = error instanceof Error ? error.message : String(error);
   }
+  const runtimeCheck = doctorRuntimeCheck(runtime, runtimeProbeError, expectLive);
+  const checks = [...result.checks, runtimeCheck];
+  const requiredChecks = requiredDoctorCheckSummary(checks);
+  const doctorResult = {
+    ...result,
+    status: requiredChecks.status,
+    checks,
+    requiredChecks
+  };
   const orphanMetros = adapter === "mobile" ? detectOrphanMetros(target, process.env.WATCHER_PORT) : [];
   const capture = captureHelperHealth();
   const deviceView = adapter === "mobile" ? mobileDeviceView(allDevices) : null;
@@ -95,7 +142,7 @@ async function handleDoctor({ options }) {
       adapter,
       target,
       runtime,
-      result,
+      doctorResult,
       orphanMetros,
       capture,
       devices,
@@ -104,11 +151,11 @@ async function handleDoctor({ options }) {
       printReady
     );
   }
-  if (json) console.log(JSON.stringify({ ...result, runtime, orphanMetros, capture, devices, additionalReachableDevices }, 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";
-    console.log(`${out(result.status === "pass" ? "ok" : "err", result.status)} ${out("bold", adapter)} ${result.compatibilityMode} ${out("dim", `manifest=${actionManifestPath}`)}`);
+    console.log(`${out(doctorResult.status === "pass" ? "ok" : "err", doctorResult.status)} ${out("bold", adapter)} ${doctorResult.compatibilityMode} ${out("dim", `manifest=${actionManifestPath}`)}`);
     if (runtime) {
       const provisionedDepsPending = runtime.reasonCode === "app-installed-deps-pending";
       const decisionStyle = provisionedDepsPending ? "info" : runtime.decision === "ready" ? "ok" : runtime.decision === "blocked" ? "err" : "warn";
@@ -119,8 +166,16 @@ async function handleDoctor({ options }) {
         `${out("label", "runtime:")} decision=${out(decisionStyle, runtime.decision)}${runtime.reasonCode ? ` ${out("dim", `(${runtime.reasonCode})`)}` : ""} deps=${out(depsStyle, runtime.deps ?? "unknown")}${devServer}`
       );
       for (const reason of runtime.reasons) console.log(`  ${out("dim", reason)}`);
+    } else if (runtimeProbeError) {
+      console.log(`${out("err", "runtime probe failed:")} ${out("dim", runtimeProbeError)}`);
     }
     console.log(renderRuntimeContext(result.runtimeContext));
+    if (adapter === "mobile") {
+      const perps = mobilePerpsEnvironment(target);
+      console.log(
+        `mobile-perps: ${perps.status} (${perps.file}; MM_PERPS_ENABLED=${perps.perpsEnabled.value ?? "missing"}; OVERRIDE_REMOTE_FEATURE_FLAGS=${perps.remoteFeatureFlagOverride.value ?? "missing"})`
+      );
+    }
     if (orphanMetros.length > 0) {
       console.log(
         `${out("warn", "orphan Metro:")} ${orphanMetros.length} leaked bundler(s) for this checkout (pids ${orphanMetros.join(", ")})`
@@ -140,7 +195,43 @@ async function handleDoctor({ options }) {
       if (liveView) renderMobileLiveBlock(deviceView?.devices ?? [], liveView.liveMap, out);
     }
   }
-  return result.status === "pass" ? 0 : 1;
+  return doctorResult.status === "pass" ? 0 : 1;
+}
+function doctorRuntimeCheck(runtime, error, expectLive) {
+  if (error) {
+    return {
+      id: "runtime",
+      status: "fail",
+      required: true,
+      message: "Runtime readiness probe failed.",
+      detail: error
+    };
+  }
+  const ready = runtime?.decision === "ready";
+  return {
+    id: "runtime",
+    status: ready ? "pass" : "fail",
+    required: expectLive,
+    message: ready ? "Runtime is ready." : `Runtime is not ready${runtime?.reasonCode ? ` (${runtime.reasonCode})` : "."}`,
+    detail: runtime?.reasons.join(" | ") || "Runtime readiness probe returned no result."
+  };
+}
+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) ${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}`);
+  return actions;
 }
 function emitExpectLiveVerdict(adapter, target, runtime, verdict) {
   const out = (style, text) => color(style, text, { stream: process.stderr });
@@ -165,7 +256,7 @@ function emitExpectLive(adapter, target, runtime, result, orphanMetros, capture,
     return EXIT.runtime;
   }
   if (json) {
-    console.log(JSON.stringify({ ...result, runtime, orphanMetros, capture, devices, additionalReachableDevices }, 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 });
@@ -208,12 +299,104 @@ async function runDoctorFix(adapter, target, manifestValidation, json) {
     return { fixed, failed };
   }
   if (Number(manifestValidation.summary?.errors ?? 0) > 0) failed.push("manifest");
+  try {
+    const surface = getAdapterSurface(adapter);
+    surface.resolveSlotPorts(target);
+    const runtimeContext = ensureRuntimeContext(target, adapter);
+    if (runtimeContext.created) fixed.push("runtime-context");
+  } catch {
+    failed.push("runtime-context");
+  }
+  if (adapter === "extension") {
+    try {
+      if (ensureExtensionPerpsBuildFlag(target)) fixed.push("extension-perps-build");
+    } catch {
+      failed.push("extension-perps-build");
+    }
+  }
+  if (adapter === "mobile") {
+    try {
+      if (ensureMobilePerpsEnvironment(target).length > 0) fixed.push("mobile-perps-env");
+    } catch {
+      failed.push("mobile-perps-env");
+    }
+  }
   const state = newHealState();
   const ensured = await ensureOverlay(adapter, target, "infra-only", state, json);
   if (!ensured.ok) failed.push("overlay");
   else if (state.mutations.length > 0) fixed.push("overlay");
+  let fixture = fixtureSummary(target, adapter);
+  if (fixture.status !== "ready") {
+    const syncFixture = path.join(runnerDir, "adapters/shared/sync-wallet-fixture.sh");
+    try {
+      execFileSync("bash", [syncFixture, "--target", target], {
+        encoding: "utf8",
+        stdio: json ? ["ignore", "ignore", "ignore"] : "inherit",
+        timeout: 3e4
+      });
+    } catch {
+    }
+    fixture = fixtureSummary(target, adapter);
+    if (fixture.status === "ready") fixed.push("wallet-fixture");
+    else failed.push("wallet-fixture");
+  }
   return { fixed, failed };
 }
+function ensureExtensionPerpsBuildFlag(target) {
+  const configPath = path.join(target, ".metamaskrc");
+  const templatePath = path.join(target, ".metamaskrc.dist");
+  const config = readTextSnapshot(configPath);
+  const template = config.kind === "file" ? null : readTextSnapshot(templatePath);
+  const source = config.kind === "file" ? config : template?.kind === "file" ? template : config.kind === "symlink" ? { kind: "file", text: "", mode: 438 } : null;
+  if (!source) return false;
+  const before = source.text;
+  if (/^\s*PERPS_ENABLED\s*=\s*(['"]?)true\1\s*$/mu.test(before)) return false;
+  const line = "PERPS_ENABLED='true'";
+  const after = /^\s*PERPS_ENABLED\s*=.*$/mu.test(before) ? before.replace(/^\s*PERPS_ENABLED\s*=.*$/mu, line) : `${before.replace(/\s*$/u, "")}
+${line}
+`;
+  const temporary = `${configPath}.${process.pid}.${randomUUID()}.tmp`;
+  let descriptor = null;
+  try {
+    const mode = config.kind === "file" ? config.mode : 438;
+    descriptor = fs.openSync(
+      temporary,
+      fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL,
+      mode
+    );
+    fs.writeFileSync(descriptor, after);
+    if (config.kind === "file") fs.fchmodSync(descriptor, config.mode);
+    fs.closeSync(descriptor);
+    descriptor = null;
+    fs.renameSync(temporary, configPath);
+  } finally {
+    if (descriptor !== null) fs.closeSync(descriptor);
+    fs.rmSync(temporary, { force: true });
+  }
+  return true;
+}
+function readTextSnapshot(file) {
+  let descriptor;
+  try {
+    descriptor = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+  } catch (error) {
+    const code = error.code;
+    if (code === "ENOENT") return { kind: "missing" };
+    if (code === "ELOOP") return { kind: "symlink" };
+    throw error;
+  }
+  try {
+    return {
+      kind: "file",
+      text: fs.readFileSync(descriptor, "utf8"),
+      mode: fs.fstatSync(descriptor).mode & 511
+    };
+  } finally {
+    fs.closeSync(descriptor);
+  }
+}
 export {
+  doctorFixNextActions,
+  ensureExtensionPerpsBuildFlag,
   handleDoctor
 };

package/dist/commands/fixtures.js

@@ -1,38 +1,60 @@
+import { randomUUID } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 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 { applyDeviceTargeting } from "./device-target.js";
-import { ADAPTER_DETECT_NEXT, EXIT, flag, parseFlags, resolveAdapter, scriptOverride, spawnScript, spawnScriptStreaming, str, targetOf, usageOut } from "./shared.js";
-const FIXTURES_BOOLEANS = /* @__PURE__ */ new Set(["json"]);
-const RECOVERABLE_SETUP_WALLET_PATTERNS = [
-  "CDP not reachable",
-  "CDP bridge",
-  "is not installed",
-  "Engine.context.KeyringController not available",
-  "Engine does not exist",
-  "Cannot read property 'transactions'",
-  "bridge-not-ready",
-  "debug-target-missing",
-  "CDP eval failed",
-  "CDP eval-async failed"
-];
-function isRecoverableSetupWalletFailure(output) {
-  return RECOVERABLE_SETUP_WALLET_PATTERNS.some((p) => output.includes(p));
+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 FIXTURE_STREAM_TIMEOUT_MS = 12e4;
+async function handleFixtures(argv, deps) {
+  const { options } = parseFlags(argv, FIXTURES_BOOLEANS);
+  const json = flag(options, "json");
+  const target = targetOf(options);
+  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);
+  }
+  try {
+    return await handleFixturesLocked(argv, deps);
+  } finally {
+    lock.release();
+  }
 }
-function resolveMobileFixturePlatform(options) {
-  const explicit = str(options, "platform") ?? process.env["MOBILE_PLATFORM"];
-  if (explicit === "android" || explicit === "ios") return explicit;
-  if (process.env.ADB_SERIAL || process.env.ANDROID_SERIAL || process.env.ANDROID_DEVICE) return "android";
-  if (process.env.IOS_SIMULATOR) return "ios";
-  return "ios";
+function ensureFixturePublicationParent(target) {
+  const repoRoot = fs.realpathSync(target);
+  const parent = path.dirname(walletFixturePath(repoRoot));
+  const relative = path.relative(repoRoot, parent);
+  if (!relative || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    return `wallet fixture runtime path escapes the checkout: ${parent}`;
+  }
+  let current = repoRoot;
+  for (const part of relative.split(path.sep)) {
+    current = path.join(current, part);
+    try {
+      const entry = fs.lstatSync(current);
+      if (entry.isSymbolicLink()) {
+        return `wallet fixture runtime path must not contain symlinks: ${current}`;
+      }
+      if (!entry.isDirectory()) {
+        return `wallet fixture runtime path component is not a directory: ${current}`;
+      }
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+      fs.mkdirSync(current);
+    }
+  }
+  return fs.realpathSync(parent) === parent ? null : `wallet fixture runtime path escapes the checkout: ${parent}`;
 }
-async function handleFixtures(argv, deps) {
+async function handleFixturesLocked(argv, deps) {
   const { positional, options } = parseFlags(argv, FIXTURES_BOOLEANS);
   const json = flag(options, "json");
   const sub = positional[0];
-  if (sub !== "sync" && sub !== "set" && sub !== "generate" && sub !== "finalize") {
-    return usageOut(json, "fixtures", "fixtures requires a subcommand: mm-harness fixtures <sync|set|generate|finalize>", "mm-harness fixtures sync   or   mm-harness fixtures set   or   mm-harness fixtures generate   or   mm-harness fixtures finalize");
+  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");
   }
   const target = targetOf(options);
   const adapter = resolveAdapter(options, target);
@@ -47,8 +69,18 @@ async function handleFixtures(argv, deps) {
   }
   if (sub === "generate") return fixturesGenerate(adapter, target, options, json);
   if (sub === "finalize") return fixturesFinalize(adapter, target, options, json);
-  if (surface.headless) return usageOut(json, "fixtures", "core is headless; it has no wallet fixture.", surface.hints.launch);
   const canonicalFixture = walletFixturePath(target);
+  if (sub === "init") return fixturesInit(adapter, target, options, json);
+  if (surface.headless && sub === "set") {
+    const fixture = fixtureSummary(target, adapter);
+    if (fixture.status !== "ready") {
+      return usageOut(json, "fixtures", `core wallet fixture is ${String(fixture.status)} at ${canonicalFixture}.`, "mm-harness fixtures init --from <path>   or   mm-harness fixtures init --dev");
+    }
+    const message = `Core reads the canonical signing fixture directly: ${canonicalFixture}`;
+    if (json) console.log(JSON.stringify({ schemaVersion: 1, command: "fixtures", action: "set", adapter, fixture: canonicalFixture, status: "pass", exitCode: EXIT.ok, message }, null, 2));
+    else console.error(message);
+    return EXIT.ok;
+  }
   const retryHint = `${surface.hints.relaunch}   # relaunch, then retry: mm-harness fixtures set`;
   if (sub === "sync") {
     const exitCode = fixturesSync(adapter, target, json);
@@ -67,25 +99,29 @@ async function handleFixtures(argv, deps) {
   process.stderr.write(`\u2192 fixtures set ${adapter} \u2014 connecting bridge + applying wallet fixture (can take ~30s)\u2026
 `);
   let status;
+  let mobileSetupResult;
   if (adapter === "mobile") {
     const setupWalletSh = path.join(runnerDir, "adapters/mobile/bridge-runtime/setup-wallet.sh");
     const previousAppRoot = process.env.APP_ROOT;
     process.env.APP_ROOT = target;
     try {
-      let result = await spawnScriptStreaming(setupWalletSh, ["--fixture", fixturePath], target);
-      if (result.status !== 0 && isRecoverableSetupWalletFailure(result.output) && !process.env["RECIPE_SETUP_WALLET_RETRIED"]) {
-        process.env["RECIPE_SETUP_WALLET_RETRIED"] = "1";
-        if (!json) process.stderr.write("  setup-wallet: recoverable failure \u2014 restarting Metro and retrying\n  Next: wait for relaunch, then wallet setup will retry automatically\n");
-        const { prepareMobile } = await import("../adapters/mobile/prepare.js");
-        const platform = resolveMobileFixturePlatform(options);
-        const relaunchResult = await prepareMobile(target, { platform, json, preflightMode: "auto", clearMetro: true });
-        if (relaunchResult.status === 0) {
-          result = await spawnScriptStreaming(setupWalletSh, ["--fixture", fixturePath], target);
+      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],
+        target,
+        {
+          env: {
+            APP_ROOT: target,
+            WATCHER_PORT: process.env.WATCHER_PORT ?? "8081",
+            METRO_PORT: process.env.METRO_PORT ?? process.env.WATCHER_PORT ?? "8081"
+          },
+          timeoutMs
         }
-      }
-      status = result.status === 0 ? "pass" : "fail";
+      );
+      status = mobileSetupResult.status === 0 ? "pass" : "fail";
     } finally {
-      delete process.env["RECIPE_SETUP_WALLET_RETRIED"];
       if (previousAppRoot === void 0) delete process.env.APP_ROOT;
       else process.env.APP_ROOT = previousAppRoot;
     }
@@ -129,8 +165,8 @@ async function handleFixtures(argv, deps) {
           exitCode: status === "pass" ? EXIT.ok : EXIT.runtime,
           message: teaching,
           error: status === "fail" ? {
-            code: "SETUP_WALLET_FAILED",
-            message: "wallet fixture setup failed",
+            code: mobileSetupResult?.timedOut ? "SETUP_WALLET_TIMEOUT" : "SETUP_WALLET_FAILED",
+            message: mobileSetupResult?.timedOut ? `wallet fixture setup exceeded its ${String(mobileSetupResult.timeoutMs)}ms bound on Metro port ${process.env.WATCHER_PORT ?? "8081"}` : `wallet fixture setup failed on ${process.env.WATCHER_PORT ?? "8081"}`,
             userAction: retryHint
           } : null
         },
@@ -262,7 +298,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}`;
@@ -316,7 +354,104 @@ function fixturesSync(adapter, target, json) {
   const syncArgs = ["--target", target];
   if (process.env.CDP_PORT) syncArgs.push("--cdp-port", process.env.CDP_PORT);
   if (process.env.RECIPE_SLOT_ID) syncArgs.push("--slot-id", process.env.RECIPE_SLOT_ID);
-  spawnScript(syncFixtureSh, syncArgs, target, json);
+  const syncResult = spawnScript(syncFixtureSh, syncArgs, target, json);
+  if (syncResult.status !== 0 || fixtureSummary(target, adapter).status !== "ready") {
+    if (!json) console.error("\u2717 no usable wallet fixture source was found.\n  Next: mm-harness fixtures init --from <path>   or   mm-harness fixtures init --dev");
+    return EXIT.runtime;
+  }
+  return EXIT.ok;
+}
+function fixturesInit(adapter, target, options, json) {
+  const canonical = walletFixturePath(target);
+  const containmentError = ensureFixturePublicationParent(target);
+  if (containmentError) {
+    return usageOut(json, "fixtures", containmentError, "replace the runtime path with checkout-contained directories, then retry");
+  }
+  const source = str(options, "from");
+  const dev = flag(options, "dev");
+  const force = flag(options, "force");
+  if (!source && !dev) {
+    return usageOut(
+      json,
+      "fixtures",
+      "choose a wallet fixture source: 1) --from <path> for an existing team/test fixture; 2) --dev for a disposable public test wallet.",
+      "mm-harness fixtures init --from <path>   or   mm-harness fixtures init --dev"
+    );
+  }
+  if (source && dev) {
+    return usageOut(json, "fixtures", "--from and --dev are mutually exclusive.", "choose exactly one fixture source");
+  }
+  if (!force) {
+    try {
+      fs.lstatSync(canonical);
+      return usageOut(json, "fixtures", `wallet fixture already exists: ${canonical}`, "re-run with --force only when replacement is intentional");
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+  }
+  fs.mkdirSync(path.dirname(canonical), { recursive: true });
+  let fixtureBytes;
+  if (source) {
+    const resolvedSource = path.resolve(source);
+    try {
+      fixtureBytes = fs.readFileSync(resolvedSource);
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        return usageOut(json, "fixtures", `wallet fixture source does not exist: ${resolvedSource}`, "pass an existing JSON file to --from");
+      }
+      throw error;
+    }
+  } else {
+    const fixture = {
+      password: "metamask",
+      accounts: [{
+        type: "mnemonic",
+        value: "test test test test test test test test test test test junk",
+        name: "dev1",
+        count: 1,
+        names: ["dev1"]
+      }],
+      settings: { skipPerpsTutorial: true, autoLockNever: true }
+    };
+    fixtureBytes = `${JSON.stringify(fixture, null, 2)}
+`;
+  }
+  const temporary = `${canonical}.${process.pid}.${randomUUID()}.tmp`;
+  let descriptor = null;
+  try {
+    descriptor = fs.openSync(
+      temporary,
+      fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL,
+      384
+    );
+    fs.writeFileSync(descriptor, fixtureBytes);
+    fs.fchmodSync(descriptor, 384);
+    fs.closeSync(descriptor);
+    descriptor = null;
+    const fixture = fixtureFileSummary(temporary, adapter, canonical);
+    if (fixture.status !== "ready") {
+      return usageOut(json, "fixtures", "wallet fixture is incomplete or invalid for this adapter.", "provide accounts and, for Mobile/Extension, a non-empty password");
+    }
+    if (force) {
+      fs.renameSync(temporary, canonical);
+    } else {
+      try {
+        fs.linkSync(temporary, canonical);
+      } catch (error) {
+        if (error.code === "EEXIST") {
+          return usageOut(json, "fixtures", `wallet fixture already exists: ${canonical}`, "re-run with --force only when replacement is intentional");
+        }
+        throw error;
+      }
+    }
+  } finally {
+    if (descriptor !== null) fs.closeSync(descriptor);
+    fs.rmSync(temporary, { force: true });
+  }
+  const warning = dev ? "Disposable public test wallet created; never use or fund it with real assets." : "Wallet fixture copied.";
+  if (json) console.log(JSON.stringify({ schemaVersion: 1, command: "fixtures", action: "init", adapter, fixture: canonical, status: "pass", warning, exitCode: EXIT.ok }, null, 2));
+  else console.error(`${warning}
+Wallet fixture: ${canonical}`);
   return EXIT.ok;
 }
 export {

package/dist/commands/launch/extension.js

@@ -12,7 +12,7 @@ import { spawnScriptStreaming } from "../shared.js";
 function extensionDepsBlock(target) {
   if (!fs.existsSync(path.join(target, "package.json"))) return null;
   const deps = depsCheck(target);
-  const userAction = "yarn install --immutable   # then re-run: mm-harness launch";
+  const userAction = "mm-harness launch --heal auto";
   if (deps.status === "missing") {
     return { message: "extension dependencies are not installed (no yarn install-state markers).", userAction };
   }
@@ -24,6 +24,10 @@ function extensionDepsBlock(target) {
   }
   return null;
 }
+function installExtensionDeps(target) {
+  const installScript = path.join(runnerDir, "adapters/shared/install-repo-deps.sh");
+  return spawnScriptStreaming(installScript, ["--target", target], target);
+}
 async function launchExtension(target, tier, wantWatch, displayMode = "fullscreen") {
   if (wantWatch) {
     const startWatchSh = path.join(runnerDir, "adapters/extension/start-watch.sh");
@@ -206,5 +210,6 @@ export {
   extensionReattach,
   extensionRebuild,
   extensionRuntimeReusable,
+  installExtensionDeps,
   launchExtension
 };