carthagent 0.0.0-stage → 1.0.7

package/extensions/experiential.ts

@@ -0,0 +1,21 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { experientialProviderConfig, EXPERIENTIAL_PROVIDER_ID } from '../lib/providers/experiential.mjs';
+import { cloudManagedUsageRecovery } from '../lib/cloud/client.mjs';
+import { noteAgentTurn, noteEngineSession } from '../lib/ship-telemetry.mjs';
+
+/** Register Carthagent Ship for the bundled agent in TUI, RPC, and headless modes. */
+export default function experiential(pi: ExtensionAPI) {
+  pi.registerProvider(EXPERIENTIAL_PROVIDER_ID, experientialProviderConfig());
+  // Ship telemetry: the engine session id is the thread id; each user turn
+  // (agent run) advances the counter stamped on managed requests.
+  pi.on('session_start', (_event: any, ctx: any) => noteEngineSession(ctx?.sessionManager?.getSessionId?.()));
+  pi.on('agent_start', () => noteAgentTurn());
+  pi.on('message_end', (event: any, ctx: any) => {
+    const message = event?.message;
+    if (message?.role !== 'assistant' || message.stopReason !== 'error') return;
+    if (message.provider !== EXPERIENTIAL_PROVIDER_ID && ctx?.model?.provider !== EXPERIENTIAL_PROVIDER_ID) return;
+    const recovery = cloudManagedUsageRecovery(message.errorMessage);
+    if (!recovery) return;
+    ctx.ui?.notify?.(recovery, 'warning');
+  });
+}

package/extensions/subscriptions.ts

@@ -0,0 +1,21 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { getAgentDir } from '@earendil-works/pi-coding-agent';
+import {
+  SUBSCRIPTION_PROVIDER_IDS,
+  registerSubscriptionProviders,
+} from '../lib/providers/subscription-models.mjs';
+
+/**
+ * Overlay Claude/ChatGPT subscription model discovery on the builtin
+ * providers. Engine startup only runs offline refreshes, so a session-start
+ * hook issues a bounded network refresh scoped to the two providers —
+ * leaving it out lets new models appear for already-signed-in users.
+ */
+export default function subscriptions(pi: ExtensionAPI) {
+  registerSubscriptionProviders(pi as unknown as Parameters<typeof registerSubscriptionProviders>[0], {
+    agentDir: getAgentDir(),
+  });
+  pi.on('session_start', (_event: unknown, ctx: { modelRegistry?: { refresh?: (options: { providers: string[] }) => Promise<unknown> } }) => {
+    void Promise.resolve(ctx?.modelRegistry?.refresh?.({ providers: [...SUBSCRIPTION_PROVIDER_IDS] })).catch(() => {});
+  });
+}

package/guidance/profiles/authenticated-web.json

@@ -0,0 +1,24 @@
+{
+  "id": "authenticated-web",
+  "title": "Authenticated web application",
+  "priority": 90,
+  "match": {
+    "keywords": ["auth", "authenticated", "authentication", "authorize", "authorization", "login", "logout", "signup", "account", "oauth", "session", "user", "member"],
+    "dependencies": ["next-auth", "@auth/core", "passport", "lucia", "@clerk/nextjs"]
+  },
+  "planning": [
+    "Separate authentication from authorization: every server route must verify both identity and access to the requested resource.",
+    "Centralize session and database helpers; do not create a new database client in each route or export framework-invalid values from route modules.",
+    "Return only fields the current user is allowed to see, especially participant identity, account, and financial data.",
+    "Require explicit confirmation and CSRF-safe methods for destructive account or membership actions."
+  ],
+  "checks": [
+    "Test unauthenticated, authenticated-but-not-authorized, missing-resource, and successful requests for each changed route.",
+    "Test direct API access independently of page middleware; client redirects are not authorization controls.",
+    "Verify secrets remain server-only and required authentication configuration fails clearly when absent."
+  ],
+  "review": [
+    "Look for ownership filters that only narrow nested relations while still returning the parent resource.",
+    "Look for host-header-derived internal requests, over-broad ORM includes, account deletion without relational handling, and user identifiers sourced from unvalidated client input."
+  ]
+}

package/guidance/profiles/data-visualization.json

