flowviant 0.125.12 → 0.125.15

package/bin/lib/modelExportProtocol.mjs

@@ -0,0 +1,80 @@
+/** The bounded model export handshake used inside the pinned browser. */
+import { ARTIFACT_BINARY_MODEL_MAX_BYTES } from './artifactPolicy.mjs';
+
+export function usableGlb(bytes) {
+  return Buffer.isBuffer(bytes) && bytes.length >= 12 && bytes.length <= ARTIFACT_BINARY_MODEL_MAX_BYTES &&
+    bytes.readUInt32LE(0) === 0x46546c67 && bytes.readUInt32LE(4) === 2 && bytes.readUInt32LE(8) === bytes.length;
+}
+
+/** A working model input also needs readable glTF JSON, geometry and its
+ * declared resources. The browser's existing header/cap rule remains intact;
+ * this stricter local prerequisite check prevents a header-only/partial file
+ * from advancing the producer. It does not attest shape, scale or engine use. */
+export function usableModelGlb(bytes) {
+  if (!usableGlb(bytes)) return false;
+  try {
+    let offset = 12, json = null, binary = null;
+    while (offset < bytes.length) {
+      if (offset + 8 > bytes.length) return false;
+      const length = bytes.readUInt32LE(offset), type = bytes.readUInt32LE(offset + 4);
+      if (length % 4 || offset + 8 + length > bytes.length) return false;
+      const chunk = bytes.subarray(offset + 8, offset + 8 + length);
+      if (offset === 12 && type !== 0x4e4f534a) return false;
+      if (type === 0x4e4f534a) { if (json) return false; json = JSON.parse(chunk.toString('utf8')); }
+      if (type === 0x004e4942) { if (binary) return false; binary = chunk; }
+      offset += 8 + length;
+    }
+    if (json?.asset?.version !== '2.0' || !binary || !Array.isArray(json.meshes) || !json.meshes.length ||
+        !Array.isArray(json.buffers) || json.buffers.length !== 1) return false;
+    const buffer = json.buffers[0];
+    if (buffer.uri != null || !Number.isInteger(buffer.byteLength) || buffer.byteLength < 1 ||
+        buffer.byteLength > binary.length || binary.length - buffer.byteLength > 3) return false;
+    const views = json.bufferViews ?? [], accessors = json.accessors ?? [], images = json.images ?? [];
+    if (!Array.isArray(views) || !Array.isArray(accessors) || !Array.isArray(images)) return false;
+    if (views.some(view => view.buffer !== 0 || !Number.isInteger(view.byteLength) || view.byteLength < 0 ||
+        !Number.isInteger(view.byteOffset ?? 0) || (view.byteOffset ?? 0) < 0 ||
+        (view.byteOffset ?? 0) + view.byteLength > buffer.byteLength)) return false;
+    if (images.some(image => image.uri != null || !Number.isInteger(image.bufferView) || !views[image.bufferView])) return false;
+    if ((json.textures ?? []).some(texture => !Number.isInteger(texture.source) || !images[texture.source])) return false;
+    if (!json.meshes.every(mesh => Array.isArray(mesh.primitives) && mesh.primitives.length && mesh.primitives.every(primitive => {
+      const position = accessors[primitive.attributes?.POSITION];
+      return position && Number.isInteger(position.count) && position.count > 0 && views[position.bufferView];
+    }))) return false;
+    return Array.isArray(json.nodes) && json.nodes.some(node => Number.isInteger(node.mesh) && json.meshes[node.mesh]);
+  } catch { return false; }
+}
+
+/** Installed before any page script runs. The top-level sandbox's parent is
+ * itself, so the existing parent/source-checked handshake runs unchanged.
+ * Accept one solicited answer, bound before conversion over the CDP pipe. */
+export const MODEL_EXPORT_BRIDGE = `(() => {
+  let requested = false, settled = false;
+  window.__flowviantExport = new Promise(resolve => {
+    addEventListener('message', e => {
+      if (e.source !== window || settled) return;
+      const said = e.data;
+      if (!requested && said?.flowviant === 'glb-ready') {
+        requested = true;
+        window.postMessage({flowviant:'export-glb'}, '*');
+      } else if (requested && said?.flowviant === 'glb-error') {
+        settled = true;
+        const message = String(said.message ?? 'Export failed');
+        resolve({error: message.length <= 500 ? message : 'The page returned a long export error. Inspect this page and repair its export handler.'});
+      } else if (requested && said?.flowviant === 'glb') {
+        settled = true;
+        const value = said.glb;
+        if (Object.prototype.toString.call(value) !== '[object ArrayBuffer]' ||
+            value.byteLength < 12 || value.byteLength > ${ARTIFACT_BINARY_MODEL_MAX_BYTES}) {
+          resolve({error:'The page did not return a bounded .glb ArrayBuffer.'}); return;
+        }
+        const bytes = new Uint8Array(value), head = new DataView(value);
+        if (head.getUint32(0,true) !== 0x46546c67 || head.getUint32(4,true) !== 2 || head.getUint32(8,true) !== bytes.length) {
+          resolve({error:'The page returned an invalid .glb header.'}); return;
+        }
+        let binary = '';
+        for (let i=0; i<bytes.length; i+=8192) binary += String.fromCharCode(...bytes.subarray(i,i+8192));
+        resolve({base64:btoa(binary)});
+      }
+    });
+  });
+})();`;

