@deeeed/metamask-harness 0.79.0 → 0.81.0

package/adapters/mobile/bridge-runtime/teaching.cjs

@@ -0,0 +1,20 @@
+'use strict';
+
+// MetaMask Mobile recovery lines for the bridge error codes that
+// @farmslot/adapter-rn classifies; cdp-bridge.cjs prints one after a coded failure.
+//
+// Every coded failure teaches the escape for the caller's ACTUAL situation — a
+// down/transitioning target is recoverable, so the Next: line names the action
+// that brings it back rather than leaving the operator to guess.
+const TEACHING_BY_ERROR_CODE = {
+  NO_TARGET:
+    'Next: bring the app to the foreground with `mm-harness launch <platform>` so a debug target is available.',
+  CDP_TIMEOUT:
+    'Next: the app is reloading or busy — retry, or `mm-harness launch <platform>` to foreground it.',
+  WS_CLOSED:
+    'Next: the Hermes debug page closed (app reload/backgrounded) — retry once the app settles.',
+  METRO_UNREACHABLE:
+    'Next: start Metro with `mm-harness start-metro` (if it is already up, check the slot WATCHER_PORT).',
+};
+
+module.exports = { TEACHING_BY_ERROR_CODE };

package/adapters/mobile/inject.sh

@@ -77,6 +77,22 @@ rsync -a --delete "$RUNNER_DIR/library/recipes/" "$HARNESS_DIR/runner/recipes/"
 rm -rf "$HARNESS_DIR/runner/flows"
 rm -f "$HARNESS_DIR/runner/library.json"
 cp -R "$RUNNER_DIR/adapters/mobile/bridge-runtime" "$HARNESS_DIR/bridge-runtime"
