flowviant 0.125.7 → 0.125.9

package/bin/lib/daemonLogging.mjs

@@ -8,11 +8,23 @@
  * module. This one owns output only; it is handed the log path and never
  * decides where per-project files live (daemonState.mjs does).
  */
-import { appendFileSync, mkdirSync, renameSync, statSync } from 'node:fs';
-import { dirname } from 'node:path';
+import { createDaemonJournal } from './daemonJournal.mjs';
 import { format } from 'node:util';
+import { compactOutput, flushActivityOutput } from './activityFeed.mjs';
 
-export const MAX_DAEMON_LOG_BYTES = 2 * 1024 * 1024;
+export { MAX_DAEMON_LOG_BYTES } from './daemonJournal.mjs';
+let journal = null;
+export const hasDaemonJournal = () => journal !== null;
+
+/** null means no local daemon journal is configured; false is a measured failure. */
+export const retainTurnRecord = record => journal ? journal.record(record) : null;
+
+// Explicit diagnostic source; silence only after its local write succeeded.
+export function diagnostic(line) {
+  if (!journal) return console.info(line);
+  const retained = journal.console(line);
+  if (!compactOutput() || !retained) process.stderr.write(`${line}\n`);
+}
 
 let events = false;
 let eventWriter = process.stdout.write.bind(process.stdout);
