@deeeed/metamask-harness 0.70.0 → 0.71.0

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 ## Unreleased
 
+## 0.71.0 - 2026-10-02
+
+### Added
+
+- `terminal` adapter for the MetaMask Web Terminal (Next.js site): `mm-harness launch|doctor|verify|install|cleanup|stop|run --adapter terminal` drive a per-slot Chrome for Testing on `--cdp-port` against the slot dev server on `--watcher-port`. `signer=extension` loads a MetaMask build with the fixture account imported; `signer=injected` is a strict EIP-1193 test wallet that rejects typed data for another chain. A wallet host logs every wallet request (method, EIP-712 primary type, chain, outcome; never params or signatures) and every MetaMask confirmation shown.
+- Terminal actions: `metamask.app.launch`, venue-backed `metamask.perps.read_positions|read_orders|read_snapshot|assert_positions|assert_orders`, testnet `metamask.perps.teardown_state` and `metamask.perps.revoke_agent` (signed in Node by the fixture account; mainnet only with `mainnet_confirmation=REAL_FUNDS`), `metamask.wallet.read_signatures|assert_signatures|list_accounts`, and `ui.*` with `surface: app|wallet` to drive the MetaMask side panel / notification.
+- Terminal browser is visible by default, one window per slot side by side on the main screen (odd CDP port left, even right; `TERMINAL_WINDOW` / `TERMINAL_SCREEN` override) with a profile zoom that keeps the desktop layout. `--headless`, launch node `headless: true` or `TERMINAL_HEADLESS=1` hide it; `--headful` stays accepted. `--slow-mo <ms>` / `slow_mo_ms` / `TERMINAL_SLOW_MO` pause before each UI action. Terminal `app.hud` draws the recipe, step N/M, current intent and last result on the app tab (closed shadow root outside `<body>`, pointer-events none, redrawn after navigation, never on MetaMask pages); `--hud auto` shows it only in a visible browser.
+- Terminal testnet enforcement: every mainnet host the venue SDK names, and the API and base URLs of `@metamask/perps-controller` and the app source, are unresolvable for the whole browser and blocked by the wallet host (`blocked-mainnet`); mainnet Hyperliquid typed data is refused before any signer sees it (`refused-mainnet`). The venues' web hosts (`app.hyperliquid.xyz`, `app.hyperliquid-testnet.xyz`) are neither blocked nor proof of the served network, and a launch fails if any scanned source uses one with an API path. Source URLs are compared in canonical form (parsed: lowercase host without a trailing dot, default port dropped, dot segments resolved), and the host resolver rules cover each host's trailing-dot form. The launch proves both blocks with probes and that the app talks to a testnet API host, and fails if the SDK names a mainnet host missing from the block list. Mainnet needs `network: mainnet` with `mainnet_confirmation: REAL_FUNDS`. A browser is reused only while it enforces the same host list.
+- Terminal slot safety: slot processes carry `--mm-harness-owner` markers and only proven-owned ones are signalled; wallet calls are judged against their own document's commit, and anything that can't be (including calls pending when a tab detaches) is logged as `unattributed`; a failed launch stops what it started and removes temporary key material; a first page that never commits is reported with what the tab and the dev server did. Only `TERMINAL_CHROME_BIN` overrides the browser.
+- Terminal focus: a visible browser starts in the background through LaunchServices with no startup window; one check after the launch (shared `macos-focus.cjs`, `restoreFrontmostIfOurs`) gives the front back once, by pid, only if this slot's browser took it, and the wallet host only observes. Pages come to front only with `MM_HARNESS_FOCUS_BROWSER=1`.
+- Terminal run diagnostics: recipe runs start the shared console collector for the slot (`terminal/app-console.log` for the app page, `terminal/extension-console.log` for MetaMask; `mm-harness logs` lists both and the wallet request log), and the run's non-probe `blocked-mainnet`, `refused-mainnet` and `unattributed` wallet entries are findings. `metamask.app.assert_no_console_errors` fails a recipe on unexplained page, browser or extension errors.
+- Console allowlists (`diagnostics/console-allowlist.json`, `schemaVersion: 3`, earlier versions refused): exact signatures of an event's first line, continuation and optional location, compared by string equality through one matcher, `library/actions/shared/console-findings.mjs`, which recipe-library guards also call. Normalisation only touches parsed fields: URLs (Next.js scope only on a plain path: every segment made of letters, digits, `.`, `_`, `@`, `-` and `%40`, never `.` or `..`) in a loopback port, a `/_next/static/` asset name (its directory and extension kept), `dpl`/`v` on `/_next/` paths and an unpacked extension id; frames and locations lose their position; other text only in times, UUIDs and hex of 9+ digits. `library/actions/shared/console-allowlist-add.mjs <run artifacts dir>` writes entries from a real run.
+
+### Changed
+
+- Console collector capture files are framed: every line after an event's first starts with `│ `, and a browser Log entry's `[browser:<source>]` tag sits in the record header before the level word, where message text can't put it; its location is its URL alone, without a line number. **Logs from older collectors:** each unprefixed line is a finding of its own (at least an error) and their browser entries read as page events, so they report REVIEW.
+- Run diagnostics and `assert_no_console_errors` require capture evidence: this runtime's own collector (a process running this checkout's `console-tail.mjs` as its script, with its exact argument list, so install and runtime paths may contain spaces; owner marker; a marker-less collector for the same log is replaced once, and this runtime's collector started by another harness install is retired before its replacement starts; capture files rotate past 32 MB) and a control line logged in the captured target that reaches the capture file (for the Extension, from MetaMask's own extension id). **Extension consumers:** a run whose capture can't be proven at the end reports UNAVAILABLE instead of CLEAN, so the browser must still be open then; a capture over the 512 KB read limit with no findings is UNAVAILABLE too. Capture control lines are never findings.
+
+## 0.70.1 - 2026-10-02
+
+### Fixed
+
+- Detect forced Google Chrome sign-in (`BrowserSignin: 2`, `ForceBrowserSignin`) as managed: `plutil` returns these scalar policies only as raw values, so a Mac with only forced sign-in looked unmanaged and fell back to the managed Chrome.
+- Disable other user extensions in the slot browser before its start page (a dapp or the wallet home) loads; a browser started without a window gets a blank background window first.
+- Fail the launch, and stop the browser, when a slot browser started without a window cannot open its start window, instead of recording a browser with no window.
+- Start the library autolaunch browser on macOS without a startup window, load the wallet home into its window's blank tab (so it is the page a screenshot of the window shows) or a background window, and restore the operator's front app once, by pid, only if its own browser took it. Headful browser probes also start without a startup window.
+- Show doctor's managed-Chrome diagnostics next to any other browser warning.
+
 ## 0.70.0 - 2026-10-02
 
 ### Added

