@deeeed/metamask-harness 0.7.3 → 0.7.4

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.7.4 - 2026-07-07
+
+### Added
+- **`fixtures generate`** — renders the extension wallet `fixture-state.json` from a wallet fixture by fronting `adapters/extension/wallet-fixture-state.cjs generate` (no reimplementation). Extension-only (mobile/core teach); requires `--fixture <wallet-fixture.json>` and `--out <fixture-state.json>`, with a `--json` machine envelope and teaching escapes on missing inputs or a non-extension adapter. This is the public surface farm packs call instead of reaching into the internal leaf, so the Extension pack's `setup/generate-fixture.cjs` resolver can be replaced by a one-line `mm-harness fixtures generate` hook.
+- **`fixtures finalize`** — seeds account labels/selection into the **live** extension over CDP and validates import parity, by fronting `adapters/extension/wallet-fixture-state.cjs seed-cdp` (no reimplementation). Extension-only, post-launch (mobile/core teach); requires `--fixture`, `--state`, `--cdp-port`, `--extension-dir` (optional `--extension-id-file` / `--out`), with a pure `--json` envelope (leaf progress on stderr), the shared `LEAF_MISSING` pre-check, and teaching escapes on missing flags or a non-extension adapter. This is the public surface for the Extension pack's `setup/preflight.sh` account-label finalization, retiring its last `--resolve-script` reach-in into the internal leaf.
+
+### Fixed
+- **`fixtures generate` teaches on a missing leaf instead of leaking a node error.** When the `wallet-fixture-state.cjs` leaf is absent (a corrupt packed install), `generate` now pre-checks the leaf on disk and fails with a one-sentence teaching error plus a `Next:` reinstall command (and a clean `--json` `LEAF_MISSING` envelope), instead of surfacing node's opaque "Cannot find module".
+- **Extension readiness no longer spawns a duplicate home tab on a transient CDP hiccup.** `ensureExtensionReady` treated any `/json/list` failure as an empty tab set, so a list that transiently failed mid-prepare (unlock → home rerender) looked like "no home tab" and opened a second one next to the healthy tab — the following health check then found two targets and failed prepare. `/json/list` now distinguishes "CDP answered: N targets" from "CDP unreachable" (retried a few times), returns `reasonCode: 'cdp-unreachable'` without touching any tab when the state is unknown, confirms a zero count with a second listing before opening, and converges over a few passes so a wrong action is corrected within the call instead of tripping the health check.
+- **`readiness` no longer opens a duplicate home tab when the existing one is attached.** `findPageTarget` required `webSocketDebuggerUrl`, but Chrome omits that field for any target another client is attached to — during prepare the fixture finalizer / smoke recipe / CDP evals attach to the healthy home tab, so it listed without a wsUrl, looked absent, and `readiness` opened a second `home.html` that then tripped the exactly-one-home health gate. Page existence is now decided by URL in any attach state; the websocket only gates UI inspection (a present-but-attached tab is reported `pagePresent: true`, `pageInspected: false` and left alone instead of duplicated). URL matching also tolerates the `home.html#/` router rewrite and query suffixes. New additive report fields: `pagePresent`, `pageInspected`.
+
+### Changed
+- **`install --adapter core` is documented and contract-locked as the public core-runner install surface for farm packs.** It already fronts `adapters/core/inject.sh` and produces the runner delegate at `<harness>/core/runner/bin/mm-harness`; a new CLI-level contract test (`tests/contract/core-install-cli.test.sh`) pins the happy path, `--json` envelope purity, and the adapter-detection teaching escape. Packs call `mm-harness install --adapter core --target <repo>` (inheriting `RECIPE_HARNESS_ROOT` / `FARMSLOT_ROOT`) instead of cloning a runner checkout and invoking the internal leaf directly — no separate top-level command is minted.
+- **`EnsureReadyResult` gains a machine-readable `action` field** (`none` | `opened` | `reopened` | `skipped`) stating the tab decision the call took, so a consumer distinguishes "opened one because a zero was confirmed" from "touched nothing because CDP state was unknown" straight from the JSON envelope.
+
 ## 0.7.3
 
 ### Fixed

package/adapters/extension/readiness.mjs

@@ -271,21 +271,40 @@ async function openExtensionPage(cdpPort, extensionId, pagePath) {
   }
 }
 
