flowviant 0.125.21 → 0.125.23

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

@@ -38,6 +38,21 @@
  * The launch obeys shot.mjs's policy: sandboxed unless `sandboxOff`, one retry
  * without it after a launch that measured a sandbox failure, and the machine
  * credential stripped from Chrome's environment.
+ *
+ * A CALLER MAY DRIVE THE HELD PAGE (`work`, 2026-10-26, the video kind's
+ * render tool): instead of one screenshot, `work(page)` runs once the page
+ * has loaded and is still the page, with `page.screenshot()` and
+ * `page.evaluate(expression)`; `initScript` runs before the page's own
+ * scripts. Every pin above still holds; the page is checked again after
+ * `work` and a page that left is still 'left-page'.
+ *
+ * A DRIVEN PAGE RUNS ON REAL TIME. Stepping Chrome's virtual time was tried
+ * for the video render and measured broken (Chrome 149): once a page's last
+ * animation ended the compositor went idle and `Page.captureScreenshot`
+ * waited for a frame that never came, whatever the clock or screenshot
+ * options — a real video turn's page hung at frame 41 — and CSS and
+ * requestAnimationFrame time ran ahead of `performance.now()`. A page that
+ * needs a clock brings its own in `initScript` (videoRender.mjs `VIDEO_CLOCK`).
  */
 
 import { spawn } from 'node:child_process';
