@deeeed/metamask-harness 0.17.4 → 0.18.0

package/dist/commands/completion-candidates.js

@@ -1,4 +1,4 @@
-import { loadActionManifest } from "../manifest.js";
+import { resolveActionManifest } from "../manifest.js";
 import {
   invalidateCompletionCache,
   readFreshCandidates,
@@ -13,13 +13,13 @@ import {
   resolveAdapter,
   targetPath
 } from "./parse-args.js";
-import { resolveMetaMaskLibrarySources } from "./run-engine.js";
+import { listRunnableRecipes, resolveMetaMaskLibrarySources } from "./run-engine.js";
 async function handleCompletionCandidates(argv) {
   const kind = argv[0];
   const { options } = parseArgs(argv.slice(1), "completion-candidates");
   const json = optionFlag(options, "json");
-  if (kind !== "actions" && kind !== "flows") {
-    console.error("completion-candidates requires <actions|flows>.");
+  if (kind !== "actions" && kind !== "flows" && kind !== "recipes") {
+    console.error("completion-candidates requires <actions|flows|recipes>.");
     return EXIT.usage;
   }
   const target = targetPath(options);
@@ -27,17 +27,15 @@ async function handleCompletionCandidates(argv) {
   let candidates;
   if (kind === "actions") {
     adapter = resolveAdapter(options).adapter;
-    candidates = readFreshCandidates(target, "actions");
-    if (!candidates) {
-      const manifest = loadActionManifest(adapter, optionString(options, "actionManifest"));
-      const { getRecipeActionManifestActionNames } = await importRecipeProtocol();
-      candidates = getRecipeActionManifestActionNames(manifest);
-      writeCompletionCandidates(target, "actions", candidates);
-    }
-  } else {
+    const sources = await resolveMetaMaskLibrarySources(optionString(options, "library"));
+    const { manifest } = await resolveActionManifest(adapter, optionString(options, "actionManifest"), sources);
+    const { getRecipeActionManifestActionNames } = await importRecipeProtocol();
+    candidates = getRecipeActionManifestActionNames(manifest);
+    writeCompletionCandidates(target, "actions", candidates);
+  } else if (kind === "flows") {
     candidates = readFreshCandidates(target, "flows");
     if (!candidates) {
-      const sources = await resolveMetaMaskLibrarySources(void 0).catch(() => void 0);
+      const sources = await resolveMetaMaskLibrarySources(optionString(options, "library")).catch(() => void 0);
       if (!sources) {
         candidates = [];
       } else {
@@ -47,6 +45,15 @@ async function handleCompletionCandidates(argv) {
         writeCompletionCandidates(target, "flows", candidates);
       }
     }
+  } else {
+    adapter = resolveAdapter(options).adapter;
+    const cacheKey = `recipes:${adapter}`;
+    candidates = readFreshCandidates(target, cacheKey);
+    if (!candidates) {
+      const sources = await resolveMetaMaskLibrarySources(optionString(options, "library")).catch(() => void 0);
+      candidates = sources ? listRunnableRecipes(adapter, sources).map((recipe) => recipe.name) : [];
+      writeCompletionCandidates(target, cacheKey, candidates);
+    }
   }
   if (json) console.log(JSON.stringify({ schemaVersion: 1, kind, adapter, candidates }, null, 2));
   else for (const candidate of candidates) console.log(candidate);

package/dist/commands/debug.js

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

package/dist/commands/doctor.js

@@ -7,6 +7,7 @@ import { createDoctorReport, fixtureSummary, renderRuntimeContext, requiredDocto
 import { detectAdapter, resolveRuntimeContextPath } from "../harness.js";
 import { assertAdapter, runnerDir } from "../paths.js";
 import { getAdapterSurface } from "../adapters/surface.js";
+import { extensionProductConfigBlock } from "../adapters/extension/product-config.js";
 import { ensureMobilePerpsEnvironment, mobilePerpsEnvironment } from "../adapters/mobile/perps-env.js";
 import { loadActionManifest, validateManifest } from "../manifest.js";
 import { ensureOverlay, newHealState, recipeRunning } from "../heal-bounds.js";
@@ -96,7 +97,19 @@ async function handleDoctor({ options }) {
       lock.release();
     }
     const result2 = createDoctorReport(adapter, target, manifestValidation, actionManifestPath);
+    let runtime2;
+    let runtimeProbeError2;
+    try {
+      runtime2 = await surface.runtimeStatus(target);
+    } catch (error2) {
+      runtimeProbeError2 = error2 instanceof Error ? error2.message : String(error2);
+    }
+    const ready = runtime2?.decision === "ready";
+    if (adapter === "extension" && runtime2?.reasonCode === "product-config-required") {
+      failed.push("extension-product-config");
+    }
     const nextActions = doctorFixNextActions(failed, result2.fixture, adapter, target);
+    if (failed.length === 0 && !ready && runtime2?.nextAction) nextActions.push(runtime2.nextAction);
     const status = result2.status === "pass" && failed.length === 0 ? "pass" : "fail";
     const retryDoctor = `mm-harness doctor --fix --adapter ${adapter} --target ${shellQuote(target)} --json`;
     const fixUserAction = failed.includes("wallet-fixture") ? `choose one wallet fixture source from nextActions, run it, then retry: ${retryDoctor}` : nextActions[0] ?? retryDoctor;
@@ -105,9 +118,15 @@ async function handleDoctor({ options }) {
       message: "doctor --fix could not make every required check pass",
       userAction: fixUserAction
     } : void 0;
-    if (json) console.log(JSON.stringify({ ...result2, status, fixed, failed, nextActions, ...error ? { error } : {} }, null, 2));
+    if (json) console.log(JSON.stringify({ ...result2, status, fixed, failed, ready, runtime: runtime2, ...runtimeProbeError2 ? { runtimeProbeError: runtimeProbeError2 } : {}, nextActions, ...error ? { error } : {} }, null, 2));
     else {
-      console.log(`${status} ${adapter} ${result2.compatibilityMode} manifest=${actionManifestPath} fixed=[${fixed.join(",")}] failed=[${failed.join(",")}]`);
+      console.log(`${status} ${adapter} ${result2.compatibilityMode} ready=${ready} manifest=${actionManifestPath} fixed=[${fixed.join(",")}] failed=[${failed.join(",")}]`);
+      if (runtime2) {
+        console.log(`runtime: decision=${runtime2.decision}${runtime2.reasonCode ? ` (${runtime2.reasonCode})` : ""}`);
+        for (const reason of runtime2.reasons) console.log(`  ${reason}`);
+      } else if (runtimeProbeError2) {
+        console.log(`runtime probe failed: ${runtimeProbeError2}`);
+      }
       for (const action of nextActions) console.error(`  Next: ${action}`);
     }
     return status === "pass" ? 0 : 1;
@@ -161,11 +180,15 @@ async function handleDoctor({ options }) {
   }
   const doctorUserAction = `mm-harness doctor --fix --adapter ${adapter} --target ${shellQuote(target)} --json`;
   const doctorError = doctorResult.status === "fail" ? { code: "DOCTOR_CHECKS_FAILED", message: "one or more required doctor checks failed", userAction: doctorUserAction } : void 0;
-  if (json) console.log(JSON.stringify({ ...doctorResult, ready: runtime?.decision === "ready", runtime, orphanMetros, capture, devices, additionalReachableDevices, ...doctorError ? { error: doctorError } : {} }, null, 2));
+  const next = doctorError?.userAction ?? (runtime?.decision === "ready" ? void 0 : runtime?.nextAction);
+  if (json) console.log(JSON.stringify({ ...doctorResult, ready: runtime?.decision === "ready", runtime, orphanMetros, capture, devices, additionalReachableDevices, ...next ? { next } : {}, ...doctorError ? { error: doctorError } : {} }, null, 2));
   else {
     const out = (style, text) => color(style, text, { stream: process.stdout });
     const stateStyle = (value, good) => value === good ? "ok" : "warn";
     console.log(`${out(doctorResult.status === "pass" ? "ok" : "err", doctorResult.status)} ${out("bold", adapter)} ${doctorResult.compatibilityMode} ${out("dim", `manifest=${actionManifestPath}`)}`);
+    console.log(
+      `${out("label", "harness:")} ${doctorResult.runner.packageName}@${doctorResult.runner.version} ${out("accent", doctorResult.runner.installKind)} ${out("dim", `executable=${doctorResult.runner.executablePath}`)}`
+    );
     if (runtime) {
       const provisionedDepsPending = runtime.reasonCode === "app-installed-deps-pending";
       const decisionStyle = provisionedDepsPending ? "info" : runtime.decision === "ready" ? "ok" : runtime.decision === "blocked" ? "err" : "warn";
@@ -198,7 +221,7 @@ async function handleDoctor({ options }) {
       if (additionalReachableDevices.length > 0) renderAdditionalReachableDevices(additionalReachableDevices, out);
       if (liveView) renderMobileLiveBlock(deviceView?.devices ?? [], liveView.liveMap, out);
     }
-    if (doctorError) console.log(`  ${out("dim", `Next: ${doctorUserAction}`)}`);
+    if (next) console.log(`  ${out("dim", `Next: ${next}`)}`);
   }
   return doctorResult.status === "pass" ? 0 : 1;
 }
@@ -236,6 +259,10 @@ function doctorFixNextActions(failed, fixture, adapter, target) {
     );
   }
   if (failed.includes("overlay")) actions.push(`${executable} install ${scope}`);
+  if (adapter === "extension" && failed.includes("extension-product-config")) {
+    const block = extensionProductConfigBlock(target);
+    if (block) actions.push(block.userAction);
+  }
   return actions;
 }
 function emitExpectLiveVerdict(adapter, target, runtime, verdict) {
@@ -243,7 +270,7 @@ function emitExpectLiveVerdict(adapter, target, runtime, verdict) {
   const detail = runtime ? `${runtime.decision}${runtime.reasonCode ? ` (${runtime.reasonCode})` : ""}` : "runtime probe unavailable";
   console.error(`${out("err", verdict)} ${out("bold", adapter)} ${detail} ${out("dim", target)}`);
   for (const reason of runtime?.reasons ?? []) console.error(`  ${out("dim", reason)}`);
-  console.error(`  Next: ${getAdapterSurface(adapter).hints.relaunch}`);
+  console.error(`  Next: ${runtime?.nextAction ?? getAdapterSurface(adapter).hints.runtimeProbeRecovery(target)}`);
 }
 function emitExpectLive(adapter, target, runtime, result, orphanMetros, capture, devices, additionalReachableDevices, json, printReady) {
   const live = runtime?.decision === "ready";
@@ -261,7 +288,7 @@ function emitExpectLive(adapter, target, runtime, result, orphanMetros, capture,
     return EXIT.runtime;
   }
   if (json) {
-    const userAction = adapter === "extension" ? `mm-harness launch --adapter extension --target ${shellQuote(target)}` : adapter === "core" ? `mm-harness verify --adapter core --target ${shellQuote(target)}` : `mm-harness status --target ${shellQuote(target)} --json`;
+    const userAction = runtime?.nextAction ?? getAdapterSurface(adapter).hints.runtimeProbeRecovery(target);
     const error = live ? void 0 : { code: "RUNTIME_NOT_LIVE", message: `${adapter} runtime is not live`, userAction };
     console.log(JSON.stringify({ ...result, ready: live, runtime, orphanMetros, capture, devices, additionalReachableDevices, ...error ? { error } : {} }, null, 2));
     return live ? EXIT.ok : EXIT.runtime;

package/dist/commands/fixtures.js

@@ -5,21 +5,22 @@ import { runnerDir, walletFixturePath } from "../paths.js";
 import { getAdapterSurface } from "../adapters/surface.js";
 import { fixtureFileSummary, fixtureSummary } from "../doctor.js";
 import { acquireCheckoutLock } from "../checkout-lock.js";
+import { colorHumanMessage } from "../cli-color.js";
 import { applyDeviceTargeting } from "./device-target.js";
 import { ADAPTER_DETECT_NEXT, 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) {
+async function handleFixtures(argv) {
   const { options } = parseFlags(argv, FIXTURES_BOOLEANS);
   const json = flag(options, "json");
   const target = targetOf(options);
-  if (!fs.existsSync(target)) return handleFixturesLocked(argv, deps);
+  if (!fs.existsSync(target)) return handleFixturesLocked(argv);
   const lock = acquireCheckoutLock(target, "fixtures");
   if ("message" in lock) {
     return checkoutBusyOut(json, "fixtures", lock.message, lock.path);
   }
   try {
-    return await handleFixturesLocked(argv, deps);
+    return await handleFixturesLocked(argv);
   } finally {
     lock.release();
   }
@@ -49,7 +50,7 @@ function ensureFixturePublicationParent(target) {
   }
   return fs.realpathSync(parent) === parent ? null : `wallet fixture runtime path escapes the checkout: ${parent}`;
 }
-async function handleFixturesLocked(argv, deps) {
+async function handleFixturesLocked(argv) {
   const { positional, options } = parseFlags(argv, FIXTURES_BOOLEANS);
   const json = flag(options, "json");
   const sub = positional[0];
@@ -112,6 +113,9 @@ async function handleFixturesLocked(argv, deps) {
       "mm-harness fixtures init --dev && mm-harness fixtures set"
     );
   }
+  if (adapter === "extension") {
+    return applyExtensionFixture(target, fixturePath, canonicalFixture, json);
+  }
   process.stderr.write(`\u2192 fixtures set ${adapter} \u2014 connecting bridge + applying wallet fixture (can take ~30s)\u2026
 `);
   let status;
@@ -144,19 +148,6 @@ async function handleFixturesLocked(argv, deps) {
     if (!json && status === "fail") {
       console.error(`  Next: ${retryHint}`);
     }
-  } else {
-    const previousFixtureEnv = process.env.RECIPE_WALLET_FIXTURE;
-    process.env.RECIPE_WALLET_FIXTURE = fixturePath;
-    try {
-      const result = await deps.runOneNode("extension", "metamask.wallet.setup", {}, target, str(options, "actionManifest"));
-      status = result.status;
-    } finally {
-      if (previousFixtureEnv === void 0) delete process.env.RECIPE_WALLET_FIXTURE;
-      else process.env.RECIPE_WALLET_FIXTURE = previousFixtureEnv;
-    }
-    if (!json && status === "fail") {
-      console.error(`  Next: ${retryHint}`);
-    }
   }
   const teaching = status === "pass" ? `Wallet fixture applied.  Want different accounts? Edit: ${canonicalFixture}` : "Wallet fixture was not applied.";
   if (json) {
@@ -187,6 +178,63 @@ async function handleFixturesLocked(argv, deps) {
   }
   return status === "pass" ? EXIT.ok : EXIT.runtime;
 }
+async function applyExtensionFixture(target, fixturePath, canonicalFixture, json) {
+  const distManifest = path.join(target, "dist/chrome/manifest.json");
+  const userAction = `mm-harness launch --build --verify --target ${JSON.stringify(target)}`;
+  if (!fs.existsSync(distManifest)) {
+    const message2 = `Extension fixture needs an existing dist/chrome build; no manifest was found at ${distManifest}.`;
+    if (json) {
+      console.log(JSON.stringify({
+        schemaVersion: 1,
+        command: "fixtures",
+        action: "set",
+        adapter: "extension",
+        fixture: fixturePath,
+        canonicalFixture,
+        status: "fail",
+        exitCode: EXIT.runtime,
+        error: { code: "EXTENSION_FIXTURE_BUILD_REQUIRED", message: message2, userAction }
+      }, null, 2));
+    } else {
+      console.error(`\u2717 mm-harness fixtures set: ${message2}
+  Next: ${userAction}`);
+    }
+    return EXIT.runtime;
+  }
+  process.stderr.write(`${colorHumanMessage("\u2192 fixtures set extension \u2014 resetting and seeding the slot-owned profile from the existing build\u2026")}
+`);
+  const liveScript = path.join(runnerDir, "adapters/extension/live.sh");
+  const args = ["--target", target, "--launch-existing-dist"];
+  if (process.env.CDP_PORT) args.push("--cdp-port", process.env.CDP_PORT);
+  const result = await spawnScriptStreaming(liveScript, args, target, {
+    env: { RECIPE_WALLET_FIXTURE: fixturePath },
+    timeoutMs: FIXTURE_STREAM_TIMEOUT_MS
+  });
+  const status = result.status === 0 ? "pass" : "fail";
+  const exitCode = status === "pass" ? EXIT.ok : EXIT.runtime;
+  const message = status === "pass" ? `Wallet fixture applied and validated. Want different accounts? Edit: ${canonicalFixture}` : "Extension wallet fixture could not be applied and validated.";
+  if (json) {
+    console.log(JSON.stringify({
+      schemaVersion: 1,
+      command: "fixtures",
+      action: "set",
+      adapter: "extension",
+      fixture: fixturePath,
+      canonicalFixture,
+      status,
+      exitCode,
+      profileReset: status === "pass",
+      message,
+      error: status === "fail" ? { code: "EXTENSION_FIXTURE_APPLY_FAILED", message, userAction } : null
+    }, null, 2));
+  } else if (status === "pass") {
+    console.error(message);
+  } else {
+    console.error(`\u2717 mm-harness fixtures set: ${message}
+  Next: ${userAction}`);
+  }
+  return exitCode;
+}
 const EXT_FIXTURE_LEAF = "adapters/extension/wallet-fixture-state.cjs";
 function emitLeafMissing(json, action, fields, leaf) {
   const message = `leaf could not start: ${path.basename(leaf)} (ENOENT).`;

package/dist/commands/flows.js

@@ -2,18 +2,18 @@ import path from "node:path";
 import { color } from "../cli-color.js";
 import { importRecipeHarnessCli } from "../paths.js";
 import { EXIT } from "./shared.js";
-import { usageError } from "./parse-args.js";
+import { parseArgs, usageError } from "./parse-args.js";
 import { resolveMetaMaskLibrarySources } from "./run-engine.js";
-const FLOWS_SUBCOMMANDS = ["list", "promote"];
-function stripTargetFlag(argv) {
+const FLOWS_SUBCOMMANDS = ["list", "describe", "promote"];
+function stripFrontOnlyFlags(argv) {
   const out = [];
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
-    if (arg === "--target") {
+    if (arg === "--target" || arg === "--library") {
       i += 1;
       continue;
     }
-    if (arg.startsWith("--target=")) continue;
+    if (arg.startsWith("--target=") || arg.startsWith("--library=")) continue;
     out.push(arg);
   }
   return out;
@@ -30,14 +30,37 @@ function restoreEnv(key, value) {
   if (value === void 0) delete process.env[key];
   else process.env[key] = value;
 }
+function libraryEntries(argv) {
+  const entries = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === "--library") {
+      const value = argv[index + 1];
+      if (value !== void 0) entries.push(value);
+      index += 1;
+    } else if (argument.startsWith("--library=")) {
+      entries.push(argument.slice("--library=".length));
+    }
+  }
+  return entries;
+}
 async function handleFlows(argv) {
-  const sources = await resolveMetaMaskLibrarySources(void 0);
+  const { positional } = parseArgs(argv);
+  const subcommand = positional[0];
+  if (subcommand === "describe" && !positional[1]) {
+    throw usageError("flows describe requires <ref>. Next: mm-harness flows list");
+  }
+  if (subcommand !== "describe" && positional[1]) {
+    throw usageError(`flows ${subcommand ?? "list"} does not accept positional ${positional[1]}.`);
+  }
+  const configuredLibraries = libraryEntries(argv);
+  const sources = await resolveMetaMaskLibrarySources(configuredLibraries);
   if (!sources) {
     throw usageError(
       "flows requires @farmslot/recipe-harness >= 0.3.3 (recipe-library support; flows resolve personal > team > canonical). Next: update the dependency and run yarn install."
     );
   }
-  const forwarded = stripTargetFlag(argv);
+  const forwarded = stripFrontOnlyFlags(argv);
   const jsonMode = forwarded.includes("--json");
   if (!jsonMode) {
     console.error(color("label", "flows resolve by precedence (highest wins; local shadows canonical):"));
@@ -46,16 +69,22 @@ async function handleFlows(argv) {
       console.error(`  ${index + 1}. ${color("cmd", name)} ${color("dim", `[${flowSourceTier(source, index, sources.length)}]`)}`);
     });
   }
-  const withSubcommand = FLOWS_SUBCOMMANDS.includes(forwarded[0]) ? forwarded : ["list", ...forwarded];
+  const resolvedSubcommand = subcommand && FLOWS_SUBCOMMANDS.includes(subcommand) ? subcommand : "list";
+  const forwardedSubcommandIndex = forwarded.indexOf(resolvedSubcommand);
+  const delegatedArgs = forwardedSubcommandIndex === -1 ? forwarded : forwarded.filter((_, index) => index !== forwardedSubcommandIndex);
+  const withSubcommand = [resolvedSubcommand, ...delegatedArgs];
   const { runRecipeHarnessCli } = await importRecipeHarnessCli();
   const previousLibraryPath = process.env.RECIPE_LIBRARY_PATH;
+  const previousExitCode = process.exitCode;
   process.env.RECIPE_LIBRARY_PATH = serializeLibrarySources(sources);
+  process.exitCode = void 0;
   try {
-    await runRecipeHarnessCli(["flows", ...withSubcommand]);
+    await runRecipeHarnessCli(["flows", ...withSubcommand], { commandName: "mm-harness" });
+    return typeof process.exitCode === "number" ? process.exitCode : EXIT.ok;
   } finally {
     restoreEnv("RECIPE_LIBRARY_PATH", previousLibraryPath);
+    process.exitCode = previousExitCode;
   }
-  return EXIT.ok;
 }
 export {
   handleFlows

package/dist/commands/launch/extension.js

@@ -3,12 +3,15 @@ import http from "node:http";
 import fs from "node:fs";
 import path from "node:path";
 import { depsCheck } from "@farmslot/recipe-harness/runtime/deps-readiness";
+import { colorHumanMessage } from "../../cli-color.js";
 import { recipeHarnessPath, recipeRuntimeDir, runnerDir } from "../../paths.js";
 import { extensionIdFromKey } from "../../adapters/extension/extension-id.js";
+import { extensionProductConfigBlock } from "../../adapters/extension/product-config.js";
 import { isExtensionDistStale } from "../../adapters/extension/runtime-decision.js";
 import { checkExtensionRuntimeHealth } from "../../adapters/extension/runtime.js";
+import { ensureExtensionHarnessFresh } from "../../adapters/extension/harness-freshness.js";
 import { stopExtensionWatcher } from "../../adapters/slot-ports.js";
-import { spawnScriptStreaming } from "../shared.js";
+import { EXIT, spawnScriptStreaming } from "../shared.js";
 function extensionDepsBlock(target) {
   if (!fs.existsSync(path.join(target, "package.json"))) return null;
   const deps = depsCheck(target);
@@ -29,17 +32,32 @@ function installExtensionDeps(target) {
   return spawnScriptStreaming(installScript, ["--target", target], target);
 }
 async function launchExtension(target, tier, wantWatch, displayMode = "fullscreen") {
+  if (process.env.CHROME_USER_DATA_DIR) {
+    process.env.CHROME_USER_DATA_DIR = path.resolve(process.env.CHROME_USER_DATA_DIR);
+  }
+  const reusable = !wantWatch && tier !== "build" && await extensionRuntimeReusable(target);
+  if (!reusable) {
+    const block = extensionProductConfigBlock(target);
+    if (block) {
+      return {
+        status: EXIT.infra,
+        output: `EXTENSION_PRODUCT_CONFIG_REQUIRED: ${block.message}
+Next: ${block.userAction}`
+      };
+    }
+  }
+  await ensureExtensionHarnessFresh(target);
   if (wantWatch) {
     const startWatchSh = path.join(runnerDir, "adapters/extension/start-watch.sh");
     const watchArgs = ["--target", target];
     if (process.env.WATCHER_PORT) watchArgs.push("--watcher-port", process.env.WATCHER_PORT);
-    console.error(`\u2192 extension watch \u2014 webpack :${process.env.WATCHER_PORT ?? "default"} (output streams below)`);
+    console.error(colorHumanMessage(`\u2192 extension watch \u2014 webpack :${process.env.WATCHER_PORT ?? "default"} (output streams below)`));
     return spawnScriptStreaming(startWatchSh, watchArgs, target);
   }
   if (tier === "build") {
     return extensionRebuild(target);
   }
-  if (await extensionRuntimeReusable(target)) {
+  if (reusable) {
     return extensionReattach(target, displayMode);
   }
   return extensionRebuild(target);
@@ -47,12 +65,16 @@ async function launchExtension(target, tier, wantWatch, displayMode = "fullscree
 async function extensionRuntimeReusable(target) {
   const cdpPort = process.env.CDP_PORT;
   if (!cdpPort) return false;
-  if (!cdpOwnedByExpectedRuntime(cdpPort, target)) return false;
-  if (!await cdpVersionReachable(cdpPort)) return false;
-  if (!await cdpHasExpectedExtensionTarget(cdpPort, target)) return false;
-  if (!await cdpRuntimeHealthy(cdpPort, target)) return false;
   if (isExtensionDistStale(target)) return false;
-  return true;
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    const reachable = await cdpVersionReachable(cdpPort);
+    const owned = reachable && cdpOwnedByExpectedRuntime(cdpPort, target);
+    const targetPresent = owned && await cdpHasExpectedExtensionTarget(cdpPort, target);
+    const healthy = targetPresent && await cdpRuntimeHealthy(cdpPort, target);
+    if (healthy) return true;
+    if (attempt < 2) await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+  return false;
 }
 function expectedChromeProfile(target) {
   const profileName = process.env.RECIPE_CHROME_PROFILE_NAME || "chrome-profile";
@@ -168,12 +190,15 @@ function cdpHasExpectedExtensionTarget(port, target) {
   });
 }
 async function cdpRuntimeHealthy(port, target) {
-  try {
-    const report = await checkExtensionRuntimeHealth(target, Number(port), { pageMode: "home-or-sidepanel" });
-    return report.status === "PASS";
-  } catch {
-    return false;
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    try {
+      const report = await checkExtensionRuntimeHealth(target, Number(port), { pageMode: "home-or-sidepanel" });
+      if (report.status === "PASS") return true;
+    } catch {
+    }
+    if (attempt < 2) await new Promise((resolve) => setTimeout(resolve, 250));
   }
+  return false;
 }
 async function extensionReattach(target, displayMode = "fullscreen") {
   const reattachScript = recipeHarnessPath(target, "extension", "scripts", "reattach.sh");
@@ -181,7 +206,7 @@ async function extensionReattach(target, displayMode = "fullscreen") {
   if (process.env.CDP_PORT) reattachArgs.push("--cdp-port", process.env.CDP_PORT);
   if (process.env.WATCHER_PORT) reattachArgs.push("--watcher-port", process.env.WATCHER_PORT);
   if (process.env.EXTENSION_START_URL) reattachArgs.push("--start-url", process.env.EXTENSION_START_URL);
-  console.error(`\u2192 extension quick reattach \u2014 reload in place \xB7 CDP :${process.env.CDP_PORT ?? "default"} (no rebuild, no relaunch)`);
+  console.error(colorHumanMessage(`\u2192 extension quick reattach \u2014 reload in place \xB7 CDP :${process.env.CDP_PORT ?? "default"} (no rebuild, no relaunch)`));
   return spawnScriptStreaming(reattachScript, reattachArgs, target);
 }
 async function extensionRebuild(target) {
@@ -195,7 +220,7 @@ async function extensionRebuild(target) {
   const liveArgs = ["--target", target, "--start-watch"];
   if (process.env.CDP_PORT) liveArgs.push("--cdp-port", process.env.CDP_PORT);
   if (process.env.EXTENSION_START_URL) liveArgs.push("--start-url", process.env.EXTENSION_START_URL);
-  console.error(`\u2192 extension quick relaunch \u2014 webpack :${process.env.WATCHER_PORT ?? "default"} \xB7 CDP :${process.env.CDP_PORT ?? "default"} (output streams below)`);
+  console.error(colorHumanMessage(`\u2192 extension quick relaunch \u2014 webpack :${process.env.WATCHER_PORT ?? "default"} \xB7 CDP :${process.env.CDP_PORT ?? "default"} (output streams below)`));
   const result = await spawnScriptStreaming(liveScript, liveArgs, target);
   if (result.output) {
     try {