flowviant 0.125.20 → 0.125.21

package/README.md

@@ -188,7 +188,17 @@ From **0.86.0**, a project whose owner turns on **Publish agent branches** has e
 
 You run your dev server yourself, in the session's own worktree, exactly as you would in any terminal. The daemon NOTICES the listening port; ask for a share in the app and it puts a [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) quick tunnel in front of it (auto-fetched if missing, pinned and checksummed), behind the daemon's own gate. Viewers reach the share through Flowviant's relay at `<name>.flowviant.dev`, never the tunnel's own address, and the gate admits only the share's password or a short-lived grant signed with the share's key. Flowviant stores that key and the password with the share, and its relay mints grants for signed-in project members — or for anyone with the link, if the share's owner opens it to everyone. Since 0.72.0 the gate also lets the Workbench embed the share in a frame: it rewrites the response's frame policy to permit exactly the app's origin, and a framed sign-in gets a partitioned cookie so it works where third-party cookies are blocked.
 
-The daemon never executes anything the repository declares. An earlier version read a `.flowviant/preview.json` from the branch and spawned the command it named — that start path was removed in 0.53.0 and is not coming back; see the header of `bin/lib/preview.mjs` for exactly what it did, so nobody rebuilds it.
+Sharing never starts a repository command. An earlier version read a `.flowviant/preview.json` from the branch and spawned the command it named — that sharing start path was removed in 0.53.0; see the header of `bin/lib/preview.mjs`.
+
+## Local UI self-review in code agents
+
+During a code build, the same agent can run a bounded local Chromium review before delivery. Its turn supplies the exact helper command and JSON-plan format. The agent chooses the repository-supported preview argv and dedicated port, names its script/configuration basis, and describes disposable fixtures. The runner starts that command inside the worktree with an isolated home and no inherited SDK credentials, measures its listener and process group, then checks HTTP readiness. It does not install a browser or dependencies, share a preview, or open a public tunnel.
+
+Each plan contains local routes and ordered CSS-selector actions (`click`, `fill`, `submit`, `waitFor`, `assertText`, `assertUrl`). Chromium uses fresh contexts for 1440×900 desktop and 390×844 mobile captures. Click/submit mean DOM activation; assertions establish the resulting state. A preview-only proxy and request fence block other destinations, popups, downloads, frames, workers and sockets. Apps requiring those capabilities must report the affected checks skipped or use a disposable fixture that works within this boundary. Repository code still executes as the user's UID; the runner is not a sandbox for a malicious backend or a substitute for choosing safe fixtures.
+
+On Claude Code and Codex build turns, `card_ui_review.inspect_screenshot` can supply an exact captured PNG as native image input. The agent must actually inspect the images and report what it saw, or report the runtime's image-input failure. A screenshot or image-input receipt alone never counts as a visual verdict. Other build CLIs can use their existing image tools if available and must name unavailable capabilities honestly.
+
+The agent can fix in-scope findings and rerun up to three attempts per turn, each capped at two minutes including startup. Every attempt stops its owned browser and preview, including on cancellation; teardown also tracks their process groups. Reports and screenshots use `.flowviant/artifacts/`, and the existing delivery Verification retains routes, viewports, actions/outcomes, scrubbed diagnostics and source identity. Tracked/nonignored file bytes and HEAD are remeasured at delivery; later changes mark evidence stale. Ignored build/runtime files are outside that source measurement. The project check, fresh read-only pre-review, human approval and merge remain separate.
 
 ## Modes
 

package/bin/cli.mjs

@@ -85,6 +85,19 @@ if (process.argv[2] === '__capture-mcp') {
   process.exit(process.exitCode ?? 0);
 }
 