@@ -25,29 +37,21 @@ export function emitMachineEvent(value) {
  * mode stdout is reserved for JSONL and those same lines go to stderr. Every
  * line is also appended to `logPath`, rotated at MAX_DAEMON_LOG_BYTES. */
 export function installDaemonLogging(logPath, { jsonEvents = false } = {}) {
-  if (!logPath) return;
   if (jsonEvents) {
     enableMachineEvents();
     process.stdout.write = (...args) => process.stderr.write(...args);
   }
+  if (!logPath) return;
   const original = { log: console.log, info: console.info, warn: console.warn, error: console.error };
+  journal = createDaemonJournal(logPath, { onFailure: error => {
+    flushActivityOutput();
+    original.warn(`Local detail could not be retained (${error?.code || 'log write failed'}). Work continues; the log may have gaps.`);
+  } });
   for (const method of Object.keys(original)) {
     console[method] = (...args) => {
+      flushActivityOutput();
       const line = format(...args);
-      try {
-        mkdirSync(dirname(logPath), { recursive: true });
-        const encoded = Buffer.from(`${line}\n`);
-        const tail = Buffer.from('\n[truncated]\n');
-        const chunk = encoded.length > MAX_DAEMON_LOG_BYTES
-          ? Buffer.concat([encoded.subarray(0, MAX_DAEMON_LOG_BYTES - tail.length), tail])
-          : encoded;
-        let size = 0;
-        try { size = statSync(logPath).size; } catch { /* new file */ }
-        if (size + chunk.length > MAX_DAEMON_LOG_BYTES) {
-          try { renameSync(logPath, `${logPath}.1`); } catch { /* no old log */ }
-        }
-        appendFileSync(logPath, chunk, { mode: 0o600 });
-      } catch { /* logging must never stop service */ }
+      journal.console(line);
       if (jsonEvents) process.stderr.write(`${line}\n`);
       else original[method](...args);
     };

package/bin/lib/fleet.mjs

@@ -35,11 +35,12 @@ import {
 import { projectLabel } from './credentials.mjs';
 import { handleVersionSignal } from './update.mjs';
 import { compareVersions } from './versionOrder.mjs';
-import { emitMachineEvent } from './daemonLogging.mjs';
-import { writeDaemonState } from './daemonState.mjs';
+import { diagnostic, emitMachineEvent, hasDaemonJournal, installDaemonLogging } from './daemonLogging.mjs';
+import { compactOutput } from './activityFeed.mjs';
+import { daemonLogPath, writeDaemonState } from './daemonState.mjs';
 import { maintenanceTick, readMaintenance } from './maintenance.mjs';
 import { repoRootOrDie, detectBaseRef, excludeInWorktree, baseRefFor } from './git.mjs';
-import { c, info, note, ok, warn, fail } from './ui.mjs';
+import { c, stamp, info, note, ok, warn, fail } from './ui.mjs';
 import { sleep } from './sleep.mjs';
 import { reapOrphanPreviews } from './previewRegistry.mjs';
 import { preflight } from './preflight.mjs';
@@ -370,9 +371,10 @@ export async function runFleetDaemon({ afterLock = null } = {}) {
   });
   installSignalHandlers(teardown, leave);
 
+  let connectionFailed = false;
   let connected = false; // log the first successful poll once
   let rosterSig = null; // last roster membership, to log changes only
-  let idleBeatAt = 0; // throttle the "still alive" idle heartbeat
+  let idleBeatAt = 0; // throttle the legacy detailed idle snapshot
   // WHOSE MACHINE THIS IS, as of the last poll the server arbitrated. 'absent'
   // is the reserved meaning — an older server, or a poll with no envpub — and
   // everything downstream of it must read exactly as it did before 0.84.0.
@@ -434,6 +436,7 @@ export async function runFleetDaemon({ afterLock = null } = {}) {
         await leave(0);
         return;
       }
+      connectionFailed = true;
       warn(`roster poll failed: ${e.message} — retrying in ${RECONCILE_SECONDS}s`);
       // Work already running keeps running offline; the measurement keeps up.
       if (!await reportMaintenance()) reportBusy();
@@ -441,6 +444,8 @@ export async function runFleetDaemon({ afterLock = null } = {}) {
       continue;
     }
     if (standingDown()) return leave.drained();
+    if (connectionFailed && connected) ok('Connection recovered — connected to Flowviant.');
+    connectionFailed = false;
     if (!connected) {
       connected = true;
       ok('Connected to Flowviant — watching your roster.');
@@ -467,6 +472,9 @@ export async function runFleetDaemon({ afterLock = null } = {}) {
     // The server's word on which project this token serves — settles the env
     // report's salt for a token that came from --fleet or the environment.
     learnProjectId(roster.project?.id);
+    // Env-token starts learn their project here. No CLI activity is hidden
+    // before a journal exists; select it before handing out this roster's work.
+    if (!hasDaemonJournal() && roster.project?.id) installDaemonLogging(daemonLogPath(roster.project.id));
     if (roster.leaseTtlSeconds) leaseTtlSeconds = roster.leaseTtlSeconds;
     // THE THREE SIGNALS THAT END THIS DAEMON — a commanded stop, then a
     // displacement, then a removal (holder.mjs, `obeyRosterCommands`). ABOVE
@@ -678,7 +686,8 @@ export async function runFleetDaemon({ afterLock = null } = {}) {
       if (holderState !== 'standby')
         info('Machine online. Open a tab in Flowviant → Terminal to start working.');
     }
-    // Heartbeat so a quiet daemon visibly stays alive. Gated on REAL work —
+    // The legacy idle snapshot remains in detail only. Compact silence does
+    // not manufacture activity or health. Gated on REAL work —
     // it was once gated on `roster.agents`, which the server sends permanently
     // empty, and printed "waiting" once a minute even while a tab's turn was
     // running. `workBusy()` is the honest question: are there session turns,
@@ -690,7 +699,8 @@ export async function runFleetDaemon({ afterLock = null } = {}) {
       // this box. The internal state is still called `standby` because it names
       // the SERVER'S arbitration arm rather than anything a person reads; what
       // a person reads is this sentence.
-      info(
+      const sayIdle = compactOutput() ? text => diagnostic(`${stamp()} · ${text}`) : info;
+      sayIdle(
         holderState === 'standby'
           ? 'inactive — another machine is serving this project.'
           : 'machine online — nothing running right now.'

package/bin/lib/fleetReports.mjs

@@ -383,11 +383,18 @@ export function reportMachine({ worktreeDir, liveTurns }) {
   // `liveTurns()` is the live registry: every CLI child this daemon is
   // holding, with the session or agent id it serves. Bounded inside the
   // snapshot, because each row costs a /proc tree walk.
-  void postToFleet(
-    MACHINE_URL,
-    machineSnapshot({
+  //
+  // WHICH BOX IS SPEAKING (2026-10-19): `pubkey`, the same label the env and
+  // tools reports carry. A standby posts this too, and the room kept one
+  // snapshot, so on a project with two boxes the vitals alternated between
+  // them; the room now keeps each box's apart, and the project settings dial
+  // recommends from the smallest. Null before a keypair exists, which the
+  // server reads as one unnamed box, as it reads every older daemon.
+  void postToFleet(MACHINE_URL, {
+    ...machineSnapshot({
       worktreeDir,
       tasks: liveTurns().map((t) => ({ intentId: t.id, pid: t.pid })),
-    })
-  );
+    }),
+    pubkey: myPubB64(),
+  });
 }

package/bin/lib/hooks/orchestrator.mjs

@@ -29,7 +29,9 @@ export async function main() {
     // output) or at a stop (the child keeps going) that refusal is false. An
     // event too large to read is never a spawn: no model writes 24 MiB of input.
     // The names are the controller's own list (nativeAgentTools.mjs).
-    if (gatedSpawnEvent(event)) { process.exitCode = 2; return; }
+    // A research card's children only read (FLOWVIANT_ORCHESTRATOR_CHILDREN,
+    // orchestrator.mjs): a child's write is refused here too.
+    if (gatedSpawnEvent(event, process.env.FLOWVIANT_ORCHESTRATOR_CHILDREN)) { process.exitCode = 2; return; }
     try { await answer({}); } catch { /* the CLI already stopped reading */ }
   }
 }

package/bin/lib/logReplay.mjs

@@ -0,0 +1,133 @@
+/** Replay and follow the existing project log plus its one predecessor.
+ * Open descriptors carry snapshot offsets into follow: a restart appends at
+ * that offset, and replacement is detected by inode, even at equal size.
+ */
+import { closeSync, constants, fstatSync, openSync, readSync } from 'node:fs';
+import { StringDecoder } from 'node:string_decoder';
+import { decodeDetailRecord, MAX_DAEMON_LOG_BYTES } from './daemonJournal.mjs';
+import { formatTurnRecord } from './turnRecord.mjs';
+import { printableText } from './printable.mjs';
+import { scrub } from './uplinkScrub.mjs';
+import { matchesTurn } from './activityFeed.mjs';
+
+const clean = text => printableText(scrub(printableText(scrub(text))));
+const same = (a, b) => a && b && a.dev === b.dev && a.ino === b.ino;
+const closeCursor = cursor => { if (cursor && !cursor.closed) { cursor.closed = true; closeSync(cursor.fd); } };
+function openCursor(path) {
+  let fd;
+  try {
+    fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    const stat = fstatSync(fd);
+    if (!stat.isFile()) throw new Error('The log is not a regular file');
+    return { fd, dev: stat.dev, ino: stat.ino, offset: 0, rest: '', decoder: new StringDecoder('utf8'), skip: false };
+  } catch (error) {
+    if (fd !== undefined) closeSync(fd);
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+export function createLogReader(path, { turnId = null } = {}) {
+  let current = null, previousSeen = null, initialized = false, closed = false;
+  const line = (raw, batch) => {
+    const row = decodeDetailRecord(raw);
+    if (row === false) { batch.lines.push('[detail gap: an incomplete or unreadable retained record was skipped]'); return; }
+    if (row) {
+      if (turnId !== null && !matchesTurn(row.turnId, turnId)) return;
+      batch.matched++;
+      for (const text of formatTurnRecord(row, { color: false }).slice(0, -1).split('\n')) batch.lines.push(text);
+    } else if (turnId === null || raw.includes('[detail gap:') || raw === '[truncated]') batch.lines.push(clean(raw));
+  };
+  const read = (cursor, batch) => {
+    const size = fstatSync(cursor.fd).size;
+    if (size < cursor.offset) {
+      batch.lines.push('[detail gap: the log was truncated in place]');
+      cursor.offset = 0; cursor.rest = ''; cursor.decoder = new StringDecoder('utf8');
+    }
+    if (size - cursor.offset > MAX_DAEMON_LOG_BYTES) {
+      batch.lines.push('[detail gap: older bytes exceeded the retained read window]');
+      cursor.offset = size - MAX_DAEMON_LOG_BYTES; cursor.rest = ''; cursor.decoder = new StringDecoder('utf8'); cursor.skip = true;
+    }
+    const bytes = Buffer.alloc(32 * 1024);
+    while (cursor.offset < size) {
+      const n = readSync(cursor.fd, bytes, 0, Math.min(bytes.length, size - cursor.offset), cursor.offset);
+      if (!n) break;
+      cursor.offset += n;
+      cursor.rest += cursor.decoder.write(bytes.subarray(0, n));
+      let at;
+      while ((at = cursor.rest.indexOf('\n')) >= 0) {
+        const raw = cursor.rest.slice(0, at); cursor.rest = cursor.rest.slice(at + 1);
+        if (cursor.skip) cursor.skip = false;
+        else line(raw, batch);
+      }
+      if (cursor.rest.length > MAX_DAEMON_LOG_BYTES) {
+        cursor.rest = ''; cursor.skip = true;
+        batch.lines.push('[detail gap: an oversized incomplete log line was skipped]');
+      }
+    }
+  };
+  const retire = (cursor, batch) => {
+    try {
+      read(cursor, batch);
+      if (cursor.rest || cursor.decoder.lastNeed) batch.lines.push('[detail gap: an unfinished log record was not replayed]');
+    } finally { closeCursor(cursor); }
+  };
+  const refresh = () => {
+    const batch = { lines: [], matched: 0, found: false };
+    if (closed) return batch;
+    const next = openCursor(path);
+    const predecessor = () => {
+      try { return openCursor(path + '.1'); }
+      catch (error) { if (next) closeCursor(next); throw error; }
+    };
+    batch.found = Boolean(next || current);
+    if (!initialized) {
+      initialized = true;
+      const previous = predecessor();
+      let latest;
+      try { latest = openCursor(path); }
+      catch (error) { closeCursor(next); closeCursor(previous); throw error; }
+      batch.found = Boolean(next || previous || latest);
+      // Rotation can happen between opening the two names. Recheck main:
+      // if it changed, our held main predates the observed predecessor.
+      if (!same(next, latest)) {
+        if (next) retire(next, batch);
+        if (previous && !same(previous, next)) retire(previous, batch);
+        else closeCursor(previous);
+        current = latest;
+      } else {
+        closeCursor(latest);
+        if (previous && !same(previous, next)) retire(previous, batch);
+        else closeCursor(previous);
+        current = next;
+      }
+      if (previous) previousSeen = previous;
+    } else if (!next) {
+      if (current) read(current, batch);
+      return batch;
+    } else if (same(current, next)) {
+      closeCursor(next);
+    } else {
+      const previous = predecessor();
+      try {
+        if (current) retire(current, batch);
+        if (previous && !same(current, previous) && !same(previousSeen, previous)) {
+          if (current) batch.lines.push('[detail gap: rotation passed the retained predecessor; some detail may have expired]');
+          previousSeen = previous; retire(previous, batch);
+        } else if (previous) closeCursor(previous);
+      } catch (error) { closeCursor(next); throw error; }
+      current = next;
+    }
+    if (current) read(current, batch);
+    return batch;
+  };
+  return {
+    snapshot(count = 80) {
+      const batch = refresh();
+      const omitted = Math.max(0, batch.lines.length - count);
+      return { ...batch, omitted, pending: Boolean(current && (current.rest || current.decoder.lastNeed)), text: batch.lines.slice(-count).join('\n') };
+    },
+    poll() { const batch = refresh(); return { ...batch, text: batch.lines.length ? batch.lines.join('\n') + '\n' : '' }; },
+    close() { if (!closed && current) closeCursor(current); closed = true; current = null; },
+  };
+}

package/bin/lib/nativeAgentTools.mjs

@@ -29,6 +29,11 @@ export const NATIVE_AGENT_TOOLS = Object.freeze({
     stop: Object.freeze(['TaskStop']),
     ask: Object.freeze(['AskUserQuestion']),
     discovery: Object.freeze(['ToolSearch']),
+    // A research child's file writes, refused by the gate (2026-10-19).
+    // Measured on 2.1.303: a research child inherits the parent's rules, so
+    // its Write under .flowviant/artifacts/ landed; its shell is the posture's
+    // guarded readers, which refused its `touch`.
+    write: Object.freeze(['Edit', 'Write', 'MultiEdit', 'NotebookEdit']),
   }),
   codex: Object.freeze({
     spawn: Object.freeze(['spawn_agent']),
@@ -38,6 +43,11 @@ export const NATIVE_AGENT_TOOLS = Object.freeze({
     stop: Object.freeze(['interrupt_agent', 'close_agent']),
     // Seen in a rollout, never gated.
     message: Object.freeze(['send_message']),
+    // A research child's file write (2026-10-19). Measured on 0.163: a child
+    // inherits the research fence, whose artifacts directory it may write by
+    // apply_patch or by shell; the shell is fenced read-only by the gate
+    // instead (orchestratorNative.mjs `readOnlyShell`).
+    write: Object.freeze(['apply_patch']),
     ask: Object.freeze(['request_user_input']),
     discovery: Object.freeze(['tool_search', 'search_tool']),
   }),
@@ -51,21 +61,28 @@ export const nativeName = name => String(name ?? '').split(/[./]/).at(-1).replac
 
 const every = row => Object.freeze(Object.values(NATIVE_AGENT_TOOLS).flatMap(tools => tools[row] ?? []));
 const SPAWN = every('spawn'), FOLLOWUP = every('followup'), BACKGROUND = every('background');
-const DISCOVERY = every('discovery'), ASK = every('ask');
+const DISCOVERY = every('discovery'), ASK = every('ask'), WRITE = every('write');
 
 export const isSpawnTool = name => SPAWN.includes(nativeName(name));
 export const isFollowupTool = name => FOLLOWUP.includes(nativeName(name));
 export const isBackgroundSpawnTool = name => BACKGROUND.includes(nativeName(name));
 export const isDiscoveryTool = name => DISCOVERY.includes(nativeName(name));
 export const isPersonQuestionTool = name => ASK.includes(nativeName(name));
+export const isChildWriteTool = name => WRITE.includes(nativeName(name));
+// Both CLIs' hooks name the shell `Bash` (Codex's exec_command, measured on 0.163).
+export const isShellTool = name => nativeName(name) === 'Bash';
 export const isClaudeFollowupTool = name => NATIVE_AGENT_TOOLS.claude.followup.includes(nativeName(name));
 // The controller reads only Claude's stop: TaskStop names its child as task_id.
 export const isClaudeStopTool = name => NATIVE_AGENT_TOOLS.claude.stop.includes(nativeName(name));
 
 /** What the hook refuses while the controller is unreachable: every spawn and
- * follow-up the controller gates. */
+ * follow-up the controller gates, and on a run whose children only read
+ * (`children` 'read', a research card) a child's write or shell, which only
+ * the controller can fence read-only. */
 export const GATED_TOOLS = Object.freeze([...SPAWN, ...FOLLOWUP]);
-export const gatedSpawnEvent = event => event?.hook_event_name === 'PreToolUse' && GATED_TOOLS.includes(nativeName(event.tool_name));
+export const gatedSpawnEvent = (event, children = 'edit') => event?.hook_event_name === 'PreToolUse' &&
+  (GATED_TOOLS.includes(nativeName(event.tool_name)) ||
+    (children === 'read' && Boolean(event.agent_id) && (isChildWriteTool(event.tool_name) || isShellTool(event.tool_name))));
 
 /** Claude's PostToolUse and PostToolUseFailure matcher (orchestratorHooks.mjs):
  * its spawns and follow-ups. */

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;