+// The page path only, with any '#fragment' or '?query' stripped. The app router
+// rewrites home.html to home.html#/ once loaded, so an exact '/home.html' suffix
+// match must compare against this, not the raw url.
+function pagePathOf(url) {
+  return String(url || '').split('#')[0].split('?')[0];
+}
+
+// Find the extension home page target. Existence is decided by URL alone and is
+// deliberately independent of webSocketDebuggerUrl: Chrome OMITS that field for a
+// target another client is already attached to (the fixture finalizer / smoke
+// recipe / CDP evals attach to the healthy home tab during prepare). Requiring it
+// here made an attached-but-healthy tab look absent, so the caller opened a second
+// home tab and the exactly-one-home health gate then failed. wsUrl only gates
+// whether the chosen page can be inspected (see inspectCdp), never whether it
+// exists. Among matches, prefer the requested page, then a non-popup page, then an
+// inspectable (wsUrl-bearing) one — so a fresh unattached tab is inspected when one
+// is available, while a sole attached tab is still recognized as present.
 function findPageTarget(targets, selectedExtensionId, preferredPagePath = '') {
   const extensionPages = targets.filter((target) => {
     const url = String(target.url || '');
-    return (
-      target.type === 'page' &&
-      url.startsWith(`chrome-extension://${selectedExtensionId}/`) &&
-      typeof target.webSocketDebuggerUrl === 'string'
-    );
+    return target.type === 'page' && url.startsWith(`chrome-extension://${selectedExtensionId}/`);
   });
+  if (extensionPages.length === 0) return undefined;
   const normalizedPreferred = String(preferredPagePath || '').replace(/^\/+/u, '');
-  return (
-    extensionPages.find((target) => normalizedPreferred && String(target.url || '').endsWith(`/${normalizedPreferred}`)) ||
-    extensionPages.find((target) => !String(target.url || '').includes('/popup-init.html')) ||
-    extensionPages[0]
-  );
+  const score = (target) => {
+    const pagePath = pagePathOf(target.url);
+    let value = 0;
+    if (normalizedPreferred && pagePath.endsWith(`/${normalizedPreferred}`)) value += 4;
+    if (!pagePath.endsWith('/popup-init.html')) value += 2;
+    if (typeof target.webSocketDebuggerUrl === 'string') value += 1;
+    return value;
+  };
+  // reduce keeps the FIRST target on a score tie, preserving /json/list order.
+  return extensionPages.reduce((best, current) => (score(current) > score(best) ? current : best), extensionPages[0]);
 }
 
 async function inspectCdp(target, cdpPort, expectedExtensionId, expectedServiceWorker, extensionPagePath) {
@@ -299,14 +318,21 @@ async function inspectCdp(target, cdpPort, expectedExtensionId, expectedServiceW
   let pageTarget = findPageTarget(targets, selectedExtensionId, extensionPagePath);
   let openedPage = false;
   if (!pageTarget) {
+    // Confirmed absence in ANY attach state (findPageTarget ignores wsUrl), so a
+    // home tab that merely has a client attached is never mistaken for missing.
+    // Only a genuinely absent page reaches here; open one and recheck.
     openedPage = await openExtensionPage(cdpPort, selectedExtensionId, extensionPagePath);
     await new Promise((resolve) => setTimeout(resolve, 500));
     targets = await httpJson(`http://127.0.0.1:${cdpPort}/json/list`);
     ({ extensionIds, selectedExtensionId } = chooseExtensionId(targets, expectedExtensionId, expectedServiceWorker));
     pageTarget = findPageTarget(targets, selectedExtensionId, extensionPagePath);
   }
+  const pagePresent = Boolean(pageTarget);
+  let pageInspected = false;
   let ui = null;
-  if (pageTarget) {
+  // Inspect only when the chosen page exposes a websocket. A present-but-attached
+  // tab has none; skip inspection and report it rather than opening a duplicate.
+  if (pageTarget && typeof pageTarget.webSocketDebuggerUrl === 'string') {
     ui = await cdpEvaluate(
       target,
       pageTarget.webSocketDebuggerUrl,
@@ -330,18 +356,19 @@ async function inspectCdp(target, cdpPort, expectedExtensionId, expectedServiceW
         };
       })()`,
     );
-    if (ui && !ui.skipped && ui.hasStartupError) {
+    pageInspected = Boolean(ui) && !ui.skipped;
+    if (pageInspected && ui.hasStartupError) {
       throw Object.assign(new Error('MetaMask extension page loaded startup error UI'), {
         report: { cdp: { browser: version.Browser || 'unknown', selectedExtensionId, ui } },
       });
     }
-    if (ui && !ui.skipped && ui.hasErrorBoundary) {
+    if (pageInspected && ui.hasErrorBoundary) {
       const detail = [ui.errorBoundaryName, ui.errorBoundaryMessage].filter(Boolean).join(': ');
       throw Object.assign(new Error(`MetaMask UI crashed (React error boundary)${detail ? `: ${detail}` : ''}`), {
         report: { cdp: { browser: version.Browser || 'unknown', selectedExtensionId, ui } },
       });
     }
-    if (ui && !ui.skipped && String(ui.url || '').startsWith('chrome-error://')) {
+    if (pageInspected && String(ui.url || '').startsWith('chrome-error://')) {
       throw Object.assign(new Error('MetaMask extension page loaded Chrome error UI'), {
         report: { cdp: { browser: version.Browser || 'unknown', selectedExtensionId, ui } },
       });
@@ -355,6 +382,8 @@ async function inspectCdp(target, cdpPort, expectedExtensionId, expectedServiceW
     targetCount: targets.length,
     openedPage,
     openedPagePath: extensionPagePath,
+    pagePresent,
+    pageInspected,
     ui,
   };
 }

package/dist/adapters/extension/ensure-ready.js

@@ -2,14 +2,18 @@ import path from "node:path";
 import { resolveExtensionId } from "./extension-id.js";
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 async function jsonList(port) {
-  try {
-    const res = await fetch(`http://127.0.0.1:${port}/json/list`, { signal: AbortSignal.timeout(5e3) });
-    if (!res.ok) return [];
-    const value = await res.json();
-    return Array.isArray(value) ? value : [];
-  } catch {
-    return [];
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    try {
+      const res = await fetch(`http://127.0.0.1:${port}/json/list`, { signal: AbortSignal.timeout(5e3) });
+      if (res.ok) {
+        const value = await res.json();
+        if (Array.isArray(value)) return { ok: true, targets: value };
+      }
+    } catch {
+    }
+    if (attempt < 2) await sleep(500);
   }
+  return { ok: false, targets: [] };
 }
 async function closeTab(port, id) {
   try {
@@ -53,6 +57,7 @@ async function ensureExtensionReady(target, options) {
     cdpPort,
     extensionId: null,
     opened: false,
+    action: "none",
     homeTabs: { before: 0, closed: 0, after: 0 },
     ready: false,
     reasonCode: "unknown",
@@ -60,32 +65,67 @@ async function ensureExtensionReady(target, options) {
     ...extra
   });
   const { extensionId } = await resolveExtensionId(resolved, { cdpPort });
-  if (!extensionId) return base({ reasonCode: "no-extension-id" });
-  const homes = homePages(await jsonList(cdpPort), extensionId);
-  const before = homes.length;
+  if (!extensionId) return base({ reasonCode: "no-extension-id", action: "skipped" });
+  const initial = await jsonList(cdpPort);
+  if (!initial.ok) return base({ extensionId, reasonCode: "cdp-unreachable", action: "skipped" });
+  const before = homePages(initial.targets, extensionId).length;
+  const MAX_PASSES = 3;
   let opened = false;
   let closed = 0;
-  if (homes.length > 1) {
-    for (const h of homes) {
-      await closeTab(cdpPort, String(h.id));
-      closed += 1;
+  let action = "none";
+  let targets = initial.targets;
+  for (let pass = 0; pass < MAX_PASSES; pass += 1) {
+    const homes = homePages(targets, extensionId);
+    if (homes.length === 1) break;
+    if (homes.length === 0) {
+      await sleep(750);
+      const recheck = await jsonList(cdpPort);
+      if (!recheck.ok) {
+        return base({ extensionId, opened, action: action === "none" ? "skipped" : action, homeTabs: { before, closed, after: 0 }, reasonCode: "cdp-unreachable" });
+      }
+      if (homePages(recheck.targets, extensionId).length !== 0) {
+        targets = recheck.targets;
+        continue;
+      }
+      action = "opened";
+      opened = await openHome(cdpPort, extensionId) || opened;
+      await sleep(1500);
+    } else {
+      action = "reopened";
+      for (const h of homes) {
+        await closeTab(cdpPort, String(h.id));
+        closed += 1;
+      }
+      await sleep(500);
+      opened = await openHome(cdpPort, extensionId) || opened;
+      await sleep(1500);
     }
-    await sleep(500);
-    opened = await openHome(cdpPort, extensionId);
-    await sleep(1500);
-  } else if (homes.length === 0) {
-    opened = await openHome(cdpPort, extensionId);
-    await sleep(1500);
+    const next = await jsonList(cdpPort);
+    if (!next.ok) {
+      return base({
+        extensionId,
+        opened,
+        action,
+        homeTabs: { before, closed, after: homePages(targets, extensionId).length },
+        reasonCode: "cdp-unreachable"
+      });
+    }
+    targets = next.targets;
   }
   const converged = await jsonList(cdpPort);
-  const homesNow = homePages(converged, extensionId);
+  const convergedTargets = converged.ok ? converged.targets : targets;
+  const homesNow = homePages(convergedTargets, extensionId);
   if (homesNow.length >= 1) {
-    for (const t of converged) {
+    for (const t of convergedTargets) {
       if (t.type === "page" && t.id && isStrayTab(t.url)) await closeTab(cdpPort, String(t.id));
     }
     if (homesNow[0]?.id) await activateTab(cdpPort, String(homesNow[0].id));
   }
-  const after = homePages(await jsonList(cdpPort), extensionId).length;
+  const finalListing = await jsonList(cdpPort);
+  if (!finalListing.ok) {
+    return base({ extensionId, opened, action, homeTabs: { before, closed, after: homesNow.length }, reasonCode: "cdp-unreachable" });
+  }
+  const after = homePages(finalListing.targets, extensionId).length;
   let health = { status: "unknown", findings: [] };
   try {
     const { checkExtensionRuntimeHealth } = await import("./runtime.js");
@@ -98,6 +138,7 @@ async function ensureExtensionReady(target, options) {
   return base({
     extensionId,
     opened,
+    action,
     homeTabs: { before, closed, after },
     ready,
     reasonCode: ready ? "ready" : after !== 1 ? "tab-count" : "unhealthy",

package/dist/cli-commands.js

@@ -13,6 +13,7 @@ const SPEC = {
     { name: "sync", desc: "Refresh harness + canonicalize wallet fixture", flags: ["--json"] },
     { name: "logs", aliases: ["tail"], desc: "Compact build events or full log", flags: ["--full", "-f", "--window", "--events", "--source", "--json"] },
     { name: "debug", aliases: ["devtools", "inspect"], desc: "Open DevTools UI", flags: ["--json", "--no-open"] },
+    { name: "fixtures", desc: "Manage the canonical wallet fixture (sync/set/generate)", args: ["sync", "set", "generate"], flags: ["--fixture", "--out", "--adapter", "--target", "--json"] },
     { name: "actions", desc: "List runnable recipe actions", flags: ["--json"] },
     { name: "doctor", desc: "Check harness/orchestration health", flags: ["--json", "--target", "--adapter", "--runtime-dir", "--expect-live", "--cdp-port"] },
     { name: "run", desc: "Execute a proof recipe", args: ["recipe.json"], flags: ["--list"] },

package/dist/cli.js

@@ -45,8 +45,8 @@ DAILY LOOP \u2014 what a teammate runs many times a day:
                mm-harness logs
   debug      Open the debug console (extension DevTools / mobile RN).
                mm-harness debug
-  fixtures   Sync fixture files + set up the wallet (SRP/password).
-               mm-harness fixtures sync                 # or: mm-harness fixtures set
+  fixtures   Sync files + set the wallet + generate fixture-state + finalize labels over CDP.
+               mm-harness fixtures sync                 # or: set | generate --fixture <f> --out <o> | finalize \u2026
 
 PROVE \u2014 run recipes and inspect capabilities:
   run        Run a recipe and write evidence (summary/trace/artifacts).

package/dist/commands/ensure-ready.js

@@ -16,7 +16,7 @@ async function handleEnsureReady({ options }) {
   );
   const result = await ensureExtensionReady(target, { cdpPort });
   if (optionFlag(options, "json")) console.log(JSON.stringify(result, null, 2));
-  else console.log(`${result.ready ? "READY" : "NOT-READY"} ${result.reasonCode} \u2014 id=${result.extensionId} homeTabs ${result.homeTabs.before}\u2192${result.homeTabs.after} (closed ${result.homeTabs.closed})`);
+  else console.log(`${result.ready ? "READY" : "NOT-READY"} ${result.reasonCode} (${result.action}) \u2014 id=${result.extensionId} homeTabs ${result.homeTabs.before}\u2192${result.homeTabs.after} (closed ${result.homeTabs.closed})`);
   return result.ready ? 0 : 1;
 }
 export {

package/dist/commands/fixtures.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { runnerDir, walletFixturePath } from "../paths.js";
 import { getAdapterSurface } from "../adapters/surface.js";
-import { ADAPTER_DETECT_NEXT, EXIT, flag, parseFlags, resolveAdapter, 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(["json"]);
 const RECOVERABLE_SETUP_WALLET_PATTERNS = [
   "CDP not reachable",
@@ -23,14 +23,16 @@ async function handleFixtures(argv, deps) {
   const { positional, options } = parseFlags(argv, FIXTURES_BOOLEANS);
   const json = flag(options, "json");
   const sub = positional[0];
-  if (sub !== "sync" && sub !== "set") {
-    return usageOut(json, "fixtures", "fixtures requires a subcommand: mm-harness fixtures <sync|set>", "mm-harness fixtures sync   or   mm-harness fixtures set");
+  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");
   }
   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);
   }
+  if (sub === "generate") return fixturesGenerate(adapter, target, options, json);
+  if (sub === "finalize") return fixturesFinalize(adapter, target, options, json);
   const surface = getAdapterSurface(adapter);
   if (surface.headless) return usageOut(json, "fixtures", "core is headless; it has no wallet fixture.", surface.hints.launch);
   const canonicalFixture = walletFixturePath(target);
@@ -128,6 +130,160 @@ async function handleFixtures(argv, deps) {
   }
   return status === "pass" ? EXIT.ok : EXIT.runtime;
 }
+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).`;
+  const userAction = "reinstall mm-harness (npm i -g @deeeed/metamask-harness) \u2014 the fixture-state leaf is missing";
+  if (json) {
+    console.log(
+      JSON.stringify(
+        { schemaVersion: 1, command: "fixtures", action, ...fields, status: "fail", exitCode: EXIT.runtime, error: { code: "LEAF_MISSING", message, userAction } },
+        null,
+        2
+      )
+    );
+  } else {
+    console.error(`\u2717 mm-harness fixtures ${action}: ${message}
+  Next: ${userAction}`);
+  }
+  return EXIT.runtime;
+}
+function fixturesGenerate(adapter, target, options, json) {
+  if (adapter !== "extension") {
+    return usageOut(
+      json,
+      "fixtures",
+      `generate builds the extension wallet fixture-state and is extension-only (detected ${adapter}).`,
+      "run it inside a metamask-extension checkout, or pass --adapter extension"
+    );
+  }
+  const fixture = str(options, "fixture");
+  const out = str(options, "out");
+  if (!fixture || !out) {
+    return usageOut(
+      json,
+      "fixtures",
+      "generate requires --fixture <wallet-fixture.json> and --out <fixture-state.json>.",
+      "mm-harness fixtures generate --fixture <wallet-fixture.json> --out <fixture-state.json>"
+    );
+  }
+  const fixturePath = path.resolve(fixture);
+  const outPath = path.resolve(out);
+  const leaf = path.join(runnerDir, EXT_FIXTURE_LEAF);
+  if (!fs.existsSync(scriptOverride(leaf) ?? leaf)) {
+    return emitLeafMissing(json, "generate", { adapter, fixture: fixturePath, out: outPath }, leaf);
+  }
+  const result = spawnScript(
+    process.execPath,
+    [leaf, "generate", "--target", target, "--fixture", fixturePath, "--out", outPath],
+    target,
+    json
+  );
+  const status = result.status === 0 ? "pass" : "fail";
+  const exitCode = result.status === 0 ? EXIT.ok : EXIT.runtime;
+  const retry = `mm-harness fixtures generate --fixture ${fixturePath} --out ${outPath}`;
+  if (json) {
+    console.log(
+      JSON.stringify(
+        {
+          schemaVersion: 1,
+          command: "fixtures",
+          action: "generate",
+          adapter,
+          fixture: fixturePath,
+          out: outPath,
+          status,
+          exitCode,
+          error: status === "fail" ? {
+            code: "FIXTURE_GENERATE_FAILED",
+            message: "wallet fixture-state generation failed",
+            userAction: `check the wallet fixture at ${fixturePath} and the extension checkout at ${target}, then re-run: ${retry}`
+          } : null
+        },
+        null,
+        2
+      )
+    );
+  } else if (status === "fail") {
+    console.error(`\u2717 mm-harness fixtures generate failed.
+  Next: check the wallet fixture at ${fixturePath} and the extension checkout, then re-run: ${retry}`);
+  } else {
+    console.error(`Wallet fixture-state written: ${outPath}`);
+  }
+  return exitCode;
+}
+async function fixturesFinalize(adapter, target, options, json) {
+  if (adapter !== "extension") {
+    return usageOut(
+      json,
+      "fixtures",
+      `finalize seeds account labels into the live extension over CDP and is extension-only (detected ${adapter}).`,
+      "run it inside a metamask-extension checkout, or pass --adapter extension"
+    );
+  }
+  const fixture = str(options, "fixture");
+  const state = str(options, "state");
+  const cdpPort = str(options, "cdpPort");
+  const extensionDir = str(options, "extensionDir");
+  if (!fixture || !state || !cdpPort || !extensionDir) {
+    return usageOut(
+      json,
+      "fixtures",
+      "finalize requires --fixture <wallet-fixture.json>, --state <fixture-state.json>, --cdp-port <port>, and --extension-dir <dist/chrome>.",
+      "mm-harness fixtures finalize --fixture <wallet-fixture.json> --state <fixture-state.json> --cdp-port <port> --extension-dir <dist/chrome> [--extension-id-file <path>] [--out <report.json>]"
+    );
+  }
+  const fixturePath = path.resolve(fixture);
+  const statePath = path.resolve(state);
+  const extensionDirPath = path.resolve(extensionDir);
+  const extensionIdFile = str(options, "extensionIdFile");
+  const out = str(options, "out");
+  const outPath = out ? path.resolve(out) : void 0;
+  const leaf = path.join(runnerDir, EXT_FIXTURE_LEAF);
+  const echo = { adapter, fixture: fixturePath, state: statePath, cdpPort, extensionDir: extensionDirPath };
+  if (!fs.existsSync(scriptOverride(leaf) ?? leaf)) {
+    return emitLeafMissing(json, "finalize", echo, leaf);
+  }
+  const leafArgs = [leaf, "seed-cdp", "--target", target, "--fixture", fixturePath, "--state", statePath, "--cdp-port", cdpPort, "--extension-dir", extensionDirPath];
+  if (extensionIdFile) leafArgs.push("--extension-id-file", path.resolve(extensionIdFile));
+  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 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}`;
+  if (json) {
+    console.log(
+      JSON.stringify(
+        {
+          schemaVersion: 1,
+          command: "fixtures",
+          action: "finalize",
+          adapter,
+          fixture: fixturePath,
+          state: statePath,
+          cdpPort,
+          extensionDir: extensionDirPath,
+          out: outPath ?? null,
+          status,
+          exitCode,
+          error: status === "fail" ? {
+            code: "FIXTURE_FINALIZE_FAILED",
+            message: "wallet fixture CDP finalization failed",
+            userAction: `confirm the extension is running with CDP on port ${cdpPort} (relaunch if not), then re-run: ${retry}`
+          } : null
+        },
+        null,
+        2
+      )
+    );
+  } else if (status === "fail") {
+    console.error(`\u2717 mm-harness fixtures finalize failed.
+  Next: confirm the extension is running with CDP on port ${cdpPort} (relaunch if not), then re-run: ${retry}`);
+  }
+  return exitCode;
+}
 function fixturesSync(adapter, target, json) {
   const mmHarnessBin = path.join(runnerDir, "bin/mm-harness");
   const installResult = spawnScript(

package/dist/commands/shared.js

@@ -52,6 +52,10 @@ function resolveAdapter(options, target, hint) {
   if (hint) return hint;
   return detectAdapter(target);
 }
+function scriptOverride(scriptPath) {
+  const stem = path.basename(scriptPath).replace(/[^A-Za-z0-9]/gu, "_").toUpperCase();
+  return process.env[`MM_HARNESS_SCRIPT_BIN_${stem}`];
+}
 function spawnScript(script, args, cwd, json, env) {
   const isNodeScript = script === process.execPath && args.length > 0;
   const stem = isNodeScript ? path.basename(args[0]).replace(/[^A-Za-z0-9]/gu, "_").toUpperCase() : path.basename(script).replace(/[^A-Za-z0-9]/gu, "_").toUpperCase();
@@ -170,6 +174,7 @@ export {
   flag,
   parseFlags,
   resolveAdapter,
+  scriptOverride,
   spawnInherit,
   spawnScript,
   spawnScriptStreaming,

package/dist/mm-harness-cli.js

@@ -350,25 +350,37 @@ Example:
   },
   {
     name: "fixtures",
-    summary: "Manage the canonical wallet fixture (wallet DATA only) \u2014 sync files / set the wallet.",
+    summary: "Manage the canonical wallet fixture (wallet DATA only) \u2014 sync / set / generate / finalize.",
     example: "mm-harness fixtures set",
-    helpText: `mm-harness fixtures <sync|set> [flags]
+    helpText: `mm-harness fixtures <sync|set|generate|finalize> [flags]
 
   Manage the ONE canonical wallet fixture per checkout \u2014 wallet DATA only.
-  sync   Refresh the wallet fixture files on the target.
-  set    Apply the canonical fixture (SRP/password/accounts); the password is read
-         FROM the fixture, never typed.
+  sync       Refresh the wallet fixture files on the target.
+  set        Apply the canonical fixture (SRP/password/accounts); the password is
+             read FROM the fixture, never typed.
+  generate   Render the extension fixture-state.json from a wallet fixture, for
+             pre-launch profile prefill (extension-only). Requires --fixture and --out.
+  finalize   Seed account labels/selection into the LIVE extension over CDP and
+             validate parity (extension-only, post-launch). Requires --fixture,
+             --state, --cdp-port, --extension-dir.
   Want different accounts? Edit the fixture file directly:
     <checkout>/temp/recipe/runtime/wallet-fixture.json
 
-  --fixture <path>                   Override the fixture path (agent form; env: RECIPE_WALLET_FIXTURE)
+  --fixture <path>                   Wallet fixture path (generate/finalize input; agent override for set/sync \u2014 env: RECIPE_WALLET_FIXTURE)
+  --out <path>                       generate: output fixture-state.json; finalize: optional validation report
+  --state <path>                     finalize: the pre-launch fixture-state.json to seed
+  --cdp-port <port>                  finalize: CDP port of the running extension
+  --extension-dir <path>             finalize: loaded extension dist (e.g. dist/chrome)
+  --extension-id-file <path>         finalize: optional file to read/write the resolved extension id
   --adapter <mobile|extension>       Target adapter (auto-detected inside a checkout)
   --target <path>                    Checkout path (default: cwd)
   --json                             Machine-readable output
 
 Example:
   mm-harness fixtures sync
-  mm-harness fixtures set`
+  mm-harness fixtures set
+  mm-harness fixtures generate --fixture wallet-fixture.json --out fixture-state.json
+  mm-harness fixtures finalize --fixture wallet-fixture.json --state fixture-state.json --cdp-port 6661 --extension-dir dist/chrome`
   }
 ];
 const RETIRED_INTERNAL = [

package/docs/CLI-SPEC.md

@@ -287,21 +287,30 @@ Recovery is silent in human mode. With `--json`: `"recovered": ["metro.restarted
 
 **One canonical wallet fixture per checkout** — same SSOT model as the farm installer. There is no fixture selection, listing, or bare status verb. **Fixture status is reported by `doctor` automatically** (grounded: `doctor.ts` `fixtureSummary()` already returns `{ status: 'missing'|'ready'|'incomplete'|'invalid', path, accountCount, hasPassword }` and is included in `createDoctorReport()` at line 125). The human edits `wallet-fixture.json` directly; `fixtures set` always teaches where.
 
-**Synopsis:** `mm-harness fixtures <sync|set> [flags]` — subcommand required.
+**Synopsis:** `mm-harness fixtures <sync|set|generate|finalize> [flags]` — subcommand required.
 
 | Subcommand | Behavior |
 |---|---|
 | `sync` | Refresh **wallet fixture files** on the target (wallet DATA only — overlay refresh is `--heal` / `doctor --fix` territory, NOT `fixtures`; they are separate concerns) |
 | `set` | Apply THE canonical fixture (SRP/password/accounts) to the running slot — password read FROM the fixture, never typed; always prints "Want different accounts? Edit: <absolute-path>/wallet-fixture.json" |
+| `generate` | Render the extension `fixture-state.json` from a wallet fixture for pre-launch profile prefill (fronts `adapters/extension/wallet-fixture-state.cjs generate`). **Extension-only** (mobile/core teach). Requires `--fixture <wallet-fixture.json>` and `--out <fixture-state.json>`. This is the public surface for farm packs that need the pre-launch fixture-state file, replacing direct reach-in to the internal leaf. |
+| `finalize` | Seed account labels/selection into the **live** extension over CDP and validate import parity (fronts `adapters/extension/wallet-fixture-state.cjs seed-cdp`). **Extension-only, post-launch** (mobile/core teach). Requires `--fixture`, `--state`, `--cdp-port`, `--extension-dir`. This is the public surface for farm packs that finalize account labels after launch, replacing the last direct reach-in to the internal leaf. |
 
 | Flag | Type | Default | ENV (agent) | Audience | Description |
 |---|---|---|---|---|---|
-| `--fixture <json>` | path | slot's `wallet-fixture.json` | `RECIPE_WALLET_FIXTURE` | **agent only** | Override fixture path; human form = edit the canonical file directly |
+| `--fixture <json>` | path | slot's `wallet-fixture.json` (`set`/`sync`); **required** for `generate`/`finalize` (input wallet fixture) | `RECIPE_WALLET_FIXTURE` | **agent** (`set`/`sync`); both (`generate`/`finalize`) | `set`/`sync`: override fixture path (human form = edit the canonical file directly). `generate`/`finalize`: the input wallet fixture. |
+| `--out <json>` | path | `generate`: **required**; `finalize`: leaf default report path | — | both | `generate`: output `fixture-state.json`. `finalize`: optional validation report path. |
+| `--state <json>` | path | — (**required** for `finalize`) | — | both | `finalize` only: the pre-launch `fixture-state.json` to seed into the live wallet |
+| `--cdp-port <port>` | number | — (**required** for `finalize`) | — | both | `finalize` only: CDP port of the running extension |
+| `--extension-dir <path>` | path | — (**required** for `finalize`) | — | both | `finalize` only: the loaded extension dist (e.g. `dist/chrome`) |
+| `--extension-id-file <path>` | path | — | — | agent | `finalize` only: file to read/write the resolved extension id |
 | `--platform <p>` | mobile\|extension | auto | `PLATFORM` | agent | Force platform |
 
-**Exit:** 0 · 1 apply failed · 2 bad args.
+**Exit:** 0 · 1 apply/generate/finalize failed · 2 bad args (incl. missing required flags, or `generate`/`finalize` on a non-extension adapter).
 **`set` teaching output:** always ends with: `Wallet fixture applied.  Want different accounts? Edit: <absolute-path>/wallet-fixture.json`.
-**Maps-to:** `sync` ← C:`sync`, D:`sync`,`update\|sync-runtime`; `set` ← C:`setup-wallet\|wallet-setup`,`unlock`,`setup:ios/android`(wallet half).
+**`generate` --json:** `{ schemaVersion, command:"fixtures", action:"generate", adapter:"extension", fixture, out, status, exitCode, error }` — leaf output stays on stderr; stdout carries only the envelope.
+**`finalize` --json:** `{ schemaVersion, command:"fixtures", action:"finalize", adapter:"extension", fixture, state, cdpPort, extensionDir, out, status, exitCode, error }` — leaf progress streams to stderr; stdout carries only the envelope. A missing packed leaf yields `error.code:"LEAF_MISSING"` (exit 1), matching `generate`.
+**Maps-to:** `sync` ← C:`sync`, D:`sync`,`update\|sync-runtime`; `set` ← C:`setup-wallet\|wallet-setup`,`unlock`,`setup:ios/android`(wallet half); `generate` ← Extension farm `setup/generate-fixture.cjs` (retires the pack's internal-leaf resolver); `finalize` ← Extension farm `setup/preflight.sh` seed-cdp finalization (retires the pack's last `--resolve-script` reach-in).
 **Extension `set`:** [GAP] no standalone path today — the first-run wallet is seeded by the legacy `mme-recipe up`; the end-state home is `fixtures set` (launch / `launch --verify` never seed).
 
 
@@ -620,6 +629,16 @@ per-checkout runtime overlay. Final home is top-level (no `harness` prefix). `li
 **JSON:** `{ schemaVersion, command:"harness", action, adapter, target, autoDetected, status, exitCode }`.
 **Maps-to:** A:`harness <verb>` (ROUTES-NOW); E: skill (REMOVE); F: orchestration entry points (KEEP-INTERNAL); C/D:`prepare`,`ready\|ensure-ready` (ABSORB-LATER).
 
+**Core-runner install — the public surface for farm packs.** `mm-harness install
+--adapter core --target <repo>` is the pack-facing way to install the headless
+core runner into a slot: it fronts `adapters/core/inject.sh` (the same leaf a farm
+pack used to clone-and-run itself) and produces the runner delegate at
+`<harness>/core/runner/bin/mm-harness`. Because the inject leaf ships inside the
+published package, packs no longer clone a runner checkout — they call this command
+and inherit `RECIPE_HARNESS_ROOT` / `FARMSLOT_ROOT` through the environment. There
+is no separate top-level `install-core` command; `--adapter core` on the existing
+`install` is the surface (grounded: `tests/contract/core-install-cli.test.sh`).
+
 ## Advanced (collapsed → KEEP-INTERNAL)
 
 **All six ADVANCED verbs are removed from the CLI surface and `--help`** — their logic

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.7.3",
+  "version": "0.7.4",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"