@deeeed/metamask-harness 0.80.0 → 0.81.0

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ## Unreleased
 
+## 0.81.0 - 2026-10-07
+
+### Added
+
+- Core's headless `RewardsController:getPerpsDiscountForAccount` now asks the rewards API for the Perps fee discount, with the calls Mobile's RewardsController makes for the selected wallet fixture account: the opt-in check, `mobile-login` signed with personal_sign, then `/vip/fees`, and Mobile's discount math. Like Mobile, it logs in when the opt-in check itself fails, reads a 401 from login as not opted in, and gives each request 10 seconds. An account that never opted in, or an address outside the fixture, gets no discount (`null`). The session token stays in memory, and an error keeps only the HTTP status, never the response body. The backend defaults to UAT, as on Mobile dev builds; `CORE_PERPS_REWARDS_API_URL` selects another. `metamask.perps.quote_fees` reports `rewardsSource: "rewards-api"` with each call it answered; `rewards_discount_bips` still replaces the answer, to prove a discount the non-VIP fixture accounts cannot get.
+
+### Changed
+
+- **BREAKING:** Perps orders follow one rule on Mobile, Extension and Core (F21). Testnet orders need no funding proof, so `run` and `call metamask.perps.place_order --adapter extension` work without the four `--funding-*` files, as on Mobile. A mainnet order is allowed only from a synced fixture account, as a 1x isolated market order with `close_immediately: true` and `network: mainnet` declared, whose worst-case fill (one size step plus max slippage over the request) stays within $15; anything else is refused before dispatch with `PERPS_MAINNET_ORDER_REFUSED`. This newly guards Mobile mainnet orders, which had no check. `place_order` takes `close_immediately` (and Mobile takes `network`): from a flat market (no position or resting order), the action closes the opened position itself, on the account and network the rule allowed, and proves the market flat. Extension background market placements now prove their postcondition on current builds (positions carry a signed size, no side). On the Extension, a run without funding files runs its mutations in a fixture-policy lane with a run-owned execution ledger; the funding files remain the stricter release lane. Core keeps `CORE_PERPS_ALLOW_MAINNET_WRITES=1`. The fixture account derivation behind `metamask.wallet.list_accounts` moved to `library/actions/shared/wallet/fixture-accounts.mjs`, shared with the order rule.
+- Extension screenshots: a capture-helper that times out is killed with SIGKILL together with everything it started (the npm wrapper runs the native binary as a child). It can ignore SIGTERM and linger, making later captures hang. Before the next capture, this user's snapshot helpers orphaned by an earlier run (matched by executable and subcommand, including the configured path) are killed with their children; recording sessions and helpers whose harness is alive are left alone. A CDP fallback screenshot records `fallbackReason` (the capture-helper error) next to `fallbackFrom`, for `run`'s fallback listing in the next `@farmslot/recipe-cli` (deeeed/farmslot#829).
+- Extension `check diff` also runs `yarn verify-locales --quiet` when a file under `app/_locales/**` changed, moved or was deleted, and `yarn circular-deps:check` when any JS/TS file changed, moved or was deleted; otherwise each reports `skip`. `changedFiles` now lists deleted files and both sides of a rename (lint, format and tests still run on existing files only).
+- Help text only: the `help` quality guidance says to assert a test command's literal pass count with `assert_output`, since `jest -t` exits 0 when no test matches.
+- The Web Terminal's venue policy lives in one module, `adapters/terminal/policy.mjs`: the blocked and served Hyperliquid hosts, link hosts, the launch probe, the testnet typed-data refusal, the start page (`/order/BTC`), the injected wallet's start chain (42161), the checkout dependencies and the dev-server testnet variable. The launch, verify, doctor and the wallet host take it as an argument instead of naming the venue themselves; the leaf scripts `adapters/terminal/{launch,verify,wallet-host}.mjs` require `--policy-module <path>`, which the Terminal adapter passes. Behaviour is unchanged.
+- The Web Terminal's web3 part moves to `@farmslot/adapter-web/dapp` (`@farmslot/adapter-web` 0.3.0): the strict test wallet, the page script that logs the app's wallet requests (or injects the provider the wallet host answers), the wallet host's judgement of each request's frame and document, and the reading and assertion of the wallet request log behind `metamask.wallet.read_signatures` / `assert_signatures`. The exact-origin checks move to `@farmslot/adapter-web/origin`. The Terminal passes in its own parts: the Hyperliquid testnet refusal, the injected wallet's MetaMask identity, and the L1 and mainnet rules of the signature assertion. Log entries, refusals and action outputs are unchanged. The page's bindings are now `__farmslotWallet{Log,Request,Resolve}` and its marker `__farmslotDapp` (were `__mmTerminal*`).
+- Depend on `@farmslot/recipe-cli` 0.5.0 and `@farmslot/adapter-sdk` 0.4.0 (were 0.4.1 and 0.3.1), which carry the run and call engine and action discovery. `@farmslot/adapter-web` moves 0.2.0 → 0.3.1 (`./dapp` from 0.3.0, the probe fix in 0.3.1); `@farmslot/adapter-rn` 0.17.0, `@farmslot/recipe-runner` 0.24.0, `@farmslot/agent-runtime` 0.17.0 and `@farmslot/protocol` 0.34.0 are unchanged, so the install still holds one `@farmslot/recipe-runner`.
+- `run` and `call` move to `@farmslot/recipe-cli/harness` with their engine (recipe execution, preflight, bounded healing, recipe library resolution, static validation, network observation) and `describeManifestActions`, the action catalog entries they share with `actions`. mm-harness hands them one engine, `src/engine.ts`: the bundled `metamask` library, `src/manifest.ts`, the MetaMask action risk table, `createMetaMaskRunner`, funded mutations bound from the `--funding-*` flags, and the console classifier. Device targeting and the `fixture.file` plan step stay in mm-harness and are passed as command options. Flags, output and the CLI goldens are unchanged.
+- The Mobile and Extension proof-runtime checks (`MOBILE_SOURCE_NOT_LOADED`, `EXTENSION_RUNTIME_*`) move into `src/adapters/mobile/run.ts` and `src/adapters/extension/run.ts`, and the Mobile and Extension network backends into `src/adapters/{mobile,extension}/network-observer.ts`. Platforms declare network and performance observation through the SDK's `observation`; the performance observer stays in mm-harness and starts through `observation.performance.start`.
+- The Perps order rule (an order needs market, side and amount) runs in each platform's `actions.inputFindings` through `src/adapters/perps-order-inputs.ts`; `AdapterSurface` drops `actions.ensureChecksOnly` (the Extension passes it to the rule) and `observation` (now the SDK's). `src/metamask-action-validation.ts` is gone; the node loop is `@farmslot/recipe-cli`'s `validateActionInputs`.
+- Discovery moves to `@farmslot/recipe-cli/harness` and runs on `src/engine.ts`'s catalog: `actions` (lookup, search, categories, `--raw`, `--matrix`), `run --list`, `run <recipe> --describe` and `call --list`. `src/commands/manifest.ts` and `src/commands/list-executables.ts` are gone. Flags, `--json` output and the CLI goldens are unchanged. Two human-output changes:
+  - `actions --action <name>` (one match) and `call <action> --help` print the same action detail: the call form, description, source and adapter, risk, result cases, typed fields, up to two example calls, and the first example as a runnable call with its recipe node. The example calls now carry only the action's fields (no `next=done`, `cases` or `default`), shell-quoted, and use the full name when the short one is ambiguous. `actions --action` used to print a one-line catalog entry; `call --help` gains the risk, result cases and runnable example.
+  - The `actions --matrix` columns come from the registered platforms (same four, same order), and a capability no platform declares reads `across Mobile, Extension, Core, or Terminal` (was `across Mobile, Extension, or Core`).
+
+### Fixed
+
+- Browser probes stop when the resolver is stopped: `@farmslot/adapter-web` 0.3.1 (was 0.3.0) stops the probe browser and removes its profile when the resolver gets a signal (SIGTERM, SIGINT, SIGHUP, SIGQUIT); a probe browser left by a resolver killed with SIGKILL is reaped by the next probe.
+
 ## 0.80.0 - 2026-10-06
 
 ### Added

