@deeeed/metamask-harness 0.83.0 → 0.85.0

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

@@ -67,9 +67,11 @@ in the registry, so a platform registered the same way is reached by the
 commands that take `--adapter` with no edit to shared code
 (`tests/fixtures/example-adapter.ts`); `status` detects the adapter from the
 checkout.
-The CLI contract (`src/command-contract.ts`) still lists the four built-ins for
-`--adapter`, so a new platform reaches `bin/mm-harness` once a plugin loader
-registers it and extends that list.
+The public command table (`src/command-contract.ts`) reads the `--adapter`
+choices when a command is validated: the registered adapters, then the adapters
+the libraries on `RECIPE_LIBRARY_PATH` and the command's `--library` entries
+declare. A new platform or library plugin reaches `bin/mm-harness` with no edit
+to the table.
 
 Extend `AdapterSurface` when a platform owns the behavior; members a platform
 does not need are optional, and Core reports headless/N/A explicitly. Put each
@@ -82,7 +84,7 @@ command-local platform ladders for surface-owned behavior:
 - `run`/`call` come from `@farmslot/recipe-cli/harness` and read `run`,
   `recording`, `diagnostics`, `observation` and `sourceFingerprint`;
   mm-harness hands them its engine (`src/engine.ts`) and its device targeting
-  and plan steps (`src/cli.ts`);
+  and plan steps (`src/mm-harness-cli.ts`);
 - the runner reads `actions` (manifest, bundled semantic actions, live adapter
   scripts, `cdp.target`, the `ui.*` transport, adapter wrappers, input checks);
 - `install`/`verify`/`cleanup` read `harness`, `agentic-runtime.json` reads
@@ -177,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

@@ -94,21 +94,21 @@ These are real farm bugs. The goldens freeze the current rejections, so fixing e
 
 `goldens-terminal` freezes the `va-mmcx-terminal-farm` hooks with their exact argv (`recipe_action_manifest`, `recipe_doctor`, `recipe_harness_{install,verify,cleanup}`, `recipe_run`, the browser `boot`/`shutdown` resources and `teardown`), against a fresh fixture slot: no slot dev server, no Extension dist, and the farm's wallet fixture outside the slot, so `install` copies it in. `launch` is frozen on its cold path: it refuses at the missing dist before any browser starts. The slot's CDP port is the one port no port holder reserves: a farm slot with no browser has it free, and the Terminal's port checks probe it.
 
-`terminal` is the plugin the `experimental-metamask-recipe-terminal` library declares (`adapters.terminal`, extends the built-in `web-dapp`), so the family loads it: set `GOLDENS_TERMINAL_LIBRARY` to a checkout of that library, which the family copies into its sandbox and puts on `RECIPE_LIBRARY_PATH`. CI has no access to the private library and skips the family (`CI` set); local runs need the variable, and without it outside CI the family fails. A release gate must set it too (proposed for the release checklist). `goldens-discovery` covers the built-in `web-dapp` in its per-adapter loop.
+`terminal` is the plugin the `experimental-metamask-recipe-terminal` library declares (`adapters.terminal`, extends the built-in `web-dapp`), so the family loads it: set `GOLDENS_TERMINAL_LIBRARY` to a checkout of that library. The family copies one pinned commit of it (`GOLDENS_TERMINAL_LIBRARY_REV` in `goldens-terminal.test.sh`) into its sandbox with `git archive` and puts it on `RECIPE_LIBRARY_PATH`, so the goldens don't move when the checkout does. The checkout must contain that commit (`git fetch`); moving the pin and regenerating the goldens is one change. CI has no access to the private library and skips the family (`CI` set); local runs need the variable, and without it outside CI the family fails. A release gate must set it too (proposed for the release checklist). `goldens-discovery` covers the built-in `web-dapp` in its per-adapter loop.
 
 Outside this boundary: a successful `launch` and the `temp/recipe/runtime/terminal/` layout (`browser.pid`), the library's recipes, `run terminal.perps.<name> --plan`, and the recipe-terminal `console-guard.mjs` import paths.
 
 ## 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/docs/feature-guard.md

@@ -74,7 +74,7 @@ Captures are normalized (paths, versions, pids, timestamps, durations, epoch num
 
 What the normaliser deliberately masks, and so cannot catch: any semver under a key ending in `version` other than the harness's own, numbers under keys ending in `Ms`/`Seconds`/`duration`/`elapsed` (so a changed timeout value), epoch-millisecond numbers, and the `volatile` paths (a new product warning during a live run). Each varies run to run on real slots; the goldens freeze the static values.
 
-Machine rules: on macwork, headless only and no focus stealing (`TERMINAL_HEADLESS=1` is in the matrix). Headful runs and the Extension wallet popup fail while macwork's screen is locked (`Page.captureScreenshot` timeout). Mobile and the Extension run on free macpro or mini slots, never mini-mm-3. The differential stops and cleans the slot runtime it used; reinstall the farm's overlay afterwards if the slot is handed back to the farm.
+Machine rules: on macwork, headless only and no focus stealing (`TERMINAL_HEADLESS=1` is in the matrix). A headful `run`/`call` (Extension, including its wallet popup, or a headful web-dapp) can't proceed while macwork's screen is locked: it refuses with `SESSION_LOCKED` at its runtime check (it used to stall until a `Page.captureScreenshot` timeout). Mobile and the Extension run on free macpro or mini slots, never mini-mm-3. The differential stops and cleans the slot runtime it used; reinstall the farm's overlay afterwards if the slot is handed back to the farm.
 
 ## 3. Release smoke
 

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)));
+}