@@ -0,0 +1,25 @@
+{
+  "id": "data-visualization",
+  "title": "Data visualization",
+  "priority": 60,
+  "match": {
+    "keywords": ["chart", "graph", "visualization", "timeseries", "time series", "analytics", "sparkline", "candlestick"],
+    "dependencies": ["recharts", "chart.js", "react-chartjs-2", "d3", "echarts", "plotly.js"]
+  },
+  "planning": [
+    "Define the canonical raw data shape and a pure transformation layer before implementing chart rendering.",
+    "Preserve machine timestamps and numeric values through sorting and filtering; format labels only at render time with an explicit timezone.",
+    "Do not fabricate smoothness by interpolating or backfilling across unknown periods unless the product semantics require it and the UI labels it.",
+    "Choose one chart implementation and remove abandoned variants after comparison.",
+    "Bound data volume and expensive transforms; derive data with memoization rather than mirrored state and JSON-stringify comparisons."
+  ],
+  "checks": [
+    "Test unsorted data, duplicate timestamps, timezone and daylight-saving boundaries, market or business closures, gaps, empty series, and malformed values.",
+    "Test rapid symbol or range changes so stale responses cannot replace current data.",
+    "Render at narrow and wide dimensions and verify accessible text or tabular summaries for key values."
+  ],
+  "review": [
+    "Reject sorting by formatted display labels, fake future prices, unnecessary animation, duplicate chart libraries, and test controls left in production UI.",
+    "Confirm tooltip values, axes, units, timestamps, and fallback provenance agree with the underlying data."
+  ]
+}

package/guidance/profiles/database-change.json

@@ -0,0 +1,24 @@
+{
+  "id": "database-change",
+  "title": "Database change",
+  "priority": 75,
+  "match": {
+    "keywords": ["database", "schema", "migration", "prisma", "sql", "foreign key", "cascade", "relation", "delete account", "account deletion", "data model"],
+    "dependencies": ["@prisma/client", "drizzle-orm", "sequelize", "typeorm", "mongoose"]
+  },
+  "planning": [
+    "Define data invariants, ownership, uniqueness, deletion behavior, and query access patterns before changing the schema.",
+    "Use database constraints for invariants that must survive concurrent requests; application checks alone are insufficient.",
+    "Plan a forward migration for existing rows and state whether rollback, backfill, or staged deployment is required.",
+    "Centralize the database client and domain queries instead of duplicating ORM access across route handlers."
+  ],
+  "checks": [
+    "Apply migrations against both an empty database and representative existing data, then run affected route or service tests.",
+    "Test uniqueness, foreign-key, cascade or restrict behavior, transaction rollback, and concurrent writes.",
+    "Inspect generated SQL and query shape for missing indexes, over-fetching, and accidental full-table work."
+  ],
+  "review": [
+    "Reject schema comments that stand in for migration design, required fields without backfills, and account deletion paths that ignore related rows.",
+    "Confirm money, timestamps, enums, and optionality use domain-appropriate database types."
+  ]
+}

package/guidance/profiles/external-api.json

@@ -0,0 +1,24 @@
+{
+  "id": "external-api",
+  "title": "External API integration",
+  "priority": 70,
+  "match": {
+    "keywords": ["third-party api", "external api", "api integration", "provider", "webhook", "oauth api", "payment provider", "email provider", "stripe", "sendgrid", "twilio"],
+    "dependencies": ["axios", "stripe", "@sendgrid/mail", "twilio"]
+  },
+  "planning": [
+    "Create one server-side provider adapter that validates configuration and normalizes remote payloads into an internal type.",
+    "Define timeout, cancellation, retry, rate-limit, cache, pagination, and partial-failure behavior before adding UI consumers.",
+    "Validate symbols, identifiers, date ranges, and other user-controlled values before placing them into provider URLs.",
+    "Keep credentials server-only and avoid logging secrets, full upstream payloads, or sensitive customer data."
+  ],
+  "checks": [
+    "Test malformed provider payloads, missing credentials, non-2xx responses, timeout, rate limiting, empty data, and partial provider outage.",
+    "Assert bounded request counts and pagination termination with deterministic mocked responses.",
+    "Verify cached or fallback data carries timestamp and provenance so stale values are not silently presented as current."
+  ],
+  "review": [
+    "Reject repeated provider-fetch logic across routes, unbounded sequential calls, arbitrary delays as rate-limit control, and zero-filled placeholder fields presented as real data.",
+    "Confirm upstream failures map to stable internal error responses without leaking provider details."
+  ]
+}

package/guidance/profiles/transactional-data.json

