@deeeed/metamask-harness 0.70.1 → 0.72.0

package/library/actions/shared/console-findings.mjs

@@ -0,0 +1,511 @@
+// The one console matcher: classify application console events and apply a
+// recipe-library allowlist of known noise. Used by run diagnostics
+// (src/run-diagnostics.ts), the assert_no_console_errors action, the
+// allowlist generator, and the recipe library's checks/console-guard.mjs
+// (which imports this file), so every caller judges an event the same way.
+//
+// Captures: console-tail.mjs logs (a "HH:MM:SS [label] [browser:<source>]
+// LEVEL  text  (at [fn ]location)" record, the browser tag only on browser
+// Log entries, plus "│ "-prefixed continuation lines), Metro or
+// webpack logs (one line per record), and JSONL captures from a CDP watcher
+// ({ kind: "console" | "exception" | "log", level, text, source | url }).
+//
+// Allowlist files: <recipe library>/diagnostics/console-allowlist.json
+//   { "schemaVersion": 3,
+//     "entries": [{ "signature": "<sig of the first line>", "continuation": "<sig of the rest>",
+//                   "first_frame": "<sig of the location>", "source": "page|extension|browser|any",
+//                   "reason": "<why it is noise>", "temporary": true }] }
+// An entry matches one event (a first line and every line that continues it)
+// by string equality of each part, no patterns:
+//   signature     the first line's text, without its location suffix;
+//   continuation  every continuation line, trimmed, blank lines dropped,
+//                 each line's signature joined with "\n" ("" for none);
+//   first_frame   optional: the event's location (a URL or path, no position).
+//
+// Normalisation is structural: only fields this file parses are changed.
+//   URLs (parsed with new URL(); Next.js scope only on a plain path, see
+//     isPlainPath): a loopback host's port → <port>; an asset under
+//     /_next/static/ → /_next/static/[chunks|media|css/]<chunk>.<ext>; the dpl and v query
+//     values on /_next/ paths → <build>; an unpacked extension id →
+//     <extension>. Everything else in a URL stays as written.
+//   Stack frame lines ("at [fn (]URL or path:line:col[)]") and event
+//     locations: the position is dropped and the URL normalised as above.
+//   Other text: ISO and clock times → <time>, UUIDs → <uuid>, 0x and 9 or
+//     more hex digits → 0x…, nothing else.
+// A matching event is downgraded to level "info" with the reason; it no
+// longer makes a run REVIEW. Entries are written from real captures with
+// console-allowlist-add.mjs.
+
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+export const ALLOWLIST_RELATIVE_PATH = path.join('diagnostics', 'console-allowlist.json');
+// Requests the harness itself makes (the launch probe of the mainnet block).
+export const HARNESS_PROBE_MARK = 'mm-harness-probe=1';
+const HARNESS_PROBE_PARAM = 'mm-harness-probe';
+const SOURCES = new Set(['page', 'extension', 'browser', 'any']);
+const SEVERITY = ['warning', 'error', 'exception'];
+
+// ---- severity -------------------------------------------------------------
+
+// The level word console-tail writes (the CDP console type, Log entry level,
+// or EXCEPTION). LOG, INFO, DEBUG and VERBOSE are not findings.
+const LEVEL_WORDS = { WARNING: 'warning', WARN: 'warning', ERROR: 'error', ASSERT: 'error', EXCEPTION: 'exception' };
+// A JSONL capture's console and Log entry levels.
+const JSONL_LEVELS = { warning: 'warning', warn: 'warning', error: 'error', assert: 'error' };
+// Text that makes any event an exception. It only ever raises a level.
+const EXCEPTION_TEXT = /\b(?:Uncaught|UnhandledPromiseRejection|FATAL EXCEPTION)\b/iu;
+
+function worst(...levels) {
+  return levels.filter(Boolean).reduce((a, b) => (a && SEVERITY.indexOf(a) >= SEVERITY.indexOf(b) ? a : b), null);
+}
+
+// A line with no recorded level (Metro/webpack output, a continuation line):
+// the level its own markers show, or null.
+export function lineLevel(trimmed) {
+  if (/\bEXCEPTION\s{2,}/u.test(trimmed) || EXCEPTION_TEXT.test(trimmed)) return 'exception';
+  if (/^(?:ERROR\s{2,}|\[error\]\s*)/iu.test(trimmed) || /\]\s+ERROR\s{2,}/u.test(trimmed)) return 'error';
+  if (/^(?:WARN(?:ING)?\s{2,}|\[warn(?:ing)?\]\s*)/iu.test(trimmed) || /\]\s+WARN(?:ING)?\s{2,}/u.test(trimmed)) return 'warning';
+  return null;
+}
+
+// ---- normalisation --------------------------------------------------------
+
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]']);
+const BUILD_PARAMS = new Set(['dpl', 'v']);
+const URL_TOKEN = /\b[a-z][\w+.-]*:\/\/[^\s'"()]+/giu;
+
+// A path the matcher may read as Next.js structure: every segment, as
+// written, is made of letters, digits, ".", "_", "@", "-" and the escape %40
+// (turbopack writes "@" in chunk names as %40), nothing else, and is never
+// "." or "..". No encoding, at any depth, can then stand for a separator or
+// a dot segment; any other path stays literal.
+const PLAIN_SEGMENT = /^(?:[A-Za-z0-9._@-]|%40)+$/u;
+function isPlainPath(raw) {
+  return raw.split('/').slice(1).every((segment) => PLAIN_SEGMENT.test(segment) && segment !== '.' && segment !== '..');
+}
+
+// One URL, changed only in the fields listed at the top of this file; any
+// string new URL() rejects is left as it is.
+export function urlSignature(token) {
+  const value = String(token);
+  const schemeEnd = value.indexOf('://');
+  if (schemeEnd <= 0) return value;
+  // Parse with placeholders a signature already has, so a signature is its
+  // own signature.
+  let url;
+  try {
+    url = new URL(value.replace(/^([^/?#]*:\/\/[^/?#]*):<port>/u, '$1:1').replace('://<extension>', `://${'a'.repeat(32)}`));
+  } catch {
+    return value;
+  }
+  const authorityStart = schemeEnd + 3;
+  const authorityLength = value.slice(authorityStart).search(/[/?#]/u);
+  const authorityEnd = authorityLength < 0 ? value.length : authorityStart + authorityLength;
+  let authority = value.slice(authorityStart, authorityEnd);
+  let rest = value.slice(authorityEnd);
+  const hashAt = rest.indexOf('#');
+  const fragment = hashAt < 0 ? '' : rest.slice(hashAt);
+  if (hashAt >= 0) rest = rest.slice(0, hashAt);
+  const queryAt = rest.indexOf('?');
+  let pathname = queryAt < 0 ? rest : rest.slice(0, queryAt);
+  let query = queryAt < 0 ? '' : rest.slice(queryAt);
+
+  // An unpacked extension's id depends on its directory.
+  if (url.protocol === 'chrome-extension:' && /^[a-p]{32}$/u.test(authority)) authority = '<extension>';
+  // The slot's ports are assigned per slot.
+  if (LOOPBACK_HOSTS.has(url.hostname)) authority = authority.replace(/:\d+$/u, ':<port>');
+  // Next.js names its build assets per build, and versions them with
+  // dpl/v parameters. Only a plain path (isPlainPath) is in scope.
+  const nextPath = (prefix) => isPlainPath(pathname) && pathname.startsWith(prefix);
+  if (nextPath('/_next/')) {
+    query = query && `?${query.slice(1).split('&').map((part) => {
+      const equals = part.indexOf('=');
+      return equals > 0 && BUILD_PARAMS.has(part.slice(0, equals)) ? `${part.slice(0, equals)}=<build>` : part;
+    }).join('&')}`;
+  }
+  // The asset's name changes per build; its directory (chunks, media, css)
+  // and extension say what kind of asset it is, and stay.
+  // A name without an extension (or with anything after it, such as a
+  // position) stays as written.
+  const asset = nextPath('/_next/static/') ? /^(?:(chunks|media|css)\/)?.*\.([A-Za-z0-9]{1,8})$/u.exec(pathname.slice('/_next/static/'.length)) : null;
+  if (asset) pathname = `/_next/static/${asset[1] ? `${asset[1]}/` : ''}<chunk>.${asset[2]}`;
+  return `${value.slice(0, authorityStart)}${authority}${pathname}${query}${fragment}`;
+}
+
+// Text outside URLs: times, UUIDs and long hex only.
+function plainTextSignature(value) {
+  return value
+    .replace(/\b\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z?/gu, '<time>')
+    .replace(/\b\d{2}:\d{2}:\d{2}(?:\.\d+)?\b/gu, '<time>')
+    .replace(/\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/giu, '<uuid>')
+    // Addresses and hashes; hex up to 8 digits (chain ids, selectors) stays.
+    .replace(/(?<![0-9])0x[0-9a-fA-F]{9,}\b/gu, '0x…');
+}
+
+// The signature of one line of message text.
+export function signature(value) {
+  const text = String(value ?? '').trim();
+  let result = '';
+  let last = 0;
+  for (const match of text.matchAll(URL_TOKEN)) {
+    result += plainTextSignature(text.slice(last, match.index)) + urlSignature(match[0]);
+    last = match.index + match[0].length;
+  }
+  return result + plainTextSignature(text.slice(last));
+}
+
+// A location: a URL or an absolute path, already without its position.
+export function locationSignature(location) {
+  const value = String(location ?? '').trim();
+  return /^[a-z][\w+.-]*:\/\//iu.test(value) ? urlSignature(value) : value;
+}
+
+// "at fn (URL or path:line:col)" or "at URL or path:line:col".
+const FRAME_LINE = /^at (?:([^\s()][^()]*) \()?((?:[a-z][\w+.-]*:\/\/|\/)\S*?):\d+:\d+(\)?)$/iu;
+// The signature of one continuation line of an event.
+export function continuationLineSignature(line) {
+  const trimmed = String(line ?? '').trim();
+  const frame = FRAME_LINE.exec(trimmed);
+  if (frame && Boolean(frame[1]) === Boolean(frame[3])) {
+    const where = locationSignature(frame[2]);
+    return frame[1] ? `at ${frame[1]} (${where})` : `at ${where}`;
+  }
+  return signature(trimmed);
+}
+
+function continuationSignature(lines) {
+  return lines.map(continuationLineSignature).join('\n');
+}
+
+// ---- events ---------------------------------------------------------------
+
+// The event a record or JSONL entry describes, with the key entries match.
+function makeEvent({ level, source, logSource = null, text, location = '', continuation = [] }) {
+  const lines = continuation.map((line) => String(line).trim()).filter(Boolean);
+  const raised = worst(level, EXCEPTION_TEXT.test(text) ? 'exception' : null, ...lines.map(lineLevel));
+  if (!raised) return null;
+  return {
+    level: raised,
+    source,
+    logSource,
+    text,
+    location,
+    continuation: lines.join('\n'),
+    key: {
+      signature: signature(text),
+      continuation: continuationSignature(lines),
+      first_frame: locationSignature(location),
+    },
+  };
+}
+
+// A frame as console-tail and CDP watchers write it, "fn URL:line:col" or
+// "URL:line[:col] fn": its location without the position, which follows the
+// path (so a port is never one). A bare URL (a Log entry's) is its own
+// location.
+function frameLocation(where) {
+  const match = /^(.*?)((?::\d+){1,2})$/u.exec(where);
+  if (!match) return where;
+  const hasPath = match[1].startsWith('/') || /^[a-z][\w+.-]*:\/\/[^/]*\//iu.test(match[1]);
+  return hasPath ? match[1] : where;
+}
+
+const RECORD_START = /^\d{2}:\d{2}:\d{2}(?:\.\d+)?\s+\[[^\]]+\]/u;
+// "HH:MM:SS [label] [browser:<Log source>] LEVEL  ": every field before the
+// message comes from the collector; the browser tag only ever here.
+const RECORD_HEAD = /^\d{2}:\d{2}:\d{2}(?:\.\d+)?\s+\[([^\]]+)\]\s+(?:\[browser:([a-z-]+)\]\s+)?(?:([A-Z]+)\s{2,})?/u;
+// The collector's "  (at [fn ]location)" suffix: a URL or an absolute path,
+// after a function name when it is a stack frame.
+const LOCATION_SUFFIX = /\s+\(at (?:([^\s()]+) )?((?:[a-z][\w+.-]*:\/\/|\/)\S*)\)$/iu;
+
+// The collector (console-tail.mjs) writes every line after an event's first
+// with this prefix, so event boundaries come from the collector, never from
+// message text.
+export const CONTINUATION_PREFIX = '│ ';
+
+// Group a log into records: a console-tail line (time + [label]) plus the
+// prefixed continuation lines the collector wrote after it. Every other
+// non-empty line is a record of its own; in a console-tail log, where the
+// collector frames every line, such a line is at least an error (an older
+// collector's continuation, or text that did not come from the collector).
+// Prefixed lines at the start of a slice continue a record before it. A last
+// line without its newline is judged like any other (a reader that cut the
+// capture at a size limit drops the partial line first).
+export function consoleRecords(text) {
+  const records = [];
+  let current = null;
+  let consoleTail = false;
+  for (const line of String(text ?? '').split(/\r?\n/u)) {
+    if (line.startsWith(CONTINUATION_PREFIX)) {
+      const continued = line.slice(CONTINUATION_PREFIX.length).trim();
+      if (current && continued) current.continuation.push(continued);
+      continue;
+    }
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const start = RECORD_START.test(trimmed);
+    consoleTail ||= start;
+    current = { line, continuation: [], start, unframed: !start && consoleTail };
+    records.push(current);
+    if (!start) current = null;
+  }
+  return records;
+}
+
+function labelSource(label) {
+  if (label.startsWith('dapp:')) return 'page';
+  if (label.startsWith('extension:') || label === 'sw' || label.startsWith('page:')) return 'extension';
+  return 'app';
+}
+
+// One record → its event (probes included), or null when it is not a finding.
+export function recordEvent(record) {
+  const trimmed = String(record.line ?? '').trim();
+  const head = record.start === false ? null : RECORD_HEAD.exec(trimmed);
+  let level;
+  let source;
+  let logSource = null;
+  let message;
+  let raw;
+  if (head) {
+    level = LEVEL_WORDS[head[3]] ?? null;
+    source = head[2] ? 'browser' : labelSource(head[1]);
+    logSource = head[2] ?? null;
+    message = trimmed.slice(head[0].length).trim();
+    raw = message;
+  } else {
+    // No recorded level: Metro/webpack output, or an unframed line.
+    level = worst(lineLevel(trimmed), record.unframed ? 'error' : null);
+    source = 'app';
+    const marker = /\b(?:EXCEPTION|ERROR|WARN(?:ING)?)\s{2,}/u.exec(trimmed);
+    message = (marker ? trimmed.slice(marker.index + marker[0].length) : trimmed).trim();
+    raw = message;
+  }
+  const suffix = LOCATION_SUFFIX.exec(message);
+  const event = makeEvent({
+    level,
+    source,
+    logSource,
+    text: suffix ? message.slice(0, suffix.index).trim() : message,
+    location: suffix ? (suffix[1] ? frameLocation(suffix[2]) : suffix[2]) : '',
+    continuation: record.continuation ?? [],
+  });
+  // The message as logged (with its location), for display.
+  return event && { ...event, message: raw };
+}
+
+// Events from a console-tail (or Metro/webpack) log.
+export function parseConsoleLog(text) {
+  return consoleRecords(text).map(recordEvent).filter(Boolean);
+}
+
+// Events from a JSONL capture. console: { level, text, source: "URL:line:col
+// fn" }; exception: { text, source }; log (a CDP Log entry): { level?, text,
+// logSource or source: the Log source, e.g. "network", url }. A Log entry
+// without a level is an error.
+export function parseJsonl(content) {
+  const events = [];
+  for (const line of String(content ?? '').split('\n')) {
+    if (!line.trim()) continue;
+    const entry = JSON.parse(line);
+    if (entry.kind !== 'console' && entry.kind !== 'exception' && entry.kind !== 'log') continue;
+    const [first = '', ...continuation] = String(entry.text ?? '').split(/\r?\n/u);
+    const event = entry.kind === 'log'
+      ? makeEvent({
+        level: entry.level === undefined ? 'error' : JSONL_LEVELS[entry.level] ?? null,
+        source: 'browser',
+        logSource: [entry.logSource, entry.source].find((value) => typeof value === 'string' && /^[a-z-]+$/u.test(value)) ?? null,
+        text: first.trim(),
+        location: typeof entry.url === 'string' ? entry.url : '',
+        continuation,
+      })
+      : makeEvent({
+        level: entry.kind === 'exception' ? 'exception' : JSONL_LEVELS[entry.level] ?? null,
+        source: 'page',
+        text: first.trim(),
+        location: frameLocation(String(entry.source ?? '').split(' ')[0]),
+        continuation,
+      });
+    if (event) events.push(event);
+  }
+  return events;
+}
+
+// ---- exemptions -----------------------------------------------------------
+
+// The failure a launch probe of the mainnet block produces, and nothing
+// else: an error-level browser Log entry from the network source, with no
+// further lines and no exception wording, whose text is exactly a failed
+// load (net::ERR_*) or a failed WebSocket, of a URL with exactly one
+// mm-harness-probe parameter, equal to 1. Probes fail before any HTTP
+// response, so a status line is never one.
+const RESOURCE_PROBE_TEXT = /^Failed to load resource: net::ERR_[A-Z_]+(?:\.Inspector)?$/u;
+const WEBSOCKET_PROBE_TEXT = /^WebSocket connection to '([^'\s]+)' failed:(?: Error in connection establishment: net::ERR_[A-Z_]+)?$/u;
+const EXCEPTION_WORDING = /uncaught|unhandled|exception|fatal|error:/iu;
+
+function isProbeUrl(url) {
+  try {
+    const values = new URL(url).searchParams.getAll(HARNESS_PROBE_PARAM);
+    return values.length === 1 && values[0] === '1';
+  } catch {
+    return false;
+  }
+}
+
+export function isHarnessProbe(event) {
+  if (event?.source !== 'browser' || event.logSource !== 'network' || event.level !== 'error' || event.continuation !== '') return false;
+  if (EXCEPTION_WORDING.test(event.text) || EXCEPTION_WORDING.test(event.location)) return false;
+  const socket = WEBSOCKET_PROBE_TEXT.exec(event.text);
+  if (socket) return isProbeUrl(socket[1]);
+  return RESOURCE_PROBE_TEXT.test(event.text) && isProbeUrl(event.location);
+}
+
+// A capture's control line (a watcher proving its capture works): exactly
+// "[mm-harness-capture-control] <id>" or "[cdp-watch-control][ <id>]",
+// alone, not an exception. Never a finding.
+const CONTROL_TEXT = /^\[(?:mm-harness-capture-control|cdp-watch-control)\](?: [\w-]+)?$/u;
+export function isControlEvent(event) {
+  return event?.level !== 'exception' && event?.continuation === '' && CONTROL_TEXT.test(event.text);
+}
+
+// ---- console-tail findings (run diagnostics, assert_no_console_errors) ----
+
+// The message with run-specific values replaced and query strings dropped,
+// so repeats of one problem group together; for display, not matching.
+export function messageSignature(message) {
+  const suffix = LOCATION_SUFFIX.exec(message);
+  const text = suffix ? message.slice(0, suffix.index) : message;
+  return signature(text).replace(/([a-z][\w+.-]*:\/\/[^\s?#'"()]+)[?#][^\s'"()]*/giu, '$1').slice(0, 240);
+}
+
+// A record → its finding, or null for ordinary output, the launch probe's own
+// failure and a capture control line: { level, source, logSource, message, signature (grouping),
+// firstFrame, text, location, continuation, key }.
+export function classifyConsoleRecord(record) {
+  const event = recordEvent(record);
+  if (!event || isHarnessProbe(event) || isControlEvent(event)) return null;
+  const frame = LOCATION_SUFFIX.exec(event.message);
+  return { ...event, signature: messageSignature(event.message), firstFrame: frame ? `${frame[1] ? `${frame[1]} ` : ''}${frame[2]}` : null };
+}
+
+// One console line → its finding, or null.
+export function classifyConsoleLine(line) {
+  return classifyConsoleRecord({ line, continuation: [], start: RECORD_START.test(String(line ?? '').trim()), unframed: false });
+}
+
+// ---- allowlist ------------------------------------------------------------
+
+const ALLOWLIST_SCHEMA_VERSION = 3;
+
+// Why an entry cannot be applied, or null. Entries are compared with
+// signatures, so they must be signatures.
+export function entryProblem(entry) {
+  if (!entry || typeof entry.signature !== 'string' || !entry.signature || typeof entry.continuation !== 'string' ||
+    !SOURCES.has(entry.source ?? 'any') || typeof entry.reason !== 'string' || !entry.reason.trim()) {
+    return 'needs signature, continuation ("" for none), source (page|extension|browser|any) and reason';
+  }
+  if (entry.first_frame !== undefined && typeof entry.first_frame !== 'string') return 'first_frame must be a string';
+  if (signature(entry.signature) !== entry.signature) return `signature is not normalised (expected ${JSON.stringify(signature(entry.signature))})`;
+  if (typeof entry.first_frame === 'string' && locationSignature(entry.first_frame) !== entry.first_frame) {
+    return `first_frame is not normalised (expected ${JSON.stringify(locationSignature(entry.first_frame))})`;
+  }
+  const lines = entry.continuation.split('\n');
+  if (entry.continuation && (lines.some((line) => !line) || continuationSignature(lines) !== entry.continuation)) {
+    return 'continuation is not normalised (one signature per line, no blank lines)';
+  }
+  return null;
+}
+
+// { entries, problems } from an allowlist document; throws on another
+// schemaVersion. Bad entries are reported, never applied.
+export function compileAllowlist(document) {
+  if (document?.schemaVersion !== ALLOWLIST_SCHEMA_VERSION) {
+    throw new Error(`schemaVersion must be ${ALLOWLIST_SCHEMA_VERSION} (exact signatures)`);
+  }
+  const problems = [];
+  const entries = (Array.isArray(document.entries) ? document.entries : []).flatMap((entry, index) => {
+    const problem = entryProblem(entry);
+    if (problem) {
+      problems.push(`entry ${index} ${problem}`);
+      return [];
+    }
+    return [{
+      ...entry,
+      first_frame: entry.first_frame ?? null,
+      source: entry.source ?? 'any',
+      reason: entry.reason.trim(),
+      temporary: entry.temporary === true,
+      index,
+    }];
+  });
+  return { entries, problems };
+}
+
+// Allowlist entries from every library root that has the file. A malformed
+// file or entry is reported, never silently applied.
+export function loadConsoleAllowlist(libraryRoots = []) {
+  const entries = [];
+  const problems = [];
+  for (const root of libraryRoots) {
+    const file = path.join(root, ALLOWLIST_RELATIVE_PATH);
+    if (!existsSync(file)) continue;
+    let compiled;
+    try {
+      compiled = compileAllowlist(JSON.parse(readFileSync(file, 'utf8')));
+    } catch (error) {
+      problems.push(`${file}: ${error.message}${/schemaVersion/u.test(error.message) ? '; no entry applied' : ''}`);
+      continue;
+    }
+    entries.push(...compiled.entries.map((entry) => ({ ...entry, file })));
+    problems.push(...compiled.problems.map((problem) => `${file}: ${problem}`));
+  }
+  return { entries, problems };
+}
+
+// The first entry equal to the event (by source and key), or null.
+export function matchEntry(event, entries) {
+  const { key } = event;
+  return entries.find((entry) =>
+    (entry.source === 'any' || entry.source === event.source) &&
+    entry.signature === key.signature &&
+    entry.continuation === key.continuation &&
+    (entry.first_frame === null || entry.first_frame === key.first_frame)) ?? null;
+}
+
+export function allowlistMatch(finding, allowlist) {
+  return matchEntry(finding, allowlist.entries);
+}
+
+// Events split into allowlisted (entry → count) and unexpected ones; probes
+// and control lines are neither.
+export function classify(events, allowlist) {
+  const allowed = new Map();
+  const unexpected = [];
+  for (const event of events) {
+    if (isHarnessProbe(event) || isControlEvent(event)) continue;
+    const entry = matchEntry(event, allowlist.entries);
+    if (entry) allowed.set(entry, (allowed.get(entry) ?? 0) + 1);
+    else unexpected.push(event);
+  }
+  return { allowed, unexpected };
+}
+
+// The entry an event would need, for the generator and for review output.
+export function entryFor(event) {
+  return {
+    signature: event.key.signature,
+    continuation: event.key.continuation,
+    ...(event.key.first_frame ? { first_frame: event.key.first_frame } : {}),
+    source: event.source,
+  };
+}
+export const allowlistEntryFor = entryFor;
+
+// RECIPE_LIBRARY_PATH: "name=/path:name=/path" (or bare paths).
+export function libraryRootsFromEnv(env = process.env) {
+  return String(env.RECIPE_LIBRARY_PATH ?? '')
+    .split(':')
+    .map((entry) => entry.includes('=') ? entry.slice(entry.indexOf('=') + 1) : entry)
+    .filter(Boolean);
+}

package/library/actions/terminal/app/assert_no_console_errors.mjs

@@ -0,0 +1,119 @@
+// Fail the recipe when the terminal page logged an error or uncaught exception
+// that the recipe libraries' console allowlist does not mark as known
+// third-party noise. Reads the slot console capture (app-console.log, and
+// extension-console.log when asked) from where the current slot browser's
+// launch began. The same classifier and allowlist feed run diagnostics.
+// It never passes on missing evidence: the slot's own console collector must
+// be running on the browser's CDP port, and for every capture file a
+// requested source reads, a control line logged in its target (the app page,
+// or MetaMask for the extension source) must reach that file; otherwise the
+// action fails as unavailable.
+
+import { closeSync, fstatSync, openSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import {
+  allowlistMatch,
+  classifyConsoleRecord,
+  consoleRecords,
+  libraryRootsFromEnv,
+  loadConsoleAllowlist,
+} from '../../shared/console-findings.mjs';
+import { collectorOwnerMarker, collectorStatus, verifyCapture } from '../../shared/console-collector.mjs';
+import { isDirectRun, readBrowserState, runAdapter, terminalRuntimeDir } from '../platform/runtime.mjs';
+
+const LOGS = Object.freeze({ page: 'app-console.log', extension: 'extension-console.log' });
+
+// The capture from a recorded offset. A file now shorter than the offset, or
+// a different file, was replaced since: read it whole and say so, rather than
+// reading nothing.
+function readFrom(file, mark) {
+  let fd;
+  try {
+    fd = openSync(file, 'r');
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { text: '', reset: false };
+    throw error;
+  }
+  try {
+    // One open file: its size and inode are those of the content read.
+    const stat = fstatSync(fd);
+    const offset = Number(mark.offset ?? 0);
+    const reset = offset > stat.size || (mark.inode != null && mark.inode !== stat.ino);
+    return { text: readFileSync(fd).subarray(reset ? 0 : offset).toString('utf8'), reset };
+  } finally {
+    closeSync(fd);
+  }
+}
+
+function unavailable(detail) {
+  return new Error(`console capture unavailable: ${detail}. The page console was not proven to be captured, so its absence of errors proves nothing.`);
+}
+
+export async function assertNoConsoleErrors(input, env = process.env, deps = {}) {
+  const node = input.node ?? {};
+  const projectRoot = input.context?.projectRoot;
+  const sources = Array.isArray(node.sources) && node.sources.length ? node.sources.map(String) : ['page', 'browser'];
+  const levels = new Set(Array.isArray(node.levels) && node.levels.length ? node.levels.map(String) : ['error', 'exception']);
+  const runtime = terminalRuntimeDir(projectRoot);
+  const state = await readBrowserState(projectRoot);
+  if (!state?.cdpPort || !state.appOrigin) throw unavailable('no slot browser state (browser.json)');
+  const capture = (deps.collectorStatus ?? collectorStatus)({
+    pidFile: path.join(runtime, 'console-tail.pid'),
+    extensionLog: path.join(runtime, LOGS.extension),
+    marker: collectorOwnerMarker(runtime),
+    cdpPort: state.cdpPort,
+  });
+  if (!capture.ok) throw unavailable(capture.detail);
+  for (const source of sources) {
+    if (!['page', 'extension', 'browser'].includes(source)) throw new Error(`sources must be page, extension or browser, got ${JSON.stringify(source)}.`);
+  }
+  // Browser log entries come from the page's own capture file.
+  const files = [...new Set(sources.map((source) => (source === 'extension' ? 'extension' : 'page')))];
+  const control = {};
+  for (const file of files) {
+    const result = await (deps.verifyCapture ?? verifyCapture)({ cdpPort: state.cdpPort, log: path.join(runtime, LOGS[file]), target: file, appOrigin: state.appOrigin, extensionId: state.extension?.id ?? null });
+    if (!result.ok) throw unavailable(result.detail);
+    control[file] = result.detail;
+  }
+  const offsets = node.since === 'start-of-log' ? {} : state?.consoleOffsets ?? {};
+  const roots = [...libraryRootsFromEnv(env), ...(typeof node.allowlist_root === 'string' ? [node.allowlist_root] : [])];
+  const allowlist = loadConsoleAllowlist(roots);
+  const failing = new Map();
+  const allowlisted = new Map();
+  const offsetResets = [];
+  for (const file of files) {
+    const { text, reset } = readFrom(path.join(runtime, LOGS[file]), { offset: offsets[file] ?? 0, inode: offsets.inodes?.[file] });
+    if (reset) offsetResets.push(file);
+    for (const record of consoleRecords(text)) {
+      const finding = classifyConsoleRecord(record);
+      if (!finding || !levels.has(finding.level) || !sources.includes(finding.source)) continue;
+      const match = allowlistMatch(finding, allowlist);
+      const bucket = match ? allowlisted : failing;
+      const key = `${finding.level}|${finding.source}|${finding.signature}`;
+      const entry = bucket.get(key) ?? { level: finding.level, source: finding.source, signature: finding.signature, example: finding.message, firstFrame: finding.firstFrame, count: 0, ...(match ? { reason: match.reason } : {}) };
+      entry.count += 1;
+      bucket.set(key, entry);
+    }
+  }
+  const output = {
+    action: input.action,
+    sources,
+    levels: [...levels],
+    findings: [...failing.values()],
+    allowlisted: [...allowlisted.values()],
+    allowlistProblems: allowlist.problems,
+    capture: { collector: capture.detail, control },
+    // The recorded launch offset was past the end of a replaced capture
+    // file; that file was read from its start.
+    offsetResets,
+    proofPath: 'terminal-console-capture',
+  };
+  if (failing.size > 0) {
+    const list = [...failing.values()].map((item) => `${item.level} [${item.source}] ${item.example} ×${item.count}`).join('\n  ');
+    throw new Error(`console errors not on the allowlist:\n  ${list}`);
+  }
+  return output;
+}
+
+if (isDirectRun(import.meta.url)) runAdapter((input) => assertNoConsoleErrors(input));

package/library/actions/terminal/app/launch.mjs

@@ -0,0 +1,45 @@
+// Explicit lifecycle step: start (or reuse) the terminal slot browser with the
+// requested signer (MetaMask extension or injected strict wallet) and fixture
+// account, and the wallet host that records wallet requests. A fresh_profile
+// start forgets the app's stored agent key and the extension's dapp permission.
+
+import { appPort, cdpPort, isDirectRun, resolveSigner, runAdapter } from '../platform/runtime.mjs';
+import { launchTerminalBrowser } from '../../../../adapters/terminal/launch.mjs';
+
+export async function launch(input) {
+  const node = input.node ?? {};
+  const state = await launchTerminalBrowser({
+    target: input.context?.projectRoot,
+    'cdp-port': cdpPort(input),
+    'app-port': appPort(input),
+    signer: resolveSigner(node.signer),
+    account: String(node.account ?? node.account_name ?? 'dev1'),
+    'fresh-profile': node.fresh_profile === true,
+    // headless: true|false wins over env TERMINAL_HEADLESS; headful: true is the
+    // older spelling of headless: false.
+    headless: node.headless === true,
+    headful: node.headless === false || (node.headless !== true && node.headful === true),
+    'slow-mo': node.slow_mo_ms,
+    network: node.network,
+    'mainnet-confirmation': node.mainnet_confirmation,
+    'start-chain': node.start_chain ?? 42161,
+  });
+  return {
+    action: input.action,
+    status: 'ready',
+    reused: state.reused,
+    signer: state.signer,
+    network: state.network ?? 'testnet',
+    account: state.account,
+    cdpPort: state.cdpPort,
+    appOrigin: state.appOrigin,
+    browser: state.browser,
+    window: state.window ?? null,
+    slowMoMs: state.slowMoMs ?? 0,
+    extension: state.extension ? { id: state.extension.id, version: state.extension.version } : null,
+    freshProfile: state.freshProfile,
+    proofPath: 'terminal-browser-launch',
+  };
+}
+
+if (isDirectRun(import.meta.url)) runAdapter((input) => launch(input));