flowviant 0.125.20 → 0.125.21

package/bin/lib/uiReview.mjs

@@ -0,0 +1,305 @@
+/** A held builder's preview/browser supervisor. No public share or API route. */
+import { spawn, execFileSync } from 'node:child_process';
+import { createServer, request as httpRequest } from 'node:http';
+import { createHash, randomUUID } from 'node:crypto';
+import { lstatSync, readFileSync, readlinkSync, realpathSync, mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join, resolve, relative, isAbsolute } from 'node:path';
+import { tmpdir, platform } from 'node:os';
+import { listenHeldTool, heldToolArgv } from './heldTool.mjs';
+import { ensureArtifactDir, ARTIFACT_DIR } from './artifacts.mjs';
+import { measureListeners, originFor, listenersSupported } from './listeners.mjs';
+import { procStat } from './procStat.mjs';
+import { killGroup } from './processGroup.mjs';
+import { unattendedEnv } from './noWindowEnv.mjs';
+import { childEnv } from './childEnv.mjs';
+import { gitRaw } from './git.mjs';
+import { serveMcpStdio } from './mcpStdio.mjs';
+import { scrub, learnExtraSecrets, forgetExtraSecrets } from './uplinkScrub.mjs';
+import { captureLocalReview, reviewDiagnostic } from './uiReviewBrowser.mjs';
+import { validateReviewPlan, reviewPath, uiReviewInstructions, UI_REVIEW_MAX_RUNS, UI_REVIEW_TIMEOUT_MS } from './uiReviewContract.mjs';
+
+const sleep = ms => new Promise(r => setTimeout(r, ms));
+const gitRead = (wt, args, encoding = 'utf8') => gitRaw(args, wt, { encoding, timeout: 10_000, maxBuffer: 8 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] });
+
+/** Hash the actual tracked/nonignored working bytes, not just a dirty flag.
+ * Ignored runtime/build output is explicitly outside this source measurement. */
+export function reviewSourceState(wt) {
+  try {
+    const head = gitRead(wt, ['rev-parse', 'HEAD']).trim();
+    const names = [...new Set(gitRead(wt, ['ls-files', '-z', '--cached', '--others', '--exclude-standard']).split('\0').filter(Boolean))].sort();
+    if (names.length > 30_000) throw new Error('Source snapshot file bound exceeded.');
+    const hash = createHash('sha256');
+    let total = 0;
+    for (const name of names) {
+      if (name === ARTIFACT_DIR || name.startsWith(ARTIFACT_DIR + '/')) continue;
+      const path = resolve(wt, name);
+      const rel = relative(wt, path);
+      if (rel.startsWith('..') || isAbsolute(rel)) throw new Error('Source path left worktree.');
+      hash.update(JSON.stringify(name));
+      let stat;
+      try { stat = lstatSync(path); } catch (error) { if (error.code === 'ENOENT') { hash.update('deleted'); continue; } throw error; }
+      if (stat.isSymbolicLink()) hash.update('link:' + readlinkSync(path));
+      else if (stat.isFile()) {
+        total += stat.size;
+        if (total > 512 * 1024 * 1024 || stat.size > 32 * 1024 * 1024) throw new Error('Source snapshot byte bound exceeded.');
+        // No symlinked parent (including a replaced tracked directory).
+        if (realpathSync(path) !== path) throw new Error('Source snapshot encountered a linked parent.');
+        hash.update(String(stat.mode & 0o777)); hash.update(readFileSync(path));
+      } else hash.update('non-file');
+    }
+    const status = gitRead(wt, ['status', '--porcelain=v1', '--untracked-files=all']).trim();
+    return { head, digest: hash.digest('hex'), dirty: Boolean(status), scope: 'Tracked and nonignored source files; ignored build/runtime files are not measured.' };
+  } catch (error) { return { unavailable: reviewDiagnostic(error.message) }; }
+}
+
+export function sameReviewSource(a, b) {
+  return Boolean(a?.head && a?.digest && a.head === b?.head && a.digest === b?.digest);
+}
+
+function processGroup(pid) {
+  if (platform() === 'linux') return procStat(pid)?.pgrp;
+  try { return Number(execFileSync('ps', ['-o', 'pgid=', '-p', String(pid)], { encoding: 'utf8', timeout: 1000 }).trim()); } catch { return null; }
+}
+
+/** Both cwd attribution and our own process group must agree. */
+export function measuredReviewOrigin(wt, port, child) {
+  if (!listenersSupported() || !child?.pid || child.exitCode != null || child.signalCode != null) return null;
+  const rows = measureListeners(wt).rows.filter(row => row.port === port);
+  if (!rows.length || rows.some(row => processGroup(row.pid) !== child.pid)) return null;
+  const picked = originFor(wt, port);
+  if (!['127.0.0.1', '::1'].includes(picked.host)) return null;
+  return `http://${picked.host === '::1' ? '[::1]' : picked.host}:${port}`;
+}
+
+/** One proxy, one owned preview. Recheck the owner on EVERY request. No
+ * upgrade, remote redirect following, inherited auth or arbitrary host dialing.
+ * CSP blocks sockets/workers; the browser bootstrap disables WebRTC, which
+ * Chrome's CSP does not implement. Fetch alone cannot fence those transports.
+ * The app sees a new private origin and cannot borrow personal cookies. */
+export async function createReviewProxy({ upstream, stillOwned, signal }) {
+  let proxyOrigin;
+  const server = createServer((req, res) => {
+    let path;
+    try { path = reviewPath(req.url); } catch { res.writeHead(403).end(); return; }
+    if (signal?.aborted || !stillOwned() || req.headers.host !== new URL(proxyOrigin).host) { res.writeHead(503).end('Preview ownership is unavailable.'); return; }
+    const url = new URL(path, upstream);
+    const headers = { ...req.headers, host: new URL(upstream).host };
+    for (const key of ['authorization', 'proxy-authorization', 'connection', 'upgrade', 'forwarded', 'x-forwarded-for', 'x-forwarded-host']) delete headers[key];
+    // Same-UID disposable app code still owns its backend; the fixture
+    // declaration is required before this runner executes repository code.
+    const out = httpRequest(url, { method: req.method, headers, signal, timeout: 10_000 }, reply => {
+      const responseHeaders = { ...reply.headers };
+      for (const key of ['content-security-policy', 'content-security-policy-report-only', 'report-to', 'reporting-endpoints', 'nel', 'refresh', 'alt-svc', 'connection']) delete responseHeaders[key];
+      // No response may direct the browser off the measured app. Relative
+      // redirects stay local; same-upstream absolute redirects use the proxy.
+      if (responseHeaders.location) {
+        const target = new URL(responseHeaders.location, upstream);
+        if (target.origin !== upstream || target.username || target.password) { reply.resume(); res.writeHead(403).end('Off-preview redirect blocked.'); return; }
+        responseHeaders.location = target.pathname + target.search + target.hash;
+      }
+      responseHeaders['content-security-policy'] = `default-src ${proxyOrigin} data: blob:; script-src ${proxyOrigin} 'unsafe-inline' 'unsafe-eval'; style-src ${proxyOrigin} 'unsafe-inline'; connect-src ${proxyOrigin}; img-src ${proxyOrigin} data: blob:; media-src ${proxyOrigin} data: blob:; font-src ${proxyOrigin} data:; frame-src 'none'; child-src 'none'; worker-src 'none'; object-src 'none'; form-action ${proxyOrigin}; base-uri ${proxyOrigin}`;
+      responseHeaders['cache-control'] = 'no-store';
+      res.writeHead(reply.statusCode ?? 502, responseHeaders); reply.pipe(res);
+    });
+    out.on('timeout', () => out.destroy());
+    out.on('error', () => { if (!res.headersSent) res.writeHead(502); res.end('Owned preview request failed.'); });
+    req.on('aborted', () => out.destroy()); req.pipe(out);
+  });
+  server.on('upgrade', (_req, socket) => socket.destroy());
+  await new Promise((r, reject) => { server.once('error', reject); server.listen(0, '127.0.0.1', r); });
+  proxyOrigin = `http://127.0.0.1:${server.address().port}`;
+  return { origin: proxyOrigin, close() { server.close(); server.closeAllConnections(); } };
+}
+
+export function reviewEvidence(reports, finalState) {
+  if (!reports.length) return 'Local UI self-review: no browser run was requested in this turn. Browser, visual inspection and interactions are unverified; see the builder’s applicability/skipped-check explanation.';
+  const last = reports.at(-1);
+  const fresh = sameReviewSource(last.before, last.after) && sameReviewSource(last.after, finalState);
+  const lines = [
+    'Local UI self-review (runner measurements; visual interpretation remains the builder’s claim).',
+    `Final source HEAD: ${finalState.head ?? 'unavailable'}; source SHA-256: ${finalState.digest ?? 'unavailable'}; dirty: ${finalState.dirty ?? 'unknown'}. ${finalState.scope ?? finalState.unavailable ?? ''}`,
+    `Latest attempt: ${last.status}. Evidence ${fresh ? 'matches the final measured source' : 'is STALE or source identity is unavailable; earlier passing checks do not establish the final code'}.`,
+    ...reports.map((r, i) => `Attempt ${i + 1}: ${r.status}${r.reason ? ' — ' + r.reason : ''}; report: ${r.artifact ?? 'not retained'}.`),
+    `Preview basis: ${last.basis ?? 'unavailable'}. Fixture: ${last.fixture ?? 'unavailable'}.`,
+    `Tested HEAD: ${last.before?.head ?? 'unavailable'}; source SHA-256: ${last.before?.digest ?? 'unavailable'}.`,
+  ];
+  for (const requested of last.requestedScenarios ?? []) lines.push(`Requested at desktop 1440×900 and mobile 390×844: ${requested.path} — ${requested.name}; ordered checks: ${requested.actions.map(a => a.type + (a.selector ? ' ' + a.selector : '')).join(' → ') || 'captures only'}. Checks without an observed row below are unrun${last.reason ? ': ' + last.reason : ' (review ended before they completed)'}.`);
+  for (const row of last.scenarios ?? []) {
+    lines.push(`${row.viewport.name} ${row.viewport.width}×${row.viewport.height} ${row.path} — ${row.name}: ${row.status}${row.reason ? ' — ' + row.reason : ''}.`);
+    row.actions.forEach((a, i) => lines.push(`  ${i + 1}. ${a.type}${a.selector ? ' ' + a.selector : ''}: ${a.status}; ${a.outcome ?? 'expected outcome not observed'}.`));
+    for (const name of row.screenshots ?? []) lines.push(`  Screenshot: ${last.folder}/${name} (capture only).`);
+    if (row.skipped) lines.push(`  Skipped: ${row.skipped}`);
+    if (row.networkSettle) lines.push(`  Unverified: ${row.networkSettle}`);
+  }
+  lines.push(`Console errors: ${last.consoleErrors?.length ?? 0}; failed/blocked requests: ${last.failedRequests?.length ?? 0}.`);
+  lines.push(`Screenshots supplied through native image-input tool: ${last.imageInputs?.length ?? 0}. This counts image bytes supplied, not the builder’s interpretation or alternate native file/image tools.`);
+  for (const diagnostic of [...(last.consoleErrors ?? []), ...(last.failedRequests ?? [])].slice(0, 10)) lines.push(reviewDiagnostic(JSON.stringify(diagnostic)));
+  lines.push('Visual inspection is not inferred from capture or tool availability. The builder must report actual image-tool observations, fixes, reruns, remaining findings and skipped checks. Previous attempt files retain the fix/recheck history. No approval or merge was performed.');
+  return scrub(lines.join('\n'));
+}
+
+/** The CLI helper calls this capability while the chosen builder is alive.
+ * All owned processes are daemon-side and taken down on abort, timeout or close. */
+export async function createUiReview({ wt, signal, capture = captureLocalReview, timeoutMs = UI_REVIEW_TIMEOUT_MS, onChild = () => () => {} }) {
+  let closed = false, busy = false, count = 0, pending = null;
+  const reports = [];
+  const captures = new Map();
+  const controller = new AbortController();
+  const abort = () => controller.abort();
+  if (signal?.aborted) abort(); else signal?.addEventListener('abort', abort, { once: true });
+  const run = async input => {
+    if (closed || controller.signal.aborted) throw new Error('This builder turn has ended.');
+    if (busy) throw new Error('A local UI review is already running.');
+    if (count >= UI_REVIEW_MAX_RUNS) throw new Error('The three-run self-review bound was reached; report remaining findings.');
+    validateReviewPlan(input);
+    busy = true; count++;
+    const runController = new AbortController();
+    const stop = () => runController.abort();
+    controller.signal.addEventListener('abort', stop, { once: true });
+    const timer = setTimeout(stop, timeoutMs);
+    const record = { status: 'unavailable', before: reviewSourceState(wt), basis: reviewDiagnostic(input.basis), fixture: reviewDiagnostic(input.fixture.description),
+      requestedScenarios: input.scenarios.map(s => ({ name: reviewDiagnostic(s.name), path: reviewDiagnostic(s.path), actions: s.actions.map(a => ({ type: a.type, ...(a.selector ? { selector: reviewDiagnostic(a.selector) } : {}) })) })),
+      scenarios: [], consoleErrors: [], failedRequests: [] };
+    let child, proxy, scratch, artifactDir, untrack;
+    try {
+      const cwd = realpathSync(resolve(wt, input.cwd ?? '.'));
+      const rel = relative(realpathSync(wt), cwd);
+      if (isAbsolute(rel) || rel === '..' || rel.startsWith('../')) throw new Error('Preview cwd must be inside this agent worktree.');
+      if (!listenersSupported()) throw new Error('This platform cannot measure preview socket ownership.');
+      if (!ensureArtifactDir(wt)) throw new Error('A safe retained artifact directory is unavailable.');
+      const name = `ui-review-${randomUUID().slice(0, 12)}`;
+      artifactDir = join(wt, ARTIFACT_DIR, name); mkdirSync(artifactDir, { mode: 0o700 });
+      record.folder = `${ARTIFACT_DIR}/${name}`;
+      record.artifact = `${record.folder}/report.json`;
+      scratch = mkdtempSync(join(tmpdir(), 'flowviant-ui-preview-'));
+      const env = unattendedEnv(childEnv({ cwd }), { browserHome: scratch });
+      // No inherited personal home, SDK credentials or browser sessions.
+      env.HOME = scratch; env.USERPROFILE = scratch; env.XDG_CONFIG_HOME = scratch;
+      env.XDG_DATA_HOME = scratch; env.XDG_CACHE_HOME = scratch;
+      let output = '';
+      child = spawn(input.command[0], input.command.slice(1), { cwd, env, stdio: ['ignore', 'pipe', 'pipe'], detached: true });
+      untrack = onChild(child);
+      let spawnError;
+      child.on('error', error => { spawnError = error; });
+      const keep = bytes => { output = reviewDiagnostic(output + bytes.toString()).slice(-2000); };
+      child.stdout.on('data', keep); child.stderr.on('data', keep);
+      const kill = () => killGroup(child);
+      runController.signal.addEventListener('abort', kill, { once: true });
+      let upstream;
+      const start = Date.now();
+      while (!runController.signal.aborted && Date.now() - start < Math.min(30_000, timeoutMs)) {
+        if (spawnError) throw spawnError;
+        upstream = measuredReviewOrigin(cwd, input.port, child);
+        if (upstream) break;
+        if (child.exitCode != null) throw new Error(`Preview exited (${child.exitCode}). ${output}`);
+        await sleep(150);
+      }
+      if (!upstream) throw new Error(`Preview readiness unavailable: no owned listener measured. ${output}`);
+      const stillOwned = () => measuredReviewOrigin(cwd, input.port, child) === upstream;
+      proxy = await createReviewProxy({ upstream, stillOwned, signal: runController.signal });
+      // A real successful HTTP response, no redirect-following, after socket
+      // attribution. Never probe an unrelated or merely guessed port.
+      let ready = false;
+      while (!runController.signal.aborted && Date.now() - start < Math.min(30_000, timeoutMs)) {
+        try {
+          const reply = await fetch(proxy.origin + reviewPath(input.readyPath ?? '/'), { redirect: 'manual', signal: AbortSignal.any([runController.signal, AbortSignal.timeout(1500)]) });
+          ready = reply.status >= 200 && reply.status < 400;
+          await reply.body?.cancel();
+          if (ready) break;
+        } catch { /* startup not ready yet */ }
+        await sleep(150);
+      }
+      if (!ready || !stillOwned()) throw new Error('The owned preview did not become HTTP-ready.');
+      record.preview = { upstream, proxy: proxy.origin, pid: child.pid, readyPath: input.readyPath ?? '/', command: input.command.map(reviewDiagnostic), cwd: input.cwd ?? '.' };
+      Object.assign(record, await capture({ origin: proxy.origin, scenarios: input.scenarios, artifactDir, signal: runController.signal, timeoutMs, onChild }));
+    } catch (error) { record.reason = reviewDiagnostic(error.message); }
+    finally {
+      clearTimeout(timer); controller.signal.removeEventListener('abort', stop);
+      runController.abort(); proxy?.close(); killGroup(child);
+      child?.stdout?.destroy(); child?.stderr?.destroy();
+      if (child && child.exitCode == null && child.signalCode == null) await Promise.race([new Promise(r => child.once('exit', r)), sleep(500)]);
+      untrack?.();
+      if (scratch) try { rmSync(scratch, { recursive: true, force: true }); } catch { /* never reused */ }
+      record.after = reviewSourceState(wt);
+      record.sourceStable = sameReviewSource(record.before, record.after);
+      reports.push(record); busy = false;
+      for (const name of record.screenshots ?? []) {
+        const path = `${record.folder}/${name}`;
+        const bytes = readFileSync(join(wt, path));
+        captures.set(path, { digest: createHash('sha256').update(bytes).digest('hex'), record });
+      }
+      if (artifactDir) writeFileSync(join(artifactDir, 'report.json'), scrub(JSON.stringify(record, null, 2)), { flag: 'wx' });
+    }
+    return { ...record, screenshots: (record.screenshots ?? []).map(name => `${record.folder}/${name}`), next: 'Open every screenshot with a real image-input tool, inspect findings, fix in scope and rerun (at most three attempts). Source edits invalidate earlier checks.' };
+  };
+  let held;
+  try {
+    held = await listenHeldTool({ envPrefix: 'FLOWVIANT_UI_REVIEW', verb: '__ui-review', requestTimeoutMs: timeoutMs + 5000, isClosed: () => closed || controller.signal.aborted,
+      respond: async (req, res) => {
+        try {
+          let body = '';
+          for await (const chunk of req) { body += chunk; if (body.length > 64 * 1024) throw new Error('UI review plan exceeds 64 KiB.'); }
+          const input = JSON.parse(body);
+          if (input.operation === 'inspect_screenshot') {
+            const capture = captures.get(input.path);
+            if (!capture) throw new Error('Select an exact screenshot path returned by this turn’s runner.');
+            const path = join(wt, input.path);
+            if (!lstatSync(path).isFile() || realpathSync(path) !== path) throw new Error('The captured image is no longer a regular local file.');
+            const bytes = readFileSync(path);
+            if (bytes.length > 2 * 1024 * 1024 || createHash('sha256').update(bytes).digest('hex') !== capture.digest) throw new Error('The screenshot changed after capture; rerun its review.');
+            capture.record.imageInputs ??= [];
+            if (!capture.record.imageInputs.includes(input.path)) capture.record.imageInputs.push(input.path);
+            res.writeHead(200, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' }).end(JSON.stringify({ path: input.path, mimeType: 'image/png', data: bytes.toString('base64'), note: 'Captured image supplied to this tool. Report what you actually see; this receipt alone is not a visual verdict.' }));
+            return;
+          }
+          if (busy) throw new Error('A local UI review is already running.');
+          pending = run(input);
+          const result = await pending;
+          res.writeHead(200, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' }).end(scrub(JSON.stringify(result)));
+        } catch (error) { res.writeHead(409, { 'Content-Type': 'application/json' }).end(JSON.stringify({ error: reviewDiagnostic(error.message) })); }
+      } });
+  } catch (error) { signal?.removeEventListener('abort', abort); throw error; }
+  const secretKey = `ui-review:${held.capability.slice(0, 12)}`;
+  learnExtraSecrets(secretKey, [{ name: 'FLOWVIANT_UI_REVIEW_CAPABILITY', value: held.capability }]);
+  return { env: held.env, config: { command: process.execPath, args: heldToolArgv('__ui-review-mcp'), env: held.env }, instructions: uiReviewInstructions([process.execPath, ...heldToolArgv('__ui-review')]),
+    async close() {
+      closed = true; controller.abort(); held.server.close(); held.server.closeAllConnections();
+      await pending?.catch(() => {}); signal?.removeEventListener('abort', abort); forgetExtraSecrets(secretKey);
+    },
+    finalize() {
+      const state = reviewSourceState(wt);
+      const evidence = reviewEvidence(reports, state);
+      if (reports.at(-1)?.folder) writeFileSync(join(wt, reports.at(-1).folder, 'delivery-state.json'), scrub(JSON.stringify({ finalState: state, latestMatches: sameReviewSource(reports.at(-1).after, state) && reports.at(-1).sourceStable, imageInputs: reports.flatMap(r => r.imageInputs ?? []) }, null, 2)));
+      return evidence;
+    },
+  };
+}
+
+/** No MCP assumption: every supported build CLI can use its existing shell. */
+export async function uiReviewMain(mcp = false) {
+  if (mcp) {
+    await serveMcpStdio({ serverInfo: { name: 'card-ui-review', version: '1.0.0' }, rawResult: true,
+      tools: [{ name: 'inspect_screenshot', description: 'Open an exact PNG from this builder turn’s local UI-review output as native image input. Inspect it and report actual visual findings; capture alone is not inspection.', inputSchema: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'], additionalProperties: false } }],
+      call: async (_name, { path }) => {
+        const result = await callUiReview({ operation: 'inspect_screenshot', path });
+        return { content: [{ type: 'text', text: `${result.path}: ${result.note}` }, { type: 'image', mimeType: result.mimeType, data: result.data }] };
+      } });
+    return;
+  }
+  try {
+    const path = process.argv[3];
+    if (!path || lstatSync(path).size > 64 * 1024 || !lstatSync(path).isFile()) throw new Error('Supply a regular JSON plan file under 64 KiB.');
+    const plan = validateReviewPlan(JSON.parse(readFileSync(path, 'utf8')));
+    const result = await callUiReview(plan);
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  } catch (error) { process.stderr.write(reviewDiagnostic(error.message) + '\n'); process.exitCode = 1; }
+}
+
+async function callUiReview(input) {
+  const url = new URL(process.env.FLOWVIANT_UI_REVIEW_URL);
+  if (url.protocol !== 'http:' || url.hostname !== '127.0.0.1' || url.pathname !== '/' || url.username || url.password) throw new Error('No held builder UI-review capability is available.');
+  const response = await fetch(url, { method: 'POST', headers: { Authorization: `Bearer ${process.env.FLOWVIANT_UI_REVIEW_CAPABILITY}`, 'Content-Type': 'application/json' }, body: JSON.stringify(input), signal: AbortSignal.timeout(UI_REVIEW_TIMEOUT_MS + 10_000) });
+  const result = await response.json();
+  if (!response.ok) throw new Error(result.error ?? 'Local UI review failed.');
+  return result;
+}

package/bin/lib/uiReviewBrowser.mjs

@@ -0,0 +1,212 @@
+import { spawn } from 'node:child_process';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir, platform } from 'node:os';
+import { createCdpClient } from './pinnedCapture.mjs';
+import { resolveBrowser, chromeFlags, sandboxOff } from './shot.mjs';
+import { unattendedEnv } from './noWindowEnv.mjs';
+import { childEnv } from './childEnv.mjs';
+import { killGroup } from './processGroup.mjs';
+import { scrub } from './uplinkScrub.mjs';
+import { UI_REVIEW_TIMEOUT_MS, UI_REVIEW_VIEWPORTS } from './uiReviewContract.mjs';
+
+export function reviewRequestAllowed(value, origin) {
+  try { const u = new URL(value); return u.protocol === 'http:' && u.origin === origin && !u.username && !u.password; }
+  catch { return false; }
+}
+
+/** URLs lose query, fragment and userinfo before retention. Text uses the
+ * daemon's existing learned-value/credential-shape scrub, then is bounded. */
+export function reviewDiagnostic(value) {
+  return scrub(String(value).replace(/https?:\/\/[^\s"'<>]+/g, raw => {
+    try { const u = new URL(raw); return u.origin + u.pathname; } catch { return '[URL]'; }
+  })).slice(0, 1000);
+}
+
+const delay = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+// Chrome does not implement the proposed CSP webrtc directive. Install this
+// before any document script, including in child frames. Frames/workers/new
+// targets are independently blocked; the aliases cannot be restored by page
+// script. No existing artifact policy is changed.
+export const LOCAL_REVIEW_BOOTSTRAP = `for (const name of ['RTCPeerConnection', 'webkitRTCPeerConnection']) {
+  Object.defineProperty(globalThis, name, { value: undefined, configurable: false, writable: false });
+}`;
+
+/** A fresh profile and browser context per scenario/viewport. The origin is
+ * the supervisor's preview-only proxy, never a free-form browser destination.
+ * This records captures, not an assertion that a model has inspected them. */
+export async function captureLocalReview({ origin, scenarios, artifactDir, signal,
+  browser = resolveBrowser(), spawnImpl = spawn, timeoutMs = UI_REVIEW_TIMEOUT_MS, onChild = () => () => {} }) {
+  const result = { status: 'unavailable', scenarios: [], consoleErrors: [], failedRequests: [], screenshots: [] };
+  if (!browser) return { ...result, reason: 'No Chrome/Chromium/Edge found; no browser checks ran.' };
+  if (browser.viaWindows) return { ...result, reason: 'WSL Windows interop cannot carry the scoped DevTools pipe.' };
+  if (signal?.aborted) return { ...result, reason: 'Review was cancelled before launch.' };
+  const profile = mkdtempSync(join(tmpdir(), 'flowviant-ui-browser-'));
+  let child, cdp, timer, abort, untrack;
+  const deadline = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new Error('Browser review timed out.')), timeoutMs);
+    abort = () => reject(new Error('Browser review cancelled.'));
+    signal?.addEventListener('abort', abort, { once: true });
+  });
+  let stopped = false;
+  const run = async () => {
+    child = spawnImpl(browser.bin, [
+      ...chromeFlags({ headlessFlag: '--headless=new', noSandbox: sandboxOff(), userDataDir: profile, width: 1440, height: 900 }),
+      '--remote-debugging-pipe', '--disable-background-networking', '--disable-extensions',
+      '--disable-sync', '--no-first-run', '--disable-default-apps',
+      '--force-webrtc-ip-handling-policy=disable_non_proxied_udp', 'about:blank',
+    ], { stdio: ['ignore', 'ignore', 'pipe', 'pipe', 'pipe'], detached: platform() !== 'win32', env: unattendedEnv({ ...childEnv(), HOME: profile, USERPROFILE: profile, XDG_CONFIG_HOME: profile, XDG_DATA_HOME: profile, XDG_CACHE_HOME: profile }, { browserHome: profile }) });
+    untrack = onChild(child);
+    if (!child.stdio?.[3] || !child.stdio?.[4]) throw new Error('No DevTools pipe is available.');
+    let stderr = '';
+    child.stderr?.on('data', data => { stderr = reviewDiagnostic(stderr + data.toString()).slice(-2000); });
+    cdp = createCdpClient(child.stdio[3], child.stdio[4]);
+    child.on('error', error => cdp.close(reviewDiagnostic(error.message)));
+    child.on('exit', code => cdp.close(`Chromium exited (${code}). ${stderr}`));
+    child.stdio[3].on('error', () => {});
+    child.stdio[4].on('error', () => {});
+    await cdp.send('Browser.getVersion');
+    await cdp.send('Browser.setDownloadBehavior', { behavior: 'deny' });
+    const attached = new Map();
+    let active = null, creating = false;
+    const keep = (list, item) => { if (list.length < 100) list.push(item); else result.diagnosticsTruncated = true; };
+    cdp.on(msg => {
+      const p = msg.params ?? {};
+      if (msg.method === 'Target.attachedToTarget' && !msg.sessionId) {
+        attached.set(p.targetInfo.targetId, p.sessionId);
+        if (!creating && p.targetInfo.targetId !== active?.targetId) {
+          cdp.send('Target.closeTarget', { targetId: p.targetInfo.targetId }).catch(() => {});
+          // Chrome's startup blank tab and late attach events from contexts
+          // we just disposed are not windows the app opened.
+          if (active && p.targetInfo.openerId === active.targetId) keep(result.failedRequests, { reason: 'A new window/target was blocked.' });
+        }
+      }
+      if (!active || msg.sessionId !== active.sessionId) return;
+      if (msg.method === 'Fetch.requestPaused') {
+        const allowed = reviewRequestAllowed(p.request?.url, origin);
+        if (!allowed) keep(result.failedRequests, { url: reviewDiagnostic(p.request?.url), reason: 'Outside measured preview; blocked.' });
+        cdp.send(allowed ? 'Fetch.continueRequest' : 'Fetch.failRequest', { requestId: p.requestId, ...(!allowed ? { errorReason: 'BlockedByClient' } : {}) }, active.sessionId).catch(() => {});
+      }
+      if (msg.method === 'Runtime.exceptionThrown') keep(result.consoleErrors, { scenario: active.name, message: reviewDiagnostic(p.exceptionDetails?.exception?.description ?? p.exceptionDetails?.text ?? 'Page exception') });
+      if (msg.method === 'Runtime.consoleAPICalled' && p.type === 'error') keep(result.consoleErrors, { scenario: active.name, message: reviewDiagnostic((p.args ?? []).map(a => a.value == null ? a.description ?? a.type : String(a.value)).join(' ')) });
+      if (msg.method === 'Log.entryAdded' && p.entry?.level === 'error') keep(result.consoleErrors, { scenario: active.name, message: reviewDiagnostic(p.entry.text) });
+      if (msg.method === 'Network.requestWillBeSent') {
+        active.requests.set(p.requestId, reviewDiagnostic(p.request?.url)); active.pending.add(p.requestId); active.networkAt = Date.now();
+      }
+      if (['Network.loadingFinished', 'Network.loadingFailed'].includes(msg.method)) { active.pending.delete(p.requestId); active.networkAt = Date.now(); }
+      if (msg.method === 'Network.loadingFailed') keep(result.failedRequests, { scenario: active.name, url: active.requests.get(p.requestId), reason: reviewDiagnostic(p.errorText) });
+      if (msg.method === 'Network.responseReceived' && p.response?.status >= 400) keep(result.failedRequests, { scenario: active.name, url: reviewDiagnostic(p.response.url), status: p.response.status });
+    });
+    await cdp.send('Target.setAutoAttach', { autoAttach: true, waitForDebuggerOnStart: true, flatten: true });
+    for (const viewport of UI_REVIEW_VIEWPORTS) {
+      for (const [index, scenario] of scenarios.entries()) {
+        if (stopped || signal?.aborted) throw new Error('Browser review cancelled.');
+        const row = { name: reviewDiagnostic(scenario.name), path: reviewDiagnostic(scenario.path), viewport,
+          actions: scenario.actions.map(action => ({ type: action.type, ...(action.selector ? { selector: reviewDiagnostic(action.selector) } : {}), status: 'skipped', outcome: 'A preceding state/action was not observed.' })), screenshots: [], status: 'failed' };
+        result.scenarios.push(row);
+        const { browserContextId } = await cdp.send('Target.createBrowserContext', { disposeOnDetach: true });
+        let captureFailure;
+        try {
+          creating = true;
+          const { targetId } = await cdp.send('Target.createTarget', { url: 'about:blank', browserContextId });
+          for (let n = 0; !attached.has(targetId) && n < 20; n++) await delay(25);
+          const sessionId = attached.get(targetId) ?? (await cdp.send('Target.attachToTarget', { targetId, flatten: true })).sessionId;
+          active = { targetId, sessionId, name: `${viewport.name}: ${scenario.name}`, requests: new Map(), pending: new Set(), networkAt: Date.now() };
+          creating = false;
+          for (const other of attached.keys()) if (other !== targetId) cdp.send('Target.closeTarget', { targetId: other }).catch(() => {});
+          const send = (method, params = {}) => cdp.send(method, params, sessionId);
+          const evaluate = async expression => {
+            const answer = await send('Runtime.evaluate', { expression, returnByValue: true, awaitPromise: true });
+            if (answer.exceptionDetails) throw new Error('Page evaluation failed; inspect console diagnostics.');
+            return answer.result?.value;
+          };
+          const until = async expression => {
+            for (let n = 0; n < 50; n++) {
+              if (stopped || signal?.aborted) throw new Error('Review cancelled.');
+              try { if (await evaluate(expression)) return; } catch { /* a navigation replaced the context */ }
+              await delay(100);
+            }
+            throw new Error('Expected state was not observed within five seconds.');
+          };
+          const settle = async () => {
+            const start = Date.now();
+            while (Date.now() - start < 2000) {
+              if (stopped || signal?.aborted) throw new Error('Review cancelled.');
+              if (!active.pending.size && Date.now() - active.networkAt >= 200) return;
+              await delay(50);
+            }
+            row.networkSettle = 'Requests did not settle within two seconds; later diagnostics are unverified.';
+          };
+          await send('Page.enable');
+          await send('Runtime.enable');
+          await send('Network.enable');
+          await send('Log.enable');
+          await send('Page.addScriptToEvaluateOnNewDocument', { source: LOCAL_REVIEW_BOOTSTRAP });
+          await send('Fetch.enable', { patterns: [{ urlPattern: '*', requestStage: 'Request' }] });
+          await send('Emulation.setDeviceMetricsOverride', { width: viewport.width, height: viewport.height, mobile: viewport.mobile, deviceScaleFactor: 1 });
+          await send('Emulation.setTouchEmulationEnabled', { enabled: viewport.mobile });
+          await send('Runtime.runIfWaitingForDebugger');
+          const url = new URL(scenario.path, origin).href;
+          const nav = await send('Page.navigate', { url });
+          if (nav.errorText) throw new Error(reviewDiagnostic(nav.errorText));
+          await until(`location.origin === ${JSON.stringify(origin)} && location.href !== 'about:blank' && document.readyState === 'complete'`);
+          await settle();
+          const screenshot = async phase => {
+            const history = await send('Page.getNavigationHistory');
+            if (!reviewRequestAllowed(history.entries?.[history.currentIndex]?.url, origin)) throw new Error('The document left the measured preview.');
+            const shot = await send('Page.captureScreenshot', { format: 'png' });
+            const bytes = Buffer.from(shot.data ?? '', 'base64');
+            if (!bytes.length || bytes.length > 2 * 1024 * 1024) throw new Error('Screenshot was empty or exceeded the retained artifact size.');
+            const name = `${viewport.name}-${index + 1}-${phase}.png`;
+            writeFileSync(join(artifactDir, name), bytes, { flag: 'wx' });
+            row.screenshots.push(name); result.screenshots.push(name);
+          };
+          captureFailure = () => screenshot('failure');
+          await screenshot('initial');
+          for (const [actionIndex, action] of scenario.actions.entries()) {
+            const observed = row.actions[actionIndex];
+            observed.status = 'failed'; delete observed.outcome;
+            const select = `document.querySelector(${JSON.stringify(action.selector ?? '')})`;
+            if (action.type === 'assertUrl') await until(`location.origin === ${JSON.stringify(origin)} && location.pathname + location.search + location.hash === ${JSON.stringify(action.value)}`);
+            else {
+              await until(`!!${select}`);
+              if (action.type === 'assertText') await until(`(${select}?.textContent ?? '').includes(${JSON.stringify(action.value)})`);
+              if (['click', 'fill', 'submit'].includes(action.type)) {
+                const operation = action.type === 'click' ? 'el.click();'
+                  : action.type === 'submit' ? 'if (!(el instanceof HTMLFormElement)) throw Error("Expected form"); el.requestSubmit();'
+                    : `const setter = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(el), 'value')?.set; if (!setter) throw Error('Expected input'); setter.call(el, ${JSON.stringify(action.value)}); el.dispatchEvent(new Event('input', { bubbles: true })); el.dispatchEvent(new Event('change', { bubbles: true }));`;
+                await evaluate(`(() => { const el = ${select}; if (!el || el.disabled || !el.getClientRects().length) throw Error('Control unavailable'); ${operation} return true; })()`);
+              }
+            }
+            observed.status = 'observed';
+            observed.outcome = ['assertText', 'assertUrl', 'waitFor'].includes(action.type) ? 'Expected state observed.' : 'DOM action dispatched; subsequent assertions establish its outcome.';
+          }
+          await settle();
+          await screenshot('final');
+          row.status = scenario.actions.some(a => a.type.startsWith('assert')) ? 'observed' : 'captured';
+          if (!scenario.actions.length) row.skipped = 'No interaction scenarios supplied; captures only.';
+        } catch (error) {
+          row.reason = reviewDiagnostic(error.message);
+          await captureFailure?.().catch(() => {});
+        }
+        finally { active = null; creating = false; await cdp.send('Target.disposeBrowserContext', { browserContextId }).catch(() => {}); }
+      }
+    }
+    result.status = result.scenarios.some(row => row.status === 'failed') || result.consoleErrors.length || result.failedRequests.length ? 'findings' : 'captured';
+    result.visualInspection = 'Not measured by Chromium. The builder must open screenshots with an actual image-input tool and report its observations.';
+    return result;
+  };
+  try { return await Promise.race([run(), deadline]); }
+  catch (error) { return { ...result, status: 'unavailable', reason: reviewDiagnostic(error.message) }; }
+  finally {
+    stopped = true;
+    clearTimeout(timer); signal?.removeEventListener('abort', abort);
+    killGroup(child); cdp?.close('Browser review ended.');
+    for (const fd of [2, 3, 4]) child?.stdio?.[fd]?.destroy();
+    // Give the killed group a short bounded opportunity to release its profile.
+    if (child && child.exitCode == null && child.signalCode == null) await Promise.race([new Promise(r => child.once('exit', r)), delay(500)]);
+    try { rmSync(profile, { recursive: true, force: true }); } catch { /* never reuse this profile */ }
+    untrack?.();
+  }
+}

