flowviant 0.125.7 → 0.125.12

package/bin/lib/observedLines.mjs

@@ -0,0 +1,63 @@
+/** Complete pipe lines, with the time their first chunk was observed.
+ * Pending text stays below 64 Ki characters in memory. Large protocol/error
+ * lines spill to an anonymous private file, so neither a long JSON event nor
+ * an unterminated stderr line needs truncation or invented line breaks.
+ * The file is unlinked immediately: close, crash and kill leave no log behind.
+ */
+import { closeSync, mkdtempSync, openSync, readFileSync, rmdirSync, unlinkSync, writeSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+export const PARTIAL_LINE_CHARS = 64 * 1024;
+
+export function createObservedLines(onLine, { now = Date.now } = {}) {
+  let parts = [], size = 0, observedAt = null, fd = null, offset = 0;
+  const clear = () => {
+    if (fd !== null) closeSync(fd);
+    parts = []; size = 0; observedAt = null; fd = null; offset = 0;
+  };
+  const write = (text) => {
+    const bytes = Buffer.from(text);
+    let written = 0;
+    while (written < bytes.length)
+      written += writeSync(fd, bytes, written, bytes.length - written, offset + written);
+    offset += written;
+  };
+  const append = (text) => {
+    if (!text) return;
+    if (observedAt === null) observedAt = now();
+    if (fd === null && size + text.length > PARTIAL_LINE_CHARS) {
+      const dir = mkdtempSync(join(tmpdir(), 'flowviant-line-'));
+      const path = join(dir, 'partial');
+      try { fd = openSync(path, 'wx+', 0o600); }
+      finally {
+        try { unlinkSync(path); } finally { rmdirSync(dir); }
+      }
+      for (const part of parts) write(part);
+      parts = [];
+    }
+    if (fd === null) parts.push(text);
+    else write(text);
+    size += text.length;
+  };
+  const flush = () => {
+    const at = observedAt ?? now();
+    try {
+      // Positioned writes leave the descriptor's read position at zero.
+      onLine(fd === null ? parts.join('') : readFileSync(fd, 'utf8'), at);
+    } finally { clear(); }
+  };
+  return {
+    push(text) {
+      let start = 0, nl;
+      while ((nl = text.indexOf('\n', start)) >= 0) {
+        append(text.slice(start, nl));
+        flush();
+        start = nl + 1;
+      }
+      append(text.slice(start));
+    },
+    end() { if (size) flush(); },
+    discard: clear,
+  };
+}

package/bin/lib/orchestrator.mjs

@@ -1,6 +1,7 @@
 /** 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 { randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
 import { fleetRequest } from './fleetPost.mjs';
 import { fleetEndpoint } from './fleetWire.mjs';
 import { DAEMON_INSTANCE, FLEET_URL } from './config.mjs';
@@ -10,11 +11,14 @@ 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 { isClaudeStopTool, isDiscoveryTool, isFollowupTool, isPersonQuestionTool, isSpawnTool } from './nativeAgentTools.mjs';
-import { followupTarget, readSpawn, spawnReceipt, withChildContract } from './orchestratorNative.mjs';
+import { 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';
 
 const WAIT = 'Waiting for a free slot on the machine';
+// A research card's children read inside its fence; the orchestrator alone writes and delivers.
+const READ_ONLY_CHILD = ' This is a research card: you only read. Write no file, edit nothing and commit nothing; return your findings, their sources and what you could not verify.';
+const READ_ONLY_REFUSAL = 'This research card’s children only read: no file writes. Return your findings to the orchestrator, which alone writes and delivers the card.';
 const HELD = 'At the checkpoint for a message';
 const terminal = status => SETTLED_SUBAGENT_STATUSES.includes(status);
 const filled = s => typeof s === 'string' && s.trim().length > 0;
@@ -22,8 +26,23 @@ const filled = s => typeof s === 'string' && s.trim().length > 0;
 const pointOf = s => String(s ?? '').trim().toLowerCase().replace(/\s+/g, ' ').replace(/^["'“‘`]+|["'”’`.!?;:,…]+$/g, '');
 const text = (s, n) => scrubNativeText(s, n, scrub);
 
+/**
+ * `children` is what this run's children may do and run at (2026-10-19):
+ * `access` 'edit' on a code card, 'read' on a research card (the gate refuses
+ * a child's write, and the hook does too while this controller is down), and
+ * the card's `model` and `effort` as the parent runs them, which a spawn that
+ * names neither inherits explicitly (orchestratorNative.mjs `childBrain`);
+ * 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 } = {}) {
+  interval = 500, hold = 60_000, clock = Date.now, scrubText = text, children = {} } = {}) {
+  const access = 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'
+    ? (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();
@@ -111,6 +130,9 @@ export async function createOrchestrator({ turnId, runtime, trace, admit, reques
     const spawn = readSpawn(event);
     if (!spawn) return { deny: 'Give this native spawn a text prompt or message so the run can gate it.' };
     const { callId, brief } = spawn;
+    // Above the card's model or effort is refused before any record or slot.
+    const chosen = childBrain(event, spawn, card);
+    if (chosen.deny) return { deny: chosen.deny };
     const resumed = spawn.resume !== null && records.has(resolve(spawn.resume)) ? resolve(spawn.resume) : null;
     const id = resumed ?? claim(spawn)?.id ?? resolve(callId);
     aliases.set(callId, id); calls.set(callId, id);
@@ -122,9 +144,13 @@ export async function createOrchestrator({ turnId, runtime, trace, admit, reques
     // Claude's SendMessage addresses a child by its Agent `name`, Codex V2 by its task name.
     for (const name of spawn.names) if (filled(name) && name.length <= 160) aliases.set(name, id);
     start(a, a.title);
-    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.${spawn.relocated ? ' Its isolation and cwd were removed: children share this card’s worktree on this machine.' : ''}`,
-      updatedInput: withChildContract(event, spawn, childContract) };
+    // A cheaper model or lower effort than the card's is relayed on the child's
+    // 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.`;
+    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) };
   }
   // 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
@@ -245,9 +271,14 @@ 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 (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)) {
+        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.' };
     }
@@ -319,8 +350,10 @@ export async function createOrchestrator({ turnId, runtime, trace, admit, reques
         error: text(error.message, 300), ...(error instanceof OrchestratorInputTooLarge ? { code: error.code } : {}),
       })); }
   };
-  const { server, env, args: argv } = await listenHeldTool({ envPrefix: 'FLOWVIANT_ORCHESTRATOR', verb: '__orchestrator-mcp', requestTimeoutMs: 5_000,
+  const { server, env: heldEnv, args: argv } = await listenHeldTool({ envPrefix: 'FLOWVIANT_ORCHESTRATOR', verb: '__orchestrator-mcp', requestTimeoutMs: 5_000,
     capability, isClosed: () => closed, respond });
+  // The hook reads it to refuse a research child's write while this is down.
+  const env = { ...heldEnv, FLOWVIANT_ORCHESTRATOR_CHILDREN: access };
   const timer = setInterval(() => {
     if (closed || polling) return;
     polling = true;

package/bin/lib/orchestratorNative.mjs

@@ -10,7 +10,7 @@
  * Words the model reads stay in orchestrator.mjs, and so do its refusals:
  * these return fields, or null.
  */
-import { isBackgroundSpawnTool, isClaudeFollowupTool } from './nativeAgentTools.mjs';
+import { isBackgroundSpawnTool, isClaudeFollowupTool, isSpawnTool } from './nativeAgentTools.mjs';
 
 /** A spawn's prompt and the fields a waiting record is matched and named by,
  * or null when the gate cannot hold it (no call id or no text prompt). */
@@ -29,10 +29,140 @@ export function readSpawn(event) {
 }
 
 /** The spawn's input as the gate rewrites it: the contract appended to its
- * prompt, and a Claude child sent to the background. */
-export const withChildContract = (event, spawn, contract) => ({ ...spawn.input, ...(isBackgroundSpawnTool(event.tool_name) ? { run_in_background: true } : {}),
+ * prompt, a Claude child sent to the background, and the child's model and
+ * effort (`brain`, from `childBrain`) where the spawn named none. */
+export const withChildContract = (event, spawn, contract, brain = {}) => ({ ...spawn.input, ...brain, ...(isBackgroundSpawnTool(event.tool_name) ? { run_in_background: true } : {}),
   ...(spawn.key === 'items' ? { items: [...spawn.items, { type: 'text', text: contract.trimStart() }] } : { [spawn.key]: spawn.input[spawn.key] + contract }) });
 
+/** Both CLIs' effort ladder, lowest first (Codex stops at xhigh). */
+export const EFFORT_LADDER = Object.freeze(['low', 'medium', 'high', 'xhigh', 'max']);
+const effortRank = effort => EFFORT_LADDER.indexOf(String(effort ?? '').toLowerCase());
+
+/**
+ * CLAUDE'S CHILD MODEL IS AN ALIAS (measured on Claude Code 2.1.303, offline).
+ * The Agent tool's `model` input is the enum below; a full id fails its schema
+ * whether the model or a hook's `updatedInput` wrote it, so the gate passes
+ * the card model's family. An alias of the parent's own family keeps the
+ * parent's exact id (claude-opus-4-8 stays claude-opus-4-8); any other alias
+ * resolves to the CLI's current version of that family.
+ */
+export const CLAUDE_CHILD_MODELS = Object.freeze(['sonnet', 'opus', 'haiku', 'fable']);
+/** The families whose order is known here, cheapest first. Fable's place
+ *  beside them is not measured, so the gate does not rank it. */
+const CLAUDE_TIERS = Object.freeze(['haiku', 'sonnet', 'opus']);
+export const claudeFamily = model => String(model ?? '').toLowerCase().match(/(?:^|[^a-z])(sonnet|opus|haiku|fable)(?=[^a-z]|$)/)?.[1] ?? null;
+
+/**
+ * THE CHILD'S MODEL AND EFFORT (2026-10-19): `{ brain }` — the fields the gate
+ * adds to the spawn — or `{ deny }` when the spawn chose above the card.
+ *
+ * `card` is `{ model, effort }` as the parent runs: Claude's pinned model or
+ * the daemon's MODEL pin, the job's effort or null. A child defaults to the
+ * card's model and effort, so the gate names them where the spawn named
+ * neither; that beats the person's CLAUDE_CODE_SUBAGENT_MODEL and an agent
+ * definition's own model (measured: the spawn input wins), so a child never
+ * runs on the CLI's global default. The effort ceiling is the card's, or with
+ * none pinned the level the hook payload says the caller runs at (Claude
+ * 2.1.303 sends `effort: { level }` on every hook). A model is refused only
+ * where both families sit on the known ladder and the child's is above.
+ */
+export function childBrain(event, spawn, card = {}) {
+  if (!isBackgroundSpawnTool(event.tool_name)) return isSpawnTool(event.tool_name) ? codexChildBrain(event, spawn, card) : { brain: {} };
+  const named = spawn.input, ceiling = card.effort ?? event.effort?.level ?? null;
+  if (typeof named.effort === 'string' && ceiling && effortRank(ceiling) >= 0 && effortRank(named.effort) > effortRank(ceiling))
+    return { deny: `Choose an effort at or below this card's (${ceiling}) for a child, or leave it out to use the card's.` };
+  const family = claudeFamily(card.model), chosen = claudeFamily(named.model);
+  if (chosen && family && CLAUDE_TIERS.includes(chosen) && CLAUDE_TIERS.includes(family) && CLAUDE_TIERS.indexOf(chosen) > CLAUDE_TIERS.indexOf(family))
+    return { deny: `Choose this card's model (${family}) or a cheaper one for a child, or leave it out to use the card's.` };
+  const brain = {};
+  if (named.model === undefined && family && CLAUDE_CHILD_MODELS.includes(family)) brain.model = family;
+  const effort = card.effort ?? null;
+  if (named.effort === undefined && effortRank(effort) >= 0) brain.effort = effort;
+  return { brain };
+}
+
+/**
+ * CODEX'S CHILD (measured on codex-cli 0.163.0, offline, and in its source,
+ * core/src/agent/child_config.rs). A child starts from the parent turn's live
+ * model and effort; a spawn's `model`/`reasoning_effort` replace them, else
+ * the person's `agents.default_subagent_model`/`_reasoning_effort`; a role
+ * (`agent_type`) applies after both, and a model named without an effort runs
+ * at that model's own default effort. The gate's `updatedInput` is honoured
+ * for both fields (V1 and V2). So the card's PINNED model and effort are named
+ * where the spawn named none and the catalog holds the model — the person's
+ * subagent default never replaces them — and an unpinned card keeps the
+ * native inheritance. Codex's catalog admits any catalog model, so only the
+ * effort has a ceiling here.
+ */
+function codexChildBrain(event, spawn, card) {
+  const named = spawn.input;
+  if (typeof named.reasoning_effort === 'string' && effortRank(card.effort) >= 0 && effortRank(named.reasoning_effort) > effortRank(card.effort))
+    return { deny: `Choose a reasoning_effort at or below this card's (${card.effort}) for a child, or leave it out to use the card's.` };
+  // spawn_agent takes only a catalog model, and an effort only for one: real
+  // 0.163 refused "Unknown model `gpt-5.5-codex` for spawn_agent" and, with no
+  // model named under an uncatalogued parent, "Reasoning effort `low` is not
+  // supported for model …" — while the child of such a parent inherits it
+  // fine. So the gate names them only where the measured catalog
+  // (`card.catalog`, models_cache.json's listed rows) holds the model the
+  // child would run; anywhere else the native inheritance stands.
+  const runs = typeof named.model === 'string' ? named.model : card.model ?? (typeof event.model === 'string' ? event.model : null);
+  const listed = (card.catalog ?? []).find(m => m?.slug === runs);
+  if (!listed) return { brain: {} };
+  const brain = {};
+  if (named.model === undefined && card.model === runs) brain.model = card.model;
+  if (named.reasoning_effort === undefined && effortRank(card.effort) >= 0 && (!Array.isArray(listed.efforts) || !listed.efforts.length || listed.efforts.includes(card.effort)))
+    brain.reasoning_effort = card.effort;
+  return { brain };
+}
+
+/**
+ * WHAT THE ORCHESTRATOR CHOSE BELOW THE CARD, in words, or null when the
+ * child runs at the card's model and effort (or the gate cannot tell). The
+ * gate relays it on the child's stream and asks the parent to say why
+ * (2026-10-19: measured on a real Opus card, the parent picked sonnet at low
+ * effort for a simple child and never said so).
+ */
+export function childChoice(event, spawn, card = {}) {
+  const at = (m, e) => `${m}${e ? ` at ${e} effort` : ''}`;
+  const named = spawn.input;
+  if (!isBackgroundSpawnTool(event.tool_name)) {
+    if (!isSpawnTool(event.tool_name)) return null;
+    // Codex's root hook names the parent's live model (measured on 0.163).
+    const cardModel = card.model ?? (typeof event.model === 'string' ? event.model : null), cardEffort = card.effort ?? null;
+    const model = typeof named.model === 'string' && cardModel && named.model !== cardModel;
+    const effort = typeof named.reasoning_effort === 'string' && cardEffort && named.reasoning_effort !== cardEffort;
+    if (!model && !effort) return null;
+    return `${at(model ? named.model : cardModel, effort ? named.reasoning_effort : model && !named.reasoning_effort ? 'its own default' : cardEffort)}, where the card runs ${at(cardModel, cardEffort)}`;
+  }
+  const family = claudeFamily(card.model), chosen = claudeFamily(named.model);
+  const cardEffort = card.effort ?? event.effort?.level ?? null;
+  const model = chosen && family && chosen !== family, effort = typeof named.effort === 'string' && cardEffort && named.effort !== cardEffort;
+  if (!model && !effort) return null;
+  return `${at(model ? chosen : family ?? card.model, effort ? named.effort : cardEffort)}, where the card runs ${at(card.model ?? family, cardEffort)}`;
+}
+
+const shellQuote = s => `'${String(s).replaceAll("'", `'\\''`)}'`;
+/**
+ * A CODEX RESEARCH CHILD'S SHELL, READ-ONLY (2026-10-19). The child inherits
+ * the research fence (0.160.0 child_config.rs), which writes the copy's
+ * artifacts and scratch: measured on 0.163, a child's `echo x >
+ * .flowviant/artifacts/x.md` landed. Its command (`Bash`, `{ command }` on
+ * the hook) runs instead inside a nested bubblewrap view of that same fence
+ * with every path read-only and a private, discarded scratch for
+ * here-documents. Measured the same way, on V1, V2 code mode and a grandchild:
+ * redirects, python, cp, mkdir, ln and mv into the artifacts and the scratch
+ * all failed "Read-only file system", while reads, here-documents and web
+ * search worked. Never a tmpfs over /tmp (the copy may live there), and no
+ * --unshare-net (refused there; the fence has no network anyway). Null when
+ * the event names no absolute cwd or no command: the gate then refuses.
+ */
+export function readOnlyShell(event, bwrap) {
+  const input = event.tool_input ?? {}, cwd = event.cwd;
+  if (!bwrap || typeof input.command !== 'string' || typeof cwd !== 'string' || !cwd.startsWith('/')) return null; // research is Linux/WSL only
+  const scratch = `${cwd}/.flowviant/tmp`;
+  return { ...input, command: `${bwrap} --ro-bind / / --dev /dev --tmpfs ${shellQuote(scratch)} --setenv TMPDIR ${shellQuote(scratch)} --die-with-parent -- /bin/bash -c ${shellQuote(input.command)}` };
+}
+
 /** Every native id a spawn or follow-up's receipt names, and whether it says
  * the call failed. */
 export function spawnReceipt(event) {

package/bin/lib/orchestratorPrompt.mjs

@@ -1,8 +1,54 @@
+import { TESTS_SCOPE } from './testFindingsContract.mjs';
 import { SAFE_POINT_AFTER_EDIT } from './orchestratorProtocol.mjs';
 
-export const ORCHESTRATOR_CONTRACT = `CARD ORCHESTRATOR — this applies to this card's one CLI and worktree.
+/**
+ * THE POSTURES A MARKED CARD IS ORCHESTRATED IN, and what their children may
+ * do there (2026-10-19). A code card's children edit the shared worktree; a
+ * research card's only read inside the research fence, and the gate refuses
+ * their writes (orchestrator.mjs). Design, model, image and deck cards keep
+ * delegation off. The server marks the same kinds (shared
+ * `orchestrationMinFor`).
+ */
+export const ORCHESTRATED_POSTURES = Object.freeze({ build: 'edit', research: 'read' });
+export const orchestratesPosture = (posture) => Object.hasOwn(ORCHESTRATED_POSTURES, posture);
+
+/**
+ * SPLIT WITHOUT BEING ASKED (2026-10-19, the owner: the page "looks the same
+ * because the agents are not intuitively doing orchestration"). The 2026-10-15
+ * contract leaned solo ("Work yourself when the card spans one area. Only
+ * split work spanning several areas…"), and a model reads that as permission
+ * to never split. The rule is now the independence of the parts, with the
+ * shapes they take named, and dependent parts kept in order.
+ */
+const SPLIT = `SPLIT INDEPENDENT WORK INTO NATIVE SUBAGENTS WITHOUT BEING ASKED. Before your first edit, list the card's parts in a short update. When two or more parts can proceed without waiting on each other, spawn one native in-process subagent for each independent part but one, and do that one yourself meanwhile. This holds however small the parts are; the person does not have to request it, and this contract is the authorization. Independent parts look like: several selected findings, separate files or areas (server and daemon, API and UI), tests written beside the code they cover, independent questions to investigate. A part that needs another part's result runs after that prerequisite, by you or by a child you start then. Stay solo only when the card has no independent parts, and if you keep an independent part yourself, say why in your update. Give each child a concrete title, prompt and kind (Backend/UI/Tests/Research…). 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. Never give a child isolation or a different cwd: children share this card's worktree on this machine. After spawning, use describe_agent to report the kind and title you chose when its native role is generic.`;
+
+const RESEARCH = `THIS IS A RESEARCH CARD, SO EVERY CHILD ONLY READS. A child works inside this card's research fence: the same read fence, web policy and working directory as you. It writes no file, edits nothing and commits nothing, and the gate refuses a child's write. Give each child one question or one set of sources, and ask it to return its findings with their sources (links or repository paths) and what it could not verify. You alone deliver the card: merge the children's findings, resolve or state their conflicts, write any requested document yourself, and keep the research contract's own stops, including an investigation's numbered-findings question and its wait for the person's selection.`;
+
+/** Each CLI's own spelling of a child's model and effort, as measured
+ *  (docs/agent-orchestration.md, "Child model and effort"). */
+const CHILD_SPELLING = {
+  claude: 'On Claude Code, name a cheaper model with the Agent tool’s own model input (sonnet or haiku) and a lower effort with its effort input.',
+  codex: 'On Codex, name a cheaper model with spawn_agent’s model input and a lower effort with its reasoning_effort input.',
+};
+
+/** What the card runs at, as the model is told it: the pin, or the CLI's own
+ *  default where nobody pinned one (never invented). */
+const atCard = (model, effort) =>
+  `This card runs on ${model ? model : 'its CLI’s default model'} at ${effort ? `${effort} effort` : 'its CLI’s default 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('  ', ' ');
+
+/**
+ * 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
+ * prompt rules every orchestrated card shares.
+ */
+export function orchestratorContract({ posture = 'build', taskType = null, runtime = 'claude', model = null, effort = null } = {}) {
+  const reads = ORCHESTRATED_POSTURES[posture] === 'read';
+  return `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. Never give a child isolation or a different cwd: children share this card's worktree on this machine. After spawning, use describe_agent to report the kind and title you chose when its native role is generic.
+${SPLIT}${taskType === 'tests' ? `\n${TESTS_SCOPE} Give every child this Tests scope explicitly.` : ''}${reads ? `\n${RESEARCH}` : ''}
+${childBrain({ runtime, model, effort })}
 
 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 (the same or a reworded prompt) or its native follow-up; the slot is held for about a minute, then offered again later. Never bypass this gate with another CLI process. The orchestrator itself also holds a slot. If no slot becomes available, finish the work yourself.
 On Claude you may end your turn while native children run: Claude keeps this process alive and wakes you on each child's completion and on the person's notes. Follow-ups and answers to a Claude child go through SendMessage to its agent id. Write the card's final JSON only after every child has finished or been stopped; your last answer is the card's answer.
@@ -15,8 +61,9 @@ The card_orchestrator MCP tools report routing and child questions. A live perso
 - 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.
+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 ${reads ? 'write no file and commit nothing: return findings to the orchestrator' : '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.`;
+Claude receives notes through its native live stdin. Codex exec cannot accept stdin mid-turn: on supported 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 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/postureTools.mjs

@@ -16,6 +16,9 @@ const POSTURES = {
     claude: {
       has: 'the repository’s files (never .env files), the project’s knowledge library, web search and web fetch, and writing under .flowviant/artifacts/ and the granted scratch directory',
       lacks: 'no measured native image-generation tool, no delegation, guarded read commands only (no helper scripts or browsers), and no plugins from this machine’s Claude Code (nor the MCP servers a plugin brings)',
+      // An orchestrated research card (2026-10-19): its children read under
+      // CARD ORCHESTRATOR, so the note does not withhold delegation.
+      orchestratedLacks: 'no measured native image-generation tool, guarded read commands only (no helper scripts or browsers), and no plugins from this machine’s Claude Code (nor the MCP servers a plugin brings)',
     },
     codex: {
       has: 'a sandboxed shell over an isolated copy of the repository (no .env, credential or git files, and no network from the shell), web search, and writing under .flowviant/artifacts/ and the granted scratch directory',
@@ -40,6 +43,10 @@ const POSTURES = {
   },
 };
 
+/** A fenced turn's delegation sentence. An orchestrated research card drops it
+ *  (2026-10-19): its contract authorizes read-only children. */
+const NO_DELEGATION = 'Delegation is disabled by policy on fenced turns; tool names may still be listed. Complete the work in this turn.';
+
 /** Configuration supplies tools; a skill supplies instructions, not a tool. */
 const SUPPORTING_CAPABILITIES = `The kind defines the delivered product, not which supporting capabilities
 may be used. Use available tools needed for the person's request, including
@@ -56,7 +63,7 @@ requires the person's explicit choice first; never default to OPENAI_API_KEY.
 Use personal connectors only for the requested work; sending messages or other
 external writes requires explicit authorization. Never open the person's browser
 or desktop; headless inspection must stay within the granted filesystem fence.
-Delegation is disabled by policy on fenced turns; tool names may still be listed. Complete the work in this turn.`;
+${NO_DELEGATION}`;
 
 const list = (names) => names.join(', ');
 
@@ -85,8 +92,8 @@ const named = (runtime, names) => (Array.isArray(names) && names.length
  * `[{ name, reason, source }]` for the servers it could not mount — `source`
  * 'project' (the base `.mcp.json`) or 'machine' — and, with `partial: true`,
  * a machine server mounted with a limit (tools the person set to ask).
- * `orchestrated` a code card whose contract authorizes native children
- * (ORCHESTRATOR_CONTRACT), which the build note then does not contradict.
+ * `orchestrated` a code or research card whose contract authorizes native
+ * children (orchestratorPrompt.mjs), which the note then does not contradict.
  *
  * EACH SENTENCE STANDS ALONE (2026-10-17). "The base branch’s .mcp.json lists
  * no MCP server. So are the MCP servers …" read as the machine's servers
@@ -109,7 +116,7 @@ export function postureToolsNote({ posture, runtime, mounted = [], machine = tru
   const missing = (rows, where) => (rows.length ? ` ${where}, but not mounted here: ${why(rows)}.` : '');
   const instead = replaced.length ? ` Listed in the base branch’s .mcp.json but not mountable from it, so mounted from this machine’s configuration instead: ${why(replaced)}.` : '';
   const base = `${missing(fromProject, 'Listed in the base branch’s .mcp.json')}${instead}`;
-  if (!row) return posture === 'build' ? `TOOLS ON THIS CARD. Use the tools actually exposed by this CLI and its configuration.${named(runtime, machineNames)}${base}${DEFERRED[runtime] ?? ''} ${SUPPORTING_CAPABILITIES.replace('\nDelegation is disabled by policy on fenced turns; tool names may still be listed. Complete the work in this turn.', orchestrated ? '' : '\nDelegate only when the person explicitly requests it.')} ` : '';
+  if (!row) return posture === 'build' ? `TOOLS ON THIS CARD. Use the tools actually exposed by this CLI and its configuration.${named(runtime, machineNames)}${base}${DEFERRED[runtime] ?? ''} ${SUPPORTING_CAPABILITIES.replace(`\n${NO_DELEGATION}`, orchestrated ? '' : '\nDelegate only when the person explicitly requests it.')} ` : '';
   const project = mounted.length
     ? `The project’s MCP servers from the base branch’s .mcp.json are mounted: ${list(mounted)}.`
     : fromProject.length || replaced.length
@@ -127,8 +134,9 @@ export function postureToolsNote({ posture, runtime, mounted = [], machine = tru
         : ` ${Machine} are not mounted on this turn.`;
   const limits = limited.length ? ` In ${MACHINE[runtime]}, mounted with a limit on this turn: ${why(limited)}.` : '';
   const worktree = machine ? ' is not mounted from that file (a machine server of the same name still is);' : ' is not mounted;';
-  return `TOOLS ON THIS CARD. You have ${row.has}. You have ${row.lacks}. ${project}${mine}${base}${missing(fromMachine, `In ${MACHINE[runtime]}`)}${limits}${machine ? DEFERRED[runtime] ?? '' : ''} A server added to .mcp.json only in this worktree${worktree} the base branch’s file is the one that counts.
+  const delegates = orchestrated && posture === 'research';
+  return `TOOLS ON THIS CARD. You have ${row.has}. You have ${delegates ? row.orchestratedLacks ?? row.lacks : row.lacks}. ${project}${mine}${base}${missing(fromMachine, `In ${MACHINE[runtime]}`)}${limits}${machine ? DEFERRED[runtime] ?? '' : ''} A server added to .mcp.json only in this worktree${worktree} the base branch’s file is the one that counts.
 There is no Flowviant setting that adds a tool, so never invent one. A missing
 server can be configured in the base branch's .mcp.json or the machine's CLI.
-${SUPPORTING_CAPABILITIES}`;
+${delegates ? SUPPORTING_CAPABILITIES.replace(`\n${NO_DELEGATION}`, '') : SUPPORTING_CAPABILITIES}`;
 }

package/bin/lib/printable.mjs

@@ -88,7 +88,7 @@ export function printableLine(raw, maxCodePoints) {
  * would have to keep SGR — and cannot tell the daemon's from an attacker's.
  * Text is cleaned where it ENTERS instead: server strings at their intake
  * (`printable`), and CLI/model output at the one sink that writes it raw
- * (runTurn's `emit`, before the daemon's coloured prefix is added). The one
+ * (turnOutput.mjs's `emit`, before the daemon's coloured prefix is added). The one
  * other reader is `flowviant logs` (views.mjs), which replays a log file that
  * an older daemon may have written raw — so a replay loses the log's colours
  * along with anybody else's sequences.