@deeeed/metamask-harness 0.14.5 → 0.15.0

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 { createDoctorReport, fixtureSummary, renderRuntimeContext, requiredDoctorCheckSummary } from "../doctor.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";
 import { loadActionManifest, validateManifest } from "../manifest.js";
 import { ensureOverlay, newHealState, recipeRunning } from "../heal-bounds.js";
 import { applyDeviceTargeting } from "./device-target.js";
@@ -15,7 +18,10 @@ import {
   renderMobileDeviceList,
   renderMobileLiveBlock
 } from "./mobile-device-view.js";
-import { ADAPTER_DETECT_NEXT, EXIT, usageOut } from "./shared.js";
+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 {
   actionManifestPathOption,
   applyRuntimeDirOption,
@@ -40,7 +46,8 @@ async function handleDoctor({ options }) {
   applyRuntimeDirOption(options);
   const target = targetPath(options);
   const json = optionFlag(options, "json");
-  const expectLive = optionFlag(options, "expectLive");
+  const printReady = optionFlag(options, "printReady");
+  const expectLive = optionFlag(options, "expectLive") || printReady;
   const allDevices = optionFlag(options, "allDevices");
   const platformOption = optionString(options, "platform");
   const explicitAdapter = optionString(options, "adapter") ?? (platformOption === "ios" || platformOption === "android" ? "mobile" : platformOption);
@@ -49,18 +56,57 @@ 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,
+      "doctor",
+      "--print-ready owns stdout for Farmslot health_check; drop --json (use --expect-live --json for the doctor envelope)",
+      "mm-harness doctor --print-ready --adapter <adapter> --target <path>"
+    );
+  }
   const actionManifestPath = actionManifestPathOption(options, adapter);
   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);
+    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);
@@ -72,20 +118,43 @@ 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;
   const liveView = deviceView ? await mobileDeviceLiveView(target, deviceView) : null;
   const devices = liveView?.devicesWithLive ?? deviceView?.devices ?? [];
   const additionalReachableDevices = liveView?.additionalReachableDevices ?? [];
-  if (expectLive) return emitExpectLive(adapter, target, runtime, result, orphanMetros, capture, devices, additionalReachableDevices, json);
-  if (json) console.log(JSON.stringify({ ...result, runtime, orphanMetros, capture, devices, additionalReachableDevices }, null, 2));
+  if (expectLive) {
+    return emitExpectLive(
+      adapter,
+      target,
+      runtime,
+      doctorResult,
+      orphanMetros,
+      capture,
+      devices,
+      additionalReachableDevices,
+      json,
+      printReady
+    );
+  }
+  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";
@@ -96,8 +165,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(", ")})`
@@ -117,12 +194,62 @@ 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) {
+  const actions = [];
+  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`);
+  }
+  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) {
+  const out = (style, text) => color(style, text, { stream: process.stderr });
+  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}`);
 }
-function emitExpectLive(adapter, target, runtime, result, orphanMetros, capture, devices, additionalReachableDevices, json) {
+function emitExpectLive(adapter, target, runtime, result, orphanMetros, capture, devices, additionalReachableDevices, json, printReady) {
   const live = runtime?.decision === "ready";
+  if (printReady) {
+    if (live) {
+      const indicator = farmslotReadyIndicator(adapter, devices);
+      if (indicator) {
+        console.log(indicator);
+        return EXIT.ok;
+      }
+      emitExpectLiveVerdict(adapter, target, runtime, "not-ready");
+      return EXIT.runtime;
+    }
+    emitExpectLiveVerdict(adapter, target, runtime, "not-live");
+    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 });
@@ -130,10 +257,7 @@ function emitExpectLive(adapter, target, runtime, result, orphanMetros, capture,
     console.log(`${out("ok", "live")} ${out("bold", adapter)} runtime ready`);
     return EXIT.ok;
   }
-  const detail = runtime ? `${runtime.decision}${runtime.reasonCode ? ` (${runtime.reasonCode})` : ""}` : "runtime probe unavailable";
-  console.error(`${out("err", "not-live")} ${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}`);
+  emitExpectLiveVerdict(adapter, target, runtime, "not-live");
   return EXIT.runtime;
 }
 function captureHelperHealth() {
@@ -168,12 +292,103 @@ 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 {
+  ensureExtensionPerpsBuildFlag,
   handleDoctor
 };

package/dist/commands/farmslot-ready.js

@@ -0,0 +1,25 @@
+function selectedDevice(devices) {
+  return devices.find((d) => d.selected) ?? devices[0];
+}
+function mobileWalletReady(device) {
+  if (device.liveState === "no-bridge" || device.liveState === "bridge-absent") return false;
+  return device.walletState === "unlocked";
+}
+function farmslotReadyIndicator(adapter, devices) {
+  switch (adapter) {
+    case "extension":
+      return "OK";
+    case "core":
+      return "ready";
+    case "mobile": {
+      const device = selectedDevice(devices);
+      if (!device) return "";
+      return mobileWalletReady(device) ? "OK" : "";
+    }
+    default:
+      return "";
+  }
+}
+export {
+  farmslotReadyIndicator
+};

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 {