package/adapters/manifest.json

@@ -588,15 +588,15 @@
       "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",
+      "inputs": "--target --cdp-port --app-port --policy-module [--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>]",
+      "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 host passes the testnet policy and the injected wallet's identity.",
+      "inputs": "--cdp-port --runtime-dir --signer --app-origin --policy-module [--extension-id] [--target --account --start-chain] [--browser-app <.app>]",
       "outputs": "<runtime>/terminal/wallet-requests.jsonl, wallet-host.ready"
     },
     {
@@ -628,7 +628,7 @@
       "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]",
+      "inputs": "--policy-module --target [--cdp-port] [--watcher-port] [--signer] [--account] [--json]",
       "outputs": "readiness report; exit 0 ready / 1 not ready"
     },
     {
@@ -639,22 +639,6 @@
       "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",
@@ -668,7 +652,7 @@
       "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)",
+      "inputs": "terminalReadiness({ policy, target, appPort, cdpPort, signer }), assertLaunchNetwork(target, { network, mainnetConfirmation }), devServerTestnetDiagnostic(target, { appPort, variable }) (advisory)",
       "outputs": "checks[]"
     },
     {
@@ -687,22 +671,22 @@
       "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)",
+      "inputs": "venueHosts(checkout), hostResolverRules(hosts), isMainnetVenueUrl(url, hosts), mainnetTypedDataReason(data), TESTNET_TYPED_DATA_POLICY",
       "outputs": "host list, launch switch, refusal reason"
     },