@@ -0,0 +1,25 @@
+{
+  "id": "transactional-data",
+  "title": "Transactional data",
+  "priority": 80,
+  "match": {
+    "keywords": ["transaction", "balance", "money", "price", "payment", "checkout", "order", "purchase", "inventory", "booking", "reservation", "billing", "invoice", "subscription", "refund", "ledger", "wallet", "credit", "debit", "funds", "trade", "portfolio", "stock", "shares", "investment"]
+  },
+  "planning": [
+    "Write domain invariants explicitly before implementation: valid quantities, allowed states, ownership, available balance or inventory, and replay behavior.",
+    "Treat client-supplied prices, totals, ownership, and status as untrusted; resolve authoritative values on the server at mutation time.",
+    "Use decimal or integer minor-unit storage for money rather than binary floating point.",
+    "Make validation and mutation atomic with an appropriate database transaction or conditional update; account for concurrent requests and retries.",
+    "Define idempotency and audit requirements for mutations that must not execute twice."
+  ],
+  "checks": [
+    "Test zero, negative, fractional, non-finite, malformed, and very large inputs as well as invalid enum values.",
+    "Run concurrent mutation tests proving balance, holdings, inventory, or capacity cannot go negative or exceed limits.",
+    "Test rollback on downstream failure and replay of the same request where duplicate execution would be harmful.",
+    "Verify calculations at rounding boundaries with deterministic fixtures."
+  ],
+  "review": [
+    "Reject read-check-write sequences outside a transaction, Float money columns, truthiness-based numeric validation, and duplicate calculation implementations.",
+    "Confirm historical reports never use future values as fallback data and never present estimated values as authoritative without labeling them."
+  ]
+}

package/guidance/profiles/web-application.json

@@ -0,0 +1,26 @@
+{
+  "id": "web-application",
+  "title": "Web application",
+  "priority": 100,
+  "activateOnDependency": true,
+  "match": {
+    "keywords": ["web", "website", "frontend", "browser", "react", "next.js", "nextjs", "vue", "svelte", "dashboard", "page", "component", "api route"],
+    "dependencies": ["next", "react", "react-dom", "vue", "svelte", "@angular/core", "vite"]
+  },
+  "planning": [
+    "Inspect the existing framework, package scripts, route conventions, design system, and neighboring components before choosing an implementation pattern.",
+    "Define one end-to-end user path before styling breadth. Keep server data access, validation, domain logic, and presentation at explicit boundaries.",
+    "Modify the canonical implementation instead of leaving copy, v1/v2/v3, test-page, or temporary variants in production paths.",
+    "Account for loading, empty, error, retry, narrow viewport, keyboard, and accessible-name states where the requested surface can encounter them.",
+    "Use shared request/response types or runtime schemas at network boundaries; do not spread untyped API payload assumptions through components."
+  ],
+  "checks": [
+    "Run the repository's existing lint, typecheck, test, and production build commands; a dev-server render alone is insufficient.",
+    "Exercise the public browser path with realistic API success and failure responses, assert no console errors, and inspect the result at desktop and narrow widths.",
+    "Check that effects clean up, stale requests cannot overwrite newer state, non-2xx responses are handled before parsing, and loading always settles."
+  ],
+  "review": [
+    "Reject duplicated components, speculative abstractions, placeholder production behavior, dead imports, broad any types, and comments that describe unfinished work.",
+    "Confirm the implementation follows the existing visual language instead of adding isolated inline styling or decorative motion not requested by the user."
+  ]
+}

package/lib/acceptance-review.mjs

@@ -0,0 +1,4 @@
+export function acceptanceReviewerPrompt(request) {
+  if (typeof request !== 'string' || !request.trim()) throw Error('Original request is required');
+  return `You are a fresh-context acceptance reviewer. Evaluate the original request below against this workspace. Do not modify product source or existing tests, commit, push, or change branches. Put any temporary evaluator artifacts only in artifacts/acceptance-review. Do not trust the author's summary or passing checks. Inspect actual entrypoints and new/changed code. Execute bounded independent falsification probes of the highest-impact assumptions: producer/consumer representation agreement, real input-to-observable-result correspondence, safety, inverses and boundaries. Test normal execution separately from alternate test modes. Expected results must follow the specification or independent library conventions, not duplicate the implementation. Successful process exit or boolean activity flags do not prove correctness. Never kill unrelated processes. Report concrete prioritized defects with reproduction commands/results; distinguish unavailable checks from failures. End with VERDICT: APPROVE or VERDICT: CHANGES-REQUESTED. This review is model-authored, not an independent correctness guarantee.\n\nOriginal request:\n${request}`;
+}

package/lib/browser-bin.mjs