package/README.md

@@ -149,15 +149,22 @@ On a cold cache the probe can take up to about 80 seconds and
 shows a small (about 480×360) browser window; `doctor --adapter extension`
 runs the same probe.
 
-On a Mac whose Google Chrome is managed by policy (force-installed extensions
-in `/Library/Managed Preferences/…/com.google.Chrome.plist`, or forced
-sign-in), `auto` uses Chrome for Testing: it does not read those policies, so
-no forced extension can open windows in the slot. If Chrome for Testing does
-not start and paint there, the launch stops and names the two ways forward
-(`RECIPE_HARNESS_BROWSER=chrome`, accepting the forced extensions' windows, or
-a less loaded machine) instead of falling back to the managed Chrome. Doctor
-lists the forced extensions. A slot profile created on the managed Chrome keeps
-it, with a warning to reset the profile.
+On a Mac whose Google Chrome is managed by policy, `auto` uses Chrome for
+Testing, which does not read those policies, so no forced extension can open
+windows in the slot. Only MDM-managed preferences are read
+(`/Library/Managed Preferences/com.google.Chrome.plist` and its per-user
+copy under `/Library/Managed Preferences/<user>/`), not `defaults` a user set
+themselves; force-installed extensions (`ExtensionInstallForcelist`,
+`ExtensionSettings`) or forced sign-in (`BrowserSignin: 2`,
+`ForceBrowserSignin`) count as managed; a policy stored as a Data or Date
+value is treated as absent. If Chrome for Testing does not start
+and paint there, the launch stops with `BROWSER_UNLAUNCHABLE` rather than
+falling back to the managed Chrome; the way out is
+`RECIPE_HARNESS_BROWSER=chrome` (accepting that forced extensions may open
+windows that take the front), or a less loaded machine. Doctor lists the forced
+extension ids, with names where it can read them (best effort, read-only: the
+slot record, or the operator's own Chrome profile folders). A slot profile
+created on the managed Chrome keeps it, with a warning to reset the profile.
 
 A slot then keeps the kind of browser its profile was created with, until the
 profile is reset (`mm-harness fixtures set` or `fixtures reset`):

package/adapters/extension/console-tail.mjs

@@ -39,11 +39,13 @@ function parseArgs(argv) {
       case '-h':
       case '--help':
         process.stdout.write(
-          'Usage: console-tail.mjs --cdp-port <port> [--extension-log <file>] [--dapp-log <file>]\n',
+          'Usage: console-tail.mjs --cdp-port <port> [--extension-log <file>] [--dapp-log <file>] [--mm-harness-owner=<marker>]\n',
         );
         process.exit(0);
         break;
       default:
+        // An ownership marker the caller identifies its collector by.
+        if (arg.startsWith('--mm-harness-owner=')) break;
         throw new Error(`Unknown argument: ${arg}`);
     }
   }
