flowviant 0.125.13 → 0.125.15

package/README.md

@@ -254,7 +254,8 @@ OpenAI, GitHub, AWS, Slack, OAuth token fields, PEM private keys) with
 hostname, a lowercase hex string) is left as it is, and a secret in none of
 those is relayed as printed. What your CLI writes through Flowviant's own tools
 (such as a tab's progress messages and purpose line, or the cards a New task
-chat stages) goes from the CLI to Flowviant, not through the daemon, as written.
+chat stages) is sent to Flowviant as written, either directly or through the
+daemon's root-only capture credential relay.
 The full list, and the exact test for what looks generated, are in
 [SECURITY.md](./SECURITY.md#what-is-redacted).
 

package/bin/cli.mjs

@@ -80,6 +80,11 @@
 // answered here before anything else loads: no config, no update check, no
 // output but the hook's. An unknown hook exits 2, which Claude Code reads as a
 // refusal — the read guard's own rule for a hook that cannot judge.
+if (process.argv[2] === '__capture-mcp') {
+  await (await import('./lib/captureAuthority.mjs')).captureMcpMain();
+  process.exit(process.exitCode ?? 0);
+}
+
 if (process.argv[2] === '__orchestrator-mcp') {
   await (await import('./lib/orchestratorClient.mjs')).orchestratorMcpMain();
   process.exit(process.exitCode ?? 0);

package/bin/lib/captureAuthority.mjs

@@ -0,0 +1,82 @@
+/** A capture credential never enters a delegated CLI or its children. The
+ * daemon relays only calls authorized by the native ROOT's trusted hook.
+ * Tickets bind the tool and complete arguments, and replay returns the same
+ * promise/result rather than performing a second staging write. */
+import { createHash, randomUUID } from 'node:crypto';
+import { fleetHeaders } from './fleetPost.mjs';
+import { callOrchestrator } from './orchestratorClient.mjs';
+import { mcpRequest, serveMcpStdio } from './mcpStdio.mjs';
+import { captureToolName } from './nativeAgentTools.mjs';
+import { DAEMON_INSTANCE } from './config.mjs';
+
+export const CAPTURE_CALL_TICKET = '_flowviantRootCall';
+const CAP = 256;
+const cleanArgs = args => Object.fromEntries(Object.entries(args ?? {}).filter(([key]) => key !== CAPTURE_CALL_TICKET));
+const canonical = value => Array.isArray(value) ? value.map(canonical) : value && typeof value === 'object'
+  ? Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])])) : value;
+const fingerprint = (name, args) => createHash('sha256').update(JSON.stringify([name, canonical(cleanArgs(args))])).digest('hex');
+
+export function createCaptureAuthority({ url, token, turnId, attempt, sessionId, signal, request = fetch, clock = Date.now }) {
+  const tickets = new Map(), calls = new Map();
+  const lifetime = new AbortController();
+  let closed = false, discovery = null;
+  const active = () => !closed && !signal?.aborted;
+  const remote = async (method, params, callId) => {
+    if (!active()) throw new Error('This capture turn stopped.');
+    const response = await request(url, { method: 'POST',
+      headers: { ...fleetHeaders({ token }), 'X-Flowviant-Capture-Turn': turnId,
+        'X-Flowviant-Capture-Attempt': String(attempt), 'X-Flowviant-Capture-Instance': DAEMON_INSTANCE,
+        ...(callId ? { 'X-Flowviant-Capture-Call': callId } : {}) },
+      body: JSON.stringify(mcpRequest(method, params, randomUUID())),
+      signal: AbortSignal.any([lifetime.signal, ...(signal ? [signal] : []), AbortSignal.timeout(30_000)]),
+    });
+    const body = await response.json();
+    if (!response.ok || body.error || !body.result) throw new Error(body.error?.message ?? 'The capture tool did not answer.');
+    if (!active()) throw new Error('This capture turn stopped.');
+    return body.result;
+  };
+  return {
+    async describe() {
+      discovery ??= (async () => {
+        const init = await remote('initialize', { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'flowviant-capture', version: '1' } });
+        const list = await remote('list', {});
+        if (!Array.isArray(list.tools) || list.tools.length > 64) throw new Error('The capture tool list is unavailable.');
+        return { ...init, tools: list.tools.map(tool => ({ ...tool, inputSchema: { ...tool.inputSchema,
+          properties: { ...tool.inputSchema?.properties, [CAPTURE_CALL_TICKET]: { type: 'string', description: 'Internal authorization supplied by the native root hook.' } },
+        } })) };
+      })();
+      return discovery;
+    },
+    authorize(event) {
+      if (!active()) return { deny: 'This capture turn stopped.' };
+      const name = captureToolName(event.tool_name), id = event.tool_use_id;
+      if (!name || typeof id !== 'string' || !id || id.length > 160) return { deny: 'The capture call has no native identity.' };
+      const args = cleanArgs(event.tool_input);
+      if (args.sessionId !== sessionId) return { deny: 'Capture tools belong to this conversation only.' };
+      const hash = fingerprint(name, args), prior = calls.get(id);
+      if (prior && prior.hash !== hash) return { deny: 'This native capture call already authorized different arguments.' };
+      if (!prior && calls.size >= CAP) return { deny: 'This capture turn has reached its tool-call bound. Finish this reply and continue in the next message.' };
+      const ticket = prior?.ticket ?? randomUUID();
+      const grant = prior ?? { ticket, hash, name, args, callId: id, at: clock(), response: null };
+      calls.set(id, grant); tickets.set(ticket, grant);
+      return { updatedInput: { ...args, [CAPTURE_CALL_TICKET]: ticket } };
+    },
+    async call({ name, args = {} }) {
+      if (!active()) throw new Error('This capture turn stopped.');
+      const grant = tickets.get(args[CAPTURE_CALL_TICKET]);
+      if (!grant || grant.hash !== fingerprint(name, args) || clock() - grant.at > 15 * 60_000)
+        throw new Error('Only the capture coordinator may call these tools. No native root authorization was supplied.');
+      grant.response ??= remote('call', { name, arguments: grant.args }, grant.callId);
+      return grant.response;
+    },
+    close() { closed = true; lifetime.abort(); tickets.clear(); calls.clear(); },
+  };
+}
+
+/** The credential-free stdio client. It knows only this attempt's loopback
+ * capability. The shared protocol loop preserves raw MCP errors and replies. */
+export async function captureMcpMain() {
+  const description = await callOrchestrator('capture_describe', {}, 65_000);
+  return serveMcpStdio({ serverInfo: description.serverInfo, tools: description.tools, instructions: description.instructions,
+    rawResult: true, call: (name, args) => callOrchestrator('capture_call', { name, args }, 35_000) });
+}

