flowviant 0.125.0 → 0.125.2

package/bin/lib/codexSubagents.mjs

@@ -0,0 +1,232 @@
+/**
+ * codex exec JSONL omits child steps (and several V2 collab tools). Read only
+ * rollouts named by this turn's native spawn receipts, never a global latest.
+ * rust-v0.160.0: exec_events.rs CollabToolCallItem; core/agent/child_config.rs
+ * reapplies the live turn's approval and permission profile after role config.
+ */
+import { open } from 'node:fs/promises';
+import { codexRolloutFile } from './runtimeLimits.mjs';
+import { codexCollabUpdates, codexSpawnResult, statusOf } from './codexSubagentEvents.mjs';
+
+export const SUBAGENT_LIMIT = 32;
+const READ_BYTES = 256 * 1024;
+const INITIAL_SCAN = 4 * 1024 * 1024;
+const THREAD_ID = /^[a-zA-Z0-9-]{16,64}$/;
+
+export function createCodexSubagentReader({ since = Date.now(), env = process.env, onSubagent, onActivity, onToolEvent, onSpawnResult,
+  findFile = codexRolloutFile } = {}) {
+  const readers = new Map();
+  const calls = new Map();
+  const targets = new Map();
+  const questions = new Map();
+  let root = null;
+  let timer = null;
+  let stopped = false;
+  let chain = Promise.resolve();
+  const report = update => {
+    if (!update?.id || !THREAD_ID.test(update.id)) return;
+    if (!readers.has(update.id) && readers.size >= SUBAGENT_LIMIT + 1) return;
+    if (!readers.has(update.id))
+      readers.set(update.id, { offset: null, rest: Buffer.alloc(0), seen: new Set(), live: false });
+    const { message, ...record } = update;
+    onSubagent?.(record);
+  };
+  const rememberTarget = (path, id) => {
+    targets.set(path, id);
+    if (targets.size > 128) targets.delete(targets.keys().next().value);
+  };
+  const targetId = value => targets.get(value) ?? (THREAD_ID.test(value ?? '') ? value : null);
+
+  function observe(ev, owner) {
+    const at = Date.parse(ev?.timestamp ?? '');
+    if (Number.isFinite(at) && at < since) return;
+    const p = ev?.payload;
+    if (!p || typeof p !== 'object') return;
+    const activity = (kind, text) => {
+      if (typeof text === 'string' && text.trim()) onActivity?.({ kind, label: text.replace(/\s+/g, ' ').slice(0, 160), full: text, agentId: owner });
+    };
+    const step = (id, command) => {
+      const seen = readers.get(owner)?.seen;
+      if (id && seen?.has(id)) return;
+      if (id) { seen?.add(id); if (seen?.size > 400) seen.delete(seen.values().next().value); }
+      onToolEvent?.('Bash', { command }, { agentId: owner, id });
+    };
+    if (ev.type === 'session_meta' && owner !== root) {
+      const src = p.source?.subagent?.thread_spawn ?? p.source?.sub_agent?.thread_spawn;
+      if (src) {
+        const title = src.agent_path ?? src.agent_nickname;
+        if (src.agent_path) rememberTarget(src.agent_path, owner);
+        report({ id: owner, ...(title ? { title } : {}), ...(src.agent_role ? { kind: src.agent_role } : {}) });
+      }
+      return;
+    }
+    if (ev.type === 'response_item' && p.type === 'function_call') {
+      const name = String(p.name ?? '').split('.').at(-1);
+      if (owner !== root && ['exec_command', 'shell_command', 'shell'].includes(name)) {
+        let args; try { args = JSON.parse(p.arguments); } catch { return; }
+        const command = args.cmd ?? args.command;
+        if (command) step(p.call_id, Array.isArray(command) ? command.join(' ') : command);
+        return;
+      }
+      if (owner !== root && name === 'request_user_input') {
+        questions.set(p.call_id, owner);
+        if (questions.size > 128) questions.delete(questions.keys().next().value);
+        report({ id: owner, status: 'asked' }); return;
+      }
+      if (!['spawn_agent', 'send_input', 'send_message', 'followup_task', 'resume_agent', 'close_agent', 'interrupt_agent'].includes(name)) return;
+      let args;
+      try { args = JSON.parse(p.arguments); } catch { return; }
+      calls.set(p.call_id, { name, args });
+      if (calls.size > 128) calls.delete(calls.keys().next().value);
+      const id = targetId(args.target ?? args.id);
+      if (id && name !== 'spawn_agent') {
+        const stopped = name === 'close_agent' || name === 'interrupt_agent';
+        report({ id, ...(stopped ? { status: 'stopped' } : name === 'followup_task' ? { status: 'running' } : {}) });
+      }
+    }
+    if (ev.type === 'response_item' && p.type === 'function_call_output') {
+      if (questions.has(p.call_id)) { report({ id: questions.get(p.call_id), status: 'running' }); questions.delete(p.call_id); }
+      const call = calls.get(p.call_id);
+      if (!['spawn_agent', 'followup_task', 'resume_agent', 'send_input'].includes(call?.name)) return;
+      let output;
+      try {
+        const body = Array.isArray(p.output) ? p.output.map(b => b.text ?? '').join('') : p.output;
+        output = typeof body === 'string' ? JSON.parse(body) : body;
+      } catch { onSpawnResult?.({ callId: p.call_id, success: false }); return; }
+      const id = output?.agent_id ?? output?.thread_id;
+      const receipt = id ?? output?.agent_path ?? (call.name !== 'spawn_agent' && (output?.submission_id || output?.status) ? call.args.target ?? call.args.id : null);
+      onSpawnResult?.({ callId: p.call_id, success: Boolean(receipt), ...(receipt ? { nativeId: receipt } : {}) });
+      if (call.name !== 'spawn_agent') return;
+      if (!id) return;
+      const args = call.args;
+      const title = args.task_name ?? args.description ?? output.agent_nickname ?? '';
+      if (args.task_name) rememberTarget(args.task_name, id);
+      if (output.agent_path) rememberTarget(output.agent_path, id);
+      report({ id, kind: args.agent_type ?? '', title, brief: args.message ?? '', status: 'running', now: '' });
+      return;
+    }
+    if (owner !== root && ev.type === 'response_item' && p.type === 'custom_tool_call') {
+      activity('tool', `${p.name ?? 'tool'}\n${String(p.input ?? '')}`);
+      return;
+    }
+    if (ev.type !== 'event_msg') return;
+    const activityState = item => {
+      const kind = String(item.kind ?? '').toLowerCase();
+      if (item.agent_thread_id) report({ id: item.agent_thread_id, title: item.agent_path,
+        ...(['started', 'completed', 'interrupted'].includes(kind) ? {
+          status: kind === 'completed' ? 'done' : kind === 'interrupted' ? 'stopped' : 'running',
+        } : {}),
+      });
+    };
+    if (p.type === 'sub_agent_activity') activityState(p);
+    if (p.type === 'item_completed') {
+      const item = p.item;
+      if (!item || p.thread_id && p.thread_id !== owner) return;
+      if (item.type === 'CollabAgentToolCall') {
+        const result = codexSpawnResult(item); if (result) onSpawnResult?.(result);
+        for (const update of codexCollabUpdates(item)) report(update);
+      }
+      if (item.type === 'SubAgentActivity') activityState(item);
+      if (owner === root) return;
+      if (item.type === 'AgentMessage') {
+        activity('say', item.content?.filter(b => b.type === 'Text' || b.type === 'text').map(b => b.text).join('\n'));
+        if (item.questions?.length) report({ id: owner, status: 'asked' });
+      }
+      if (item.type === 'Reasoning') activity('think', item.summary_text?.join('\n'));
+      if (item.type === 'CommandExecution') step(item.id, Array.isArray(item.command) ? item.command.join(' ') : item.command);
+      return;
+    }
+    if (p.type === 'collab_agent_spawn_end' && p.new_thread_id) {
+      report({ id: p.new_thread_id, brief: p.prompt ?? '', kind: p.new_agent_role ?? '', title: p.new_agent_nickname ?? '',
+        status: statusOf(typeof p.status === 'object' ? Object.keys(p.status)[0]?.toLowerCase() : p.status) ?? 'running' });
+    }
+    if (owner === root) return;
+    if (p.type === 'agent_message') activity('say', p.message);
+    if (p.type === 'agent_reasoning') activity('think', p.text);
+    if (p.type === 'exec_command_begin') {
+      step(p.call_id, Array.isArray(p.command) ? p.command.join(' ') : p.command);
+    }
+    if (p.type === 'patch_apply_begin') {
+      for (const [path, change] of Object.entries(p.changes ?? {}).slice(0, 40))
+        onToolEvent?.('Write', { file_path: path, content: change?.add?.content ?? '' }, { agentId: owner, id: p.call_id });
+    }
+    if (p.type === 'task_started' || p.type === 'turn_started') report({ id: owner, status: 'running' });
+    if (p.type === 'task_complete' || p.type === 'turn_complete') report({ id: owner, status: 'done', ...(p.last_agent_message ? { now: p.last_agent_message } : {}) });
+    if (p.type === 'turn_aborted') report({ id: owner, status: 'stopped' });
+  }
+
+  async function read(id, state) {
+    let file;
+    let fh;
+    try {
+      file = state.file ?? await findFile(id, { env });
+      if (!file) return;
+      state.file = file;
+      fh = await open(file, 'r');
+      const { size } = await fh.stat();
+      const initial = state.offset === null;
+      const initialEvents = [];
+      if (initial) {
+        state.offset = Math.max(0, size - INITIAL_SCAN);
+        state.skip = state.offset > 0;
+      }
+      if (size < state.offset) { state.offset = 0; state.rest = Buffer.alloc(0); }
+      // Bounded work per poll, including an immediately completed child.
+      const end = Math.min(size, state.offset + INITIAL_SCAN);
+      while (state.offset < end) {
+        const buffer = Buffer.alloc(Math.min(READ_BYTES, end - state.offset));
+        const { bytesRead } = await fh.read(buffer, 0, buffer.length, state.offset);
+        if (!bytesRead) break;
+        state.offset += bytesRead;
+        const data = Buffer.concat([state.rest, buffer.subarray(0, bytesRead)]);
+        let start = 0, nl;
+        while ((nl = data.indexOf(10, start)) >= 0) {
+          const line = data.subarray(start, nl).toString('utf8');
+          start = nl + 1;
+          if (state.skip) { state.skip = false; continue; }
+          try {
+            const ev = JSON.parse(line);
+            if (initial && id !== root) initialEvents.push(ev);
+            else if (id === root || state.live || ev.type === 'session_meta') observe(ev, id);
+            else if (ev.type === 'event_msg' && ['task_started', 'turn_started'].includes(ev.payload?.type)) {
+              state.live = true; observe(ev, id);
+            }
+          } catch { /* non-JSON/unknown native events */ }
+        }
+        // Keep bytes across UTF-8 and partial-line boundaries. Oversized lines
+        // are discarded through their newline rather than reparsed as a suffix.
+        state.rest = data.subarray(start);
+        if (state.rest.length > READ_BYTES) { state.rest = Buffer.alloc(0); state.skip = true; }
+      }
+      if (initial && id !== root) {
+        // A fork copies the parent's old EventMsgs. Only the child's newest
+        // native turn belongs to this card; inherited history is never replayed.
+        for (const ev of initialEvents) if (ev.type === 'session_meta') observe(ev, id);
+        const start = initialEvents.findLastIndex(ev => ev.type === 'event_msg' && ['task_started', 'turn_started'].includes(ev.payload?.type));
+        if (start >= 0) {
+          state.live = true;
+          for (const ev of initialEvents.slice(start)) observe(ev, id);
+        }
+      }
+    } catch { /* a native rollout may not have been created yet */ }
+    finally { await fh?.close().catch(() => {}); }
+  }
+  const flush = () => {
+    chain = chain.then(async () => {
+      for (const [id, state] of readers) await read(id, state);
+    }).catch(() => {});
+    return chain;
+  };
+  return {
+    thread(id) {
+      if (!THREAD_ID.test(id ?? '') || root) return;
+      root = id;
+      readers.set(id, { offset: null, rest: Buffer.alloc(0), seen: new Set(), live: false });
+      if (!stopped) { timer = setInterval(() => void flush(), 1_000); timer.unref?.(); }
+    },
+    update(update) { report(update); },
+    observe,
+    flush,
+    async stop() { stopped = true; clearInterval(timer); await flush(); },
+  };
+}