package/bin/lib/uiReviewContract.mjs

@@ -0,0 +1,51 @@
+/** Local UI review is a builder tool, never an approval or a pre-review. */
+export const UI_REVIEW_MAX_RUNS = 3;
+export const UI_REVIEW_TIMEOUT_MS = 120_000;
+export const UI_REVIEW_VIEWPORTS = Object.freeze([
+  { name: 'desktop', width: 1440, height: 900, mobile: false },
+  { name: 'mobile', width: 390, height: 844, mobile: true },
+]);
+
+/** Only relative routes on the measured preview; no repaired URLs. */
+export function reviewPath(value) {
+  if (typeof value !== 'string' || !value.startsWith('/') || value.startsWith('//') || /[\\\r\n]/.test(value)) throw new Error('Review routes must be local absolute paths.');
+  const url = new URL(value, 'http://preview.invalid');
+  if (url.origin !== 'http://preview.invalid' || url.username || url.password) throw new Error('Review route left the preview.');
+  return url.pathname + url.search + url.hash;
+}
+
+/** Shared input for the command client, supervisor and Chromium runner.
+ * command is argv, cwd is worktree-relative, port is explicitly configured in
+ * that repository command. No auto-install, public tunnel or personal session.
+ * captureLocalReview({ origin, scenarios, artifactDir, signal }) returns
+ * { status, reason?, scenarios, consoleErrors, failedRequests, screenshots }.
+ * createUiReview({ wt, signal }) returns { env, instructions, close, finalize }.
+ * finalize() returns Markdown evidence after remeasuring the final worktree.
+ */
+export function validateReviewPlan(plan) {
+  if (!plan || !Array.isArray(plan.command) || !plan.command.length || plan.command.length > 40 || plan.command.some(s => typeof s !== 'string' || !s || s.length > 4000)) throw new Error('Supply the repository-supported preview command as an argv array.');
+  if (!Number.isInteger(plan.port) || plan.port < 1024 || plan.port > 65535) throw new Error('Supply a dedicated unprivileged preview port.');
+  if (typeof plan.basis !== 'string' || !plan.basis.trim()) throw new Error('Name the repository file/script establishing this preview command.');
+  if (plan.fixture?.isolated !== true || typeof plan.fixture.description !== 'string' || !plan.fixture.description.trim()) throw new Error('Describe isolated fixtures or disposable test state before browsing.');
+  if (!Array.isArray(plan.scenarios) || !plan.scenarios.length || plan.scenarios.length > 8) throw new Error('Supply one to eight acceptance scenarios.');
+  const kinds = ['click', 'fill', 'submit', 'assertText', 'assertUrl', 'waitFor'];
+  for (const scenario of plan.scenarios) {
+    reviewPath(scenario.path);
+    if (typeof scenario.name !== 'string' || !scenario.name.trim() || scenario.name.length > 200) throw new Error('Name each acceptance scenario.');
+    if (!Array.isArray(scenario.actions) || scenario.actions.length > 20) throw new Error('Each scenario takes at most twenty ordered actions.');
+    for (const action of scenario.actions) {
+      if (!kinds.includes(action.type)) throw new Error('Unsupported review action.');
+      if (action.type === 'assertUrl') reviewPath(action.value);
+      else if (typeof action.selector !== 'string' || !action.selector || action.selector.length > 1000) throw new Error('Supply a bounded CSS selector.');
+      if (['fill', 'assertText'].includes(action.type) && (typeof action.value !== 'string' || action.value.length > 4000)) throw new Error('Supply a bounded fixture value or expected text.');
+    }
+  }
+  reviewPath(plan.readyPath ?? '/');
+  return plan;
+}
+
+export function uiReviewInstructions(argv) {
+  return `LOCAL UI SELF-REVIEW — before delivering UI-changing code, use this turn's owned headless runner: ${JSON.stringify([...argv, '<plan.json>'])}.
+Read repository preview scripts and affected acceptance criteria first. Write a JSON plan with command (argv array), basis (repository file/script), cwd (relative directory, optional), port (dedicated port explicitly set in command), readyPath, fixture: { isolated: true, description }, and scenarios: [{ name, path, actions: [{ type, selector, value }] }]. Actions: click, fill, submit, assertText, assertUrl (value is a local path), waitFor. Use only disposable local fixtures; never production data, real email, payments, personal sessions or credentials. The runner starts and measures its own preview and permits only that preview's resources. External dependencies are blocked and reported; use local fixtures instead.
+Run desktop and mobile scenarios; read the returned report and OPEN EVERY returned screenshot using card_ui_review.inspect_screenshot when that tool is actually mounted (it returns the exact PNG as native image input), or your runtime's actual image-input tool (for example Read or view_image). Record which files you visually inspected and what you observed in delivery verification. A PNG path, capture success, tool listing or a skill is not proof of inspection. If image input is unavailable, report visual inspection skipped with its measured reason. Check console/network findings, expected and observed interaction results. Fix in-scope problems in this same worktree and rerun affected checks. At most ${UI_REVIEW_MAX_RUNS} runs per turn, each at most ${UI_REVIEW_TIMEOUT_MS / 1000}s; at the bound deliver remaining findings honestly. Later source edits invalidate earlier evidence; commit before the final run when possible. Include changed routes, ordered actions/outcomes, viewport sizes, screenshots, changes prompted by review and every unrun/unavailable check with reasons in verification. Missing browser, runnable preview or safe fixtures is unavailable, never passed; do not install tools or weaken isolation. This review never approves or merges work. For non-UI changes, state why browser review is not applicable.`;
+}

package/bin/lib/uiReviewTurn.mjs

@@ -0,0 +1,15 @@
+/** Applied at every builder spawn, including native resumes and delivery
+ * continuations. Some CLIs do not reread system text on resume, so the same
+ * turn-scoped capability instructions also travel with its prompt. */
+export function withUiReview(args, instructions, env) {
+  if (!instructions) return args;
+  return { ...args, prompt: `${args.prompt ?? ''}\n\n${instructions}`,
+    system: `${args.system ?? ''}\n\n${instructions}`,
+    ...(env ? { mcpEnv: { ...args.mcpEnv, ...env } } : {}),
+  };
+}
+
+/** Browser observations share the existing delivery Verification surface. */
+export function appendUiReviewEvidence(body, evidence) {
+  if (body.outcome === 'delivered' && evidence) body.verification = [body.verification, evidence].filter(Boolean).join('\n\n');
+}