package/bin/lib/claudePosture.mjs

@@ -499,6 +499,15 @@ export function withNativeChildren(perm) {
   return out;
 }
 
+/** A consult keeps exactly its readers and guard. The only additional MCP
+ * permission is the daemon's local coordination capability, never flowviant's
+ * board/staging tools or a project/personal server. Capture keeps its already
+ * allowed flowviant tools behind the daemon's root-only credential relay. */
+export function withReadOnlyCoordination(perm) {
+  return withNativeChildren(perm).flatMap(arg => arg === '--allowedTools'
+    ? [arg, 'SendMessage', 'TaskStop', 'ToolSearch', 'mcp__card_orchestrator'] : [arg]);
+}
+
 /**
  * CLAUDE'S PERMISSION LIST FOR A TURN PROFILE, by the profile's name — one
  * entry per profile Claude declares, plus plan-mode (runtimeClaude.mjs

package/bin/lib/hooks/orchestrator.mjs

@@ -31,7 +31,7 @@ export async function main() {
     // The names are the controller's own list (nativeAgentTools.mjs).
     // A research card's children only read (FLOWVIANT_ORCHESTRATOR_CHILDREN,
     // orchestrator.mjs): a child's write is refused here too.
-    if (gatedSpawnEvent(event, process.env.FLOWVIANT_ORCHESTRATOR_CHILDREN)) { process.exitCode = 2; return; }
+    if (gatedSpawnEvent(event, process.env.FLOWVIANT_ORCHESTRATOR_CHILDREN, process.env.FLOWVIANT_ORCHESTRATOR_READ_ONLY === '1')) { process.exitCode = 2; return; }
     try { await answer({}); } catch { /* the CLI already stopped reading */ }
   }
 }

package/bin/lib/mcpStdio.mjs

@@ -15,18 +15,26 @@
  */
 import { createInterface } from 'node:readline';
 
+/** The same vocabulary for daemon-side MCP relays, without another protocol
+ * envelope or tools/list spelling in each client. */
+export const mcpRequest = (action, params, id) => ({ jsonrpc: '2.0', id,
+  method: { initialize: 'initialize', list: 'tools/list', call: 'tools/call' }[action], params });
+
 /** `call(name, args)` answers a listed tool; what it resolves is the text result, as JSON. */
-export async function serveMcpStdio({ serverInfo, tools, call, input = process.stdin, write = s => process.stdout.write(s) }) {
+export async function serveMcpStdio({ serverInfo, tools, call, instructions, rawResult = false, input = process.stdin, write = s => process.stdout.write(s) }) {
   for await (const line of createInterface({ input })) {
     let req;
     try {
       req = JSON.parse(line); if (req.id === undefined) continue;
       let result;
-      if (req.method === 'initialize') result = { protocolVersion: req.params?.protocolVersion ?? '2024-11-05', capabilities: { tools: {} }, serverInfo };
+      if (req.method === 'initialize') result = { protocolVersion: req.params?.protocolVersion ?? '2024-11-05', capabilities: { tools: {} }, serverInfo, ...(instructions ? { instructions } : {}) };
       else if (req.method === 'ping') result = {};
       else if (req.method === 'tools/list') result = { tools };
       else if (req.method === 'tools/call' && tools.some(t => t.name === req.params?.name)) {
-        try { result = { content: [{ type: 'text', text: JSON.stringify(await call(req.params.name, req.params.arguments ?? {})) }] }; }
+        try {
+          const answer = await call(req.params.name, req.params.arguments ?? {});
+          result = rawResult ? answer : { content: [{ type: 'text', text: JSON.stringify(answer) }] };
+        }
         catch (error) { result = { isError: true, content: [{ type: 'text', text: error.message }] }; }
       } else { write(`${JSON.stringify({ jsonrpc: '2.0', id: req.id, error: { code: -32601, message: 'Unknown method' } })}\n`); continue; }
       write(`${JSON.stringify({ jsonrpc: '2.0', id: req.id, result })}\n`);

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