@deeeed/metamask-harness 0.70.1 → 0.71.0

package/library/actions/terminal/platform/page.mjs

@@ -0,0 +1,247 @@
+// Select the CDP page a terminal UI action drives: the app tab (default) or the
+// MetaMask wallet surface (side panel / notification / popup) that shows the
+// pending dapp request. Pages are never brought to front unless
+// MM_HARNESS_FOCUS_BROWSER=1, as in the Extension adapter: Page.bringToFront
+// activates the browser on macOS and takes the operator's keyboard focus. The
+// app tab is the only tab of its window (the wallet host closes the others),
+// so it stays the window's active tab and keeps painting without it.
+
+import { resolveSlowMo } from '../../../../adapters/terminal/lib/display.mjs';
+import { HUD_ELEMENT } from '../../../../adapters/terminal/lib/hud.mjs';
+import { isAppUrl } from '../../../../adapters/terminal/lib/origin.mjs';
+import { cdpListenerPids } from '../../../../adapters/terminal/lib/processes.mjs';
+import { appOrigin, cdpPort, readBrowserState } from './runtime.mjs';
+import { importRecipeHarnessRuntimeCdp } from '../../harness-exports.mjs';
+
+const { CdpSession, CdpWebPage, listCdpTargets, sleep } = await importRecipeHarnessRuntimeCdp();
+
+export const WALLET_SURFACES = Object.freeze(['sidepanel.html', 'notification.html', 'popup.html']);
+const CONFIRMATION_ROUTE = /^\/(connect|confirm-transaction|confirmation|confirm|signature-request)(\/|$)/u;
+
+export function resolveSurface(node = {}) {
+  const surface = node.surface == null ? 'app' : String(node.surface);
+  if (surface !== 'app' && surface !== 'wallet') {
+    throw new Error(`surface must be app or wallet, got ${JSON.stringify(node.surface)}.`);
+  }
+  return surface;
+}
+
+export function isWalletRequestTarget(target, extensionId) {
+  if (target.type !== 'page' || !target.url) return false;
+  const origin = extensionId ? `chrome-extension://${extensionId}/` : 'chrome-extension://';
+  if (!target.url.startsWith(origin)) return false;
+  if (!WALLET_SURFACES.some((surface) => target.url.includes(`/${surface}`))) return false;
+  const route = (target.url.split('#')[1] ?? '').split('?')[0];
+  return CONFIRMATION_ROUTE.test(route);
+}
+
+export function pickAppTarget(targets, origin) {
+  const pages = targets.filter((target) => target.type === 'page');
+  return pages.find((target) => isAppUrl(target.url, origin)) ?? pages.find((target) => target.url === 'about:blank') ?? null;
+}
+
+export async function selectTerminalTarget(input) {
+  const node = input.node ?? {};
+  const port = cdpPort(input);
+  const surface = resolveSurface(node);
+  const state = input.context?.projectRoot ? await readBrowserState(input.context.projectRoot) : null;
+  if (surface === 'wallet') {
+    if (state?.signer === 'injected') {
+      throw new Error('surface=wallet needs signer=extension; the injected strict wallet has no confirmation UI.');
+    }
+    const timeoutMs = Number(node.wallet_timeout_ms ?? node.timeout_ms ?? 20000);
+    const deadline = Date.now() + timeoutMs;
+    while (true) {
+      const targets = await listCdpTargets('127.0.0.1', port);
+      const match = targets.find((target) => isWalletRequestTarget(target, state?.extension?.id));
+      if (match) return { target: match, surface, port };
+      if (Date.now() >= deadline) {
+        throw new Error(`No MetaMask confirmation surface (side panel / notification) showed a pending request within ${timeoutMs}ms.`);
+      }
+      await sleep(250);
+    }
+  }
+  const origin = appOrigin(input);
+  const target = pickAppTarget(await listCdpTargets('127.0.0.1', port), origin);
+  if (!target) {
+    throw new Error(`No app tab on CDP ${port}. Next: run metamask.app.launch before UI nodes.`);
+  }
+  return { target, surface, port };
+}
+
+// MetaMask pages run under LavaMoat scuttling, so main-world helpers (timers in
+// wait loops) are unavailable there; evaluate in an isolated world that shares
+// the DOM instead.
+class WalletSurfacePage extends CdpWebPage {
+  evaluate(expression) {
+    return this.evaluateInIsolatedWorld(expression, 'mm-terminal-wallet-surface');
+  }
+}
+
+// Number inputs ignore select(), so the generic setInput would append to a
+// prefilled value (the order form prefills the mid price). Clear the field with
+// the editor's selectAll command, as a user's Cmd+A would, type over the
+// selection and require the field to read back exactly that value.
+// Screenshots are evidence of the app, so the recipe HUD is hidden while one
+// is captured and shown again afterwards.
+export function hudVisibilityExpression(visible) {
+  return `(() => { const host = document.documentElement.querySelector(':scope > ${HUD_ELEMENT}'); if (!host) return false; host.style.visibility = ${JSON.stringify(visible ? '' : 'hidden')}; return true; })()`;
+}
+
+class TerminalAppPage extends CdpWebPage {
+  async screenshot(context, relPath, metadata = {}) {
+    const hidden = await this.evaluate(hudVisibilityExpression(false)).catch(() => false);
+    try {
+      return await super.screenshot(context, relPath, metadata);
+    } finally {
+      if (hidden) await this.evaluate(hudVisibilityExpression(true)).catch(() => {});
+    }
+  }
+
+  // A tab whose first load is still pending (a slow dev-server compile) has no
+  // committed history entry yet; navigating away from it is still fine.
+  async currentNavigationUrl() {
+    const history = await this.session.call('Page.getNavigationHistory');
+    const committed = history.entries?.[history.currentIndex]?.url;
+    if (committed) return committed;
+    return (await this.evaluate('location.href')) || 'about:blank';
+  }
+
+  // A dev-server overlay (the Next.js issues badge) can cover part of a
+  // control. Click the first point of the control that is actually on top, as a
+  // user would aim at its visible part; fail when no part is reachable.
+  async click(selector, timeoutMs = 10000) {
+    // Rows and dialogs render after venue streams update; wait for the control
+    // to exist and expose a reachable point before giving up.
+    const deadline = Date.now() + timeoutMs;
+    let target = await this.#clickTarget(selector);
+    while (target.error && Date.now() < deadline) {
+      await new Promise((resolve) => setTimeout(resolve, 250));
+      target = await this.#clickTarget(selector);
+    }
+    if (target.error) throw new Error(target.error);
+    await this.clickPoint(target.x, target.y);
+    return { clicked: true, selector, tagName: target.tagName, partiallyCovered: target.covered };
+  }
+
+  #clickTarget(selector) {
+    return this.evaluateInIsolatedWorld(`(() => {
+      const el = document.querySelector(${JSON.stringify(selector)});
+      if (!el) return { error: 'Selector not found: ' + ${JSON.stringify(selector)} };
+      el.scrollIntoView({ block: 'center', inline: 'center' });
+      const rect = el.getBoundingClientRect();
+      if (rect.width === 0 || rect.height === 0) return { error: 'Target has no box: ' + ${JSON.stringify(selector)} };
+      const xs = [0.5, 0.25, 0.75, 0.1, 0.9];
+      const ys = [0.5, 0.25, 0.75, 0.1, 0.9];
+      for (const fy of ys) {
+        for (const fx of xs) {
+          const x = rect.left + rect.width * fx;
+          const y = rect.top + rect.height * fy;
+          const hit = document.elementFromPoint(x, y);
+          if (hit && (hit === el || el.contains(hit))) return { x, y, tagName: el.tagName, covered: !(fx === 0.5 && fy === 0.5) };
+        }
+      }
+      const top = document.elementFromPoint(rect.left + rect.width / 2, rect.top + rect.height / 2);
+      return { error: 'Target is fully covered by ' + (top ? top.tagName.toLowerCase() : 'nothing') + ': ' + ${JSON.stringify(selector)} };
+    })()`, 'mm-terminal-click');
+  }
+
+  async setInput(selector, value) {
+    const text = String(value ?? '');
+    const focus = await this.evaluate(`(() => {
+      const root = document.querySelector(${JSON.stringify(selector)});
+      const el = root && (root.matches('input, textarea') ? root : root.querySelector('input, textarea'));
+      if (!el) throw new Error('Input target not found: ' + ${JSON.stringify(selector)});
+      if (el.disabled) throw new Error('Input target is disabled: ' + ${JSON.stringify(selector)});
+      el.scrollIntoView({ block: 'center', inline: 'nearest' });
+      el.focus();
+      return { tagName: el.tagName, previousValue: el.value ?? '' };
+    })()`);
+    await this.session.call('Input.dispatchKeyEvent', { type: 'rawKeyDown', key: 'a', code: 'KeyA', windowsVirtualKeyCode: 65, commands: ['selectAll'] });
+    await this.session.call('Input.dispatchKeyEvent', { type: 'keyUp', key: 'a', code: 'KeyA', windowsVirtualKeyCode: 65 });
+    // Replace the selection in one edit: deleting first lets the order form
+    // refill the empty limit price with the live mid before the text lands.
+    if (text) {
+      await this.session.call('Input.insertText', { text });
+    } else {
+      await this.session.call('Input.dispatchKeyEvent', { type: 'rawKeyDown', key: 'Backspace', code: 'Backspace', windowsVirtualKeyCode: 8 });
+      await this.session.call('Input.dispatchKeyEvent', { type: 'keyUp', key: 'Backspace', code: 'Backspace', windowsVirtualKeyCode: 8 });
+    }
+    const after = await this.evaluate(`(() => {
+      const root = document.querySelector(${JSON.stringify(selector)});
+      const el = root && (root.matches('input, textarea') ? root : root.querySelector('input, textarea'));
+      if (!el) throw new Error('Input target disappeared after typing');
+      el.dispatchEvent(new Event('change', { bubbles: true }));
+      return { value: el.value ?? '' };
+    })()`);
+    if (!inputReadsBack(text, after.value)) {
+      throw new Error(`Input target value mismatch after typing ${selector}: expected ${JSON.stringify(text)}, got ${JSON.stringify(after.value)}.`);
+    }
+    return { set: true, selector, tagName: focus.tagName, previousValue: focus.previousValue, value: after.value };
+  }
+}
+
+// A typed number may come back decorated by a formatting field ("1" -> "1x",
+// "15" -> "$15"); the digits must still match exactly. Anything else must read
+// back verbatim.
+export function inputReadsBack(typed, actual) {
+  if (actual === typed) return true;
+  if (!/^-?[\d.,]+$/u.test(typed)) return false;
+  const digits = (value) => String(value).replace(/[^\d.-]/gu, '');
+  return digits(actual) === digits(typed) && digits(actual) !== '';
+}
+
+// Slow-mo resolved at launch (--slow-mo, slow_mo_ms, TERMINAL_SLOW_MO), else
+// the current TERMINAL_SLOW_MO.
+export function slowMoFor(browserState, env = process.env) {
+  if (Number.isInteger(browserState?.slowMoMs)) return browserState.slowMoMs;
+  return resolveSlowMo({ env });
+}
+
+export function focusBrowserRequested(env = process.env) {
+  return env.MM_HARNESS_FOCUS_BROWSER === '1';
+}
+
+// Defence in depth before a wallet confirmation: the app port is still served
+// by the processes that served it when the browser launched. A later, more
+// specific bind on the port would otherwise put another server behind the tab.
+export function assertAppListenersUnchanged(state, current) {
+  const recorded = Array.isArray(state?.appListeners) ? state.appListeners : [];
+  if (recorded.length === 0) return;
+  const added = current.filter((pid) => !recorded.includes(pid));
+  if (added.length > 0) {
+    throw new Error(`the app port is now also served by pid ${added.join(', ')}, which did not serve it at launch; refusing to confirm a wallet request.`);
+  }
+}
+
+const PAGE_DEPS = Object.freeze({
+  listeners: (port) => cdpListenerPids(port),
+  select: (input) => selectTerminalTarget(input),
+  connect: (url) => CdpSession.connect(url),
+  browserState: (projectRoot) => readBrowserState(projectRoot),
+  sleep: (ms) => sleep(ms),
+  env: process.env,
+});
+
+export async function withTerminalPage(input, callback, deps = PAGE_DEPS) {
+  const state = input.context?.projectRoot ? await deps.browserState(input.context.projectRoot) : null;
+  const delay = slowMoFor(state, deps.env);
+  if (delay > 0) await deps.sleep(delay);
+  const { target, surface, port } = await deps.select(input);
+  if (surface === 'wallet' && state?.appOrigin) {
+    assertAppListenersUnchanged(state, deps.listeners(Number(new URL(state.appOrigin).port)));
+  }
+  const session = await deps.connect(target.webSocketDebuggerUrl);
+  try {
+    await session.call('Page.enable');
+    await session.call('Runtime.enable');
+    if (focusBrowserRequested(deps.env)) await session.call('Page.bringToFront');
+    const page = surface === 'wallet' ? new WalletSurfacePage(session) : new TerminalAppPage(session);
+    const result = await callback(page);
+    return result && typeof result === 'object' && !Array.isArray(result)
+      ? { ...result, surface, cdpPort: port, targetUrl: target.url.replace(/0x[0-9a-fA-F]{40}/gu, '<address>') }
+      : result;
+  } finally {
+    session.close();
+  }
+}