package/bin/lib/nativeAgentTools.mjs

@@ -74,14 +74,17 @@ export const isShellTool = name => nativeName(name) === 'Bash';
 export const isClaudeFollowupTool = name => NATIVE_AGENT_TOOLS.claude.followup.includes(nativeName(name));
 // The controller reads only Claude's stop: TaskStop names its child as task_id.
 export const isClaudeStopTool = name => NATIVE_AGENT_TOOLS.claude.stop.includes(nativeName(name));
+/** Both runtime hook spellings for the capture server. */
+export const captureToolName = name => String(name ?? '').match(/^(?:mcp__flowviant__|mcp[./]flowviant[./]|flowviant[./])([a-z_]+)$/)?.[1] ?? null;
 
 /** What the hook refuses while the controller is unreachable: every spawn and
  * follow-up the controller gates, and on a run whose children only read
  * (`children` 'read', a research card) a child's write or shell, which only
  * the controller can fence read-only. */
 export const GATED_TOOLS = Object.freeze([...SPAWN, ...FOLLOWUP]);
-export const gatedSpawnEvent = (event, children = 'edit') => event?.hook_event_name === 'PreToolUse' &&
+export const gatedSpawnEvent = (event, children = 'edit', readOnlyRun = false) => event?.hook_event_name === 'PreToolUse' &&
   (GATED_TOOLS.includes(nativeName(event.tool_name)) ||
+    (readOnlyRun && (isChildWriteTool(event.tool_name) || Boolean(captureToolName(event.tool_name)) || /^(?:mcp__|mcp[./])/.test(String(event.tool_name)))) ||
     (children === 'read' && Boolean(event.agent_id) && (isChildWriteTool(event.tool_name) || isShellTool(event.tool_name))));
 
 /** Claude's PostToolUse and PostToolUseFailure matcher (orchestratorHooks.mjs):

package/bin/lib/orchestrator.mjs

@@ -11,7 +11,7 @@ import { scrub, learnExtraSecrets, forgetExtraSecrets } from './uplinkScrub.mjs'
 import { OrchestratorInputTooLarge, readOrchestratorInput } from './orchestratorInput.mjs';
 import { SAFE_POINT_AFTER_EDIT as AFTER_EDIT } from './orchestratorProtocol.mjs';
 import { MACHINE_MESSAGE_ROUTE_STATES, MESSAGE_ROUTE_FIELD_MAX, OPEN_MESSAGE_ROUTE_STATES, ORCHESTRATOR_SERVER } from './orchestratorProtocol.mjs';
-import { isChildWriteTool, isClaudeStopTool, isDiscoveryTool, isFollowupTool, isPersonQuestionTool, isShellTool, isSpawnTool } from './nativeAgentTools.mjs';
+import { captureToolName, isChildWriteTool, isClaudeStopTool, isDiscoveryTool, isFollowupTool, isPersonQuestionTool, isShellTool, isSpawnTool } from './nativeAgentTools.mjs';
 import { childBrain, childChoice, followupTarget, readOnlyShell, readSpawn, spawnReceipt, withChildContract } from './orchestratorNative.mjs';
 import { SETTLED_SUBAGENT_STATUSES, SUBAGENT_CAP, SUBAGENT_FIELD_CAPS } from './subagentBounds.mjs';
 
@@ -35,18 +35,23 @@ const text = (s, n) => scrubNativeText(s, n, scrub);
  * on Codex, only for a model in `catalog`, the measured spawnable models.
  */
 export async function createOrchestrator({ turnId, runtime, trace, admit, request = fleetRequest, notify = () => false, taken = () => {},
-  interval = 500, hold = 60_000, clock = Date.now, scrubText = text, children = {} } = {}) {
-  const access = children.access === 'read' ? 'read' : 'edit',
+  interval = 500, hold = 60_000, clock = Date.now, scrubText = text, children = {}, readOnlyRun = null, signal, rootTools = null } = {}) {
+  // Consults belong to a held attempt, never to a card turn. This capability
+  // is entirely local; it cannot report routes or borrow an agent principal.
+  if (readOnlyRun && (!['plan', 'capture'].includes(readOnlyRun.scope) || !filled(readOnlyRun.id) ||
+    !Number.isSafeInteger(readOnlyRun.attempt) || readOnlyRun.attempt < 0)) throw new Error('A read-only run needs its held attempt identity.');
+  if (rootTools && readOnlyRun?.scope !== 'capture') throw new Error('Only a capture coordinator may authorize capture tools.');
+  const access = (readOnlyRun || children.access === 'read') ? 'read' : 'edit',
     card = { model: children.model ?? null, effort: children.effort ?? null, catalog: Array.isArray(children.catalog) ? children.catalog : [] };
   // A Codex research child's shell runs in a read-only bubblewrap view
   // (orchestratorNative.mjs `readOnlyShell`); without one it is refused.
   // Claude's research shell is the posture's guarded readers already.
-  const bwrap = runtime === 'codex' && access === 'read'
+  const bwrap = runtime === 'codex' && access === 'read' && !readOnlyRun
     ? (children.bwrap !== undefined ? children.bwrap : ['/usr/bin/bwrap', '/bin/bwrap'].find(path => existsSync(path)) ?? null) : null;
   if (typeof admit !== 'function' || typeof admit.reserve !== 'function') throw new Error('This run has no project admission pool.');
   // Minted before the server exists, so the scrubber knows it from the start.
   const capability = mintHeldCapability();
-  const secretKey = `orchestrator:${turnId}:${capability.slice(0, 8)}`;
+  const secretKey = `orchestrator:${readOnlyRun ? `${readOnlyRun.scope}:${readOnlyRun.id}:${readOnlyRun.attempt}` : turnId}:${capability.slice(0, 8)}`;
   learnExtraSecrets(secretKey, [{ name: 'FLOWVIANT_ORCHESTRATOR_CAPABILITY', value: capability }]);
   const records = new Map(), aliases = new Map(), calls = new Map(), notes = new Map(), questions = new Map();
   // A person's notes (Codex) and the daemon's wakes queue apart: a burst of
@@ -54,7 +59,8 @@ export async function createOrchestrator({ turnId, runtime, trace, admit, reques
   const inbox = new Map(), wakes = new Map();
   const pending = new Map(), steps = new Map();
   let closed = false, polling = false, rootSession = null, offerAt = 0;
-  const identity = { scope: 'agent', turnId, instance: DAEMON_INSTANCE };
+  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;
   // A re-held note keeps its native id; resolve it when matched, not when held.
   const target = note => note.agentId ? resolve(note.agentId) : undefined;
@@ -78,6 +84,7 @@ export async function createOrchestrator({ turnId, runtime, trace, admit, reques
   };
   const field = (key, value, cap) => { const v = filled(value) ? scrubText(value, cap) : ''; return v.trim() ? { [key]: v } : {}; };
   const route = async args => {
+    if (readOnlyRun) throw new Error('Read-only coordination has no card routing or board-write capability.');
     const note = notes.get(args.messageId);
     if (!note) throw new Error('That note is not held by this run.');
     if (!MACHINE_MESSAGE_ROUTE_STATES.includes(args.state)) throw new Error('Choose queued, handed or taken.');
@@ -148,9 +155,11 @@ 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 = `\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.`;
+    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.`;
     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 + (access === 'read' ? READ_ONLY_CHILD : ''), chosen.brain) };
+      updatedInput: withChildContract(event, spawn, childContract + (access === 'read' && !readOnlyRun ? READ_ONLY_CHILD : ''), 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
@@ -214,6 +223,7 @@ export async function createOrchestrator({ turnId, runtime, trace, admit, reques
     if (native === null) return claude ? null : { deny: 'Name the native agent to resume.' };
     const id = named(native);
     if (!records.has(id)) {
+      if (readOnlyRun) return { deny: 'That child does not belong to this read-only attempt. Start a new investigation here.' };
       // 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.' };
@@ -271,22 +281,30 @@ export async function createOrchestrator({ turnId, runtime, trace, admit, reques
       }
       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.' };
-      if (child && access === 'read' && isChildWriteTool(ev.tool_name)) return { deny: READ_ONLY_REFUSAL };
+      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.' };
+        return rootTools.authorize(ev);
+      }
+      if (readOnlyRun && /^(?:mcp__|mcp[./])/.test(String(ev.tool_name)) && !String(ev.tool_name).includes(ORCHESTRATOR_SERVER))
+        return { deny: 'This read-only attempt has only internal coordination tools; no board, staging or external MCP capability.' };
       if (isSpawnTool(ev.tool_name)) return preSpawn(ev);
       if (isFollowupTool(ev.tool_name)) { const resumed = preResume(ev); if (resumed) return resumed; }
       const point = checkpoint(ev); if (point.deny) return point;
-      if (child && access === 'read' && runtime === 'codex' && isShellTool(ev.tool_name)) {
+      if (child && access === 'read' && !readOnlyRun && runtime === 'codex' && isShellTool(ev.tool_name)) {
         const fenced = readOnlyShell(ev, bwrap);
         return fenced ? { updatedInput: fenced } : { deny: `${READ_ONLY_REFUSAL} ${bwrap ? 'Its shell could not be fenced read-only: give the command as text.' : 'This machine has no bubblewrap to keep a child’s shell read-only, so a child here searches the web; the orchestrator reads files.'}` };
       }
       if (isPersonQuestionTool(ev.tool_name))
-        return { deny: 'A child asks its orchestrator with agent_question first. The orchestrator escalates only person-only decisions through the existing blocked JSON question card.' };
+        return { deny: readOnlyRun?.scope === 'capture' ? 'A child asks the coordinator with agent_question. Only the coordinator asks a person-only question through the existing single-question flowviant-ask fence.' : 'A child asks its orchestrator with agent_question first. The orchestrator escalates only person-only decisions through the existing blocked JSON question card.' };
     }
     if (ev.hook_event_name === 'PostToolUse' && (isSpawnTool(ev.tool_name) || isFollowupTool(ev.tool_name))) postSpawn(ev);
     return {};
   }
   async function handle(action, args) {
-    if (closed) throw new Error('This run stopped.');
+    if (ended()) throw new Error('This run stopped.');
+    if (action === 'capture_describe' && rootTools) return rootTools.describe();
+    if (action === 'capture_call' && rootTools) return rootTools.call(args);
     if (action === 'hook') {
       const result = hook(args);
       // Root PreToolUse/PostToolUse additionalContext is measured on both CLIs.
@@ -300,7 +318,7 @@ export async function createOrchestrator({ turnId, runtime, trace, admit, reques
     // 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.
-    if (action === 'answer_agent' && !records.has(id) && typeof id === 'string' && id.length > 0 && id.length <= 160 && records.size < SUBAGENT_CAP &&
+    if (!readOnlyRun && action === 'answer_agent' && !records.has(id) && typeof id === 'string' && id.length > 0 && id.length <= 160 && records.size < SUBAGENT_CAP &&
       typeof args.question === 'string' && args.question.trim() && args.question.length <= 4_000) {
       // Resumable, never spawnable: no slot is offered until a gated follow-up targets it.
       emit({ id, kind: scrubText(args.kind ?? '', SUBAGENT_FIELD_CAPS.kind), title: scrubText(args.title ?? '', SUBAGENT_FIELD_CAPS.title), brief: '', status: 'asked', now: args.question, resumable: true });
@@ -319,7 +337,7 @@ export async function createOrchestrator({ turnId, runtime, trace, admit, reques
       let q = questions.get(id);
       // The person answers in a later run; the child ends now so this run settles on the question card.
       if (q?.escalated && !q.answer) return { waiting: true, escalated: true,
-        instruction: 'Your orchestrator escalated this to the person. Stop now: end your work with a short summary of where you are. You will be continued with the answer.' };
+        instruction: readOnlyRun ? 'Stop this investigation and return your findings and the unresolved question to the coordinator. This attempt will not resume after it ends.' : 'Your orchestrator escalated this to the person. Stop now: end your work with a short summary of where you are. You will be continued with the answer.' };
       // A given answer stands for a reworded poll until the child has it.
       if (q?.answer && (!q.read || q.question === args.question)) { q.read = true; return { answer: q.answer }; }
       if (!q || q.question !== args.question) {
@@ -333,7 +351,7 @@ export async function createOrchestrator({ turnId, runtime, trace, admit, reques
     if (action === 'answer_agent') {
       const q = questions.get(id); if (!q) throw new Error('That agent has no unanswered question.');
       if (args.escalate === true) { q.escalated = true; return { askingAgent: { id, nativeAgentId: a.nativeId, kind: a.kind, title: a.title },
-        question: `${a.kind || a.title || id} asks: ${q.question}`, instruction: 'The child is told to stop. Once every child has finished or been stopped, return the existing blocked JSON question card with this attribution. Leave the agent asked until the person answers.' }; }
+        question: `${a.kind || a.title || id} asks: ${q.question}`, instruction: readOnlyRun?.scope === 'capture' ? 'The child is told to stop and return findings. Consolidate person-only uncertainties into the existing one-question flowviant-ask fence in this conversation. Keep staged row IDs, provisional assumptions and the coordinator final reply; do not return a card-delivery JSON or stage a card per child.' : readOnlyRun ? 'The child is told to stop and return findings. Retain the uncertainty in proposal evidence, or use the existing question shape if this is a diagnostic turn. Keep the turn’s existing final JSON protocol.' : 'The child is told to stop. Once every child has finished or been stopped, return the existing blocked JSON question card with this attribution. Leave the agent asked until the person answers.' }; }
       if (typeof args.answer !== 'string' || !args.answer.trim() || args.answer.length > 4_000) throw new Error('Give the agent a bounded answer.');
       q.answer = args.answer; trace.handoff(id, runtime, args.answer); emit({ id, status: a.release ? 'running' : 'waiting', now: 'Question answered by the orchestrator' });
       return { answered: true, instruction: 'Give this answer to the child with its native follow-up/resume tool.' };
@@ -350,12 +368,17 @@ export async function createOrchestrator({ turnId, runtime, trace, admit, reques
         error: text(error.message, 300), ...(error instanceof OrchestratorInputTooLarge ? { code: error.code } : {}),
       })); }
   };
-  const { server, env: heldEnv, args: argv } = await listenHeldTool({ envPrefix: 'FLOWVIANT_ORCHESTRATOR', verb: '__orchestrator-mcp', requestTimeoutMs: 5_000,
-    capability, isClosed: () => closed, respond });
+  let listener;
+  try {
+    listener = await listenHeldTool({ envPrefix: 'FLOWVIANT_ORCHESTRATOR', verb: '__orchestrator-mcp', requestTimeoutMs: 5_000,
+      capability, isClosed: ended, respond });
+  } catch (error) { forgetExtraSecrets(secretKey); throw error; }
+  const { server, env: heldEnv, args: argv } = listener;
   // The hook reads it to refuse a research child's write while this is down.
-  const env = { ...heldEnv, FLOWVIANT_ORCHESTRATOR_CHILDREN: access };
+  const env = { ...heldEnv, FLOWVIANT_ORCHESTRATOR_CHILDREN: access,
+    ...(readOnlyRun ? { FLOWVIANT_ORCHESTRATOR_READ_ONLY: '1' } : {}) };
   const timer = setInterval(() => {
-    if (closed || polling) return;
+    if (ended() || polling) return;
     polling = true;
     try {
       const now = clock();
@@ -397,6 +420,7 @@ export async function createOrchestrator({ turnId, runtime, trace, admit, reques
     outstanding() { return [...notes.values()].filter(n => OPEN_MESSAGE_ROUTE_STATES.includes(n.state)).map(n => ({ id: n.messageId, state: n.state, body: n.body, agentId: target(n), safePoint: n.safePoint })); },
     input(id, body) { if (closed || inbox.size >= 64 && !inbox.has(id)) return false; inbox.set(id, body); return true; },
     observe(update) {
+      if (ended()) return;
       if (update.nativeId) bind(update.nativeId, update.id);
       if (update.callId && calls.has(update.callId)) bind(update.id, calls.get(update.callId));
       const id = resolve(update.id);
@@ -408,10 +432,12 @@ export async function createOrchestrator({ turnId, runtime, trace, admit, reques
       apply(id, update);
     },
     async close(stopped = false) {
+      if (closed) return;
       closed = true; clearInterval(timer);
+      rootTools?.close();
       // Only an escalated question waits for the person; any other asked child ended with the run.
       for (const a of records.values()) { release(a.id); const q = questions.get(a.id);
-        if (!terminal(a.status) && !(a.status === 'asked' && !stopped && q?.escalated && !q.answer)) emit({ id: a.id, status: 'stopped', now: stopped ? 'Stopped with the run' : 'Run ended' }); }
+        if (!terminal(a.status) && !(a.status === 'asked' && !readOnlyRun && !stopped && q?.escalated && !q.answer)) emit({ id: a.id, status: 'stopped', now: stopped ? 'Stopped with the run' : 'Run ended' }); }
       server.close(); server.closeAllConnections();
       forgetExtraSecrets(secretKey);
     },

package/bin/lib/orchestratorClient.mjs

@@ -9,13 +9,13 @@ export const ORCHESTRATOR_CLIENT_TIMEOUT_MS = 15_000;
 /** The controller's own refusal (a 409 body's words), relayed as said. */
 export class OrchestratorRefusal extends Error {}
 
-export async function callOrchestrator(action, args) {
+export async function callOrchestrator(action, args, timeoutMs = ORCHESTRATOR_CLIENT_TIMEOUT_MS) {
   const url = new URL(process.env.FLOWVIANT_ORCHESTRATOR_URL);
   if (url.hostname !== '127.0.0.1' || url.protocol !== 'http:') throw new Error('No held run is available.');
   const body = JSON.stringify({ action, args });
   if (Buffer.byteLength(body) > ORCHESTRATOR_REQUEST_BYTES) throw new OrchestratorInputTooLarge();
   const response = await fetch(url, { method: 'POST', headers: { Authorization: `Bearer ${process.env.FLOWVIANT_ORCHESTRATOR_CAPABILITY}`, 'Content-Type': 'application/json' },
-    body, signal: AbortSignal.timeout(ORCHESTRATOR_CLIENT_TIMEOUT_MS) });
+    body, signal: AbortSignal.timeout(timeoutMs) });
   // A closed or foreign run answers a bare 403: no body to parse.
   let result = null;
   try { result = JSON.parse(await response.text()); } catch { result = null; }

package/bin/lib/orchestratorPrompt.mjs

@@ -38,6 +38,76 @@ const atCard = (model, effort) =>
 
 const childBrain = ({ runtime, model, effort }) => `CHILD MODEL AND EFFORT. ${atCard(model, effort)} By default every child runs at the card's model and effort${model || effort ? '; the gate names them when your spawn names neither, so a child never falls back to the CLI\'s own global default' : ', which it inherits from this run when your spawn names neither'}. For a simple, well-bounded child — a search, a sweep of file reads, a mechanical edit — you may choose a cheaper model or a lower effort. Keep the card's model and effort for hard or judgment-heavy work. Never choose a model or effort above the card's, and only models of this card's own CLI; the gate refuses an effort above the card's. ${CHILD_SPELLING[runtime] ?? ''} When you choose anything other than the card's model or effort for a child, name the choice and why in your update.`.replace('  ', ' ');
 
+/** Investigators do not propose separate plans. Only this coordinator sees
+ * and reconciles the complete selection before the existing JSON validator. */
+export function planningOrchestratorContract({ diagnosis = false, ...brain } = {}) {
+  return `READ-ONLY PLANNING COORDINATOR
+${diagnosis ? 'You alone return the existing diagnostic JSON for the entire selected workload. A fresh planning consult follows a repaired diagnosis; do not return a proposal here.' : 'You alone return the existing proposal JSON for the entire selected workload.'}
+Identify independent repository questions or code areas before investigating.
+Delegate independent investigations to native children while you inspect one
+part yourself. Dependent investigations wait for their inputs; small inseparable
+work stays solo. Use only native children that can call card_orchestrator, sharing
+this checkout, its repository/knowledge read boundary and runtime restrictions.
+Every child only reads: no file writes, commits, worktrees, board/staging tools,
+project/personal MCP or network capability. Ask for findings, source paths and
+uncertainties, not a partial proposal. A claimed citation is not measured proof
+of a successful read. Preserve reader failures and unknown results.
+Reconcile all findings and conflicts across the complete selection, including
+exact card identities, prerequisites first, declared dependencies, cross-source
+file collisions, retained research/source context and live work. Source composers
+are provenance, never grouping boundaries. Never drop an uninvestigated card.
+${diagnosis ? 'Keep the existing repaired/question diagnostic shape.' : 'Keep the existing proposal shape and per-group human acceptance: no work starts.'}
+Children ask you through agent_question; answer with answer_agent and its native
+follow-up, from this context and the repository. Retain unresolved uncertainties
+in proposal evidence; the existing diagnostic question protocol still applies
+when diagnosing a failed attempt. Only you ask any person-only question.
+The root and children share the project's Turns at once pool. A refused spawn
+has not started: continue investigating yourself. Retry only when offered a
+slot, and finish solo if none becomes available. Do not bypass admission with
+another CLI process. Wait for every started child to finish or stop before your
+final proposal. Stop ends the whole attempt; stale children cannot be resumed.
+${childBrain(brain).replaceAll('card', 'planning turn')}`;
+}
+
+export function captureOrchestratorContract(brain = {}) {
+  return `READ-ONLY CAPTURE INVESTIGATIONS
+You own this one ongoing conversation and its staged proposals. For a broad
+request with independent repository questions, give bounded read-only questions
+to native children while you investigate another area. Small focused requests,
+simple corrections and short follow-ups with no independent investigations stay
+solo. Dependent questions wait for their inputs. Use only native children that
+can call card_orchestrator, sharing this checkout and its repository/knowledge
+read boundary. They gain no network or project/personal MCP access.
+Children write no files and call NO flowviant tools, including list/staging or
+stream_session_turn. They return findings, source paths and uncertainties to
+you; you alone ask the person, using the existing single-question fence, and
+you alone read list_cards/list_staged/read_card, dedupe the complete request,
+stage, edit or withdraw rows and stream the conversation. The tool gate and
+credential relay enforce this for descendants and resumed children too.
+Before staging, reconcile all findings with the original request, selected
+repository catalog, exact attached/retained reference versions, prior decisions,
+assumptions and dependencies. A claimed citation does not establish a successful
+read. Preserve actual failed/unknown reader outcomes. Keep grounded references
+and unresolved assumptions on every affected brief. Stage independently shippable
+outcomes, never one card per child or one card per investigation step. Put
+prerequisites first and describe dependencies in both briefs. Refine existing
+staged rows in place; never duplicate or withdraw/restage them to recover.
+Ordinary conversational questions do not create unsolicited cards. Human
+landing, Plan and acceptance controls remain the only ways work starts.
+Each child registers with card_orchestrator and asks you with agent_question;
+answer from this conversation and repository using answer_agent and native
+follow-up. Consolidate person-only uncertainties into the existing one question.
+Wait for every started child to finish or stop before your final reply. Preserve
+the existing final-answer and streamed-reply protocol; child prose is not a
+second conversation reply. A refused spawn has not started: continue yourself,
+retry only when a slot is offered, and finish solo if none is available.
+The root and children share the project's Turns at once pool. Stop ends the
+whole run. Every new native invocation has a fresh capability; do not resume a
+child from a previous turn or retry. Preserve staged row IDs and use list_staged
+to reconcile an interrupted call before repeating it.
+${childBrain(brain).replaceAll('card', 'capture turn')}`;
+}
+
 /**
  * The orchestrator's contract for one run: its posture's split and child
  * rules, the card's own model and effort, then the gate, routing and child

package/bin/lib/pinnedCapture.mjs

@@ -46,6 +46,7 @@ import { join } from 'node:path';
 import { tmpdir, platform } from 'node:os';
 import { SANDBOX_FAILURE_RE, chromeEnv, chromeFlags, resolveBrowser, sandboxOff } from './shot.mjs';
 import { killGroup } from './processGroup.mjs';
+import { MODEL_EXPORT_BRIDGE } from './modelExportProtocol.mjs';
 
 /** How long a closing browser gets to exit before it is killed. */
 const EXIT_GRACE_MS = 3_000;
@@ -135,7 +136,7 @@ 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 }, { spawnImpl, env }) {
+async function captureOnce(browser, { url, out, width, height, timeoutMs, budgetMs, allowSubresource, headlessFlag, noSandbox, modelExport, signal }, { spawnImpl, env }) {
   const userDataDir = mkdtempSync(join(tmpdir(), 'flowviant-pin-'));
   const args = [...chromeFlags({ headlessFlag, noSandbox, userDataDir, width, height }), '--remote-debugging-pipe', 'about:blank'];
   let child;
@@ -190,10 +191,16 @@ async function captureOnce(browser, { url, out, width, height, timeoutMs, budget
   };
 
   let left = null; // the first sign the page was left, in words
+  let pageError = null;
   const leave = (why) => { if (!left) left = why; };
   let deadline;
   const timedOut = new Promise((resolve) => {
-    deadline = setTimeout(() => resolve({ ok: false, reason: 'timeout', message: `the page did not finish within ${timeoutMs / 1000}s.` }), timeoutMs);
+    deadline = setTimeout(() => resolve({ ok: false, reason: 'timeout', message: `the page did not finish within ${timeoutMs / 1000}s${pageError ? ': ' + pageError : '.'}` }), timeoutMs);
+  });
+  let onAbort;
+  const aborted = new Promise(resolve => {
+    onAbort = () => resolve({ ok: false, reason: 'aborted', message: 'The export was interrupted.' });
+    if (signal?.aborted) onAbort(); else signal?.addEventListener('abort', onAbort, { once: true });
   });
 
   const run = async () => {
@@ -247,6 +254,10 @@ async function captureOnce(browser, { url, out, width, height, timeoutMs, budget
         return;
       }
       if (!ours || msg.sessionId !== ours.sessionId) return;
+      if (msg.method === 'Runtime.exceptionThrown') {
+        const message = String(p.exceptionDetails?.exception?.description ?? p.exceptionDetails?.text ?? 'Page script failed');
+        pageError = message.length <= 500 ? message : 'A page script failed. Inspect this page and repair it.';
+      }
       if (msg.method === 'Fetch.requestPaused') {
         const requestId = p.requestId;
         const reqUrl = p.request?.url ?? '';
@@ -291,21 +302,32 @@ 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) await cdp.send('Page.addScriptToEvaluateOnNewDocument', { source: MODEL_EXPORT_BRIDGE }, sessionId);
     await cdp.send('Fetch.enable', { patterns: [{ urlPattern: '*', requestStage: 'Request' }] }, sessionId);
     await cdp.send('Emulation.setDeviceMetricsOverride', { width, height, deviceScaleFactor: 1, mobile: false }, sessionId);
-    await cdp.send('Emulation.setVirtualTimePolicy', { policy: 'pause' }, sessionId);
+    if (!modelExport) 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);
     if (nav.errorText) {
       return { ok: false, reason: 'render', message: `the page did not load (${nav.errorText}).` };
     }
-    // Let fonts and scripts settle, as `--virtual-time-budget` does.
-    await cdp.send('Emulation.setVirtualTimePolicy', { policy: 'pauseIfNetworkFetchesPending', budget: budgetMs }, sessionId);
+    // 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);
+    let exported = null;
+    if (modelExport) {
+      const answer = await cdp.send('Runtime.evaluate', {
+        expression: 'window.__flowviantExport', awaitPromise: true, returnByValue: true,
+      }, sessionId);
+      exported = answer.result?.value;
+      if (!exported?.base64) return { ok: false, reason: 'export', message: exported?.error ?? 'The page did not supply its model export.' };
+    }
     // A Chrome that never reports the budget is captured on the wall clock,
     // short of the deadline, rather than never.
     let wall;
-    await Promise.race([budget, new Promise((r) => { wall = setTimeout(r, Math.max(budgetMs, timeoutMs - EXIT_GRACE_MS)); })]);
+    if (!modelExport) await Promise.race([budget, new Promise((r) => { wall = setTimeout(r, Math.max(budgetMs, timeoutMs - EXIT_GRACE_MS)); })]);
     clearTimeout(wall);
 
     const history = await cdp.send('Page.getNavigationHistory', {}, sessionId);
@@ -318,6 +340,8 @@ async function captureOnce(browser, { url, out, width, height, timeoutMs, budget
     }
     if (left) return { ok: false, reason: 'left-page', message: `${left}.` };
 
+    if (modelExport) return { ok: true, base64: exported.base64 };
+
     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}.` };
@@ -329,9 +353,11 @@ async function captureOnce(browser, { url, out, width, height, timeoutMs, budget
     return await Promise.race([
       run().catch((e) => ({ ok: false, reason: 'render', message: e?.message ?? String(e) })),
       timedOut,
+      aborted,
     ]);
   } finally {
     clearTimeout(deadline);
+    signal?.removeEventListener('abort', onAbort);
     await shutdown();
   }
 }
@@ -352,6 +378,8 @@ export async function capturePinnedPage({
   timeoutMs = 60_000,
   budgetMs = 5_000,
   allowSubresource = () => false,
+  modelExport = false,
+  signal,
   browser = resolveBrowser(),
   spawn: spawnImpl = spawn,
   uid = process.getuid?.(),
@@ -367,7 +395,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 }, { spawnImpl, env });
+      captureOnce(browser, { url, out, width, height, timeoutMs, budgetMs, allowSubresource, headlessFlag, noSandbox, modelExport, signal }, { spawnImpl, env });
     let r = await once();
     if (!r.ok && r.sandboxFailed) {
       noSandbox = true; // sticky: the one retry this capture gets

package/bin/lib/prompts.mjs

@@ -1172,8 +1172,11 @@ or, if you are stopping to ask:
 \`\`\`
 
 "raised" is optional and only for work you did that was NOT this card. Do not
-list the card itself there. Do not put commit shas in the summary — they are
-read from git.
+list the card itself there. Each raised brief states the failure, the repair
+already completed on this branch and its verification or unverified limits.
+Raised work stays with this delivery; it is not a request for another execution.
+Use the separate prerequisite reply for explicitly requested unfinished work.
+Do not put commit shas in the summary — they are read from git.
 
 "progress" is REQUIRED on both shapes. It is the running account a person reads
 at the top of this run, and it REPLACES the previous one whole — so write it
@@ -1255,7 +1258,11 @@ and unresolved choices. Never invent physical defaults or replace approved
 texture bytes with new canvas art or regenerated images. Read the retained
 files and distinguish browser export receipts, structural checks and human
 claims. Check decoding/resources and engine import with available local tools;
-label checks not run and why. If a required model, GLB, buffer, original generated
+label checks not run and why. On a same-agent workflow, first read the measured
+intermediate-output paths and producer/card/hash receipts in this prompt; these
+working inputs require no human Download, acceptance or Library retention. Use
+the designated page's own materialized GLB and preserve original texture PNGs.
+If a required model, GLB, buffer, original generated
 PNG or texture mapping is measured missing or unusable, STOP dependent
 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