+if (process.argv[2] === '__reference-mcp') {
+  await (await import('./lib/publicReferenceTool.mjs')).referenceToolMain();
+  // A screenshot can exceed the pipe buffer. EOF on the client's input must
+  // not truncate a completed result while stdout is still draining.
+  await new Promise(resolve => process.stdout.write('', resolve));
+  process.exit(process.exitCode ?? 0);
+}
+
+if (['__ui-review', '__ui-review-mcp'].includes(process.argv[2])) {
+  await (await import('./lib/uiReview.mjs')).uiReviewMain(process.argv[2] === '__ui-review-mcp');
+  process.exit(process.exitCode ?? 0);
+}
+
 if (process.argv[2] === '__orchestrator-mcp') {
   await (await import('./lib/orchestratorClient.mjs')).orchestratorMcpMain();
   process.exit(process.exitCode ?? 0);

package/bin/lib/artifactContracts.mjs

@@ -158,7 +158,54 @@ export const LOOK_HEADLESS = `${NO_WINDOW} To look at your page, screenshot it
  * so it posts to `parent` with `'*'`; the app accepts only its own frame's
  * messages. A page with no handshake (every 0.105.0 bundle) is still viewed;
  * it is just never offered a Download .glb.
+ *
+ * THE MANIFEST AND THE POSTER (2026-10-25, the owner's `Output Viewer Frame`;
+ * decision record `2026-10-25-flowviant-draws-standard-outputs`). Flowviant
+ * draws the exported GLB in its own viewer, and every control over it, so the
+ * page becomes a full-bleed canvas and its folder gains `view.json`, the
+ * manifest the web reads when present (packages/shared/src/modelViewer.ts —
+ * its literal here is `MODEL_VIEW_MANIFEST`, held to that schema by
+ * agentTaskKinds.test.mjs). It uploads on the general rule — an allowlisted
+ * type the turn changed is prepared and sent (intermediateArtifacts.mjs) — so
+ * only these words had been keeping it out. It proves no delivery: the page
+ * and its measured export still do.
+ *
+ * THE POSTER IS THE DAEMON'S RENDER OF THE PAGE (0.125.21). These words first
+ * asked the agent to screenshot its own `poster.png`, the still a list or a
+ * nested kit shows without loading a GLB; but a Claude model card cannot run
+ * Chrome under its fenced shell, and the daemon already renders every HTML
+ * artifact it uploads (artifactPreview.mjs `renderDesignPreview`), which the
+ * server stores as that artifact's preview. So the page's default view IS the
+ * poster, and the contract asks for that view instead: the whole model,
+ * full-bleed, nothing over it, standing within the render's few seconds.
+ * "poster" stays optional in the shape: a poster.png an agent already has
+ * still ships on the same general rule.
  */
+export const MODEL_VIEW_MANIFEST = `{
+  "kind": "map",
+  "title": "Street and metro map",
+  "entry": "street-metro-map/index.glb",
+  "poster": "street-metro-map/poster.png",
+  "view": {
+    "units": { "metre": 1, "unit": "m" },
+    "upAxis": "Y",
+    "front": "+Z",
+    "defaultView": "overview",
+    "views": [
+      { "id": "overview", "label": "Overview", "group": "overview", "direction": "iso" },
+      { "id": "plan", "label": "Plan", "group": "overview", "direction": "top" },
+      { "id": "konbini", "label": "Konbini", "group": "spot", "area": "Shops", "direction": "front", "part": "konbini" },
+      { "id": "north-platform", "label": "North platform", "group": "spot", "area": "Station",
+        "camera": { "position": [42, 6, -18], "target": [42, 1, -4] } }
+    ],
+    "layers": [
+      { "id": "konbini", "label": "Konbini", "part": "konbini" },
+      { "id": "station-platforms", "label": "Station platforms", "part": "station-platforms" }
+    ]
+  },
+  "parts": ["konbini", "station-platforms"]
+}`;
+
 export const SYSTEM_AGENT_MODEL = `You are the human's own Claude, working one 3D MODEL card in a git worktree of
 their repository. Nobody is watching this run. You have the repo and the tools
 TOOLS ON THIS CARD names below — no board, no chat.
@@ -177,8 +224,9 @@ WHAT TO DO:
 
 2. Write ONE viewer, .flowviant/artifacts/<kebab-name>/index.html — a short
    kebab-case name for what it is (for example
-   .flowviant/artifacts/reading-chair/index.html). Keep the viewer self-contained;
-   do not add scripts or notes in its folder. Flowviant materializes index.glb
+   .flowviant/artifacts/reading-chair/index.html). Keep the viewer self-contained:
+   beside it, its folder holds only the view.json below (and a poster.png, if
+   you already have one), never scripts or notes. Flowviant materializes index.glb
    beside this exact page before completing the card, through the handler below.
    Keep original generated texture PNGs elsewhere under .flowviant/artifacts/;
    preserve their bytes and material mapping. The page BUILDS
@@ -186,6 +234,9 @@ WHAT TO DO:
    - three.js as ES modules from cdn.jsdelivr.net/npm, through an import map
      for "three" and "three/addons/"; orbit controls, lights and a neutral
      ground. Nothing else loads from the network, and nothing can be sent.
+   - the page is the scene and nothing else: a full-bleed canvas, with no
+     title, panel, legend, button or text over the model. Flowviant draws
+     every control.
    - the model is ONE THREE.Group named for what it is, built from three.js
      geometry (lathe, extrude, tube, box and the rest, one mesh per part),
      with MeshStandardMaterial only. Colour, roughness and metalness are
@@ -228,6 +279,40 @@ WHAT TO DO:
 
    ${LOOK_HEADLESS}
 
