@deeeed/metamask-harness 0.84.0 → 0.86.0

package/dist/commands/runtime-launch.js

@@ -10,6 +10,7 @@ import {
   writeMobileReleaseArtifactState
 } from "../adapters/mobile/release-artifact-state.js";
 import { extensionDepsBlock } from "./launch/extension.js";
+import { recordExtensionConsoleLaunch } from "../adapters/extension/console-capture.js";
 import { isExtensionDistStale } from "../adapters/extension/runtime-decision.js";
 import { FeatureFlagSpecError, parseRemoteFlagSpec } from "../feature-flags.js";
 async function handleRuntimeLaunch(args) {
@@ -186,6 +187,7 @@ async function handleRuntimeLaunchLocked({ options }) {
       cdpPort
     }));
   }
+  recordExtensionConsoleLaunch(target);
   const result = await spawnScriptStreaming(command[0], command.slice(1), target, {
     forward: jsonMode ? "stderr" : "original",
     stdin: jsonMode ? "ignore" : "inherit",

package/dist/commands/status-probe.js

@@ -52,6 +52,13 @@ function parseBridgeEntries(raw) {
     ...e.featureFlags !== void 0 ? { featureFlags: e.featureFlags } : {}
   }));
 }
+function androidModelMatches(deviceName, model, device, devices) {
+  if (deviceName === model || deviceName.startsWith(`${model} -`)) return true;
+  if (!deviceName.endsWith(` ${model}`) && !deviceName.includes(` ${model} -`)) return false;
+  const physical = (d) => d.platform === "android" && !d.id.startsWith("emulator-");
+  if (!physical(device)) return false;
+  return devices.filter((d) => physical(d) && d.name === device.name).length === 1;
+}
 function matchBridgeEntry(device, entries, devices) {
   const byId = entries.find((e) => e.deviceName === device.id);
   if (byId) return byId;
@@ -60,7 +67,7 @@ function matchBridgeEntry(device, entries, devices) {
     if (byName) return byName;
     if (device.platform === "android") {
       const model = device.name.replace(/_/gu, " ");
-      const byModel = entries.find((e) => e.deviceName === model || e.deviceName.startsWith(`${model} -`));
+      const byModel = entries.find((e) => androidModelMatches(e.deviceName, model, device, devices));
       if (byModel) return byModel;
     }
   }

package/dist/commands/status.js

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { featureFlagReport } from "../feature-flags.js";
-import { color, detectAdapter, adapterDetectNext, EXIT, usageOut, optionFlag, optionString, targetPath } from "@farmslot/recipe-cli/harness";
+import { color, contextAdapter, harnessContextField, adapterDetectNext, EXIT, usageOut, optionFlag, optionString, targetPath } from "@farmslot/recipe-cli/harness";
 import { collectCheckoutView, renderCheckoutView } from "../checkout-view.js";
 import { assertAdapter } from "../paths.js";
 import { getAdapterSurface } from "../adapters/surface.js";
@@ -24,7 +24,7 @@ async function handleStatus({ options }) {
   }
   const fast = optionFlag(options, "fast");
   const allDevices = optionFlag(options, "allDevices");
-  const adapter = detectAdapter(target);
+  const adapter = contextAdapter(target);
   if (!adapter) {
     return usageOut(json, "status", `could not detect the MetaMask repo type for ${target}`, adapterDetectNext());
   }
@@ -58,6 +58,7 @@ async function handleStatus({ options }) {
             command: "status",
             adapter,
             target,
+            ...harnessContextField(),
             view,
             devices: liveView.devicesWithLive,
             featureFlags: featureFlagReport(liveView.featureFlagOverrides),
@@ -79,6 +80,7 @@ async function handleStatus({ options }) {
             command: "status",
             adapter,
             target,
+            ...harnessContextField(),
             view,
             devices,
             featureFlags: staticFeatureFlags,

package/dist/commands/task-init.js

@@ -1,7 +1,6 @@
-import { harnessExecutable, detectAdapter, EXIT } from "@farmslot/recipe-cli/harness";
+import { harnessExecutable, contextAdapter, EXIT } from "@farmslot/recipe-cli/harness";
 import { spawnSync } from "node:child_process";
 import { createRequire } from "node:module";
-import "../adapters/surface.js";
 const require2 = createRequire(import.meta.url);
 const USAGE = "mm-harness task init <task-dir> --flow f --template id --title t [options]";
 function hasOption(argv, name) {
@@ -14,7 +13,7 @@ function metamaskDefaults(argv) {
     defaults.push("--mark-command", `${harnessExecutable()} checklist mark`);
   }
   if (!hasOption(argv, "--platform")) {
-    const adapter = detectAdapter(process.cwd());
+    const adapter = contextAdapter(process.cwd());
     if (adapter) defaults.push("--platform", adapter);
   }
   return defaults;

package/dist/console-classifier.js

@@ -4,13 +4,14 @@ import {
   consoleRecords,
   libraryRootsFromEnv,
   loadConsoleAllowlist,
-  messageSignature
+  messageSignature,
+  withBundledLibraryRoot
 } from "../library/actions/shared/console-findings.mjs";
 const consoleClassifier = {
   records: (text) => consoleRecords(text),
   classify: (record) => classifyConsoleRecord(record),
   signature: (message) => messageSignature(message),
-  loadAllowlist: (libraryRoots) => loadConsoleAllowlist([...libraryRoots]),
+  loadAllowlist: (libraryRoots) => loadConsoleAllowlist(withBundledLibraryRoot([...libraryRoots])),
   match: (event, allowlist) => allowlistMatch(event, allowlist),
   libraryRoots: () => libraryRootsFromEnv()
 };

package/dist/doctor.js

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { RECIPE_CLI_VERSION } from "@farmslot/recipe-cli";
-import { color, harnessExecutable, recipeHarnessRoot, recipeRuntimeDir, readRuntimeContextField, resolveRuntimeContextPath } from "@farmslot/recipe-cli/harness";
+import { color, harnessContext, harnessContextField, harnessExecutable, recipeHarnessRoot, recipeRuntimeDir, readRuntimeContextField, resolveRuntimeContextPath } from "@farmslot/recipe-cli/harness";
 import { normalizeFeatureFlagRecord } from "./feature-flags.js";
 import { getAdapterSurface } from "./adapters/surface.js";
 import { isPin } from "./harness-pin.js";
@@ -107,10 +107,13 @@ function runtimeContextSummary(target, adapter) {
   const file = envOverride ?? path.relative(target, contextPath);
   const fields = {};
   const specs = adapter ? RUNTIME_CONTEXT_FIELDS.filter((spec) => spec.adapters.includes(adapter)) : RUNTIME_CONTEXT_FIELDS;
+  const filled = new Set(
+    Object.values(harnessContext()?.ports ?? {}).flatMap((port) => port?.filled ? port.names ?? [] : [])
+  );
   for (const spec of specs) {
     const envName = spec.envVars.find((name) => {
       const value = process.env[name];
-      return value !== void 0 && value !== "";
+      return value !== void 0 && value !== "" && !filled.has(name);
     });
     if (envName !== void 0) {
       fields[spec.key] = { value: process.env[envName], source: "env", envVar: envName, customize: spec.customize };
@@ -165,6 +168,7 @@ function createDoctorReport(adapter, target, manifestValidation, actionManifestP
     requiredChecks,
     adapter,
     target,
+    ...harnessContextField(),
     runner: runnerProvenance(actionManifestPath),
     compatibilityMode: mode,
     shape: repoShape(target),

package/dist/mm-harness-cli.js

@@ -5,8 +5,8 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import {
+  contextAdapter,
   createHarnessCli,
-  detectAdapter,
   handleActions,
   handleCall,
   handleHarness,
@@ -16,6 +16,7 @@ import {
   handleRun,
   handleStop,
   harnessHost,
+  optionValues,
   parseArgs,
   targetPath
 } from "@farmslot/recipe-cli/harness";
@@ -26,7 +27,9 @@ import {
   explainMissingAdapterLibrary,
   HIDDEN_COMMANDS,
   PUBLIC_COMMANDS,
-  REPLACED_OPTIONS
+  REPLACED_OPTIONS,
+  selectableAdapters,
+  withAdapterList
 } from "./command-contract.js";
 import { handleCheck } from "./commands/check.js";
 import { handleChecklist } from "./commands/checklist.js";
@@ -60,7 +63,7 @@ import { handleTutorial } from "./commands/tutorial.js";
 import { handleUpdate, maybeNudge } from "./commands/update.js";
 import { metaMaskEngine } from "./engine.js";
 import { ActionManifestError } from "./manifest.js";
-import { walletFixturePath } from "./paths.js";
+import { harnessSlotPoolDir, walletFixturePath } from "./paths.js";
 import { configPath, hydrateLibraryPathEnv, readConfig } from "./review/knowledge.js";
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 function hostVersion() {
@@ -99,7 +102,7 @@ function overlay(command) {
       try {
         const { options } = parseArgs(args);
         const target = targetPath(options);
-        const adapterRaw = (typeof options["adapter"] === "string" ? options["adapter"] : void 0) ?? (typeof options["platform"] === "string" ? options["platform"] : void 0) ?? detectAdapter(target);
+        const adapterRaw = contextAdapter(target);
         if (adapterRaw && adapterRegistry.has(adapterRaw)) {
           await handleHarness(["install", "--platform", adapterRaw, "--target", target, "--quiet"]);
         }
@@ -116,6 +119,9 @@ function overlay(command) {
     return code;
   };
 }
+function invocationLibraries() {
+  return optionValues(process.argv.slice(2), "--library");
+}
 function withManifestEnvelope(command, run) {
   return async (args) => {
     try {
@@ -169,7 +175,8 @@ const PUBLIC_RUN = {
   fixtures: { run: handleFixtures }
 };
 const HIDDEN_RUN = {
-  "completion-candidates": { run: handleCompletionCandidates, nudge: false },
+  // Shell completion answers for the checkout's adapter, so it resolves one.
+  "completion-candidates": { run: handleCompletionCandidates, nudge: false, context: "adapter" },
   "runtime-health": { run: (args) => handleRuntimeHealth(parseArgs(args)) },
   "runtime-decision": { run: (args) => handleRuntimeDecision(parseArgs(args, { recordIsFlag: true })) },
   "resolve-extension": { run: (args) => handleResolveExtension(parseArgs(args)) },
@@ -227,9 +234,15 @@ await createHarnessCli({
   afterAdapterLoad,
   // `mm-harness config set libraries.<name>` libraries, read before hydration.
   configuredLibraries: configuredLibrarySources,
+  slotPoolDir: () => harnessSlotPoolDir(),
   commands: [
     ...PUBLIC_COMMANDS.map((command) => ({
       ...command,
+      // Rendered on read: the adapter list includes the operator's libraries
+      // and this invocation's --library entries.
+      get helpText() {
+        return withAdapterList(command.helpText, invocationLibraries());
+      },
       ...PUBLIC_RUN[command.name],
       run: withManifestEnvelope(command.name, PUBLIC_RUN[command.name].run)
     })),
@@ -244,7 +257,7 @@ await createHarnessCli({
     description: "the MetaMask recipe harness: launch the app, prove behavior, manage the runtime overlay",
     intro: (out) => [
       `${out("bold", "mm-harness")} \u2014 one front door for the MetaMask recipe loop: launch the app, prove behavior, manage the runtime overlay.`,
-      "Run it from inside a MetaMask checkout; the platform (mobile | extension | core | terminal) is auto-detected.",
+      `Run it from inside a MetaMask checkout; the platform (${selectableAdapters(invocationLibraries()).join(" | ")}) is auto-detected.`,
       `Grammar: ${out("cmd", "mm-harness <command> [target] [flags]")}   (target is a positional: ios | android; flags add agent depth; --json is the agent contract)`
     ],
     groups: HELP_GROUPS,

package/dist/paths.js

@@ -17,12 +17,12 @@ function recipeWatchLogCandidates() {
     path.join(recipeRuntimeDir(), "recipe-harness-webpack.log")
   ];
 }
-function resolveLocalProtocolRoot() {
-  const root = process.env.METAMASK_RUNNER_PROTOCOL_ROOT || readConfiguredProtocolRoot();
+function resolveLocalProtocolRoot(env = process.env) {
+  const root = env.METAMASK_RUNNER_PROTOCOL_ROOT || readConfiguredProtocolRoot();
   return root ? path.resolve(root) : void 0;
 }
-function resolveFarmslotPoolDir(starts = [runnerDir, process.cwd()]) {
-  const configured = resolveLocalProtocolRoot();
+function resolveFarmslotPoolDir(starts = [runnerDir, process.cwd()], env = process.env) {
+  const configured = resolveLocalProtocolRoot(env);
   if (configured) return path.join(configured, "pool");
   for (const start of starts) {
     const pool = findPoolDir(start);
@@ -30,6 +30,10 @@ function resolveFarmslotPoolDir(starts = [runnerDir, process.cwd()]) {
   }
   return void 0;
 }
+function harnessSlotPoolDir(env = process.env, starts) {
+  if (env.FARMSLOT_POOL_DIR || env.FARMSLOT_ROOT) return void 0;
+  return resolveFarmslotPoolDir(starts, env);
+}
 const LIBRARY_ACTION_NAMESPACE = "metamask";
 function readConfiguredProtocolRoot() {
   const configPath = path.join(runnerDir, ".farmslot-root");
@@ -156,6 +160,7 @@ export {
   PREPARE_PROGRESS_ARTIFACT,
   assertAdapter,
   extensionIdPath,
+  harnessSlotPoolDir,
   importMetaMaskNativeUiProvider,
   importRecipeHarness,
   importRecipeHarnessAppLifecycle,

package/dist/recipe-security.js

@@ -32,7 +32,7 @@ const READ_ONLY_CUSTOM_ACTIONS = /* @__PURE__ */ new Set([
   // Terminal wallet request log reads.
   "metamask.wallet.read_signatures",
   "metamask.wallet.assert_signatures",
-  // Terminal console capture read.
+  // Console capture read (web-dapp, Mobile, Extension).
   "metamask.app.assert_no_console_errors"
 ]);
 const APP_MUTATION_CUSTOM_ACTIONS = /* @__PURE__ */ new Set([

package/dist/review/knowledge.js

@@ -1,4 +1,4 @@
-import { detectAdapter, usageError } from "@farmslot/recipe-cli/harness";
+import { AdapterAmbiguousError, detectAdapter, usageError } from "@farmslot/recipe-cli/harness";
 import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
@@ -95,6 +95,7 @@ function withRevision(location) {
   return revision ? { ...location, revision } : location;
 }
 function siblingRoots(context) {
+  if ((context.env ?? process.env).MM_HARNESS_SIBLING_LIBRARIES === "0") return [];
   const home = context.homeDir ?? os.homedir();
   const parents = [path.dirname(path.resolve(context.target)), path.join(home, "shared-library")];
   const roots = [];
@@ -173,6 +174,9 @@ function resolveLibrary(name, options) {
   return void 0;
 }
 function discoverLibraries(context) {
+  return discoverLibraryLocations(context).map(withRevision);
+}
+function discoverLibraryLocations(context) {
   const env = context.env ?? process.env;
   const seenRoots = /* @__PURE__ */ new Set();
   const seenNames = /* @__PURE__ */ new Set();
@@ -184,7 +188,7 @@ function discoverLibraries(context) {
     if (seenNames.has(libraryName)) return;
     seenRoots.add(resolved);
     seenNames.add(libraryName);
-    found.push(withRevision({ name: libraryName, root: resolved, source }));
+    found.push({ name: libraryName, root: resolved, source });
   };
   for (const entry of parseLibraryPathEnv(declaredLibraryPathFor(env))) add(entry.name, entry.root, "env");
   for (const [name, root] of Object.entries(context.config?.libraries ?? {})) add(name, root, "config");
@@ -215,7 +219,7 @@ async function hydrateLibraryPathEnv(context) {
       (entry) => entry.name ?? loadOwnedPaths(entry.root)?.domain ?? path.basename(entry.root)
     )
   );
-  const discovered = discoverLibraries(context).filter(
+  const discovered = discoverLibraryLocations(context).filter(
     (library) => library.source !== "env" && !declared.has(library.name)
   );
   if (discovered.length === 0) return;
@@ -234,7 +238,7 @@ function resolveReference(adapter, context) {
   const fromConfig = context.config?.references?.[adapter];
   if (fromConfig && isDir(path.resolve(fromConfig))) return { adapter, root: path.resolve(fromConfig), source: "config" };
   const target = path.resolve(context.target);
-  const siblings = siblingRoots(context).filter((root) => root !== target && detectAdapter(root) === adapter).sort((a, b) => {
+  const siblings = siblingRoots(context).filter((root) => root !== target && siblingAdapter(root) === adapter).sort((a, b) => {
     const refA = path.basename(a).endsWith("-ref") ? 0 : 1;
     const refB = path.basename(b).endsWith("-ref") ? 0 : 1;
     return refA - refB || path.basename(a).length - path.basename(b).length || a.localeCompare(b);
@@ -242,6 +246,14 @@ function resolveReference(adapter, context) {
   if (siblings[0]) return { adapter, root: siblings[0], source: "sibling" };
   return void 0;
 }
+function siblingAdapter(root) {
+  try {
+    return detectAdapter(root);
+  } catch (error) {
+    if (error instanceof AdapterAmbiguousError) return void 0;
+    throw error;
+  }
+}
 function referenceHint(adapter) {
   return `set ${referenceEnvName(adapter)} or run: mm-harness config set references.${adapter} <path>`;
 }

package/dist/runner.js

@@ -78,7 +78,7 @@ async function createMetaMaskRunner(adapter, actionManifest, options = {}) {
         const { createAgentDeviceUiTransport } = await importMetaMaskNativeUiProvider();
         return createAgentDeviceUiTransport(options2);
       }
-    }, preparedLiveAdapters, { hudPolicy: options.autoHud === true ? "show" : "auto" })
+    }, preparedLiveAdapters)
   });
   const existing = new Set([...core, ...ui].map((entry) => entry.action));
   const lifecycleAdapters = bindMetaMaskMobileLifecycleDeadline(
@@ -97,7 +97,8 @@ async function createMetaMaskRunner(adapter, actionManifest, options = {}) {
   ].filter(
     (entry) => declaredActions.has(entry.action) && !existing.has(entry.action) && !lifecycle.some((lifecycleEntry) => lifecycleEntry.action === entry.action)
   );
-  const autoHudDisabled = options.autoHud === false || options.autoHud === void 0 && (process.env.METAMASK_RECIPE_AUTO_HUD === "0" || process.env.METAMASK_RECIPE_AUTO_HUD === "false");
+  const hudOffSwitch = process.env.METAMASK_RECIPE_AUTO_HUD === "0" || process.env.METAMASK_RECIPE_AUTO_HUD === "false";
+  const autoHudDisabled = options.autoHud === false || options.autoHud === void 0 && hudOffSwitch;
   const externalMutationActions = new Set(
     Object.entries(actionManifest.actions).filter(([, declaration]) => Array.isArray(declaration.execution_capabilities) && declaration.execution_capabilities.includes("external-mutation")).map(([action]) => action)
   );
@@ -111,7 +112,7 @@ async function createMetaMaskRunner(adapter, actionManifest, options = {}) {
     ...adapterSecurity(entry.action, actionSources, options.trustTaskActions)
   }));
   const mutationBound = surface.actions.trustedMutation ? withTrustedMutationContext(secured, options.trustedMutation, externalMutationActions) : secured;
-  return createRecipeRunner({
+  const runner = createRecipeRunner({
     actionManifest,
     adapters: withActionProgress(
       surface.actions.wrap ? await surface.actions.wrap(mutationBound) : mutationBound,
@@ -139,6 +140,20 @@ async function createMetaMaskRunner(adapter, actionManifest, options = {}) {
       }
     }
   });
+  const clearHud = surface.actions.clearHud;
+  if (options.autoHud !== false || hudOffSwitch || !clearHud) return runner;
+  return {
+    preflight: (request) => runner.preflight(request),
+    async run(request) {
+      if (request.projectRoot) {
+        await clearHud(request.projectRoot).catch((error) => {
+          process.stderr.write(`WARN: could not clear the HUD a previous run left (${error instanceof Error ? error.message : String(error)}); this run's screenshots may show it.
+`);
+        });
+      }
+      return runner.run(request);
+    }
+  };
 }
 function withTrustedMutationContext(adapters, base, externalMutationActions) {
   let selectedIdentitySha256;

package/docs/CONTRIBUTING.md

@@ -176,9 +176,20 @@ or wrapper, verify real callers and retain compatibility only when one exists.
 yarn test:unit
 yarn test:coverage
 yarn check
+npm run build
 bash tests/contract/run.sh
 ```
 
+`run.sh` refuses to start when `dist/` is missing or older than any `src/**/*.ts`: the
+CLI would then run the TypeScript source on every start. It runs half the
+cores' worth of tests at once (`-j N` to change it), each
+in its own process group and `TMPDIR`, and prints each test's duration and the
+15 slowest. A test gets 60 s (`CONTRACT_TEST_TIMEOUT`); one whose product waits
+are longer declares `# contract: timeout=<seconds>`, and one that cannot share
+the machine (it rebuilds `dist/`) declares `# contract: serial` and runs after
+the others. Whatever a test leaves running is killed and named on a `LEAK` line.
+An unfiltered run over 3 minutes (`CONTRACT_BUDGET`) fails.
+
 Runtime changes also require real affected-platform QA and a packed installation
 test. Update `CHANGELOG.md` under `Unreleased` for user-visible behavior.
 

package/docs/QA.md

@@ -183,6 +183,7 @@ mm-harness debug
 
 ```bash
 yarn check
+npm run build
 bash tests/contract/run.sh
 ```
 

package/docs/RECIPES.md

@@ -19,6 +19,18 @@ mm-harness run <name> --describe
 Discovery reports parameters, selected adapter variant, nested recipes, source,
 and shadows. Use `--json` for exact metadata.
 
+Before ticket work, run `mm-harness run health.check`. It is read-only and
+picks the variant for the current adapter. Mobile and Extension check that the
+app answers, onboarding is done, the wallet is unlocked on a selected account
+at wallet home, and the app logged no console error since launch outside the
+console allowlists, then take one screenshot. Core reads one HyperLiquid
+testnet account through the Perps controller and requires a numeric balance.
+A failure stops at a node named after the error (`APP_NOT_RUNNING`,
+`ONBOARDING`, `WALLET_LOCKED`, `NO_SELECTED_ACCOUNT`, `NOT_ON_HOME`,
+`CONSOLE_ERRORS`, `CONTROLLER_UNAVAILABLE`, `ACCOUNT_READ_FAILED`), and that
+node's intent gives the recovery command. A reachable bridge does not prove
+the iOS app is in the foreground; check the screenshot.
+
 ## Optional recipe advisor
 
 `recipe-quality plan` assesses acceptance criteria against adapter-supported
@@ -317,7 +329,10 @@ block, skip, or refuse; a fixture that demands an empty account must converge
 rather than refuse. Extension `ensure_*` and `teardown_state` only assert, so
 converge there through an explicitly funded leaf action. Never broaden cleanup
 onto an account or market the task does not own; obtain an owned one instead
-of blocking. Mainnet is read-only.
+of blocking. On mainnet, orders follow the Perps order rule above, Core needs
+`CORE_PERPS_ALLOW_MAINNET_WRITES=1` for any write, Mobile cleanup acts on
+whatever network the app is on, and Extension refuses mainnet writes other than
+orders and `close_visible_position` in the fixture-policy lane.
 
 ### Mobile advanced-order setup
 
@@ -419,7 +434,8 @@ mm-harness run perps.performance \
   --heal off --record-video=full-run
 ```
 
-The Mobile recipe HUD is shown by default, including during performance
+The recipe HUD is shown by default on every adapter (Mobile, Extension,
+web-dapp/Terminal, headless browsers included), including during performance
 validation. Use `--hud hide` only when a specific opaque/release proof requires
 an unobstructed product surface; do not hide it merely to collect timings.
 

package/docs/cli-contract.md

@@ -101,14 +101,15 @@ Outside this boundary: a successful `launch` and the `temp/recipe/runtime/termin
 ## Running the goldens
 
 ```bash
-yarn test:goldens               # compare all families in parallel (CI runs them in the contract shards)
+npm run build                   # first: the families run the CLI from dist/, and refuse a stale one
+yarn test:goldens               # compare all families in parallel, within 2 minutes (CI runs them in the contract shards)
 yarn test:goldens mobile        # families whose name contains "mobile"
 yarn test:goldens --update      # rewrite goldens, print a per-field diff summary, drop orphans
 ```
 
-Every family checks its own golden directory: a golden no case writes fails the family, in CI too (`--update` deletes it). Every family also fails on a golden directory that has no `goldens-<dir>.test.sh`, so deleting a whole family script is caught. Families run in parallel locally and sequentially inside the contract CI shards.
+Every family checks its own golden directory: a golden no case writes fails the family, in CI too (`--update` deletes it). Every family also fails on a golden directory that has no `goldens-<dir>.test.sh`, so deleting a whole family script is caught. Families run through `tests/contract/run.sh`, locally and inside the contract CI shards, as many at once as `-j` allows (half the cores by default).
 
-Each case runs under a safety cap, `GOLDENS_CASE_TIMEOUT` (default 600 s). A case that hits it reports `TIMEOUT <case>` and fails without being compared or written, so `--update` can never accept a truncated capture.
+Families run through `tests/contract/run.sh`, so a family that hangs is stopped at its time limit, and the run fails over `GOLDENS_BUDGET` (default 120 s). Each case runs under a safety cap, `GOLDENS_CASE_TIMEOUT` (default 60 s). A case that hits it reports `TIMEOUT <case>` and fails without being compared or written, so `--update` can never accept a truncated capture.
 
 Each family is a normal contract test (`tests/contract/goldens-<family>.test.sh`). `gd_init` (`tests/contract/goldens/lib.sh`) builds a sandbox on `ct_init`, and every case runs under `env -i`:
 - `gd_init` first unsets every inherited `MM_HARNESS_*`, `RECIPE_*`, `METAMASK_*` and `FARMSLOT_*` variable, plus device and port pins (`IOS_SIMULATOR`, `ADB_SERIAL`, `WATCHER_PORT`, `METRO_PORT`, `CDP_PORT`, `IDB_PATH`, `ANDROID_HOME`, …). A developer's `MM_HARNESS_BIN` or `RECIPE_RN_IDB_PATH` export therefore cannot redirect a case;
@@ -116,12 +117,13 @@ Each family is a normal contract test (`tests/contract/goldens-<family>.test.sh`
 - every interpreter and tool the goldens launch is resolved to its real binary before `HOME` moves into the sandbox: `node` (`process.execPath`), `git` (`git --exec-path`), `bash` (`$BASH`) and `timeout`. The goldens need no Python. A tool that resolves to a script, the shape of an asdf/mise/volta/pyenv shim, fails the family up front with a message naming it. Each is checked to run with a sandboxed `HOME`;
 - `PATH` is pinned to the case stubs, the sandbox stubs, those real binaries, and `/usr/bin:/bin:/usr/sbin:/sbin`. Host tools (`idb`, `capture-helper`, a developer's Chrome) cannot change a golden;
 - device-tool discovery is pinned: `RECIPE_RN_IDB_PATH` and `RECIPE_RN_ADB_PATH` point at sandbox stubs, which discovery checks before any absolute Homebrew or pipx path;
-- localhost probes cannot reach a real server. `gd_reserve_ports` runs a Node port holder (`tests/contract/goldens/port-holder.mjs`) that holds ephemeral ports on `127.0.0.1` and `::1` and resets every connection it accepts, so Metro `/status` and CDP probes never get a response and nothing real can take the port mid-run. Each family exports the farm's slot port variables (`RECIPE_CDP_PORT`, `WATCHER_PORT`, `METRO_PORT`) set to those ports, so commands without an explicit port use them too. Goldens show them as `<PORT:NAME>`, rewritten only in port positions (`*port` keys, `:<port>`, `port <n>`/`PORT=<n>`, or a string that is exactly the port), so an unrelated equal number such as a 60000 ms timeout is never rewritten;
+- localhost probes cannot reach a real server. `gd_reserve_ports` runs a Node port holder (`tests/contract/goldens/port-holder.mjs`) that holds ephemeral ports on `127.0.0.1` and `::1` and resets every connection it accepts, so Metro `/status` and CDP probes never get a response and nothing real can take the port mid-run. Each family exports the farm's slot port variables (`RECIPE_CDP_PORT`, `WATCHER_PORT`, `METRO_PORT`) set to those ports, so commands without an explicit port use them too. Goldens show them as `<PORT:NAME>`, rewritten only in port positions (`*port` keys, numbers under a `ports` object, `:<port>`, `port <n>`/`PORT=<n>`, or a string that is exactly the port), so an unrelated equal number such as a 60000 ms timeout is never rewritten;
 - `tmux`, `xcrun` and `adb` are stubbed (`ct_init`, plus one booted simulator and one Android device for Mobile);
 - forbidden stubs record any call to `open`, `osascript`, `lsappinfo`, `screencapture`, `yarn`, `npx`, `npm`, `corepack`, `gh` and Chrome/Chromium, and the family fails if one is called. A browser stub answers only `--version`, and `npm` only `root -g` (install-source detection), with a sandbox path;
 - inert stubs on the case PATH only: `lsof`, `pgrep` and `pkill` find nothing, `ps` passes per-pid queries (`-p`, the CLI identifying its own processes) and lists an empty host for table listings, and `watchman` and `caffeinate` are no-ops. `stop` cannot see or signal a real process or touch a host daemon;
 - `RECIPE_HARNESS_BROWSER` points at the sandbox Chrome stub, so browser resolution never probe-launches Chrome for Testing or reads host Chrome policy;
-- `MM_HARNESS_MOBILE_VERIFY_PROBE_TIMEOUT_MS=2000` shortens Mobile verify's live-bridge wait (default 60 s), because no fixture provides a debug target.
+- `MM_HARNESS_MOBILE_VERIFY_PROBE_TIMEOUT_MS=2000` shortens Mobile verify's live-bridge wait (default 60 s), because no fixture provides a debug target;
+- `goldens-mobile-launch` points `METAMASK_RECIPE_MOBILE_BRIDGE_SCRIPT` at a bridge that answers "no app is running" at once (`ct_no_mobile_app`): launch clears remote feature-flag overrides through the bridge, and the real one waits out its 10 s CDP timeout when no app runs.
 
 Mobile Metro, device, bridge and wallet leaves, the Extension build/browser leaf, and the fixture-state leaf are stubbed through `MM_HARNESS_SCRIPT_BIN_*`. `leaf-calls.log` and `live-calls.log` are frozen per launch case.
 
@@ -140,7 +142,7 @@ The goldens need the harness to be a git checkout: `execution-provenance.json` `
 
 `tests/contract/goldens/normalize.mjs` is the only normaliser. It rewrites only volatile values:
 
-1. Absolute paths: the sandbox becomes `<SANDBOX>`, the repo `<REPO>`, the real `$HOME` `<HOME>`, the node binary and its prefix `<NODE>`/`<NODE_PREFIX>`, and `os.tmpdir()` `<TMP>`. Both `/var` and `/private/var` spellings are covered. Ports from `gd_reserve_ports` become `<PORT:NAME>` in port positions only: numbers under `*port` keys, and in text after `:`, `port `, `port=` or `PORT=`, or a string that is exactly the port (`^<port>$`; `60000 ms` is left alone).
+1. Absolute paths: the sandbox becomes `<SANDBOX>`, the repo `<REPO>`, the real `$HOME` `<HOME>`, the node binary and its prefix `<NODE>`/`<NODE_PREFIX>`, and `os.tmpdir()` `<TMP>`. Both `/var` and `/private/var` spellings are covered. Ports from `gd_reserve_ports` become `<PORT:NAME>` in port positions only: numbers under `*port` keys or a `ports` object (the context's `ports.cdp.value`), and in text after `:`, `port `, `port=` or `PORT=`, or a string that is exactly the port (`^<port>$`; `60000 ms` is left alone).
 2. UUIDs become `<UUID>`. Git object ids (40 hex, or a short hex value under a `*head`/`*gitRef`/`*commit` key) become `<GIT_REF>`. ISO-8601 timestamps become `<TIMESTAMP>`, and compact stamps in names `<STAMP>`. Path-derived slot ids `local-<adapter>-<8 hex>` become `local-<adapter>-<HASH>`.
 3. The package version becomes `<HARNESS_VERSION>`. Any other `x.y.z` under a key ending in `version` becomes `<VERSION>`.
 4. Numbers under volatile keys: `*pid` becomes `<PID>`, `inode` `<INODE>`, `*port` `<PORT>`, `*At`/`*Time`/`*timestamp`/`mtime*` `<TIMESTAMP>`, and `*Ms`/`duration*`/`elapsed*` `<DURATION>`. Values inside `schema` and `examples` subtrees (static manifest content) are never rewritten.

package/library/actions/core/perps/_controller.mjs

@@ -229,8 +229,8 @@ let cached = null;
 /**
  * Resolve the requested network. Default testnet; mainnet only when a node
  * explicitly sets network: "mainnet". Mainnet reads are safe; mainnet mutations
- * use REAL funds and must be explicitly requested — mirrors the extension/mobile
- * "mainnet is read-only unless explicitly requested" contract.
+ * use REAL funds and must be explicitly requested (see the Perps order rule in
+ * docs/RECIPES.md).
  */
 export function resolveNetwork(input) {
   const raw = String(input.node?.network ?? 'testnet').toLowerCase();

package/library/actions/extension/app/assert_no_console_errors.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+// Fail the recipe when MetaMask (its service worker or UI pages) logged an
+// error or uncaught exception that no console allowlist marks as known noise.
+// Reads extension-console.log, written by the slot's console collector
+// (adapters/extension/console-tail.mjs). The same classifier and allowlist
+// feed run diagnostics.
+//
+// Window: since "launch" (the default) judges the events since the launch
+// began, by their own timestamps. The harness records each launch's start
+// before it (re)starts the browser (extension-console.launch.json,
+// written by src/adapters/extension/console-capture.ts): the log's offset
+// and inode, and the time. The collector appends across launches, so
+// the log is read from that offset; and a collector replaced on a launch that
+// keeps the browser replays the browser's console from before it, so a record
+// stamped (with the event's own CDP timestamp) before the launch time is left
+// out too. Without a mark the action fails instead of reading earlier
+// sessions. since "start-of-log" reads the whole file.
+//
+// It never passes on missing evidence: this runtime's collector must be
+// running on the run's CDP port, and a control line logged in MetaMask's
+// service worker or page must reach extension-console.log; otherwise the
+// action fails as unavailable.
+
+import { readFileSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+
+import { recipeRuntimePath } from '@farmslot/recipe-cli/harness';
+
+import { captureUnavailable, consoleLevels, inWindow, judgeConsole, nodeAllowlist, readFrom, readLaunchMark, reportVerdict, throwOnFindings } from '../../shared/console-assert.mjs';
+import { collectorOwnerMarker, collectorStatus, verifyCapture } from '../../shared/console-collector.mjs';
+import { runAdapter } from '../platform/cdp.mjs';
+
+const LOG = 'extension-console.log';
+const LAUNCH_MARK = 'extension-console.launch.json';
+const unavailable = (detail) => captureUnavailable(detail, 'The MetaMask extension console');
+
+// A file's content, or null when it does not exist.
+function readOptional(file) {
+  try {
+    return readFileSync(file, 'utf8');
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+export async function assertNoConsoleErrors(input, env = process.env, deps = {}) {
+  const node = input.node ?? {};
+  const projectRoot = input.context?.projectRoot;
+  const levels = consoleLevels(node);
+  const log = recipeRuntimePath(projectRoot, LOG);
+  // The CDP port as every Extension live action resolves it.
+  const cdpPort = node.cdp_port ?? env.CDP_PORT ?? env.RECIPE_CDP_PORT;
+  if (!cdpPort) throw unavailable('no CDP port (node.cdp_port, CDP_PORT or RECIPE_CDP_PORT)');
+  const capture = (deps.collectorStatus ?? collectorStatus)({
+    pidFile: recipeRuntimePath(projectRoot, 'console-tail.pid'),
+    extensionLog: log,
+    marker: collectorOwnerMarker(recipeRuntimePath(projectRoot)),
+    cdpPort: String(cdpPort),
+  });
+  if (!capture.ok) throw unavailable(capture.detail);
+  const extensionId = readOptional(recipeRuntimePath(projectRoot, 'extension.id'))?.trim() || null;
+  const control = await (deps.verifyCapture ?? verifyCapture)({
+    cdpPort,
+    log,
+    target: 'extension',
+    extensionId,
+    ...(node.timeout_ms ? { timeoutMs: Number(node.timeout_ms) } : {}),
+  });
+  if (!control.ok) throw unavailable(control.detail);
+  const mark = node.since === 'start-of-log' ? null : readLaunchMark(recipeRuntimePath(projectRoot, LAUNCH_MARK), unavailable);
+  const { text, reset } = readFrom(log, mark ?? { offset: 0 });
+  const allowlist = nodeAllowlist(node, env);
+  const keep = inWindow({ sinceMs: mark?.launchedAtMs ?? null, now: deps.now ?? Date.now() });
+  const { findings, allowlisted } = judgeConsole([text], { levels, allowlist, keep });
+  const output = {
+    action: input.action,
+    since: node.since ?? 'launch',
+    levels: [...levels],
+    findings,
+    allowlisted,
+    allowlistProblems: allowlist.problems,
+    capture: { collector: capture.detail, control: control.detail },
+    // The launch mark was past the end of a replaced (rotated) capture
+    // file; that file was read from its start.
+    offsetReset: reset,
+    proofPath: 'extension-console-capture',
+  };
+  throwOnFindings(findings, allowlist.problems);
+  return output;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  reportVerdict(() => runAdapter((input) => assertNoConsoleErrors(input)));
+}