@@ -0,0 +1,160 @@
+/**
+ * Bundled browser provisioning — downloads the lightweight `chrome-headless-shell`
+ * build from Chrome for Testing on demand and caches it under the carthagent
+ * data dir. Zero npm deps; zip entries are extracted with node:zlib.
+ *
+ * Resolution order for checks: CARTHAGENT_BROWSER env → bundled shell →
+ * system chrome/chromium → Firefox (legacy fallback).
+ */
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync, chmodSync } from 'node:fs';
+import { delimiter, dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { spawnSync } from 'node:child_process';
+import { inflateRawSync } from 'node:zlib';
+
+export const BUNDLED_BROWSER_VERSION = process.env.CARTHAGENT_BROWSER_VERSION || '154.0.8037.92';
+
+const SHELL_URL = version => `https://storage.googleapis.com/chrome-for-testing-public/${version}/${platformKey()}/chrome-headless-shell-${platformKey()}.zip`;
+
+function platformKey() {
+  if (process.platform === 'linux') return process.arch === 'arm64' ? 'linux-arm64' : 'linux64';
+  if (process.platform === 'darwin') return process.arch === 'arm64' ? 'mac-arm64' : 'mac-x64';
+  if (process.platform === 'win32') return process.arch === 'x64' ? 'win64' : 'win32';
+  throw Error(`Unsupported platform ${process.platform}/${process.arch} for the bundled browser`);
+}
+
+export function browserRoot(base = join(homedir(), '.carthagent')) {
+  return join(base, 'browser');
+}
+
+/** Expected path of the bundled shell binary for this platform. */
+export function bundledBinaryPath({ version = BUNDLED_BROWSER_VERSION, base } = {}) {
+  const key = platformKey();
+  const name = process.platform === 'win32' ? 'chrome-headless-shell.exe' : 'chrome-headless-shell';
+  return join(browserRoot(base), version, `chrome-headless-shell-${key}`, name);
+}
+
+/** True when Chromium's stderr indicates the process sandbox cannot start
+ * (Ubuntu ≥23.10 AppArmor, containers without userns). The caller should
+ * retry once with --no-sandbox. */
+export function isSandboxFailure(stderr = '') {
+  return /unprivileged user namespaces|apparmor|SUID sandbox|cannot run as root|sandbox/i.test(stderr);
+}
+
+/** Locate a usable headless browser: env → bundled → system chrome/chromium → firefox. */
+export function findBrowser({ env = process.env } = {}) {
+  const chromium = findChromium({ env });
+  if (chromium) return chromium;
+  if (env.FIREFOX && existsSync(env.FIREFOX)) return env.FIREFOX;
+  for (const candidate of ['/usr/bin/firefox', '/snap/bin/firefox']) if (existsSync(candidate)) return candidate;
+  return null;
+}
+
+/** Chromium-family binary only (CDP/flag dialect): env → bundled → system chrome/chromium. */
+export function findChromium({ env = process.env } = {}) {
+  if (env.CARTHAGENT_BROWSER && existsSync(env.CARTHAGENT_BROWSER)) return env.CARTHAGENT_BROWSER;
+  const bundled = bundledBinaryPath();
+  if (existsSync(bundled)) return bundled;
+  const names = process.platform === 'win32'
+    ? ['chrome-headless-shell.exe', 'chrome.exe', 'chromium.exe']
+    : ['chrome-headless-shell', 'google-chrome-stable', 'google-chrome', 'chromium', 'chromium-browser'];
+  for (const dir of (env.PATH || '').split(delimiter)) {
+    for (const name of names) {
+      const candidate = join(dir, name);
+      if (existsSync(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+
+/**
+ * Minimal zip extractor (store + deflate). Parses the end-of-central-directory
+ * record and central directory, then reads each local file entry. Sufficient
+ * for Chrome for Testing archives without shelling out to unzip/tar.
+ */
+export function extractZip(zipPath, destDir) {
+  const buf = readFileSync(zipPath);
+  const eocdSig = 0x06054b50;
+  let eocd = -1;
+  for (let i = buf.length - 22; i >= Math.max(0, buf.length - 22 - 65536); i--) {
+    if (buf.readUInt32LE(i) === eocdSig) { eocd = i; break; }
+  }
+  if (eocd < 0) throw Error('zip: end of central directory not found');
+  const count = buf.readUInt16LE(eocd + 10);
+  let offset = buf.readUInt32LE(eocd + 16);
+  const written = [];
+  for (let i = 0; i < count; i++) {
+    if (buf.readUInt32LE(offset) !== 0x02014b50) throw Error('zip: corrupt central directory');
+    const method = buf.readUInt16LE(offset + 10);
+    const compressedSize = buf.readUInt32LE(offset + 20);
+    const nameLen = buf.readUInt16LE(offset + 28);
+    const extraLen = buf.readUInt16LE(offset + 30);
+    const commentLen = buf.readUInt16LE(offset + 32);
+    const name = buf.subarray(offset + 46, offset + 46 + nameLen).toString('utf8');
+    const localOffset = buf.readUInt32LE(offset + 42);
+    offset += 46 + nameLen + extraLen + commentLen;
+    if (!name || name.endsWith('/')) continue;
+    const rel = name.split('\\').join('/');
+    if (rel.split('/').some(seg => seg === '..' || seg === '' || isDangerousAbsolute(rel))) throw Error(`zip: refusing entry ${rel}`);
+    if (buf.readUInt32LE(localOffset) !== 0x04034b50) throw Error('zip: corrupt local header');
+    const localNameLen = buf.readUInt16LE(localOffset + 26);
+    const localExtraLen = buf.readUInt16LE(localOffset + 28);
+    const dataStart = localOffset + 30 + localNameLen + localExtraLen;
+    const raw = buf.subarray(dataStart, dataStart + compressedSize);
+    const data = method === 0 ? raw : method === 8 ? inflateRawSync(raw) : null;
+    if (data == null) throw Error(`zip: unsupported compression method ${method} for ${rel}`);
+    const out = join(destDir, rel);
+    mkdirSync(dirname(out), { recursive: true });
+    writeFileSync(out, data);
+    written.push(out);
+  }
+  return written;
+}
+
+function isDangerousAbsolute(rel) {
+  return rel.startsWith('/') || /^[a-zA-Z]:\//.test(rel);
+}
+
+/**
+ * Download + cache the bundled headless shell for this platform.
+ * `CARTHAGENT_BROWSER_VERSION` pins a specific Chrome for Testing build; the
+ * default tracks the last-known-good stable version recorded at build time.
+ * Returns the binary path. Download artifacts land in a sibling temp dir and
+ * are renamed into place so interrupted installs never leave a half binary.
+ */
+export async function ensureBundledBrowser({ version = BUNDLED_BROWSER_VERSION, fetchImpl = globalThis.fetch, base } = {}) {
+  const bin = bundledBinaryPath({ version, base });
+  if (existsSync(bin)) return bin;
+  if (typeof fetchImpl !== 'function') throw Error('Bundled browser download requires fetch support');
+  const root = browserRoot(base);
+  mkdirSync(root, { recursive: true });
+  // Stage under `root` (not tmpdir) so the final rename stays on one filesystem.
+  const stage = mkdtempSync(join(root, '.stage-'));
+  try {
+    const url = SHELL_URL(version);
+    const response = await fetchImpl(url);
+    if (!response.ok) throw Error(`Bundled browser download failed (${response.status}) for ${url}`);
+    const zip = join(stage, 'shell.zip');
+    writeFileSync(zip, Buffer.from(await response.arrayBuffer()));
+    const extracted = join(stage, 'out');
+    extractZip(zip, extracted);
+    const leaf = `chrome-headless-shell-${platformKey()}`;
+    const target = join(root, version);
+    rmSync(target, { recursive: true, force: true });
+    mkdirSync(target, { recursive: true });
+    renameSync(join(extracted, leaf), join(target, leaf));
+    const name = process.platform === 'win32' ? 'chrome-headless-shell.exe' : 'chrome-headless-shell';
+    const binary = join(target, leaf, name);
+    if (!existsSync(binary)) throw Error('Bundled browser archive did not contain the shell binary');
+    if (process.platform !== 'win32') chmodSync(binary, 0o755);
+    // Cheap self-check: the shell should answer --version without a display.
+    const probe = spawnSync(binary, ['--version'], { encoding: 'utf8', timeout: 15000 });
+    if (probe.status !== 0) {
+      rmSync(target, { recursive: true, force: true });
+      throw Error(`Bundled browser failed --version probe: ${(probe.stderr || probe.error?.message || '').slice(0, 200)}`);
+    }
+    return binary;
+  } finally {
+    rmSync(stage, { recursive: true, force: true });
+  }
+}

package/lib/browser-errors.mjs

@@ -0,0 +1,54 @@
+/** Firefox WebDriver BiDi log capture. Subscribe before navigation, never silently degrade. */
+export async function captureBrowserErrors(url) {
+  if (!url) throw Error('Driver did not provide a BiDi webSocketUrl; error capture unavailable');
+  const socket = new WebSocket(url);
+  const pending = new Map();
+  const errors = [];
+  let dropped = 0;
+  let sequence = 0;
+  let closed = false;
+  socket.addEventListener('message', event => {
+    let message;
+    try { message = JSON.parse(event.data); } catch { return; }
+    if (message.id !== undefined) {
+      const handler = pending.get(message.id);
+      if (handler) { pending.delete(message.id); handler(message); }
+    }
+    if (message.method === 'log.entryAdded' && message.params.level === 'error') {
+      const entry = message.params;
+      if (errors.length === 50) { dropped++; return; }
+      errors.push({ type: entry.type, text: String(entry.text ?? '').slice(0, 2000),
+        stack: (entry.stackTrace?.callFrames || []).slice(0, 8).map(frame => ({ url: String(frame.url).slice(0, 500), lineNumber: frame.lineNumber, columnNumber: frame.columnNumber })) });
+    }
+  });
+  socket.addEventListener('close', () => { closed = true; });
+  async function command(method, params) {
+    if (closed) throw Error('Browser error capture connection closed');
+    const id = ++sequence;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => { pending.delete(id); reject(Error(`BiDi ${method} timed out`)); }, 5000);
+      pending.set(id, message => {
+        clearTimeout(timer);
+        if (message.type === 'error') reject(Error(`BiDi ${method}: ${message.message}`));
+        else resolve(message.result);
+      });
+      socket.send(JSON.stringify({ id, method, params }));
+    });
+  }
+  try {
+    await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => reject(Error('BiDi connection timed out')), 5000);
+      socket.addEventListener('open', () => { clearTimeout(timer); resolve(); }, { once: true });
+      socket.addEventListener('error', () => { clearTimeout(timer); reject(Error('BiDi connection failed')); }, { once: true });
+    });
+    await command('session.subscribe', { events: ['log.entryAdded'] });
+  } catch (error) { socket.close(); throw error; }
+  return {
+    async inspect() {
+      // Round trip on the same event channel before consuming the observed log.
+      await command('session.status', {});
+      return { errors: [...errors], dropped };
+    },
+    close() { socket.close(); }
+  };
+}