+    {
+      "id": "terminal/policy",
+      "entry": "adapters/terminal/policy.mjs",
+      "kind": "lib",
+      "purpose": "The Web Terminal's venue policy: blocked and served venue hosts, link hosts, the launch probe, the testnet typed-data refusal, the start page, the injected wallet's start chain, the checkout dependencies and the dev-server testnet variable. launch, verify, doctor and the wallet host take it as an argument (--policy-module for the leaf processes).",
+      "inputs": "policy.venueHosts(checkout)",
+      "outputs": "policy"
+    },
     {
       "id": "terminal/surface",
       "entry": "src/adapters/terminal/surface.ts",

package/adapters/terminal/launch.mjs

@@ -29,7 +29,7 @@ import { createRequire } from 'node:module';
 import { appendFileSync, chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import {
   fixtureEntry,
@@ -42,7 +42,7 @@ import { CdpClient, browserWebSocketUrl } from './lib/cdp-client.mjs';
 import { clearHudState } from './lib/hud.mjs';
 import { browserDisplayArgs, resolveHeadless, resolveSlowMo, windowPlacement, writeProfileZoom } from './lib/display.mjs';
 import { cdpListenerPids, ownedBrowserPids, ownerMarker, ownsProcess, pidAlive, stopTerminalBrowser, terminate } from './lib/processes.mjs';
-import { hostResolverRules, venueHosts } from './lib/mainnet-guard.mjs';
+import { hostResolverRules } from './lib/mainnet-guard.mjs';
 import { assertLaunchNetwork, devServerTestnetDiagnostic } from './lib/readiness.mjs';
 
 const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
@@ -51,7 +51,7 @@ const HARNESS_ROOT = path.resolve(SCRIPT_DIR, '../..');
 const FIXTURE_STATE_SCRIPT = path.join(HARNESS_ROOT, 'adapters/extension/wallet-fixture-state.cjs');
 
 function usage() {
-  return 'Usage: launch.mjs --target <checkout> --cdp-port <port> --app-port <port> [--signer extension|injected] [--account <name>] [--fresh-profile] [--headless | --headful] [--slow-mo <ms>] [--network testnet|mainnet --mainnet-confirmation REAL_FUNDS] [--start-chain <id>] [--json]';
+  return 'Usage: launch.mjs --target <checkout> --cdp-port <port> --app-port <port> --policy-module <venue policy module> [--signer extension|injected] [--account <name>] [--fresh-profile] [--headless | --headful] [--slow-mo <ms>] [--network testnet|mainnet --mainnet-confirmation REAL_FUNDS] [--start-chain <id>] [--json]';
 }
 
 export function parseLaunchArgs(argv) {
@@ -67,7 +67,7 @@ export function parseLaunchArgs(argv) {
     args[flag.slice(2)] = argv[index + 1];
     index += 1;
   }
-  for (const key of ['target', 'cdp-port', 'app-port']) {
+  for (const key of ['target', 'cdp-port', 'app-port', 'policy-module']) {
     if (!args[key]) throw Object.assign(new Error(`Missing --${key}\n${usage()}`), { exitCode: 2 });
   }
   args.signer = resolveSigner(args.signer);
@@ -344,7 +344,9 @@ function writePrivateFile(file, text) {
 // which waits for a cold dev-server compile.
 export const LAUNCH_TIMEOUTS = Object.freeze({ browserStartMs: 90000, hostReadyMs: 180000 });
 
-export async function launchTerminalBrowser(args, env = process.env, { timeouts = LAUNCH_TIMEOUTS } = {}) {
+// `policy`: the venue policy (adapters/terminal/policy.mjs).
+export async function launchTerminalBrowser(args, env = process.env, { timeouts = LAUNCH_TIMEOUTS, policy } = {}) {
+  if (!policy?.module) throw new Error('launchTerminalBrowser needs the venue policy (adapters/terminal/policy.mjs).');
   const target = path.resolve(args.target);
   const cdpPort = Number(args['cdp-port']);
   const appPort = Number(args['app-port']);
@@ -353,12 +355,12 @@ export async function launchTerminalBrowser(args, env = process.env, { timeouts
   // browser: the SDK's mainnet venue hosts are unresolvable for the whole
   // browser, and the wallet host blocks, logs and refuses anything mainnet.
   const network = assertLaunchNetwork(target, { network: args.network, mainnetConfirmation: args['mainnet-confirmation'] });
-  const venues = network === 'testnet' ? venueHosts(target) : { mainnet: [], testnet: [] };
-  const mainnetHosts = venues.mainnet;
+  const venues = network === 'testnet' ? policy.venueHosts(target) : { blocked: [], served: [] };
+  const mainnetHosts = venues.blocked;
   // What the running browser enforces; a browser enforcing anything else is
   // never reused (its resolver rules are fixed at start).
-  const enforcementFingerprint = createHash('sha256').update(JSON.stringify({ network, mainnetHosts, testnetHosts: venues.testnet })).digest('hex').slice(0, 16);
-  const devServer = network === 'testnet' ? devServerTestnetDiagnostic(target, { appPort }) : null;
+  const enforcementFingerprint = createHash('sha256').update(JSON.stringify({ network, mainnetHosts, testnetHosts: venues.served })).digest('hex').slice(0, 16);
+  const devServer = network === 'testnet' ? devServerTestnetDiagnostic(target, { appPort, variable: policy.testnetVariable }) : null;
   if (devServer && !(devServer.known && devServer.forced)) {
     log(`WARN dev server testnet check: ${devServer.detail} (advisory; the browser enforces testnet itself)`);
   }
@@ -541,11 +543,12 @@ export async function launchTerminalBrowser(args, env = process.env, { timeouts
       '--app-origin', appOrigin,
       '--target', target,
       '--account', args.account,
-      '--start-chain', String(args['start-chain'] ?? 42161),
+      '--start-chain', String(args['start-chain'] ?? policy.startChain),
       '--network', network,
+      '--policy-module', policy.module,
       ownerMarker('wallet-host', runtime),
     ];
-    if (network === 'testnet') hostArgs.push('--mainnet-hosts', mainnetHosts.join(','), '--testnet-hosts', venues.testnet.join(','));
+    if (network === 'testnet') hostArgs.push('--mainnet-hosts', mainnetHosts.join(','), '--testnet-hosts', venues.served.join(','));
     if (extension?.id) hostArgs.push('--extension-id', extension.id);
     if (guardFocus) hostArgs.push('--observe-focus', '1');
     if (launchMethod === LAUNCH_SERVICES) hostArgs.push('--window', [windowBounds.x, windowBounds.y, windowBounds.width, windowBounds.height].join(','));
@@ -568,7 +571,7 @@ export async function launchTerminalBrowser(args, env = process.env, { timeouts
       signer,
       network,
       networkEnforcement: network === 'testnet'
-        ? { mode: 'enforced', mainnetHosts, testnetHosts: venues.testnet, fingerprint: enforcementFingerprint, layers: ['host-resolver-rules', 'cdp-fetch-block', 'wallet-refusal', 'served-network-check'] }
+        ? { mode: 'enforced', mainnetHosts, testnetHosts: venues.served, fingerprint: enforcementFingerprint, layers: ['host-resolver-rules', 'cdp-fetch-block', 'wallet-refusal', 'served-network-check'] }
         : { mode: 'disabled', reason: 'network=mainnet with mainnet_confirmation=REAL_FUNDS', fingerprint: enforcementFingerprint },
       devServerDiagnostic: devServer,
       consoleOffsets,
@@ -618,7 +621,8 @@ if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.me
     process.exit(0);
   }
   try {
-    const state = await launchTerminalBrowser(args);
+    const { policy } = await import(pathToFileURL(path.resolve(args['policy-module'])).href);
+    const state = await launchTerminalBrowser(args, process.env, { policy });
     process.stdout.write(`${JSON.stringify({ status: 'pass', ...state }, null, args.json ? 0 : 2)}\n`);
   } catch (error) {
     const message = String(error?.stderr ?? '').trim() || error.message;

package/adapters/terminal/lib/mainnet-guard.mjs

@@ -175,3 +175,12 @@ export function mainnetTypedDataReason(data) {
   if (data?.primaryType === 'Agent' && message.source === 'a') return 'L1 Agent source=a';
   return null;
 }
+
+// The wallet refusal for testnet runs, as the @farmslot/adapter-web/dapp page
+// script and wallet-request binding take it: mainnetTypedDataReason runs in
+// the page too, so it stays self-contained.
+export const TESTNET_TYPED_DATA_POLICY = Object.freeze({
+  reason: mainnetTypedDataReason,
+  kind: 'refused-mainnet',
+  message: 'Refused: this test run is held to Hyperliquid testnet and the request signs a mainnet action.',
+});

package/adapters/terminal/lib/readiness.mjs

@@ -34,8 +34,9 @@ async function httpStatus(url, timeoutMs = 20000) {
 }
 
 // Diagnostic only. Whether the slot's dev server looks configured for testnet:
-// the farm starts `next dev` (temp/farmslot/next-dev.pid) with
-// NEXT_PUBLIC_HYPERLIQUID_FORCE_TESTNET=true. Process inspection cannot prove
+// the farm starts `next dev` (temp/farmslot/next-dev.pid) with the policy's
+// testnet variable set to true (the Terminal's
+// NEXT_PUBLIC_HYPERLIQUID_FORCE_TESTNET). Process inspection cannot prove
 // what the browser talks to (macOS reports a process's initial environment,
 // and lsof cannot see other users' sockets), so this only warns; the browser
 // is held to testnet by the network and wallet layers (mainnet-guard.mjs, the
@@ -45,7 +46,6 @@ async function httpStatus(url, timeoutMs = 20000) {
 // entries from sysctl KERN_PROCARGS2) and must carry the testnet variable. An
 // unreadable process makes the result unknown.
 export const DEV_SERVER_PID_FILE = 'temp/farmslot/next-dev.pid';
-const FORCE_VARIABLE = 'NEXT_PUBLIC_HYPERLIQUID_FORCE_TESTNET';
 
 function run(command, args) {
   try {
@@ -142,7 +142,7 @@ function chainTo(listener, root, parents) {
   return null;
 }
 
-export function devServerTestnetDiagnostic(target, { appPort, probe = systemProbe } = {}) {
+export function devServerTestnetDiagnostic(target, { appPort, variable, probe = systemProbe } = {}) {
   const checkout = canonicalPath(target);
   const unknown = (detail) => ({ known: false, forced: false, detail });
   const pidFile = path.join(checkout, DEV_SERVER_PID_FILE);
@@ -170,14 +170,14 @@ export function devServerTestnetDiagnostic(target, { appPort, probe = systemProb
       const processMode = nextServerMode(args.argv);
       if (processMode === 'start') return { known: true, forced: false, detail: `pid ${pid} runs next start; its environment cannot prove what the build inlined` };
       if (processMode === 'dev') mode = 'dev';
-      const value = environmentValue(args.env, FORCE_VARIABLE);
+      const value = environmentValue(args.env, variable);
       if (value !== 'true') {
-        return { known: true, forced: false, detail: `pid ${pid} (between app port ${appPort} and next dev pid ${root}) has ${FORCE_VARIABLE}=${value ?? '<unset>'}` };
+        return { known: true, forced: false, detail: `pid ${pid} (between app port ${appPort} and next dev pid ${root}) has ${variable}=${value ?? '<unset>'}` };
       }
     }
   }
   if (mode !== 'dev') return { known: true, forced: false, detail: `no process serving app port ${appPort} runs next dev` };
-  return { known: true, forced: true, detail: `every process from app port ${appPort}'s listeners (cwd ${checkout}) up to next dev pid ${root} has ${FORCE_VARIABLE}=true` };
+  return { known: true, forced: true, detail: `every process from app port ${appPort}'s listeners (cwd ${checkout}) up to next dev pid ${root} has ${variable}=true` };
 }
 
 export const MAINNET_CONFIRMATION = 'REAL_FUNDS';
@@ -195,7 +195,15 @@ export function assertLaunchNetwork(_target, { network, mainnetConfirmation } =
   return requested;
 }
 
+// "a, b and c".
+function listing(names) {
+  return names.length > 1 ? `${names.slice(0, -1).join(', ')} and ${names.at(-1)}` : names.join('');
+}
+
+// `policy`: the venue policy (adapters/terminal/policy.mjs): dependencies,
+// startPath, testnetVariable.
 export async function terminalReadiness({
+  policy,
   target,
   appPort,
   cdpPort,
@@ -207,17 +215,17 @@ export async function terminalReadiness({
   const checks = [];
   const shape = isTerminalCheckout(target);
   checks.push(check('checkout', shape, shape ? 'Next.js checkout with src/features/perpetuals' : `${target} is not a Web Terminal checkout`));
-  const deps = ['next', '@nktkas/hyperliquid', '@metamask/perps-controller'].filter((name) => !existsSync(path.join(target, 'node_modules', name, 'package.json')));
-  checks.push(check('dependencies', deps.length === 0, deps.length === 0 ? 'next, @nktkas/hyperliquid and @metamask/perps-controller installed' : `missing: ${deps.join(', ')} (run npm ci on Node 22)`));
+  const deps = policy.dependencies.filter((name) => !existsSync(path.join(target, 'node_modules', name, 'package.json')));
+  checks.push(check('dependencies', deps.length === 0, deps.length === 0 ? `${listing(policy.dependencies)} installed` : `missing: ${deps.join(', ')} (run npm ci on Node 22)`));
 
   if (appPort) {
-    const status = await httpStatus(`http://127.0.0.1:${appPort}/order/BTC`);
-    checks.push(check('app-dev-server', status === 200, `GET http://localhost:${appPort}/order/BTC -> ${status}`));
+    const status = await httpStatus(`http://127.0.0.1:${appPort}${policy.startPath}`);
+    checks.push(check('app-dev-server', status === 200, `GET http://localhost:${appPort}${policy.startPath} -> ${status}`));
   } else {
     checks.push(check('app-dev-server', false, 'no dev-server port; pass --watcher-port <port> or set TERMINAL_APP_PORT'));
   }
   // Advisory: the browser enforces testnet itself (mainnet-guard.mjs).
-  const testnet = devServerTestnetDiagnostic(target, { appPort });
+  const testnet = devServerTestnetDiagnostic(target, { appPort, variable: policy.testnetVariable });
   checks.push(check('testnet-forced', testnet.known && testnet.forced, testnet.detail, {
     required: false,
     status: testnet.known && testnet.forced ? 'pass' : 'warn',

package/adapters/terminal/policy.mjs

@@ -0,0 +1,35 @@
+// The Web Terminal's venue policy: what the generic web-dapp launch, wallet
+// host and readiness need to know about Hyperliquid. They take it as an
+// argument (the leaf scripts import it from --policy-module, reading its
+// `policy` export), so none of them names the venue. It becomes the terminal
+// plugin's `policy` once recipe libraries can declare adapters; the Terminal's
+// detection and its signature-log rules (_signature-log.mjs) move with it.
+
+import { fileURLToPath } from 'node:url';
+
+import { LINK_HOSTS, TESTNET_TYPED_DATA_POLICY, venueHosts } from './lib/mainnet-guard.mjs';
+
+export const policy = Object.freeze({
+  // network=testnet: the hosts the browser must never reach, and the hosts
+  // whose traffic proves the app serves testnet.
+  venueHosts(checkout) {
+    const { mainnet, testnet } = venueHosts(checkout);
+    return { blocked: mainnet, served: testnet };
+  },
+  // Venue web hosts (pages, coin icons): never blocked, never proof.
+  linkHosts: Object.freeze([...LINK_HOSTS]),
+  // The launch's proof that the block holds: requests to this blocked host
+  // (preferred; else the first blocked host) must fail.
+  probe: Object.freeze({ host: 'api.hyperliquid.xyz', httpPath: '/info', httpBody: '{"type":"meta"}', wsPath: '/ws' }),
+  // The chain the injected wallet starts on (Arbitrum One).
+  startChain: 42161,
+  // Typed data a testnet run never signs.
+  refuseTypedData: TESTNET_TYPED_DATA_POLICY,
+  // The app's first page: the launch opens it, readiness probes it.
+  startPath: '/order/BTC',
+  dependencies: Object.freeze(['next', '@nktkas/hyperliquid', '@metamask/perps-controller']),
+  // The dev-server environment variable that forces testnet (advisory check).
+  testnetVariable: 'NEXT_PUBLIC_HYPERLIQUID_FORCE_TESTNET',
+  // This module, for the wallet host (a separate process).
+  module: fileURLToPath(import.meta.url),
+});

package/adapters/terminal/verify.mjs

@@ -3,18 +3,18 @@
 // Web Terminal slot (checkout, deps, dev server, forced testnet, fixture,
 // browser start probe, MetaMask extension copy, CDP port).
 //
-// Inputs: --target <checkout> [--cdp-port <port>] [--watcher-port <app port>]
+// Inputs: --policy-module <venue policy module> --target <checkout> [--cdp-port <port>] [--watcher-port <app port>]
 //   [--signer extension|injected] [--account <name>] [--json]
 // Outputs: readiness JSON (or a human summary) on stdout. Exit 0 ready; 1 not ready.
 // Never launches the slot browser or the dev server.
 
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { resolveBrowser } from './launch.mjs';
 import { terminalReadiness } from './lib/readiness.mjs';
 
-const usage = 'Usage: verify.mjs --target <checkout> [--cdp-port <port>] [--watcher-port <app port>] [--signer extension|injected] [--account <name>] [--json]';
+const usage = 'Usage: verify.mjs --policy-module <venue policy module> --target <checkout> [--cdp-port <port>] [--watcher-port <app port>] [--signer extension|injected] [--account <name>] [--json]';
 
 if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
   const argv = process.argv.slice(2);
@@ -27,7 +27,14 @@ if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.me
     return index >= 0 ? argv[index + 1] : undefined;
   };
   const num = (raw) => (raw && /^\d+$/u.test(raw) ? Number(raw) : undefined);
+  const policyModule = value('--policy-module');
+  if (!policyModule) {
+    process.stderr.write(`Missing --policy-module\n${usage}\n`);
+    process.exit(2);
+  }
+  const { policy } = await import(pathToFileURL(path.resolve(policyModule)).href);
   const report = await terminalReadiness({
+    policy,
     target: path.resolve(value('--target') ?? process.cwd()),
     appPort: num(value('--watcher-port') ?? process.env.TERMINAL_APP_PORT ?? process.env.WATCHER_PORT),
     cdpPort: num(value('--cdp-port') ?? process.env.RECIPE_CDP_PORT ?? process.env.CDP_PORT),