package/bin/lib/hooks/orchestrator.mjs

@@ -0,0 +1,22 @@
+/** Native gate; a full pool refuses only this spawn, preserving the turn. */
+import { fileURLToPath } from 'node:url';
+import { callOrchestrator } from '../orchestratorClient.mjs';
+
+export async function main() {
+  try {
+    let raw = ''; for await (const chunk of process.stdin) { raw += chunk; if (Buffer.byteLength(raw) > 64 * 1024) throw new Error('Hook input is too large.'); }
+    const event = JSON.parse(raw);
+    const result = await callOrchestrator('hook', event);
+    const output = result.deny ? { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: result.deny } }
+      : result.updatedInput || result.context ? { hookSpecificOutput: { hookEventName: event.hook_event_name,
+        ...(result.updatedInput ? { permissionDecision: 'allow', updatedInput: result.updatedInput } : {}),
+        ...(result.context ? { additionalContext: result.context } : {}) } } : {};
+    process.stdout.write(`${JSON.stringify(output)}\n`);
+  } catch {
+    // Both CLIs interpret exit 2 as a tool refusal. A failed capability must
+    // never let a native spawn escape the shared admission pool.
+    process.stderr.write('The run’s orchestration gate is unavailable. Keep the work in the orchestrator until it reconnects.\n');
+    process.exitCode = 2;
+  }
+}
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main();