package/lib/browser.mjs

@@ -0,0 +1,219 @@
+/**
+ * Browser testing helpers for delivery checks — fully repo-contained.
+ *
+ * Three capability tiers:
+ *   serve  — static file server over node:http (zero deps)
+ *   dom    — jsdom DOM assertions with real inline-script execution (npm dep)
+ *   shot   — headless shell screenshot: bundled chrome-headless-shell, system
+ *            Chrome/Chromium, or legacy Firefox fallback (zero npm deps)
+ *
+ * Used by tools/browser-check.mjs; also importable for custom check scripts.
+ */
+import { createServer } from 'node:http';
+import { existsSync, mkdtempSync, readFileSync, rmSync, statSync } from 'node:fs';
+import { delimiter, extname, join, resolve, normalize, isAbsolute, relative } from 'node:path';
+import { spawn } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { isSandboxFailure } from './browser-bin.mjs';
+// Load jsdom only for DOM checks; static serving and WebDriver need no DOM runtime.
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8', '.htm': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8', '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8', '.json': 'application/json; charset=utf-8',
+  '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif',
+  '.svg': 'image/svg+xml', '.webp': 'image/webp', '.ico': 'image/x-icon',
+  '.wasm': 'application/wasm', '.txt': 'text/plain; charset=utf-8',
+  '.woff': 'font/woff', '.woff2': 'font/woff2', '.map': 'application/json',
+};
+
+/** Start a static file server rooted at `root`. Returns { server, port, url, close }. */
+export function serveDir(root, { port = 0 } = {}) {
+  const base = resolve(root);
+  const server = createServer((req, res) => {
+    try {
+      const url = new URL(req.url, 'http://x');
+      let rel = decodeURIComponent(url.pathname);
+      if (rel.endsWith('/')) rel += 'index.html';
+      const full = normalize(join(base, rel));
+      const local = relative(base, full);
+      if (local === '..' || local.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`) || isAbsolute(local)) { res.writeHead(403); res.end('forbidden'); return; }
+      if (!existsSync(full) || !statSync(full).isFile()) { res.writeHead(404); res.end('not found'); return; }
+      res.writeHead(200, { 'content-type': MIME[extname(full).toLowerCase()] || 'application/octet-stream' });
+      res.end(readFileSync(full));
+    } catch (e) { res.writeHead(500); res.end(String(e)); }
+  });
+  return new Promise((ok, err) => {
+    server.once('error', err);
+    server.listen(port, '127.0.0.1', () => {
+      const p = server.address().port;
+      ok({ server, port: p, url: `http://127.0.0.1:${p}`, close: () => server.close() });
+    });
+  });
+}
+
+/**
+ * Screenshot tier: prefer the bundled/system headless shell
+ * (`chrome-headless-shell --screenshot` — no display or driver needed), fall
+ * back to Firefox when no Chromium-family binary is found. `browser` is the
+ * resolved binary path; pass the result of findBrowser()/ensureBundledBrowser()
+ * or a known binary name ('firefox' selects the Firefox flag dialect).
+ * Returns { ok, out, engine, stderr }.
+ */
+export function browserScreenshot(url, out, { width = 1280, height = 800, timeoutMs = 45000, waitSeconds, browser } = {}) {
+  const isFirefox = !browser || /firefox/i.test(browser);
+  if (isFirefox) return firefoxScreenshot(url, out, { width, height, timeoutMs, waitSeconds });
+  const abs = isAbsolute(out) ? out : resolve(out);
+  const attempt = noSandbox => new Promise((ok) => {
+    const profile = mkdtempSync(join(tmpdir(), 'carthagent-chrome-shot-'));
+    const args = [
+      ...(noSandbox ? ['--no-sandbox'] : []),
+      '--user-data-dir=' + profile, '--no-first-run', '--no-default-browser-check',
+      '--disable-extensions', '--mute-audio', '--hide-scrollbars',
+      '--screenshot=' + abs, `--window-size=${width},${height}`,
+    ];
+    // --virtual-time-budget fast-forwards timers/animation deterministically.
+    if (waitSeconds != null) args.push(`--virtual-time-budget=${Math.ceil(waitSeconds * 1000)}`);
+    args.push(url);
+    const child = spawn(browser, args, { stdio: ['ignore', 'ignore', 'pipe'] });
+    let stderr = '';
+    child.stderr.on('data', d => { stderr += d; });
+    const timer = setTimeout(() => { child.kill('SIGKILL'); }, timeoutMs);
+    const done = extra => { clearTimeout(timer); rmSync(profile, { recursive: true, force: true }); ok({ out: abs, stderr: stderr.slice(-2000), engine: 'chrome-headless-shell', ...extra }); };
+    child.on('close', code => done({ ok: code === 0 && existsSync(abs), code }));
+    child.on('error', e => done({ ok: false, error: String(e) }));
+  });
+  // Environments that block Chromium's sandbox (Ubuntu >=23.10 AppArmor,
+  // containers) get one retry with --no-sandbox.
+  return attempt(false).then(result => (result.ok || !isSandboxFailure(result.stderr || '')) ? result : attempt(true));
+}
+
+/** Find the firefox binary. Honors FIREFOX env var, then PATH, then common snap paths. */
+export function findFirefox() {
+  if (process.env.FIREFOX) return process.env.FIREFOX;
+  const names = process.platform === 'win32' ? ['firefox.exe', 'firefox'] : ['firefox'];
+  for (const dir of (process.env.PATH || '').split(delimiter)) {
+    for (const name of names) {
+      const candidate = join(dir, name);
+      if (existsSync(candidate)) return candidate;
+    }
+  }
+  for (const candidate of ['/usr/bin/firefox', '/snap/bin/firefox']) if (existsSync(candidate)) return candidate;
+  return names[0];
+}
+
+/**
+ * Take a screenshot with the system Firefox (headless). Zero npm deps.
+ * Firefox snap can only write inside $HOME — `out` must be an absolute path under HOME.
+ * Returns { ok, out, stderr }.
+ */
+export function firefoxScreenshot(url, out, { width = 1280, height = 800, timeoutMs = 45000, waitSeconds } = {}) {
+  return new Promise((ok) => {
+    const abs = isAbsolute(out) ? out : resolve(out);
+    const profile = mkdtempSync(join(tmpdir(), 'carthagent-firefox-'));
+    const args = ['--headless', '--no-remote', '--profile', profile, '--screenshot', abs, '--window-size', `${width},${height}`];
+    if (waitSeconds != null) args.push('--screenshot-delay', String(waitSeconds));
+    args.push(url);
+    const child = spawn(findFirefox(), args, { stdio: ['ignore', 'ignore', 'pipe'] });
+    let stderr = '';
+    child.stderr.on('data', d => { stderr += d; });
+    const timer = setTimeout(() => { child.kill('SIGKILL'); }, timeoutMs);
+    child.on('close', code => {
+      clearTimeout(timer);
+      rmSync(profile, { recursive: true, force: true });
+      ok({ ok: code === 0 && existsSync(abs), out: abs, code, stderr: stderr.slice(-2000) });
+    });
+    child.on('error', e => {
+      clearTimeout(timer);
+      rmSync(profile, { recursive: true, force: true });
+      ok({ ok: false, out: abs, error: String(e), stderr });
+    });
+  });
+}
+
+/**
+ * Load a page in jsdom (executes inline + same-origin scripts), then run assertions.
+ *
+ * assertions: array of
+ *   { selector, count? }                    — element exists / exact count
+ *   { selector, text?: string|RegExp }      — textContent contains/matches
+ *   { selector, attr, value? }              — attribute equals/contains
+ *   { action:'click', selector, then:assert }  — dispatch click, then assert
+ *   { action:'type', selector, value, then }   — set input value + input event
+ *   { action:'key', key, selector?, then }     — KeyboardEvent on element/document
+ *   { eval: string, expect?: any }          — evaluate JS in page context, check result
+ *   { console: 'error-free' }               — no console.error/pageerror captured
+ *
+ * Module scripts are unsupported by jsdom and fail execution-enabled checks.
+ * Use runScripts:false only for static DOM inspection, not application verification.
+ * Returns { pass, failures:[...], consoleErrors:[...], document }.
+ */
+export async function domCheck(source, assertions = [], { url, runScripts = true, waitMs = 250 } = {}) {
+  const { JSDOM, VirtualConsole } = await import('jsdom');
+  const consoleErrors = [];
+  const vc = new VirtualConsole();
+  vc.on('jsdomError', e => consoleErrors.push(String(e.detail || e)));
+  vc.on('error', (...a) => consoleErrors.push(a.join(' ')));
+
+  const html = source.startsWith('http') ? await (await fetch(source)).text() : source;
+  const dom = new JSDOM(html, {
+    url: url || (source.startsWith('http') ? source : 'http://localhost/'),
+    runScripts: runScripts ? 'dangerously' : 'outside-only',
+    resources: 'usable',
+    pretendToBeVisual: true,
+    virtualConsole: vc,
+  });
+  if (runScripts) await new Promise(r => setTimeout(r, waitMs)); // let inline scripts settle
+
+  const { document } = dom.window;
+  const failures = [];
+  if (runScripts && [...document.querySelectorAll('script')].some(script =>
+    (script.getAttribute('type') || '').toLowerCase() === 'module')) {
+    failures.push('Unsupported module scripts: jsdom does not execute them. Use a real-browser check for application verification, or runScripts:false for static DOM inspection only.');
+  }
+  const run = a => {
+    try {
+      if (a.eval) {
+        const result = dom.window.eval(a.eval);
+        if ('expect' in a && JSON.stringify(result) !== JSON.stringify(a.expect))
+          failures.push(`eval ${JSON.stringify(a.eval)} → ${JSON.stringify(result)}, expected ${JSON.stringify(a.expect)}`);
+        return;
+      }
+      if (a.console === 'error-free') return; // checked at end
+      if (a.action === 'click') {
+        const el = document.querySelector(a.selector);
+        if (!el) { failures.push(`click: ${a.selector} not found`); return; }
+        el.dispatchEvent(new dom.window.MouseEvent('click', { bubbles: true }));
+      } else if (a.action === 'type') {
+        const el = document.querySelector(a.selector);
+        if (!el) { failures.push(`type: ${a.selector} not found`); return; }
+        el.value = a.value;
+        el.dispatchEvent(new dom.window.Event('input', { bubbles: true }));
+      } else if (a.action === 'key') {
+        const target = a.selector ? document.querySelector(a.selector) : document;
+        if (!target) { failures.push(`key: ${a.selector} not found`); return; }
+        target.dispatchEvent(new dom.window.KeyboardEvent('keydown', { key: a.key, bubbles: true }));
+      }
+      if (a.then) run(a.then);
+      if (!a.selector) return;
+      const els = document.querySelectorAll(a.selector);
+      if (a.count != null && els.length !== a.count) { failures.push(`${a.selector}: count ${els.length} ≠ ${a.count}`); return; }
+      if (a.count == null && !els.length) { failures.push(`${a.selector}: not found`); return; }
+      const el = els[0];
+      if (a.text != null) {
+        const t = el.textContent || '';
+        const okText = a.text instanceof RegExp ? a.text.test(t) : t.includes(a.text);
+        if (!okText) failures.push(`${a.selector}: text ${JSON.stringify(t.slice(0, 80))} does not match ${a.text}`);
+      }
+      if (a.attr != null) {
+        const v = el.getAttribute(a.attr);
+        const okAttr = a.value == null ? v != null : String(v).includes(a.value);
+        if (!okAttr) failures.push(`${a.selector}[${a.attr}]: ${JSON.stringify(v)} does not match ${a.value ?? '(any)'}`);
+      }
+    } catch (e) { failures.push(`${a.selector || a.eval || '?'}: ${e.message}`); }
+  };
+  for (const a of assertions) run(a);
+  if (assertions.some(a => a.console === 'error-free') && consoleErrors.length)
+    failures.push(`console errors: ${consoleErrors.slice(0, 3).join(' | ')}`);
+  return { pass: failures.length === 0, failures, consoleErrors, document, window: dom.window };
+}