flowviant 0.125.1 → 0.125.3

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,28 @@
+/** Native gate; a full pool refuses only this spawn, preserving the turn. */
+import { fileURLToPath } from 'node:url';
+import { callOrchestrator } from '../orchestratorClient.mjs';
+import { OrchestratorInputTooLarge, readOrchestratorInput } from '../orchestratorInput.mjs';
+import { runningCompiledBinary } from '../launchCommand.mjs';
+
+export async function main() {
+  try {
+    const event = await readOrchestratorInput(process.stdin);
+    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 } : {}) } } : {};
+    // __hook exits as soon as main returns. A large rewritten child prompt
+    // must reach the pipe before that exit, not stop partway through JSON.
+    await new Promise((resolve, reject) => process.stdout.write(`${JSON.stringify(output)}\n`, error => error ? reject(error) : resolve()));
+  } catch (error) {
+    // 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(error instanceof OrchestratorInputTooLarge ? `${error.message}\n`
+      : 'The run’s orchestration gate is unavailable. Keep the work in the orchestrator until it reconnects.\n');
+    process.exitCode = 2;
+  }
+}
+// Bun bundles this module at the virtual entrypoint too. Only cli.mjs may
+// dispatch it there; otherwise importing it consumes stdin before dispatch.
+if (!runningCompiledBinary() && process.argv[1] === fileURLToPath(import.meta.url)) await main();

package/bin/lib/orchestrator.mjs

@@ -0,0 +1,298 @@
+/** 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';
+import { OrchestratorInputTooLarge, readOrchestratorInput } from './orchestratorInput.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 {
+      const { action, args } = await readOrchestratorInput(req);
+      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(error instanceof OrchestratorInputTooLarge ? 413 : 409,
+      { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' }).end(JSON.stringify({
+        error: text(error.message, 300), ...(error instanceof OrchestratorInputTooLarge ? { code: error.code } : {}),
+      })); }
+  });
+  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,34 @@
+import { createInterface } from 'node:readline';
+import { ORCHESTRATOR_TOOLS } from './orchestratorProtocol.mjs';
+import { ORCHESTRATOR_REQUEST_BYTES, ORCHESTRATOR_INPUT_TOO_LARGE, OrchestratorInputTooLarge } from './orchestratorInput.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 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(15_000) });
+  const result = await response.json();
+  if (result.code === ORCHESTRATOR_INPUT_TOO_LARGE) throw new OrchestratorInputTooLarge();
+  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}]`];
+}