+   THE PAGE'S DEFAULT VIEW IS THE POSTER FLOWVIANT SHOWS. Flowviant renders
+   this page itself when it uploads it, and that still is the model's picture
+   wherever the model is listed. So the page opens on the default view below:
+   the whole model, fitted full-bleed to the frame, with nothing over it — no
+   loading text, label or overlay — standing within a few seconds of load.
+   Take no poster yourself; a poster.png you already have may sit in the
+   folder, named in "poster" below.
+
+   Then write <kebab-name>/view.json — how Flowviant's viewer frames the
+   model, exactly in this shape (a map's, with every field):
+
+${MODEL_VIEW_MANIFEST.replace(/^/gm, '     ')}
+
+   "kind" is "model" for one object, "map" for a scene that places several
+   kits. "entry" is a path under .flowviant/artifacts/: this folder's
+   index.glb. "poster" is optional: name this folder's poster.png only when
+   the folder holds one; otherwise leave the field out. Declare "units"
+   once, as the size of the scene's unit in metres —
+   { "stud": 0.28, "unit": "m" } for a scene built in studs — and never
+   write units or any other text into the scene; Flowviant draws the scale
+   bar. "upAxis" is "Y" (three.js is Y-up); "front" is the side the model
+   faces: "+X", "-X", "+Z" or "-Z". "views": up to three "overview" views,
+   "defaultView" naming one; a map adds named "spot" views, each grouped
+   under its "area". A view looks from a "direction" ("iso", "top",
+   "front", "side" or "back") fitted to the whole scene or to one "part", or
+   from a "camera" position and target in scene units. "layers", for a map:
+   one per kit, its "part" the kit's scene node name exactly. "parts": every
+   node you name in code (.name, which GLTFExporter keeps); each "part"
+   above is one of them, spelled the same. A single model has no spots and
+   no layers: Flowviant gives it Display and Turntable. A label or area is a
+   few words, 40 characters at most; at most 40 views, 60 layers and 200
+   parts — a manifest past any limit is not read. The page's opening view
+   is the one "defaultView" names, so the poster and the viewer agree.
+
 ${ARTIFACT_CONTRACT_TAIL({
   ask: `If you cannot model it without a DECISION only a person can make — which of
    two directions, what size or style, which asset it stands beside — STOP AND

package/bin/lib/artifactIteration.mjs

@@ -1,4 +1,5 @@
 /** Explicit iteration relationships, plus measured local deletions. No model runs here. */
+import { REFERENCE_CAPTURE_FILE } from './referenceCaptureProtocol.mjs';
 import { constants, openSync, closeSync, fstatSync, readFileSync, lstatSync, unlinkSync, realpathSync, writeFileSync, renameSync, rmSync } from 'node:fs';
 import { join, dirname, resolve, sep } from 'node:path';
 import { createHash } from 'node:crypto';
@@ -117,7 +118,7 @@ export function seenArtifacts(record, stored, present, bornAt = null) {
   let seen = record;
   if (!seen) {
     const since = Number.isFinite(bornAt)
-      ? stored.filter((a) => storedAt(a) >= bornAt).map((a) => a.name) : [];
+      ? stored.filter((a) => storedAt(a) >= bornAt && !REFERENCE_CAPTURE_FILE.test(a.name)).map((a) => a.name) : [];
     seen = since.some((n) => present.has(n)) ? new Set(since) : new Set();
   }
   return new Set([...seen, ...present].filter((n) => names.has(n) || present.has(n)));

package/bin/lib/artifactReporter.mjs

@@ -297,7 +297,7 @@ export function createArtifactReporter({
 
   /** Upload what this turn changed in `placeDir`. Resolves to the number of
    *  bodies SENT this call (delivered or held), for the tests and the log. */
-  const report = async ({ placeDir, before, sessionId, agentId, turnId, idle = false, requireStored = false, includeNames = null, requiredOutputs = null }) => {
+  const report = async ({ placeDir, before, sessionId, agentId, turnId, idle = false, requireStored = false, includeNames = null, requiredOutputs = null, referenceCapture = false }) => {
     if (!placeDir || (!sessionId && !agentId)) return 0;
     const changes = iterationChanges(placeDir, before);
     const protectedNames = imageRevisionProtection(before?.stored, before?.imageRevision);
@@ -347,7 +347,7 @@ export function createArtifactReporter({
       failures.push(`Required intermediate output ${name} is missing, unsafe or excluded from reporting; its handoff is unfinished.`);
     let n = 0;
     for (const entry of changed) {
-      const body = buildUpload(entry, { sessionId, agentId, turnId }, scrub, secretIn);
+      const body = buildUpload(entry, { sessionId, agentId, turnId, ...(referenceCapture ? { referenceCapture: true } : {}) }, scrub, secretIn);
       if (required.has(entry.name) && (!body?.bytes || body.withheld || body.fields.sha256 !== required.get(entry.name))) {
         failures.push(`Required intermediate output ${entry.name} is unreadable, withheld or changed since preparation. Restore its exact producer bytes and retry.`);
         continue;

package/bin/lib/artifacts.mjs

@@ -74,6 +74,7 @@
  * that cannot show an artifact must not have the CLI told it will.
  */
 
+import { REFERENCE_CAPTURE_MANIFEST, REFERENCE_CAPTURE_FILE } from './referenceCaptureProtocol.mjs';
 import { constants, closeSync, fstatSync, lstatSync, mkdirSync, openSync, readdirSync, readSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { join } from 'node:path';
@@ -305,7 +306,7 @@ export const artifactStoredName = (name) => name.split('/').map(safeArtifactName
  * re-sent exactly as it was first built (scrubbed once, never re-read from a
  * disk the agent may have changed since).
  */
-export function buildArtifactUpload(entry, { sessionId, agentId, turnId }, scrub = (s) => s, secretIn = () => null) {
+export function buildArtifactUpload(entry, { sessionId, agentId, turnId, referenceCapture = false }, scrub = (s) => s, secretIn = () => null) {
   const type = artifactTypeFor(entry.name);
   const fields = {
     ...(sessionId ? { sessionId } : { agentId }),
@@ -313,6 +314,9 @@ export function buildArtifactUpload(entry, { sessionId, agentId, turnId }, scrub
     name: artifactStoredName(entry.name),
     bytes: String(entry.size),
   };
+  // Reserved evidence names are writable only by the measured browser
+  // consumer. Model-authored JSON cannot become a page-access measurement.
+  if (REFERENCE_CAPTURE_FILE.test(entry.name) && !referenceCapture) return { withheld: 'measured-reference-capture-only', fields };
   if (!type) return { fields, bytes: null }; // reported by name only
   const maxBytes = artifactMaxBytesFor(entry.name);
   if (entry.size > maxBytes) return { fields: { ...fields, tooLarge: '1' }, bytes: null };
@@ -328,7 +332,10 @@ export function buildArtifactUpload(entry, { sessionId, agentId, turnId }, scrub
     const secret = secretIn(bytes);
     if (secret) return { withheld: secret, fields };
   } else {
+    const original = bytes;
     bytes = Buffer.from(String(scrub(bytes.toString('utf8'))), 'utf8');
+    if (REFERENCE_CAPTURE_MANIFEST.test(entry.name) && !bytes.equals(original))
+      return { withheld: 'reference-capture-redaction', fields };
     // A redaction marker can be longer than the value it replaced.
     if (bytes.byteLength > maxBytes) {
       return { fields: { ...fields, bytes: String(bytes.byteLength), tooLarge: '1' }, bytes: null };

package/bin/lib/claudeStream.mjs

@@ -198,6 +198,7 @@ export function handleStreamLine(line, options) {
     for (const b of ev.message.content) {
       if (b.type === 'tool_result') onToolEvent?.(null, {}, {
         id: b.tool_use_id, result: true, isError: b.is_error === true,
+        toolSuccess: b.is_error !== true,
         ...(agentId ? { agentId } : {}),
         output: typeof b.content === 'string' ? b.content : Array.isArray(b.content) ? b.content.slice(0, 8).filter(x => x?.type === 'text' && typeof x.text === 'string').map(x => x.text).join('\n') : '',
         detail: typeof b.content === 'string' ? b.content : Array.isArray(b.content) ? b.content.filter(x => x?.type === 'text' && typeof x.text === 'string').map(x => x.text).join('\n') : '',
@@ -232,6 +233,12 @@ export function handleStreamLine(line, options) {
     // alias, and this is the CLI naming what it chose. See turnModel.mjs.
     const resolved = turnModelOf(ev.model);
     if (resolved) onModel?.(resolved);
+    if (Array.isArray(ev.tools)) for (const tool of ['WebSearch', 'WebFetch']) {
+      onToolEvent?.('WebsiteAccess', { method: 'capability', tool }, {
+        id: `website-capability:${tool}`, result: true,
+        website: { access: 'unknown', availability: ev.tools.includes(tool) ? 'advertised' : 'unknown' },
+      });
+    }
     if (Array.isArray(ev.skills) || typeof ev.session_id === 'string' || Array.isArray(ev.mcp_servers)) {
       onInit?.({
         skills: Array.isArray(ev.skills) ? ev.skills.map(String) : undefined,

package/bin/lib/codexFencedMount.mjs

@@ -109,7 +109,7 @@ const table = (v) => (v && typeof v === 'object' && !Array.isArray(v) ? v : {});
  * config.toml could not be read), and
  * `unmounted` `[{ name, reason, source: 'project' | 'machine', partial? }]`.
  */
-export function codexFencedMount(usable, expand, machineEnv, turnServers = {}) {
+export function codexFencedMount(usable, expand, machineEnv, turnServers = {}, { includeMachine = true } = {}) {
   const args = [];
   const childEnv = {};
   const mounted = [];
@@ -192,7 +192,7 @@ export function codexFencedMount(usable, expand, machineEnv, turnServers = {}) {
   }
 
   const projectNames = new Set([...usable.map((t) => t.name), ...ownNames]);
-  const personal = machineCodexServers(machineEnv);
+  const personal = includeMachine ? machineCodexServers(machineEnv) : [];
   for (const [name, server] of personal ?? []) {
     if (projectNames.has(name) || server.enabled === false) continue;
     if (typeof server.command !== 'string' && typeof server.url !== 'string') continue;

package/bin/lib/pinnedCapture.mjs

@@ -59,17 +59,28 @@ const ATTACH_WAIT_MS = 2_000;
  * protocol's error; `on(fn)` receives every event; `close(reason)` rejects
  * whatever is still waiting (the browser is gone).
  */
-export function createCdpClient(writable, readable) {
+export function createCdpClient(writable, readable, { maxMessageBytes = Infinity } = {}) {
   let nextId = 0;
   let closed = null;
   const waiting = new Map();
   const listeners = [];
   let chunks = [];
+  let chunkBytes = 0;
+  const close = reason => {
+    if (closed) return;
+    closed = reason;
+    chunks = []; chunkBytes = 0;
+    for (const w of waiting.values()) w.reject(new Error(reason));
+    waiting.clear();
+  };
   readable.on('data', (d) => {
+    if (closed) return;
     let start = 0;
     for (let i = 0; i < d.length; i++) {
       if (d[i] !== 0) continue;
       chunks.push(d.subarray(start, i));
+      chunkBytes += i - start;
+      if (chunkBytes > maxMessageBytes) { close('DevTools message exceeded the reference bound.'); return; }
       start = i + 1;
       let msg;
       try {
@@ -78,6 +89,7 @@ export function createCdpClient(writable, readable) {
         msg = null;
       }
       chunks = [];
+      chunkBytes = 0;
       if (!msg) continue;
       if (msg.id != null && waiting.has(msg.id)) {
         const w = waiting.get(msg.id);
@@ -88,7 +100,11 @@ export function createCdpClient(writable, readable) {
         for (const fn of listeners) fn(msg);
       }
     }
-    if (start < d.length) chunks.push(d.subarray(start));
+    if (start < d.length) {
+      chunkBytes += d.length - start;
+      if (chunkBytes > maxMessageBytes) { close('DevTools message exceeded the reference bound.'); return; }
+      chunks.push(d.subarray(start));
+    }
   });
   return {
     send(method, params = {}, sessionId) {
@@ -108,12 +124,7 @@ export function createCdpClient(writable, readable) {
     on(fn) {
       listeners.push(fn);
     },
-    close(reason) {
-      if (closed) return;
-      closed = reason;
-      for (const w of waiting.values()) w.reject(new Error(reason));
-      waiting.clear();
-    },
+    close,
   };
 }
 

package/bin/lib/postureTools.mjs

@@ -15,10 +15,10 @@ const POSTURES = {
   research: {
     claude: {
       has: 'the repository’s files (never .env files), the project’s knowledge library, web search and web fetch, and writing under .flowviant/artifacts/ and the granted scratch directory',
-      lacks: 'no measured native image-generation tool, no delegation, guarded read commands only (no helper scripts or browsers), and no plugins from this machine’s Claude Code (nor the MCP servers a plugin brings)',
+      lacks: 'no measured native image-generation tool, no delegation, guarded read commands only (no helper scripts or direct browser launches), and no plugins from this machine’s Claude Code (nor the MCP servers a plugin brings)',
       // An orchestrated research card (2026-10-19): its children read under
       // CARD ORCHESTRATOR, so the note does not withhold delegation.
-      orchestratedLacks: 'no measured native image-generation tool, guarded read commands only (no helper scripts or browsers), and no plugins from this machine’s Claude Code (nor the MCP servers a plugin brings)',
+      orchestratedLacks: 'no measured native image-generation tool, guarded read commands only (no helper scripts or direct browser launches), and no plugins from this machine’s Claude Code (nor the MCP servers a plugin brings)',
     },
     codex: {
       has: 'a sandboxed shell over an isolated copy of the repository (no .env, credential or git files, and no network from the shell), web search, and writing under .flowviant/artifacts/ and the granted scratch directory',

package/bin/lib/publicReferenceBrowser.mjs

@@ -0,0 +1,180 @@
+/** Chromium has an empty private root and no network. Public response bytes
+ * enter only through the bounded DNS-pinned broker, over a private CDP pipe.
+ * Unsupported namespace or Chrome sandbox launch never retries unsandboxed. */
+import { spawn } from 'node:child_process';
+import { existsSync, openSync, readSync, closeSync, realpathSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { resolveBrowser, SANDBOX_FAILURE_RE } from './shot.mjs';
+import { createCdpClient } from './pinnedCapture.mjs';
+import { killGroup } from './processGroup.mjs';
+import { createReferenceNetwork, publicReferenceUrl } from './publicReferenceNetwork.mjs';
+import { REFERENCE_BOUNDS as B } from './publicReferenceProtocol.mjs';
+
+export function referenceBrowserLaunch(browser = resolveBrowser()) {
+  if (process.platform !== 'linux') return { unavailable: 'unsupported_isolation' };
+  if (process.getuid?.() === 0) return { unavailable: 'root_browser_unsupported' };
+  if (!browser || browser.viaWindows) return { unavailable: 'no_native_browser' };
+  const bwrap = ['/usr/bin/bwrap', '/bin/bwrap'].find(existsSync);
+  if (!bwrap) return { unavailable: 'no_namespace_sandbox' };
+  let binary;
+  try {
+    const real = realpathSync(browser.bin);
+    binary = [real, join(dirname(real), 'chrome'), join(dirname(real), 'chromium')].find(file => {
+      let fd;
+      try { fd = openSync(file, 'r'); const magic = Buffer.alloc(4); readSync(fd, magic, 0, 4, 0); return magic.equals(Buffer.from([127, 69, 76, 70])); }
+      catch { return false; } finally { if (fd !== undefined) closeSync(fd); }
+    });
+  } catch { /* An unsupported wrapper cannot widen the filesystem mounts. */ }
+  if (!binary) return { unavailable: 'unsupported_browser_layout' };
+  const root = dirname(binary);
+  // A broad system-bin bind would expose shell/network helpers. Only browser
+  // distribution files, runtime libraries and fonts are in the private root.
+  if (!['/opt/google/chrome', '/opt/google/chrome-beta', '/opt/google/chrome-unstable',
+    '/usr/lib/chromium', '/usr/lib/chromium-browser', '/opt/microsoft/msedge', '/opt/brave.com/brave'].includes(root))
+    return { unavailable: 'unsupported_browser_layout' };
+  const args = ['--unshare-all', '--die-with-parent', '--new-session', '--cap-drop', 'ALL',
+    '--proc', '/proc', '--dev', '/dev', '--size', String(B.scratchBytes), '--tmpfs', '/tmp',
+    '--size', String(B.profileBytes), '--tmpfs', '/profile', '--size', '1048576', '--tmpfs', '/home', '--size', '1048576', '--tmpfs', '/etc',
+    '--ro-bind', root, '/browser'];
+  for (const dir of ['/usr/lib', '/lib', '/lib64', '/usr/share/fonts', '/usr/share/fontconfig', '/etc/fonts'])
+    if (existsSync(dir)) args.push('--ro-bind', dir, dir);
+  args.push('--clearenv', '--setenv', 'HOME', '/profile', '--setenv', 'TMPDIR', '/tmp', '--setenv', 'LANG', 'C.UTF-8',
+    '--', `/browser/${binary.slice(root.length + 1)}`,
+    '--headless=new', '--remote-debugging-pipe', '--user-data-dir=/profile', '--no-first-run', '--no-default-browser-check',
+    '--disable-gpu', '--disable-dev-shm-usage', '--disable-extensions', '--disable-background-networking',
+    '--disable-component-update', '--disable-sync', '--disable-breakpad', '--disable-crash-reporter',
+    '--disable-domain-reliability', '--disable-default-apps', '--no-pings', '--no-proxy-server',
+    '--disable-quic', '--disable-features=MediaRouter,OptimizationHints,AutofillServerCommunication',
+    '--renderer-process-limit=2', '--js-flags=--max-old-space-size=128', '--force-color-profile=srgb',
+    `--window-size=${B.width},${B.height}`, 'about:blank');
+  return { command: bwrap, args, env: { PATH: '/usr/bin:/bin', LANG: 'C.UTF-8' } };
+}
+
+export async function capturePublicReference({ url, signal, attemptId = randomUUID() }, {
+  launch = referenceBrowserLaunch, spawnBrowser = spawn, networkFactory = createReferenceNetwork,
+} = {}) {
+  const attemptedAt = new Date().toISOString();
+  const capture = { version: 1, attemptId, requestedUrl: url, attemptedAt, capturedAt: null, viewport: { width: B.width, height: B.height },
+    observation: { access: 'unknown', observedAt: attemptedAt }, contentAssessment: 'unverified' };
+  try { publicReferenceUrl(url); } catch { return { ...capture, reason: 'blocked_destination', observation: { ...capture.observation, access: 'permission_denied', permissionSource: 'flowviant' } }; }
+  if (signal?.aborted) return { ...capture, reason: 'aborted' };
+  const spec = launch();
+  if (spec.unavailable) return { ...capture, reason: spec.unavailable, observation: { ...capture.observation, access: 'unavailable' } };
+  const controller = new AbortController();
+  const network = networkFactory({ signal: controller.signal });
+  let child, cdp, timer, abort, interrupt, started = false, stderr = '';
+  let documents = 0, requests = 0, blocked = 0, mainFrame, target, session, loaded = false, pending = 0, networkFailure;
+  const responses = new Map();
+  const finish = (access, reason) => ({ ...capture, blockedRequests: blocked, ...(reason ? { reason } : {}),
+    observation: { ...capture.observation, observedAt: new Date().toISOString(), access,
+      ...(['blocked_destination', 'blocked_method'].includes(reason) ? { access: 'permission_denied', permissionSource: 'flowviant' } : {}) } });
+  const interrupted = new Promise(resolve => {
+    interrupt = (access, reason) => { controller.abort(); if (child) killGroup(child); resolve(finish(access, reason)); };
+    abort = () => interrupt('unknown', 'aborted');
+    if (signal?.aborted) abort(); else signal?.addEventListener('abort', abort, { once: true });
+    timer = setTimeout(() => interrupt(!started ? 'unavailable' : loaded ? 'partial' : 'failed', 'timeout'), B.timeoutMs);
+  });
+  const run = async () => {
+    child = spawnBrowser(spec.command, spec.args, { env: spec.env, detached: true, stdio: ['ignore', 'ignore', 'pipe', 'pipe', 'pipe'] });
+    child.stderr.on('data', data => { stderr = (stderr + data.toString()).slice(-4000); });
+    cdp = createCdpClient(child.stdio[3], child.stdio[4], { maxMessageBytes: 8 * 1024 * 1024 });
+    for (const fd of [3, 4]) child.stdio[fd].on('error', () => {});
+    child.once('error', () => cdp.close('Browser unavailable.'));
+    child.once('exit', () => cdp.close('Browser exited.'));
+    await cdp.send('Browser.getVersion');
+    started = true;
+    await cdp.send('Browser.setDownloadBehavior', { behavior: 'deny' });
+    // Only our page runs. Popups, out-of-process frames and workers are closed
+    // while paused; in-process requests still pass the broker. A bypass has
+    // no network route, no user home and no host credential files to reach.
+    cdp.on(message => {
+      const p = message.params ?? {};
+      if (message.method === 'Target.attachedToTarget' && p.targetInfo?.targetId !== target) {
+        if (p.waitingForDebugger && typeof p.targetInfo?.targetId === 'string') { blocked++; cdp.send('Target.closeTarget', { targetId: p.targetInfo.targetId }).catch(() => {}); }
+      }
+      if (message.sessionId !== session) return;
+      if (message.method === 'Page.lifecycleEvent' && p.frameId === mainFrame && ['DOMContentLoaded', 'load'].includes(p.name)) loaded = true;
+      if (message.method !== 'Fetch.requestPaused') return;
+      pending++;
+      void (async () => {
+        try {
+          if (controller.signal.aborted) throw new Error('aborted');
+          if (++requests > B.requests) { interrupt(loaded ? 'partial' : 'failed', 'request_limit'); return; }
+          if (p.resourceType === 'Document' && ++documents > B.documents) { interrupt(loaded ? 'partial' : 'failed', 'navigation_limit'); return; }
+          const response = await network.request(p.request.url, p.request.method);
+          if (p.resourceType === 'Document' && p.frameId === mainFrame) responses.set(publicReferenceUrl(p.request.url).href, { status: response.status,
+            challenge: response.headers.some(h => h.name.toLowerCase() === 'cf-mitigated' && h.value.toLowerCase() === 'challenge') });
+          await cdp.send('Fetch.fulfillRequest', { requestId: p.requestId, responseCode: response.status, responseHeaders: response.headers, body: response.body.toString('base64') }, session);
+        } catch (error) {
+          if (error.reason === 'byte_limit' || error.reason === 'request_limit') { interrupt(loaded ? 'partial' : 'failed', error.reason); return; }
+          if (p.resourceType === 'Document' && p.frameId === mainFrame) networkFailure = error.reason ?? 'navigation_failed';
+          blocked++;
+          await cdp.send('Fetch.failRequest', { requestId: p.requestId, errorReason: 'BlockedByClient' }, session).catch(() => {});
+        } finally { pending--; }
+      })();
+    });
+    const context = await cdp.send('Target.createBrowserContext', { disposeOnDetach: true });
+    const created = await cdp.send('Target.createTarget', { url: 'about:blank', browserContextId: context.browserContextId });
+    target = created.targetId;
+    session = (await cdp.send('Target.attachToTarget', { targetId: target, flatten: true })).sessionId;
+    await cdp.send('Target.setAutoAttach', { autoAttach: true, waitForDebuggerOnStart: true, flatten: true }, session);
+    await cdp.send('Page.enable', {}, session);
+    await cdp.send('Page.setLifecycleEventsEnabled', { enabled: true }, session);
+    await cdp.send('Network.enable', {}, session);
+    await cdp.send('Network.setBypassServiceWorker', { bypass: true }, session);
+    await cdp.send('Network.setCacheDisabled', { cacheDisabled: true }, session);
+    await cdp.send('Fetch.enable', { patterns: [{ urlPattern: '*', requestStage: 'Request' }] }, session);
+    await cdp.send('Emulation.setDeviceMetricsOverride', { width: B.width, height: B.height, deviceScaleFactor: 1, mobile: false }, session);
+    mainFrame = (await cdp.send('Page.getFrameTree', {}, session)).frameTree.frame.id;
+    await cdp.send('Target.setAutoAttach', { autoAttach: true, waitForDebuggerOnStart: true, flatten: true });
+    const nav = await cdp.send('Page.navigate', { url }, session);
+    if (nav.errorText) return finish('failed', networkFailure ?? 'navigation_failed');
+    const until = Date.now() + 12_000;
+    while ((!loaded || pending) && Date.now() < until && !controller.signal.aborted) await new Promise(resolve => setTimeout(resolve, 50));
+    if (controller.signal.aborted) return finish('unknown', 'aborted');
+    const frame = (await cdp.send('Page.getFrameTree', {}, session)).frameTree.frame;
+    let finalUrl;
+    try { publicReferenceUrl(frame.url); finalUrl = frame.url; } catch { return finish('failed', 'unverified_document'); }
+    const response = responses.get(publicReferenceUrl(finalUrl).href);
+    if (!response || frame.unreachableUrl || !loaded) return finish('failed', networkFailure ?? 'unverified_document');
+    capture.finalUrl = finalUrl;
+    capture.observation.finalUrl = finalUrl;
+    capture.observation.httpStatus = response.status;
+    // Content remains untrusted source data. Restrict what evaluation returns;
+    // there is no tool for arbitrary JS, clicks, forms or document mutation.
+    const content = await cdp.send('Runtime.evaluate', { returnByValue: true, timeout: 2000, expression: `JSON.stringify({text:(document.body?.innerText||'').slice(0,${B.textChars}),links:Array.from(document.querySelectorAll('a[href]')).slice(0,${B.links}).map(a=>({url:a.href.slice(0,4096),text:(a.innerText||'').slice(0,160)}))})` }, session);
+    const parsed = JSON.parse(content.result?.value ?? '{}');
+    capture.text = typeof parsed.text === 'string' ? parsed.text.slice(0, B.textChars) : '';
+    capture.capturedAt = new Date().toISOString();
+    capture.links = Array.isArray(parsed.links) ? parsed.links.slice(0, B.links).flatMap(link => {
+      try { publicReferenceUrl(link.url); return typeof link.text === 'string' ? [{ url: link.url, text: link.text.slice(0, 160) }] : []; } catch { return []; }
+    }) : [];
+    const shot = await cdp.send('Page.captureScreenshot', { format: 'png', captureBeyondViewport: false }, session);
+    const png = Buffer.from(shot.data ?? '', 'base64');
+    if (!png.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))) return finish('partial', 'screenshot_unavailable');
+    if (png.length > B.screenshotBytes) return finish('partial', 'screenshot_limit');
+    capture.screenshot = { mimeType: 'image/png', data: png.toString('base64') };
+    capture.capturedAt = new Date().toISOString();
+    const after = (await cdp.send('Page.getFrameTree', {}, session)).frameTree.frame;
+    if (after.loaderId !== frame.loaderId || after.url !== frame.url || pending) {
+      delete capture.screenshot; delete capture.text; delete capture.links; capture.capturedAt = null;
+      return finish('partial', 'document_changed');
+    }
+    return finish(response.challenge ? 'challenge' : response.status >= 400 ? 'failed' : blocked ? 'partial' : 'loaded');
+  };
+  try {
+    return await Promise.race([run().catch(() => finish(started ? 'failed' : 'unavailable', SANDBOX_FAILURE_RE.test(stderr) ? 'browser_sandbox_unavailable' : started ? 'browser_failed' : 'isolation_launch_failed')), interrupted]);
+  } finally {
+    clearTimeout(timer); signal?.removeEventListener('abort', abort);
+    controller.abort(); network.close(); cdp?.close('Reference capture ended.');
+    if (child) {
+      const exited = new Promise(resolve => { if (child.exitCode !== null || child.signalCode !== null) resolve(); else { child.once('exit', resolve); child.once('error', resolve); } });
+      killGroup(child);
+      let reapTimer;
+      await Promise.race([exited, new Promise(resolve => { reapTimer = setTimeout(resolve, 2000); })]);
+      clearTimeout(reapTimer);
+      for (const stream of child.stdio ?? []) stream?.destroy?.();
+    }
+  }
+}