@@ -73,7 +75,13 @@ const cooldown = new Map();
 // Writes formatted console-event strings (never raw HTTP response bodies) to
 // stdout and optionally to a caller-supplied log file. The source is the local
 // Chrome CDP WebSocket (127.0.0.1:<cdpPort>) — a trusted-local endpoint.
-function out(line, destination = null) {
+// Every line after an event's first is written with this prefix, so text
+// inside a message can never read as the start of another event.
+const CONTINUATION_PREFIX = '│ ';
+
+function out(event, destination = null) {
+  const [first, ...rest] = String(event).split('\n');
+  const line = [first, ...rest.map((continued) => `${CONTINUATION_PREFIX}${continued}`)].join('\n');
   process.stdout.write(`${line}\n`);
   if (destination) {
     // This file is explicitly an untrusted application-console transcript; it is never executed or parsed as configuration.
@@ -136,10 +144,23 @@ function previewArg(arg) {
   return arg.subtype || arg.type || '?';
 }
 
+// Where an event came from, appended as "  (at <frame>)": the first stack
+// frame of a console call or exception, the URL of a browser log entry. Run
+// diagnostics group findings by message and report this frame.
+function frameText(callFrame) {
+  if (!callFrame?.url) return '';
+  return `${callFrame.functionName || '<anonymous>'} ${callFrame.url}:${(callFrame.lineNumber ?? 0) + 1}:${(callFrame.columnNumber ?? 0) + 1}`;
+}
+
+function atSuffix(frame) {
+  return frame ? `  (at ${frame})` : '';
+}
+
 function emitConsole(label, params, destination) {
   const level = String(params.type || 'log').toUpperCase();
   const text = (params.args || []).map(previewArg).join(' ');
-  out(`${stamp()} [${label}] ${level}  ${text}`, destination);
+  const [first, ...rest] = text.split('\n');
+  out(`${stamp()} [${label}] ${level}  ${first}${atSuffix(frameText(params.stackTrace?.callFrames?.[0]))}${rest.length ? `\n${rest.join('\n')}` : ''}`, destination);
 }
 
 function emitException(label, params, destination) {
@@ -149,13 +170,23 @@ function emitException(label, params, destination) {
     d.exception?.value ||
     d.text ||
     'uncaught exception';
-  out(`${stamp()} [${label}] EXCEPTION  ${text}`, destination);
+  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);
 }
 
+// Browser log entries (network failures, interventions, deprecations) are
+// tagged with their Log source in the record header, before the level word,
+// e.g. "[dapp:page:BTC] [browser:network] ERROR  …": message text (written
+// after the level word) can never produce the tag.
 function emitLogEntry(label, params, destination) {
   const e = params.entry || {};
   const level = String(e.level || 'log').toUpperCase();
-  out(`${stamp()} [${label}] ${level}  ${e.text || ''}`, destination);
+  const source = String(e.source || 'other').replace(/[^a-z-]/gu, '') || 'other';
+  // 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);
 }
 
 function handleMessage(label, destination, data) {
@@ -185,7 +216,8 @@ function handleMessage(label, destination, data) {
 function attach(target) {
   const stream = targetStream(target);
   if (!stream) return;
-  const label = `${stream.kind}:${shortLabel(target)}`;
+  // No brackets or spaces: the label is a header field.
+  const label = `${stream.kind}:${shortLabel(target)}`.replace(/[[\]\s]/gu, '_');
   const ws = new WebSocket(target.webSocketDebuggerUrl);
   const entry = { ws, label, destination: stream.log, opened: false };
   attached.set(target.id, entry);

package/adapters/extension/launch-browser.cjs

@@ -223,7 +223,7 @@ try {
       }
     }
     if (loadsOverCdp) cdpLoad = loadExtensionOverCdp(browserPid);
-    else if (application) openBackgroundWindow(initialUrl);
+    else if (application) openBackgroundWindow(browserPid, initialUrl);
     owner = cdpLoad?.owner ?? ownerIdentity(browserPid);
     for (const problem of pruneExtraHomeTabs(cdpPort, args['extension-dir'])) {
       process.stderr.write(`[launch] home-tab pruning: ${problem}\n`);
@@ -283,14 +283,26 @@ try {
 }
 
 // The first window of a browser started without one, opened in the background.
-function openBackgroundWindow(url) {
+// Without it the slot has no window at all, so a failure fails the launch:
+// the owned browser is stopped (its markers kept if it cannot be).
+function openBackgroundWindow(pid, url) {
   const result = spawnSync(process.execPath, [browserResolverPath, 'open-window', '--port', String(cdpPort), '--url', url], {
     encoding: 'utf8',
     timeout: 30_000,
   });
-  if (result.status !== 0) {
-    process.stderr.write(`[launch] could not open the start window: ${(result.stderr || result.error?.message || '').trim()}\n`);
+  if (result.status === 0) return;
+  const openError = (result.stderr || result.error?.message || `exit ${result.status}`).trim();
+  try {
+    stopProfileProcessesSync(args.profile, { extraPids: [pid] });
+  } catch (stopError) {
+    throw new Error(
+      `Chrome started but its start window could not be opened (${openError}), and stopping it failed: ${stopError.message}. ` +
+        `The launch markers for port ${cdpPort} and ${args.profile} are kept. Next: stop pid ${pid}, then rerun.`,
+    );
   }
+  clearDetachedLaunchUnproven(args.profile);
+  if (!activeValidationLease) clearValidationPortQuarantine(cdpPort, args.profile);
+  throw new Error(`Chrome started but its start window could not be opened: ${openError}. Next: inspect ${args['chrome-log']}, then rerun.`);
 }
 
 // live.sh passes the record its resolver just wrote (--browser-resolution);

package/adapters/manifest.json

@@ -638,6 +638,134 @@
       "purpose": "Bootstrap numbered MetaMask checkouts through the setup-base command.",
       "inputs": "setup-base command arguments",
       "outputs": "numbered checkouts, saved preferences, and run summary"
+    },
+    {
+      "id": "terminal/launch",
+      "entry": "adapters/terminal/launch.mjs",
+      "kind": "node",
+      "purpose": "Start or reuse the Web Terminal 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 venue SDK's mainnet hosts 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>/terminal/browser.json + pid/log files; JSON on stdout; exit 0/1/2"
+    },
+    {
+      "id": "terminal/wallet-host",
+      "entry": "adapters/terminal/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).",
+      "inputs": "--cdp-port --runtime-dir --signer --app-origin [--extension-id] [--target --account --start-chain] [--browser-app <.app>]",
+      "outputs": "<runtime>/terminal/wallet-requests.jsonl, wallet-host.ready"
+    },
+    {
+      "id": "terminal/stop",
+      "entry": "adapters/terminal/stop.mjs",
+      "kind": "node",
+      "purpose": "Stop the terminal 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": "terminal/inject",
+      "entry": "adapters/terminal/inject.mjs",
+      "kind": "node",
+      "purpose": "Terminal install: overlay marker, runtime dir and wallet fixture (0600); no product writes.",
+      "inputs": "--target [--fixture] [--force]; env RECIPE_WALLET_FIXTURE",
+      "outputs": "<harness>/terminal/install.json, <runtime>/wallet-fixture.json; exit 0/1"
+    },
+    {
+      "id": "terminal/cleanup",
+      "entry": "adapters/terminal/cleanup.mjs",
+      "kind": "node",
+      "purpose": "Terminal cleanup: stop browser/host, remove terminal 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": "terminal/verify",
+      "entry": "adapters/terminal/verify.mjs",
+      "kind": "node",
+      "purpose": "Read-only terminal 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": "terminal/lib-cdp-client",
+      "entry": "adapters/terminal/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": "terminal/lib-page-script",
+      "entry": "adapters/terminal/lib/page-script.mjs",
+      "kind": "lib",
+      "purpose": "Page script source: wallet request logging and the injected strict provider (EIP-6963 io.metamask).",
+      "inputs": "pageScriptSource({ signer, appOrigin })",
+      "outputs": "script source string"
+    },
+    {
+      "id": "terminal/lib-strict-wallet",
+      "entry": "adapters/terminal/lib/strict-wallet.mjs",
+      "kind": "lib",
+      "purpose": "EIP-1193 strict test wallet enforcing typed-data chainId == active chain.",
+      "inputs": "createStrictWallet({ account, chainId })",
+      "outputs": "request()"
+    },
+    {
+      "id": "terminal/lib-processes",
+      "entry": "adapters/terminal/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": "stopTerminalBrowser(target, { cdpPort }), stopConsoleCollector(target), ownerMarker(kind, runtimeDir), ownsProcess(kind, pid, runtimeDir)",
+      "outputs": "stopped processes"
+    },
+    {
+      "id": "terminal/lib-readiness",
+      "entry": "adapters/terminal/lib/readiness.mjs",
+      "kind": "lib",
+      "purpose": "Terminal slot readiness checks shared by verify, doctor and the surface.",
+      "inputs": "terminalReadiness({ target, appPort, cdpPort, signer }), assertLaunchNetwork(target, { network, mainnetConfirmation }), devServerTestnetDiagnostic(target, { appPort }) (advisory)",
+      "outputs": "checks[]"
+    },
+    {
+      "id": "terminal/lib-display",
+      "entry": "adapters/terminal/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": "terminal/lib-hud",
+      "entry": "adapters/terminal/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": "terminal/lib-origin",
+      "entry": "adapters/terminal/lib/origin.mjs",
+      "kind": "lib",
+      "purpose": "Exact app-origin and app top-frame checks for targets, wallet requests and log entries.",
+      "inputs": "isAppUrl(url, appOrigin), isAppTopFrameContext(context, { targetId, appOrigin })",
+      "outputs": "boolean"
+    },
+    {
+      "id": "terminal/lib-mainnet-guard",
+      "entry": "adapters/terminal/lib/mainnet-guard.mjs",
+      "kind": "lib",
+      "purpose": "Testnet enforcement: the venue endpoint hosts (from the venue SDK, @metamask/perps-controller and the app source in the checkout), the browser's host-resolver block, and the mainnet typed-data classifier used by the page script and the wallet host.",
+      "inputs": "venueHosts(checkout), hostResolverRules(hosts), isMainnetVenueUrl(url, hosts), mainnetTypedDataReason(data)",
+      "outputs": "host list, launch switch, refusal reason"
+    },
+    {
+      "id": "terminal/surface",
+      "entry": "src/adapters/terminal/surface.ts",
+      "kind": "module",
+      "purpose": "Terminal adapter surface (runtime status, browser stop, logs, hints).",
+      "inputs": "terminalSurface",
+      "outputs": "AdapterSurface"
     }
   ]
 }

package/adapters/shared/browser-cdp.cjs

@@ -428,12 +428,21 @@ async function openBackgroundWindow(send, url, timeoutMs) {
   return send('Target.createTarget', { url, newWindow: true, background: true }, undefined, timeoutMs);
 }
 
+const isBlankPage = (target) => target.type === 'page' && (target.url === 'about:blank' || target.url.startsWith('chrome://newtab') || target.url.startsWith('chrome://new-tab-page'));
+
+// A browser started without a window gets a blank background window, so the
+// first window never takes the operator's focus and nothing is navigated yet.
+async function ensureBackgroundWindow(send, remaining) {
+  const { targetInfos } = await send('Target.getTargets', {}, undefined, remaining());
+  if ((targetInfos || []).some((target) => target.type === 'page')) return;
+  await openBackgroundWindow(send, 'about:blank', remaining());
+}
+
 // Point the launch tab at `url` once the extension exists: the tab opened at
-// launch would otherwise show an error page for chrome-extension:// URLs. A
-// browser started without a window gets a background window instead.
+// launch would otherwise show an error page for chrome-extension:// URLs.
 async function openUrl(send, url, remaining) {
   const { targetInfos } = await send('Target.getTargets', {}, undefined, remaining());
-  const blank = targetInfos.find((target) => target.type === 'page' && (target.url === 'about:blank' || target.url.startsWith('chrome://newtab') || target.url.startsWith('chrome://new-tab-page')));
+  const blank = (targetInfos || []).find(isBlankPage);
   if (!blank) {
     await openBackgroundWindow(send, url, remaining());
     return;
@@ -489,12 +498,15 @@ async function loadUnpackedOverPort(port, extensionDir, {
     assertSameOwner(owner, { exec, timeoutMs: remaining() });
     step = 'Extensions.loadUnpacked';
     const loaded = await loadUnpackedExtension(client.send, extensionDir, { expectedId, timeoutMs: remaining() });
-    // The start page first: a browser started without a window gets its first
-    // window here, in the background, before isolation opens its tab.
-    step = 'opening the start page';
-    if (url) await openUrl(client.send, url, remaining);
+    // A browser started without a window gets a blank background window
+    // first; other extensions are disabled before the start page (a dapp, or
+    // the wallet home) loads in it.
+    step = 'opening a background window';
+    await ensureBackgroundWindow(client.send, remaining);
     step = 'isolating the wallet from other extensions';
     const otherExtensions = await isolateWalletExtension(client.send, loaded.id, { timeoutMs: remaining() });
+    step = 'opening the start page';
+    if (url) await openUrl(client.send, url, remaining);
     remaining();
     return { ...loaded, otherExtensions, owner };
   } catch (error) {
@@ -523,6 +535,8 @@ module.exports = {
   expectedExtensionId: (extensionDir) => extensionIdFromExtensionDir(extensionDir) || null,
   loadUnpackedExtension,
   loadUnpackedOverPort,
+  ensureBackgroundWindow,
   isolateWalletExtension,
   openBackgroundWindow,
+  openUrl,
 };

package/adapters/shared/browser-resolver.cjs

@@ -106,14 +106,24 @@ function managedChromePlists(env = process.env) {
   ];
 }
 
-// One policy key as JSON, or undefined when absent or unreadable.
+// One policy key, or undefined when absent or unreadable. `plutil -extract
+// … json` only extracts arrays and dictionaries; a scalar (BrowserSignin: 2,
+// ForceBrowserSignin: true) comes out with `raw`.
 function readPolicyKey(file, key) {
+  const extract = (format) => execFileSync('plutil', ['-extract', key, format, '-o', '-', file], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+    timeout: 5000,
+  });
   try {
-    return JSON.parse(execFileSync('plutil', ['-extract', key, 'json', '-o', '-', file], {
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'ignore'],
-      timeout: 5000,
-    }));
+    return JSON.parse(extract('json'));
+  } catch {
+    // A scalar, or the key is absent: try it as a raw value.
+  }
+  try {
+    const raw = extract('raw').trim();
+    if (raw === 'true' || raw === 'false') return raw === 'true';
+    return /^-?\d+$/u.test(raw) ? Number(raw) : raw;
   } catch {
     return undefined;
   }
@@ -512,11 +522,12 @@ async function probeLaunch(executable, {
   let exited = null;
   try {
     const port = await freePort();
-    // A headful Launch Services probe starts like the slot browser: in the
-    // background with no startup window (Chrome activates itself when it opens
-    // one); renderCheck opens a background window. Like the launcher, it keeps
-    // a window that sits behind the operator's apps rendering.
-    const backgroundWindow = method === LAUNCH_SERVICES && display === HEADFUL;
+    // A headful probe starts like the slot browsers (the launchers and the
+    // library autolaunch): in the background with no startup window (Chrome
+    // activates itself when it opens one); renderCheck opens a background
+    // window. Like the launchers, it keeps a window behind the operator's apps
+    // rendering.
+    const backgroundWindow = display === HEADFUL;
     const args = [
       ...(display === HEADLESS ? ['--headless=new'] : ['--window-size=480,360']),
       `--user-data-dir=${profile}`,

package/adapters/terminal/cleanup.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+// cleanup.mjs — `mm-harness cleanup --adapter terminal`: stop the slot browser
+// and wallet host, then remove the terminal runtime state and the installed
+// wallet fixture. Browser profiles are kept unless --reset-profile.
+//
+// Inputs: --target <checkout> [--cdp-port <port>] [--reset-profile]
+// Outputs: JSON summary on stdout. Exit 0 cleaned; 1 the CDP port stayed busy.
+// Never touches: product source files, the Next.js dev server.
+
+import { existsSync, readdirSync, rmSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { recipeHarnessPath, walletFixturePath } from '../../library/actions/harness-exports.mjs';
+import { terminalRuntimeDir } from '../../library/actions/terminal/platform/runtime.mjs';
+import { stopConsoleCollector, stopTerminalBrowser } from './lib/processes.mjs';
+
+const usage = 'Usage: cleanup.mjs --target <checkout> [--cdp-port <port>] [--reset-profile]';
+
+export async function cleanupTerminalRuntime({ target, cdpPort, resetProfile = false }) {
+  const root = path.resolve(target);
+  const stop = await stopTerminalBrowser(root, { cdpPort });
+  await stopConsoleCollector(root);
+  const runtime = terminalRuntimeDir(root);
+  const removed = [];
+  if (existsSync(runtime)) {
+    for (const entry of readdirSync(runtime)) {
+      if (entry.startsWith('profile-') && !resetProfile) continue;
+      rmSync(path.join(runtime, entry), { recursive: true, force: true });
+      removed.push(entry);
+    }
+  }
+  const overlay = recipeHarnessPath(root, 'terminal');
+  if (existsSync(overlay)) {
+    rmSync(overlay, { recursive: true, force: true });
+    removed.push(path.relative(root, overlay));
+  }
+  const fixture = walletFixturePath(root);
+  if (existsSync(fixture)) {
+    rmSync(fixture, { force: true });
+    removed.push(path.relative(root, fixture));
+  }
+  return { status: 'pass', target: root, stopped: stop.stopped, cdpPortFree: stop.cdpPortFree, removed };
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const argv = process.argv.slice(2);
+  if (argv.includes('--help') || argv.includes('-h')) {
+    process.stdout.write(`${usage}\n`);
+    process.exit(0);
+  }
+  const value = (flag) => {
+    const index = argv.indexOf(flag);
+    return index >= 0 ? argv[index + 1] : undefined;
+  };
+  const rawPort = value('--cdp-port') ?? process.env.RECIPE_CDP_PORT ?? process.env.CDP_PORT;
+  try {
+    const result = await cleanupTerminalRuntime({
+      target: value('--target') ?? process.cwd(),
+      cdpPort: rawPort ? Number(rawPort) : undefined,
+      resetProfile: argv.includes('--reset-profile'),
+    });
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+  } catch (error) {
+    process.stdout.write(`${JSON.stringify({ status: 'fail', error: error.message })}\n`);
+    process.exit(1);
+  }
+}

package/adapters/terminal/inject.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+// inject.mjs — `mm-harness install --adapter terminal`: prepare the slot runtime
+// directory and install the wallet fixture the terminal actions read.
+//
+// Inputs: --target <terminal checkout> [--fixture <wallet-fixture.json>] [--force]
+//   env RECIPE_WALLET_FIXTURE (fixture source when --fixture is absent)
+// Outputs: <target>/<harness root>/terminal/install.json (overlay marker),
+//   <target>/<runtime>/terminal/ (0700), <runtime>/wallet-fixture.json (0600);
+//   JSON summary on stdout (account names only). Exit 0 installed; 1 failure; 2 usage.
+// Never touches: product source files; never prints key material.
+
+import { copyFileSync, chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { recipeHarnessPath, recipeRuntimeDir, walletFixturePath } from '../../library/actions/harness-exports.mjs';
+import { terminalRuntimeDir } from '../../library/actions/terminal/platform/runtime.mjs';
+import { isTerminalCheckout } from './lib/readiness.mjs';
+
+const usage = 'Usage: inject.mjs --target <terminal checkout> [--fixture <wallet-fixture.json>] [--force]';
+
+export function installTerminalRuntime({ target, fixture, force = false }) {
+  const root = path.resolve(target);
+  if (!isTerminalCheckout(root)) throw new Error(`${root} is not a Web Terminal checkout (needs next + src/features/perpetuals).`);
+  mkdirSync(path.join(root, recipeRuntimeDir()), { recursive: true, mode: 0o700 });
+  mkdirSync(terminalRuntimeDir(root), { recursive: true, mode: 0o700 });
+  const destination = walletFixturePath(root);
+  let fixtureAction = 'kept';
+  if (fixture && (force || !existsSync(destination))) {
+    const parsed = JSON.parse(readFileSync(fixture, 'utf8'));
+    if (!Array.isArray(parsed.accounts) || parsed.accounts.length === 0) throw new Error(`${fixture} has no accounts.`);
+    copyFileSync(fixture, destination);
+    chmodSync(destination, 0o600);
+    fixtureAction = 'installed';
+  } else if (!existsSync(destination)) {
+    fixtureAction = 'missing';
+  }
+  const accounts = existsSync(destination)
+    ? JSON.parse(readFileSync(destination, 'utf8')).accounts.map((account) => account?.name).filter(Boolean)
+    : [];
+  const marker = { schemaVersion: 1, adapter: 'terminal', installedAt: new Date().toISOString(), fixture: fixtureAction };
+  // The overlay directory is the install marker run/call auto-ensure checks.
+  const overlay = recipeHarnessPath(root, 'terminal');
+  mkdirSync(overlay, { recursive: true, mode: 0o700 });
+  writeFileSync(path.join(overlay, 'install.json'), `${JSON.stringify(marker, null, 2)}\n`, { mode: 0o600 });
+  return { status: fixtureAction === 'missing' ? 'fail' : 'pass', target: root, fixture: fixtureAction, fixturePath: destination, accounts };
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const argv = process.argv.slice(2);
+  if (argv.includes('--help') || argv.includes('-h')) {
+    process.stdout.write(`${usage}\n`);
+    process.exit(0);
+  }
+  const value = (flag) => {
+    const index = argv.indexOf(flag);
+    return index >= 0 ? argv[index + 1] : undefined;
+  };
+  try {
+    const result = installTerminalRuntime({
+      target: value('--target') ?? process.cwd(),
+      fixture: value('--fixture') ?? process.env.RECIPE_WALLET_FIXTURE,
+      force: argv.includes('--force'),
+    });
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+    if (result.status !== 'pass') {
+      process.stderr.write('No wallet fixture installed. Next: set RECIPE_WALLET_FIXTURE or pass --fixture <wallet-fixture.json>.\n');
+      process.exit(1);
+    }
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    process.exit(1);
+  }
+}