@deeeed/metamask-harness 0.83.0 → 0.84.0

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 ## Unreleased
 
+## 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/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/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;
+  }
+}

package/adapters/web-dapp/metamask-signer.mjs

@@ -0,0 +1,212 @@
+// metamask-signer.mjs — MetaMask as web-dapp's extension signer, and the
+// identity the injected strict wallet presents.
+//
+// Purpose:
+//   @farmslot/adapter-web/web-dapp runs the slot browser and wallet host; this
+//   module is the signer module it loads (RECIPE_WEB_DAPP_SIGNER_MODULE or
+//   --signer-module). signer=extension loads the slot's copy of the MetaMask
+//   extension and imports the fixture account through the Extension adapter's
+//   fixture flow (wallet-fixture-state.cjs generate → prefill-profile →
+//   seed-cdp); the wallet host then logs every MetaMask confirmation it sees
+//   open. signer=injected presents the strict test wallet as MetaMask, so the
+//   app connects to it the way it connects to the extension.
+//
+// Inputs: env TERMINAL_EXTENSION_DIR (the MetaMask dist, default
+//   <checkout>/temp/metamask-extension/chrome), TERMINAL_EXTENSION_CHECKOUT (an
+//   installed metamask-extension checkout at the dist commit),
+//   TERMINAL_EXTENSION_NODE (that checkout's node; else asdf's install for its .nvmrc).
+// Outputs: the `signers` hooks; per-slot key files in the runtime dir, which the
+//   launcher removes when the launch ends.
+// Never prints: mnemonics, private keys, the wallet password.
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { fixtureEntry, readinessCheck } from '../../library/actions/web-dapp/platform/adapter-web-lib.mjs';
+
+const HARNESS_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+const FIXTURE_STATE_SCRIPT = path.join(HARNESS_ROOT, 'adapters/extension/wallet-fixture-state.cjs');
+// adapter-web's LAUNCH_SERVICES launch method, named as the launch leaf names it.
+const LAUNCH_SERVICES = 'launch-services';
+
+function extensionDirFor(target, env) {
+  return path.resolve(env.TERMINAL_EXTENSION_DIR || path.join(target, 'temp/metamask-extension/chrome'));
+}
+
+// Node of the extension checkout (its native modules, e.g. classic-level, are
+// built for that ABI): TERMINAL_EXTENSION_NODE, else asdf's install for .nvmrc.
+export function resolveExtensionNode(checkout, env = process.env) {
+  if (env.TERMINAL_EXTENSION_NODE) return env.TERMINAL_EXTENSION_NODE;
+  const nvmrc = path.join(checkout, '.nvmrc');
+  if (existsSync(nvmrc)) {
+    const wanted = readFileSync(nvmrc, 'utf8').trim().replace(/^v/u, '');
+    const root = path.join(os.homedir(), '.asdf/installs/nodejs');
+    if (existsSync(root)) {
+      const match = readdirSync(root)
+        .filter((version) => version === wanted || version.startsWith(`${wanted}.`))
+        .sort((a, b) => b.localeCompare(a, undefined, { numeric: true }))[0];
+      if (match) return path.join(root, match, 'bin/node');
+    }
+  }
+  return process.execPath;
+}
+
+// The Extension vault needs a mnemonic keyring, so a privateKey account is
+// imported beside the fixture's first mnemonic account and selected.
+export function slotWalletFixture(fixture, accountName) {
+  const entry = fixtureEntry(fixture, accountName);
+  const accounts = [];
+  if (entry.type === 'privateKey') {
+    const primary = fixture.accounts.find((account) => account?.type === 'mnemonic');
+    if (!primary) throw new Error(`fixture has no mnemonic account to host the imported key ${accountName}.`);
+    accounts.push({ ...primary, count: 1, names: [primary.name] });
+    accounts.push(entry);
+  } else {
+    accounts.push({ ...entry, count: 1, names: [entry.name] });
+  }
+  return { password: fixture.password, settings: fixture.settings ?? {}, accounts, selectedAccount: accountName };
+}
+
+function runFixtureState(node, phase, flags) {
+  return execFileSync(node, [FIXTURE_STATE_SCRIPT, phase, ...flags], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: 240000,
+  });
+}
+
+async function extensionIdFor(withBrowserClient, idFile) {
+  if (existsSync(idFile)) return readFileSync(idFile, 'utf8').trim();
+  return withBrowserClient(async (client) => {
+    const deadline = Date.now() + 30000;
+    while (Date.now() < deadline) {
+      const { targetInfos } = await client.send('Target.getTargets');
+      const worker = targetInfos.find((info) => info.type === 'service_worker' && info.url.startsWith('chrome-extension://'));
+      if (worker) return new URL(worker.url).host;
+      await new Promise((resolve) => setTimeout(resolve, 250));
+    }
+    throw new Error('the MetaMask service worker did not start');
+  });
+}
+
+// MetaMask shows dapp requests in its side panel (the fixture default) or a
+// notification/popup window; only request routes count as confirmations.
+const WALLET_SURFACES = ['sidepanel.html', 'notification.html', 'popup.html'];
+const CONFIRMATION_ROUTE = /^\/(connect|confirm-transaction|confirmation|confirm|signature-request)(\/|$)/u;
+
+export const signers = {
+  injected: {
+    identity: {
+      info: {
+        uuid: '5d1e5b4e-e2e0-4c3f-9a1d-000000000001',
+        name: 'MetaMask (strict test wallet)',
+        icon: "data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg'/>",
+        rdns: 'io.metamask',
+      },
+      isMetaMask: true,
+    },
+  },
+
+  extension: {
+    async prepareProfile({ target, runtime, profile, account, fixture, env, freshProfile, log, writePrivateFile, trackSecret }) {
+      const extensionDir = extensionDirFor(target, env);
+      const checkout = env.TERMINAL_EXTENSION_CHECKOUT ? path.resolve(env.TERMINAL_EXTENSION_CHECKOUT) : null;
+      if (!existsSync(path.join(extensionDir, 'manifest.json'))) {
+        throw new Error(`MetaMask extension dist not found at ${extensionDir}.\nNext: copy a built dist/chrome there or set TERMINAL_EXTENSION_DIR.`);
+      }
+      if (!checkout || !existsSync(path.join(checkout, 'node_modules'))) {
+        throw new Error('signer=extension needs TERMINAL_EXTENSION_CHECKOUT: an installed metamask-extension checkout at the dist commit (fixture state generation).');
+      }
+      const manifest = JSON.parse(readFileSync(path.join(extensionDir, 'manifest.json'), 'utf8'));
+      const node = resolveExtensionNode(checkout, env);
+      // Key material (the slot fixture) and the encrypted vault (fixture state).
+      const slotFixture = trackSecret(path.join(runtime, `wallet-fixture.${account}.json`));
+      const fixtureState = trackSecret(path.join(runtime, `fixture-state.${account}.json`));
+      writePrivateFile(slotFixture, JSON.stringify(slotWalletFixture(fixture, account)));
+      const idFile = path.join(runtime, 'extension.id');
+      runFixtureState(node, 'generate', ['--target', checkout, '--fixture', slotFixture, '--out', fixtureState]);
+      if (freshProfile) {
+        runFixtureState(node, 'prefill-profile', ['--target', checkout, '--state', fixtureState, '--profile', profile, '--extension-dir', extensionDir, '--extension-id-file', idFile]);
+        log(`prefilled extension profile for ${account}`);
+      }
+      return {
+        browserArgs: [
+          '--disable-features=ExtensionContentVerification,DisableLoadExtensionCommandLineSwitch',
+          '--disable-extensions-file-access-check',
+          `--disable-extensions-except=${extensionDir}`,
+          `--load-extension=${extensionDir}`,
+        ],
+        secrets: [],
+        // browser.json's `extension`; the id is filled in once the extension runs.
+        state: { id: undefined, version: manifest.version, dir: extensionDir, checkout },
+        async afterBrowserStart({ cdpPort, launchMethod, withBrowserClient, openBackgroundWindow }) {
+          if (launchMethod === LAUNCH_SERVICES) {
+            // The seed reuses an open MetaMask page; without one it would open a
+            // tab in the foreground and activate the browser.
+            const extensionId = await extensionIdFor(withBrowserClient, idFile);
+            await openBackgroundWindow(`chrome-extension://${extensionId}/home.html`);
+          }
+          runFixtureState(node, 'seed-cdp', [
+            '--target', checkout,
+            '--fixture', slotFixture,
+            '--state', fixtureState,
+            '--cdp-port', String(cdpPort),
+            '--extension-dir', extensionDir,
+            '--extension-id-file', idFile,
+            '--out', path.join(runtime, `seed-report.${account}.json`),
+          ]);
+          const id = readFileSync(idFile, 'utf8').trim();
+          log(`extension ${id} seeded and unlocked for ${account}`);
+          return { state: { id }, hostArgs: ['--extension-id', id] };
+        },
+      };
+    },
+
+    confirm({ args, appendEntry, say, focus }) {
+      const extensionOrigin = args['extension-id'] ? `chrome-extension://${args['extension-id']}` : null;
+      const seenConfirmationUrls = new Map();
+      const isWalletSurfaceUrl = (url) =>
+        Boolean(extensionOrigin) && WALLET_SURFACES.some((surface) => url.startsWith(`${extensionOrigin}/${surface}`));
+      const confirmationRoute = (url) => {
+        const route = (url.split('#')[1] ?? '').split('?')[0];
+        return CONFIRMATION_ROUTE.test(route) ? route.replace(/0x[0-9a-fA-F]{40}/gu, '<address>') : null;
+      };
+      return {
+        isWalletSurfaceUrl,
+        observe(targetId, url) {
+          if (!isWalletSurfaceUrl(url)) return;
+          if (focus && !url.includes('/sidepanel.html') && !seenConfirmationUrls.has(targetId)) {
+            setTimeout(() => focus.observe(url.includes('/popup.html') ? 'popup' : 'notification', 'MetaMask'), 1000);
+          }
+          const route = confirmationRoute(url);
+          if (!route || seenConfirmationUrls.get(targetId) === route) return;
+          seenConfirmationUrls.set(targetId, route);
+          const surface = WALLET_SURFACES.find((name) => url.includes(name))?.replace('.html', '');
+          appendEntry({ kind: 'confirmation-shown', t: Date.now(), surface, route });
+          say(`confirmation shown in ${surface}: ${route}`);
+        },
+      };
+    },
+
+    async readinessChecks({ target, env, required }) {
+      const checks = [];
+      const extensionDir = extensionDirFor(target, env);
+      const manifestPath = path.join(extensionDir, 'manifest.json');
+      if (existsSync(manifestPath)) {
+        const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        checks.push(readinessCheck('metamask-extension', true, `MetaMask ${manifest.version} at ${extensionDir}`, { required }));
+      } else {
+        checks.push(readinessCheck('metamask-extension', false, `no extension dist at ${extensionDir}`, { required }));
+      }
+      const checkout = env.TERMINAL_EXTENSION_CHECKOUT;
+      const checkoutOk = Boolean(checkout) && existsSync(path.join(checkout, 'node_modules/@metamask/browser-passworder'));
+      checks.push(readinessCheck('extension-fixture-tooling', checkoutOk, checkoutOk
+        ? `extension checkout ${checkout} has fixture-state dependencies`
+        : 'TERMINAL_EXTENSION_CHECKOUT unset or not installed (needed to import the wallet into the extension)', { required }));
+      return checks;
+    },
+  },
+};

package/dist/adapters/extension/run.js

@@ -9,6 +9,7 @@ import {
   verifyExtensionConsoleControl
 } from "./console-capture.js";
 import { emitProofFailure } from "../proof-failure.js";
+import { refuseLockedSession } from "../session-lock.js";
 import { launchedBrowser } from "./launched-browser.js";
 const AUTOLAUNCH_ENV = "METAMASK_RECIPE_EXTENSION_AUTOLAUNCH";
 const extensionRun = {
@@ -39,8 +40,9 @@ const extensionRun = {
     });
   },
   // The proof runtime is checked on the run's own ports (the engine's scope).
-  runtimeCheck({ target, heal, state, json, onRecovery }) {
-    return () => ensureExtensionProofRuntime(target, heal, state, json, { onRecovery });
+  // The Extension browser is always headful: a locked session refuses first.
+  runtimeCheck({ target, options, heal, state, json, onRecovery }) {
+    return async () => refuseLockedSession(json, options) ?? ensureExtensionProofRuntime(target, heal, state, json, { onRecovery });
   },
   launchedBrowser: (target, artifactsDir, cdpPort) => launchedBrowser(target, artifactsDir, cdpPort),
   browserProvenance: (browser) => ({