@deeeed/metamask-harness 0.84.0 → 0.85.0

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";
@@ -234,7 +234,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 +242,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

@@ -179,6 +179,14 @@ yarn check
 bash tests/contract/run.sh
 ```
 
+`run.sh` 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/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
@@ -419,7 +431,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,14 @@ 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)
+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 +116,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 +141,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/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)));
+}

package/library/actions/extension/platform/cdp.mjs

@@ -76,6 +76,32 @@ export function extensionTarget(targets, extensionId = null, cdpTargetId = null)
   return home ?? sidepanel ?? null;
 }
 
+// The recipe-runner HUD (app.hud's clear) removed from every extension page on
+// the slot's CDP port. Launches nothing; each step is bounded and a missing
+// port or browser clears nothing.
+const CLEAR_HUD_EXPRESSION = "(() => { const hud = document.getElementById('farmslot-recipe-hud'); hud?.remove(); document.getElementById('farmslot-recipe-hud-reserved-space')?.remove(); document.documentElement.style.removeProperty('--farmslot-recipe-hud-height'); document.body?.style.removeProperty('padding-bottom'); return Boolean(hud); })()";
+
+export async function clearExtensionHud(env = process.env, timeoutMs = 2000) {
+  const port = Number(env.CDP_PORT ?? env.RECIPE_CDP_PORT);
+  if (!Number.isInteger(port) || port <= 0) return { cleared: 0 };
+  const response = await fetch(`http://127.0.0.1:${port}/json/list`, { signal: AbortSignal.timeout(timeoutMs) }).catch(() => null);
+  const targets = response?.ok ? await response.json().catch(() => []) : [];
+  let cleared = 0;
+  for (const target of Array.isArray(targets) ? targets : []) {
+    if (target?.type !== 'page' || !String(target.url ?? '').startsWith('chrome-extension://') || !target.webSocketDebuggerUrl) continue;
+    let session;
+    try {
+      session = await CdpSession.connect(target.webSocketDebuggerUrl, { timeoutMs });
+      const result = await session.call('Runtime.evaluate', { expression: CLEAR_HUD_EXPRESSION, returnByValue: true }, { timeoutMs });
+      if (result?.result?.value === true) cleared += 1;
+    } catch {
+      // A busy or closing page keeps nothing worth failing the run for.
+    } finally {
+      session?.close();
+    }
+  }
+  return { cleared };
+}
 
 function resolveRelativeArtifactPath(artifactsDir, relPath) {
   const relative = relPath || 'screenshots/extension-page.png';

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

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+// Fail the recipe when the app logged an error or uncaught exception that no
+// console allowlist marks as known noise. Reads app-console.log, written by the
+// adapter-rn console forwarder (adapters/mobile/start-console-forwarder.sh).
+// The same classifier and allowlist feed run diagnostics.
+//
+// Window: since "launch" (the default) judges the events since the launch
+// began, by their own timestamps. A launch records its start once its
+// refusals are behind it and before anything can restart the app
+// (app-console.launch.json, recordMobileConsoleLaunch in
+// src/adapters/mobile/launch.ts); a recovery attempt that restarts the app
+// records it again. Stamps come from the device's clock, so the window is
+// moved onto it by the offset the capture control line shows. Every launch
+// restarts the forwarder, and start-console-forwarder.sh empties
+// app-console.log and the forwarder's replay cursor as it does, so a
+// relaunched app's first lines are kept; but on a launch that keeps the app
+// runtime, the new forwarder replays that runtime's console from before the
+// launch. The forwarder stamps each line with the event's own runtime time,
+// so a record stamped before the launch is left out. Without a mark the
+// action fails as unavailable. since "start-of-log" reads the whole file.
+//
+// Device: app-console.log holds every device the forwarder sees; only the
+// device the control line came back from (the one the bridge selects for this
+// run) is judged. When that line names no device, every device is, and the
+// output says so (devices: "all").
+//
+// It never passes on missing evidence: the forwarder named by
+// console-forwarder.pid must be alive and writing this checkout's
+// app-console.log, and a control line logged inside the app through the debug
+// bridge must reach that file; otherwise the action fails as unavailable. The
+// opaque runtime (an installed release build) has no bridge, so it always
+// fails as unavailable.
+
+import { randomUUID } from 'node:crypto';
+import { existsSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { recipeRuntimeDir } from '@farmslot/recipe-cli/harness';
+
+import { captureUnavailable, consoleLevels, inWindow, nearestInstant, judgeConsole, nodeAllowlist, readFrom, readLaunchMark, reportVerdict, throwOnFindings } from '../../shared/console-assert.mjs';
+import { CAPTURE_CONTROL_MARK, controlLineReached, fileSize, processCommand, readPid } from '../../shared/console-collector.mjs';
+import { consoleRecords, recordStamp } from '../../shared/console-findings.mjs';
+import { evalSync, runAdapter } from '../platform/bridge.mjs';
+
+const LOG = 'app-console.log';
+const LAUNCH_MARK = 'app-console.launch.json';
+const unavailable = (detail) => captureUnavailable(detail, 'The app console');
+
+// The forwarder start-console-forwarder.sh started for this checkout: a live
+// process running console-forwarder.cjs whose --out is this runtime's
+// app-console.log, as the script writes it (the checkout's resolved path).
+export function forwarderStatus({ pidFile, log }) {
+  const pid = readPid(pidFile);
+  if (!pid) return { ok: false, detail: `no console forwarder pid in ${pidFile}` };
+  const command = processCommand(pid);
+  if (!command) return { ok: false, detail: `console forwarder pid ${pid} is not running` };
+  if (!/\/console-forwarder\.cjs --port \S+ --out /u.test(command) || !command.endsWith(` --out ${log}`)) {
+    return { ok: false, detail: `pid ${pid} is not this checkout's console forwarder` };
+  }
+  return { ok: true, detail: `console forwarder pid ${pid}` };
+}
+
+// Log a control line inside the app; the forwarder writes it at info level,
+// and the classifier never reports a capture control line anyway.
+function logInApp(input, line) {
+  return evalSync(input, `(console.info(${JSON.stringify(line)}), true)`);
+}
+
+export async function assertNoConsoleErrors(input, env = process.env, deps = {}) {
+  const node = input.node ?? {};
+  const levels = consoleLevels(node);
+  if (env.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME === '1') {
+    throw unavailable('the opaque runtime has no debug bridge to log a control line through');
+  }
+  const projectRoot = input.context?.projectRoot;
+  if (!projectRoot || !existsSync(projectRoot)) throw unavailable(`no checkout at ${projectRoot}`);
+  const runtime = path.join(realpathSync(projectRoot), recipeRuntimeDir());
+  const log = path.join(runtime, LOG);
+  const forwarder = (deps.forwarderStatus ?? forwarderStatus)({ pidFile: path.join(runtime, 'console-forwarder.pid'), log });
+  if (!forwarder.ok) throw unavailable(forwarder.detail);
+  const mark = node.since === 'start-of-log' ? null : readLaunchMark(path.join(runtime, LAUNCH_MARK), unavailable);
+  const nonce = randomUUID();
+  const start = fileSize(log);
+  const clock = deps.clock ?? (() => deps.now ?? Date.now());
+  const before = clock();
+  try {
+    await (deps.logInApp ?? logInApp)(input, `${CAPTURE_CONTROL_MARK} ${nonce}`);
+  } catch (error) {
+    // No line logged: the capture is unproven, which is this action's failure.
+    throw unavailable(`could not log the capture control line in the app (${error.message})`);
+  }
+  const after = clock();
+  const timeoutMs = Number(node.timeout_ms) > 0 ? Number(node.timeout_ms) : 8000;
+  if (!await controlLineReached(log, start, nonce, timeoutMs)) {
+    throw unavailable(`the capture control line logged in the app did not reach ${log} within ${timeoutMs}ms`);
+  }
+  const { text } = readFrom(log, { offset: 0 });
+  // The control line names the device, and its stamp, from the device's clock,
+  // bounds that clock's offset from this machine's (a physical device's clock
+  // can run minutes off; the simulator shares the host's). The line was
+  // logged between `before` and `after` on the host, so bridge latency only
+  // widens the bound; it never moves the launch past a fresh record.
+  const control = consoleRecords(text).find((record) => record.line.includes(nonce));
+  const controlStamp = control ? recordStamp(control) : null;
+  const device = controlStamp?.device ?? null;
+  const controlAt = controlStamp ? nearestInstant(controlStamp.clock, before) : null;
+  const offset = controlAt === null ? { min: 0, max: 0 } : { min: controlAt - after, max: controlAt - before };
+  const allowlist = nodeAllowlist(node, env);
+  const keep = inWindow({ sinceMs: mark?.launchedAtMs ?? null, device, now: clock(), offset });
+  const { findings, allowlisted } = judgeConsole([text], { levels, allowlist, keep });
+  const output = {
+    action: input.action,
+    since: node.since ?? 'launch',
+    devices: device ?? 'all',
+    levels: [...levels],
+    findings,
+    allowlisted,
+    allowlistProblems: allowlist.problems,
+    capture: { forwarder: forwarder.detail, control: `control line from the app reached ${LOG}` },
+    proofPath: 'mobile-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)));
+}