flowviant 0.125.7 → 0.125.12

package/bin/lib/codexResearch.mjs

@@ -10,7 +10,9 @@ import { ensureRealSubdir, realDirState } from './ownedDirs.mjs';
 import { closeSync, constants, copyFileSync, existsSync, fstatSync, openSync, readFileSync, readSync, lstatSync, mkdirSync, readdirSync, realpathSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { createRequire } from 'node:module';
+import { prepareResearchLaunch } from './researchHandoff.mjs';
 import { versionAtLeast } from './versionOrder.mjs';
+import { copyResultInputs } from './resultInputs.mjs';
 
 const MAX_FILES = 20_000;
 const MAX_BYTES = 128 * 1024 * 1024;
@@ -120,7 +122,7 @@ export function researchFence({ cwd, helper, generatedImages }) {
  * nothing. Artifact publication stays in the original worktree for the
  * existing uploader.
  */
-export function publishResearch(source, destination) {
+export function publishResearch(source, destination, inputs = new Map()) {
   if (realDirState(destination) === 'none') mkdirSync(destination, { recursive: true });
   if (realDirState(destination) !== 'dir') throw new Error('The research artifact destination is not a real directory.');
   for (const entry of readdirSync(source, { withFileTypes: true })) {
@@ -128,7 +130,7 @@ export function publishResearch(source, destination) {
     const to = join(destination, entry.name);
     const stat = lstatSync(from);
     if (stat.isSymbolicLink()) throw new Error('An isolated research output is a symlink; nothing was accepted through it.');
-    if (stat.isDirectory()) publishResearch(from, to);
+    if (stat.isDirectory()) publishResearch(from, to, inputs);
     else if (stat.isFile() && /\.md$/i.test(entry.name)) {
       if (stat.size > 2 * 1024 * 1024) throw new Error('The research Markdown output exceeds 2 MB.');
       let there = null;
@@ -139,6 +141,7 @@ export function publishResearch(source, destination) {
       }
       if (there && !there.isFile()) throw new Error('The research output would overwrite a non-file.');
       const bytes = readFileSync(from);
+      if (inputs.get(from)?.equals(bytes)) continue;
       if (there && there.size === bytes.length && readFileSync(to).equals(bytes)) continue;
       if (there) unlinkSync(to);
       writeFileSync(to, bytes, { flag: 'wx' });
@@ -146,8 +149,27 @@ export function publishResearch(source, destination) {
   }
 }
 
+// Retained context is person/source scoped. Do not make another discussion's
+// reports readable merely because they happen to stand in this worktree.
+function retainResearchInputs(dir, names, relative = '') {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const name = relative + entry.name, path = join(dir, entry.name);
+    if (entry.isDirectory()) retainResearchInputs(path, names, name + '/');
+    else if (!names.has(name)) rmSync(path, { force: true });
+  }
+}
+function rememberResearchInputs(dir, inputs = new Map()) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) rememberResearchInputs(path, inputs);
+    else if (entry.isFile() && /\.md$/i.test(entry.name)) inputs.set(path, readFileSync(path));
+  }
+  return inputs;
+}
+
 export async function runIsolatedResearch(opts, run, {
   resolveHelper = codexResearchHelper,
+  prepareLaunch = prepareResearchLaunch,
   readVersion = (helper) => execFileSync(helper, ['--version'], { encoding: 'utf8', timeout: 10_000 }),
 } = {}) {
   if (process.platform !== 'linux') throw new Error('Isolated Codex research requires Linux or WSL.');
@@ -170,12 +192,18 @@ export async function runIsolatedResearch(opts, run, {
   const snapshot = join(isolation, 'repo');
   try {
     copyResearchView(original, snapshot);
+    copyResultInputs(original, snapshot, opts.resultInputs);
     let knowledge = null;
-    if (opts.knowledgeDir) {
+    if (Number.isInteger(opts.researchHandoff?.knowledgeRev)) {
+      // The launch loader will build this from the held current manifest.
+      // Never copy an unmeasured/background-sync mirror into its input view.
+      knowledge = join(snapshot, '.flowviant/knowledge');
+    } else if (opts.knowledgeDir) {
       knowledge = join(snapshot, '.flowviant/knowledge');
       copyResearchView(realpathSync(opts.knowledgeDir), knowledge);
     }
     for (const dir of ['artifacts', 'tmp']) mkdirSync(join(snapshot, '.flowviant', dir), { recursive: true, mode: 0o700 });
+    if (opts.researchHandoff) retainResearchInputs(join(snapshot, '.flowviant/artifacts'), new Set(opts.researchHandoff.artifacts.filter(a => !a.unavailable).map(a => a.name)));
     const rewrite = (text) => typeof text === 'string'
       ? text.replaceAll(original, snapshot).replaceAll(opts.knowledgeDir || '\0', knowledge || '\0') : text;
     const intro = 'This fresh research turn uses an isolated read-only copy. Prior reports are available under .flowviant/artifacts/; previous CLI conversations are not resumed because they may contain host secrets. Git metadata, .env files, credential files, symlinks and personal CLI settings are omitted. Write the Markdown report only under .flowviant/artifacts/. Web search is available; shell networking is disabled. Use exec_command with shell=/bin/bash and login=false; personal shells are outside the fence.\n\n';
@@ -187,13 +215,15 @@ export async function runIsolatedResearch(opts, run, {
         throw new Error('The native generated image directory is not a real directory.');
       generatedImages = join(imageHome, 'generated_images');
     }
-    const result = await run({ ...opts, resume: false, resumeThreadId: null, resumeConversationId: null, cwd: snapshot, knowledgeDir: knowledge,
+    const prepared = await prepareLaunch({ ...opts, resume: false, resumeThreadId: null, resumeConversationId: null, adoptResumeId: null, cwd: snapshot, knowledgeDir: knowledge,
       prompt: intro + rewrite(opts.prompt), system: rewrite(opts.system),
       researchIsolation: { cwd: snapshot, helper, generatedImages } });
+    const inputs = rememberResearchInputs(join(snapshot, '.flowviant/artifacts'));
+    const result = await run(prepared);
     // Made, or found, real at publication too: every component checked again.
     if (!ensureRealSubdir(original, '.flowviant/artifacts'))
       throw new Error('The research artifact destination is not a real directory.');
-    publishResearch(join(snapshot, '.flowviant/artifacts'), join(original, '.flowviant/artifacts'));
+    publishResearch(join(snapshot, '.flowviant/artifacts'), join(original, '.flowviant/artifacts'), inputs);
     return typeof result === 'string' ? result.replaceAll(snapshot, original) : result;
   } finally { rmSync(isolation, { recursive: true, force: true }); }
 }

package/bin/lib/commandSpecs.mjs

@@ -30,10 +30,13 @@ export const COMMANDS = [
   {
     name: 'start',
     usesCheckout: true,
-    usage: 'flowviant [start] [--project <name|id>]',
+    usage: 'flowviant [start] [--detail] [--project <name|id>]',
     summary: "Serve this repo's project: run agents and Terminal tabs here. Plain `flowviant` does the same.",
     details: [
       'Run it inside the repository you connected. The first run in a new repo asks you to approve this computer.',
+      'Default: compact chronological activity, with fresh routine summaries every 10 seconds and at event boundaries.',
+      '--detail   print each runtime activity in the foreground; preserved through login and update relaunches',
+      'flowviant logs -f --turn @<label>   follow retained detail for the short turn label in the feed (full ids also work)',
       '--project <name|id>   serve that stored project instead of the one this repo is bound to',
     ],
     group: 'run',
@@ -41,9 +44,9 @@ export const COMMANDS = [
   {
     name: 'login',
     usesCheckout: true,
-    usage: 'flowviant login [--no-start]',
+    usage: 'flowviant login [--no-start] [--detail]',
     summary: 'Connect this repo to a project: approve the code in your browser, then start serving.',
-    details: ['--no-start   save the connection without starting the daemon'],
+    details: ['--no-start   save the connection without starting the daemon', '--detail     start with the detailed foreground stream'],
     group: 'run',
   },
   {
@@ -64,9 +67,9 @@ export const COMMANDS = [
   {
     name: 'logs',
     usesCheckout: true,
-    usage: 'flowviant logs [-f] [--project <name|id>]',
+    usage: 'flowviant logs [-f] [-n <lines>] [--turn <id>] [--project <name|id>]',
     summary: "The daemon's log for this repo's project.",
-    details: ['-f, --follow   keep printing new lines as they are written', '-n <lines>     how many lines to show first (default 80)'],
+    details: ['-f, --follow   keep printing new retained lines across rotation and restart', '-n <lines>     how many matching lines to show first (default 80)', '--turn <id>    select an exact full id or the @short label in the feed, including native children', '--project <name|id>   select a connected project', 'Retains the current 2 MiB log and one predecessor; older detail expires.', 'Native records keep supplied prose and tool data, at most 64 KiB each.', 'Truncation and detected gaps are marked. This is diagnostic detail, not a full transcript.'],
     group: 'look',
   },
   {

package/bin/lib/daemonJournal.mjs

@@ -0,0 +1,102 @@
+/** Bounded local diagnostic journal. Native records share the existing project
+ * log with legacy console lines. Each native record occupies one JSON line;
+ * replay renders its text, rather than presenting shortened labels as history.
+ */
+import { appendFileSync, closeSync, constants, fchmodSync, fstatSync, mkdirSync, openSync, renameSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { StringDecoder } from 'node:string_decoder';
+import { printableLine, printableText } from './printable.mjs';
+import { scrub } from './uplinkScrub.mjs';
+
+export const MAX_DAEMON_LOG_BYTES = 2 * 1024 * 1024;
+export const MAX_DETAIL_RECORD_BYTES = 64 * 1024;
+export const DETAIL_PREFIX = '@flowviant-detail ';
+export const DETAIL_TRUNCATED = '\n[truncated: local detail record exceeded 64 KiB]';
+export const DETAIL_GAP = '[detail gap: local log writes failed; some detail was not retained]';
+
+export const utf8Prefix = (text, bytes) => new StringDecoder('utf8').write((Buffer.isBuffer(text) ? text : Buffer.from(text)).subarray(0, Math.max(0, bytes)));
+const safe = text => printableText(scrub(printableText(scrub(String(text ?? '')))));
+
+export function encodeDetailRecord(record) {
+  const row = { v: 1, observedAt: record.observedAt, kind: printableLine(safe(record.kind), 120), name: printableLine(safe(record.name), 120),
+    workId: safe(record.workId), turnId: safe(record.turnId), source: safe(record.source),
+    ...(record.agentId ? { agentId: safe(record.agentId) } : {}), text: safe(record.text) };
+  const encode = () => DETAIL_PREFIX + JSON.stringify(row) + '\n';
+  const encoded = row.text.length <= MAX_DETAIL_RECORD_BYTES ? encode() : null;
+  if (encoded && Buffer.byteLength(encoded) <= MAX_DETAIL_RECORD_BYTES) return encoded;
+  const full = Buffer.from(row.text);
+  row.truncated = true;
+  row.text = DETAIL_TRUNCATED;
+  if (Buffer.byteLength(encode()) > MAX_DETAIL_RECORD_BYTES) throw new Error('Detail attribution exceeds the record limit');
+  let low = 0, high = Math.min(full.length, MAX_DETAIL_RECORD_BYTES);
+  while (low < high) {
+    const mid = Math.ceil((low + high) / 2);
+    row.text = utf8Prefix(full, mid) + DETAIL_TRUNCATED;
+    if (Buffer.byteLength(encode()) <= MAX_DETAIL_RECORD_BYTES) low = mid;
+    else high = mid - 1;
+  }
+  row.text = utf8Prefix(full, low) + DETAIL_TRUNCATED;
+  return encode();
+}
+
+export function decodeDetailRecord(line) {
+  if (!line.startsWith(DETAIL_PREFIX)) return null;
+  if (Buffer.byteLength(line) > MAX_DETAIL_RECORD_BYTES) return false;
+  try {
+    const row = JSON.parse(line.slice(DETAIL_PREFIX.length));
+    if (row?.v !== 1 || !Number.isFinite(row.observedAt) ||
+        !['kind', 'name', 'workId', 'turnId', 'source', 'text'].every(k => typeof row[k] === 'string') ||
+        row.agentId !== undefined && typeof row.agentId !== 'string') return false;
+    // Older/local files are untrusted at replay too. Scrub text before it is
+    // expanded into terminal lines; never revive escapes from a JSON string.
+    return { ...row, kind: printableLine(safe(row.kind), 120), name: printableLine(safe(row.name), 120),
+      workId: printableLine(safe(row.workId), Infinity), turnId: printableLine(safe(row.turnId), Infinity),
+      ...(row.agentId ? { agentId: printableLine(safe(row.agentId), Infinity) } : {}), text: safe(row.text) };
+  } catch { return false; }
+}
+
+export function createDaemonJournal(path, { onFailure = () => {} } = {}) {
+  let missed = false;
+  const append = (raw) => {
+    let fd = null;
+    try {
+      let chunk = Buffer.from(raw);
+      const tail = '\n[truncated]\n';
+      if (chunk.length > MAX_DAEMON_LOG_BYTES)
+        chunk = Buffer.from(utf8Prefix(raw, MAX_DAEMON_LOG_BYTES - Buffer.byteLength(tail)) + tail);
+      const gap = missed ? Buffer.from('\n' + DETAIL_GAP + '\n') : Buffer.alloc(0);
+      mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+      const open = () => openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_APPEND | constants.O_NOFOLLOW | constants.O_NONBLOCK, 0o600);
+      fd = open();
+      fchmodSync(fd, 0o600);
+      if (!fstatSync(fd).isFile()) throw new Error('The local log is not a regular file');
+      if (fstatSync(fd).size + gap.length + chunk.length > MAX_DAEMON_LOG_BYTES) {
+        closeSync(fd); fd = null;
+        renameSync(path, path + '.1');
+        fd = open();
+        fchmodSync(fd, 0o600);
+      }
+      // A gap is a separate bounded entry, so even a file-sized console line
+      // cannot make a recovered log exceed its cap.
+      if (gap.length && gap.length + chunk.length <= MAX_DAEMON_LOG_BYTES) appendFileSync(fd, gap);
+      else if (gap.length) {
+        appendFileSync(fd, gap); closeSync(fd); fd = null;
+        renameSync(path, path + '.1'); fd = open(); fchmodSync(fd, 0o600);
+      }
+      appendFileSync(fd, chunk);
+      missed = false;
+      return true;
+    } catch (error) {
+      if (!missed) try { onFailure(error); } catch { /* diagnostic only */ }
+      missed = true;
+      return false;
+    } finally { if (fd !== null) try { closeSync(fd); } catch { /* a log close never stops work */ } }
+  };
+  return {
+    console: text => append(safe(text) + '\n'),
+    record(record) {
+      try { return append(encodeDetailRecord(record)); }
+      catch (error) { if (!missed) try { onFailure(error); } catch { /* diagnostic only */ } missed = true; return false; }
+    },
+  };
+}

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. */