@deeeed/metamask-harness 0.68.0 → 0.70.0

package/adapters/shared/open-debug.mjs

@@ -475,8 +475,13 @@ async function openBrokeredMobileDebugger(port, shouldOpen) {
 function pickExtensionTarget(targets, targetKind) {
   const extensionTargets = targets.filter((target) => String(target.url || '').startsWith('chrome-extension://'));
   if (targetKind === 'worker') {
+    // Branded Chrome runs component extensions with their own service workers;
+    // prefer the worker of the extension whose wallet page is open.
+    const walletPage = extensionTargets.find((target) => /\/(home|sidepanel)\.html/u.test(String(target.url || '')));
+    const walletId = process.env.RECIPE_HARNESS_EXTENSION_ID || (walletPage ? String(walletPage.url).split('/')[2] : '');
     return (
-      extensionTargets.find((target) => target.type === 'service_worker')
+      (walletId && extensionTargets.find((target) => target.type === 'service_worker' && String(target.url).startsWith(`chrome-extension://${walletId}/`)))
+      || extensionTargets.find((target) => target.type === 'service_worker')
       || targets.find((target) => target.type === 'service_worker' && String(target.url || '').startsWith('chrome-extension://'))
       || null
     );

package/dist/adapters/mobile/prepare.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { recordDepsBaseline } from "@farmslot/recipe-harness/runtime/deps-readiness";
 import { resolveAndExportMobileToolPaths } from "../../../library/actions/mobile/platform/tool-paths.mjs";
 import { EXIT, spawnScriptStreaming } from "../../commands/shared.js";
+import { shellQuote } from "../../commands/parse-args.js";
 import { runnerDir } from "../../paths.js";
 import {
   decideMobileReadiness,
@@ -51,12 +52,14 @@ async function prepareMobile(target, opts = {}) {
   });
   if (report.decision === "blocked") {
     const reasons = report.reasons.join(" ");
-    const next = report.userAction ?? "fix the bundle error in app code before retrying recipe up.";
+    const next = report.userAction ?? `mm-harness logs --target ${shellQuote(target)} --full`;
     const msg = `mobile prepare blocked: ${reasons}
   Next: ${next}`;
-    if (!json) process.stderr.write(`${msg}
-`);
-    return { status: EXIT.runtime, output: msg };
+    return {
+      status: EXIT.runtime,
+      output: msg,
+      readinessBlock: { reasonCode: report.reasonCode, message: reasons, userAction: next }
+    };
   }
   const iosAccessibilityChanged = platform === "ios" && report.decision !== "unknown" && enableIosAccessibility(json);
   const rebuildNative = preflightMode === "rebuild-native" || preflightMode === "clean";

package/dist/adapters/mobile/runtime-decision.js

@@ -12,6 +12,7 @@ import {
 } from "@farmslot/recipe-harness/runtime/log-analysis";
 import { probeMetroPackager } from "@farmslot/recipe-harness/runtime/metro-probe";
 import { color } from "../../cli-color.js";
+import { shellQuote } from "../../commands/parse-args.js";
 import { recipeRuntimePath } from "../../paths.js";
 import { resolveMobileToolPath } from "../../../library/actions/mobile/platform/tool-paths.mjs";
 import { mobileProductMarkers } from "./deps-markers.js";
@@ -149,7 +150,7 @@ const launchActions = (target, clearMetro = false) => {
   return actions;
 };
 function depsInstallCommand(resolved) {
-  return fs.existsSync(path.join(resolved, "node_modules")) ? "`yarn setup:expo --no-build-ios --no-build-android`" : "`yarn install --immutable && yarn setup:expo --no-build-ios --no-build-android`";
+  return fs.existsSync(path.join(resolved, "node_modules")) ? "yarn setup:expo --no-build-ios --no-build-android" : "yarn install --immutable && yarn setup:expo --no-build-ios --no-build-android";
 }
 async function decideMobileReadiness(target, options = {}) {
   const resolved = path.resolve(target);
@@ -157,18 +158,15 @@ async function decideMobileReadiness(target, options = {}) {
   const fast = options.preflightMode === "fast";
   const report = await computeMobileReadiness(resolved, options, fast);
   if (fast && report.decision === "install") {
-    const standalone = depsInstallCommand(resolved);
     return {
       ...report,
       decision: "blocked",
       reasonCode: "deps-not-ready",
       reasons: [
-        "Fast preflight found dependencies not ready and does not install them (the orchestrator deps phase owns installation).",
-        ...report.reasons
+        ...report.reasons,
+        "Quick launch does not install dependencies."
       ],
-      userAction: `1. Standalone checkout \u2014 run ${standalone} in the checkout.
-  2. Orchestrated slot \u2014 run its deps/prepare phase.
-  After the selected action succeeds, re-run \`mm-harness launch <platform>\`.`,
+      userAction: `cd ${shellQuote(resolved)} && ${depsInstallCommand(resolved)}`,
       actions: []
     };
   }
@@ -189,9 +187,9 @@ async function decideMobileReadiness(target, options = {}) {
     )
   };
 }
-function writeDepsNote(resolved) {
+function writeDepsNote() {
   const stream = process.stderr;
-  const body = `package.json/yarn.lock are newer than the node_modules install markers and no install baseline is recorded yet, so the installed node_modules are used as they are. Pulling commits refreshes those timestamps without changing dependencies, and a required-dependency presence check still runs, so this on its own is not evidence that anything drifted. Act only if you know dependencies changed: run ${depsInstallCommand(resolved)} once \u2014 that refreshes the markers, and \`mm-harness prepare\` records a baseline when it runs the install, so this note stops.`;
+  const body = "No install baseline is recorded. Required package checks passed; timestamps alone do not establish dependency drift. Reusing the installed dependencies.";
   stream.write(
     `
 ${color("warn", "mm-harness note (deps):", { stream })} ${color("dim", body, { stream })}
@@ -206,7 +204,6 @@ async function computeMobileReadiness(resolved, options, fast) {
   let deps = rawDeps;
   if (rawDeps.status === "stale" && !rawDeps.hasBaseline) {
     deps = { installed: rawDeps.installed, status: "current", hasBaseline: false };
-    writeDepsNote(resolved);
   }
   if (deps.status === "current") {
     const absent = missingRequiredDeps(resolved);
@@ -325,6 +322,7 @@ async function computeMobileReadiness(resolved, options, fast) {
       actions: installActions(resolved)
     };
   }
+  if (rawDeps.status === "stale" && !rawDeps.hasBaseline) writeDepsNote();
   if (metro.status === "down") {
     return {
       schemaVersion: 1,

package/dist/command-contract.js

@@ -168,6 +168,7 @@ const PUBLIC_COMMAND_CONTRACTS = {
       "--title": value(),
       "--task-text": value(),
       "--task-file": value(),
+      "--acceptance": value(),
       "--ticket": value(),
       "--source-ref": value(),
       "--surface": value(),
@@ -241,6 +242,9 @@ const PUBLIC_COMMAND_CONTRACTS = {
   call: {
     options: options(HELP, JSON, TARGET, ADAPTER, MOBILE_PLATFORM, DEVICE, RUNTIME_PORTS, RECIPE_RUNTIME, {
       "--list": bool(),
+      "--domain": value(),
+      "--source": value(),
+      "--sort": value(["domain", "name", "library"]),
       "--arg": value()
     }),
     positionals: [{ label: "action" }],
@@ -253,6 +257,9 @@ const PUBLIC_COMMAND_CONTRACTS = {
   run: {
     options: options(HELP, JSON, JSON_STREAM, TARGET, ADAPTER, MOBILE_PLATFORM, DEVICE, RUNTIME_PORTS, RECIPE_RUNTIME, RUN_FUNDING, {
       "--list": bool(),
+      "--domain": value(),
+      "--source": value(),
+      "--sort": value(["domain", "name", "library"]),
       "--plan": bool(),
       "--proof": bool(),
       "--describe": bool(),

package/dist/commands/call.js

@@ -65,6 +65,9 @@ async function handleCall(argv) {
   }
   const { action: shortName, args, rest } = parseCallArgs(argv);
   const { options } = parseArgs(rest, "call");
+  if (["domain", "source", "sort"].some((name) => optionString(options, name) !== void 0)) {
+    throw usageError("--domain, --source, and --sort require call --list.");
+  }
   const json = optionFlag(options, "json");
   if (!shortName) {
     let example = "mm-harness call <action>";

package/dist/commands/launch/index.js

@@ -320,6 +320,10 @@ async function handleLaunchLocked(argv, stream) {
   if (attempt.status === 0) {
     return await settleLaunch(jsonOutput, machine, stream, adapter, mobileTarget, tier, displayMode, target, state, wantWatch, wantVerify, remoteFlagRequest, true, attempt.remoteFeatureFlags);
   }
+  const readinessFailure = mobileReadinessFailure(attempt);
+  if (readinessFailure) {
+    return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, readinessFailure);
+  }
   if (adapter === "extension" && attempt.output.includes("REMOTE_FLAG_NOT_PINNABLE:")) {
     return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
       code: "REMOTE_FLAG_NOT_PINNABLE",
@@ -503,6 +507,10 @@ async function handleLaunchLocked(argv, stream) {
     state.recovered.push(recoveryCode);
     return await settleLaunch(jsonOutput, machine, stream, adapter, mobileTarget, tier, displayMode, target, state, wantWatch, wantVerify, remoteFlagRequest, true, attempt.remoteFeatureFlags);
   }
+  const retryReadinessFailure = mobileReadinessFailure(attempt);
+  if (retryReadinessFailure) {
+    return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, retryReadinessFailure);
+  }
   return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
     code: "SAME_RECOVERY_TWICE",
     message: `launch ${adapter}${mobileTarget ? ` ${mobileTarget}` : ""} failed again after ${recoveryCode} recovery \u2014 refusing to loop.`,
@@ -511,6 +519,17 @@ async function handleLaunchLocked(argv, stream) {
     originalError: attempt.output.trim() || void 0
   });
 }
+function mobileReadinessFailure(result) {
+  const block = result.readinessBlock;
+  if (!block) return void 0;
+  return {
+    code: block.reasonCode === "deps-not-ready" ? "MOBILE_DEPENDENCIES_NOT_READY" : "MOBILE_READINESS_BLOCKED",
+    message: block.message,
+    userAction: block.userAction,
+    recoverable: false,
+    exitCode: result.status
+  };
+}
 function extensionQuickReattachFailed(output) {
   return /\[reattach\]|extension quick reattach|mm-harness launch --build/u.test(output);
 }

package/dist/commands/list-executables.js

@@ -5,13 +5,14 @@ import { importRecipeProtocol } from "../paths.js";
 import { color } from "../cli-color.js";
 import { EXIT } from "./shared.js";
 import { optionFlag, optionString, optionStrings, resolveAdapter, shellQuoteArg } from "./parse-args.js";
-import { describeManifestActions, renderHumanActionCatalog } from "./manifest.js";
+import { actionDomain, describeManifestActions, renderHumanActionCatalog } from "./manifest.js";
 import {
   describeRunnableRecipe,
   listRunnableRecipes,
   resolveMetaMaskLibrarySources
 } from "./run-engine.js";
 const finalSegment = (name) => name.split(".").pop() ?? name;
+const recipeDomain = (name) => name.includes(".") ? name.split(".")[0].replaceAll("_", "-") : "general";
 function catalogDescription(description) {
   if (!description) return "";
   const firstSentence = description.match(/^.*?[.!?](?:\s|$)/u)?.[0]?.trim() ?? description;
@@ -20,23 +21,64 @@ function catalogDescription(description) {
 async function handleListExecutables(command, options) {
   const json = optionFlag(options, "json");
   const { adapter } = resolveAdapter(options);
+  const domainFilter = optionString(options, "domain")?.replaceAll("_", "-");
+  const sourceFilter = optionString(options, "source");
+  const sort = optionString(options, "sort") ?? (json ? "name" : "domain");
+  const groupKey = (entry, domain) => sort === "library" ? entry.source : sort === "domain" ? domain : "";
+  const select = (available2, domainOf) => available2.filter((entry) => (!domainFilter || domainOf(entry) === domainFilter) && (!sourceFilter || entry.source === sourceFilter)).sort((left, right) => groupKey(left, domainOf(left)).localeCompare(groupKey(right, domainOf(right))) || left.name.localeCompare(right.name));
+  const out = (style, text) => color(style, text, { stream: process.stdout });
+  const stylesFor = (domains) => {
+    const palette = ["label", "accent", "ok", "warn"];
+    return new Map([...new Set(domains)].sort().map((domain, index) => [domain, palette[index % palette.length]]));
+  };
   const librarySources = await resolveMetaMaskLibrarySources(optionStrings(options, "library"));
+  const libraryLines = () => {
+    const lines = ["Libraries loaded:"];
+    for (const source of librarySources ?? []) {
+      const name = source.name ?? path.basename(source.root);
+      const kind = source.provenance?.kind === "bundled" ? "bundled" : "linked";
+      lines.push(`  ${out("bold", name)} ${kind} \xB7 ${source.root}`);
+    }
+    if (domainFilter || sourceFilter) {
+      lines.push(`Filter: ${[domainFilter && `domain=${domainFilter}`, sourceFilter && `source=${sourceFilter}`].filter(Boolean).join(" ")}`);
+    }
+    return lines;
+  };
   if (command === "run") {
-    const recipes = await listRunnableRecipes(adapter, librarySources);
+    const available2 = await listRunnableRecipes(adapter, librarySources);
+    const recipes = select(available2, (recipe) => recipeDomain(recipe.name));
     if (json) {
       console.log(JSON.stringify({ schemaVersion: 1, command, action: "list", adapter, recipes }, null, 2));
       return EXIT.ok;
     }
-    const out = (style, text) => color(style, text, { stream: process.stdout });
+    const domainStyles = stylesFor(available2.map((recipe) => recipeDomain(recipe.name)));
     console.log(out("bold", `runnable recipes (${adapter})`));
+    for (const line of libraryLines()) console.log(line);
     console.log(out("comment", "Inspect: mm-harness run <recipe> --describe"));
+    if (recipes.length === 0) {
+      console.log("No runnable recipes match.");
+      console.log(`Available domains: ${[...domainStyles.keys()].join(", ") || "none"}`);
+      console.log(`Available sources: ${[...new Set(available2.map((recipe) => recipe.source))].join(", ") || "none"}`);
+    }
+    const groups = /* @__PURE__ */ new Map();
     for (const recipe of recipes) {
-      const shadowed = recipe.shadows.length > 0 ? ` shadows=${recipe.shadows.join(",")}` : "";
-      const variant = recipe.variant ? ` variant=${recipe.variant}` : " variant=all";
-      const parameters = recipe.parameters.length > 0 ? ` params=${recipe.parameters.map((parameter) => parameter.name).join(",")}` : "";
-      const summary = catalogDescription(recipe.description);
-      const description = summary ? ` \u2014 ${summary}` : "";
-      console.log(`  ${out("cmd", recipe.name)} ${out("dim", `[${recipe.source}]${variant}${shadowed}${parameters}`)}${description}`);
+      const group = groupKey(recipe, recipeDomain(recipe.name));
+      groups.set(group, [...groups.get(group) ?? [], recipe]);
+    }
+    for (const [group, entries] of groups) {
+      if (group) {
+        const label = sort === "library" ? `Library: ${group}` : group;
+        console.log(`
+${out(sort === "domain" ? domainStyles.get(group) : "bold", label)} ${out("dim", `(${entries.length})`)}`);
+      }
+      for (const recipe of entries) {
+        const style = domainStyles.get(recipeDomain(recipe.name));
+        const shadowed = recipe.shadows.length > 0 ? ` shadows=${recipe.shadows.join(",")}` : "";
+        const variant = recipe.variant ? ` variant=${recipe.variant}` : " variant=all";
+        const summary = catalogDescription(recipe.description);
+        console.log(`  ${out(style, recipe.name)} ${out("dim", `library=${recipe.source}${variant}${shadowed}`)}`);
+        if (summary) console.log(`    ${summary}`);
+      }
     }
     return EXIT.ok;
   }
@@ -47,9 +89,10 @@ async function handleListExecutables(command, options) {
   );
   const { getRecipeActionManifestActionNames } = await importRecipeProtocol();
   const protocolNames = new Set(getRecipeActionManifestActionNames(manifest));
-  const described = describeManifestActions(manifest, actionSources).filter((entry) => protocolNames.has(entry.name)).sort((left, right) => left.name.localeCompare(right.name));
+  const available = describeManifestActions(manifest, actionSources).filter((entry) => protocolNames.has(entry.name)).sort((left, right) => left.name.localeCompare(right.name));
+  const described = select(available, actionDomain);
   const shortCounts = /* @__PURE__ */ new Map();
-  for (const entry of described) {
+  for (const entry of available) {
     const short = finalSegment(entry.name);
     shortCounts.set(short, (shortCounts.get(short) ?? 0) + 1);
   }
@@ -73,9 +116,17 @@ async function handleListExecutables(command, options) {
     console.log(JSON.stringify({ schemaVersion: 1, command, action: "list", adapter, actions }, null, 2));
     return EXIT.ok;
   }
+  const contextLines = libraryLines();
+  if (described.length === 0) {
+    contextLines.push(`Available domains: ${[...new Set(available.map(actionDomain))].sort().join(", ") || "none"}`);
+    contextLines.push(`Available sources: ${[...new Set(available.map((entry) => entry.source))].sort().join(", ") || "none"}`);
+  }
   console.log(renderHumanActionCatalog(described, {
     title: `invocable actions (${adapter})`,
     guidance: "Use: mm-harness call <name>  \xB7  short names shown first where unambiguous",
+    sort,
+    domainStyles: stylesFor(available.map(actionDomain)),
+    contextLines,
     displayName: (entry) => {
       const short = shortByName.get(entry.name);
       return short ? `${short} (${entry.name})` : `${entry.name} (full name only \u2014 ambiguous short)`;

package/dist/commands/manifest.js

@@ -345,16 +345,21 @@ function summarizeDescribedAction(entry) {
   const { schema: _schema, examples: _examples, ...summary } = entry;
   return summary;
 }
+function actionDomain(entry) {
+  return entry.category.replaceAll("_", "-");
+}
 function renderHumanActionCatalog(actions, options) {
   const out = (style, text) => color(style, text, { stream: process.stdout });
   const groups = /* @__PURE__ */ new Map();
   for (const entry of actions) {
-    const group = actionDomainGroup(entry);
+    const group = options.sort === "name" ? "" : options.sort === "library" ? `Library: ${entry.source}` : options.sort === "domain" ? actionDomain(entry) : actionDomainGroup(entry);
     groups.set(group, [...groups.get(group) ?? [], entry]);
   }
-  const lines = [out("bold", options.title), out("comment", options.guidance)];
+  const lines = [out("bold", options.title), ...options.contextLines ?? [], out("comment", options.guidance)];
+  if (actions.length === 0) lines.push("No callable actions match.");
   for (const [group, entries] of groups) {
-    lines.push("", `${out(group === "official" ? "label" : "accent", group)} ${out("dim", `(${entries.length})`)}`);
+    const groupStyle = options.sort === "domain" ? options.domainStyles?.get(group) ?? "accent" : group === "official" ? "label" : "accent";
+    if (group) lines.push("", `${out(groupStyle, group)} ${out("dim", `(${entries.length})`)}`);
     for (const entry of entries) {
       const fieldNames = humanFieldNames(entry);
       const fields = fieldNames.length ? ` ${out("dim", `fields=${fieldNames.join(",")}`)}` : "";
@@ -362,7 +367,8 @@ function renderHumanActionCatalog(actions, options) {
       const description = entry.description ? ` ${out("comment", `\u2014 ${entry.description}`)}` : "";
       const source = ` ${out("dim", `[${entry.source}]`)}`;
       const risk = entry.capabilities.length ? ` ${out("dim", `risk=${entry.capabilities.join(",")}`)}` : "";
-      lines.push(`  ${out("cmd", options.displayName?.(entry) ?? entry.name)}${source}${fields}${cases}${risk}${description}`);
+      const nameStyle = options.domainStyles?.get(actionDomain(entry)) ?? "cmd";
+      lines.push(`  ${out(nameStyle, options.displayName?.(entry) ?? entry.name)}${source}${fields}${cases}${risk}${description}`);
     }
   }
   return lines.join("\n");
@@ -585,6 +591,7 @@ function levenshtein(left, right) {
 }
 export {
   ACTION_MATRIX_ADAPTERS,
+  actionDomain,
   actionExampleCommand,
   actionLibraryContextArgs,
   describeManifestActions,

package/dist/commands/run-engine.js

@@ -44,6 +44,7 @@ import {
   beginRunDiagnostics,
   finishRunDiagnostics
 } from "../run-diagnostics.js";
+import { executedBrowser, recipeCdpPorts } from "./run-report.js";
 import { EXIT } from "./shared.js";
 import {
   actionManifestPathOption,
@@ -155,7 +156,13 @@ async function runRecipe(adapter, recipe, artifactsDir, projectRoot, actionManif
       finalized.artifactManifestPath,
       effectsState
     );
-    return finalized;
+    const browser = executedBrowser(
+      adapter,
+      projectRoot,
+      finalized.artifactManifestPath,
+      recipeCdpPorts(runRequest)
+    );
+    return browser ? { ...finalized, browser } : finalized;
   } finally {
     restoreRuntimeEnvironment();
   }

package/dist/commands/run-report.js

@@ -1,6 +1,8 @@
 import fs from "node:fs";
+import { createRequire } from "node:module";
 import path from "node:path";
 import { execFileSync } from "node:child_process";
+import { recipeRuntimeDir } from "../paths.js";
 import { isRecord } from "./parse-args.js";
 function writeRunReport(result) {
   const summaryPath = String(result.summaryPath);
@@ -20,7 +22,7 @@ function writeRunReport(result) {
     preview: lines.filter((line) => line.startsWith("- ")).slice(0, 6).map((line) => line.slice(2))
   };
 }
-function indexProductProvenanceArtifact(artifactManifestPath, target, adapter) {
+function indexProductProvenanceArtifact(artifactManifestPath, target, adapter, browser = null) {
   const artifactsDir = path.dirname(artifactManifestPath);
   let gitRef = "unknown";
   let branch = "unknown";
@@ -53,7 +55,8 @@ function indexProductProvenanceArtifact(artifactManifestPath, target, adapter) {
     repository: path.basename(path.resolve(target)),
     git_ref: gitRef,
     branch,
-    dirty
+    dirty,
+    ...browser ? { browser } : {}
   };
   fs.writeFileSync(
     path.join(artifactsDir, "product-provenance.json"),
@@ -77,7 +80,13 @@ function indexProductProvenanceArtifact(artifactManifestPath, target, adapter) {
       type: "json",
       label: "Product checkout provenance",
       category: "system",
-      metadata: { adapter, git_ref: gitRef, branch, dirty }
+      metadata: {
+        adapter,
+        git_ref: gitRef,
+        branch,
+        dirty,
+        ...browser?.boundTo && browser.boundTo !== "none" ? { browser: browser.browser, browser_version: browser.version, browser_source: browser.source, extension_loading: browser.extensionLoading } : {}
+      }
     }
   ];
   fs.writeFileSync(
@@ -86,6 +95,87 @@ function indexProductProvenanceArtifact(artifactManifestPath, target, adapter) {
 `
   );
 }
+function readRecord(file) {
+  try {
+    const recorded = JSON.parse(fs.readFileSync(file, "utf8"));
+    return isRecord(recorded) ? recorded : null;
+  } catch {
+    return null;
+  }
+}
+const browserCdp = createRequire(import.meta.url)("../../adapters/shared/browser-cdp.cjs");
+function verifyLaunch(record, cdpPort) {
+  const launch = isRecord(record.launch) ? record.launch : {};
+  const pid = Number(launch.pid);
+  const port = Number(launch.cdpPort);
+  if (!Number.isInteger(pid) || !Number.isInteger(port) || typeof launch.profile !== "string" || typeof launch.processStartedAt !== "string") {
+    return "the browser record has no process identity (pid, start time, profile, CDP port)";
+  }
+  if (cdpPort && port !== Number(cdpPort)) return `the browser record is for CDP port ${port}, not ${cdpPort}`;
+  try {
+    const owner = browserCdp.cdpOwner(port, launch.profile);
+    if (owner.pid !== pid || owner.startedAt !== launch.processStartedAt) {
+      return `CDP port ${port} is now held by another browser process than the recorded pid ${pid}`;
+    }
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+  return null;
+}
+function resolveTemplatedPort(value, params, recipe) {
+  let resolved = value;
+  const template = /^\{\{\s*params\.([\w-]+)\s*\}\}$/u.exec(String(value).trim());
+  if (template) {
+    const name = template[1];
+    const schema = isRecord(recipe) && isRecord(recipe.paramsSchema) && isRecord(recipe.paramsSchema.properties) ? recipe.paramsSchema.properties[name] : void 0;
+    resolved = isRecord(params) && params[name] !== void 0 ? params[name] : isRecord(schema) ? schema.default : void 0;
+  }
+  const text = String(resolved ?? "").trim();
+  return /^\d+$/u.test(text) ? text : null;
+}
+function recipeCdpPorts(request) {
+  const ports = /* @__PURE__ */ new Set();
+  const envPort = request.env?.CDP_PORT || request.env?.RECIPE_CDP_PORT;
+  if (envPort) ports.add(String(envPort));
+  let recipe = request.recipeDocument;
+  if (recipe === void 0 && request.recipePath) {
+    try {
+      recipe = JSON.parse(fs.readFileSync(request.recipePath, "utf8"));
+    } catch {
+      recipe = void 0;
+    }
+  }
+  const workflow = isRecord(recipe) && isRecord(recipe.workflow) ? recipe.workflow : null;
+  const nodes = workflow && isRecord(workflow.nodes) ? Object.values(workflow.nodes) : [];
+  for (const node of nodes) {
+    if (!isRecord(node) || node.cdp_port === void 0 || node.cdp_port === null) continue;
+    const port = resolveTemplatedPort(node.cdp_port, request.params, recipe);
+    ports.add(port ?? `unresolved ${String(node.cdp_port)}`);
+  }
+  return [...ports];
+}
+function executedBrowser(adapter, target, artifactManifestPath, ports) {
+  if (adapter !== "extension") return null;
+  if (ports.length === 0) return { boundTo: "none", reason: "the run had no known CDP port" };
+  if (ports.length > 1) return { boundTo: "none", reason: `the run drove several CDP ports (${ports.join(", ")})` };
+  return launchedBrowser(target, path.dirname(artifactManifestPath), ports[0]);
+}
+function launchedBrowser(target, artifactsDir, cdpPort) {
+  const runtime = readRecord(path.join(artifactsDir, "extension-runtime", "runtime.json"));
+  const autolaunched = runtime && isRecord(runtime.browser) ? runtime.browser : null;
+  const candidates = [];
+  if (autolaunched) candidates.push([autolaunched, "run-autolaunch"]);
+  const slot = readRecord(path.join(path.resolve(target), recipeRuntimeDir(), "browser-resolution.json"));
+  if (slot) candidates.push([slot, "slot-runtime"]);
+  if (candidates.length === 0) return null;
+  const reasons = [];
+  for (const [record, boundTo] of candidates) {
+    const problem = verifyLaunch(record, cdpPort);
+    if (problem === null) return { ...record, boundTo };
+    reasons.push(`${boundTo}: ${problem}`);
+  }
+  return { boundTo: "none", reason: reasons.join("; ") };
+}
 function renderRunReport(summary, entries) {
   const lines = [
     "# MetaMask Recipe Run",
@@ -187,6 +277,9 @@ function indexRunReportArtifact(artifactManifestPath) {
 `);
 }
 export {
+  executedBrowser,
   indexProductProvenanceArtifact,
+  launchedBrowser,
+  recipeCdpPorts,
   writeRunReport
 };

package/dist/commands/run.js

@@ -147,6 +147,9 @@ async function handleRun(parsed) {
   }
 }
 async function handleRunInner({ positional, options }, stream) {
+  if (!optionFlag(options, "list") && ["domain", "source", "sort"].some((name) => optionString(options, name) !== void 0)) {
+    throw usageError("--domain, --source, and --sort require run --list.");
+  }
   if (optionFlag(options, "describe") && (optionFlag(options, "list") || optionFlag(options, "plan"))) {
     const message = "--describe cannot be combined with --list or --plan.";
     const userAction = "choose one: mm-harness run --list, mm-harness run <recipe> --describe, or mm-harness run <recipe> --plan";
@@ -373,7 +376,8 @@ async function handleRunInner({ positional, options }, stream) {
     indexProductProvenanceArtifact(
       result.artifactManifestPath,
       target,
-      adapter
+      adapter,
+      result.browser ?? null
     );
     if (violation !== null) {
       const userAction = violation.userAction ?? `inspect ${shellQuote(result.summaryPath)} and ${shellQuote(result.tracePath)}; fix the application or recipe failure before retrying`;

package/dist/doctor.js

@@ -1,3 +1,4 @@
+import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
@@ -167,7 +168,7 @@ function createDoctorReport(adapter, target, manifestValidation, actionManifestP
       message: mode === "unsupported/no bridge" ? `No ${adapter} bridge is available for this checkout.` : `${adapter} compatibility mode: ${mode}.`
     },
     ...adapter === "mobile" ? mobileToolDoctorChecks(mobilePlatform) : [],
-    ...adapter === "extension" ? [extensionBrowserDoctorCheck(target)] : []
+    ...adapter === "extension" ? [extensionBrowserDoctorCheck(target), extensionBrowserResolutionDoctorCheck(target)] : []
   ];
   const requiredChecks = requiredDoctorCheckSummary(checks);
   return {
@@ -214,6 +215,51 @@ function extensionBrowserDoctorCheck(target) {
     userAction: "yarn playwright install chromium"
   };
 }
+function extensionBrowserResolutionDoctorCheck(target) {
+  const resolver = path.join(runnerDir, "adapters/shared/browser-resolver.cjs");
+  const runtime = path.join(path.resolve(target), recipeRuntimeDir());
+  const record = path.join(runtime, "browser-resolution.json");
+  let profile = process.env.CHROME_USER_DATA_DIR || path.join(runtime, process.env.RECIPE_CHROME_PROFILE_NAME || "chrome-profile");
+  while (profile.length > 1 && profile.endsWith("/")) profile = profile.slice(0, -1);
+  const profileExists = fs.existsSync(path.join(profile, "Local State"));
+  const result = spawnSync(process.execPath, [
+    resolver,
+    "resolve",
+    "--target",
+    path.resolve(target),
+    "--launch-method",
+    "launch-services",
+    "--display",
+    "headful",
+    ...profileExists && fs.existsSync(record) ? ["--recorded", record] : [],
+    "--json"
+  ], {
+    cwd: path.resolve(target),
+    encoding: "utf8",
+    timeout: 135e3
+  });
+  if (result.status === 0) {
+    const resolution = JSON.parse(result.stdout);
+    const managed = resolution.managedChrome;
+    const managedNote = managed && !resolution.warning ? ` Google Chrome is managed by policy (${managed.forcedExtensions.length} forced extension${managed.forcedExtensions.length === 1 ? "" : "s"}: ${managed.forcedExtensions.map(({ id, name }) => name ? `${id} (${name})` : id).join(", ")}${managed.signinForced ? "; browser sign-in forced" : ""}); slots use Chrome for Testing.` : "";
+    const probe = resolution.probe ? `; Chrome for Testing probe (${resolution.probe.launchMethod}, ${resolution.probe.display}${resolution.probe.cached ? ", cached" : ""}${resolution.probe.transient ? `, retried after ${resolution.probe.expiresAt}` : ""}): ${resolution.probe.reason}` : resolution.recordedFrom ? `; kept from the slot profile record ${resolution.recordedFrom}` : "";
+    return {
+      id: "extension-browser",
+      status: "pass",
+      required: false,
+      message: `Launch browser: ${resolution.browser} ${resolution.version ?? "(unknown version)"} via ${resolution.source} (${resolution.mode}); extension loading: ${resolution.extensionLoading}${probe}.${managedNote}${resolution.warning ? ` Warning: ${resolution.warning}` : ""}`,
+      detail: resolution.bin
+    };
+  }
+  const message = (result.stderr || result.error?.message || "browser resolution failed").trim();
+  return {
+    id: "extension-browser",
+    status: "fail",
+    required: message.includes("BROWSER_UNLAUNCHABLE:"),
+    message,
+    userAction: "install Google Chrome, or set RECIPE_HARNESS_BROWSER / RECIPE_HARNESS_CHROME_BIN to a browser that starts"
+  };
+}
 function mobileToolDoctorChecks(platform) {
   const specs = platform === "android" ? [{ tool: "adb", platform: "Android" }] : platform === "ios" ? [{ tool: "idb", platform: "iOS" }] : [
     { tool: "adb", platform: "Android" },
@@ -294,6 +340,7 @@ export {
   compatibilityMode,
   createDoctorReport,
   extensionBrowserDoctorCheck,
+  extensionBrowserResolutionDoctorCheck,
   fixtureFileSummary,
   fixtureSummary,
   mobileToolDoctorChecks,

package/dist/mm-harness-cli.js

@@ -298,6 +298,7 @@ Example:
 Task:
   --title <t>                        Task title (required)
   --task-text <s> | --task-file <p>  Task description, inline or from a file
+  --acceptance <criterion>          Authored acceptance criterion (repeatable, preserved in order)
   --ticket <key>                     Ticket key
   --source-ref <url>                 Where the task came from
 
@@ -430,6 +431,9 @@ Example:
   mm-harness actions.
 
   --list                             List actions accepted by call for this adapter; no <action> needed
+  --domain <name>                    With --list: filter by action domain, e.g. perps or swap-bridge
+  --source <name>                    With --list: filter by origin, e.g. metamask, perps, or official
+  --sort <domain|name|library>       With --list: grouping/order (default: domain; JSON: name)
   --arg k=v                          Action field value (repeatable; equivalent to key=value shorthand)
   --device <udid|serial|name>        Mobile only: target this device (sets IOS_SIMULATOR / ADB_SERIAL and updates agentic-runtime.json). Without it, >1 connected mobile device fails fast and lists them. Do not shut down other devices to force selection.
   --cdp-port <port>                  Extension only: bind the action to this live browser runtime.
@@ -464,6 +468,9 @@ Remote feature flags (mobile applies at runtime; extension pins at launch):
 
 Discovery:
   --list                             List complete recipes accepted by run for this adapter; no <recipe> needed
+  --domain <name>                    With --list: filter by recipe domain, e.g. perps or swap-bridge
+  --source <name>                    With --list: filter by library origin, e.g. metamask or perps
+  --sort <domain|name|library>       With --list: grouping/order (default: domain; JSON: name)
   --describe                         Show one recipe's parameters, composed actions/recipes, and runnable command
   --plan                             Validate + print execution plan, touching nothing. Exit 5 if invalid.
   --proof                            Preflight behavioral proof bindings before planning/execution; runtime evidence is still required.

package/docs/QA.md

@@ -94,6 +94,9 @@ mm-harness debug
   `EXTENSION_PRODUCT_CONFIG_REQUIRED` before build or browser startup.
 - [ ] Missing Chromium returns `EXTENSION_BROWSER_REQUIRED` without using system
   Chrome.
+- [ ] `doctor --adapter extension` names the launch browser, its version, why
+  it was chosen and how the extension loads; `RECIPE_HARNESS_BROWSER=cft`
+  restores Chrome for Testing, `=chrome` loads into Google Chrome over CDP.
 - [ ] Launch uses the checkout-owned profile, opens one MetaMask surface, avoids
   keychain prompts, and preserves keyboard focus by default.
 - [ ] A second launch reuses the watcher/profile without duplicate tabs.