package/library/actions/terminal/platform/runtime.mjs

@@ -0,0 +1,200 @@
+// Resolve the Web Terminal slot runtime: ports, runtime paths, browser state and
+// wallet-fixture accounts. Key material is only ever returned as a viem account
+// object; callers must never log or persist it.
+
+import { realpathSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { mnemonicToAccount, privateKeyToAccount } from 'viem/accounts';
+
+import { recipeRuntimeDir, walletFixturePath } from '../../harness-exports.mjs';
+
+export const SIGNER_MODES = Object.freeze(['extension', 'injected']);
+export const DEFAULT_ACCOUNT = 'dev1';
+
+// The checkout's canonical path: a symlinked or /tmp-vs-/private/tmp spelling
+// of the same slot must name the same runtime dir, profile and pid owners.
+export function canonicalPath(target) {
+  const resolved = path.resolve(target);
+  try {
+    return realpathSync(resolved);
+  } catch {
+    return resolved;
+  }
+}
+
+export function terminalRuntimeDir(projectRoot) {
+  return path.join(canonicalPath(projectRoot), recipeRuntimeDir(), 'terminal');
+}
+
+export function terminalRuntimePath(projectRoot, ...segments) {
+  return path.join(terminalRuntimeDir(projectRoot), ...segments);
+}
+
+function portFrom(raw, label) {
+  if (raw === undefined || raw === null || raw === '') return undefined;
+  const port = Number(raw);
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+    throw new Error(`${label} must be a TCP port, got ${JSON.stringify(raw)}.`);
+  }
+  return port;
+}
+
+// The slot's Next.js dev server. Farmslot passes it as --watcher-port {{port}};
+// TERMINAL_APP_PORT is the explicit override.
+export function appPort(input = {}, env = process.env) {
+  const port =
+    portFrom(input.node?.app_port, 'app_port') ??
+    portFrom(env.TERMINAL_APP_PORT, 'TERMINAL_APP_PORT') ??
+    portFrom(env.RECIPE_WATCHER_PORT, 'RECIPE_WATCHER_PORT') ??
+    portFrom(env.WATCHER_PORT, 'WATCHER_PORT');
+  if (!port) {
+    throw new Error(
+      'terminal adapter requires the slot dev-server port.\n' +
+      'Next: pass --watcher-port <port> (Farmslot: {{port}}) or set TERMINAL_APP_PORT.',
+    );
+  }
+  return port;
+}
+
+export function appOrigin(input = {}, env = process.env) {
+  return `http://localhost:${appPort(input, env)}`;
+}
+
+export function cdpPort(input = {}, env = process.env) {
+  const port =
+    portFrom(input.node?.cdp_port, 'cdp_port') ??
+    portFrom(env.RECIPE_CDP_PORT, 'RECIPE_CDP_PORT') ??
+    portFrom(env.CDP_PORT, 'CDP_PORT');
+  if (!port) {
+    throw new Error(
+      'terminal adapter requires a per-slot browser CDP port.\n' +
+      'Next: pass --cdp-port <port> (Farmslot: {{cdp_port}}).',
+    );
+  }
+  return port;
+}
+
+export async function readJsonFile(file) {
+  try {
+    return JSON.parse(await readFile(file, 'utf8'));
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+export async function writePrivateJson(file, value) {
+  await writeFile(file, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+}
+
+export async function readBrowserState(projectRoot) {
+  return readJsonFile(terminalRuntimePath(projectRoot, 'browser.json'));
+}
+
+export function resolveSigner(raw) {
+  const signer = raw == null || raw === '' ? 'extension' : String(raw);
+  if (!SIGNER_MODES.includes(signer)) {
+    throw new Error(`signer must be one of ${SIGNER_MODES.join(' | ')}, got ${JSON.stringify(raw)}.`);
+  }
+  return signer;
+}
+
+// Account name precedence: node.account_name → node.account (when not an
+// address) → the running browser's account → dev1.
+export function accountName(input = {}, browserState = null) {
+  const explicit = input.node?.account_name ?? input.node?.account;
+  if (typeof explicit === 'string' && explicit.trim() && !/^0x[0-9a-fA-F]{40}$/u.test(explicit.trim())) {
+    return explicit.trim();
+  }
+  return browserState?.account?.name ?? DEFAULT_ACCOUNT;
+}
+
+export function fixturePath(projectRoot, env = process.env) {
+  return env.RECIPE_WALLET_FIXTURE ? path.resolve(env.RECIPE_WALLET_FIXTURE) : walletFixturePath(projectRoot);
+}
+
+export async function loadWalletFixture(projectRoot, env = process.env) {
+  const file = fixturePath(projectRoot, env);
+  const fixture = await readJsonFile(file);
+  if (!fixture) {
+    throw new Error(
+      `wallet fixture not found at ${file}.\n` +
+      'Next: mm-harness install --adapter terminal --target <checkout> with RECIPE_WALLET_FIXTURE set, or copy the fixture there (0600).',
+    );
+  }
+  if (!Array.isArray(fixture.accounts) || fixture.accounts.length === 0) {
+    throw new Error(`wallet fixture at ${file} has no accounts.`);
+  }
+  return { file, fixture };
+}
+
+export function fixtureEntry(fixture, name) {
+  const entry = fixture.accounts.find((account) => account?.name === name);
+  if (!entry) {
+    const names = fixture.accounts.map((account) => account?.name).filter(Boolean).join(', ');
+    throw new Error(`wallet fixture has no account named "${name}". Available: ${names}.`);
+  }
+  if (entry.type !== 'mnemonic' && entry.type !== 'privateKey') {
+    throw new Error(`wallet fixture account "${name}" must be mnemonic or privateKey, got "${entry.type}".`);
+  }
+  if (typeof entry.value !== 'string' || !entry.value.trim()) {
+    throw new Error(`wallet fixture account "${name}" has no value.`);
+  }
+  return entry;
+}
+
+// Mnemonics use BIP-44 index 0, the MetaMask default and the derivation the
+// Extension fixture flow imports.
+export function viemAccountFromEntry(entry) {
+  if (entry.type === 'mnemonic') return mnemonicToAccount(entry.value.trim(), { addressIndex: 0 });
+  const raw = entry.value.trim();
+  const key = raw.startsWith('0x') ? raw : `0x${raw}`;
+  if (!/^0x[0-9a-fA-F]{64}$/u.test(key)) {
+    throw new Error(`wallet fixture privateKey account "${entry.name}" is not a 32-byte hex key.`);
+  }
+  return privateKeyToAccount(key);
+}
+
+export async function fixtureAccount(projectRoot, name, env = process.env) {
+  const { fixture } = await loadWalletFixture(projectRoot, env);
+  return viemAccountFromEntry(fixtureEntry(fixture, name));
+}
+
+// Address-only view of the account a node targets: an explicit address wins
+// (read-only use), otherwise the fixture account is derived.
+export async function resolveAccountAddress(input, env = process.env) {
+  const raw = input.node?.account;
+  if (typeof raw === 'string' && /^0x[0-9a-fA-F]{40}$/u.test(raw.trim())) {
+    return { name: null, address: raw.trim() };
+  }
+  const projectRoot = input.context?.projectRoot;
+  const browserState = projectRoot ? await readBrowserState(projectRoot) : null;
+  const name = accountName(input, browserState);
+  const account = await fixtureAccount(projectRoot, name, env);
+  return { name, address: account.address };
+}
+
+export async function loadInput() {
+  const inputPath = process.argv[2] || process.env.METAMASK_RECIPE_ADAPTER_INPUT;
+  if (!inputPath) throw new Error('Missing live adapter input path.');
+  return JSON.parse(await readFile(inputPath, 'utf8'));
+}
+
+export function isDirectRun(importMetaUrl) {
+  const entry = process.argv[1];
+  return Boolean(entry) && importMetaUrl === pathToFileURL(entry).href;
+}
+
+export async function runAdapter(callback) {
+  const input = await loadInput();
+  try {
+    const output = await callback(input);
+    await writeFile(input.outputPath, `${JSON.stringify(output, null, 2)}\n`);
+  } catch (error) {
+    process.stderr.write(`[terminal] ${input.action} failed: ${error?.stack ?? error}\n`);
+    process.exitCode = 1;
+  }
+}

package/library/actions/terminal/ui/navigate.mjs

@@ -0,0 +1,31 @@
+// Navigate the terminal app tab to a product page (order/<MARKET>, portfolio)
+// or an explicit app path, and wait for the document to be ready.
+
+import { appOrigin, isDirectRun, runAdapter } from '../platform/runtime.mjs';
+import { withTerminalPage } from '../platform/page.mjs';
+
+export function pathFor(node = {}) {
+  if (typeof node.path === 'string' && node.path.startsWith('/')) return node.path;
+  const page = node.page == null ? 'order' : String(node.page);
+  if (page === 'order' || page === 'market') {
+    const market = String(node.market ?? node.symbol ?? 'BTC').toUpperCase();
+    if (!/^[A-Z0-9:_-]+$/u.test(market)) throw new Error(`unsupported market symbol ${JSON.stringify(market)}`);
+    return `/order/${market}`;
+  }
+  if (page === 'portfolio') return '/portfolio';
+  if (page === 'home') return '/';
+  throw new Error(`ui.navigate page must be order, portfolio or home (or pass path), got ${JSON.stringify(page)}.`);
+}
+
+export async function navigate(input) {
+  const node = input.node ?? {};
+  const url = `${appOrigin(input)}${pathFor(node)}`;
+  return withTerminalPage({ ...input, node: { ...node, surface: 'app' } }, async (page) => {
+    await page.navigate(url, Number(node.timeout_ms ?? 120000));
+    await page.waitForDocumentReady({ expectedUrl: url, timeoutMs: Number(node.timeout_ms ?? 120000) });
+    if (node.settle_ms) await new Promise((resolve) => setTimeout(resolve, Number(node.settle_ms)));
+    return { action: input.action, url, page: node.page ?? 'order', market: node.market ?? null };
+  });
+}
+
+if (isDirectRun(import.meta.url)) runAdapter((input) => navigate(input));

package/library/actions/terminal/wallet/_signature-log.mjs

@@ -0,0 +1,177 @@
+// Read, window and assert the terminal wallet request log the wallet host
+// writes: one JSON line per request the app sent to the main wallet (method,
+// EIP-712 primary type, domain/active chain, outcome) and, in extension mode,
+// one line per confirmation window MetaMask opened. Never holds params,
+// messages or signatures.
+
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { terminalRuntimePath } from '../platform/runtime.mjs';
+
+export const L1_PRIMARY_TYPE = 'Agent';
+export const L1_CHAIN_ID = 1337;
+
+export function signatureLogPath(projectRoot) {
+  return terminalRuntimePath(projectRoot, 'wallet-requests.jsonl');
+}
+
+export function signatureCursorPath(projectRoot) {
+  return terminalRuntimePath(projectRoot, 'wallet-requests.cursor.json');
+}
+
+export function parseLog(text) {
+  return text
+    .split('\n')
+    .filter((line) => line.trim())
+    .map((line, index) => {
+      try {
+        return { seq: index, ...JSON.parse(line) };
+      } catch {
+        return { seq: index, kind: 'unparseable' };
+      }
+    });
+}
+
+export async function readLog(projectRoot) {
+  try {
+    return parseLog(await readFile(signatureLogPath(projectRoot), 'utf8'));
+  } catch (error) {
+    if (error?.code === 'ENOENT') return [];
+    throw error;
+  }
+}
+
+export async function readCursor(projectRoot) {
+  try {
+    const cursor = JSON.parse(await readFile(signatureCursorPath(projectRoot), 'utf8'));
+    return Number.isInteger(cursor.seq) ? cursor.seq : 0;
+  } catch (error) {
+    if (error?.code === 'ENOENT') return 0;
+    throw error;
+  }
+}
+
+export async function writeCursor(projectRoot, seq) {
+  await writeFile(signatureCursorPath(projectRoot), `${JSON.stringify({ seq, at: new Date().toISOString() })}\n`, { mode: 0o600 });
+}
+
+// "HyperliquidTransaction:ApproveAgent" → "ApproveAgent".
+export function shortPrimaryType(primaryType) {
+  if (primaryType == null) return null;
+  const raw = String(primaryType);
+  return raw.includes(':') ? raw.slice(raw.lastIndexOf(':') + 1) : raw;
+}
+
+export function isTypedDataRequest(entry) {
+  return entry.kind === 'request' && /^eth_signTypedData/u.test(String(entry.method));
+}
+
+export function isL1Request(entry) {
+  return isTypedDataRequest(entry) &&
+    (shortPrimaryType(entry.primaryType) === L1_PRIMARY_TYPE || Number(entry.domainChainId) === L1_CHAIN_ID);
+}
+
+export function summarize(entries) {
+  const requests = entries.filter((entry) => entry.kind === 'request');
+  const typed = requests.filter(isTypedDataRequest);
+  const byPrimaryType = {};
+  for (const entry of typed) {
+    const key = shortPrimaryType(entry.primaryType) ?? '<none>';
+    byPrimaryType[key] ??= { requested: 0, signed: 0, rejected: 0, chainIds: [] };
+    byPrimaryType[key].requested += 1;
+    if (entry.outcome === 'signed') byPrimaryType[key].signed += 1;
+    if (entry.outcome === 'rejected' || entry.outcome === 'error') byPrimaryType[key].rejected += 1;
+    if (!byPrimaryType[key].chainIds.includes(entry.domainChainId)) byPrimaryType[key].chainIds.push(entry.domainChainId);
+  }
+  const byMethod = {};
+  for (const entry of requests) byMethod[entry.method] = (byMethod[entry.method] ?? 0) + 1;
+  return {
+    requests: requests.length,
+    typedDataRequests: typed.length,
+    l1Requests: typed.filter(isL1Request).length,
+    confirmationsShown: entries.filter((entry) => entry.kind === 'confirmation-shown').length,
+    // Testnet enforcement and evidence gaps: each one fails the assertion.
+    blockedMainnet: entries.filter((entry) => entry.kind === 'blocked-mainnet' && !entry.probe).length,
+    refusedMainnet: entries.filter((entry) => entry.kind === 'refused-mainnet').length,
+    unattributed: entries.filter((entry) => entry.kind === 'unattributed').length,
+    // Calls from an iframe, a foreign page or a blank document: refused, kept as evidence.
+    outsideAppFrame: entries.filter((entry) => entry.kind === 'outside-app-frame').length,
+    byPrimaryType,
+    byMethod,
+  };
+}
+
+function exact(label, actual, expected, failures) {
+  if (actual !== expected) failures.push(`${label}: expected ${expected}, got ${actual}`);
+}
+
+// Every expectation is optional; max_l1_requests defaults to 0 because an L1
+// (agent-signed) payload must never reach the main wallet.
+export function evaluateSignatureLog(entries, node = {}) {
+  const summary = summarize(entries);
+  const typed = entries.filter(isTypedDataRequest);
+  const failures = [];
+  if (summary.blockedMainnet > 0) failures.push(`the browser tried to reach a mainnet venue ${summary.blockedMainnet} time(s) (blocked-mainnet)`);
+  if (summary.refusedMainnet > 0) failures.push(`the app asked the wallet to sign ${summary.refusedMainnet} mainnet action(s) (refused-mainnet)`);
+  if (summary.unattributed > 0) failures.push(`${summary.unattributed} wallet log entr(y/ies) could not be attributed to the app's top frame (unattributed)`);
+  const maxL1 = node.max_l1_requests == null ? 0 : Number(node.max_l1_requests);
+  if (summary.l1Requests > maxL1) {
+    failures.push(`L1 requests reached the main wallet: ${summary.l1Requests} > ${maxL1}`);
+  }
+  if (Array.isArray(node.allowed_primary_types)) {
+    const allowed = new Set(node.allowed_primary_types.map(shortPrimaryType));
+    for (const entry of typed) {
+      const type = shortPrimaryType(entry.primaryType);
+      if (!allowed.has(type)) failures.push(`primary type ${type} (seq ${entry.seq}) is not allowed`);
+    }
+  }
+  if (node.counts && typeof node.counts === 'object') {
+    for (const [type, expected] of Object.entries(node.counts)) {
+      exact(`signed ${shortPrimaryType(type)}`, summary.byPrimaryType[shortPrimaryType(type)]?.signed ?? 0, Number(expected), failures);
+    }
+  }
+  if (node.request_counts && typeof node.request_counts === 'object') {
+    for (const [type, expected] of Object.entries(node.request_counts)) {
+      exact(`requested ${shortPrimaryType(type)}`, summary.byPrimaryType[shortPrimaryType(type)]?.requested ?? 0, Number(expected), failures);
+    }
+  }
+  if (node.methods && typeof node.methods === 'object') {
+    for (const [method, expected] of Object.entries(node.methods)) {
+      exact(`method ${method}`, summary.byMethod[method] ?? 0, Number(expected), failures);
+    }
+  }
+  if (node.max_typed_data_requests != null && summary.typedDataRequests > Number(node.max_typed_data_requests)) {
+    failures.push(`typed-data requests ${summary.typedDataRequests} > ${node.max_typed_data_requests}`);
+  }
+  if (node.expect_confirmations != null) {
+    exact('confirmations shown', summary.confirmationsShown, Number(node.expect_confirmations), failures);
+  }
+  if (node.require_active_chain === true) {
+    for (const entry of typed.filter((item) => item.outcome === 'signed')) {
+      if (Number(entry.domainChainId) !== Number(entry.activeChainId)) {
+        failures.push(`seq ${entry.seq} ${shortPrimaryType(entry.primaryType)} signed with domain chainId ${entry.domainChainId} while the wallet was on ${entry.activeChainId}`);
+      }
+    }
+  }
+  if (node.max_rejected != null) {
+    const rejected = typed.filter((entry) => entry.outcome === 'rejected' || entry.outcome === 'error').length;
+    if (rejected > Number(node.max_rejected)) failures.push(`rejected typed-data requests ${rejected} > ${node.max_rejected}`);
+  }
+  return { ok: failures.length === 0, failures, summary };
+}
+
+export async function windowSinceCursor(projectRoot) {
+  const [entries, cursor] = await Promise.all([readLog(projectRoot), readCursor(projectRoot)]);
+  return { cursor, entries: entries.filter((entry) => entry.seq >= cursor), total: entries.length };
+}
+
+export async function writeLogArtifact(input, payload) {
+  const artifactsDir = input.context?.artifactsDir;
+  if (!artifactsDir) return [];
+  const nodeId = String(input.context?.nodeId ?? input.action).replaceAll('/', '__');
+  const relative = `terminal-wallet/${nodeId}-signature-log.json`;
+  await mkdir(path.join(artifactsDir, 'terminal-wallet'), { recursive: true });
+  await writeFile(path.join(artifactsDir, relative), `${JSON.stringify(payload, null, 2)}\n`);
+  return [{ path: relative, type: 'report', nodeId: String(input.context?.nodeId ?? input.action) }];
+}