+# cdp-bridge.cjs runs from the target checkout, which cannot resolve the runner's
+# packages; vendor the bridge libraries it requires next to it.
+node - "$RUNNER_DIR" "$HARNESS_DIR/bridge-runtime/node_modules/@farmslot" <<'NODE' || exit 1
+const fs = require('node:fs');
+const path = require('node:path');
+const { createRequire } = require('node:module');
+const [runnerDir, dest] = process.argv.slice(2);
+const requireFromRunner = createRequire(path.join(runnerDir, 'package.json'));
+for (const [name, dirs] of [['adapter-rn', ['bridge-runtime']], ['recipe-runner', ['cdp-broker']]]) {
+  const packageJson = requireFromRunner.resolve(`@farmslot/${name}/package.json`);
+  const target = path.join(dest, name);
+  fs.mkdirSync(target, { recursive: true });
+  fs.copyFileSync(packageJson, path.join(target, 'package.json'));
+  for (const dir of dirs) fs.cpSync(path.join(path.dirname(packageJson), dir), path.join(target, dir), { recursive: true });
+}
+NODE
 chmod -R u+rwX,go+rX "$HARNESS_DIR"
 
 add_git_exclude() {

package/adapters/mobile/launch-console-forwarder.cjs

@@ -2,7 +2,6 @@
 'use strict';
 
 const fs = require('node:fs');
-const path = require('node:path');
 const { spawn } = require('node:child_process');
 
 const args = { port: '', out: '', err: '' };
@@ -25,7 +24,7 @@ if (!args.port || !args.out || !args.err) {
   process.exit(2);
 }
 
-const forwarder = path.join(__dirname, 'bridge-runtime', 'console-forwarder.cjs');
+const forwarder = require.resolve('@farmslot/adapter-rn/bridge-runtime/console-forwarder.cjs');
 const errFd = fs.openSync(args.err, 'a');
 try {
   const child = spawn(process.execPath, [forwarder, '--port', args.port, '--out', args.out], {

package/adapters/mobile/open-device.sh

@@ -28,7 +28,7 @@ PLATFORM="ios"
 TARGET="$PWD"
 SIMULATOR="${SIM_UDID:-${IOS_SIMULATOR:-booted}}"
 ADB_SERIAL_ARG="${ADB_SERIAL:-${ANDROID_SERIAL:-}}"
-ADB_BIN="${MM_HARNESS_ADB_PATH:-}"
+ADB_BIN="${RECIPE_RN_ADB_PATH:-}"
 PREFLIGHT_MODE="${MOBILE_PREFLIGHT_MODE:-fast}"
 PORT="${WATCHER_PORT:-${METRO_PORT:-8081}}"
 UI_ONLY=false
@@ -67,7 +67,7 @@ if [ "$PLATFORM" = "android" ]; then
     printf 'Next: brew install android-platform-tools\n' >&2
     exit 1
   fi
-  export MM_HARNESS_ADB_PATH="$ADB_BIN"
+  export RECIPE_RN_ADB_PATH="$ADB_BIN"
 fi
 
 TARGET="$(cd "$TARGET" && pwd)"

package/adapters/mobile/reload-app.mjs

@@ -4,13 +4,13 @@ import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { createRequire } from 'node:module';
-import { resolveMobileToolPath } from '../../library/actions/mobile/platform/tool-paths.mjs';
+import { resolveMobileToolPath } from '@farmslot/adapter-rn';
 
 const require = createRequire(import.meta.url);
 const WebSocket = require('ws');
-const { discoverTarget, rankRuntimeCandidates } = require('./bridge-runtime/lib/target-discovery.cjs');
-const { brokerSocketPath, createBrokerClient, deviceIdFromUrl } = require('./bridge-runtime/lib/cdp-broker.cjs');
-const { createWSClient } = require('./bridge-runtime/lib/ws-client.cjs');
+const { discoverTarget, rankRuntimeCandidates } = require('@farmslot/adapter-rn/bridge-runtime/lib/target-discovery.cjs');
+const { brokerSocketPath, createBrokerClient, deviceIdFromUrl } = require('@farmslot/recipe-runner/cdp-broker');
+const { createWSClient } = require('@farmslot/adapter-rn/bridge-runtime/lib/ws-client.cjs');
 
 async function observeRuntimeReset(port, target) {
   const socketPath = brokerSocketPath(

package/adapters/mobile/reset-app-data.sh

@@ -6,7 +6,7 @@ PLATFORM="${PLATFORM:-ios}"
 TARGET="$PWD"
 SIMULATOR="${SIM_UDID:-${IOS_SIMULATOR:-booted}}"
 ADB_SERIAL_ARG="${ADB_SERIAL:-${ANDROID_SERIAL:-}}"
-ADB_BIN="${MM_HARNESS_ADB_PATH:-}"
+ADB_BIN="${RECIPE_RN_ADB_PATH:-}"
 MM_RESET_TEMP_ROOT=""
 MM_RESET_STAGING_DIR=""
 

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

@@ -23,13 +23,14 @@ done
 TARGET="$(cd "$TARGET" && pwd -P)"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 if [ -z "$PORT" ] && command -v node >/dev/null 2>&1; then
-  PORT="$(APP_ROOT="$TARGET" CONFIG_PATH="$SCRIPT_DIR/bridge-runtime/lib/config.cjs" node -e "process.stdout.write(String(require(process.env.CONFIG_PATH).resolvePort()))")"
+  PORT="$(cd "$SCRIPT_DIR" && APP_ROOT="$TARGET" node -e "process.stdout.write(String(require('@farmslot/adapter-rn/bridge-runtime/lib/config.cjs').resolvePort()))")"
 fi
 PORT="${PORT:-8081}"
 # shellcheck disable=SC1091
 . "$SCRIPT_DIR/../shared/harness-path.sh"
 LOG_DIR="$TARGET/$(recipe_runtime_dir)" || exit 1
-FORWARDER="$SCRIPT_DIR/bridge-runtime/console-forwarder.cjs"
+command -v node >/dev/null 2>&1 || exit 0
+FORWARDER="$(cd "$SCRIPT_DIR" && node -p "require.resolve('@farmslot/adapter-rn/bridge-runtime/console-forwarder.cjs')")" || exit 1
 PID_FILE="$LOG_DIR/console-forwarder.pid"
 APP_LOG_FILE="$LOG_DIR/app-console.log"
 

package/adapters/mobile/start-metro.sh

@@ -54,18 +54,23 @@ fi
 # only ever inspect or signal a Metro listening on $PORT.
 # shellcheck disable=SC1091
 . "$SCRIPT_DIR/lib/metro-listener.sh"
-HARNESS_METRO_CONFIG="$SCRIPT_DIR/metro-config.cjs"
+# Metro config wrapper, launcher and log helpers ship in @farmslot/adapter-rn.
+ADAPTER_RN_METRO_DIR="$(cd "$SCRIPT_DIR" && node -p "require('node:path').dirname(require.resolve('@farmslot/adapter-rn/metro/metro-config.cjs'))")" || {
+  echo "start-metro: @farmslot/adapter-rn is not installed next to the runner; reinstall the runner." >&2
+  exit 1
+}
+HARNESS_METRO_CONFIG="$ADAPTER_RN_METRO_DIR/metro-config.cjs"
 if [ "${EXPO_OVERRIDE_METRO_CONFIG:-}" = "$HARNESS_METRO_CONFIG" ]; then
-  PRODUCT_METRO_CONFIG="${MM_HARNESS_METRO_BASE_CONFIG:-$TARGET/metro.config.js}"
+  PRODUCT_METRO_CONFIG="${RECIPE_RN_METRO_BASE_CONFIG:-$TARGET/metro.config.js}"
 else
   PRODUCT_METRO_CONFIG="${EXPO_OVERRIDE_METRO_CONFIG:-$TARGET/metro.config.js}"
 fi
-export MM_HARNESS_METRO_PROJECT_ROOT="$TARGET"
-export MM_HARNESS_METRO_BASE_CONFIG="$PRODUCT_METRO_CONFIG"
+export RECIPE_RN_METRO_PROJECT_ROOT="$TARGET"
+export RECIPE_RN_METRO_BASE_CONFIG="$PRODUCT_METRO_CONFIG"
 export EXPO_OVERRIDE_METRO_CONFIG="$HARNESS_METRO_CONFIG"
-MOBILE_METRO_REQUIRED_ENV="${MOBILE_METRO_REQUIRED_ENV:-MM_INFURA_PROJECT_ID METAMASK_BUILD_TYPE METAMASK_ENVIRONMENT} MM_HARNESS_METRO_PROJECT_ROOT MM_HARNESS_METRO_BASE_CONFIG EXPO_OVERRIDE_METRO_CONFIG"
-if [ -n "${MM_HARNESS_METRO_ENV_FINGERPRINT:-}" ]; then
-  MOBILE_METRO_REQUIRED_ENV="$MOBILE_METRO_REQUIRED_ENV MM_HARNESS_METRO_ENV_FINGERPRINT"
+MOBILE_METRO_REQUIRED_ENV="${MOBILE_METRO_REQUIRED_ENV:-MM_INFURA_PROJECT_ID METAMASK_BUILD_TYPE METAMASK_ENVIRONMENT} RECIPE_RN_METRO_PROJECT_ROOT RECIPE_RN_METRO_BASE_CONFIG EXPO_OVERRIDE_METRO_CONFIG"
+if [ -n "${RECIPE_RN_METRO_ENV_FINGERPRINT:-}" ]; then
+  MOBILE_METRO_REQUIRED_ENV="$MOBILE_METRO_REQUIRED_ENV RECIPE_RN_METRO_ENV_FINGERPRINT"
 fi
 
 # RECIPE_RUNTIME_DIR (relative, validated) makes runtime state per-run so jobs
@@ -75,8 +80,8 @@ mkdir -p "$LOG_DIR"
 LOG_FILE="$LOG_DIR/metro.log"
 PID_FILE="$LOG_DIR/metro.pid"
 METRO_BUILD_ENV_FILE="$LOG_DIR/metro-build-env.sh"
-METRO_LOG_GENERATION="$SCRIPT_DIR/metro-log-generation.cjs"
-METRO_LOG_COALESCER="$SCRIPT_DIR/coalesce-metro-log.cjs"
+METRO_LOG_GENERATION="$ADAPTER_RN_METRO_DIR/metro-log-generation.cjs"
+METRO_LOG_COALESCER="$ADAPTER_RN_METRO_DIR/coalesce-metro-log.cjs"
 
 # --- helpers ------------------------------------------------------------------
 
@@ -106,8 +111,8 @@ write_metro_build_env() {
     done
   )" || { rm -f "$temporary"; return 1; }
   eval "$product_values"
-  required_MM_HARNESS_METRO_PROJECT_ROOT="$MM_HARNESS_METRO_PROJECT_ROOT"
-  required_MM_HARNESS_METRO_BASE_CONFIG="$MM_HARNESS_METRO_BASE_CONFIG"
+  required_RECIPE_RN_METRO_PROJECT_ROOT="$RECIPE_RN_METRO_PROJECT_ROOT"
+  required_RECIPE_RN_METRO_BASE_CONFIG="$RECIPE_RN_METRO_BASE_CONFIG"
   required_EXPO_OVERRIDE_METRO_CONFIG="$EXPO_OVERRIDE_METRO_CONFIG"
   [ "$CLEAR" = true ] && clear_value=1
   {
@@ -322,7 +327,7 @@ else
     )
     [ -z "$METRO_WORKERS" ] || launcher_args+=(--workers "$METRO_WORKERS")
     [ "$CLEAR" = true ] && launcher_args+=(--clear)
-    node "$SCRIPT_DIR/launch-metro.cjs" "${launcher_args[@]}"
+    node "$ADAPTER_RN_METRO_DIR/launch-metro.cjs" "${launcher_args[@]}"
   ) || exit 1
   STARTED_METRO_PID="$(cat "$PID_FILE" 2>/dev/null || true)"
 

package/adapters/mobile/wait-for-bridge.cjs

@@ -14,10 +14,10 @@ const {
   describeRequested,
   describeTargets,
   hasMatchingRoute,
-} = require('./bridge-runtime/lib/match-bridge-target.cjs');
+} = require('@farmslot/adapter-rn/bridge-runtime/lib/match-bridge-target.cjs');
 const {
   rankRuntimeCandidates,
-} = require('./bridge-runtime/lib/target-discovery.cjs');
+} = require('@farmslot/adapter-rn/bridge-runtime/lib/target-discovery.cjs');
 
 const DEFAULT_MAX_POLLS = 90;
 const DEFAULT_POLL_INTERVAL_MS = 2_000;

package/adapters/shared/harness-source-fingerprint.mjs

@@ -8,7 +8,7 @@
 // the next launch refreshes every slot from it.
 //
 // Source files count by size + mtime, so it is cheap enough to run on every launch;
-// the only file read is @farmslot/adapter-web's package.json, for its version. No
+// the only files read are the vendored packages' package.json, for their versions. No
 // Date.now()/random is used (both would break determinism).
 import fs from 'node:fs';
 import path from 'node:path';
@@ -25,17 +25,22 @@ export function harnessSourceFingerprint(runnerDir, adapter = 'extension') {
   for (const rel of sourceDirs) {
     collect(path.join(runnerDir, rel), runnerDir, entries);
   }
-  // inject.mjs copies the browser helpers from @farmslot/adapter-web, so its sources
-  // are overlay inputs too; label them by package so the install location does not count.
-  if (adapter === 'extension') {
-    const packageJson = createRequire(path.join(runnerDir, 'package.json')).resolve('@farmslot/adapter-web/package.json');
+  // The injectors copy package files into the overlay (Extension: @farmslot/adapter-web's
+  // browser helpers; Mobile: the bridge libraries cdp-bridge.cjs requires), so those
+  // sources are overlay inputs too; label them by package so the install location
+  // does not count.
+  const vendored = adapter === 'extension'
+    ? [['@farmslot/adapter-web', ['src']]]
+    : [['@farmslot/adapter-rn', ['bridge-runtime']], ['@farmslot/recipe-runner', ['cdp-broker']]];
+  for (const [name, dirs] of vendored) {
+    const packageJson = createRequire(path.join(runnerDir, 'package.json')).resolve(`${name}/package.json`);
     const packageRoot = path.dirname(packageJson);
     const packageEntries = [];
-    collect(path.join(packageRoot, 'src'), packageRoot, packageEntries);
-    entries.push(...packageEntries.map((entry) => `@farmslot/adapter-web/${entry}`));
+    for (const dir of dirs) collect(path.join(packageRoot, dir), packageRoot, packageEntries);
+    entries.push(...packageEntries.map((entry) => `${name}/${entry}`));
     // npm tarballs carry fixed mtimes, so an upgrade can keep every size and mtime:
     // the version marks it.
-    entries.push(`@farmslot/adapter-web@${JSON.parse(fs.readFileSync(packageJson, 'utf8')).version}`);
+    entries.push(`${name}@${JSON.parse(fs.readFileSync(packageJson, 'utf8')).version}`);
   }
   entries.sort();
   return crypto.createHash('sha256').update(entries.join('\n')).digest('hex');

package/adapters/shared/open-debug.mjs

@@ -15,10 +15,10 @@ import path from 'node:path';
 const require = createRequire(import.meta.url);
 const {
   discoverTarget,
-} = require('../mobile/bridge-runtime/lib/target-discovery.cjs');
+} = require('@farmslot/adapter-rn/bridge-runtime/lib/target-discovery.cjs');
 const {
   deviceIdFromUrl,
-} = require('../mobile/bridge-runtime/lib/cdp-broker.cjs');
+} = require('@farmslot/recipe-runner/cdp-broker');
 
 function usage() {
   console.error(`Usage:

package/adapters/shared/sync-wallet-fixture.sh

@@ -60,12 +60,15 @@ fi
 
 # Farmslot slot sync (requires farmslot root and sync-fixtures.sh).
 if [ -n "$SLOT_ID" ]; then
+  # An explicit FARMSLOT_ROOT wins; otherwise the operator checkout's farm script.
   FARMSLOT_ROOT="${FARMSLOT_ROOT:-}"
-  for candidate in "$HOME/dev/farmslot" "$HOME/farmslot"; do
-    [ -d "$candidate/scripts" ] || continue
-    FARMSLOT_ROOT="$candidate"
-    break
-  done
+  if [ -z "$FARMSLOT_ROOT" ]; then
+    for candidate in "$HOME/dev/farmslot" "$HOME/farmslot"; do
+      [ -f "$candidate/scripts/sync-fixtures.sh" ] || continue
+      FARMSLOT_ROOT="$candidate"
+      break
+    done
+  fi
   if [ -n "$FARMSLOT_ROOT" ] && [ -f "$FARMSLOT_ROOT/scripts/sync-fixtures.sh" ]; then
     if bash "$FARMSLOT_ROOT/scripts/sync-fixtures.sh" --slot "$SLOT_ID" 2>/dev/null; then
       [ -f "$CANONICAL" ] && exit 0

package/adapters/terminal/cleanup.mjs

@@ -11,7 +11,8 @@ 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 { recipeHarnessPath } from '@farmslot/recipe-cli/harness';
+import { walletFixturePath } from '../../library/actions/harness-exports.mjs';
 import { terminalRuntimeDir } from '../../library/actions/terminal/platform/runtime.mjs';
 import { stopConsoleCollector, stopTerminalBrowser } from './lib/processes.mjs';
 

package/adapters/terminal/inject.mjs

@@ -13,7 +13,8 @@ import { copyFileSync, chmodSync, existsSync, mkdirSync, readFileSync, writeFile
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import { recipeHarnessPath, recipeRuntimeDir, walletFixturePath } from '../../library/actions/harness-exports.mjs';
+import { recipeHarnessPath, recipeRuntimeDir } from '@farmslot/recipe-cli/harness';
+import { walletFixturePath } from '../../library/actions/harness-exports.mjs';
 import { terminalRuntimeDir } from '../../library/actions/terminal/platform/runtime.mjs';
 import { isTerminalCheckout } from './lib/readiness.mjs';
 

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),