flowviant 0.125.20 → 0.125.22

package/bin/lib/orchestrator.mjs

@@ -58,7 +58,9 @@ export async function createOrchestrator({ turnId, runtime, trace, admit, reques
   // wakes never evicts a note input() accepted.
   const inbox = new Map(), wakes = new Map();
   const pending = new Map(), steps = new Map();
-  let closed = false, polling = false, rootSession = null, offerAt = 0;
+  // Whether this run admitted a sealed (Codex V2) spawn or follow-up, whose
+  // child reads its contract at SubagentStart or its first tool instead.
+  let closed = false, polling = false, rootSession = null, offerAt = 0, sealedRun = false;
   const identity = readOnlyRun ? { ...readOnlyRun, instance: DAEMON_INSTANCE } : { scope: 'agent', turnId, instance: DAEMON_INSTANCE };
   const ended = () => closed || signal?.aborted;
   const resolve = id => aliases.get(id) ?? id;
@@ -123,6 +125,19 @@ export async function createOrchestrator({ turnId, runtime, trace, admit, reques
     return held.find(a => a.brief === brief) ?? held.find(a => title && a.title === title) ?? held.find(a => kind && a.kind === kind)
       ?? held[0] ?? open.find(a => a.brief === brief) ?? open.find(a => title && a.title === title);
   };
+  // A child's contract, naming its record by its id (the words ride its
+  // prompt) or, with no id, a sealed Codex V2 child's record by its task
+  // name: the plain `Task name: /root/<name>` header Codex puts on its task
+  // message, which resolves through the spawn's task_name alias (`named`).
+  // The start hook cannot say which spawn a child came from; its name can.
+  const childContract = (id = null) => {
+    const ref = id ?? 'your task name: the "Task name:" line of your task message, such as /root/backend',
+      arg = id ? `agentId=${id}` : 'agentId set to that task name';
+    return (readOnlyRun
+      ? `\n\nRead-only investigation agent record id: ${ref}. FIRST call card_orchestrator.register_agent with ${arg} before work (tool discovery is allowed). Share this checkout and its repository/knowledge read boundary. Write no file, edit nothing, commit nothing, start no work and call no board or staging tool. Return findings, source paths and uncertainties in your final message to the coordinator. Ask questions only through card_orchestrator.agent_question with ${arg}, and read its answer before proceeding. ${readOnlyRun.scope === 'capture' ? 'Call no flowviant tool, including streaming. Only the coordinator dedupes and authors staged outcomes and asks the person through the existing single-question flowviant-ask fence.' : 'Only the coordinator reconciles the complete workload and returns the proposal.'}`
+      : `\n\nCard orchestrator agent record id: ${ref}. FIRST call card_orchestrator.register_agent with ${arg} before doing work (tool discovery is allowed). Share this worktree and preserve others’ edits. Ask questions through card_orchestrator.agent_question with ${arg}; read its answer before proceeding. Only your orchestrator escalates person-only decisions. When you are done, end with your work or findings as your final message: that is how they reach your orchestrator, which owns the card’s final commit and JSON. agent_question is only for a question you cannot settle yourself, never for handing back results.`)
+      + (!readOnlyRun ? assignmentContext() : '') + (access === 'read' && !readOnlyRun ? READ_ONLY_CHILD : '');
+  };
   // Admitted: the offer is spent, and notes that paused this child are being
   // delivered, so its checkpoint lets it work until their route lands.
   const start = (a, now) => {
@@ -146,7 +161,8 @@ export async function createOrchestrator({ turnId, runtime, trace, admit, reques
     if (aliases.size > 256) aliases.delete(aliases.keys().next().value);
     if (calls.size > 128) calls.delete(calls.keys().next().value);
     if (!records.has(id) && records.size >= SUBAGENT_CAP) return { deny: `This run already has ${SUBAGENT_CAP} agent records. Continue the work yourself.` };
-    const a = emit({ id, brief, title: spawn.title ?? '', kind: spawn.kind ?? '', status: 'waiting', now: WAIT });
+    // A sealed message's words are unknown: no brief, never its ciphertext.
+    const a = emit({ id, ...(spawn.sealed ? {} : { brief }), title: spawn.title ?? '', kind: spawn.kind ?? '', status: 'waiting', now: WAIT });
     if (!slot(id)) { a.denied = resumed ? 'resume' : 'spawn'; return { deny: `${WAIT}. Agent id: ${id}. Keep working yourself; you will be told when this spawn can be retried. Do not wait for a child that has not started.` }; }
     // Claude's SendMessage addresses a child by its Agent `name`, Codex V2 by its task name.
     for (const name of spawn.names) if (filled(name) && name.length <= 160) aliases.set(name, id);
@@ -155,11 +171,9 @@ export async function createOrchestrator({ turnId, runtime, trace, admit, reques
     // stream, and the parent is asked to say why in its own update.
     const choice = childChoice(event, spawn, card);
     if (choice) trace.prose('note', `Runs on ${choice}.`, id);
-    const childContract = readOnlyRun
-      ? `\n\nRead-only investigation agent record id: ${id}. FIRST call card_orchestrator.register_agent with agentId=${id} before work (tool discovery is allowed). Share this checkout and its repository/knowledge read boundary. Write no file, edit nothing, commit nothing, start no work and call no board or staging tool. Return findings, source paths and uncertainties in your final message to the coordinator. Ask questions only through card_orchestrator.agent_question with agentId=${id}, and read its answer before proceeding. ${readOnlyRun.scope === 'capture' ? 'Call no flowviant tool, including streaming. Only the coordinator dedupes and authors staged outcomes and asks the person through the existing single-question flowviant-ask fence.' : 'Only the coordinator reconciles the complete workload and returns the proposal.'}`
-      : `\n\nCard orchestrator agent record id: ${id}. FIRST call card_orchestrator.register_agent with agentId=${id} before doing work (tool discovery is allowed). Share this worktree and preserve others’ edits. Ask questions through card_orchestrator.agent_question with agentId=${id}; read its answer before proceeding. Only your orchestrator escalates person-only decisions. When you are done, end with your work or findings as your final message: that is how they reach your orchestrator, which owns the card’s final commit and JSON. agent_question is only for a question you cannot settle yourself, never for handing back results.`;
+    if (spawn.sealed) sealedRun = true;
     return { context: `Agent record id: ${id}. Use it with card_orchestrator for routing and questions.${spawn.relocated ? ' Its isolation and cwd were removed: children share this card’s worktree on this machine.' : ''}${choice ? ` This child runs on ${choice}: name that choice and why in your next update.` : ''}`,
-      updatedInput: withChildContract(event, spawn, childContract + (!readOnlyRun ? assignmentContext() : '') + (access === 'read' && !readOnlyRun ? READ_ONLY_CHILD : ''), chosen.brain) };
+      updatedInput: withChildContract(event, spawn, spawn.sealed ? '' : childContract(id), chosen.brain) };
   }
   // Native readings never revive a settled record or start a waiting spawn
   // or follow-up (Codex records a refused call's start anyway); only an
@@ -205,10 +219,13 @@ export async function createOrchestrator({ turnId, runtime, trace, admit, reques
     steps.delete(native);
     if (aliases.size > 256) aliases.delete(aliases.keys().next().value);
   };
-  // Codex V2 names a child `backend` or `/root/backend` interchangeably.
+  // Codex V2 names a child `backend` or `/root/backend` interchangeably, and
+  // a sealed child registers by the canonical path its task message wears.
   const named = native => {
+    if (typeof native !== 'string') return resolve(native);
     if (aliases.has(native) || records.has(native)) return resolve(native);
-    const hits = new Set([...aliases].filter(([k]) => k.endsWith(`/${native}`) || native.endsWith(`/${k}`)).map(([, v]) => v));
+    const near = k => k.endsWith(`/${native}`) || native.endsWith(`/${k}`);
+    const hits = new Set([...[...aliases].filter(([k]) => near(k)).map(([, v]) => v), ...[...records.keys()].filter(near)]);
     return hits.size === 1 ? [...hits][0] : native;
   };
   function postSpawn(event) {
@@ -219,7 +236,7 @@ export async function createOrchestrator({ turnId, runtime, trace, admit, reques
     if (failed) { release(id); emit({ id, status: 'stopped' }); }
   }
   function preResume(event) {
-    const input = event.tool_input ?? {}, { claude, native } = followupTarget(event);
+    const input = event.tool_input ?? {}, { claude, native, sealed } = followupTarget(event);
     if (native === null) return claude ? null : { deny: 'Name the native agent to resume.' };
     const id = named(native);
     if (!records.has(id)) {
@@ -227,7 +244,7 @@ export async function createOrchestrator({ turnId, runtime, trace, admit, reques
       // SendMessage also reaches "main" and teammates: only a known child is a follow-up.
       if (claude) return null;
       if (records.size >= SUBAGENT_CAP) return { deny: 'Continue the work in this run’s orchestrator.' };
-      emit({ id, kind: '', title: native, brief: typeof input.message === 'string' ? input.message : '', status: 'waiting', now: WAIT, resumable: true });
+      emit({ id, kind: '', title: native, ...(sealed ? {} : { brief: typeof input.message === 'string' ? input.message : '' }), status: 'waiting', now: WAIT, resumable: true });
     }
     if (spawnable(records.get(id))) return { deny: `Agent ${id} has not started. Retry its native spawn instead.` };
     // A refused follow-up retried on its offered slot reaches a finished child.
@@ -236,6 +253,9 @@ export async function createOrchestrator({ turnId, runtime, trace, admit, reques
     start(records.get(id), 'Continuing with the orchestrator’s note');
     records.get(id).queued = running;
     calls.set(event.tool_use_id, id);
+    // A sealed follow-up rides as written; its child registers by task name
+    // if this run has not bound it yet (the refusal at its first tool says how).
+    if (sealed) { sealedRun = true; return {}; }
     return typeof input.message === 'string' ? { updatedInput: { ...input,
       message: input.message + `\n\nCurrent card orchestrator agent record id: ${id}. Before continuing work, call card_orchestrator.register_agent with this id. Return questions to the orchestrator.` } } : {};
   }
@@ -259,6 +279,10 @@ export async function createOrchestrator({ turnId, runtime, trace, admit, reques
     return { deny: 'Your orchestrator has a note for this checkpoint. Stop editing and wait for its follow-up; keep your work so far.' };
   }
   function hook(ev) {
+    // A sealed child's contract, as it starts (measured on codex-cli 0.163
+    // and 0.164: this additionalContext reached the child, and the event
+    // names the child's agent_id but not the spawn that started it).
+    if (ev.hook_event_name === 'SubagentStart') return sealedRun && childOf(ev) ? { context: childContract().trimStart() } : {};
     // A child's next tool round carries a follow-up queued to it; after its
     // stop, its own tool use is the CLI running it again with that follow-up.
     const kid = records.get(resolve(childOf(ev)));
@@ -275,12 +299,14 @@ export async function createOrchestrator({ turnId, runtime, trace, admit, reques
       if (String(ev.tool_name).includes(ORCHESTRATOR_SERVER) && String(ev.tool_name).endsWith('register_agent')) {
         // Binding the root would pause the orchestrator at its children's checkpoints.
         if (!child) return { deny: 'Only a native child registers an agent record. As the orchestrator, use the record id with describe_agent, route_message or answer_agent.' };
-        const id = resolve(ev.tool_input?.agentId);
-        if (!records.has(id)) return { deny: 'Use the agent record id in your prompt.' };
+        const id = named(ev.tool_input?.agentId);
+        if (!records.has(id)) return { deny: sealedRun ? `That names no agent in this run.${childContract()}` : 'Use the agent record id in your prompt.' };
         bind(child, id);
       }
+      // A sealed child that missed (or never got) its start's words reads
+      // them here, whole: an earlier run's follow-up, or a CLI without the hook.
       if (child && !records.has(resolve(child)) && !isDiscoveryTool(ev.tool_name))
-        return { deny: 'Before working, call card_orchestrator.register_agent with the agent record id in your prompt. Tool discovery is allowed.' };
+        return { deny: sealedRun ? `Register with your orchestrator before working.${childContract()}` : 'Before working, call card_orchestrator.register_agent with the agent record id in your prompt. Tool discovery is allowed.' };
       if ((child && access === 'read' || readOnlyRun) && isChildWriteTool(ev.tool_name)) return { deny: readOnlyRun ? 'This attempt only reads: no file writes.' : READ_ONLY_REFUSAL };
       if (rootTools && captureToolName(ev.tool_name)) {
         if (child || !rootSession || ev.session_id !== rootSession) return { deny: 'Only the top-level capture coordinator may call capture tools. Return findings to it.' };
@@ -314,7 +340,7 @@ export async function createOrchestrator({ turnId, runtime, trace, admit, reques
       return held.length ? { ...result, context: [result.context, ...held].filter(Boolean).join('\n\n') } : result;
     }
     if (action === 'route_message') return route(args);
-    const id = resolve(args.agentId);
+    const id = named(args.agentId);
     // A person’s answer starts a new CLI turn. The parent carries the earlier
     // question and native identity in its own conversation; relay that known
     // context instead of inventing a new child or requiring another question.

package/bin/lib/orchestratorHooks.mjs

@@ -24,9 +24,22 @@ export function orchestratorHooks() {
   return { PreToolUse: [{ matcher: '.*', hooks }], PostToolUse: [{ matcher: spawns, hooks }], PostToolUseFailure: [{ matcher: spawns, hooks }], SubagentStop: [{ hooks }] };
 }
 
-export function codexOrchestratorArgs() {
+/**
+ * CODEX'S SubagentStart HANDS A SEALED CHILD ITS CONTRACT (2026-10-24). A V2
+ * spawn's message is ciphertext the gate must not edit (orchestratorNative.mjs
+ * `isSealedMessage`), so the words reach the child as this hook's
+ * additionalContext. Measured on real codex-cli 0.163.0 and 0.164.0 with this
+ * exact `matcher=".*"` row: the hook ran once per child and the child obeyed
+ * its context. Both CLIs start normally with the key (and with an unknown
+ * event's, offline). An older CLI is unmeasured, so it goes without; its
+ * children meet the same words when the gate refuses their first tool.
+ */
+export const CODEX_SUBAGENT_START_MIN = '0.163.0';
+export function codexOrchestratorArgs(codexVersion) {
   // A Codex `-c` value is TOML, quoted by the one quoter (codexToml.mjs).
   const row = `{matcher=".*",hooks=[{type="command",command=${toml(command())},timeout=${ORCHESTRATOR_HOOK_TIMEOUT_S}}]}`;
+  const start = versionAtLeast(String(codexVersion ?? '').replace(/^codex-cli\s+/, ''), CODEX_SUBAGENT_START_MIN);
   return ['--dangerously-bypass-hook-trust', '-c', 'features.hooks=true',
-    '-c', `hooks.PreToolUse=[${row}]`, '-c', `hooks.PostToolUse=[${row}]`, '-c', `hooks.SubagentStop=[${row}]`];
+    '-c', `hooks.PreToolUse=[${row}]`, '-c', `hooks.PostToolUse=[${row}]`, '-c', `hooks.SubagentStop=[${row}]`,
+    ...(start ? ['-c', `hooks.SubagentStart=[${row}]`] : [])];
 }

package/bin/lib/orchestratorNative.mjs

@@ -12,8 +12,27 @@
  */
 import { isBackgroundSpawnTool, isClaudeFollowupTool, isSpawnTool } from './nativeAgentTools.mjs';
 
+/**
+ * A CODEX V2 MESSAGE IS CIPHERTEXT (2026-10-24). Since codex-cli 0.138
+ * (openai/codex PR #26210) the model writes spawn_agent's and followup_task's
+ * `message` encrypted, and the child's first request hands it back to be
+ * decrypted. The gate appended its contract to it, so every V2 child of the
+ * card runs from 10-19 to 10-24 (133 of them) died on that request with
+ * `invalid_encrypted_content` before its first tool. Measured on real 0.164:
+ * no hook and an identity rewrite both ran the child; one appended line failed
+ * it. Sealed, a message is relayed untouched and never read as a brief.
+ * V2 is the `collaboration` namespace (all 209 real messages, every one a
+ * `gAAAAA…` token); the token's shape is checked too, so a sealed message under
+ * another spelling is never edited. Codex V1 and Claude write plain text.
+ */
+const SEALED_TOKEN = /^gAAAAA[A-Za-z0-9_-]{40,}={0,2}$/;
+export const isSealedMessage = (toolName, message) => typeof message === 'string' &&
+  !isBackgroundSpawnTool(toolName) && !isClaudeFollowupTool(toolName) &&
+  (/^collaboration[./]?(?:spawn_agent|followup_task)$/.test(String(toolName ?? '')) || SEALED_TOKEN.test(message));
+
 /** A spawn's prompt and the fields a waiting record is matched and named by,
- * or null when the gate cannot hold it (no call id or no text prompt). */
+ * or null when the gate cannot hold it (no call id or no text prompt). A
+ * sealed message (`isSealedMessage`) gives no brief: its words are unknown. */
 export function readSpawn(event) {
   // A child stays in the card's worktree on this machine, inside the pool.
   const { isolation, cwd, ...input } = event.tool_input ?? {}, callId = event.tool_use_id;
@@ -21,18 +40,20 @@ export function readSpawn(event) {
   const items = Array.isArray(input.items) ? input.items : null;
   const key = ['prompt', 'message'].find(k => typeof input[k] === 'string') ?? (items ? 'items' : null);
   if (!callId || !key) return null;
-  const brief = key === 'items' ? items.filter(i => i?.type === 'text' && typeof i.text === 'string').map(i => i.text).join('\n') : input[key];
-  return { callId, input, items, key, brief, relocated: isolation !== undefined || cwd !== undefined,
+  const sealed = key === 'message' && isSealedMessage(event.tool_name, input.message);
+  const brief = sealed ? null : key === 'items' ? items.filter(i => i?.type === 'text' && typeof i.text === 'string').map(i => i.text).join('\n') : input[key];
+  return { callId, input, items, key, brief, sealed, relocated: isolation !== undefined || cwd !== undefined,
     resume: typeof input.resume === 'string' ? input.resume : null,
     title: input.description ?? input.task_name, kind: input.subagent_type ?? input.agent_type,
     names: [input.name, input.task_name] };
 }
 
 /** The spawn's input as the gate rewrites it: the contract appended to its
- * prompt, a Claude child sent to the background, and the child's model and
- * effort (`brain`, from `childBrain`) where the spawn named none. */
+ * prompt (never to a sealed message, whose child is handed it at its start),
+ * a Claude child sent to the background, and the child's model and effort
+ * (`brain`, from `childBrain`) where the spawn named none. */
 export const withChildContract = (event, spawn, contract, brain = {}) => ({ ...spawn.input, ...brain, ...(isBackgroundSpawnTool(event.tool_name) ? { run_in_background: true } : {}),
-  ...(spawn.key === 'items' ? { items: [...spawn.items, { type: 'text', text: contract.trimStart() }] } : { [spawn.key]: spawn.input[spawn.key] + contract }) });
+  ...(spawn.sealed ? {} : spawn.key === 'items' ? { items: [...spawn.items, { type: 'text', text: contract.trimStart() }] } : { [spawn.key]: spawn.input[spawn.key] + contract }) });
 
 /** Both CLIs' effort ladder, lowest first (Codex stops at xhigh). */
 export const EFFORT_LADDER = Object.freeze(['low', 'medium', 'high', 'xhigh', 'max']);
@@ -178,11 +199,11 @@ export function spawnReceipt(event) {
   return { ids, failed: Boolean(output?.is_error || output?.isError || event.error) };
 }
 
-/** Which child a follow-up addresses (null when it names none in bounds), and
- * whether it is Claude's SendMessage. */
+/** Which child a follow-up addresses (null when it names none in bounds),
+ * whether it is Claude's SendMessage, and whether its message is sealed. */
 export function followupTarget(event) {
   const input = event.tool_input ?? {}, claude = isClaudeFollowupTool(event.tool_name);
   // Measured Claude 2.1.302 PreToolUse SendMessage input: {to, message, recipient, content, …}.
   const native = claude ? input.to ?? input.recipient ?? input.target ?? input.id : input.target ?? input.id;
-  return { claude, native: typeof native === 'string' && native.length <= 160 ? native : null };
+  return { claude, native: typeof native === 'string' && native.length <= 160 ? native : null, sealed: isSealedMessage(event.tool_name, input.message) };
 }

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/prompts.mjs

@@ -24,7 +24,7 @@ import { AGENT_PREREQUISITE_CONTRACT } from './agentPrerequisiteContract.mjs';
 import { agentTaskKindOf } from './agentTaskKinds.mjs';
 // A card's type (0.106.0) likewise: the table holds the words, this file prints them.
 import { AGENT_TASK_TYPES, agentTaskTypeFor, agentTaskTypeOf } from './agentTaskTypes.mjs';
-import { ARTIFACT_CONTRACT_TAIL, HELP_THEM_DECIDE, LOOK_HEADLESS, SYSTEM_AGENT_DECK, SYSTEM_AGENT_IMAGE, SYSTEM_AGENT_MODEL } from './artifactContracts.mjs';
+import { ARTIFACT_CONTRACT_TAIL, HELP_THEM_DECIDE, LOOK_HEADLESS, SYSTEM_AGENT_DECK, SYSTEM_AGENT_IMAGE, SYSTEM_AGENT_MODEL, WHOLE_REQUEST } from './artifactContracts.mjs';
 import { isLibraryReference } from './knowledgeLibrary.mjs';
 import { readCardThread } from './cardThread.mjs';
 import { AGENT_FILE_LINE_MAX, AGENT_FILES_PER_MESSAGE_MAX, CARD_FILES_PER_TURN_MAX } from './agentFiles.mjs';
@@ -581,9 +581,19 @@ with the matching name your CLI exposes.
    ask: each brief names the original ask, the part this card delivers and
    what its sibling cards own, and carries the context its agent needs — the
    design link or kept reference, the expected look and behaviour of its
-   area, the files you found. If you could not open or read a reference, say
-   so in each brief and in \`assumed\`, and cut by what the person described
-   and the current product shows; never invent what it contains. For example,
+   area, the files you found. Copy the person's links, design references and
+   file lists into every brief they shape, word for word. If you could not
+   open or read a reference, say so in each brief and in \`assumed\`, and cut
+   by what the person described and the current product shows; never invent
+   what it contains. AN UNREAD REFERENCE NEVER NARROWS SCOPE: write "UNREAD
+   AT PLANNING: <the link or name>. The agent working this card opens it
+   itself (a Claude Code agent reads a claude.ai/design link with its
+   DesignSync tool), builds this card's share of all of it, and names any part
+   no card owns." Never write that the agent should use only what you could
+   read as its scope, and never state that the reference is unavailable to the
+   agent: your read access is not its. When the person names a design or
+   mockup without a link, look for its link in the repository's docs, decision
+   records and the Library, and carry what you found. For example,
    "remake the settings page from this design", where the design shows a new
    sidebar, a redesigned profile form, a billing tab and inline save
    confirmations, is four cards, each carrying the design link and the
@@ -1268,6 +1278,8 @@ implementation and ask for the person's decision. Unknown generator-source
 identity is not a claim that an embedded GLB image is the original PNG. Opening
 a result handoff never authorizes an automatic asset commit or merge.
 
+${WHOLE_REQUEST}
+
 ${HELP_THEM_DECIDE}`;
 
 /**
@@ -1814,6 +1826,15 @@ HOW TO READ IT:
    asked for that the diff does not show, changes that reach further than the
    card did. Not formatting, not naming preferences, not the rewrite you would
    have preferred.
+6. THE WHOLE REQUEST, AND WHAT THE AGENT SAYS IS MISSING. A card may carry
+   THE PERSON'S OWN WORDS (the chat it was planned in) and the agent's
+   declared gaps. Judge the diff against the words as well as the criteria:
+   a screen, state, rule or linked design file the person asked for that the
+   diff does not show and the gaps do not list is a concern, named in the
+   card's note. A declared gap is the agent being honest, not a concern by
+   itself; put the serious ones in "overall" so the reviewer meets them first.
+   A linked design you cannot open is named in the note as unchecked, never
+   judged from its name.
 
 END YOUR TURN WITH ONE JSON OBJECT AND NOTHING AFTER IT, in a \`\`\`json fence:
 

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?.();
+    }
+  }
+}