@@ -147,9 +162,18 @@ export function sameDocument(a, b) {
  * `launchFailed` means the browser never answered on the pipe — the only
  * failure a different launch (classic headless, or no sandbox) can change.
  */
-async function captureOnce(browser, { url, out, width, height, timeoutMs, budgetMs, allowSubresource, headlessFlag, noSandbox, modelExport, signal }, { spawnImpl, env }) {
+async function captureOnce(browser, { url, out, width, height, timeoutMs, budgetMs, allowSubresource, headlessFlag, noSandbox, modelExport, work, initScript, signal }, { spawnImpl, env }) {
+  // The thumbnail's bounded virtual-time policy; never a model export's or a
+  // driven page's (see the header).
+  const clocked = !modelExport && !work;
   const userDataDir = mkdtempSync(join(tmpdir(), 'flowviant-pin-'));
-  const args = [...chromeFlags({ headlessFlag, noSandbox, userDataDir, width, height }), '--remote-debugging-pipe', 'about:blank'];
+  // A driven page's WINDOW is at least 400×400, its viewport still exactly
+  // width × height (the metrics override below): MEASURED on Chrome 149
+  // (2026-10-26), a window 50 px tall or less left screenshots of a driven
+  // page waiting on a frame that never came, from about the tenth frame on,
+  // while 120 px and taller never did, at any width.
+  const windowSize = work ? { width: Math.max(width, 400), height: Math.max(height, 400) } : { width, height };
+  const args = [...chromeFlags({ headlessFlag, noSandbox, userDataDir, ...windowSize }), '--remote-debugging-pipe', 'about:blank'];
   let child;
   try {
     child = spawnImpl(browser.bin, args, {
@@ -238,6 +262,9 @@ async function captureOnce(browser, { url, out, width, height, timeoutMs, budget
     const ourSession = new Promise((r) => { ready = r; });
     let budgetDone;
     const budget = new Promise((r) => { budgetDone = r; });
+    // A driven page is driven once it has loaded.
+    let loadedDone;
+    const loaded = new Promise((r) => { loadedDone = r; });
 
     let navigating = false;
     // Called only for a target that is paused before it runs. Once the page
@@ -292,6 +319,7 @@ async function captureOnce(browser, { url, out, width, height, timeoutMs, budget
         return;
       }
       if (msg.method === 'Emulation.virtualTimeBudgetExpired') budgetDone();
+      if (msg.method === 'Page.loadEventFired') loadedDone();
     });
 
     await cdp.send('Browser.setDownloadBehavior', { behavior: 'deny' }).catch(() => {});
@@ -313,11 +341,12 @@ async function captureOnce(browser, { url, out, width, height, timeoutMs, budget
     ours = { targetId: ourTargetId, sessionId };
 
     await cdp.send('Page.enable', {}, sessionId);
-    if (modelExport) await cdp.send('Runtime.enable', {}, sessionId);
+    if (modelExport || work) await cdp.send('Runtime.enable', {}, sessionId);
     if (modelExport) await cdp.send('Page.addScriptToEvaluateOnNewDocument', { source: MODEL_EXPORT_BRIDGE }, sessionId);
+    if (work && initScript) await cdp.send('Page.addScriptToEvaluateOnNewDocument', { source: initScript }, sessionId);
     await cdp.send('Fetch.enable', { patterns: [{ urlPattern: '*', requestStage: 'Request' }] }, sessionId);
     await cdp.send('Emulation.setDeviceMetricsOverride', { width, height, deviceScaleFactor: 1, mobile: false }, sessionId);
-    if (!modelExport) await cdp.send('Emulation.setVirtualTimePolicy', { policy: 'pause' }, sessionId);
+    if (clocked) await cdp.send('Emulation.setVirtualTimePolicy', { policy: 'pause' }, sessionId);
     await cdp.send('Runtime.runIfWaitingForDebugger', {}, sessionId).catch(() => {});
     navigating = true;
     const nav = await cdp.send('Page.navigate', { url }, sessionId);
@@ -326,7 +355,7 @@ async function captureOnce(browser, { url, out, width, height, timeoutMs, budget
     }
     // Model readiness/export waits on actual loaded textures and the page's
     // handler. Thumbnails keep their bounded virtual-time screenshot policy.
-    if (!modelExport) await cdp.send('Emulation.setVirtualTimePolicy', { policy: 'pauseIfNetworkFetchesPending', budget: budgetMs }, sessionId);
+    if (clocked) await cdp.send('Emulation.setVirtualTimePolicy', { policy: 'pauseIfNetworkFetchesPending', budget: budgetMs }, sessionId);
     let exported = null;
     if (modelExport) {
       const answer = await cdp.send('Runtime.evaluate', {
@@ -338,7 +367,8 @@ async function captureOnce(browser, { url, out, width, height, timeoutMs, budget
     // A Chrome that never reports the budget is captured on the wall clock,
     // short of the deadline, rather than never.
     let wall;
-    if (!modelExport) await Promise.race([budget, new Promise((r) => { wall = setTimeout(r, Math.max(budgetMs, timeoutMs - EXIT_GRACE_MS)); })]);
+    if (clocked) await Promise.race([budget, new Promise((r) => { wall = setTimeout(r, Math.max(budgetMs, timeoutMs - EXIT_GRACE_MS)); })]);
+    else if (work) await Promise.race([loaded, new Promise((r) => { wall = setTimeout(r, Math.max(budgetMs, timeoutMs - EXIT_GRACE_MS)); })]);
     clearTimeout(wall);
 
     const history = await cdp.send('Page.getNavigationHistory', {}, sessionId);
@@ -353,6 +383,25 @@ async function captureOnce(browser, { url, out, width, height, timeoutMs, budget
 
     if (modelExport) return { ok: true, base64: exported.base64 };
 
+    if (work) {
+      const page = {
+        screenshot: async () => {
+          const shot = await cdp.send('Page.captureScreenshot', { format: 'png' }, sessionId);
+          return Buffer.from(shot.data ?? '', 'base64');
+        },
+        evaluate: async (expression) => {
+          const answer = await cdp.send('Runtime.evaluate', { expression, awaitPromise: true, returnByValue: true }, sessionId);
+          if (answer.exceptionDetails) throw new Error(String(answer.exceptionDetails.exception?.description ?? answer.exceptionDetails.text ?? 'evaluation failed').slice(0, 500));
+          return answer.result?.value;
+        },
+        left: () => left,
+        pageError: () => pageError,
+      };
+      const value = await work(page);
+      if (left) return { ok: false, reason: 'left-page', message: `${left}.` };
+      return { ok: true, value };
+    }
+
     const shot = await cdp.send('Page.captureScreenshot', { format: 'png' }, sessionId);
     // One last look: a navigation that landed during the capture.
     if (left) return { ok: false, reason: 'left-page', message: `${left}.` };
@@ -390,6 +439,8 @@ export async function capturePinnedPage({
   budgetMs = 5_000,
   allowSubresource = () => false,
   modelExport = false,
+  work = null,
+  initScript = null,
   signal,
   browser = resolveBrowser(),
   spawn: spawnImpl = spawn,
@@ -406,7 +457,7 @@ export async function capturePinnedPage({
   let last = null;
   for (const headlessFlag of ['--headless=new', '--headless']) {
     const once = () =>
-      captureOnce(browser, { url, out, width, height, timeoutMs, budgetMs, allowSubresource, headlessFlag, noSandbox, modelExport, signal }, { spawnImpl, env });
+      captureOnce(browser, { url, out, width, height, timeoutMs, budgetMs, allowSubresource, headlessFlag, noSandbox, modelExport, work, initScript, signal }, { spawnImpl, env });
     let r = await once();
     if (!r.ok && r.sandboxFailed) {
       noSandbox = true; // sticky: the one retry this capture gets

package/bin/lib/projectTools.mjs

@@ -219,7 +219,10 @@ export function prepareAgentTools(snapshot, runner, callerEnv = process.env, wor
       mcpServers[name] = { type: config.type ?? 'http', url, ...(Object.keys(headers).length ? { headers } : {}) };
     }
   }
-  Object.assign(mcpServers, turnServers); // daemon-owned names cannot be replaced by project config
+  // Daemon-owned names cannot be replaced by project config. A turn server's
+  // `toolTimeoutSec` is the Codex mount's alone (codexFencedMount.mjs); it is
+  // no key of Claude's mcp.json.
+  for (const [name, { toolTimeoutSec: _codexOnly, ...config }] of Object.entries(turnServers)) mcpServers[name] = config;
   const mcpPath = join(dir, 'mcp.json');
   writeFileSync(mcpPath, JSON.stringify({ mcpServers }), { mode: 0o600 });
   const pointers = [];

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, SYSTEM_AGENT_VIDEO, 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
@@ -642,6 +652,9 @@ with the matching name your CLI exposes.
      "An illustration", "a hero image", "a photo of", "artwork for". Only on a
      machine whose Codex makes images: if stage_card refuses the kind, say so
      rather than staging another kind in its place.
+   - "video": an animation — GIF, MP4 or WebM files rendered from a page the
+     agent writes; no code changed. "A GIF", "an animation", "a video of",
+     "a looping clip", "animate the logo".
    - "deck": a presentation — one HTML slide deck; no code changed. "Slides",
      "a deck", "a presentation", "a pitch".
    - "research": findings or a requested Markdown document — read the repo and the web; no code changed.
@@ -881,6 +894,7 @@ export const INTAKE_TASK_TYPE_MEANINGS = Object.freeze({
   model3d: 'Game-ready or product assets',
   vector: 'SVG icons, logos, marks',
   image: 'Illustrations, photos, artwork',
+  video: 'Animated GIFs and short clips',
   research: 'Find out and cite',
   writing: 'Docs, copy, specs',
 });
@@ -993,15 +1007,16 @@ THE RULES THAT MATTER:
 
 8. EVERY CARD HAS A KIND. A "code" card lands as commits and is merged; every
    other kind — "design" (a mockup), "model" (a 3D model), "image" (pictures),
-   "deck" (a presentation) and "research" (findings or a requested document) —
+   "video" (GIF, MP4 or WebM animations), "deck" (a presentation) and
+   "research" (findings or a requested document) —
    changes nothing in the repository. Research retains findings, sources and
    uncertainties directly on its source card; only requested documents need
    a Markdown file. The other non-code kinds hand back files. Keep non-code cards in agents of their
    own unless they are prerequisites for code, including an investigation
    whose findings the next card fixes. Independent artifacts mixed into a code
    agent turn a review that is "look at this and
-   accept it" into a merge. Image cards run on Codex. Mockup, 3D model and deck
-   cards run on Claude OR Codex, so dependent image and model work belongs on
+   accept it" into a merge. Image cards run on Codex. Mockup, 3D model, video
+   and deck cards run on Claude OR Codex, so dependent image and model work belongs on
    ONE Codex agent. Research runs on Claude, or on Codex where that machine
    reports support; keep each group on a CLI that can run all its cards.
    Different end products alone are not a reason to split dependent work.
@@ -1268,6 +1283,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}`;
 
 /**
@@ -1437,6 +1454,7 @@ export const AGENT_CONTRACTS = Object.freeze({
   design: SYSTEM_AGENT_DESIGN,
   model: SYSTEM_AGENT_MODEL,
   image: SYSTEM_AGENT_IMAGE,
+  video: SYSTEM_AGENT_VIDEO,
   deck: SYSTEM_AGENT_DECK,
   research: SYSTEM_AGENT_RESEARCH,
 });
@@ -1444,6 +1462,7 @@ export const AGENT_HANDS_BACK = Object.freeze({
   design: 'a DESIGN card: it hands back a mockup',
   model: 'a 3D MODEL card: it hands back a model to view and download as a .glb',
   image: 'an IMAGE card: it hands back pictures as PNG or WebP files',
+  video: 'a VIDEO card: it hands back animation files as GIF, MP4 or WebM',
   deck: 'a PRESENTATION card: it hands back an HTML slide deck',
   research: 'a RESEARCH card: it hands back findings or a requested document',
 });
@@ -1814,6 +1833,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/runtimeCodex.mjs

@@ -347,7 +347,7 @@ export const CODEX_RUNTIME = {
     if (a.includes('--ignore-user-config')) a.push(...(personal?.args ?? []));
 
     a.push(...mcp, ...resultSchemaArgs);
-    if (gated) a.push(...codexOrchestratorArgs());
+    if (gated) a.push(...codexOrchestratorArgs(codexVersion));
     a.push(streamInput ? '-' : codexPrompt({ system, prompt, profile }));
     return a;
   },

package/bin/lib/turnGaps.mjs

@@ -0,0 +1,47 @@
+/**
+ * WHAT THE AGENT SAYS IT DID NOT DELIVER (2026-10-25).
+ *
+ * An audit of eighteen merged runs found the same shape in most of them: the
+ * delivery report said what was done and how it was checked, and nothing in
+ * the contract asked what was NOT done against the request — so a dropped
+ * design state came back as a "decision" ("Before Review they keep the old
+ * per-card plates"), a faked measurement as "measured 2500ms", and the pre-review,
+ * grading only the card's own checklist, passed both. The contract's
+ * `WHOLE_REQUEST` now asks for `gaps`; this reads them and says them where the
+ * person reviews (Verification on a code card, the summary on any other).
+ *
+ * THREE STATES, the house rule: no key is unknown and renders NOTHING (an
+ * older prompt, a resumed conversation that never saw it); `[]` is the
+ * agent's claim that it walked the request and nothing is missing; entries are
+ * listed. A malformed entry costs that entry alone.
+ */
+export const GAP_STATUSES = ['not built', 'partly', 'unverified', 'unowned'];
+export const MAX_GAPS = 40;
+export const MAX_GAP_ITEM = 300;
+export const MAX_GAP_WHY = 800;
+
+const cut = (s, n) => (s.length > n ? s.slice(0, n - 1) + '…' : s);
+
+/** The declared gaps, scrubbed then bounded; undefined when none were declared. */
+export function parseGaps(raw, scrub) {
+  if (!Array.isArray(raw)) return undefined;
+  const out = [];
+  for (const g of raw) {
+    if (out.length >= MAX_GAPS) break;
+    if (!g || typeof g !== 'object' || typeof g.item !== 'string' || !g.item.trim()) continue;
+    const status = typeof g.status === 'string' ? g.status.trim().toLowerCase() : '';
+    if (!GAP_STATUSES.includes(status)) continue;
+    const why = typeof g.why === 'string' && g.why.trim() ? cut(scrub(g.why.trim()), MAX_GAP_WHY) : null;
+    out.push({ item: cut(scrub(g.item.trim()), MAX_GAP_ITEM), status, ...(why ? { why } : {}) });
+  }
+  return out;
+}
+
+/** The section the person reads, or null for no declaration. */
+export function gapsMarkdown(gaps) {
+  if (!Array.isArray(gaps)) return null;
+  if (!gaps.length) return '**Gaps against the request:** none reported.';
+  return ['**Gaps against the request**', ...gaps.map((g) => `- **${g.status}** — ${oneLine(g.item)}${g.why ? `: ${oneLine(g.why)}` : ''}`)].join('\n');
+}
+
+const oneLine = (s) => s.replace(/\s*\n\s*/g, ' ');

package/bin/lib/uiReviewContract.mjs

@@ -46,6 +46,6 @@ export function validateReviewPlan(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.
+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. Shape the fixture from the case the request describes, not from your implementation: the person's screenshot or report (its counts, names and states, such as a 23-card agent or a page with no stored render) or a committed export of real data among the repository's test fixtures when one exists. A fixture shaped only by your own code shows the code renders, not that the request is met: list that as an "unverified" gap.
 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.`;
 }