@deeeed/metamask-harness 0.83.0 → 0.85.0

package/CHANGELOG.md

@@ -2,6 +2,68 @@
 
 ## Unreleased
 
+## 0.85.0 - 2026-10-09
+
+### Added
+
+- `health.check` recipes for Mobile, Extension and Core: a read-only readiness check to run before ticket work. A failed precondition stops at a node named after its error (for example `WALLET_LOCKED`, `NOT_ON_HOME` or, on Mobile and Extension, `CONSOLE_ERRORS`), whose intent gives the recovery command. `mm-harness help` lists it under the target step.
+- `metamask.app.assert_no_console_errors` on Mobile and Extension, as on `web-dapp`: it fails on a console error or exception that no console allowlist covers, judging the events since the launch began by their own timestamps, and fails as unavailable unless the capture is proven (the slot's console forwarder or collector is running and a control line logged in the app or MetaMask reaches the log). `launch` records when it starts, and console lines replayed from before then (by an app runtime or browser the launch kept) are left out. Mobile reads `app-console.log`, which every launch now restarts empty along with the forwarder's replay cursor, and judges only the device the bridge selects; Extension reads `extension-console.log` from the offset `launch` records, and its collector now stamps each line with the event's own time (UTC, with milliseconds). Known app noise is accepted only when it also appears on the app's unchanged base build: the bundled library ships `diagnostics/console-allowlist.json` (the Extension unlock page's `UNSAFE_componentWillMount` warning), read ahead of other libraries' by these actions and by run diagnostics, and the classifier carries pattern rules for base-reproduced errors one exact entry cannot cover: Mobile's SES lockdown intrinsic reports and its notifications startup failure (`createOnChainTriggers`), whose message carries the bundle line; Extension's `getBearerToken` while locked (MetaMask/metamask-extension#46688) and the Money query adapter's `mutations` TypeError (TAT-4063), whose stacks name build-specific chunks. Allowlist entries can name the `app` source Mobile lines carry, and Mobile console lines match without the forwarder's time and device prefix.
+
+### Changed
+
+- **BREAKING:** `run --hud` takes `show` or `hide`, default `show`. `auto` is gone: the CLI refuses it as an invalid choice (`--hud must be show or hide; received 'auto'.`); drop the flag to get the default. The recipe HUD, each node's intent, now draws on every adapter that implements `app.hud`, headless browsers included. A headless web-dapp (Terminal) browser gets it where `auto` skipped it; Mobile and Extension already drew it by default. A Mobile release artifact still runs without it, since it has no dev bridge to draw with. `METAMASK_RECIPE_AUTO_HUD=0` stays the internal off switch for self-test, verify and the test sandboxes, and `--hud show` wins over it.
+- **BREAKING:** web-dapp `ui.screenshot` keeps the HUD in the capture (it hid it while capturing), so Terminal screenshot evidence shows the node's intent as Mobile and Extension evidence does. `--hud hide` is the way to a HUD-free screenshot.
+- A `surface=wallet` web-dapp `ui.screenshot` (the MetaMask confirmation window or side panel) shows the running node's intent too: the HUD is a bar docked to that MetaMask page's bottom edge for the capture only, which reserves its own height so the request and the footer buttons move up rather than being covered (pointer-events none), and is removed after it.
+- A run with the HUD off (`--hud hide`, a `call`, an untrusted source) first clears the HUD an earlier run left on the slot, so its screenshots never show a previous recipe's intent: web-dapp deletes `hud.json` (the wallet host redraws from it) and the drawn HUD on the app tabs; Extension removes the runner HUD from its pages. Nothing is launched to do it, `METAMASK_RECIPE_AUTO_HUD=0` skips it, and a failed clear prints one `WARN:` line on stderr.
+- Inside a checkout, every command resolves its adapter, target and slot once, through recipe-cli's context resolver, so `status`, `doctor`, `run` and the rest need no `--adapter`. The order is: flag, then the checkout's runtime binding, then its slot, then a unique detect match among the built-ins and the operator's library plugins (matched by their declared `detect`, before any plugin code loads).
+  - A checkout that more than one adapter matches stops with `ADAPTER_AMBIGUOUS` (exit 2) and lists the candidates. With no match, a command keeps its "could not detect the MetaMask repo type" error.
+  - `status`, `doctor`, `run`, `call` and discovery (`actions`, `run --list`/`--describe`, `call --list`) carry `context` in their `--json` envelopes (each value and its source), as does a command's own `USAGE` error once its context has resolved. Grammar refusals (raised before resolution), the task view (`status --task`/`--watch`) and the other commands' envelopes, `launch` on every adapter included, are unchanged. Human output adds one `context:` line on stderr when the adapter was not given by a flag.
+  - Terminal detection needs a recipe-terminal library that declares `detect` (recipe-terminal #8, 8a44aee); with an older library, pass `--adapter terminal`.
+  - `status` accepts `--adapter` and `--platform` (it refused them with `CLI_UNKNOWN_OPTION`).
+  - The slot comes from mm-harness's own pool resolution (the configured Farmslot root, else the nearest Farmslot checkout's `pool/`) unless `FARMSLOT_POOL_DIR` or `FARMSLOT_ROOT` names one, so a slot checkout beside a Farmslot checkout resolves its slot, and its ports fill `--cdp-port`/`--watcher-port`, with no env.
+  - Commands no longer detect the adapter themselves: status, doctor, check, provision, prepare, help, task init, `verify`'s overlay, debug, logs, fixtures, review and domain all read the resolved one. `check` still refuses `--platform ios|android`.
+  - `review` and `domain` scope to the resolved adapter when review covers it (mobile, extension, core, terminal), else run unscoped. Only an explicit `--adapter` that names another adapter is refused.
+- Depend on `@farmslot/recipe-cli` 0.11.0 and `@farmslot/adapter-sdk` 0.8.0 (were 0.10.0 and 0.7.1) for the context resolver (deeeed/farmslot#864), on `@farmslot/recipe-runner` 0.28.0, `@farmslot/protocol` 0.35.0 and `@farmslot/agent-runtime` 0.17.1 (were 0.27.0, 0.34.0 and 0.17.0), and on `@farmslot/adapter-web` 0.6.4, `@farmslot/adapter-rn` 0.19.3 and `@farmslot/adapter-node` 0.1.6 (were 0.6.2, 0.19.1 and 0.1.4). With them, a web-dapp launch stops waiting for CDP when its browser dies (deeeed/farmslot#865). The install holds one `@farmslot/adapter-sdk` and one `@farmslot/recipe-runner`.
+- Help lists the selectable adapters (the registered ones, then those the operator's libraries and the invocation's `--library` entries declare) wherever it names `--adapter` or `--platform`, instead of a fixed `mobile|extension|core|terminal`.
+- **BREAKING:** Mobile `verify` takes `--watcher-port` (the public `verify` grammar accepted it; the Mobile leaf refused it) and reads `RECIPE_WATCHER_PORT`: the Metro port is `--watcher-port`, then `RECIPE_WATCHER_PORT`, then `WATCHER_PORT`, then the slot's `.js.env`. With no port env set, a checkout the slot pool maps gets the pool slot's port through `WATCHER_PORT`, so that port now wins over the checkout's `.js.env` `WATCHER_PORT`.
+- **BREAKING:** A `RECIPE_RUNTIME_CONTEXT` that belongs to another checkout no longer sets the Extension slot's ports (`CDP_PORT`, `WATCHER_PORT`, `SLOT_ID`), Extension `verify`'s `RECIPE_SLOT_ID` and `RECIPE_HARNESS_EXTENSION_ID` (it reads the checkout's own context instead), or the Mobile provision slot (simulator, slot id). It counts when its `repoRoot` is the checkout's Git top level (so a clone nested inside another checkout never takes that checkout's context), or, without a `repoRoot`, when the file sits inside the checkout: the rule recipe-cli applies to the runtime binding. A context outside every checkout that names no `repoRoot` used to be authoritative; an orchestrator that keeps the file elsewhere sets `repoRoot`.
+- Contributors: `bash tests/contract/run.sh` runs half the cores' worth of tests at once (`-j N`), each in its own process group, `TMPDIR` and output file, and prints each test's duration and the 15 slowest. A test gets 60 s (`CONTRACT_TEST_TIMEOUT`, or `# contract: timeout=<s>` in its header) and fails as `timed out`; what it leaves running is killed and named on a `LEAK` line; a test that rebuilds `dist/` declares `# contract: serial`. An unfiltered run over `CONTRACT_BUDGET` (180 s) fails, and a stopped run first lets each running test clean up (its EXIT trap reaps the leaves its CLI detached), then kills every process group left in the test's tree. A process a test leaves behind can no longer stall the run.
+- Contributors: `yarn test:goldens` runs its families through `run.sh` and fails over `GOLDENS_BUDGET` (120 s); a golden case gets 60 s (`GOLDENS_CASE_TIMEOUT`, was 600 s). Docs: CONTRIBUTING and cli-contract describe both.
+- Contributors: `AGENTS.md` has a `## Test speed` section: the default and CI suite must take 5 minutes or less (the contract and goldens runs check their own budgets; build and unit are not checked), and a new or changed test uses no fixed waits of 1 s or more, moves to `tests/live/` when it takes over 5 s (a golden case over 30 s), tears down every background process, and never rebuilds `dist/` under concurrent readers.
+- Site: the platform map (`site/platform.html`) is a static page instead of the zoomable canvas. It shows the five layers (Libraries, MetaMask preset, Adapters, CLI, Engine) with their packages, one `mm-harness run` traced through them, and who changes what. It renders from `file://` (no `fetch`), so `site/assets/platform.json` is removed.
+
+### Fixed
+
+- Extension reopen (`adapters/extension/ensure-browser.sh`) no longer builds its `node -e` script or its `python3` profile cleanup from the slot id, checkout, runtime, profile, extension and runner paths, CDP port, webpack pid or wallet fixture path. The scripts are fixed text and get those values as argv. Before, a checkout path with an apostrophe (`/tmp/Arthur's checkout`) broke the reopen script's syntax and silently skipped the profile cleanup, and a crafted value could change the code the reopen ran.
+
+## 0.84.0 - 2026-10-08
+
+### Changed
+
+- `mm-harness` is the MetaMask preset over `@farmslot/recipe-cli`'s `createHarnessCli`: the CLI program, help, the strict command grammar, library hydration, adapter loading and dispatch come from recipe-cli; mm-harness supplies its commands, handlers and help text. Apart from the removals under Removed and the `--json-stream` refusal change below, every command, flag, help text and JSON envelope is unchanged.
+  - `mm-harness --version` (and `-v`) still prints only the harness version. `mm-harness --version --verbose` adds a second line, `@farmslot/recipe-cli <version>`, the recipe-cli it runs on, and `doctor --json` reports it as `runner.recipeCliVersion`.
+  - `src/command-contract.ts` holds the one public command table (`PUBLIC_COMMANDS`: name, aliases, summary, example, help text, grammar) and `HIDDEN_COMMANDS`; `src/cli.ts` is gone.
+  - `mm-harness --help -- --help` prints the grouped help (it printed an older usage text), and a failure inside `update`, `pin`, `help`, `tutorial`, `setup-base`, `completions` or `call <action> --help` prints its message and exits with its code instead of a stack trace.
+- Docs: the site's tutorial template snapshots (`site/assets/template-examples.json`) are regenerated from the recipe-cook templates at Consensys/skills b115bd2, which pass `call` inputs as bare `key=value` (`call app.lifecycle command=restart`) now that `call --arg` is refused.
+- Docs: the README's Operate section and the feature-guard machine rules say a headful run, call or web-dapp launch on a locked macOS session refuses with `SESSION_LOCKED` (and how to proceed).
+- `run` and `call` apply `--runtime-dir` before the slot resolves, as `doctor` does: the slot context, the checkout lock and the run's runtime state come from that directory. The flag was accepted and ignored.
+- `call` never loads a funded mutation from its command line (it never accepted the `--funding-*` flags); funded mutations run through `run`.
+- Depend on `@farmslot/recipe-cli` 0.10.0 and `@farmslot/adapter-sdk` 0.7.1 (were 0.8.0 and 0.6.0): `createHarnessCli`'s `afterAdapterLoad` and `explainInvalidChoice` hooks (deeeed/farmslot#846), which the preset uses for the web-dapp policy fence and the missing Terminal library, one `--watcher-port` (#806) and key=value-only `call` inputs (#808). Also `@farmslot/recipe-runner` 0.27.0, `@farmslot/adapter-web` 0.6.2, `@farmslot/adapter-rn` 0.19.1 and `@farmslot/adapter-node` 0.1.4 (were 0.26.0, 0.4.1, 0.18.0 and 0.1.2). `@farmslot/agent-runtime` 0.17.0 and `@farmslot/protocol` 0.34.0 are unchanged, and the install holds one `@farmslot/adapter-sdk` and one `@farmslot/recipe-runner`. With them, `launch` prints its setup stage on stderr (a line at least every 15 s, and a no-progress notice after 60 s); `run`, `run --plan` and `call` refuse `--record-video` on an adapter without recording before anything runs (`RECORDING_UNSUPPORTED`, exit 2); and `run` lists evidence an action produced through a fallback provider (`fallbacks` in `--json` and the `--json-stream` completion, a marked line in human output).
+- Under `--json-stream`, a refused adapter plugin (a loader or venue-policy refusal) prints NDJSON on stdout, an `error` event then `complete` with `status: fail`, where 0.83.0 printed the human line on stderr. Human and `--json` output and the exit code (2) are unchanged.
+- `call` writes its artifacts by `run`'s rule: inside a task (`RECIPE_TASK_DIR`/`FARMSLOT_TASK_DIR`) under `<task>/artifacts/calls/<action>-<uuid>`, else `temp/recipe/calls/<action>-<uuid>`; `--artifacts-dir` still wins.
+- The built-in `web-dapp` is adapter-web's `createWebDappAdapter` (`@farmslot/adapter-web/web-dapp`): the slot browser, wallet host, venue policy and its fence, readiness and the launch, verify, stop, inject and cleanup leaves moved there. MetaMask is its extension signer (`adapters/web-dapp/metamask-signer.mjs`: dist and fixture import, seeding, confirmation surfaces, the two readiness checks, and the MetaMask identity of the injected wallet), loaded by every web-dapp process through `RECIPE_WEB_DAPP_SIGNER_MODULE`. The launch, verify, stop, install and cleanup flags and runtime files are unchanged.
+
+### Removed
+
+- **BREAKING:** the web-dapp leaf scripts (`adapters/web-dapp/{launch,verify,stop,inject,cleanup,wallet-host}.mjs`) and `adapters/web-dapp/lib/*` (policy, policy fence, readiness, processes, display, HUD, CDP client, blocked hosts) are no longer in the package. They live in `@farmslot/adapter-web/web-dapp`: use its `webDappPolicy` (same name; `POLICY_VERSION` is no longer exported, and the loader enforces the version) and `createWebDappAdapter`. `mm-harness launch|verify|stop` for web-dapp targets are unchanged. recipe-terminal's own `checks/terminal-policy.test.mjs` imports the old path before its #7 (d3a98d2).
+- **BREAKING:** `--metro-port` is gone from `run`, `call`, `doctor`, `launch` and `verify`; pass `--watcher-port`. The CLI answers `--metro-port` with `Did you mean '--watcher-port'`. `doctor`'s `metroPort` runtime-context row reads `mirrors watcherPort`.
+- **BREAKING:** `call` no longer takes `--arg k=v`; pass action inputs as `key=value` (the documented form, which carries every value `--arg` did, leading `-`/`--` included). The CLI answers `--arg` with `Did you mean 'key=value'`. The Mobile stale-source next step is `mm-harness call app.lifecycle command=restart …`.
+
+### Fixed
+
+- Unattended Extension and web-dapp (Terminal) runs on a Mac whose login session is locked fail fast with `SESSION_LOCKED` instead of hanging until a screenshot or unlock timeout. macOS stops painting windows while the session is locked; the probe reads the on-console session's `CGSSessionScreenIsLocked` from `ioreg` (bounded to 3 s). `run` and `call` refuse before they launch or drive a headful browser (exit 3; the Extension always, web-dapp unless its running slot browser, or else `TERMINAL_HEADLESS`, is headless; a saved `browser.json` counts only while its browser process is alive and this slot's), and `run --json-stream` carries `SESSION_LOCKED` as an `error` event ahead of `RUN_PREPARE_FAILED`. The web-dapp launcher refuses to start or reuse a headful browser on a locked session (`SESSION_LOCKED: …` in the launch error), so a recipe launch step can't start one either. The Extension health check reports a stalled compositor as `SESSION_LOCKED` rather than `UI_COMPOSITOR_SUSPENDED` when the session is locked. The next step says to unlock the Mac; caffeinate keeps it awake but does not unlock it. Nothing changes when the session is unlocked, off macOS, or when the lock state can't be read.
+- Extension validation now stops a CDP listener that is this slot's own Chrome when no runtime identity proves it (for example after a reload loses CDP): a single Chrome listener whose `--user-data-dir` resolves, by real path, inside the checkout's recipe runtime dir gets the same TERM-then-KILL as an identity-proven one, after its command line is re-read just before the kill. Any other listener (a profile outside the checkout, a non-Chrome process, several listeners, or a command line whose `--user-data-dir` can't be parsed unambiguously) is still refused, and the refusal now names each pid and the `--user-data-dir` it saw, with the next step: stop that pid if it is this slot's browser, or free the port.
+
 ## 0.83.0 - 2026-10-07
 
 ### Added

package/README.md

@@ -113,6 +113,13 @@ Extension `launch` keeps its incremental watcher running. Refresh the active
 page after a successful rebuild; use `launch --build` only for an explicit
 production-like LavaMoat rebuild.
 
+macOS stops painting visible windows while the login session is locked. On a locked Mac:
+
+- a headful Extension or web-dapp (Terminal) `run`/`call` refuses with `SESSION_LOCKED` at its runtime check, before it launches or drives the browser, instead of stalling on screenshots and UI actions;
+- a headful web-dapp launch, including reuse of a running browser, refuses the same way.
+
+The Extension has no headless mode, so unlock the Mac. For the web-dapp, unlock, or relaunch its browser headless (`mm-harness launch --adapter terminal --headless`, or set `TERMINAL_HEADLESS=1` before launching): `TERMINAL_HEADLESS=1` alone doesn't help while a headful slot browser is still running. caffeinate keeps a Mac awake but does not unlock it.
+
 ### Extension browser
 
 `RECIPE_HARNESS_BROWSER` picks the browser that hosts the unpacked extension:
@@ -259,7 +266,7 @@ how `prepare --remote-flag` keeps its pin through the fixtures step.
 
 ```bash
 mm-harness call metamask.feature_flags.read
-mm-harness call metamask.feature_flags.set --arg 'flags={"perpsEnabled":true}'   # mobile
+mm-harness call metamask.feature_flags.set 'flags={"perpsEnabled":true}'   # mobile
 mm-harness call metamask.feature_flags.clear                                      # mobile
 ```
 

package/adapters/extension/console-tail.mjs

@@ -90,10 +90,14 @@ function out(event, destination = null) {
   }
 }
 
-function stamp() {
-  const d = new Date();
-  const p = (n) => String(n).padStart(2, '0');
-  return `${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`;
+// A record's time: the UTC time of day of the event's own timestamp (CDP
+// Runtime.Timestamp, ms since the epoch), as the Mobile console forwarder
+// writes it, or of the write when the event carries none. Events the browser
+// replays when a collector attaches keep their own time, so
+// metamask.app.assert_no_console_errors can leave out those from before a
+// launch.
+function stamp(timestamp) {
+  return new Date(Number.isFinite(timestamp) ? timestamp : Date.now()).toISOString().slice(11, 23);
 }
 
 function shortLabel(target) {
@@ -160,7 +164,7 @@ function emitConsole(label, params, destination) {
   const level = String(params.type || 'log').toUpperCase();
   const text = (params.args || []).map(previewArg).join(' ');
   const [first, ...rest] = text.split('\n');
-  out(`${stamp()} [${label}] ${level}  ${first}${atSuffix(frameText(params.stackTrace?.callFrames?.[0]))}${rest.length ? `\n${rest.join('\n')}` : ''}`, destination);
+  out(`${stamp(params.timestamp)} [${label}] ${level}  ${first}${atSuffix(frameText(params.stackTrace?.callFrames?.[0]))}${rest.length ? `\n${rest.join('\n')}` : ''}`, destination);
 }
 
 function emitException(label, params, destination) {
@@ -172,7 +176,7 @@ function emitException(label, params, destination) {
     'uncaught exception';
   const frame = frameText(d.stackTrace?.callFrames?.[0]) || frameText({ url: d.url, lineNumber: d.lineNumber, columnNumber: d.columnNumber });
   const [first, ...rest] = String(text).split('\n');
-  out(`${stamp()} [${label}] EXCEPTION  ${first}${atSuffix(frame)}${rest.length ? `\n${rest.join('\n')}` : ''}`, destination);
+  out(`${stamp(params.timestamp)} [${label}] EXCEPTION  ${first}${atSuffix(frame)}${rest.length ? `\n${rest.join('\n')}` : ''}`, destination);
 }
 
 // Browser log entries (network failures, interventions, deprecations) are
@@ -186,7 +190,7 @@ function emitLogEntry(label, params, destination) {
   // A Log entry's location is its URL as is: a line number appended to a URL
   // could not be told apart from the URL's own text.
   const where = e.url ? e.url : frameText(e.stackTrace?.callFrames?.[0]);
-  out(`${stamp()} [${label}] [browser:${source}] ${level}  ${e.text || ''}${atSuffix(where)}`, destination);
+  out(`${stamp(e.timestamp)} [${label}] [browser:${source}] ${level}  ${e.text || ''}${atSuffix(where)}`, destination);
 }
 
 function handleMessage(label, destination, data) {

package/adapters/extension/ensure-browser.sh

@@ -235,9 +235,10 @@ echo "[cleanup] Reusing profile ${PROFILE}"
 # shutdowns; --load-extension re-advertises the path but does not flip it back,
 # leaving MV3 service workers inert).
 if [ -f "${PROFILE}/Default/Preferences" ]; then
-  python3 -c "
+  python3 - "${PROFILE}/Default/Preferences" 2>/dev/null <<'PY' && echo "[cleanup] Cleared crash recovery state + re-enabled extensions"
 import json
-pf = '${PROFILE}/Default/Preferences'
+import sys
+pf = sys.argv[1]
 prefs = json.load(open(pf))
 prefs['profile'] = prefs.get('profile', {})
 prefs['profile']['exit_type'] = 'Normal'
@@ -248,7 +249,7 @@ for ext_id, ext_prefs in ext_settings.items():
         ext_prefs['state'] = 1
         ext_prefs.pop('disable_reasons', None)
 json.dump(prefs, open(pf, 'w'))
-" 2>/dev/null && echo "[cleanup] Cleared crash recovery state + re-enabled extensions"
+PY
 fi
 
 # Readiness gate: wait until webpack emits a loadable background entry before
@@ -289,10 +290,13 @@ echo "[reopen] ${SLOT_ID} — CDP:${CDP_PORT:-off}"
 cd "${REPO}"
 
 trap - EXIT
-exec node -e "
+# The reopen script is fixed text; paths, ids and ports reach it as argv, never as source.
+IFS= read -r -d '' REOPEN_SCRIPT <<'NODE' || true
+const [SCRIPT_DIR, SLOT_ID, AGENT_DIR, EXTENSION, REPO, RUNNER_BIN, PROFILE, cdpPortArg, webpackPidArg, WALLET_FIXTURE] =
+  process.argv.slice(1);
 const path = require('path');
 const fs = require('fs');
-const adapterWeb = (name) => require('module').createRequire(path.join('${SCRIPT_DIR}', 'package.json'))('@farmslot/adapter-web/' + name);
+const adapterWeb = (name) => require('module').createRequire(path.join(SCRIPT_DIR, 'package.json'))('@farmslot/adapter-web/' + name);
 const http = require('http');
 const { execFileSync } = require('child_process');
 let chromium; try { chromium = require('@playwright/test').chromium; } catch { chromium = require('playwright').chromium; }
@@ -318,15 +322,9 @@ const {
   resolveBrowser,
 } = adapterWeb('browser-resolver');
 
-const SLOT_ID = '${SLOT_ID}';
-const AGENT_DIR = '${AGENT_DIR}';
-const EXTENSION = '${EXTENSION}';
-const REPO = '${REPO}';
-const RUNNER_BIN = '${RUNNER_BIN}';
-const PROFILE = '${PROFILE}';
-const CDP_PORT = '${CDP_PORT}' || null;
-const WEBPACK_PID = '${WEBPACK_PID}' || null;
-const walletFixture = JSON.parse(fs.readFileSync('${WALLET_FIXTURE}', 'utf8'));
+const CDP_PORT = cdpPortArg || null;
+const WEBPACK_PID = webpackPidArg || null;
+const walletFixture = JSON.parse(fs.readFileSync(WALLET_FIXTURE, 'utf8'));
 const PASSWORD = walletFixture.password;
 
 if (!PASSWORD) {
@@ -522,8 +520,8 @@ const releaseFocusHold = () => {
   await evaluatePageViaCdp(page, applyPersistentSlotTitle, { slotId: SLOT_ID, defaultTitle: 'MetaMask' });
 
   // Wait for runtime state to settle, then unlock if needed.
-  const unlockSelector = '[data-testid=\"unlock-password\"]';
-  const homeSelector = '[data-testid=\"account-menu-icon\"]';
+  const unlockSelector = '[data-testid="unlock-password"]';
+  const homeSelector = '[data-testid="account-menu-icon"]';
   let detectedState = 'unknown';
   for (let i = 0; i < 15; i++) {
     if (await page.locator(homeSelector).count()) {
@@ -544,7 +542,7 @@ const releaseFocusHold = () => {
   if (detectedState === 'locked') {
     console.log('[reopen] Unlocking wallet...');
     await page.fill(unlockSelector, PASSWORD);
-    await page.click('[data-testid=\"unlock-submit\"]');
+    await page.click('[data-testid="unlock-submit"]');
     await page.waitForSelector(homeSelector, { timeout: 30000 });
     console.log('[reopen] Unlocked');
   } else if (detectedState === 'onboarding') {
@@ -611,4 +609,5 @@ const releaseFocusHold = () => {
   console.error(e);
   process.exit(1);
 });
-"
+NODE
+exec node -e "$REOPEN_SCRIPT" "$SCRIPT_DIR" "$SLOT_ID" "$AGENT_DIR" "$EXTENSION" "$REPO" "$RUNNER_BIN" "$PROFILE" "$CDP_PORT" "$WEBPACK_PID" "$WALLET_FIXTURE"

package/adapters/manifest.json

@@ -498,6 +498,14 @@
       "inputs": "ESM import; env RECIPE_HARNESS_ROOT optional override",
       "outputs": "recipeHarnessRoot() relative path string"
     },
+    {
+      "id": "lib/session-lock",
+      "entry": "adapters/shared/session-lock.mjs",
+      "kind": "lib",
+      "purpose": "Bounded macOS locked-session probe (ioreg CGSSessionScreenIsLocked) and the SESSION_LOCKED wording, shared by the run/call preflight and the Extension health check.",
+      "inputs": "ESM import from src/adapters/session-lock.ts or src/adapters/extension/runtime.ts",
+      "outputs": "macosSessionLocked() true/false/null; parseSessionLocked(); SESSION_LOCKED_MESSAGE and SESSION_LOCKED_USER_ACTION"
+    },
     {
       "id": "lib/resolve-slot-ports-sh",
       "entry": "adapters/shared/resolve-slot-ports.sh",
@@ -592,122 +600,18 @@
       "outputs": "numbered checkouts, saved preferences, and run summary"
     },
     {
-      "id": "web-dapp/launch",
-      "entry": "adapters/web-dapp/launch.mjs",
-      "kind": "node",
-      "purpose": "Start or reuse the web-dapp slot browser (Chrome for Testing unless TERMINAL_CHROME_BIN; MetaMask extension with the fixture imported, or the injected strict wallet) and its wallet host. On macOS the browser starts through LaunchServices with no startup window; in testnet mode the hosts the venue policy blocks are unresolvable for the whole browser.",
-      "inputs": "--target --cdp-port --app-port [--signer extension|injected] [--account] [--fresh-profile] [--headless|--headful] [--slow-mo] [--network mainnet --mainnet-confirmation REAL_FUNDS] [--json]; env TERMINAL_CHROME_BIN, TERMINAL_EXTENSION_DIR, TERMINAL_EXTENSION_CHECKOUT, RECIPE_WALLET_FIXTURE, TERMINAL_HEADLESS, TERMINAL_SLOW_MO, TERMINAL_WINDOW, TERMINAL_SCREEN",
-      "outputs": "<runtime>/<adapter id>/browser.json + pid/log files; JSON on stdout; exit 0/1/2"
-    },
-    {
-      "id": "web-dapp/wallet-host",
-      "entry": "adapters/web-dapp/wallet-host.mjs",
-      "kind": "node",
-      "purpose": "Long-running CDP observer: opens the app tab blank, hooks it once per target, navigates it to the app and verifies the log binding before ready; logs every wallet request from the app top frame and every MetaMask confirmation shown; answers the injected strict wallet in injected mode (other frames and blank popups get 4100). The page script, the frame judgement and the strict wallet are @farmslot/adapter-web/dapp's; the venue policy (RECIPE_WEB_DAPP_POLICY) gives the testnet refusal, hosts, probe and start page.",
-      "inputs": "--cdp-port --runtime-dir --signer --app-origin [--extension-id] [--target --account --start-chain] [--browser-app <.app>]",
-      "outputs": "<runtime>/<adapter id>/wallet-requests.jsonl, wallet-host.ready"
-    },
-    {
-      "id": "web-dapp/stop",
-      "entry": "adapters/web-dapp/stop.mjs",
-      "kind": "node",
-      "purpose": "Stop the web-dapp slot browser, wallet host and console collector and prove the CDP port is free.",
-      "inputs": "--target [--cdp-port]",
-      "outputs": "JSON on stdout; exit 0/1"
-    },
-    {
-      "id": "web-dapp/inject",
-      "entry": "adapters/web-dapp/inject.mjs",
-      "kind": "node",
-      "purpose": "web-dapp install: overlay marker, runtime dir and wallet fixture (0600); refuses a checkout the venue policy does not match; no product writes.",
-      "inputs": "--target [--fixture] [--force]; env RECIPE_WALLET_FIXTURE",
-      "outputs": "<harness>/<adapter id>/install.json, <runtime>/wallet-fixture.json; exit 0/1"
-    },
-    {
-      "id": "web-dapp/cleanup",
-      "entry": "adapters/web-dapp/cleanup.mjs",
-      "kind": "node",
-      "purpose": "web-dapp cleanup: stop browser/host, remove the slot's runtime state, overlay marker and installed fixture; profiles kept unless --reset-profile.",
-      "inputs": "--target [--cdp-port] [--reset-profile]",
-      "outputs": "JSON on stdout; exit 0/1"
-    },
-    {
-      "id": "web-dapp/verify",
-      "entry": "adapters/web-dapp/verify.mjs",
-      "kind": "node",
-      "purpose": "Read-only web-dapp slot readiness: checkout, deps, dev server, forced testnet, fixture, browser start probe, extension copy, CDP port.",
-      "inputs": "--target [--cdp-port] [--watcher-port] [--signer] [--account] [--json]",
-      "outputs": "readiness report; exit 0 ready / 1 not ready"
-    },
-    {
-      "id": "web-dapp/lib-cdp-client",
-      "entry": "adapters/web-dapp/lib/cdp-client.mjs",
-      "kind": "lib",
-      "purpose": "Browser-level CDP client with flattened target sessions for the wallet host.",
-      "inputs": "CdpClient.connect(url)",
-      "outputs": "send/on"
-    },
-    {
-      "id": "web-dapp/lib-processes",
-      "entry": "adapters/web-dapp/lib/processes.mjs",
-      "kind": "lib",
-      "purpose": "Pid-file process stop with owner-marker checks (--mm-harness-owner=<kind>-<id>, exact token; live foreign pids kept and reported, dead ones dropped), process-group termination, CDP port release check.",
-      "inputs": "stopWebDappBrowser(target, { cdpPort }), stopConsoleCollector(target), ownerMarker(kind, runtimeDir), ownsProcess(kind, pid, runtimeDir)",
-      "outputs": "stopped processes"
-    },
-    {
-      "id": "web-dapp/lib-readiness",
-      "entry": "adapters/web-dapp/lib/readiness.mjs",
-      "kind": "lib",
-      "purpose": "web-dapp slot readiness checks shared by verify, doctor and the surface.",
-      "inputs": "webDappReadiness({ policy, target, appPort, cdpPort, signer }), assertLaunchNetwork(target, { network, mainnetConfirmation }), devServerTestnetDiagnostic(target, { appPort, variable }) (advisory)",
-      "outputs": "checks[]"
-    },
-    {
-      "id": "web-dapp/lib-display",
-      "entry": "adapters/web-dapp/lib/display.mjs",
-      "kind": "lib",
-      "purpose": "Headless/headful and slow-mo resolution, per-slot window placement and the profile zoom that keeps the desktop layout.",
-      "inputs": "resolveHeadless, resolveSlowMo, windowPlacement, writeProfileZoom",
-      "outputs": "browser display args"
-    },
-    {
-      "id": "web-dapp/lib-hud",
-      "entry": "adapters/web-dapp/lib/hud.mjs",
-      "kind": "lib",
-      "purpose": "Recipe HUD state (<runtime>/hud.json) and the page expression that draws it on the app origin only.",
-      "inputs": "nextHudState, hudRenderExpression",
-      "outputs": "HUD state, expression source"
-    },
-    {
-      "id": "web-dapp/lib-blocked-hosts",
-      "entry": "adapters/web-dapp/lib/blocked-hosts.mjs",
-      "kind": "lib",
-      "purpose": "Testnet enforcement mechanics: the host-resolver rule that makes the policy's blocked hosts unresolvable, and the canonical host check the wallet host's request block uses.",
-      "inputs": "hostResolverRules(hosts), hostOf(url), isBlockedUrl(url, hosts)",
-      "outputs": "launch switch, booleans"
-    },
-    {
-      "id": "web-dapp/lib-policy",
-      "entry": "adapters/web-dapp/lib/policy.mjs",
-      "kind": "lib",
-      "purpose": "The venue policy of the adapter that extends web-dapp (e.g. the Terminal plugin's), loaded from the module RECIPE_WEB_DAPP_POLICY names; the host sets it when it binds that adapter.",
-      "inputs": "env RECIPE_WEB_DAPP_POLICY",
-      "outputs": "webDappPolicy(), webDappAdapterId()"
-    },
-    {
-      "id": "web-dapp/lib-policy-fence",
-      "entry": "adapters/web-dapp/lib/policy-fence.mjs",
+      "id": "web-dapp/metamask-signer",
+      "entry": "adapters/web-dapp/metamask-signer.mjs",
       "kind": "lib",
-      "purpose": "Checks the venue policy a plugin binds: the policy and every file it imports must be files the plugin digest covers (its module's directory or the library's actions/), imported by literal relative path or as node built-ins. Records their digest in RECIPE_WEB_DAPP_POLICY_DIGEST; a process loading the policy refuses files that changed since.",
-      "inputs": "policy path, plugin library root and module; env RECIPE_WEB_DAPP_POLICY_DIGEST",
-      "outputs": "fencePolicy(), assertPolicyDigest(), PolicyFenceError"
+      "purpose": "MetaMask as @farmslot/adapter-web web-dapp's extension signer (load the slot's MetaMask dist, import the fixture account through wallet-fixture-state.cjs generate, prefill-profile and seed-cdp, judge MetaMask's confirmation surfaces, readiness checks for the dist and fixture tooling) and the MetaMask identity the injected strict wallet presents.",
+      "inputs": "loaded by the web-dapp leaves through RECIPE_WEB_DAPP_SIGNER_MODULE or --signer-module; env TERMINAL_EXTENSION_DIR, TERMINAL_EXTENSION_CHECKOUT, TERMINAL_EXTENSION_NODE",
+      "outputs": "signers.extension (prepareProfile, confirm, readinessChecks) and signers.injected.identity"
     },
     {
       "id": "web-dapp/surface",
       "entry": "src/adapters/web-dapp/surface.ts",
       "kind": "module",
-      "purpose": "The web-dapp adapter surface (runtime status, browser stop, logs, hints) and bindWebDappPolicy, which binds the venue policy of the adapter that extends it.",
+      "purpose": "The web-dapp adapter: @farmslot/adapter-web's createWebDappAdapter with the MetaMask signer module, the web-dapp action set, console capture, the locked-session preflight and observation, plus the MetaMask-only surface members; bindWebDappPolicy binds the venue policy and the signer module of the adapter that extends it.",
       "inputs": "webDappSurface",
       "outputs": "AdapterSurface"
     }

package/adapters/mobile/start-console-forwarder.sh

@@ -72,7 +72,15 @@ if [ -f "$PID_FILE" ]; then
   rm -f "$PID_FILE"
 fi
 
+# Each launch starts a fresh log. The replay cursor goes with it: it marks
+# lines as written that are no longer in the file, such as the relaunched
+# app's first lines the previous forwarder wrote, so the new forwarder replays
+# the app runtime's console buffer into the new log instead of skipping them.
+# A runtime the launch kept replays lines from before the launch too;
+# metamask.app.assert_no_console_errors leaves those out by their own time
+# against the mark each launch attempt records (app-console.launch.json).
 : > "$APP_LOG_FILE"
+rm -f "$APP_LOG_FILE.forwarder-state.json"
 pid="$(node "$SCRIPT_DIR/launch-console-forwarder.cjs" \
   --port "$PORT" \
   --out "$APP_LOG_FILE" \

package/adapters/shared/resolve-slot-ports-core.mjs

@@ -198,15 +198,57 @@ function mergeKvLayers(...layers) {
   return Object.keys(result).length ? formatKvLines(result) : '';
 }
 
+// Whether a runtime context belongs to the checkout at `repo` (recipe-cli's
+// binding rule): its repoRoot is the checkout's Git top level, so a clone
+// nested inside another checkout never takes that checkout's context; without
+// a repoRoot, the file sits inside that top level. An orchestrator may keep the
+// file elsewhere as long as it names the checkout. Twin of recipe-cli's
+// runtimeContextOwned: this module stays dependency-free for the shell paths
+// that load it, so the rule is repeated here rather than imported.
+export function ownsRuntimeContext(file, repo) {
+  let repoRoot;
+  try {
+    const value = JSON.parse(fs.readFileSync(file, 'utf8'));
+    repoRoot = typeof value?.repoRoot === 'string' ? value.repoRoot : undefined;
+  } catch {
+    return false;
+  }
+  if (repoRoot === undefined) return within(gitTopLevel(repo), file);
+  try {
+    return fs.realpathSync(repoRoot) === fs.realpathSync(gitTopLevel(repo));
+  } catch {
+    // A path that does not exist owns nothing.
+    return false;
+  }
+}
+
+function gitTopLevel(dir) {
+  try {
+    return execFileSync('git', ['-C', dir, 'rev-parse', '--show-toplevel'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    // Not a Git checkout: the directory is its own root.
+    return dir;
+  }
+}
+
+function within(outer, inner) {
+  try {
+    const relative = path.relative(fs.realpathSync(outer), fs.realpathSync(inner));
+    return !(relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative));
+  } catch {
+    // A path that does not exist owns nothing.
+    return false;
+  }
+}
+
 function extensionRuntimeContextPath(repo) {
   const repoRoot = path.resolve(repo);
   const envCtx = process.env.RECIPE_RUNTIME_CONTEXT;
-  if (envCtx) {
-    // Farmslot may manage runtime context outside the checkout. Treat the
-    // explicit environment override as authoritative; containment is not a
-    // security boundary and silently dropping it selects the wrong port.
-    return path.resolve(envCtx);
-  }
+  // Another checkout's context would set this checkout's ports.
+  if (envCtx && ownsRuntimeContext(path.resolve(envCtx), repoRoot)) return path.resolve(envCtx);
   return path.join(repoRoot, recipeRuntimeDir(), 'agentic-runtime.json');
 }
 

package/adapters/shared/session-lock.mjs

@@ -0,0 +1,43 @@
+// Whether the macOS login session is locked. macOS stops painting visible
+// windows while it is, so a headful browser's screenshots, video and UI actions
+// stall until their own timeouts. The run/call preflight (src/adapters/
+// session-lock.ts) and the web-dapp launcher refuse up front instead.
+
+import { spawnSync } from 'node:child_process';
+
+export const SESSION_LOCKED_MESSAGE =
+  "The macOS login session is locked, so the headful browser can't paint (screenshots, video and UI actions stall).";
+export const SESSION_LOCKED_USER_ACTION =
+  'Unlock the Mac and keep its login session unlocked while the run drives the browser, then rerun. ' +
+  'caffeinate keeps the Mac awake but does not unlock it.';
+
+const LOCKED = /<key>CGSSessionScreenIsLocked<\/key>\s*<true\/>/u;
+const ON_CONSOLE = /<key>kCGSSessionOnConsoleKey<\/key>\s*<true\/>/u;
+
+// `ioreg -n Root -d1 -a` output: the lock flag of the on-console session in
+// IOConsoleUsers (any session's when none is on console); false for a plist
+// without it, null for anything else.
+export function parseSessionLocked(output) {
+  if (!/<plist[\s>]/u.test(output)) return null;
+  const users = /<key>IOConsoleUsers<\/key>\s*<array>([\s\S]*?)<\/array>/u.exec(output)?.[1] ?? '';
+  const onConsole = users.match(/<dict>[\s\S]*?<\/dict>/gu)?.find((session) => ON_CONSOLE.test(session));
+  return LOCKED.test(onConsole ?? output);
+}
+
+// true or false on macOS; null when unknown (another platform, or ioreg failed
+// or took longer than 3 s). Never throws.
+export function macosSessionLocked() {
+  if (process.platform !== 'darwin') return null;
+  try {
+    const result = spawnSync('ioreg', ['-n', 'Root', '-d1', '-a'], {
+      encoding: 'utf8',
+      timeout: 3_000,
+      maxBuffer: 8 * 1024 * 1024,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    if (result.error || result.status !== 0) return null;
+    return parseSessionLocked(result.stdout);
+  } catch {
+    return null;
+  }
+}