package/bin/lib/orchestrator.mjs

@@ -0,0 +1,295 @@
+/** A run-scoped loopback capability. Only this daemon holds fleet credentials;
+ * native tools and MCP clients receive a random capability for this one run. */
+import { createServer } from 'node:http';
+import { randomBytes, randomUUID } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { sameSecret } from './grant.mjs';
+import { fleetRequest } from './fleetPost.mjs';
+import { fleetEndpoint } from './fleetWire.mjs';
+import { DAEMON_INSTANCE, FLEET_URL } from './config.mjs';
+import { runningCompiledBinary } from './launchCommand.mjs';
+import { scrubNativeText } from './runtimeEvents.mjs';
+import { scrub, learnExtraSecrets, forgetExtraSecrets } from './uplinkScrub.mjs';
+
+const WAIT = 'Waiting for a free slot on the machine';
+// Codex 0.160 V2 serializes the namespace without punctuation in hook
+// tool_name (measured: collaborationspawn_agent). V1 spawn has an alias.
+const nativeName = name => String(name ?? '').split(/[./]/).at(-1).replace(/^(collaboration|multi_agent_v1)(?=spawn_agent|followup_task|resume_agent|send_input|interrupt_agent|close_agent)/, '');
+const spawnTool = name => ['Agent', 'Task', 'spawn_agent'].includes(nativeName(name));
+const resumeTool = name => ['followup_task', 'resume_agent', 'send_input'].includes(nativeName(name));
+const terminal = status => ['done', 'stopped'].includes(status);
+const text = (s, n) => scrubNativeText(s, n, scrub);
+
+
+
+export async function createOrchestrator({ turnId, runtime, trace, admit, request = fleetRequest, notify = () => {}, taken = () => {},
+  interval = 500, scrubText = text } = {}) {
+  if (typeof admit !== 'function' || typeof admit.reserve !== 'function') throw new Error('This run has no project admission pool.');
+  const capability = randomBytes(32).toString('hex');
+  const secretKey = `orchestrator:${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(), inbox = new Map(), questions = new Map();
+  const pending = new Map(), steps = new Map();
+  let closed = false, polling = false, rootSession = null;
+  const identity = { scope: 'agent', turnId, instance: DAEMON_INSTANCE };
+  const resolve = id => aliases.get(id) ?? id;
+  const emit = update => {
+    const id = resolve(update.id), prior = records.get(id) ?? { id };
+    const reading = { ...prior, ...update, id };
+    if (reading.namedKind) reading.kind = reading.namedKind;
+    if (reading.namedTitle) reading.title = reading.namedTitle;
+    records.set(id, reading); trace.agent(reading); return reading;
+  };
+  const release = id => { const a = records.get(resolve(id)); a?.release?.(); if (a) a.release = null; };
+  const announce = message => { if (!closed) {
+    inbox.set(randomUUID(), message); if (inbox.size > 64) inbox.delete(inbox.keys().next().value);
+    notify(message);
+  } };
+  const route = async args => {
+    const note = notes.get(args.messageId);
+    if (!note) throw new Error('That note is not held by this run.');
+    if (!['queued', 'handed', 'taken'].includes(args.state)) throw new Error('Choose queued, handed or taken.');
+    const id = args.agentId ? resolve(args.agentId) : undefined;
+    const a = id ? records.get(id) : null;
+    if (args.state !== 'taken' && (!a || !args.safePoint || !args.kind)) throw new Error('Name the agent, its kind and this note’s safe point.');
+    if (args.state === 'handed' && a?.status === 'waiting') throw new Error('The agent has not started yet. Keep this note queued.');
+    // Flush the descriptor before the holder-bound route write validates it.
+    await trace.flush(1_000);
+    const next = { state: args.state, runtime, ...(id ? { agentId: trace.agentId(id), nativeAgentId: scrubText(a.nativeId ?? id, 160), kind: scrubText(args.kind, 80), safePoint: scrubText(args.safePoint, 200) } : {}) };
+    const result = await request(fleetEndpoint('agent-message-route', FLEET_URL), { body: { ...identity, messageId: args.messageId, route: next }, timeoutMs: 10_000 });
+    if (!result.ok || !result.json?.data?.reported) throw new Error('The route was not recorded. Re-read the note and retry.');
+    Object.assign(note, args, { agentId: id });
+    taken(args.messageId); // the model naming the UUID proves receipt
+    // The API stores the handoff atomically with the route; a crash between
+    // this receipt and a trace flush must not lose or duplicate that item.
+    return { recorded: true };
+  };
+  function slot(id) {
+    const a = records.get(id);
+    if (a.release) return true;
+    if (admit('churn')) return false;
+    a.release = admit.reserve();
+    return true;
+  }
+  const match = input => [...records.values()].find(a => a.brief === (input.prompt ?? input.message ?? '') && a.status === 'waiting');
+  function preSpawn(event) {
+    const input = event.tool_input ?? {}, callId = event.tool_use_id;
+    if (!callId || typeof (input.prompt ?? input.message) !== 'string') throw new Error('A native spawn needs its call id and prompt.');
+    const waiting = match(input);
+    const resumed = input.resume && records.has(resolve(input.resume)) ? resolve(input.resume) : null;
+    const id = resumed ?? waiting?.id ?? resolve(callId);
+    aliases.set(callId, id); calls.set(callId, id);
+    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 >= 32) return { deny: 'This run already has 32 agent records. Continue the work yourself.' };
+    const a = emit({ id, brief: input.prompt ?? input.message, title: input.description ?? input.task_name ?? '',
+      kind: input.subagent_type ?? input.agent_type ?? '', status: 'waiting', now: WAIT });
+    if (!slot(id)) 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.` };
+    a.started = true;
+    a.checkpointSaid = false;
+    emit({ id, status: 'running', now: a.title });
+    const promptKey = typeof input.prompt === 'string' ? 'prompt' : 'message';
+    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. Return your work to it; it owns the card’s final commit and JSON.`;
+    return { context: `Agent record id: ${id}. Use it with card_orchestrator for routing and questions.`,
+      updatedInput: { ...input, ...(['Agent', 'Task'].includes(nativeName(event.tool_name)) ? { run_in_background: true } : {}), [promptKey]: input[promptKey] + childContract } };
+  }
+  const bind = (native, id) => {
+    if (typeof native !== 'string' || native.length > 160 || !id) return;
+    const target = resolve(id); aliases.set(native, target);
+    if (records.has(target)) records.get(target).nativeId = native;
+    if (pending.has(native)) {
+      const update = pending.get(native);
+      if (terminal(update.status)) release(target);
+      emit({ ...update, id: target }); pending.delete(native);
+    }
+    for (const step of steps.get(native) ?? []) step(target);
+    steps.delete(native);
+    if (aliases.size > 256) aliases.delete(aliases.keys().next().value);
+  };
+  function postSpawn(event) {
+    const id = calls.get(event.tool_use_id);
+    if (!id) return;
+    let output = event.tool_response;
+    try { if (typeof output === 'string') output = JSON.parse(output); } catch { /* native plain output */ }
+    if (Array.isArray(output)) output = output.map(b => b.text ?? '').join('');
+    try { if (typeof output === 'string') output = JSON.parse(output); } catch { /* native prose */ }
+    bind(output?.agent_id ?? output?.agentId ?? output?.thread_id ?? output?.agent_path, id);
+    for (const block of output?.content ?? []) {
+      if (typeof block.text !== 'string') continue;
+      try { const parsed = JSON.parse(block.text); bind(parsed.agent_id ?? parsed.thread_id ?? parsed.agent_path, id); } catch { /* prose */ }
+    }
+    if (output?.is_error || output?.isError || event.error) { release(id); emit({ id, status: 'stopped' }); }
+  }
+  function preResume(event) {
+    const input = event.tool_input ?? {};
+    const native = input.target ?? input.id;
+    if (typeof native !== 'string' || native.length > 160) return { deny: 'Name the native agent to resume.' };
+    const id = resolve(native);
+    if (!records.has(id)) {
+      if (records.size >= 32) return { deny: 'Continue the work in this run’s orchestrator.' };
+      emit({ id, kind: '', title: native, brief: input.message ?? '', status: 'waiting', now: WAIT });
+    }
+    if (!slot(id)) { emit({ id, status: 'waiting', now: WAIT }); return { deny: `${WAIT}. Retry the native follow-up when notified. Agent id: ${id}` }; }
+    records.get(id).started = true; records.get(id).checkpointSaid = false;
+    emit({ id, status: 'running', now: 'Continuing with the orchestrator’s note' });
+    calls.set(event.tool_use_id, id);
+    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.` } } : {};
+  }
+  function checkpoint(event) {
+    const id = resolve(event.agent_id ?? event.session_id);
+    if (!records.has(id)) return {};
+    const queued = [...notes.values()].filter(n => n.state === 'queued' && n.agentId === id);
+    if (!queued.length) return {};
+    // The orchestrator, not this hook, chose each checkpoint. Pause tool
+    // execution at its next boundary and ask the parent to use native stop /
+    // follow-up. The child keeps its worktree and transcript intact.
+    const edits = queued.filter(n => n.safePoint === 'after its current edit');
+    if (!edits.length) return {};
+    if (records.get(id).checkpointSaid) return { deny: 'Remain at the checkpoint until your orchestrator sends the follow-up.' };
+    records.get(id).checkpointSaid = true;
+    emit({ id, status: 'waiting', now: 'At the checkpoint for a message' });
+    announce(`Agent ${id} is between tools. Stop it with the native tool and resume/follow up with note ${edits.map(n => n.messageId).join(' ')} plus its work so far. Then report handed.`);
+    return { deny: 'Your orchestrator has a note for this checkpoint. Stop editing and wait for its follow-up; keep your work so far.' };
+  }
+  async function handle(action, args) {
+    if (closed) throw new Error('This run stopped.');
+    if (action === 'hook') {
+      const ev = args;
+      if (ev.hook_event_name === 'SubagentStop') { const id = resolve(ev.agent_id ?? ev.session_id); release(id); if (records.has(id)) emit({ id, status: questions.has(id) && !questions.get(id).answer ? 'asked' : 'done' }); }
+      if (ev.hook_event_name === 'PostToolUseFailure' && (spawnTool(ev.tool_name) || resumeTool(ev.tool_name))) {
+        const id = calls.get(ev.tool_use_id); if (id && records.get(id)?.started) { release(id); emit({ id, status: 'stopped', now: 'The native spawn did not start' }); }
+      }
+      if (ev.hook_event_name === 'PreToolUse') {
+        if (String(ev.tool_name).includes('card_orchestrator') && String(ev.tool_name).endsWith('register_agent')) {
+          const id = resolve(ev.tool_input?.agentId);
+          if (!records.has(id)) return { deny: 'Use the agent record id in your prompt.' };
+          bind(ev.agent_id ?? ev.session_id, id);
+        }
+        const child = ev.agent_id ?? (rootSession && ev.session_id !== rootSession ? ev.session_id : null);
+        if (child && !records.has(resolve(child)) && !['tool_search', 'search_tool'].includes(nativeName(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 (spawnTool(ev.tool_name)) return preSpawn(ev);
+        if (resumeTool(ev.tool_name)) return preResume(ev);
+        const point = checkpoint(ev); if (point.deny) return point;
+        if (['AskUserQuestion', 'request_user_input'].includes(nativeName(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.' };
+      }
+      if (ev.hook_event_name === 'PostToolUse' && (spawnTool(ev.tool_name) || resumeTool(ev.tool_name))) postSpawn(ev);
+      if (runtime === 'codex' && !ev.agent_id && rootSession && ev.session_id === rootSession) {
+        const context = [...inbox.entries()].slice(0, 4); for (const [id] of context) inbox.delete(id);
+        return { context: context.map(([, body]) => body).join('\n\n') };
+      }
+      return {};
+    }
+    if (action === 'route_message') return route(args);
+    const id = resolve(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.
+    if (action === 'answer_agent' && !records.has(id) && typeof id === 'string' && id.length > 0 && id.length <= 160 && records.size < 32 &&
+      typeof args.question === 'string' && args.question.trim() && args.question.length <= 4_000) {
+      emit({ id, kind: scrubText(args.kind ?? '', 80), title: scrubText(args.title ?? '', 200), brief: '', status: 'asked', now: args.question });
+      questions.set(id, { question: args.question });
+      if (args.nativeAgentId) bind(args.nativeAgentId, id);
+    }
+    const a = records.get(id);
+    if (!a) throw new Error('Name an agent in this run.');
+    if (action === 'register_agent') return { registered: true, agentId: id };
+    if (action === 'describe_agent') {
+      if (typeof args.kind !== 'string' || !args.kind.trim() || args.kind.length > 80 || typeof args.title !== 'string' || !args.title.trim() || args.title.length > 200) throw new Error('Give this agent a bounded kind and title.');
+      emit({ id, kind: args.kind, title: args.title, namedKind: args.kind, namedTitle: args.title });
+      return { recorded: true };
+    }
+    if (action === 'agent_question') {
+      let q = questions.get(id);
+      if (!q || q.question !== args.question) {
+        if (typeof args.question !== 'string' || args.question.length > 4_000) throw new Error('Keep the question within 4000 characters.');
+        q = { question: args.question }; questions.set(id, q); emit({ id, status: 'asked', now: args.question });
+        trace.prose('note', args.question, id);
+        announce(`${a.kind || a.title || id} asks: ${args.question}\nAnswer with answer_agent from the card, code and earlier notes if possible. Escalate only a real person-only decision.`);
+      }
+      return q.answer ? { answer: q.answer } : { waiting: true, escalated: q.escalated === true };
+    }
+    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: '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.' };
+    }
+    throw new Error('Unknown orchestration action.');
+  }
+  const server = createServer(async (req, res) => {
+    if (closed || req.method !== 'POST' || req.url !== '/' || !sameSecret(req.headers.authorization, `Bearer ${capability}`)) { res.writeHead(403).end(); return; }
+    try {
+      let raw = ''; for await (const chunk of req) { raw += chunk; if (Buffer.byteLength(raw) > 64 * 1024) throw new Error('Orchestration input is too large.'); }
+      const { action, args } = JSON.parse(raw);
+      const result = await handle(action, args ?? {});
+      res.writeHead(200, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' }).end(JSON.stringify(result));
+    } catch (error) { res.writeHead(409, { 'Content-Type': 'application/json' }).end(JSON.stringify({ error: text(error.message, 300) })); }
+  });
+  server.requestTimeout = 5_000;
+  await new Promise((resolve, reject) => { server.once('error', reject); server.listen(0, '127.0.0.1', resolve); });
+  const env = { FLOWVIANT_ORCHESTRATOR_URL: `http://127.0.0.1:${server.address().port}/`, FLOWVIANT_ORCHESTRATOR_CAPABILITY: capability };
+  const argv = runningCompiledBinary() ? ['__orchestrator-mcp'] : [fileURLToPath(new URL('../cli.mjs', import.meta.url)), '__orchestrator-mcp'];
+  const timer = setInterval(() => {
+    if (closed || polling) return;
+    polling = true;
+    try {
+      for (const a of records.values()) if (a.status === 'waiting' && !a.started && !a.release && slot(a.id)) {
+        emit({ id: a.id, status: 'waiting', now: 'Ready to start' });
+        announce(`A slot is available for agent ${a.id}. Retry its native spawn with the same prompt now; its slot is reserved. If it is no longer needed, finish the run yourself.`);
+      }
+    } finally { polling = false; }
+  }, interval);
+  timer.unref?.();
+  return { env, config: { command: process.execPath, args: argv, env }, handle,
+    root(id) { if (typeof id === 'string') rootSession = id; },
+    resolve,
+    spawnResult(result) {
+      const id = calls.get(result.callId);
+      if (!id) return;
+      if (result.success) { if (result.nativeId) bind(result.nativeId, id); }
+      else if (records.get(id)?.started) { release(id); emit({ id, status: 'stopped', now: 'The native spawn did not start' }); }
+    },
+    attributed(native, step) {
+      const id = resolve(native);
+      if (records.has(id)) { step(id); return; }
+      if (!steps.has(native) && steps.size >= 32) return;
+      const queue = steps.get(native) ?? []; queue.push(step); if (queue.length > 40) queue.shift(); steps.set(native, queue);
+    },
+    note(message) { if (!notes.has(message.id) && notes.size < 64) notes.set(message.id, { ...message, messageId: message.id,
+      state: message.route?.state ?? 'deciding', ...(message.route?.nativeAgentId ? { agentId: resolve(message.route.nativeAgentId), safePoint: message.route.safePoint } : {}) }); },
+    outstanding() { return [...notes.values()].filter(n => ['deciding', 'queued'].includes(n.state)).map(n => ({ id: n.messageId, state: n.state, body: n.body, agentId: n.agentId, 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 (update.nativeId) bind(update.nativeId, update.id);
+      if (update.callId && calls.has(update.callId)) bind(update.id, calls.get(update.callId));
+      let id = resolve(update.id);
+      if (!records.has(id)) {
+        // Bind from a native receipt, never a guessed match on title/kind.
+        if (pending.size < 128 || pending.has(id)) pending.set(id, { ...pending.get(id), ...update });
+        return;
+      }
+      const a = records.get(id);
+      if (a?.status === 'waiting' && !a.started) {
+        const { status: _status, now: _now, ...metadata } = update;
+        emit({ ...metadata, id }); return;
+      }
+      const finished = terminal(update.status);
+      if (finished) release(id);
+      if (questions.has(id) && !questions.get(id).answer) update = { ...update, status: 'asked' };
+      emit({ ...update, id });
+      if (finished) for (const note of notes.values()) if (note.state === 'queued' && note.agentId === id)
+        announce(`Agent ${id} finished. Deliver note ${note.messageId} in its next task or a native follow-up and report handed at that checkpoint.`);
+    },
+    async close(stopped = false) {
+      closed = true; clearInterval(timer);
+      for (const a of records.values()) { release(a.id); if (!terminal(a.status) && !(a.status === 'asked' && !stopped)) 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

@@ -0,0 +1,30 @@
+import { createInterface } from 'node:readline';
+import { ORCHESTRATOR_TOOLS } from './orchestratorProtocol.mjs';
+
+export async function callOrchestrator(action, args) {
+  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 response = await fetch(url, { method: 'POST', headers: { Authorization: `Bearer ${process.env.FLOWVIANT_ORCHESTRATOR_CAPABILITY}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify({ action, args }), signal: AbortSignal.timeout(15_000) });
+  const result = await response.json();
+  if (!response.ok) throw new Error(result.error ?? 'This run is no longer held.');
+  return result;
+}
+
+export async function orchestratorMcpMain() {
+  for await (const line of createInterface({ input: process.stdin })) {
+    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: { name: 'card-orchestrator', version: '2' } };
+      else if (req.method === 'ping') result = {};
+      else if (req.method === 'tools/list') result = { tools: ORCHESTRATOR_TOOLS };
+      else if (req.method === 'tools/call' && ORCHESTRATOR_TOOLS.some(t => t.name === req.params?.name)) {
+        try { result = { content: [{ type: 'text', text: JSON.stringify(await callOrchestrator(req.params.name, req.params.arguments ?? {})) }] }; }
+        catch (error) { result = { isError: true, content: [{ type: 'text', text: error.message }] }; }
+      } else { process.stdout.write(`${JSON.stringify({ jsonrpc: '2.0', id: req.id, error: { code: -32601, message: 'Unknown method' } })}\n`); continue; }
+      process.stdout.write(`${JSON.stringify({ jsonrpc: '2.0', id: req.id, result })}\n`);
+    } catch { if (req?.id !== undefined) process.stdout.write(`${JSON.stringify({ jsonrpc: '2.0', id: req.id, error: { code: -32602, message: 'Invalid request' } })}\n`); }
+  }
+}

package/bin/lib/orchestratorHooks.mjs

@@ -0,0 +1,15 @@
+import { fileURLToPath } from 'node:url';
+import { hookCommand } from './claudePosture.mjs';
+
+const command = () => hookCommand('orchestrator', fileURLToPath(new URL('./hooks/orchestrator.mjs', import.meta.url)));
+export function orchestratorHooks() {
+  const hooks = [{ type: 'command', command: command(), timeout: 20 }];
+  return { PreToolUse: [{ matcher: '.*', hooks }], PostToolUse: [{ matcher: '.*', hooks }], PostToolUseFailure: [{ matcher: '.*', hooks }], SubagentStop: [{ hooks }] };
+}
+
+export function codexOrchestratorArgs() {
+  const quote = s => JSON.stringify(String(s));
+  const row = `{matcher=".*",hooks=[{type="command",command=${quote(command())},timeout=20}]}`;
+  return ['--dangerously-bypass-hook-trust', '-c', 'features.hooks=true',
+    '-c', `hooks.PreToolUse=[${row}]`, '-c', `hooks.PostToolUse=[${row}]`, '-c', `hooks.SubagentStop=[${row}]`];
+}

package/bin/lib/orchestratorPrompt.mjs

@@ -0,0 +1,19 @@
+export const ORCHESTRATOR_CONTRACT = `CARD ORCHESTRATOR — this applies to this card's one CLI and worktree.
+You are the model the person chose and remain responsible for the card and its final JSON.
+Work yourself when the card spans one area. Only split work spanning several areas into native in-process subagents by kind (Backend/UI/Tests…). This is authorization to use those native agents on this card. Give each a concrete title, prompt and kind, and post short updates of your own. Do not create extra branches or Flowviant agents. Use a native agent type that can call card_orchestrator MCP (Claude general-purpose); keep the work yourself if none can. After spawning, use describe_agent to report the kind and title you chose when its native role is generic.
+
+The daemon gates every native spawn against this project's Turns at once pool, shared with its other turns. Claude children run in the background so you remain available for messages and their questions; Codex spawns are already asynchronous. A refused spawn with a waiting id has not started. Keep working yourself; do not wait for it. When notified of a free slot, retry its native spawn with the same prompt. Never bypass this gate with another CLI process. The orchestrator itself also holds a slot. If no slot becomes available, finish the work yourself.
+
+The card_orchestrator MCP tools report routing and child questions. A live person’s note has a Message id. Report each note using route_message:
+- Handle it yourself: taken.
+- Delegate it: queued, with the native agent id, its kind, and the safePoint chosen FOR THIS NOTE: "when it finishes", "after its current edit", or a precise stated checkpoint.
+- When it finishes: wait for that child's completion, then put the note in its next native task/follow-up.
+- After its current edit: the gate pauses further tool use at the next boundary. Use the native stop/interrupt tool, preserve its work so far, and resume it or start a follow-up with that context and the note. Do not interrupt in the middle of an edit.
+- Only after native delivery at that checkpoint: handed with that agent id/kind/safePoint. This appends "From {orchestrator} …" to its stream. Never report a handoff before doing it.
+Use the tools' agent record id when one is supplied by a native spawn gate. Keep a later native id with that record.
+
+All child prompts must say: share this worktree, preserve others' edits, return questions to the orchestrator with agent_question, read its answer before continuing, never escalate directly to the person, and do not commit independently of the card's orchestrator. Answer child questions from the card, code and earlier notes with answer_agent when possible. If only the person can decide, mark escalate with answer_agent, then use the existing blocked JSON question card naming the asking child. Leave that child asked until answered. When the person answers in a resumed run, call answer_agent with the earlier agentId, nativeAgentId, kind/title and question from your conversation plus their answer; then give it to that same child through a native follow-up. Never guess a missing identity.
+
+Urgent is the person's explicit exception. The daemon uses the whole-turn interrupt/resume fallback when a child cannot be targeted reliably; the same stored note becomes the resumed prompt and reads "interrupted the run". Stop ends the whole run. Do not keep working or hand off notes after Stop.
+
+Claude receives notes through its native live stdin. Codex exec cannot accept stdin mid-turn: on supported code-card CLIs, the daemon injects pending notes through the next native tool hook boundary in the same turn. During a tool-free answer or on fenced/older Codex turns, the note remains for the next run; do not claim it was already read. No new model is involved.`;

package/bin/lib/orchestratorProtocol.mjs

@@ -0,0 +1,15 @@
+/** The run-scoped MCP vocabulary; safe to load in a credential-free client. */
+export const ORCHESTRATOR_TOOLS = [
+  { name: 'register_agent', description: 'A native child calls this first with the agent record id in its prompt, before working. It binds native events to that record.',
+    inputSchema: { type: 'object', properties: { agentId: { type: 'string' } }, required: ['agentId'], additionalProperties: false } },
+  { name: 'describe_agent', description: 'The orchestrator reports the kind and title it chose for a child when the native role is generic. Use Backend, UI, Tests or the actual area of work.',
+    inputSchema: { type: 'object', properties: { agentId: { type: 'string' }, kind: { type: 'string' }, title: { type: 'string' } }, required: ['agentId', 'kind', 'title'], additionalProperties: false } },
+  { name: 'route_message', description: 'Report where you routed a person’s live note. Choose its safe point per note. Report handed only after native delivery at that checkpoint; taken means you handled it yourself.',
+    inputSchema: { type: 'object', properties: { messageId: { type: 'string' }, state: { enum: ['queued', 'handed', 'taken'] },
+      agentId: { type: 'string' }, kind: { type: 'string' }, safePoint: { type: 'string' } }, required: ['messageId', 'state'], additionalProperties: false } },
+  { name: 'agent_question', description: 'A child asks its orchestrator before asking the person. Call again to read an answer. The orchestrator answers from the card/code/earlier notes or escalates a real person-only decision.',
+    inputSchema: { type: 'object', properties: { agentId: { type: 'string' }, question: { type: 'string' } }, required: ['agentId', 'question'], additionalProperties: false } },
+  { name: 'answer_agent', description: 'Answer a child question from known facts, or mark it for escalation to the person. An escalation returns the attribution to put on the existing blocked question card.',
+    inputSchema: { type: 'object', properties: { agentId: { type: 'string' }, answer: { type: 'string' }, escalate: { type: 'boolean' },
+      question: { type: 'string' }, nativeAgentId: { type: 'string' }, kind: { type: 'string' }, title: { type: 'string' } }, required: ['agentId'], additionalProperties: false } },
+];